Copyright: Copyright © 2001-2007 Developer Express Inc. ALL RIGHTS RESERVED


cxDBExtLookupComboBox Unit Overview
cxDBExtLookupComboBox Unit

Classes

TcxCustomExtLookupComboBox

TcxDBExtLookupComboBox

TcxEditRepositoryExtLookupComboBoxItem

TcxExtLookupComboBox

TcxExtLookupComboBoxProperties


TcxCustomExtLookupComboBox
TcxCustomExtLookupComboBox Object

Hierarchy          Properties          Methods          Events          See Also

Represents the base class for lookup editors displaying a grid view in the dropdown window.

Unit

cxDBExtLookupComboBox

TcxCustomExtLookupComboBox = class(TcxCustomDBLookupEdit);

Description

The TcxCustomExtLookupComboBox editor is the ancestor for lookup editors (TcxExtLookupComboBox and TcxDBExtLookupComboBox) which display grid views within their dropdown windows.  To specify the view for the editor, see its Properties.View attribute.  Only data-aware table and banded table views can be used for this purpose.

A view repository component represented by the TcxGridViewRepository class helps you to create and customize views.  Note: you must not reuse the same view in your grid control and ExtLookupEditor.

Lookup editors are designed to edit values "indirectly" by picking up a record from the dropdown view.  When you select a specific record from the view, this action changes the display text (the Text property) and the edit value (the EditValue property) obtained from the selected record.

The edit value is determined by the record’s Properties.KeyFieldNames field.  Moreover, the edit value matches this field value.  That is when you modify the EditValue property, the record with the key field matching the edit value is focused and the display text of ExtLookupEditor is changed.

You can specify more than one field in the KeyFieldNames property, in this case the edit value contains an array of variant values.

The display text is obtained from the Properties.ListFieldItem column of the selected record.  You cannot modify the text in the edit box.  It only helps you to identify the selected record visually.

Data-aware lookup editors are used to edit values from one dataset by selecting a record from another dataset (displayed by the view).  The field being edited by a TcxDBExtLookupComboBox control is specified by the editor’s DataBinding.DataField property.  The edit value matches the value of the field being edited.

To make a lookup editor work properly, you need to:

1)	Assign a view to the Properties.View property

2)	Select a view column (the Properties.ListFieldItem property) whose data will be displayed within the edit box of ExtLookupEditor

3)	For the data-aware ExtLookupEditor, specify the field being edited via the DataBinding.DataField property.  This field must match the Properties.KeyFieldNames property.

4)	Specify the key field name(s) via the Properties.KeyFieldNames property to identify records within the dropdown view.


TcxCustomExtLookupComboBox Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomComboBox

     |

TcxCustomLookupEdit

     |

TcxCustomDBLookupEdit

     |


Properties for TcxCustomExtLookupComboBox
TcxCustomExtLookupComboBox Properties

TcxCustomExtLookupComboBox          Legend

In TcxCustomExtLookupComboBox

ActiveProperties

EditValue

Properties

Text

Derived from TcxCustomDBLookupEdit

ActiveProperties

Properties

Derived from TcxCustomLookupEdit

ActiveProperties

Properties

Derived from TcxCustomComboBox

ActiveProperties

ItemIndex

Properties

Derived from TcxCustomDropDownEdit

ActiveProperties

DroppedDown

PopupWindow

Properties

Derived from TcxCustomMaskEdit

ActiveProperties

Properties

Derived from TcxCustomTextEdit

ActiveProperties

BeepOnEnter

CursorPos

EditingText

Properties

SelLength

SelStart

SelText

Text

Derived from TcxCustomEdit

ActiveProperties

AutoSize

DataBinding

EditModified

EditValue

InnerEdit

ModifiedAfterEnter

Properties

RepositoryItem

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Derived from TcxControl

BorderStyle

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading


Methods for TcxCustomExtLookupComboBox
TcxCustomExtLookupComboBox Methods

TcxCustomExtLookupComboBox          Legend

Derived from TcxCustomComboBox

 CanDropDown

Derived from TcxCustomDropDownEdit

 CanDropDown

 CloseUp

 Create

 Destroy

 DropDown

 Focused

 PopupWindowClosed

 PopupWindowClosing

Derived from TcxCustomMaskEdit

 CutToClipboard

 PasteFromClipboard

Derived from TcxCustomTextEdit

 Clear

 ClearSelection

 CopyToClipboard

 Create

 CutToClipboard

 SelectAll

 SetSelection

 Undo

Derived from TcxCustomEdit

 AdjustInnerEditPosition

 CanModify

 Clear

 CopyToClipboard

 Create

 CreateInnerEdit

 CutToClipboard

 Destroy

 DoButtonClick

 DoButtonDown

 DoButtonUp

 DoEditKeyDown

 DoEditKeyPress

 DoEditKeyUp

 PasteFromClipboard

 PostEditValue

 PropertiesChanged

 RefreshEdit

 ResetEditValue

 SelectAll

 ValidateEdit

Derived from TcxControl

 Create

 Destroy

 InvalidateRect


Events for TcxCustomExtLookupComboBox
TcxCustomExtLookupComboBox Events

TcxCustomExtLookupComboBox          Legend

Derived from TcxCustomEdit

 OnEditing

 OnFocusChanged


TcxCustomExtLookupComboBox.ActiveProperties

TcxCustomExtLookupComboBox          See Also

Obtains the properties that are currently applied to a lookup editor.

property ActiveProperties: TcxExtLookupComboBoxProperties;

Description

Use the ActiveProperties property to obtain the properties of the current lookup editor that are currently in effect.  This property is especially useful when the lookup editor has a repository item assigned to it via the RepositoryItem property.  In this case the ActiveProperties property returns the properties of the corresponding repository item that are active while the item is assigned to the lookup editor.  Otherwise, the inherent lookup editor’s properties are returned.

ReadOnly Property


TcxCustomExtLookupComboBox.EditValue

TcxCustomExtLookupComboBox          See Also

Specifies the value or an array of values edited by ExtLookupEditor.

property EditValue: Variant;

Description

ExtLookupComboBox allows you to edit a value(s) indirectly by picking up a record from the dropdown view.

The EditValue property represents a value(s) being edited.  It always matches a value(s) of a specific field(s) set via the Properties.KeyFieldNames property obtained from the view’s selected record.  If the KeyFieldNames property specifies more than one field names, EditValue represents an array of variant values.

Setting focus to a specific record within the view changes the EditValue property and the text displayed in the edit box.  For TcxDBExtLookupComboBox editors, changing EditValue modifies the value of the dataset field to which the editor is connected via the DataBinding.DataField attribute.

The value displayed within the ExtLookupEditor is addressed by the Properties.ListFieldItem view column.


TcxCustomExtLookupComboBox.Properties

TcxCustomExtLookupComboBox

Contains settings affecting the behavior of a ExtLookupEditor.

property Properties: TcxExtLookupComboBoxProperties;

Description

Use attributes of the Properties object to adjust settings of ExtLookupEditor.  The main attributes are:

•	the View property

Represents the view displayed within the dropdown window of ExtLookupEditor

•	the KeyFieldNames property

Specifies one or more fields matching the edit value(s).  See the EditValue property to get the edit value(s).  If the KeyFieldNames property specifies several field names delimited by the semicolon, the EditValue property holds an array of variants (values from the currently selected record in the dropdown view).

For data-aware ExtLookupEditors (TcxDBExtLookupComboBox), the KeyFieldNames property must correspond to the field being edited by ExtLookupComboBox.  This field is set via the DataBinding.DataField property

•	the ListFieldItem property

This property is used to specify the column in the dropdown view whose value is displayed in the edit box.  It is obtained from the current record.


TcxCustomExtLookupComboBox.Text

TcxCustomExtLookupComboBox          See Also

Specifies the text displayed in the edit box of ExtLookupEditor.

property Text: TCaption;

Description

The Text property represents the text displayed in the edit box of ExtLookupEditor.  Changing the Text property results in locating a specific record in the dropdown view whose field identified by the Properties.ListFieldItem attribute equals to Text.  This changes the edit value of the lookup editor (the EditValue property).  If no record can be located, the Text property will not be changed.


TcxDBExtLookupComboBox
 TcxDBExtLookupComboBox Object

Hierarchy          Properties          Methods          Events          See Also

Represents a control to edit a dataset field by picking up a record in its dropdown data-aware view.

Unit

cxDBExtLookupComboBox

TcxDBExtLookupComboBox = class(TcxCustomExtLookupComboBox);

Description

The TcxDBExtLookupComboBox control allows you to edit a dataset field referenced by the DataBinding.DataField property indirectly.  You are not able to type the text to change the edit value.  Instead, you change the edit value by picking up a record from the dropdown view.  The view’s selected record provides values for the display text (drawn in the edit box) and the edit value of TcxDBExtLookupComboBox.

The edit value is determined by the record’s Properties.KeyFieldNames field.  Moreover, the edit value matches this field value.  That is when you modify the EditValue property, the record with the key field matching the edit value is selected and the display text of ExtLookupEditor is changed.

The field (the DataBinding.DataField property) being edited by a TcxDBExtLookupComboBox control matches the edit value, i.e. it matches the value of the selected record’s Properties.KeyFieldNames field.

The editor’s display text is obtained from the Properties.ListFieldItem column of the selected record.  You cannot modify the text in the edit box.  It only helps you to identify the selected record visually.

To assign the view to an ExtLookupEditor, see its Properties.View attribute.  It is possible to use only a data-aware (banded) table view for this purpose.  A view repository component represented by the TcxGridViewRepository class helps you to create and customize views.

Note: you must not employ the same view in your grid control and ExtLookupEditor.

To know more about adjusting ExtLooupEditors, refer to the TcxCustomExtLookupComboBox class description.


TcxDBExtLookupComboBox Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomComboBox

     |

TcxCustomLookupEdit

     |

TcxCustomDBLookupEdit

     |

TcxCustomExtLookupComboBox

     |


Properties for TcxDBExtLookupComboBox
TcxDBExtLookupComboBox Properties

TcxDBExtLookupComboBox          Legend

In TcxDBExtLookupComboBox

DataBinding

Derived from TcxCustomExtLookupComboBox

ActiveProperties

EditValue

Properties

Text

Derived from TcxCustomDBLookupEdit

Properties

Derived from TcxCustomLookupEdit

Properties

Derived from TcxCustomComboBox

ItemIndex

Properties

Derived from TcxCustomDropDownEdit

DroppedDown

PopupWindow

Properties

Style

Derived from TcxCustomMaskEdit

Properties

Derived from TcxCustomTextEdit

BeepOnEnter

CursorPos

EditingText

Properties

SelLength

SelStart

SelText

Text

Derived from TcxCustomEdit

AutoSize

DataBinding

EditModified

EditValue

InnerEdit

Properties

RepositoryItem

Style

Derived from TcxControl

BorderStyle

Bounds

Canvas

ClientBounds

FocusOnClick

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxDBExtLookupComboBox
TcxDBExtLookupComboBox Methods

TcxDBExtLookupComboBox          Legend

Derived from TcxCustomComboBox

 CanDropDown

Derived from TcxCustomDropDownEdit

 CanDropDown

 CloseUp

 Create

 Destroy

 DropDown

 Focused

 PopupWindowClosed

 PopupWindowClosing

Derived from TcxCustomMaskEdit

 CutToClipboard

 PasteFromClipboard

Derived from TcxCustomTextEdit

 Clear

 ClearSelection

 CopyToClipboard

 Create

 CutToClipboard

 SelectAll

 SetSelection

 Undo

Derived from TcxCustomEdit

 AdjustInnerEditPosition

 CanModify

 Clear

 CopyToClipboard

 Create

 CreateInnerEdit

 CutToClipboard

 Destroy

 DoButtonClick

 DoButtonDown

 DoButtonUp

 DoEditKeyDown

 DoEditKeyPress

 DoEditKeyUp

 PasteFromClipboard

 PostEditValue

 PropertiesChanged

 RefreshEdit

 ResetEditValue

 SelectAll

 ValidateEdit

Derived from TcxControl

 Create

 Destroy

 InvalidateRect


Events for TcxDBExtLookupComboBox
TcxDBExtLookupComboBox Events

TcxDBExtLookupComboBox          Legend

Derived from TcxCustomEdit

 OnEditing

 OnFocusChanged


TcxDBExtLookupComboBox.DataBinding

TcxDBExtLookupComboBox          See Also

Specifies the object responsible for connection of the ExtLookupEditor to a dataset.

property DataBinding: TcxDBEditDataBinding;

Description

Use the attributes of the DataBinding object to specify the data source and field being edited by the ExtLookupEditor.  You should use the DataSource and DataField properties for this purpose.

The view displayed within the dropdown window of the ExtLookupEditor must contain a field corresponding to DataField.  This field is addressed by the editor’s Properties.KeyFieldNames property.  When you select a specific record from the dropdown view, this changes the value of the DataField into the value of the KeyFieldNames property of the selected record.  Conversely, changing the value of the DataField field results in selecting another record in the dropdown view whose KeyFieldNames field value is equal to the DataField field value.


TcxEditRepositoryExtLookupComboBoxItem
TcxEditRepositoryExtLookupComboBoxItem Object

Hierarchy          Properties          Methods          See Also

Represents a repository item containing settings for a TcxExtLookupComboBox editor.

Unit

cxDBExtLookupComboBox

TcxEditRepositoryExtLookupComboBoxItem = class(TcxEditRepositoryItem);

Description

TcxEditRepositoryExtLookupComboBoxItem stores properties specific to a TcxExtLookupComboBox editor via the Properties object.  A repository object of the TcxEditRepository class maintains a collection of repository items.


TcxEditRepositoryExtLookupComboBoxItem Hierarchy
Hierarchy

TComponent

     |

TcxEditRepositoryItem

     |


Properties for TcxEditRepositoryExtLookupComboBoxItem
TcxEditRepositoryExtLookupComboBoxItem Properties

TcxEditRepositoryExtLookupComboBoxItem          Legend

In TcxEditRepositoryExtLookupComboBoxItem

Properties

Derived from TcxEditRepositoryItem

Properties

Repository


Methods for TcxEditRepositoryExtLookupComboBoxItem
TcxEditRepositoryExtLookupComboBoxItem Methods

TcxEditRepositoryExtLookupComboBoxItem          Legend

Derived from TcxEditRepositoryItem

 Create

 Destroy

 GetBaseName


TcxEditRepositoryExtLookupComboBoxItem.Properties

TcxEditRepositoryExtLookupComboBoxItem

Defines settings specific to an appropriate editor.

property Properties: TcxExtLookupComboBoxProperties;

Description

Use the Properties object to define settings specific to a corresponding edit control.


TcxExtLookupComboBox
 TcxExtLookupComboBox Object

Hierarchy          Properties          Methods          Events          See Also

Represents a lookup editor displaying a grid view in its dropdown window.

Unit

cxDBExtLookupComboBox

TcxExtLookupComboBox = class(TcxCustomExtLookupComboBox);

Description

A TcxExtLookupComboBox control displays a data-aware grid view in its dropdown window which is specified by the Properties.View attribute.  Similar to other Express Editors, you have to use the attributes of the Properties object to customize an ExtLookupEditor.

A TcxExtLookupComboBox control allows you to edit values indirectly.  You are not able to type the text to change the edit value.  Instead, you change the edit value by picking up a record from the dropdown view.  The view’s selected record provides values for the display text (drawn in the edit box) and the edit value of TcxDBExtLookupComboBox.

You cannot modify the text (display value) in the edit box.  It is used for display purpose only to identify the record being currently selected.

The edit value of an ExtLookupEditor matches a value of the Properties.KeyFieldNames field of the currently selected record.  When you select a specific record within the dropdown view, the control’s edit value is automatically changed.  It always holds a value of the record’s Properties.KeyFieldNames field.  To access the edit value, see the published EditValue property.  It is possible to specify several key field names by separating them with the semicolon.  In this case, EditValue will contain an array of variants.

Changing EditValue automatically selects another record in the dropdown view whose key field values are equal to a new edit value(s).

To assign the view to an ExtLookupEditor, see its Properties.View attribute.  It is possible to use only a data-aware (banded) table view for this purpose.  A view repository component represented by the TcxGridViewRepository class helps you to create and customize views.  Note: you must not reuse the same view in your grid control and the ExtLookupEditor.

To get more information on customizing ExtLookupEditors, refer to the TcxCustomExtLookupComboBox topic.


TcxExtLookupComboBox Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomComboBox

     |

TcxCustomLookupEdit

     |

TcxCustomDBLookupEdit

     |

TcxCustomExtLookupComboBox

     |


Properties for TcxExtLookupComboBox
TcxExtLookupComboBox Properties

TcxExtLookupComboBox          Legend

Derived from TcxCustomExtLookupComboBox

ActiveProperties

EditValue

Properties

Text

Derived from TcxCustomDBLookupEdit

ActiveProperties

Properties

Derived from TcxCustomLookupEdit

Properties

Derived from TcxCustomComboBox

ItemIndex

Properties

Derived from TcxCustomDropDownEdit

DroppedDown

PopupWindow

Properties

Style

Derived from TcxCustomMaskEdit

Properties

Derived from TcxCustomTextEdit

BeepOnEnter

CursorPos

EditingText

Properties

SelLength

SelStart

SelText

Text

Derived from TcxCustomEdit

AutoSize

DataBinding

EditModified

EditValue

InnerEdit

Properties

RepositoryItem

Style

Derived from TcxControl

BorderStyle

Bounds

Canvas

ClientBounds

FocusOnClick

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxExtLookupComboBox
TcxExtLookupComboBox Methods

TcxExtLookupComboBox          Legend

Derived from TcxCustomComboBox

 CanDropDown

Derived from TcxCustomDropDownEdit

 CanDropDown

 CloseUp

 Create

 Destroy

 DropDown

 Focused

 PopupWindowClosed

 PopupWindowClosing

Derived from TcxCustomMaskEdit

 CutToClipboard

 PasteFromClipboard

Derived from TcxCustomTextEdit

 Clear

 ClearSelection

 CopyToClipboard

 Create

 CutToClipboard

 SelectAll

 SetSelection

 Undo

Derived from TcxCustomEdit

 AdjustInnerEditPosition

 CanModify

 Clear

 CopyToClipboard

 Create

 CreateInnerEdit

 CutToClipboard

 Destroy

 DoButtonClick

 DoButtonDown

 DoButtonUp

 DoEditKeyDown

 DoEditKeyPress

 DoEditKeyUp

 PasteFromClipboard

 PostEditValue

 PropertiesChanged

 RefreshEdit

 ResetEditValue

 SelectAll

 ValidateEdit

Derived from TcxControl

 Create

 Destroy


Events for TcxExtLookupComboBox
TcxExtLookupComboBox Events

TcxExtLookupComboBox          Legend

Derived from TcxCustomEdit

 OnEditing

 OnFocusChanged


TcxExtLookupComboBoxProperties
TcxExtLookupComboBoxProperties Object

Hierarchy          Properties          Methods          Events          See Also

Contains settings for ExtLookupEditors.

Unit

cxDBExtLookupComboBox

TcxExtLookupComboBoxProperties = class(TcxCustomDBLookupEditProperties);

Description

The TcxExtLookupComboBoxProperties class contains a set of attributes controlling the behavior of ExtLookupEditors (TcxExtLookupComboBox and TcxDBExtLookupComboBox).

An ExtLookupEditor displays a data-aware (banded) table view within its dropdown window specified by the View property.  Selecting a specific record in this view changes the display text and edit value(s) of the editor.  The display text is obtained from the ListFieldItem column of the selected record.  The edit value(s) is determined by a selected record’s field(s) set via the KeyFieldNames property.

You can use the FocusPopup property to enable/disable editing data within the dropdown view.  If FocusPopup is set to True, a user has the full-function grid view in the dropdown (editing, filtering is enabled).  Otherwise, a user is not able to edit and filter data; only sorting and grouping are supported.


TcxExtLookupComboBoxProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |

TcxCustomDropDownEditProperties

     |

TcxCustomComboBoxProperties

     |

TcxCustomLookupEditProperties

     |

TcxCustomDBLookupEditProperties

     |


Properties for TcxExtLookupComboBoxProperties
TcxExtLookupComboBoxProperties Properties

TcxExtLookupComboBoxProperties          Legend

In TcxExtLookupComboBoxProperties

AutoSearchOnPopup

FocusPopup

GridMode

ListFieldItem

View

Derived from TcxCustomDBLookupEditProperties

CaseSensitiveSearch

DataController

KeyFieldNames

ListField

ListFieldIndex

ListFieldNames

Derived from TcxCustomLookupEditProperties

DropDownAutoSize

DropDownHeight

DropDownListStyle

DropDownWidth

IncrementalFiltering

Derived from TcxCustomComboBoxProperties

DropDownAutoWidth

DropDownListStyle

DropDownRows

DropDownSizeable

DropDownWidth

ImmediateUpdateText

ItemHeight

Items

Revertable

Sorted

Derived from TcxCustomDropDownEditProperties

ButtonGlyph

ImmediateDropDown

ImmediatePopup

PopupAlignment

PopupAutoSize

PopupClientEdge

PopupHeight

PopupMinHeight

PopupMinWidth

PopupSizeable

PopupSysPanelStyle

PopupWidth

PostPopupValueOnTab

Derived from TcxCustomMaskEditProperties

AlwaysShowBlanksAndLiterals

CaseInsensitive

EditMask

IgnoreMaskBlank

IsMasked

MaskKind

Derived from TcxCustomTextEditProperties

AssignedValues

CharCase

DisplayFormat

EchoMode

EditFormat

HideCursor

HideSelection

ImeMode

ImeName

LookupItems

LookupItemsSorted

MaxLength

MaxValue

MinValue

OEMConvert

PasswordChar

UseDisplayFormatWhenEditing

ValidChars

ViewStyle

Derived from TcxCustomEditProperties

Alignment

AssignedValues

AutoSelect

BeepOnError

Buttons

ButtonsViewStyle

ClearKey

ClickKey

ImmediatePost

ReadOnly

UseLeftAlignmentOnEditing

UseMouseWheel

ValidateOnEnter


Methods for TcxExtLookupComboBoxProperties
TcxExtLookupComboBoxProperties Methods

TcxExtLookupComboBoxProperties          Legend

Derived from TcxCustomMaskEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

IsDisplayValueValid

IsEditValueValid

IsValidChar

RestoreDefaults


Events for TcxExtLookupComboBoxProperties
TcxExtLookupComboBoxProperties Events

TcxExtLookupComboBoxProperties          Legend

Derived from TcxCustomComboBoxProperties

OnDrawItem

OnMeasureItem

Derived from TcxCustomDropDownEditProperties

OnCloseQuery

OnCloseUp

OnInitPopup

OnPopup

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxExtLookupComboBoxProperties.AutoSearchOnPopup

TcxExtLookupComboBoxProperties          See Also

Determines whether an incremental search is performed when a user types within the edit box of the ExtLookupEditor.

property AutoSearchOnPopup: Boolean;

Description

The AutoSearchOnPopup property is in effect only when the FocusPopup property is set to True.

An ExtLookupEditor displays a value of the ListFieldItem column in the edit box.  If the AutoSearchOnPopup property is set to True, typing within the edit box initiates an incremental search against the ListFieldItem column.  This locates the first record whose ListFieldItem column value starts with the characters typed.  Also, you can continue the incremental search with the same starting characters by pressing the Ctrl+UpArrow or Ctrl+DownArrow key.

If the AutoSearchOnPopup property is set to False, the first character you typed within the edit box is used to locate the record whose ListFieldItem column value starts with it.  Subsequent characters typed are used to modify a value of the focused column of this record.

The default value of the AutoSearchOnPopup property is True.


TcxExtLookupComboBoxProperties.FocusPopup

TcxExtLookupComboBoxProperties

Specifies whether a user can edit within the dropdown view of the ExtLookupEditor.

property FocusPopup: Boolean;

Description

You can set the FocusPopup property to True to enable editing and filtering data within the dropdown view of the ExtLookupEditor.  When you open the dropdown window, for instance, by clicking the dropdown button or by pressing the F4, Alt+↑ or Alt+↓ key, the focus is moved to the view.  This view is specified by the View property.

If the FocusPopup property is True, incremental filtering within the dropdown view is disabled (the IncrementalFiltering property is automatically set to False).

When the FocusPopup property is set to False, editing and filtering data are not allowed.  In this case, focus remains in the edit box when you open the dropdown view.  However, you are still able to navigate its records using the Up and Down arrow keys.

The default value of the FocusPopup property is False.


TcxExtLookupComboBoxProperties.GridMode

TcxExtLookupComboBoxProperties

Specifies whether a lookup grid is in GridMode.

property GridMode: Boolean;

Description

You can use the GridMode property to speed up working with large lookup datasets (datasets displayed in the dropdown).

When Grid Mode is not set, a lookup editor loads all records into memory upon connecting to a dataset.  For large lookup datasets, this can result in lowering performance.

Setting the GridMode property to True enables caching of edit values and display texts.  If required edit value and display text are not present in the cache, they are obtained from the lookup dataset and stored in the cache for future use.  This considerably increases the performance, when the lookup combobox is used as an in-place editor in a Grid control.

Grid Mode imposes some restrictions on working with the editor and lookup dataset:

Grid Mode imposes some restrictions on working with the editor and lookup dataset:

•	the edit box of the lookup editor displays a value (TField.AsString) rather than display text of the field addressed by the ListFieldItem property.

•	similarly, an incremental search is performed against field values rather than display texts.

•	you must not navigate the lookup dataset programmatically as this can conflict with the Locate method used by the editor itself.

The default value of the GridMode property is False.


TcxExtLookupComboBoxProperties.ListFieldItem

TcxExtLookupComboBoxProperties          See Also

Specifies the column of the ExtLookupEditor’s dropdown view whose data is displayed in the edit box.

property ListFieldItem: TcxCustomGridTableItem;

Description

The text displayed within the edit box of the ExtLookupEditor is determined by the ListFieldItem property.  It references one of the columns of the dropdown view set via the View property.

You are not able to edit text in the edit box.  It is used for display purpose only to identify the record currently selected.

The edit value of the ExtLookupEditor matches a value of the selected record’s field identified by the KeyFieldNames property.  See the editor’s EditValue property to get the edit value.  It is possible to specify several key field names via the KeyFieldNames property.  In this case, EditValue will hold an array of variants.


TcxExtLookupComboBoxProperties.View

TcxExtLookupComboBoxProperties          See Also

Determines the data-aware (banded) table view displayed within the dropdown window of an ExtLookupEditor.

property View: TcxCustomGridTableView;

Description

Use the View property to assign a view displayed in the dropdown window of an ExtLookupEditor.  Only data-aware table and banded table views can be assigned.

A view repository component represented by the TcxGridViewRepository class helps you to create and customize views.  Note: you must not employ the same view in your grid control and ExtLookupEditor.

The value to display in the edit box and the edit value are obtained from the currently selected record in the dropdown view.  The display value is obtained from the column identified by the ListFieldItem property.

The edit value is specified by the field referenced by KeyFieldNames property.  See the editor’s EditValue property to get the edit value.  It is possible to specify several key fields via the KeyFieldNames property.  In this case, EditValue will hold an array of variants.


cxGrid Unit Overview
cxGrid Unit

Classes

TcxCustomGrid

TcxGrid

TcxGridLevelTabs

TcxGridViewRepository

Global Constants

cxGridLevelTabsDefaultCaptionAlignment

cxGridLevelTabsDefaultImageBorder


TcxCustomGrid
TcxCustomGrid Object

Hierarchy          Properties          Methods          Events          See Also

Represents the base class for a grid control.

Unit

cxGrid

TcxCustomGrid = class(TcxControl);

Description

The TcxCustomGrid class implements the ExpressQuantumGrid control which allows you to present data in a hierarchical tabular form.  It is the base class for TcxGrid which simply publishes TcxCustomGrid members.

TcxCustomGrid uses the concept of grid levels to create a hierarchical structure of displayed data.  A level can have child levels and each level represents data from an individual data store.  A level represents data with the help of a view (a TcxCustomGridView descendant) which implements displaying data in a specific form (table, banded table, card view and others).

Using the Levels property, you can access root grid levels (at the root nesting level) within a grid control and then obtain references to all child grid levels.  It is possible to create several grid levels at the same nesting level (even at the root nesting level).  Thus, one grid control enables you to represent data from multiple datasets.  You can switch between views displayed at the same nesting level with the help of the tab panel.

Views retrieve data via a data controller which provides an interface to a data store (custom data source or database) and provides grouping, sorting, filtering and calculation of summary values.  Not all views support all these operations. For instance, a card view (TcxGridCardView and TcxGridDBCardView) does not support grouping and calculation of summaries.

The Views property supports a list of all views within a grid control.  In order to display data from a view, you need to assign the view to the TcxGridLevel.GridView property.

Do not instantiate the TcxCustomGrid class.  Use the TcxGrid class instead.


TcxCustomGrid Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |


Properties for TcxCustomGrid
TcxCustomGrid Properties

TcxCustomGrid          Legend

In TcxCustomGrid

ActiveLevel

ActiveView

DragOpening

DragOpeningWaitTime

FocusedView

Levels

LevelTabs

LookAndFeel

RootLevelOptions

RootLevelStyles

ViewCount

Views

TabStop

Derived from TcxControl

BorderStyle

Bounds

Canvas

ClientBounds

FocusOnClick

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxCustomGrid
TcxCustomGrid Methods

TcxCustomGrid          Legend

In TcxCustomGrid

 BeginUpdate

 CancelUpdate

 CreateView

 EndUpdate

 LayoutChanged

 SizeChanged

Derived from TcxControl

 Create

 Destroy

 InvalidateRect


Events for TcxCustomGrid
TcxCustomGrid Events

TcxCustomGrid          Legend

In TcxCustomGrid

 OnActiveTabChanged

 OnFocusedViewChanged

 OnLayoutChanged

Derived from TcxControl

OnMouseEnter

OnMouseLeave


TcxCustomGrid.ActiveLevel

TcxCustomGrid          See Also

Specifies the root grid level which is currently active.

property ActiveLevel: TcxGridLevel;

Description

The grid control enables you to display several data views at one hierarchy level.  This takes place, for instance, if a master row has several detail views.  Moreover, the grid control is capable of displaying several data views at the root level of the hierarchy.  These views can be bound to the datasets which are not related to each other (compare with detail views, which are bound to the same master record).

The collection of root levels can be accessed via the Levels property of the grid control.  You can use an indexer to access individual levels represented by TcxGridLevel objects.  Assigning one of these objects to the ActiveLevel property makes a specified grid level active.

End-users can also navigate through root grid levels using special tabs.  These can be made visible by setting the RootLevelOptions.DetailTabsPosition property to dtpTop or to dtpLeft.  You must use the Caption property of TcxGridLevel objects to specify the tab captions corresponding to particular grid levels.

If end-users are able to navigate through root grid levels, you may want to determine the currently active one.  Read the ActiveLevel property for this purpose.

The image below displays the grid control containing two root grid levels. The Customers level is currently active.


TcxCustomGrid.ActiveView

TcxCustomGrid          See Also

Gets the view assigned to the currently active root grid level.

property ActiveView: TcxCustomGridView;

Description

The ActiveView property returns the view assigned to the level specified by the ActiveLevel property.  A view is an object capable of retrieving data from a data store to represent it in a particular form (table view, card view, for instance).

ReadOnly Property


TcxCustomGrid.DragOpening

TcxCustomGrid          See Also

Specifies whether top-level views are to be opened when dragging an object over their tabs.

property DragOpening: Boolean;

Description

A grid control gives you the ability to display several grid views at the root hierarchy level.  A user can switch between them via special tabs.  See the TcxGrid.RootLevelOptions.DetailTabsPosition property to make the tabs visible.

If DragOpening is True, the corresponding view is opened automatically when dragging an object over its tab.  Otherwise, the view is not opened.

The view’s OptionsBehavior.DragOpening property affects the opening of nested (non-root) detail views during drag-and-drop.

The delay between hovering over the tab and activating a relative grid view is defined by the DragOpeningWaitTime property.

The default value of the DragOpening property is True.


TcxCustomGrid.DragOpeningWaitTime

TcxCustomGrid          See Also

Specifies the delay in milliseconds between hovering over a target item and its opening/expanding during a drag-and-drop operation.

property DragOpeningWaitTime: Integer;

Description

It is possible to automatically open/expand group rows, master rows and tabbed views during drag-and-drop.  The DragOpeningWaitTime property specifies the delay between hovering over a particular item before expanding it (in milliseconds).

The TcxCustomGrid.DragOpening property determines whether tabbed root views are automatically opened when a user drags over their tabs.

The view’s OptionsBehavior.DragOpening property affects the opening of nested (non-root) detail views and group/master rows during drag-and-drop.

The default value of the DragOpeningWaitTime property is cxGridDefaultDragOpeningWaitTime.


TcxCustomGrid.FocusedView

TcxCustomGrid          See Also

Specifies the currently focused view.

property FocusedView: TcxCustomGridView;

Description

The FocusedView property provides access to the view which currently has focus and thus receives keyboard and mouse events.  When you switch between different views, the OnFocusedViewChanged event is generated.


TcxCustomGrid.Levels

TcxCustomGrid          See Also

Provides access to the collection of root grid levels within a grid control.

property Levels: TcxGridLevel;

Description

Use the Levels property to access the collection of root grid levels within a grid control.  Each grid level in turn may contain child levels, thus constructing a data hierarchy.  To access child grid levels or the currently active root grid level, use the TcxGridLevel.Items and ActiveLevel properties, correspondingly.

The following code iterates the child levels of the first root grid level and disables filtering for the associated grid views (but ignores card views).

//Delphi

var

  I: Integer;

  AGridView: TcxCustomGridView;

//...

  for I := 0 to cxGrid1.Levels[0].Count - 1 do

  begin

    AGridView := cxGrid1.Levels[0].Items[I].GridView;

    if AGridView is TcxGridTableView then

      TcxGridTableView(AGridView).OptionsCustomize.ColumnFiltering := False;

  end;

// C++ Builder

TcxCustomGridView *AGridView;

//...

  for (int I = 0; I < cxGrid1->Levels[0]->Count; I++)

  {

    AGridView = cxGrid1->Levels[0]->Items[I]->GridView;

    if (dynamic_cast< TcxGridTableView *>( AGridView) != 0)

      ((TcxGridTableView*)AGridView)->OptionsCustomize->ColumnFiltering = false;

  }


TcxCustomGrid.LevelTabs

TcxCustomGrid          See Also

Specifies a set of options that control the appearance aspects of grid level tabs.

property LevelTabs: TcxGridLevelTabs;

Description

Use this property to customize various appearance aspects of grid level tabs (such as painting style, tab caption alignment, etc).


TcxCustomGrid.LookAndFeel

TcxCustomGrid          See Also

Specifies the default look and feel of a grid control.

property LookAndFeel: TcxLookAndFeel;

Description

LookAndFeel controls the default look and feel of a grid control (tab panels, dropdown buttons) and the style behavior in response to user actions.

The NativeStyle attribute determines whether the control’s elements (borders, buttons and the background) are drawn using the display settings determined by the operating system.  For instance, in Windows XP the current XP theme is used if NativeStyle is set to True.

If NativeStyle is set to False, then the Kind property specifies the default look and feel of a grid.  Three styles (standard, flat and ultra flat) determine the manner in which a grid is painted and responds to mouse events.


TcxCustomGrid.RootLevelOptions

TcxCustomGrid          See Also

Represents a set of options managing the appearance of top grid levels.

property RootLevelOptions: TcxGridLevelOptions;

Description

The root nesting level can contain several grid levels accessible via the Levels member, each associated with a particular view.  The RootLevelOptions property supplies options to manage the appearance of views displayed via top grid levels.  This includes the width of a frame around these views and the position of the tabs for switching the displayed view.

For a non-root level equivalent, use the master level’s TcxGridLevel.Options property.

See the RootLevelStyles property to specify the style of the tab panel (the text font, color and background).


TcxCustomGrid.RootLevelStyles

TcxCustomGrid          See Also

Controls the appearance of root level elements.

property RootLevelStyles: TcxGridLevelStyles;

Description

The RootLevelStyles property provides attributes and events controlling the style for the tabs and the tab panel used for displaying views linked to root grid levels.  This property affects only the tabs at the root nesting level.  To specify styles for the tabs used to switch between child levels (and their views), see the master level’s TcxGridLevel.Styles property.

By default, the tab panel is invisible and only one view is displayed.  You can display the tab panel by setting the DetailTabsPosition attribute of the RootLevelOptions property to a value other than dtpNone.  In addition, you should set the Caption property of the corresponding grid level to identify the level (and its view) on the panel.

Use the RootLevelOptions property to specify the position of the tab panel and the frame width around the views at the root nesting level.


TcxCustomGrid.TabStop

TcxCustomGrid

Determines whether the end-user can tab to a grid control.

property TabStop: Boolean;

Description

The TabStop property allows you to specify whether a user can focus the current grid control using the Tab key.  If True, the grid control is in the tab order and the user can press the Tab key to move focus to it.  Otherwise, pressing the Tab key doesn’t allow you to move to the grid and it can be focused only by a mouse click.

Actually, when a user switches to the grid control by pressing the Tab key, focus moves to the currently focused grid site, i.e. to the focused grid view.  A grid site is a control of the TcxGridSite class containing and displaying grid views.  To access the currently focused view, use the FocusedGridView property.  The site displaying the view is specified by its Site property.

The default value of the TabStop property is True.


TcxCustomGrid.ViewCount

TcxCustomGrid          See Also

Gets the number of all views contained within the current grid control.

property ViewCount: Integer;

Description

The ViewCount property returns the number of views owned by a grid control.  See the Views property to access a particular view by its index.  This property stores all views created by the CreateView method.  A view to be displayed on screen must be associated with a grid level via the TcxGridLevel.GridView property.

ReadOnly Property


TcxCustomGrid.Views

TcxCustomGrid          See Also

Specifies the list of all views contained within a grid control.

property Views[Index: Integer]: TcxCustomGridView;

Description

Use the Views property to iterate through all views within a grid control.  The Views property stores all views created by the CreateView method.  Use this method to create a specific view based on the view class.  Refer to the Views topic regarding the view classes provided by ExpressQuantumGrid.

Each view must be associated with a level via the TcxGridLevel.GridView property to display its data on screen.

ReadOnly Property


TcxCustomGrid.BeginUpdate

TcxCustomGrid          See Also

Prevents a grid control from being updated until one of the EndUpdate or CancelUpdate methods is called.

procedure BeginUpdate;

Description

Each time you modify a single property of a grid control, it is updated to reflect these changes.  If you need to change several properties at once, flickering may occur.  In this case, you can use the BeginUpdate/EndUpdate methods to enclose the code updating a grid control.

The BeginUpdate method postpones grid updates.  To apply the changes made, you should call the EndUpdate method, which also causes the grid control invalidation.  If no changes are made, you can call the CancelUpdate method thus enabling further updates.  Unlike EndUpdate, the CancelUpdate method does not invalidate the grid control.  If you call the CancelUpdate method after performing changes that affect the visual representation of the grid, an exception will occur.

Ensure that every call to BeginUpdate has a corresponding call to the EndUpdate method (and, if required, the CancelUpdate method).


TcxCustomGrid.CancelUpdate

TcxCustomGrid          See Also

Enables updating of a grid control after the BeginUpdate method is called.

procedure CancelUpdate;

Description

Each time you modify a single property of a grid control, it is updated to reflect these changes.  If you need to change several properties at once, flickering may occur.  In this case, you can use the BeginUpdate/EndUpdate methods to enclose the code statements updating a grid control.

The BeginUpdate method postpones grid updates.  To apply the changes made, you should call the EndUpdate method, which also causes the grid control invalidation.  If no changes are made, you can call the CancelUpdate method thus enabling further updates.  Unlike EndUpdate, the CancelUpdate method does not invalidate the grid control.  If you call the CancelUpdate method after performing changes that affect the visual representation of the grid, an exception will occur.

Make sure that every call to BeginUpdate matches the call to the EndUpdate or CancelUpdate method.


TcxCustomGrid.CreateView

TcxCustomGrid          See Also

Creates a view of a specified class and adds it to the view list.

type

TcxCustomGridViewClass = class of TcxCustomGridView;

function CreateView(AViewClass: TcxCustomGridViewClass): TcxCustomGridView;

Description

The CreateView function creates a particular view, adds it to the view list specified by the Views property and returns it as the function’s result.  The view class is defined by the AViewClass parameter.  You can refer to the Views topic to learn about different view classes.

To display a view within a grid control, it must be assigned to a grid level of the TcxGridLevel class.


TcxCustomGrid.EndUpdate

TcxCustomGrid          See Also

Enables updating of a grid control after the BeginUpdate method is called.

procedure EndUpdate;

Description

Each time you modify a single property of a grid control, it is updated to reflect these changes.  If you need to change several properties at once, flickering may occur.  In this case, you can use the BeginUpdate/EndUpdate methods to enclose the code statements updating a grid control.

The BeginUpdate method postpones grid updates.  To apply the changes made, you should call the EndUpdate method, which causes the grid control invalidation.   If no changes are made, you can call the CancelUpdate method thus enabling further updates.  Unlike EndUpdate, the CancelUpdate method does not invalidate the grid control.  If you call the CancelUpdate method after performing changes that affect the visual representation of the grid, an exception will occur.

Make sure that every call to BeginUpdate matches the call to the EndUpdate or CancelUpdate method.


TcxCustomGrid.LayoutChanged

TcxCustomGrid

Invalidates a grid control in response to changing the layout.

procedure LayoutChanged; virtual;

Description

LayoutChanged invalidates a grid control when the layout (colors, texts, etc.) is changed.  Typically, you would use this when custom painting.


TcxCustomGrid.SizeChanged

TcxCustomGrid

Invalidates a grid control in response to resizing.

procedure SizeChanged; virtual;

Description

SizeChanged recalculates the dimensions of grid elements and then invalidates the grid control.  Use this method, for instance, when specifying fonts with different heights in style events.


TcxCustomGrid.OnActiveTabChanged

TcxCustomGrid          See Also

Occurs on switching between detail levels.

type

  TcxGridActiveTabChangedEvent = procedure(Sender: TcxCustomGrid; ALevel: TcxGridLevel) of object;

property OnActiveTabChanged: TcxGridActiveTabChangedEvent;

Description

The OnActiveTabChanged event occurs when a user switches to a detail level (defined by the ALevel parameter) by using tabs.  The Sender parameter specifies the grid control.

To display tabs, set the detail level caption via the TcxGridLevel.Caption property and specify the tabs position via the TcxGridLevelOptions.DetailTabsPosition property of a corresponding parent level.  To display the grid level tabs at the root level, specify the Grid.RootLevelOptions property’s value.


TcxCustomGrid.OnFocusedViewChanged

TcxCustomGrid          See Also

Occurs after setting focus to another view.

type

  TcxGridFocusedViewChangedEvent = procedure(Sender: TcxCustomGrid; APrevFocusedView, AFocusedView: TcxCustomGridView) of object;

property OnFocusedViewChanged: TcxGridFocusedViewChangedEvent;

Description

The OnFocusedViewChanged event occurs when the focused view identified by the FocusedView property is changed.  The Sender parameter defines the grid control for which this event is generated.  The APrevFocusedView and AFocusedView parameters specify the previously and currently focused views respectively.


TcxCustomGrid.OnLayoutChanged

TcxCustomGrid

Occurs after the grid layout changes.

type

  TcxGridLayoutChangedEvent = procedure(Sender: TcxCustomGrid; AGridView: TcxCustomGridView) of object;

property OnLayoutChanged: TcxGridLayoutChangedEvent;

Description

The OnLayoutChanged event is generated after the grid layout has changed. The grid layout refers to various properties defining grid element dimensions and arrangements, grouping and sorting states, styles, etc.


TcxGrid
 TcxGrid Object

Hierarchy          Properties          Methods          Events          See Also

Represents a grid control.

Unit

cxGrid

TcxGrid = class(TcxCustomGrid);

Description

A grid control presents data from a data store in various ways.  A grid is just a container of views and these retrieve data from data stores to display in various formats.  There are several different types of views provided by the ExpressQuantumGrid:

-	Table View (TcxGridTableView and TcxGridDBTableView) represents data in a tabular form (like a standard TCustomGrid control);

-	Banded Table View (TcxGridBandedTableView and TcxGridDBBandedTableView) a table view with an additional ability to create bands to hold the sets of columns;

-	Card View (TcxGridCardView and TcxGridDBCardView) represents data source records in cards (data source columns with the data displayed vertically);

-	Chart View (TcxGridChartView and TcxGridDBChartView) represents data using various chart diagrams (both simple and multiple/grouped diagram types).

The following image shows a grid control showing a master-detail relationship between the Customers and Orders tables from the CarsDB database.  Customers is a master table, while Orders is a detail table.

A view retrieves data from a data controller which provides an interface to a data store (custom data source or database), and provides grouping, filtering and calculation of summary values.  Not all views support all these operations.  For instance, a Card View (TcxGridCardView and TcxGridDBCardView) does not support grouping and calculation of summaries.

The Views property supports a list of all views within a grid control.  In order to display data from a view, it must be associated with a level (a TcxGridLevel object).  TcxGrid uses the concept of grid levels to create a hierarchical structure of displayed data.  A level can have child levels and each level represents data from an individual data store.  Levels allow you to construct complicated master-detail relationships between two or more stores.

Using the Levels property, you can access root grid levels (i.e. at the top level) within a grid control and then obtain references to all child grid levels.  It is possible to create several grid levels at the same hierarchical level (even at the top level).  Thus, a single grid control enables you to represent data from multiple datasets. You can see one view at a particular level and switch to another using the tab panel provided (it contains tabs at the top or at the left grid edge).

The grid displayed above has two root grid levels (Customers and Cars), each located on a separate page and they display data from the Customers and Cars tables respectively.  A user can switch between them by clicking the corresponding tab.

In order to make a pop-up menu appear when the grid is selected and an end-user clicks it with the right mouse button, assign a value to the PopupMenu property.


TcxGrid Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxCustomGrid

     |


Properties for TcxGrid
TcxGrid Properties

TcxGrid          Legend

Derived from TcxCustomGrid

ActiveLevel

ActiveView

DragOpening

DragOpeningWaitTime

FocusedView

Levels

LevelTabs

LookAndFeel

RootLevelOptions

RootLevelStyles

ViewCount

Views

TabStop

Derived from TcxControl

BorderStyle

Bounds

Canvas

ClientBounds

FocusOnClick

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxGrid
TcxGrid Methods

TcxGrid          Legend

Derived from TcxCustomGrid

 BeginUpdate

 CancelUpdate

 CreateView

 EndUpdate

 LayoutChanged

 SizeChanged

Derived from TcxControl

 Create

 Destroy

 InvalidateRect


Events for TcxGrid
TcxGrid Events

TcxGrid          Legend

Derived from TcxCustomGrid

 OnActiveTabChanged

 OnFocusedViewChanged

 OnLayoutChanged

Derived from TcxControl

OnMouseEnter

OnMouseLeave


TcxGridLevelTabs
TcxGridLevelTabs Object

Hierarchy          Properties          See Also

Represents options that control the appearance aspects of grid level tabs.

Unit

cxGrid

TcxGridLevelTabs = class(TPersistent)

Description

This class provides properties that allow you to control various appearance aspects of grid level tabs.  The grid control’s LevelTabs property references an instance of the TcxGridLevelTabs class.


TcxGridLevelTabs Hierarchy
Hierarchy

TPersistent

     |

TcxGridLevelTabs


Properties for TcxGridLevelTabs
TcxGridLevelTabs Properties

TcxGridLevelTabs          Legend

In TcxGridLevelTabs

CaptionAlignment

ImageBorder

Images

Owner

Slants

Style


TcxGridLevelTabs.CaptionAlignment

TcxGridLevelTabs          See Also

Specifies the horizontal alignment of tab captions.

type

  TAlignment = (taLeftJustify, taRightJustify, taCenter);

property CaptionAlignment: TAlignment;

Description

Use the CaptionAlignment property to specify how tab captions of all grid levels are aligned within the corresponding grid level tabs.  This property is only in effect for horizontally arranged grid level tabs (i.e. tabs of grid levels whose immediate parent grid level’s DetailTabsPosition property is set to dtpLeft).

To specify the caption and image associated with a grid level tab, use the Caption and ImageIndex properties of the corresponding grid level respectively.

The default value of the CaptionAlignment property is specified by the cxGridLevelTabsDefaultCaptionAlignment constant.


TcxGridLevelTabs.ImageBorder

TcxGridLevelTabs          See Also

Specifies the width (in pixels) of the transparent border around tab images.

property ImageBorder: Integer;

Description

Use this property to specify the width (in pixels) of the transparent border which is painted around grid level tab images.  0 indicates that the border is not painted.

To associate an image with a grid level tab, use the ImageIndex property of the corresponding grid level.

The default value of the ImageBorder property is specified by the cxGridLevelTabsDefaultImageBorder constant.


TcxGridLevelTabs.Images

TcxGridLevelTabs

Specifies the source of images to display within grid level tabs.

property Images: TImageList;

Description

Use this property to specify the TImageList object that can be displayed within grid level tabs.  To associate an image with a grid level tab, use the grid level’s ImageIndex property.  The image will be displayed within the tab along with a tab caption specified by the grid level’s Caption property.


TcxGridLevelTabs.Owner

TcxGridLevelTabs

Provides access to the grid control which displays grid level tabs.

property Owner: TcxCustomGrid;

Description

Use this property to access members of the grid control that displays grid level tabs using settings specified by the current instance of the TcxGridLevelTabs class.

ReadOnly Property


TcxGridLevelTabs.Slants

TcxGridLevelTabs

Specifies options available for tab slants.

property Slants: TcxTabSlants;

Description

When the Slanted painting style is applied, the Slants property determines the manner in which grid level tab slants are painted.  Options include slant kind and the positions (sides) at which the tabs are "slanted".

Use the Style property to specify the painting style for all grid level tabs.


TcxGridLevelTabs.Style

TcxGridLevelTabs

Specifies the painting style of grid level tabs.

type

  TcxPCStyleID = -1 .. High(Integer);

property Style: TcxPCStyleID;

Description

Use this property to specify the painting style for all grid level tabs.  Refer to the description of TcxPCStyleID for all available painting styles.

Note:	Use the Slants property to customize the appearance of grid level tabs when the Slanted painting style is applied.

The default value of the Style property is specified by the cxPCDefaultStyle constant.


TcxGridViewRepository
 TcxGridViewRepository Object

Hierarchy          Properties          Methods          See Also

Represents a component for managing a collection of grid views.

Unit

cxGrid

TcxGridViewRepository = class(TComponent);

Description

The view repository represents a component allowing you to create, delete and customize grid views.  Views created within the view repository can be used in a grid control (assigned to a specific level) or in ExtLookupEditors which implement lookup functionality with the help of grid views.

Note: You must not employ the same view in your grid control and ExtLookupEditor at the same time.

The design-time editor of a view repository is similar to the grid’s Component Editor except that it does not provide the Structure panel.  To open it, double-click the view repository icon or select the Editor… option from its context menu.

Using the editor you can add and delete views, access their properties via the Object Inspector, manipulate view columns and manage summaries.  Please refer to the Component Editor topic to get more information on editor’s controls.


TcxGridViewRepository Hierarchy
Hierarchy

TComponent

     |


Properties for TcxGridViewRepository
TcxGridViewRepository Properties

TcxGridViewRepository          Legend

In TcxGridViewRepository

Count

Items


Methods for TcxGridViewRepository
TcxGridViewRepository Methods

TcxGridViewRepository          Legend

In TcxGridViewRepository

 CreateItem


TcxGridViewRepository.Count

TcxGridViewRepository          See Also

Specifies the number of views stored in the view repository.

property Count: Integer;

Description

The Count property returns the number of views within the view repository.  You can add a view via the CreateItem method.  All views can be accessed via the indexed Items property.

ReadOnly Property


TcxGridViewRepository.Items

TcxGridViewRepository          See Also

Provides the indexed access to views within the view repository.

property Items[Index: Integer]: TcxCustomGridView;

Description

Use the Items property to access a specific view by its zero-based index within the repository.  You can determine the number of views via the Count property.  To add a view to the repository, use the CreateItem method.

ReadOnly Property


TcxGridViewRepository.CreateItem

TcxGridViewRepository          See Also

Creates a new view of a specific class and adds it to the view repository.

type TcxCustomGridViewClass = class of TcxCustomGridView;

function CreateItem(AItemClass: TcxCustomGridViewClass): TcxCustomGridView;

Description

You can use the CreateItem function to add a new view to the view repository.  The class of the view is determined by the AItemClass parameter.  The Editor of the view repository allows you to create a view of the required type at design-time.  To open it, double-click the view repository icon or select the Editor… option from its context menu.

To delete a specific view from the view repository, call its destructor.

The following code adds a new TcxGridDBTableView view to the view repository:

//Delphi

var

  AView: TcxGridDBTableView;

//...

  AView := TcxGridDBTableView

    (cxGridViewRepository1.CreateItem(TcxGridDBTableView));

  with AView do

  begin

    DataController.DataSource := DataSource1;

    DataController.CreateAllItems;

    //...

  end;

//C++ Builder

  TcxGridDBTableView* AView = (TcxGridDBTableView*)

    cxGridViewRepository1->CreateItem(__classid(TcxGridDBTableView));

  AView->DataController->DataSource = DataSource1;

  AView->DataController->CreateAllItems();

  //...


cxGridLevelTabsDefaultCaptionAlignment constant
cxGridLevelTabsDefaultCaptionAlignment global constant

Specifies the default horizontal alignment of tab captions.

Unit

cxGrid

cxGridLevelTabsDefaultCaptionAlignment = taCenter;

Description

This constant determines the default value of the grid control’s LevelTabs.CaptionAlignment property.  This property specifies how tab captions of all grid levels are aligned within the corresponding horizontally arranged grid level tabs.


cxGridLevelTabsDefaultImageBorder constant
cxGridLevelTabsDefaultImageBorder global constant

Specifies the default width (in pixels) of the transparent border around tab images.

Unit

cxGrid

cxGridLevelTabsDefaultImageBorder = 0;

Description

This constant determines the default value of the grid control’s LevelTabs.ImageBorder property.  This property specifies the width (in pixels) of the transparent border that is painted around grid level tab images.


Legend

 Protected

 Published

 ReadOnly


TcxGridBandedColumn
TcxGridBandedColumn Object

Hierarchy          Properties          Methods          Events          See Also

Represents a column within a banded table view.

Unit

cxGridBandedTableView

TcxGridBandedColumn = class(TcxGridColumn);

Description

The TcxGridBandedColumn class extends the functionality of a TcxGridColumn by enabling grouping of columns in bands (TcxGridBand) in a banded table view.  A banded table view of the TcxGridBandedTableView class provides the Bands and Columns properties containing bands and columns respectively.  Only the columns associated with a band by setting the column’s Position object attributes are displayed within a banded table view.

Using Options you can specify the behavior of the column, i.e. whether the column can be resized, moved, focused or used for grouping etc.

The Styles object provides a number of properties and events managing the appearance of the column elements (header, footer panels and data cells).


TcxGridBandedColumn Hierarchy
Hierarchy

TComponent

     |

TcxCustomGridTableItem

     |

TcxGridColumn

     |


Properties for TcxGridBandedColumn
TcxGridBandedColumn Properties

TcxGridBandedColumn          Legend

In TcxGridBandedColumn

GridView

Options

Position

Styles

Derived from TcxGridColumn

FooterAlignmentHorz

GridView

GroupSummaryAlignment

HeaderGlyph

HeaderGlyphAlignmentHorz

HeaderGlyphAlignmentVert

IsBottom

IsLeft

IsMostBottom

IsMostLeft

IsMostRight

IsPreview

IsRight

Options

Styles

Derived from TcxCustomGridTableItem

ActuallyVisible

Caption

DataBinding

DateTimeGrouping

Editing

EditValue

Filtered

Focused

GridView

GroupIndex

HeaderAlignmentHorz

HeaderAlignmentVert

Hidden

ID

IncSearching

Index

IsFirst

IsLast

MinWidth

Options

Properties

PropertiesClass

RepositoryItem

SortIndex

SortOrder

Styles

Visible

VisibleForCustomization

VisibleIndex

Width


Methods for TcxGridBandedColumn
TcxGridBandedColumn Methods

TcxGridBandedColumn          Legend

Derived from TcxCustomGridTableItem

 ApplyBestFit

 GetProperties

 RestoreDefaults


Events for TcxGridBandedColumn
TcxGridBandedColumn Events

TcxGridBandedColumn          Legend

Derived from TcxGridColumn

 OnCustomDrawFooterCell

 OnCustomDrawHeader

 OnHeaderClick

Derived from TcxCustomGridTableItem

 OnCustomDrawCell

 OnGetCellHint

 OnGetDataText

 OnGetDisplayText

 OnGetFilterDisplayText

 OnGetFilterValues

 OnGetProperties

 OnGetStoredProperties

 OnGetStoredPropertyValue

 OnInitFilteringDateRanges

 OnSetStoredPropertyValue

 OnUserFiltering


TcxGridBandedColumn.GridView

TcxGridBandedColumn

Gets the banded table view containing the column.

property GridView: TcxGridBandedTableView;

Description

The GridView property returns the banded table view which contains the current column.  Use this property to access multiple options managing the behavior and appearance of all columns within a view.  To access bands contained within a banded table view, see the view’s Bands attribute.

ReadOnly Property


TcxGridBandedColumn.Options

TcxGridBandedColumn          See Also

Contains a number of settings managing the behavior of banded columns.

property Options: TcxGridBandedColumnOptions;

Description

Using the Options property you can perform various operations on a column.  You can enable or disable editing the column data, grouping by the column, sizing, sorting, etc.  The view’s options allow you to define settings common to all columns in a banded table view.


TcxGridBandedColumn.Position

TcxGridBandedColumn          See Also

Specifies the position of a column within a banded table view.

property Position: TcxGridBandedColumnPosition;

Description

Use the Position property to specify the band in which the column will be displayed and the column position within this band.  To assign a column to a band you have to set the Position.BandIndex property to a band index in the view’s Bands collection.  The Position.ColIndex and Position.RowIndex specify the coordinates of the column within the band.


TcxGridBandedColumn.Styles

TcxGridBandedColumn          See Also

Specifies styles managing the appearance of banded table column elements.

property Styles: TcxGridBandedColumnStyles;

Description

Use the Styles object to specify styles for column elements (data cells, header and footer panels).  The view’s Styles property manages the appearance of all columns within a view.

You can handle the styles events to provide different styles for individual records.


TcxGridBandedColumnOptions
TcxGridBandedColumnOptions Object

Hierarchy          Properties          See Also

Represents settings managing the behavior of a banded column.

Unit

cxGridBandedTableView

TcxGridBandedColumnOptions = class(TcxGridColumnOptions);

Description

The TcxGridBandedColumnOptions class provides a number of settings managing the behavior of a banded column.  TcxGridBandedColumnOptions extends the functionality of the TcxGridColumnOptions class by introducing the VertSizing property which controls the ability to resize a column vertically.

You can adjust various options via multiple view properties, thus specifying behavior common to all columns in this view.

To set options to a banded column, see TcxGridBandedColumn.Options.


TcxGridBandedColumnOptions Hierarchy
Hierarchy

TPersistent

     |

TcxCustomGridTableItemCustomOptions

     |

TcxCustomGridTableItemOptions

     |

TcxGridColumnOptions

     |


Properties for TcxGridBandedColumnOptions
TcxGridBandedColumnOptions Properties

TcxGridBandedColumnOptions          Legend

In TcxGridBandedColumnOptions

VertSizing

Derived from TcxGridColumnOptions

HorzSizing

Derived from TcxCustomGridTableItemOptions

Editing

Filtering

FilteringFilteredItemsList

FilteringMRUItemsList

FilteringPopup

FilteringPopupMultiSelect

Focusing

Grouping

IgnoreTimeForFiltering

IncSearch

Moving

ShowCaption

ShowEditButtons

SortByDisplayText

Sorting


TcxGridBandedColumnOptions.VertSizing

TcxGridBandedColumnOptions          See Also

Specifies whether a user can resize the banded column vertically.

property VertSizing: Boolean;

Description

If the VertSizing property is True, a user can change the height of a banded column header.  This changes the height of the corresponding column cells.

If VertSizing is False, then the column height is defined by the column’s Position.LineCount attribute.

The OptionsCustomize.VertColumnSizing property allows you to prevent a user from changing the height of all banded columns in a view.

The default value of the VertSizing property is True.


TcxGridBandedColumnPosition
TcxGridBandedColumnPosition Object

Hierarchy          Properties          Methods          See Also

Represents the position of a banded column within a banded table view.

Unit

cxGridBandedTableView

TcxGridBandedColumnPosition = class(TcxCustomGridTableItemCustomOptions);

Description

The TcxGridBandedColumnPosition class defines attributes specifying the band to display the banded column and the coordinates of the column within this band.  To set the banded column position, use the TcxGridBandedColumn.Position property.

You can assign a banded column to a band by setting the BandIndex property.  It assigns the band to display the column.  Columns in a band can appear in different rows and this is controlled by the RowIndex.  The horizontal position of a column in a row is set via the ColIndex attribute.  A column can be located on several rows (one by default).  To set the banded column height use LineCount.


TcxGridBandedColumnPosition Hierarchy
Hierarchy

TPersistent

     |

TcxCustomGridTableItemCustomOptions

     |


Properties for TcxGridBandedColumnPosition
TcxGridBandedColumnPosition Properties

TcxGridBandedColumnPosition          Legend

In TcxGridBandedColumnPosition

Band

BandIndex

ColIndex

GridView

Item

LineCount

Row

RowIndex

VisibleBandIndex

VisibleColIndex

VisibleRowIndex


Methods for TcxGridBandedColumnPosition
TcxGridBandedColumnPosition Methods

TcxGridBandedColumnPosition          Legend

In TcxGridBandedColumnPosition

 Create


TcxGridBandedColumnPosition.Band

TcxGridBandedColumnPosition          See Also

Gets the band to which the banded column is assigned.

property Band: TcxGridBand;

Description

The Band property returns the band displaying the current column.  The band allows you to define properties common to all columns within the band and to access general band settings.  To assign a band to a column, see the BandIndex property.

ReadOnly Property


TcxGridBandedColumnPosition.BandIndex

TcxGridBandedColumnPosition          See Also

Specifies the band which displays the current column.

property BandIndex: Integer;

Description

Use the BandIndex property to define the band displaying the current column.  The BandIndex property addresses a band by its index in the view’s Bands collection.  To specify the position of a column within a band, you need to set the ColIndex and/or RowIndex properties.

If you set BandIndex to –1, the column will be removed from the band.


TcxGridBandedColumnPosition.ColIndex

TcxGridBandedColumnPosition          See Also

Specifies the horizontal position of the current column in a band row.

property ColIndex: Integer;

Description

The ColIndex property allows you to define the position of a banded column in a row specified by the RowIndex property value.  The left-most column in a row has a ColIndex value of 0.


TcxGridBandedColumnPosition.GridView

TcxGridBandedColumnPosition

Gets the banded table view containing the current column.

property GridView: TcxGridBandedTableView;

Description

The GridView property provides access to the view containing the current banded column.  You can use this property to adjust general view settings such as the number of bands and columns, etc.

ReadOnly Property


TcxGridBandedColumnPosition.Item

TcxGridBandedColumnPosition

Specifies the banded column whose position is defined via the current TcxGridBandedColumnPosition instance.

property Item: TcxGridBandedColumn;

Description

The Item property references the banded column whose position within a banded view is specified via the current TcxGridBandedColumnPosition class instance.  Use this property to access the sets of behavior options and styles and other column properties.

ReadOnly Property


TcxGridBandedColumnPosition.LineCount

TcxGridBandedColumnPosition

Defines the number of lines in which the current column is displayed.

property LineCount: Integer;

Description

The LineCount property specifies the height of a column.  By default, columns are displayed with one line each.  You can use the LineCount property to expand the column to several lines.  Whenever this property’s value exceeds the default value, the contents of its cells are automatically shown in a data row in the manner of a multi-line column.  Note that this also prohibits end-users from changing the height of data rows by dragging the bottom edge of indicator items (when the column is currently visible within the view and the view’s OptionsCustomize.DataRowSizing property is set to True).

The default value of the LineCount property is 1.


TcxGridBandedColumnPosition.Row

TcxGridBandedColumnPosition          See Also

Gets the band row containing the current column.

property Row: TcxGridBandRow;

Description

The Row property returns a TcxGridBandRow object referencing the row which contains the current banded column.  The column row is assigned via the RowIndex attribute.

ReadOnly Property


TcxGridBandedColumnPosition.RowIndex

TcxGridBandedColumnPosition          See Also

Identifies the vertical position of the banded column.

property RowIndex: Integer;

Description

Use the RowIndex property to define the band row to display the current banded column.  The row itself can be accessed via the Row object.  By default, all columns are placed at the first band row with RowIndex set to 0.  To define the horizontal position of the column in a row, use the ColIndex property.


TcxGridBandedColumnPosition.VisibleBandIndex

TcxGridBandedColumnPosition          See Also

Returns the position of the band containing the current column.

property VisibleBandIndex: Integer;

Description

The VisibleBandIndex property returns the position of the band which contains the current banded column.  If the band is not visible (TcxGridBand.Visible is set to False), –1 is returned.

ReadOnly Property


TcxGridBandedColumnPosition.VisibleColIndex

TcxGridBandedColumnPosition          See Also

Gets the horizontal position of the current column among visible columns of an appropriate band row.

property VisibleColIndex: Integer;

Description

Unlike the ColIndex property, the VisibleColIndex returns –1 if the column is not displayed in a row (the column’s Visible property is set to False) or the band is not assigned.

ReadOnly Property


TcxGridBandedColumnPosition.VisibleRowIndex

TcxGridBandedColumnPosition          See Also

Returns the visible position of a column row.

property VisibleRowIndex: Integer;

Description

If the column is contained in a non-visible band row (i.e. if all contained columns have their Visible property set to False), then the VisibleRowIndex property returns –1.

ReadOnly Property


TcxGridBandedColumnPosition.Create

TcxGridBandedColumnPosition

Creates an instance of the TcxGridBandedColumnPosition class.

constructor Create(AItem: TcxCustomGridTableItem); override;

Description

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


TcxGridBandedColumnStyles
TcxGridBandedColumnStyles Object

Hierarchy          Properties          Methods          Events          See Also

Represents styles managing the appearance of banded column elements.

Unit

cxGridBandedTableView

TcxGridBandedColumnStyles = class(TcxGridColumnStyles);

Description

The TcxGridBandedColumnStyles property defines a number of properties and events allowing you to specify the appearance of the column’s content region, header and footer panels.  By handling styles events, it is possible to define different styles for individual records.  To set the styles of the banded column, see the TcxGridBandedColumn.Styles property.

You can define the default appearance of banded columns via the view’s Styles and the band’s Styles objects followed by redefining styles for individual columns as necessary.


TcxGridBandedColumnStyles Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomStyles

     |

TcxStyles

     |

TcxCustomGridStyles

     |

TcxCustomGridTableItemStyles

     |

TcxGridColumnStyles

     |


Properties for TcxGridBandedColumnStyles
TcxGridBandedColumnStyles Properties

TcxGridBandedColumnStyles          Legend

In TcxGridBandedColumnStyles

Item

Derived from TcxGridColumnStyles

Footer

GridView

GroupSummary

Header

Item

Derived from TcxCustomGridTableItemStyles

Content

GridView

Item

Derived from TcxCustomGridStyles

GridView

Derived from TcxCustomStyles

StyleSheet


Methods for TcxGridBandedColumnStyles
TcxGridBandedColumnStyles Methods

TcxGridBandedColumnStyles          Legend

Derived from TcxGridColumnStyles

GetFooterParams

GetGroupSummaryParams

GetHeaderParams

Derived from TcxCustomStyles

Assign

Create

Destroy


Events for TcxGridBandedColumnStyles
TcxGridBandedColumnStyles Events

TcxGridBandedColumnStyles          Legend

Derived from TcxGridColumnStyles

OnGetFooterStyle

OnGetFooterStyleEx

OnGetFooterSummaryStyle

OnGetGroupSummaryStyle

OnGetHeaderStyle

Derived from TcxCustomGridTableItemStyles

OnGetContentStyle


TcxGridBandedColumnStyles.Item

TcxGridBandedColumnStyles

Specifies the banded column for which the current TcxGridBandedColumnStyles instance is created.

property Item: TcxGridBandedColumn;

Description

The Item property returns the banded column for which the current TcxGridBandedColumnStyles instance defines the appearance of column elements.

ReadOnly Property


TcxGridBandRow
TcxGridBandRow Object

Hierarchy          Properties          Methods          See Also

Represents a row in a band.

Unit

cxGridBandedTableView

TcxGridBandRow = class(TObject);

Description

The position of a column within a band in a banded table view is determined by two coordinates: ColIndex and RowIndex.  The RowIndex references the band row in which the column caption is displayed.  The row index also affects the position of data cells in this column and the footer summary result position.

Every row in a band is represented by the TcxGridBandRow class.  You can define the horizontal position of a banded column within a row by setting the ColIndex property.  The row’s Items property provides an indexed access to columns that belong to the current row.  Visible columns can be accessed via the VisibleItems property.

You can access a specific row of a band via the TcxGridBand.Rows property of the TcxGridBandRows class.  TcxGridBandRows provides the Items and VisibleItems properties that support collections of all and visible rows respectively.

The following image shows several columns arranged into 2 band rows within a single band:

The RowIndex property value is 0 for the Name, Fixed Date and Created Date columns, and 1 for the Project, Type and Status columns.  The ColIndex property value for the Name and Project columns is 0, 1 for the Fixed Data and Type columns and 2 for the Created Date and Status columns.


TcxGridBandRow Hierarchy
Hierarchy

TObject

     |


Properties for TcxGridBandRow
TcxGridBandRow Properties

TcxGridBandRow          Legend

In TcxGridBandRow

BandRows

Count

Index

IsFirst

IsLast

Items

LineCount

LineOffset

Visible

VisibleCount

VisibleIndex

VisibleItems


Methods for TcxGridBandRow
TcxGridBandRow Methods

TcxGridBandRow          Legend

In TcxGridBandRow

 Destroy

 IndexOf


TcxGridBandRow.BandRows

TcxGridBandRow

Specifies a collection of rows within a band to which the current TcxGridBandRow object belongs.

property BandRows: TcxGridBandRows;

Description

The BandRows property returns the reference to a collection containing the current row.  See the TcxGridBandRows.Count property to ascertain the number of rows in the collection.  To access a row at a specific index, use the TcxGridBandRows.Items property.

ReadOnly Property


TcxGridBandRow.Count

TcxGridBandRow          See Also

Specifies the number of columns contained within the current row.

property Count: Integer;

Description

The Count property returns the number of columns assigned to the current row that is columns whose Position.RowIndex property addresses this row.  Use the Items property to access a specific banded table column.

ReadOnly Property


TcxGridBandRow.Index

TcxGridBandRow          See Also

Specifies the position of the row within a row collection to which it belongs.

property Index: Integer;

Description

The Index property returns the zero-based index of the current row within a row collection defined by the BandRows property.  The row index affects the vertical position of a row in a band.

ReadOnly Property


TcxGridBandRow.IsFirst

TcxGridBandRow          See Also

Specifies whether the row is displayed at the top of a band.

property IsFirst: Boolean;

Description

The IsFirst property returns True if the row is positioned at the top of a band, i.e. its VisibleIndex is 0.  Otherwise, False is returned.

ReadOnly Property


TcxGridBandRow.IsLast

TcxGridBandRow          See Also

Specifies whether the row is displayed last within a band.

property IsLast: Boolean;

Description

Use the IsLast property to ascertain whether the current row is the last visible row within a band.  The visible position of a row is identified by the VisibleIndex attribute.

ReadOnly Property


TcxGridBandRow.Items

TcxGridBandRow          See Also

Provides the indexed access to columns assigned to the current row.

property Items[Index: Integer]: TcxGridBandedColumn;

Description

The Items property provides a reference to a column at a specific horizontal position in a row.  You can specify the column position via the column’s Position.ColIndex property.  The number of columns assigned to the row is determined by Count.

The VisibleItems property supports a collection of visible columns (i.e. with their Visible property set to True).

ReadOnly Property


TcxGridBandRow.LineCount

TcxGridBandRow          See Also

Returns the number of lines occupied by the current row.

property LineCount: Integer;

Description

You can force every column in a row to occupy several lines via the Position.LineCount attribute.  In this case, the row will occupy several lines.  Columns, combined into a band may have different height settings:

The LineCount property returns the maximum of the column Position.LineCount value, i.e. for the image above, the LineCount property value is 4.

ReadOnly Property


TcxGridBandRow.LineOffset

TcxGridBandRow          See Also

Gets the number of lines in a band which precede the current row.

property LineOffset: Integer;

Description

The LineOffset property returns the number of lines preceding the current row.  Every row can occupy several lines, the number of which is available via LineCount.

ReadOnly Property


TcxGridBandRow.Visible

TcxGridBandRow

Specifies whether the current row is visible.

property Visible: Boolean;

Description

The Visible property returns True if a row contains any visible columns (a column whose Visible property is set to True).  If all columns assigned to a row are hidden, the row is also hidden.

ReadOnly Property


TcxGridBandRow.VisibleCount

TcxGridBandRow          See Also

Specifies the number of visible columns assigned to a row.

property VisibleCount: Integer;

Description

The VisibleCount property returns the number of visible banded columns assigned to a row (i.e. Visible property is set to True).  You can access visible columns via the indexed VisibleItems property.  If a row is not assigned any columns (i.e. a new row) or no columns assigned are visible, VisibleCount returns 0 and the row is not displayed.

ReadOnly Property


TcxGridBandRow.VisibleIndex

TcxGridBandRow          See Also

Specifies the position of the current row among visible band rows.

property VisibleIndex: Integer;

Description

The VisibleIndex property returns the index of the current row within the BandRows.VisibleItems collection.  Visible indexes define the order in which rows are displayed within a band.

ReadOnly Property


TcxGridBandRow.VisibleItems

TcxGridBandRow          See Also

Specifies a collection of visible columns displayed in the current row.

property VisibleItems[Index: Integer]: TcxGridBandedColumn;

Description

The VisibleItems property provides indexed access to visible columns assigned to the current row (i.e. with the Visible property set to True).  The number of visible columns is determined by the VisibleCount property.  To access all columns assigned to a row, use the Items property.

ReadOnly Property


TcxGridBandRow.Destroy

TcxGridBandRow

Destroys an instance of the TcxGridBandRow class.

destructor Destroy; override;

Description

The destructor destroys the current row and removes it from the band row collection.


TcxGridBandRow.IndexOf

TcxGridBandRow          See Also

Returns the index of a given column.

function IndexOf(AColumn: TcxGridBandedColumn): Integer;

Description

Use the IndexOf property to determine the position of the column specified by the AColumn parameter in a collection of columns assigned to this row.  This collection is supported by the Items property.  If the column is not assigned to the current row, -1 is returned.


TcxGridBandRows
TcxGridBandRows Object

Hierarchy          Properties          Methods          See Also

Represents a collection of rows belonging to a specific band in a banded table view.

Unit

cxGridBandedTableView

TcxGridBandRows = class(TObject);

Description

The TcxGridBandRows class stores rows belonging to the band passed as the constructor parameter.  Use the TcxGridBand.Rows property to access a collection of rows for this band.  TcxGridBandRows provides the Items array property which supports a collection of individual rows (TcxGridBandRow).   Visible rows can be accessed via the VisibleItems property.


TcxGridBandRows Hierarchy
Hierarchy

TObject

     |


Properties for TcxGridBandRows
TcxGridBandRows Properties

TcxGridBandRows          Legend

In TcxGridBandRows

Band

Count

FirstVisible

GridView

Items

LastVisible

VisibleCount

VisibleItems


Methods for TcxGridBandRows
TcxGridBandRows Methods

TcxGridBandRows          Legend

In TcxGridBandRows

 Create

 Destroy

 GetLineIndex

 GetRowIndex


TcxGridBandRows.Band

TcxGridBandRows

Specifies a band owning the current row collection.

property Band: TcxGridBand;

Description

Read the Band property to get a band owning the current row collection.

ReadOnly Property


TcxGridBandRows.Count

TcxGridBandRows          See Also

Specifies the number of rows in the current row collection.

property Count: Integer;

Description

The Count property specifies the number of rows in the current TcxGridBandRows collection.  To access a particular row, see the Items property.  Rows that are currently visible can also be retrieved via the VisibleItems array.


TcxGridBandRows.FirstVisible

TcxGridBandRows          See Also

Returns the first visible row in the current TcxGridBandRows collection.

property FirstVisible: TcxGridBandRow;

Description

The FirstVisible property specifies the first visible row in a band.  Visible rows can be accessed via the VisibleItems collection.

ReadOnly Property


TcxGridBandRows.GridView

TcxGridBandRows

Specifies the banded table view containing the band to which the current row collection belongs.

property GridView: TcxGridBandedTableView;

Description

Use the GridView property to obtain a reference to a view containing the current row collection.  A banded table view contains a set of bands each of which may have one or more rows for displaying columns.

ReadOnly Property


TcxGridBandRows.Items

TcxGridBandRows          See Also

Provides an indexed access to all rows within the current row collection.

property Items[Index: Integer]: TcxGridBandRow;

Description

The Items property allows you to access a specific row by its index.  The Count property determines the number of rows in the Items collection.  In order to restrict access to visible rows, use the VisibleItems property.

ReadOnly Property


TcxGridBandRows.LastVisible

TcxGridBandRows          See Also

Gets the last visible row in the current row collection.

property LastVisible: TcxGridBandRow;

Description

The LastVisible property specifies the last visible row in a band.  Visible rows can be accessed via the VisibleItems collection.

ReadOnly Property


TcxGridBandRows.VisibleCount

TcxGridBandRows          See Also

Returns the number of visible rows in the current row collection.

property VisibleCount: Integer;

Description

Use VisibleCount to determine the number of visible rows in the current TcxGridBandRows collection.  To access a visible row by its visible index use the VisibleItems property.

ReadOnly Property


TcxGridBandRows.VisibleItems

TcxGridBandRows          See Also

Specifies a collection of visible rows displayed in the current band.

property VisibleItems[Index: Integer]: TcxGridBandRow;

Description

The VisibleItems property provides an indexed access to visible rows.  A row is visible if it is assigned any column with the Visible property set to True.  The number of visible rows is defined by the VisibleCount property.

ReadOnly Property


TcxGridBandRows.Create

TcxGridBandRows

Creates an instance of the TcxGridBandRows class for a specified band.

constructor Create(ABand: TcxGridBand); virtual;

Description

The ABand parameter defines the band in a banded table view for which to create a row collection.  The constructor creates an empty row collection and initializes its properties to default values.


TcxGridBandRows.Destroy

TcxGridBandRows

Destroys the current instance of the TcxGridBandRows class.

destructor Destroy; override;

Description

The destructor destroys a TcxGridBandRows instance and frees all memory allocated by the object.


TcxGridBandRows.GetLineIndex

TcxGridBandRows          See Also

Returns the number of lines preceding a specific row.

function GetLineIndex(ARowIndex: Integer): Integer;

Description

The GetLineIndex property returns the number of lines preceding a row referenced by the ARowIndex parameter.  This parameter defines a row index in the VisibleItems collection.  Every row can occupy several lines as defined by the TcxGridBandRow.LineCount property.  To return the number of lines preceding a specific row use TcxGridBandRow.LineOffset.


TcxGridBandRows.GetRowIndex

TcxGridBandRows          See Also

Returns the index of a visible row containing the specified line.

function GetRowIndex(ALineIndex: Integer): Integer;

Description

The GetRowIndex method returns the row index which contains the line specified by the ALineIndex parameter.  You can make a row occupy several lines by changing the LineCount property of a column assigned to this row.

If the ALineIndex parameter addresses an invalid line, -1 is returned.


TcxGridBandedTableView
TcxGridBandedTableView Object

Hierarchy          Properties          Methods          Events          See Also

Represents a view that groups columns into bands.

Unit

cxGridBandedTableView

TcxGridBandedTableView = class(TcxGridTableView);

Description

The TcxGridBandedTableView object represents a view which can group columns into bands and also combine bands in a similar way.  Bands can be used to show columns on different lines thus compacting a view horizontally so that end users can view a large number of columns without having to use the horizontal scrollbar.  Bands can be moved within a view and resized by the end user.  This is accomplished via clicking and dragging the band header or the band side.

A banded view must contain at least one band otherwise it cannot display data.  After the one or more bands are created and named via the Band.Caption property columns can be assigned to them.

Each column within a banded table view is an instance of the TcxGridBandedColumn class.  This class provides several properties to a user.  The main property of a TcxGridBandedColumn is the GridBandedColumn.Position property.  It defines the column position within the view bands.

To associate a column with a specific band use the Position.BandIndex property. This determines which band the column will appear in.

The column position within a single band is determined via the Position.ColIndex and Position.RowIndex properties.  If a specific band contains several columns, then set different values to the Position.RowIndex property of those columns to arrange them into several rows.

Columns within bands can have different heights.  The column height within a band is specified via the Position.LineCount property which is the number of rows (lines) this column occupies.

When you have plenty of bands you can group them into larger bands.  In order to assign a band to another band (also called assigning a parent band or nesting), set the parent band’s index to the child band’s Position.BandIndex property.  After that the child band as well as any columns associated with it will be displayed within the parent band.

The band within a banded table view is an instance of the TcxGridBand class.  This class provides several properties to a user for customizing the band’s behavior, position within a View and appearance aspects via the Options, Position and Styles properties, respectively.

The band’s horizontal position within a view or parent band is determined via the Position.ColIndex property.  The band’s vertical position can be adjusted via band nesting only.

The band's height within a view is automatically adjusted according to the cumulative height of the bands which are located on the same view’s band hierarchy level.

The BandedTableView has several option sets which manage the various aspects of the view behavior and appearance.  These sets include:

•	OptionsBehavior which contains that determine how the BandedTableView will react to end-user actions;

•	OptionsCustomize which contains settings that control the availability of the customization options to end-users at runtime;

•	OptionsData which contains settings that determine the functionality of the data-aware BandedTableView;

•	OptionsSelection which contains settings that are to do with row and cell selections within the BandedTableView;

•	OptionsView which contains settings that control the appearance of the BandedTableView;

•	Filtering which controls the filter settings for the BandedTableView;

•	FilterBox which contains appearance options of the filter box within the BandedTableView.

•	Preview which contains settings that determine the appearance of the preview section within the BandedTableView.

The Styles property determines the appearance aspects of the elements within the BandedTableView.


TcxGridBandedTableView Hierarchy
Hierarchy

TComponent

     |

TcxControlChildComponent

     |

TcxCustomGridView

     |

TcxCustomGridTableView

     |

TcxGridTableView

     |


Properties for TcxGridBandedTableView
TcxGridBandedTableView Properties

TcxGridBandedTableView          Legend

In TcxGridBandedTableView

BackgroundBitmaps

Bands

Columns

Controller

GroupedColumns

OptionsBehavior

OptionsCustomize

OptionsView

Styles

VisibleColumns

Derived from TcxGridTableView

ColumnCount

Columns

Controller

Filtering

GroupedColumnCount

GroupedColumns

OptionsCustomize

OptionsData

OptionsSelection

OptionsView

Preview

Styles

ViewData

VisibleColumnCount

VisibleColumns

Derived from TcxCustomGridTableView

Control

Controller

DataController

DateTimeHandling

FilterBox

GroupedItemCount

GroupedItems

ItemCount

Items

MasterGridRecord

NavigatorButtons

OptionsCustomize

OptionsData

OptionsSelection

OptionsView

Styles

SortedItemCount

SortedItems

VisibleItemCount

VisibleItems

Derived from TcxCustomGridView

CloneCount

Clones

Controller

DataController

DragMode

Focused

IsControlFocused

IsDetail

IsMaster

IsPattern

Level

MasterGridRecordIndex

MasterGridView

MasterRecordIndex

OptionsSelection

OptionsView

PatternGridView

Site

Styles

ViewData

ViewInfo

Visible

Derived from TcxControlChildComponent

Control

IsDestroying

IsLoading


Methods for TcxGridBandedTableView
TcxGridBandedTableView Methods

TcxGridBandedTableView          Legend

In TcxGridBandedTableView

 CreateColumn

Derived from TcxGridTableView

 CreateColumn

Derived from TcxCustomGridTableView

 ApplyBestFit

 ClearItems

 CopyToClipboard

 CreateItem

 FindItemByID

 FindItemByName

 IndexOfItem

 MakeMasterGridRecordVisible

 RestoreDefaults

Derived from TcxCustomGridView

 BeginUpdate

 CancelUpdate

 EndUpdate

 GetHitTest

 LayoutChanged

 RestoreDefaults

 RestoreFromIniFile

 RestoreFromRegistry

 RestoreFromStream

 SizeChanged

 StoreToIniFile

 StoreToRegistry

 StoreToStream

 ViewChanged

Derived from TcxControlChildComponent

 CreateEx

 Destroy


Events for TcxGridBandedTableView
TcxGridBandedTableView Events

TcxGridBandedTableView          Legend

In TcxGridBandedTableView

 OnBandPosChanged

 OnBandSizeChanged

 OnCustomDrawBandHeader

Derived from TcxGridTableView

 OnColumnHeaderClick

 OnColumnPosChanged

 OnColumnSizeChanged

 OnCustomDrawColumnHeader

 OnCustomDrawFooterCell

 OnCustomDrawIndicatorCell

 OnLeftPosChanged

Derived from TcxCustomGridTableView

 OnCanSelectRecord

 OnCellClick

 OnCustomDrawCell

 OnCustomDrawPartBackground

 OnCustomization

 OnEditChanged

 OnEditing

 OnEditValueChanged

 OnFilterControlDialogShow

 OnFilterCustomization

 OnFilterDialogShow

 OnFocusedItemChanged

 OnFocusedRecordChanged

 OnGetCellHeight

 OnInitEdit

 OnInitEditValue

 OnSelectionChanged

 OnTopRecordIndexChanged

Derived from TcxCustomGridView

 OnDblClick

 OnDragDrop

 OnDragOver

 OnEndDrag

 OnGetStoredProperties

 OnGetStoredPropertyValue

 OnInitStoredObject

 OnMouseDown

 OnMouseEnter

 OnMouseLeave

 OnMouseUp

 OnSetStoredPropertyValue

 OnStartDrag


TcxGridBandedTableView.BackgroundBitmaps

TcxGridBandedTableView

Specifies background bitmaps for visual elements of the view.

property BackgroundBitmaps: TcxGridBandedTableBackgroundBitmaps;

Description

Use the BackgroundBitmaps property to assign background images to the elements of a banded table view.  The TcxGridBandedTableBackgroundBitmaps object represents this property.  The object provides a number of properties, each of which specifies the bitmap for a specific element type.  Please refer to the TcxGridBandedTableBackgroundBitmaps object for details.

Note that you can also assign background images to elements of the view using styles.  Specify the Bitmap property of the style assigned to an element for this purpose.  Styles are assigned via the Styles property of the view.


TcxGridBandedTableView.Bands

TcxGridBandedTableView          See Also

Provides indexed access to the bands within a banded table view.

property Bands: TcxGridBands;

Description

Use the Bands property to view the collection of bands belonging to the current view.  Each band provides access to all its columns via the Band.Columns property.  It also publishes the Band.Options property which contains options controlling band behavior.  The Band.Styles property allows you to define appearance of the band elements.

//Delphi

...

with btvItems.Bands.Add do

begin

  Caption := 'Additional Info';

  Index := 1;

  Width := 200;

  Options.Moving := False;

  btvItemsDESCRIPTION.Position.BandIndex := Index;

  btvItemsRESOLUTION.Position.BandIndex := Index;

  btvItemsRESOLUTION.Position.RowIndex := 1;

  Columns[0].SortOrder := TcxDataSortOrder(soAscending);

end;

...


TcxGridBandedTableView.Columns

TcxGridBandedTableView          See Also

Provides indexed access to all columns within a banded table view.

property Columns[Index: Integer]: TcxGridBandedColumn;

Description

Use the Columns property to view a collection of the views columns.  All visible Columns within a banded view must belong to a band.  To associate a column with a specific band assign the index of that band to the BandedColumn.Position.BandIndex property of that column.

The BandedColumn.Position.ColIndex property specifies the column’s position within a band (if a band contains several columns).


TcxGridBandedTableView.Controller

TcxGridBandedTableView

Specifies a view controller.

property Controller: TcxGridBandedTableController;

Description

The Controller property provides access to the view’s controller functionality.  TcxGridBandedTableController provides properties and methods specific to a banded table view which enable you to:

-	control editing of a record cell

-	set focus to a specific column and record

-	start/cancel an incremental search

-	access the collection of selected records

-	perform scrolling

-	navigate records and items

-	display/hide the customization form

ReadOnly Property


TcxGridBandedTableView.GroupedColumns

TcxGridBandedTableView          See Also

Provides indexed access to the group columns within a banded table view.

property GroupedColumns[Index: Integer]: TcxGridBandedColumn;

Description

Use the GroupedColumns property to access a collection of grouped columns within the current view.

To group a view by a specific column values set the Column.GroupIndex property of the column to a value greater than –1.

ReadOnly Property


TcxGridBandedTableView.OptionsBehavior

TcxGridBandedTableView          See Also

Contains settings determining how the banded table view responds to end user actions.

property OptionsBehavior: TcxGridBandedTableOptionsBehavior;

Description

Use the OptionsBehavior property to specify the settings which determine how the banded table view responds to end user actions.  These property settings determine whether the cell editors are always active, whether the focus can be moved using the Tab and Enter keys, whether band header and column header hints will be displayed, etc.


TcxGridBandedTableView.OptionsCustomize

TcxGridBandedTableView          See Also

Settings that determine the run-time functionality of a banded table views columns and bands.

property OptionsCustomize: TcxGridBandedTableOptionsCustomize;

Description

Use the OptionsCustomize property to determine the features that can be used by end users at runtime for columns and bands manipulations within the banded table view.  These features include filtering, grouping, sorting, columns resizing and moving.  Some of them affect others (for instance, if the ColumnMoving property value is False, then the grouping feature is also disabled).

Column and band manipulations can be performed programmatically regardless of OptionsCustomize values.


TcxGridBandedTableView.OptionsView

TcxGridBandedTableView          See Also

Settings defining the banded table views appearance.

property OptionsView: TcxGridBandedTableOptionsView;

Description

Use the OptionsView property to set the views appearance.  Among these settings are the fixed band separator color and width, the option determining whether the band headers are displayed within the current view.


TcxGridBandedTableView.Styles

TcxGridBandedTableView          See Also

The set of styles defining the appearance of view elements.

property Styles: TcxGridBandedTableViewStyles;

Description

Use the Styles property to access the set of styles defining the appearance of elements of a view.  This set is expanded for more specialized types of views as the Styles property is redefined by TcxCustomGridView descendants.  In the base class the Styles set includes a style defining the appearance of the current view background.  In this class the styles collection contains the styles of it’s parent class and adds it’s own styles for band headers and the band background.


TcxGridBandedTableView.VisibleColumns

TcxGridBandedTableView          See Also

Indexed access to the visible columns within the banded table view.

property VisibleColumns[Index: Integer]: TcxGridBandedColumn;

Description

Use the VisibleColumns property to gain access to the collection of visible columns within the current view.  Column visibility is determined via the GridBandedColumn.Visible property of the column object.  If this property is set to False for a column, then that column is not visible within the current view.

Note: the order of columns within the VisibleColumns list doesn’t necessarily match the columns’ visible order.  To determine or set a particular column’s position, use the column’s Position.BandIndex, Position.ColIndex and Position.RowIndex properties.

ReadOnly Property


TcxGridBandedTableView.CreateColumn

TcxGridBandedTableView          See Also

Creates a column and adds it to the Columns collection of the current view, returning a pointer to the column created.

function CreateColumn: TcxGridBandedColumn;

Description

Use the CreateColumn method to create an instance of the TcxGridBandedColumn class and add it to the Columns collection of the current view.  After the column is added to the collection it can be associated with a specific band via setting the GridBandedColumn.Position.BandIndex property value.  The columns position within a band is determined via the Position.ColIndex and Position.RowIndex properties.


TcxGridBandedTableView.OnBandPosChanged

TcxGridBandedTableView          See Also

Occurs when an end user changes the visibility or position of a band within the current view.

type

  TcxGridBandEvent = procedure(Sender: TcxGridBandedTableView; ABand: TcxGridBand) of object;

property OnBandPosChanged: TcxGridBandEvent;

Description

The OnBandPosChanged event is fired when an end-user moves the band or changes its visibility within the current view using the Quick Band Customization.  The Sender parameter specifies the view in which a band’s position has been changed.  The ABand parameter identifies the band being moved or shown/hidden.


TcxGridBandedTableView.OnBandSizeChanged

TcxGridBandedTableView          See Also

Occurs when a user changes band width.

type

  TcxGridBandEvent = procedure(Sender: TcxGridBandedTableView; ABand: TcxGridBand) of object;

property OnBandSizeChanged: TcxGridBandEvent;

Description

Write an OnBandSizeChanged event handler to perform specific actions when a user changes the width of a band.  The View parameter specifies the view whose band is being resized.  The ABand parameter identifies the band whose width is changed.


TcxGridBandedTableView.OnCustomDrawBandHeader

TcxGridBandedTableView          See Also

Occurs when a band header within a banded table view needs to be painted.

type

    TcxGridBandCustomDrawHeaderEvent = procedure(Sender: TcxGridBandedTableView; ACanvas: TcxCanvas; AViewInfo: TcxGridBandHeaderViewInfo; var ADone: Boolean) of object;

property OnCustomDrawBandHeader: TcxGridBandCustomDrawHeaderEvent;

Description

The OnCustomDrawBandHeader occurs every time a band header needs to be painted. As with other custom draw events it provides a canvas for the grid control (ACanvas parameter), view info to get the bounding rectangle of the painted element (AViewInfo parameter and its Bounds property). Sender is usually the element that caused the repaint. The ADone parameter is initially False you should set it to True to tell the grid that you have chosen to custom draw this item.


TcxGridCardViewOptionsBehavior
TcxGridCardViewOptionsBehavior Object

Hierarchy          Properties          See Also

Contains settings determining how the card view responds to user actions via the mouse and keyboard.

Unit

cxGridCardView

TcxGridCardViewOptionsBehavior = class(TcxCustomGridTableOptionsBehavior);

Description

The TcxGridCardViewOptionsBehavior object contains settings determining the grid table view response to the user actions.  This class is inherited from the TcxCustomGridTableOptionsBehavior class and publishes properties but does not implement any new functionality.   These properties determine whether the cell editors are always active, whether the focus can be moved using the Tab and Enter keys, etc.

Use the OptionsBehavior property to access this set of options.


TcxGridCardViewOptionsBehavior Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |

TcxCustomGridTableOptionsBehavior

     |


Properties for TcxGridCardViewOptionsBehavior
TcxGridCardViewOptionsBehavior Properties

TcxGridCardViewOptionsBehavior          Legend

In TcxGridCardViewOptionsBehavior

ExpandRowOnDblClick

RowCaptionHints

Derived from TcxCustomGridTableOptionsBehavior

AlwaysShowEditor

BestFitMaxRecordCount

CellHints

DragFocusing

DragHighlighting

DragOpening

DragScrolling

FocusCellOnCycle

FocusCellOnTab

FocusFirstCellOnNewRecord

GoToNextCellOnEnter

ImmediateEditor

IncSearch

IncSearchItem

NavigatorHints

PullFocusing

Derived from TcxCustomGridOptions

GridView


TcxGridCardViewOptionsBehavior.ExpandRowOnDblClick

TcxGridCardViewOptionsBehavior

Specifies whether a category row can be expanded or collapsed when its caption is double-clicked.

property ExpandRowOnDblClick: Boolean;

Description

A grid provides two ways of expanding a category row – by using a category row’s expand button or by double-clicking on the row’s caption.

Set the ExpandRowOnDblClick property to True to allow a category row to be expanded or collapsed when double clicked.

The default value of the ExpandRowOnDblClick property is True.


TcxGridCardViewOptionsBehavior.RowCaptionHints

TcxGridCardViewOptionsBehavior

Indicates whether a hint box is displayed when hovering over a row containing a clipped caption.

property RowCaptionHints: Boolean;

Description

Set the RowCaptionHints property to True to display a hint box when moving the mouse pointer over partially visible rows or rows which have their captions clipped by their bounds.  The hint box will contain the caption of the underlying row.

The following image shows a card view with several rows.  The row hint is displayed for the ‘Email’ row:

The default value of the RowCaptionHints property is True.


TcxGridCardViewOptionsCustomize
TcxGridCardViewOptionsCustomize Object

Hierarchy          Properties          Methods

Contains settings which let an end user customize a view via runtime modifications of the card view and the view’s rows.

Unit

cxGridCardView

TcxGridCardViewOptionsCustomize = class(TcxCustomGridTableOptionsCustomize)

Description

An end user can customize a view at runtime by resizing and expanding the cards, filtering rows and moving rows.  All these actions can also be performed in code.  The properties of the TcxGridCardViewOptionsCustomize object control the availability of the card and row features to end users.

Use the OptionsCustomize property to access this options set.


TcxGridCardViewOptionsCustomize Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |

TcxCustomGridTableOptionsCustomize

     |


Properties for TcxGridCardViewOptionsCustomize
TcxGridCardViewOptionsCustomize Properties

TcxGridCardViewOptionsCustomize          Legend

In TcxGridCardViewOptionsCustomize

CardExpanding

CardSizing

GridView

LayeredRows

RowExpanding

RowFiltering

RowHiding

RowMoving

Derived from TcxCustomGridTableOptionsCustomize

ItemFiltering

ItemGrouping

ItemHiding

ItemMoving

ItemSorting

Derived from TcxCustomGridOptions

GridView


Methods for TcxGridCardViewOptionsCustomize
TcxGridCardViewOptionsCustomize Methods

TcxGridCardViewOptionsCustomize          Legend

Derived from TcxCustomGridTableOptionsCustomize

SupportsItemsQuickCustomizationReordering


TcxGridCardViewOptionsCustomize.CardExpanding

TcxGridCardViewOptionsCustomize          See Also

Specifies whether cards can be collapsed and expanded.

property CardExpanding: Boolean;

Description

If the CardExpanding property value is True, you can expand and collapse cards via code using the records’ Expand and Collapse methods.  If you need to expand or collapse all cards within the view at once, use the view’s ViewData.Expand and ViewData.Collapse methods.  A particular card’s expanded state can be obtained using the corresponding record’s Expanded property.

End users can also expand and collapse cards.  To allow this, the view displays card expand buttons within cards’ caption rows.  The expand button’s horizontal alignment is specified using the card view’s OptionsView.CardExpandButtonAlignment property.

Note: card expand buttons are displayed within the first created caption row.  To create a caption row, you need to set the desired row’s Kind property to rkCaption.

The image below shows a card view that allows end users to expand and collapse cards.

The default value of the CardExpanding property is False.


TcxGridCardViewOptionsCustomize.CardSizing

TcxGridCardViewOptionsCustomize          See Also

Specifies whether end users can resize cards at run time.

property CardSizing: Boolean;

Description

When the CardSizing property is set to True end users can resize cards at run time by clicking and dragging the card separator to adjust card widths.  Otherwise, cards can be resized only programmatically by setting the OptionsView.CardWidth property.

The default value of the CardSizing property is True.


TcxGridCardViewOptionsCustomize.GridView

TcxGridCardViewOptionsCustomize

Represents a card view to which the current settings are applied.

property GridView: TcxGridCardView;

Description

Use the GridView property to access the card view instance.

ReadOnly Property


TcxGridCardViewOptionsCustomize.LayeredRows

TcxGridCardViewOptionsCustomize          See Also

Specifies whether an end-user can perform layering on card rows.

property LayeredRows: Boolean;

Description

Set the LayeredRows property to True, to allow end-users to create layers by moving items into appropriate spaces of a card:

Note: the view’s RowLayout property is set to rlVertical.

The default value of the LayeredRows property is False.


TcxGridCardViewOptionsCustomize.RowExpanding

TcxGridCardViewOptionsCustomize

Specifies whether expand buttons will be drawn in category rows.

property RowExpanding: Boolean;

Description

Set the RowExpanding property to True, to make expand buttons visible in all the category rows that are currently available in the card view.

Note: the Options.Expanding property has priority over the RowExpanding property.

The default value of the RowExpanding property is True.


TcxGridCardViewOptionsCustomize.RowFiltering

TcxGridCardViewOptionsCustomize

Specifies whether card rows can display filter dropdown buttons.

property RowFiltering: Boolean;

Description

If the RowFiltering property value is True, card rows display filter dropdown buttons provided that their Options.Filtering option is enabled.  Otherwise, filter dropdown buttons are not displayed within card rows regardless of other settings.

The default value of the RowFiltering property is True.


TcxGridCardViewOptionsCustomize.RowHiding

TcxGridCardViewOptionsCustomize          See Also

Determines the manner in which the card view’s rows can be hidden from a view.

property RowHiding: Boolean;

Description

Use the RowHiding property to determine the manner in which the card view’s rows can be hidden in a view.  When this property is set to False, rows can only be hidden by dragging them to the active customization form.  When RowHiding is set to True, rows can also be hidden by dragging their captions, even if the customization form is not displayed.  If a row is displayed within the customization form, it is not visible within the view (i.e. the Visible property value of that row is False).  A row can also be made invisible within the customization form.  Set the Row.VisibleForCustomization property value to True and then a row can only be returned to a view programmatically.

The default value of the RowHiding property is False.


TcxGridCardViewOptionsCustomize.RowMoving

TcxGridCardViewOptionsCustomize          See Also

Determines whether the card view’s rows can be moved by dragging their captions.

property RowMoving: Boolean;

Description

Set the RowMoving property to True to allow rows to be moved by dragging their captions.

The default value of the RowMoving property is False.


TcxGridCardViewOptionsData
TcxGridCardViewOptionsData Object

Hierarchy          Properties          See Also

Contains settings determining the functionality of a data-aware card view.

Unit

cxGridCardView

TcxGridCardViewOptionsData = class(TcxCustomGridTableOptionsData);

Description

The properties of the TcxGridCardViewOptionsData object are used to determine which actions can be performed for a data set which provides records for a card view.  This class is inherited from the TcxCustomGridTableOptionsData class and publishes properties but does not implement any new functionality.  These actions include inserting, appending, editing and deleting records.  The data options also indicate whether confirmation is requested before record deletion and whether empty records can be posted into a data set.

Use the OptionsData property to access this set of options.


TcxGridCardViewOptionsData Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |

TcxCustomGridTableOptionsData

     |


Properties for TcxGridCardViewOptionsData
TcxGridCardViewOptionsData Properties

TcxGridCardViewOptionsData          Legend

Derived from TcxCustomGridTableOptionsData

Appending

CancelOnExit

Deleting

DeletingConfirmation

Editing

GridView

Inserting

Derived from TcxCustomGridOptions

GridView


TcxGridCardViewOptionsSelection
TcxGridCardViewOptionsSelection Object

Hierarchy          Properties          See Also

Contains settings concerning selections within a card view.

Unit

cxGridCardView

TcxGridCardViewOptionsSelection = class(TcxCustomGridTableOptionsSelection);

Description

The properties of the TcxGridCardViewOptionsSelection object determine the selection options for a card view.  The TcxGridCardViewOptionsSelection class is inherited from the TcxCustomGridTableOptionsSelection class and publishes properties but does not implement any new functionality.  Its properties indicate whether individual cells may be selected, whether a focus rectangle is displayed around the focused row and whether multiple row selection is available etc.


TcxGridCardViewOptionsSelection Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |

TcxCustomGridOptionsSelection

     |

TcxCustomGridTableOptionsSelection

     |


Properties for TcxGridCardViewOptionsSelection
TcxGridCardViewOptionsSelection Properties

TcxGridCardViewOptionsSelection          Legend

In TcxGridCardViewOptionsSelection

CardBorderSelection

Derived from TcxCustomGridTableOptionsSelection

CellSelect

HideFocusRect

HideFocusRectOnExit

HideSelection

InvertSelect

MultiSelect

UnselectFocusedRecordOnExit

Derived from TcxCustomGridOptions

GridView


TcxGridCardViewOptionsSelection.CardBorderSelection

TcxGridCardViewOptionsSelection

Specifies whether a focus rectangle is displayed around the selected card.

property CardBorderSelection: Boolean;

Description

Set the CardBorderSelection property to True to draw a focus rectangle.

The default value of the CardBorderSelection property is True.


TcxGridCardViewOptionsView
TcxGridCardViewOptionsView Object

Hierarchy          Properties          See Also

Contains settings defining the appearance of a card view.

Unit

cxGridCardView

TcxGridCardViewOptionsView = class(TcxCustomGridTableOptionsView);

Description

The properties of the TcxGridCardViewOptionsView object define the appearance of a specific card view.  These properties affect cards, card borders, row caption widths and card separator color & width.  They also determine whether the height of card view rows and their captions is changed as necessary in order to display their text entirely.

Use the OptionsView property to access this set of options.


TcxGridCardViewOptionsView Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |

TcxCustomGridOptionsView

     |

TcxCustomGridTableOptionsView

     |


Properties for TcxGridCardViewOptionsView
TcxGridCardViewOptionsView Properties

TcxGridCardViewOptionsView          Legend

In TcxGridCardViewOptionsView

CaptionSeparator

CaptionWidth

CardAutoWidth

CardBorderWidth

CardExpandButtonAlignment

CardIndent

CardWidth

CategoryIndent

CategoryRowCaptionInRowAlternateCaption

CategorySeparatorWidth

EmptyRows

GridView

LayerSeparatorWidth

RowCaptionAutoHeight

RowCaptionEndEllipsis

SeparatorColor

SeparatorWidth

ShowRowFilterButtons

Derived from TcxCustomGridTableOptionsView

CellAutoHeight

CellEndEllipsis

CellTextMaxLineCount

GridView

ShowEditButtons

Derived from TcxCustomGridOptionsView

ScrollBars

Derived from TcxCustomGridOptions

GridView


Methods for TcxGridCardViewOptionsView
TcxGridCardViewOptionsView Methods

TcxGridCardViewOptionsView          Legend

In TcxGridCardViewOptionsView

 GetSeparatorColor

Derived from TcxCustomGridTableOptionsView

 GetNoDataToDisplayInfoText


TcxGridCardViewOptionsView.CaptionSeparator

TcxGridCardViewOptionsView

Specifies the character displayed at the end of a row caption within the current card view.

property CaptionSeparator: Char;

Description

A card row consists of two elements: caption obtained from the Caption property and field value.  The CaptionSeparator property determines the character appended to row captions.  The default value of CaptionSeparator is ‘:’.

The Styles.RowCaption property allows you to define the style for row captions.

The default value of the CaptionSeparator property is cxGridDefaultCardViewCaptionSeparator.


TcxGridCardViewOptionsView.CaptionWidth

TcxGridCardViewOptionsView          See Also

Specifies the width of card view row captions.

property CaptionWidth: Integer;

Description

Use the CaptionWidth property to specify the width of card view row captions.  If this value is insufficient to display row captions entirely, then text clipping may occur.

The RowCaptionAutoHeight property allows you to control the height of rows automatically.  If it is set to True, a row with a long caption is displayed in several lines and the caption is wrapped.  If RowCaptionAutoHeight is False, the row is displayed in a single line and a long caption may be clipped.

If CaptionWidth is set to 0, then the width is automatically changed to fit row caption texts (the Caption property). This, of course, is dependent on the fonts used to display them.

The default value of the CaptionWidth property is 0.


TcxGridCardViewOptionsView.CardAutoWidth

TcxGridCardViewOptionsView

Specifies whether the client area’s width is a multiple of the card’s width.

property CardAutoWidth: Boolean;

Description

Set the CardAutoWidth property to True to stretch cards so they occupy the entire client area’s width.  The CardWidth property’s value is ignored in this instance.  Otherwise the CardWidth property specifies the card’s width.

The default value of the CardAutoWidth property is False.


TcxGridCardViewOptionsView.CardBorderWidth

TcxGridCardViewOptionsView

Specifies the card border width.

property CardBorderWidth: Integer;

Description

Use the CardBorderWidth property to specify the width of the card border.

The default value of the CardBorderWidth property is specified by the cxGridDefaultCardBorderWidth constant.


TcxGridCardViewOptionsView.CardExpandButtonAlignment

TcxGridCardViewOptionsView          See Also

Specifies the card expand button’s horizontal alignment.

type

  TcxGridCardExpandButtonAlignment = (cebaLeft, cebaRight);

property CardExpandButtonAlignment: TcxGridCardExpandButtonAlignment;

Description

If the card view’s OptionsCustomize.CardExpanding option is enabled and there is at least one caption row defined, caption rows display expand buttons that allow end users to expand and collapse cards.  You can specify whether such buttons are displayed to the left or to the right of the caption row’s text using the CardExpandButtonAlignment property.  The table below lists this property’s possible values.

Value	Meaning
cebaLeft	Card expand buttons are left aligned within caption rows.
cebaRight	Card expand buttons are right aligned within caption rows.

For details on expanding and collapsing cards, see the OptionsCustomize.CardExpanding property description.

The default value of the CardExpandButtonAlignment property is cebaRight.


TcxGridCardViewOptionsView.CardIndent

TcxGridCardViewOptionsView

Specifies the card’s indent in pixels.

property CardIndent: Integer;

Description

Use the CardIndent property to specify the card’s indent across the horizontal and vertical axes.

The default value of the CardIndent property is cxGridCardDefaultIndent.


TcxGridCardViewOptionsView.CardWidth

TcxGridCardViewOptionsView          See Also

Specifies the card width.

property CardWidth: Integer;

Description

Use the CardWidth property to specify the card width.  The CaptionWidth property defines the width of card row captions.  If the width of a row cell or row caption is too small to display all its text, then you can use the CellAutoHeight and RowCaptionAutoHeight options to adjust the height of such rows with large texts and thus wrap the text.

Changing this property value affects the size of all card elements.  If this value is too small, card view rows will not able to display all text in full.  To avoid this, activate the CellAutoHeight and RowCaptionAutoHeight options.

The default value of the CardWidth property is cxGridCardDefaultWidth.


TcxGridCardViewOptionsView.CategoryIndent

TcxGridCardViewOptionsView          See Also

Specifies the size of the category row’s children indentation in pixels.

property CategoryIndent: Integer;

Description

The default value of the CategoryIndent property is cxGridCardDefaultCategoryIndent.


TcxGridCardViewOptionsView.CategoryRowCaptionInRowAlternateCaption

TcxGridCardViewOptionsView          See Also

Specifies whether to add the category row’s caption at the beginning of children’s captions.

property CategoryRowCaptionInRowAlternateCaption: Boolean;

Description

Set the CategoryRowCaptionInRowAlternateCaption property to True to concatenate the category row’s and children’s captions.

Note: In the resulting string, the category row’s and children’s captions are delimited by the dash ‘–’ character.  You can change the default separator by assigning a new character to the cxGridCardViewAlternateCaptionSeparator constant.

The default value of the CategoryRowCaptionInRowAlternateCaption property is False.


TcxGridCardViewOptionsView.CategorySeparatorWidth

TcxGridCardViewOptionsView          See Also

Specifies the width of the category row separator in pixels.

property CategorySeparatorWidth: Integer;

Description

Use the CategorySeparatorWidth property to specify the category row separator’s width.

The default value of the CategorySeparatorWidth property is cxGridCardDefaultCategorySeparatorWidth.


TcxGridCardViewOptionsView.EmptyRows

TcxGridCardViewOptionsView

Specifies whether empty rows should be displayed.

property EmptyRows: Boolean;

Description

Set the EmptyRows property to False to prohibit displaying card rows with null values.  Thus, cards will only display rows that have data.  If the EmptyRows property value is True, each card displays the same set of rows regardless of whether they are empty.


TcxGridCardViewOptionsView.GridView

TcxGridCardViewOptionsView

Represents a card view that the current options are applied to.

property GridView: TcxGridCardView;

Description

Use the GridView property to access the card view instance.

ReadOnly Property


TcxGridCardViewOptionsView.LayerSeparatorWidth

TcxGridCardViewOptionsView          See Also

Specifies the width of a layer separator in pixels.

property LayerSeparatorWidth: Integer;

Description

A layer separator is a bar that visually divides layered card rows in a card:

Use the LayerSeparatorWidth property to specify the layer separator’s width.

The default value of the LayerSeparatorWidth property is cxGridCardDefaultLayerSeparatorWidth.


TcxGridCardViewOptionsView.RowCaptionAutoHeight

TcxGridCardViewOptionsView          See Also

Determines whether the caption height of card view rows is automatically changed in order to entirely display the caption text.

property RowCaptionAutoHeight: Boolean;

Description

Use the RowCaptionAutoHeight property to specify whether the height of card view rows with long captions are automatically changed in order to display their full captions.  The size of a card view row caption is determined by the Caption property value and the font used to display it.

If RowCaptionAutoHeight is True and the row caption is too large to be displayed in a single line, then the caption is wrapped.  The CaptionWidth property specifies the width of a region within which the caption is drawn.

The default value of the RowCaptionAutoHeight property is False.


TcxGridCardViewOptionsView.RowCaptionEndEllipsis

TcxGridCardViewOptionsView          See Also

Specifies whether to display an ellipsis when the row caption is clipped.

property RowCaptionEndEllipsis: Boolean;

Description

The RowCaptionEndEllipsis property determines whether to display the ellipsis when the caption width is too small to display the row caption entirely.  The row caption is specified by the Caption property.

The default value of the RowCaptionEndEllipsis property is False.


TcxGridCardViewOptionsView.SeparatorColor

TcxGridCardViewOptionsView          See Also

Specifies the color of the lines separating card groups.

property SeparatorColor: TColor;

Description

Use the SeparatorColor property to specify the color of the lines separating card groups.  Cards are grouped according to the card view layout.  The card view layout is specified via the GridCardView.LayoutDirection property, which provides vertical and horizontal options.  If the card view layout is horizontal, then the separator lines are vertical, and a vertical layout results in horizontal lines

The default value of the SeparatorColor property is clDefault.


TcxGridCardViewOptionsView.SeparatorWidth

TcxGridCardViewOptionsView          See Also

Specifies the width of the lines separating card groups.

property SeparatorWidth: Integer;

Description

Use the SeparatorWidth property to specify the width of the lines separating card groups.  Cards are grouped according to the card view layout.  The card view layout is specified via the GridCardView.LayoutDirection property, which provides vertical and horizontal options.  If the card view layout is horizontal, then the separator lines are vertical, and a vertical layout results in horizontal lines.

The default value of the SeparatorWidth property is defined by the cxGridDefaultCardViewSeparatorWidth constant.


TcxGridCardViewOptionsView.ShowRowFilterButtons

TcxGridCardViewOptionsView

Specifies the manner use to show row filter dropdown buttons.

property ShowRowFilterButtons: TcxGridShowItemFilterButtons;

Description

The TcxGridShowItemFilterButtons enumeration specifies two ways in which to display filter buttons:

•	sfbAlways – filter buttons are permanently visible in all card view rows;

•	sfbWhenSelected – a filter button is only drawn in the selected row.

Use the ShowRowFilterButtons property to specify the appearance of row filter dropdown buttons.

The default value of the ShowRowFilterButtons property is sfbWhenSelected.


TcxGridCardViewOptionsView.GetSeparatorColor

TcxGridCardViewOptionsView          See Also

Returns the color of the card group’s separator.

function GetSeparatorColor: TColor;

Description

The separator divides card groups in a card view.

Use the GetSeparatorColor method to determine the separator’s color.


TcxGridCardViewDateTimeHandling
TcxGridCardViewDateTimeHandling Object

Hierarchy          Properties          Methods          See Also

Represents a set of options that determine the manner in which card rows that display date/time values are filtered and how their values are displayed when filtering is applied

Unit

cxGridCardView

TcxGridCardViewDateTimeHandling = class(TcxCustomGridTableDateTimeHandling)

Description

This class does not introduce any new functionality.  Refer to the description of the base TcxCustomGridTableDateTimeHandling class for details on available options.

Use a Card View’s DateTimeHandling property to access an instance of the TcxGridCardViewDateTimeHandling class.


TcxGridCardViewDateTimeHandling Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |

TcxCustomGridTableDateTimeHandling

     |

TcxGridCardViewDateTimeHandling


Properties for TcxGridCardViewDateTimeHandling
TcxGridCardViewDateTimeHandling Properties

TcxGridCardViewDateTimeHandling          Legend

Derived from TcxCustomGridTableDateTimeHandling

DateFormat

Filters

GridView

Grouping

HourFormat

IgnoreTimeForFiltering

MonthFormat

UseLongDateFormat

UseShortTimeFormat

YearFormat


Methods for TcxGridCardViewDateTimeHandling
TcxGridCardViewDateTimeHandling Methods

TcxGridCardViewDateTimeHandling          Legend

Derived from TcxCustomGridTableDateTimeHandling

GetDateFormat

GetHourFormat

GetMonthFormat

GetYearFormat


TcxGridCardViewFiltering
TcxGridCardViewFiltering Object

Hierarchy          Properties          Methods          See Also

Provides filtering settings for a card view.

Unit

cxGridCardView

TcxGridCardViewFiltering = class(TcxCustomGridTableFiltering)

Description

TcxGridCardViewFiltering objects are exposed via the Filtering property of card views.  They provide a number of settings specifying the filtering features available to end-users.  Additionally, the TcxGridCardViewFiltering object provides the RunCustomizeDialog method that can be used to invoke filter customization dialogs via code.

To apply filtering to a view via code, use the view’s DataController.Filter property.


TcxGridCardViewFiltering Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |

TcxCustomGridTableFiltering

     |


Properties for TcxGridCardViewFiltering
TcxGridCardViewFiltering Properties

TcxGridCardViewFiltering          Legend

In TcxGridCardViewFiltering

RowFilteredItemsList

RowMRUItemsList

RowMRUItemsListCount

RowPopup

RowPopupDropDownWidth

RowPopupMaxDropDownItemCount

Derived from TcxCustomGridTableFiltering

CustomizeDialog

DropDownWidth

ItemMRUItemsList

ItemMRUItemsListCount

MaxDropDownCount

MRUItemsList

MRUItemsListCount

MRUItemsListDropDownCount

Position

Visible

Derived from TcxCustomGridOptions

GridView


Methods for TcxGridCardViewFiltering
TcxGridCardViewFiltering Methods

TcxGridCardViewFiltering          Legend

Derived from TcxCustomGridTableFiltering

 RunCustomizeDialog


TcxGridCardViewFiltering.RowFilteredItemsList

TcxGridCardViewFiltering

Specifies whether to display a list of all filter items or only filtered items in filter dropdowns.

property RowFilteredItemsList: Boolean;

Description

Set the RowFilteredItemsList property to True to only display filtered items (selected items) in filter dropdowns.

Note: The row’s Options.FilteringFilteredItemsList property specifies the visibility of dropdown items for a specific card row.

The default value of the RowFilteredItemsList property is False.


TcxGridCardViewFiltering.RowMRUItemsList

TcxGridCardViewFiltering          See Also

Specifies whether filter dropdowns for card rows should display the most recently used filter items.

property RowMRUItemsList: Boolean;

Description

If the RowMRUItemsList property’s value is True, filter dropdowns for card rows display the most recently used filter items at the top of the list.  The maximum number of most recently used filter items that can be displayed within the list is specified by the RowMRUItemsListCount property value.

Note:	To disable the most recently used list for a particular card row, set its Options.FilteringMRUItemsList property.

The default value of the RowMRUItemsList property is True.


TcxGridCardViewFiltering.RowMRUItemsListCount

TcxGridCardViewFiltering          See Also

Specifies the maximum number of most recently used filter items that can be displayed within filter dropdowns for card rows.

property RowMRUItemsListCount: Integer;

Description

Filter dropdowns for card rows can display a list of the most recently used filter items (MRU list for short).  Each time after a filter item in the dropdown has been selected it is displayed at the top of the MRU list.  The next time another filter item is selected it is added to the top of the MRU list thus increasing the number of filter items in the list.  This takes place until the number of filter items reaches the RowMRUItemsListCount property’s value.  After this has happened, selecting a filter item results in this item being added to the top of the MRU list and the bottom filter item in the list being deleted.

The RowPopup.MaxDropDownItemCount property’s value specifies the number of filter items that can be displayed simultaneously within filter dropdowns for card rows.

The default value of the RowMRUItemsListCount property is specified by the cxGridFilterDefaultItemMRUItemsListCount constant.


TcxGridCardViewFiltering.RowPopup

TcxGridCardViewFiltering

Represents options for a filter dropdown.

property RowPopup: TcxGridItemFilterPopupOptions;

Description

With these options, you can specify the mode the view is updated in against the filter criteria (see the ApplyMultiSelectChanges property), the size of a filter dropdown – its width and the maximum number of items in the filter dropdown (see the DropDownWidth and MaxDropDownItemCount properties), and whether multiple selection of the filter dropdown’s items is available (see the MultiSelect property).


TcxGridCardViewFiltering.RowPopupDropDownWidth

TcxGridCardViewFiltering

Specifies the width of filter dropdowns for card rows.

property RowPopupDropDownWidth: Integer;

Description

This property is obsolete and used for compatibility purposes.  Use the RowPopup.DropDownWidth property instead.


TcxGridCardViewFiltering.RowPopupMaxDropDownItemCount

TcxGridCardViewFiltering          See Also

Specifies the number of filter items which are displayed within filter dropdowns for card rows simultaneously.

property RowPopupMaxDropDownItemCount: Integer;

Description

This property is obsolete and used for compatibility purposes.  Use the RowPopup.MaxDropDownItemCount property instead.


cxGridCardDefaultCategoryIndent constant
cxGridCardDefaultCategoryIndent global constant

See Also

Specifies the default size of the category row’s children indent in pixels.

Unit

cxGridCardView

cxGridCardDefaultCategoryIndent = 17;

Description

Use the cxGridCardDefaultCategoryIndent constant to specify the required default indent of the category row’s children.


cxGridCardDefaultIndent constant
cxGridCardDefaultIndent global constant

See Also

Specifies the default size of the card spacing in pixels.

Unit

cxGridCardView

cxGridCardDefaultIndent = 7;

Description

Use the cxGridCardDefaultIndent constant to specify the required default spacing of the card.


cxGridCustomPopupMenu Unit Overview
cxGridCustomPopupMenu Unit

Classes

TcxCustomGridPopupMenu

TcxPopupMenuInfo

TcxPopupMenuInfos

Routines

GetHitTypeByHitCode


TcxCustomGridPopupMenu
TcxCustomGridPopupMenu Object

Hierarchy          Properties

Represents a base class for the grid popup menu component.

Unit

cxGridCustomPopupMenu

TcxCustomGridPopupMenu = class(TComponent);

Description

The TcxCustomGridPopupMenu class provides basic functionality for all grid popup menu components.  You should never use it directly but only as an ancestor for your own popup menu components.


TcxCustomGridPopupMenu Hierarchy
Hierarchy

TComponent

     |


Properties for TcxCustomGridPopupMenu
TcxCustomGridPopupMenu Properties

TcxCustomGridPopupMenu          Legend

In TcxCustomGridPopupMenu

Count


TcxCustomGridPopupMenu.Count

TcxCustomGridPopupMenu

Contains the number of custom menus within the current popup menu component.

property Count: Integer;

Description

Read the Count property to get the number of TcxPopupMenuInfos collection members that represent custom menus.

ReadOnly Property


TcxPopupMenuInfo
TcxPopupMenuInfo Object

Hierarchy          Properties          Events

Represents information on the custom popup menu contained in the TcxGridPopupMenu component.

Unit

cxGridCustomPopupMenu

TcxPopupMenuInfo = class(TCollectionItem);

Description

The TcxGridPopupMenu component allows you to create custom popup menus for grid views both at design time and runtime.  At design time you can use the TcxGridPopupMenu.PopupMenus property editor to add a new menu.

and setup them

At runtime, you can add the popup menu using the TcxGridPopupMenu.RegisterPopupMenu method.

First, you should create an OnPopup event handler.

//Delphi

procedure TForm1.cxGridPopupMenu1Proc(ASenderMenu: TComponent;

  AHitTest: TcxCustomGridHitTest; X, Y: Integer);

begin

  PopupMenu1.Popup(X, Y);

end;

//C++ Builder

void __fastcall TForm1::cxGridPopupMenu1Proc(TComponent *ASenderMenu, TcxCustomGridHitTest *AHitTest, int X, int Y) {

  PopupMenu1->Popup(X, Y);

}

The following code assumes that you are adding the standard VCL popup menu (TPopupMenu).  Keep in mind that the popup menu will not appear as expected unless you add the following code into your TcxPopupMenuInfo.OnPopup event handler.

//Delphi

  PopupMenu1.Popup(X, Y);

//C++ Builder

  PopupMenu1->Popup(X, Y);

Now you are ready to add a custom popup menu to the collection.  The code below adds a new TcxPopupMenuInfo class instance to the TcxPopupMenuInfos collection and sets its properties to the values specified by the TcxGridPopupMenu.RegisterPopupMenu method parameters.

//Delphi

cxGidPopupMenu1.RegisterPopupMenu(PopupMenu1, [gvhtCell], cxGridPopupMenu1Proc, cxGrid1DBTableView1);

//C++ Builder

cxGidPopupMenu1->RegisterPopupMenu(&PopupMenu1, [gvhtCell], &cxGridPopupMenu1Proc, &cxGrid1DBTableView1);

Each menu info you add to the TcxGridPopupMenu component is a TcxPopupMenuInfo class instance.  All menus are contained in the TcxPopupMenuInfos which can be accessed via the TcxGridPopupMenu.PopupMenus property.

The TcxPopupMenuInfo class provides all necessary properties for proper popup menu display.  This includes:

•	GridView - specifies the grid view to associate with the popup menu.

•	HitTypes - specifies the grid view elements to which the popup menu can be applied.

•	OnPopup - specifies the popup event. The menu will not appear unless you properly handle this event.


TcxPopupMenuInfo Hierarchy
Hierarchy

TCollectionItem

     |


Properties for TcxPopupMenuInfo
TcxPopupMenuInfo Properties

TcxPopupMenuInfo          Legend

In TcxPopupMenuInfo

GridView

HitTypes

Index

PopupMenu


Events for TcxPopupMenuInfo
TcxPopupMenuInfo Events

TcxPopupMenuInfo          Legend

In TcxPopupMenuInfo

 OnPopup


TcxPopupMenuInfo.GridView

TcxPopupMenuInfo

Specifies the owner grid view for the popup menu.

property GridView: TcxCustomGridView;

Description

The GridView property specifies the grid view whose elements can be used for popup menu activation.  In order to setup the appropriate elements, use the HitTypes property.


TcxPopupMenuInfo.HitTypes

TcxPopupMenuInfo

Determines the grid view elements that can display a corresponding popup menu.

property HitTypes: TcxGridViewHitTypes;

Description

This property represents a set of TcxGridViewHitType values.  Each value has a corresponding grid element.  If a value is included into the HitTypes set, the corresponding grid element responds to the right-click by displaying the popup menu specified by the PopupMenu property.


TcxPopupMenuInfo.Index

TcxPopupMenuInfo

Indicates the position of the menu info in the collection.

property Index: Integer;

Description

The Index property represents a zero-based index of the menu info within the TcxPopupMenuInfos collection.  Never use this property directly.


TcxPopupMenuInfo.PopupMenu

TcxPopupMenuInfo

Specifies the popup menu that is associated with the popup menu info.

property PopupMenu: TComponent;

Description

The PopupMenu property specifies the menu that will be displayed based upon the conditions determined by the current menu info.  The menu info properties that set these conditions are:

•	GridView

•	HitTypes

First determines the grid view to which to associate the popup menu then determines the grid view elements that can display the popup menu.


TcxPopupMenuInfo.OnPopup

TcxPopupMenuInfo

Occurs when a user right-clicks the grid view element associated with the popup menu.

type

  TcxGridOnPopupProc = procedure(ASenderMenu: TComponent; AHitTest: TcxCustomGridHitTest; X, Y: Integer) of object;

property OnPopup: TcxGridOnPopupProc;

Description

The OnPopup event occurs every time the grid view element associated with the popup menu info is right-clicked.  To associate the grid view with the popup menu info, you should include the corresponding element into the value of the HitTypes property. Keep in mind that the menu added to the TcxPopupMenuInfos collection will not appear on a right-click until you add the following code into the OnPopup event handler:

//Delphi

procedure TForm1.cxGridPopupMenu1PopupMenus0Popup(ASenderMenu: TComponent;

  AHitTest: TcxCustomGridHitTest; X, Y: Integer);

begin

  //...

  PopupMenu1.Popup(X, Y);

  //...

end;

//C++ Builder

void fastcall TForm1::cxGridPopupMenu1PopupMenus0Popup(TComponent *ASenderMenu,

  TcxCustomGridHitTest *AHitTest, int X, int Y) {

  //...

  PopupMenu1->Popup(X, Y);

  //...

}

The code listed above assumes that you have an application with a TcxGridPopupMenu component named cxGridPopupMenu1 and the TPopupMenu component named PopupMenu1.

To obtain the popup menu of the menu info use the ASenderMenu parameter.  The AHitTest parameter indicates the right-clicked grid element.


TcxPopupMenuInfos
TcxPopupMenuInfos Object

Hierarchy          Properties          Methods

The TcxPopupMenuInfos collection represents a container for TcxPopupMenuInfo objects.

Unit

cxGridCustomPopupMenu

TcxPopupMenuInfos = class(TCollection);

Description

Each TcxPopupMenuInfos class instance holds a collection of TcxPopupMenuInfo objects in a popup menu component (TcxGridPopupMenu). This class enables you to manipulate menu infos both at design time and runtime.

Use the collection editor of the TcxGridPopupMenu.PopupMenus property to add and delete collection items at design time.

Call the TcxGridPopupMenu.RegisterPopupMenu and TcxGridPopupMenu.UnregisterPopupMenu methods to do the same at runtime.

To setup menu infos within the collection at design time, use the collection editor again.

At runtime you can access menu infos via the TcxGridPopupMenu.PopupMenus property.


TcxPopupMenuInfos Hierarchy
Hierarchy

TCollection

     |


Properties for TcxPopupMenuInfos
TcxPopupMenuInfos Properties

TcxPopupMenuInfos          Legend

In TcxPopupMenuInfos

Items


Methods for TcxPopupMenuInfos
TcxPopupMenuInfos Methods

TcxPopupMenuInfos          Legend

In TcxPopupMenuInfos

 Create

 GetSameMenuCount


TcxPopupMenuInfos.Items

TcxPopupMenuInfos

Lists the menus infos in the collection.

property Items[AIndex: Integer]: TcxPopupMenuInfo;

Description

Use the Items property to access individual menus infos.  The value of the Index parameter corresponds to the Index property of the TcxPopupMenuInfo class. It represents the index of the menu info in the collection.

The Items property is the default property of the TcxPopupMenuInfos collection.  This means that the property name, Items, can be omitted when referring to menus infos of the TcxPopupMenuInfos collection. Thus, the following code:

//Delphi

  cxGridPopupMenu1.PopupMenus.Items[0];

//C++ Builder

  cxGridPopupMenu1->PopupMenus->Items[0];

can also be written as

//Delphi

  cxGridPopupMenu1.PopupMenus[0];

//C++ Builder

  cxGridPopupMenu1->PopupMenus[0];


TcxPopupMenuInfos.Create

TcxPopupMenuInfos

Creates and initializes a TcxPopupMenuInfos object.

constructor Create(AOwner: TComponent); virtual;

Description

An application should not call this method directly.  Instead, objects that use the TcxPopupMenuInfos collection instantiate the collection as part of their initialization. An example of such an object is the TcxGridPopupMenu component and its PopupMenus property.


TcxPopupMenuInfos.GetSameMenuCount

TcxPopupMenuInfos

function GetSameMenuCount(const AMenu: TComponent): Integer;

Description

Returns a number that indicates how many times the popup menu is registered.


TcxGridViewHitType
TcxGridViewHitType type

Provides hit test indicators for each grid view element wherein a grid popup menu can appear.

Unit

cxGridCustomPopupMenu

TcxGridViewHitType = (gvhtNone, gvhtRecord, gvhtCell, gvhtExpandButton, gvhtGroupByBox, gvhtColumnHeader, gvhtFooter, gvhtFooterCell, gvhtGroupFooter, gvhtGroupFooterCell, gvhtRowIndicator, gvhtRowLevelIndent);

Description

The TcxGridViewHitType enumeration contains all available grid view elements identifiers:

Value	Description
gvhtNone	Indicates that the clicked area is not a grid view element.
gvhtRecord	Specifies the grid view record.
gvhtCell	Specifies the grid view cell.
gvhtExpandButton	Specifies the grid view expand button.
gvhtGroupByBox	Specifies the group by box.
gvhtColumnHeader	Specifies the column header.
gvhtFooter	Specifies the grid view footer.
gvhtFooterCell	Specifies the grid view footer cell.
gvhtGroupFooter	Specifies the grid view group footer.
gvhtGroupFooterCell	Specifies the grid view group footer cell.
gvhtRowIndicator	Specifies the grid view row indicator.
gvhtRowLevelIndent	Specifies the grid view level indent.


TcxGridViewHitTypes
TcxGridViewHitTypes type

Specifies a set of grid view element indicators.

Unit

cxGridCustomPopupMenu

TcxGridViewHitTypes = set of TcxGridViewHitType;

Description

The TcxGridViewHitTypes type represents a set of grid view element indicators determining the grid view elements that can display a popup menu. See the TcxPopupMenuInfo.HitTypes property for details.


GetHitTypeByHitCode Function

Converts the grid hit test code to the grid element identifier.

Unit

cxGridCustomPopupMenu

Declaration

function GetHitTypeByHitCode(AHitCode: Integer): TcxGridViewHitType;

Description

The GetHitTypeByHitCode function converts the grid hit test code to the grid view element identifier. Commonly this identifier is used to determine the grid view element that can display popup menus. See the TcxPopupMenuInfo.HitTypes and TcxGridPopupMenu.HitType properties for more information.

The following example demonstrates how to use the GetHitTypeByHitCode function.  It identifies the grid view element that was right-clicked and which fired the TcxPopupMenuInfo.OnPopup event:

//Delphi

procedure TForm1.cxGridPopupMenu1PopupMenus0Popup(ASenderMenu: TComponent;

  AHitTest: TcxCustomGridHitTest; X, Y: Integer);

var

  AHitType: TcxGridViewHitType;

begin

  AHitType := GetHitTypeByHitCode(AHitTest.HitTestCode);

  if AHitType = gvhtCell then

  begin

    if Odd((AHitTest as TcxGridRecordCellHitTest).GridRecord.Index) then

      PopupMenu1.Popup(X, Y)

    else

      PopupMenu2.Popup(X, Y)

  end;

end;

//C++ Builder

void __fastcall TForm1::cxGridPopupMenu1PopupMenus0Popup(TComponent *ASenderMenu, TcxCustomGridHitTest *AHitTest, int X, int Y) {

  TcxGridViewHitType AHitType = GetHitTypeByHitCode(AHitTest->HitTestCode);

  if (AHitType == gvhtCell) {

    if Odd(((TcxGridRecordCellHitTest *)AHitTest)->GridRecord->Index) {

      PopupMenu1->Popup(X, Y)

    } else {

      PopupMenu2->Popup(X, Y)

    }

  }

}

The code above assumes that you have an application with a TcxGridPopupMenu component named cxGridPopupMenu1 and two TPopupMenu components named PopupMenu1 and PopupMenu2 correspondingly.


TcxCustomGridTableOptionsBehavior
TcxCustomGridTableOptionsBehavior Object

Hierarchy          Properties          See Also

Contains settings determining the grid view’s response to user actions.

Unit

cxGridCustomTableView

TcxCustomGridTableOptionsBehavior = class(TcxCustomGridOptionsBehavior);

Description

The TcxCustomGridTableOptionsBehavior object contains settings determining the grid view’s response to user actions via the mouse or keyboard.  These options determine whether the cell editors are always active and whether focus can be moved using the Tab and Enter keys, etc.

These options also specify the type of synchronization which is used to keep all the created "clone" views’ settings synchronized with their "pattern" view’s settings.

Use the view’s OptionsBehavior property to access this set of options.


TcxCustomGridTableOptionsBehavior Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |

TcxCustomGridOptionsBehavior

     |


Properties for TcxCustomGridTableOptionsBehavior
TcxCustomGridTableOptionsBehavior Properties

TcxCustomGridTableOptionsBehavior          Legend

In TcxCustomGridTableOptionsBehavior

AlwaysShowEditor

BestFitMaxRecordCount

CellHints

CopyCaptionsToClipboard

DragDropText

DragFocusing

DragHighlighting

DragOpening

DragScrolling

FocusCellOnCycle

FocusCellOnTab

FocusFirstCellOnNewRecord

GoToNextCellOnEnter

ImmediateEditor

IncSearch

IncSearchItem

NavigatorHints

PullFocusing

Derived from TcxCustomGridOptionsBehavior

PostponedSynchronization

Derived from TcxCustomGridOptions

GridView


TcxCustomGridTableOptionsBehavior.AlwaysShowEditor

TcxCustomGridTableOptionsBehavior          See Also

Determines whether the cell editors are always active.

property AlwaysShowEditor: Boolean;

Description

Use the AlwaysShowEditor property to make the cell editors always active.  This means that a user does not have to press the Enter or F2 key to enable editing for a cell.  This option is not in effect if editing is disabled within a view or if the OptionsSelection.CellSelect option is not active.

The default value of the AlwaysShowEditor property is False.


TcxCustomGridTableOptionsBehavior.BestFitMaxRecordCount

TcxCustomGridTableOptionsBehavior          See Also

Specifies the maximum number of records processed to calculate the best width for columns when calling ApplyBestFit.

property BestFitMaxRecordCount: Integer;

Description

Use the BestFitMaxRecordCount property to limit the number of records used to calculate the best width for columns when calling the ApplyBestFit method.

The ApplyBestFit method calculates the width of columns so that their contents are fully displayed within grid cells.

The default value (0) of the BestFitMaxRecordCount property indicates that all records are used to determine the best width.  If the view displays a large amount of records, this operation can require much time.  In order to speed up performance when the ApplyBestFit method is called, assign the required number of records to process to the BestFitMaxRecordCount property.  In this case, the view processes the number of records determined by BestFitMaxRecordCount starting from the top visible record.

To make a view iterate only currently visible records, set BestFitMaxRecordCount to the value returned by the view’s ViewInfo.VisibleRecordCount property.

The default value of the BestFitMaxRecordCount property is 0.


TcxCustomGridTableOptionsBehavior.CellHints

TcxCustomGridTableOptionsBehavior          See Also

Indicates whether a hint box is displayed when hovering over a cell containing clipped text.

property CellHints: Boolean;

Description

Set the CellHints property to True to display a hint box when moving the mouse pointer over cells with text clipped by cell bounds.  The hint box will contain the contents of the underlying cell.

The following image shows two cards.  A cell hint is displayed for the second one:

The default value of the CellHints property is False.


TcxCustomGridTableOptionsBehavior.CopyCaptionsToClipboard

TcxCustomGridTableOptionsBehavior          See Also

Indicates whether item (column or row) captions should be included in the resulting text which is copied to the clipboard.

property CopyCaptionsToClipboard: Boolean;

Description

Set the CopyCaptionsToClipboard property to True to add item (column or row) captions to the resulting text which is copied to the clipboard.  Only visible items’ captions are copied.  In the resulting text item captions are positioned at the first line and are separated from records by the line break character (#13#10).  The Tab character is used to separate items within this line.

The default value of the CopyCaptionsToClipboard property is True.


TcxCustomGridTableOptionsBehavior.DragDropText

TcxCustomGridTableOptionsBehavior          See Also

Specifies whether the text is displayed adjacent to the mouse pointer when a drag operation is performed.

property DragDropText: Boolean;

Description

Set the DragDropText property to True to display the text adjacent to the mouse pointer during a drag operation.  By default, the displayed text is the display value of the currently focused table item.  When this property is set to True, the view’s OnGetDragDropText event occurs when the drag operation is started.  Using this event you can easily customize the text that will be displayed.

The default value of the DragDropText property is False.


TcxCustomGridTableOptionsBehavior.DragFocusing

TcxCustomGridTableOptionsBehavior          See Also

Specifies the manner in which the target row is focused in a drag-and-drop operation.

type TcxGridDragFocusing = (dfNone, dfDragOver, dfDragDrop);

property DragFocusing: TcxGridDragFocusing;

Description

By default, the DragFocusing property is set to dfNone and this indicates that focus is not moved when dragging/dropping over the current view.

Set DragFocusing to dfDragOver to automatically focus the record under the cursor when dragging an object over the current target view.  Set the DragFocusing property to dfDragDrop to restrict moving focus to the record under the cursor when dropping an object.  When a focused record is changed, the view’s OnFocusedRecordChanged event occurs.

The OnDragOver and OnDragDrop events are fired when you drag and drop an object over the current view.

The default value of the DragFocusing property is dfNone.


TcxCustomGridTableOptionsBehavior.DragHighlighting

TcxCustomGridTableOptionsBehavior          See Also

Indicates whether the target record is highlighted when dragging an object over the current view.

property DragHighlighting: Boolean;

Description

The DragHighlighting property enables/disables target record highlighting in a drag-and-drop operation.  Set DragHighlighting to True to highlight the record under the cursor when dragging an object over the current view.

You can change the style attributes of highlighted records via the Styles.Selection property.

Use the DragFocusing property to enable record focusing while dragging.

The default value of the DragHighlighting property is True.


TcxCustomGridTableOptionsBehavior.DragOpening

TcxCustomGridTableOptionsBehavior          See Also

Specifies whether group and master rows and detail level tabs are expanded during drag-and-drop.

property DragOpening: Boolean;

Description

If DragOpening is set to True, dragging an object over the [+] signs of group or master rows expands them.  If DragOpening is set to False, group and master rows are not expanded during drag-and-drop.

A grid control allows you to associate several detail views at the same hierarchy level with the current view.  Such views are displayed in tabbed pages.  See the TcxGridLevel.Options.DetailTabsPosition property to make tabs visible.

When DragOpening is True and you drag an object over a tab, the corresponding page is activated.  If DragOpening is False, the detail is not opened when dragging over its tab.

The delay before opening a corresponding item is specified by the DragOpeningWaitTime property.

The default value of the DragOpening property is True.


TcxCustomGridTableOptionsBehavior.DragScrolling

TcxCustomGridTableOptionsBehavior          See Also

Enables scrolling of the current view during drag-and-drop.

property DragScrolling: Boolean;

Description

The DragScrolling property indicates whether the current view is scrolled automatically when dragging an object to the top, left, bottom or right view edges.

If DragScrolling is set to False, the view is not automatically scrolled during drag-and-drop.  Setting DragScrolling to False is convenient if the user is likely to drag items of the current grid view in order to drop on another control.  When the mouse exits the view, scrolling may occur when the user doesn't actually need or want it.

The default value of the DragScrolling property is True.


TcxCustomGridTableOptionsBehavior.FocusCellOnCycle

TcxCustomGridTableOptionsBehavior          See Also

Determines whether focus moves to the next/previous row after it passes the rightmost/leftmost cell within the current row.

property FocusCellOnCycle: Boolean;

Description

Use the FocusCellOnCycle property to allow the cell focus to cycle within the current view by moving focus to the next row when it passes the last cell within the current row or to the previous row when it passes the first cell of the current row.

Note:	Moving the cell focus outside of the view from the first or last cell in the current view results in removing the focus from the grid control and focusing the next or previous control in a form (according to the form’s tab order).

The default value of the FocusCellOnCycle property is False.


TcxCustomGridTableOptionsBehavior.FocusCellOnTab

TcxCustomGridTableOptionsBehavior          See Also

Determines whether the Tab key is used to navigate through the current view’s cells.

property FocusCellOnTab: Boolean;

Description

Use the FocusCellOnTab property to enable moving through the current view’s cells using the Tab key.  If this property value is False, then the Tab key navigates the form controls instead.

Note:	Moving the cell focus outside of the view from the first or last cell in the current view results in removing the focus from the grid control and focusing the next or previous control in a form (according to the form’s tab order).

The default value of the FocusCellOnTab property is False.


TcxCustomGridTableOptionsBehavior.FocusFirstCellOnNewRecord

TcxCustomGridTableOptionsBehavior          See Also

Determines whether the focus moves to the first cell of a newly created row.

property FocusFirstCellOnNewRecord: Boolean;

Description

Use the FocusCellOnNewRecord property to determine whether focus moves to the first cell of a newly created record.  If this property value is False, then focus stays on the same cell relative to the previously focused record.

The default value of the FocusFirstCellOnNewRecord property is False.


TcxCustomGridTableOptionsBehavior.GoToNextCellOnEnter

TcxCustomGridTableOptionsBehavior          See Also

Determines whether the current view columns can be navigated by using the Enter key.

property GoToNextCellOnEnter: Boolean;

Description

Use the GoToNextCellOnEnter property to enable navigation of the current view columns by using the Enter key.

The default value of the GoToNextCellOnEnter property is False.


TcxCustomGridTableOptionsBehavior.ImmediateEditor

TcxCustomGridTableOptionsBehavior          See Also

Determines whether a specific column editor is activated immediately after an appropriate cell is clicked.

property ImmediateEditor: Boolean;

Description

Use the ImmediateEditor property to determine whether a specific column editor is activated when a user clicks an appropriate cell.  If this property value is False, then the grid cell editor is activated by pressing the Enter key when focus is located within a specific cell.

The default value of the ImmediateEditor property is True.


TcxCustomGridTableOptionsBehavior.IncSearch

TcxCustomGridTableOptionsBehavior          See Also

Specifies whether a user can perform an incremental search within the current view.

property IncSearch: Boolean;

Description

Set the IncSearch property to True to enable a user to start typing and have the grid automatically navigate to the closest match.  If IncSearch is False, a user cannot locate records in this way.

The item’s Options.IncSearch property specifies whether an incremental search can be performed on individual items and overrides the grid tables global behavior.

The default value of the IncSearch property is False.


TcxCustomGridTableOptionsBehavior.IncSearchItem

TcxCustomGridTableOptionsBehavior          See Also

Specifies the item against which an incremental search is performed when cell focusing is disabled.

property IncSearchItem: TcxCustomGridTableItem;

Description

The incremental search feature allows an end-user to locate the required record by the value of a specific item.  To enable an incremental search, set the view’s OptionsBehavior.IncSearch property to True.  The item’s Options.IncSearch property must be True as well.  An end-user can then find the desired record by focusing the item against which the search is to be performed followed by typing the start of the required value. The cell containing the typed value will be located within the item and the corresponding record will be focused.

However, if the view’s OptionsSelection.CellSelect property is set to False, the user is unable to focus the required item.  In this case, use the IncSearchItem property to specify the search item explicitly.  Setting the OptionsSelection.CellSelect property to False can be useful, for instance, when you want to disable editing data within the view, but still provide the user with the ability to do the search.  Note that IncSearchItem is effective only if focusing is disabled via setting the OptionsSelection.CellSelect property to False.

Use the view’s Controller.IncSearchingText property to start the search programmatically.  The view’s DataController.Search.LocateNext method allows you to continue the search in the required direction.  To cancel the search, see the Controller.CancelIncSearching method.


TcxCustomGridTableOptionsBehavior.NavigatorHints

TcxCustomGridTableOptionsBehavior

Specifies whether hints should be displayed for the embedded navigator’s buttons.

property NavigatorHints: Boolean;

Description

Card views, table views and banded table views display embedded data navigators provided that their OptionsView.Navigator option is enabled.  To display hints for the navigator buttons, set the NavigatorHints property to True.  This will enable default hints for all navigator buttons.  Note that you can override the default hint text for a particular button by setting the desired TcxNavigatorButton object’s Hint property to a proper string.  TcxNavigatorButton objects representing individual buttons can be accessed via the grid view’s NavigatorButtons property.


TcxCustomGridTableOptionsBehavior.PullFocusing

TcxCustomGridTableOptionsBehavior          See Also

Indicates whether focus moves to the record under the mouse pointer when a user clicks the left mouse button within a view and starts moving the mouse while holding the button down.

property PullFocusing: Boolean;

Description

Set the PullFocusing property to True to make the focused record track the mouse pointer when the end user clicks the left mouse button within a view and starts moving the mouse while holding the button down.  This allows you to scroll view records and move focus while dragging the mouse pointer within the view.  This behavior is similar to that provided by the listbox as this also allows you to select items by dragging.  Furthermore, focused records then become selected and remain so, if the view’s OptionsSelection.MultiSelect property is set to True.  When the OptionsSelection.CellMultiSelect property is set to True, clicking and moving the mouse also selects cells.

If PullFocusing is False, a click within the view focuses the underlying record.  However, subsequent dragging has no effect.

The PullFocusing property affects focus movement only if a click within a view does not initiate drag-and-drop.  This is the case if the view’s DragMode property is set to dmManual and you do not initiate drag-and-drop yourself by handling mouse-down events.

The default value of the PullFocusing property is False.


TcxCustomGridTableOptionsCustomize
TcxCustomGridTableOptionsCustomize Object

Hierarchy          Properties         Methods          See Also

Contains settings determining whether a user can customize a view via the view items (columns).

Unit

cxGridCustomTableView

TcxCustomGridTableOptionsCustomize = class(TcxCustomGridOptions);

Description

The TcxGrid control enables end users to perform a number of operations over view items (columns). These operations include changing the visible state (visible or hidden) and order of items, applying grouping and sorting by the item values.  You can use the OptionsCustomize property to control the availability of these features to the end users.

Note: You can implement all the mentioned features via code regardless of the OptionsCustomize options.


TcxCustomGridTableOptionsCustomize Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |


Properties for TcxCustomGridTableOptionsCustomize
TcxCustomGridTableOptionsCustomize Properties

TcxCustomGridTableOptionsCustomize          Legend

In TcxCustomGridTableOptionsCustomize

ItemFiltering

ItemGrouping

ItemHiding

ItemMoving

ItemSorting

Derived from TcxCustomGridOptions

GridView


Methods for TcxCustomGridTableOptionsCustomize
TcxCustomGridTableOptionsCustomize Methods

TcxCustomGridTableOptionsCustomize          Legend

In TcxCustomGridTableOptionsCustomize

SupportsItemsQuickCustomizationReordering


TcxCustomGridTableOptionsCustomize.ItemFiltering

TcxCustomGridTableOptionsCustomize          See Also

Controls the runtime filtering of the view’s items.

property ItemFiltering: Boolean;

Description

Use the ItemFiltering property to enable or disable the runtime filtering of the view’s items.  This property determines whether an end user can filter the view by items’ values.  Setting the ItemFiltering property to False prevents the filter dropdown buttons from being displayed within the items’ captions regardless of their Filtering property values.

The default value of the ItemFiltering property is True.


TcxCustomGridTableOptionsCustomize.ItemGrouping

TcxCustomGridTableOptionsCustomize          See Also

Activates runtime grouping for the view’s items.

property ItemGrouping: Boolean;

Description

Use the ItemGrouping property to enable or disable runtime grouping for the view’s items.  This property determines whether an end user can group the view via the required item values.  Even when this property value is False, grouping can still be performed via code.  Runtime grouping can also be disabled if the ItemMoving property value is False.

The default value of the ItemGrouping property is True.


TcxCustomGridTableOptionsCustomize.ItemHiding

TcxCustomGridTableOptionsCustomize          See Also

Controls the visibility of view items in the Customization form.

property ItemHiding: Boolean;

Description

Use the ItemHiding property to control the visibility of the view items in the Customization form.  Runtime view customization can also be disabled if the ItemMoving property value is False.

The default value of the ItemHiding property is False.


TcxCustomGridTableOptionsCustomize.ItemMoving

TcxCustomGridTableOptionsCustomize          See Also

Activates runtime moving of the view’s items.

property ItemMoving: Boolean;

Description

Use the ItemMoving property to enable or disable runtime moving of the view’s items.  This property also affects runtime grouping and item customization within a view.  If this property's value is False, then moving, grouping and item customization can be performed only via code.

The default value of the ItemMoving property is True.


TcxCustomGridTableOptionsCustomize.ItemSorting

TcxCustomGridTableOptionsCustomize          See Also

Activates runtime sorting of the view’s items.

property ItemSorting: Boolean;

Description

Use the ItemGrouping property to enable or disable runtime sorting within a view.  This property determines whether the end user can sort the view’s item values.  If this property's value is False, then sorting can still be performed via code.

The default value of the ItemSorting property is True.


TcxCustomGridTableOptionsCustomize.SupportsItemsQuickCustomizationReordering

TcxCustomGridTableOptionsCustomize          See Also

Determines whether users can reorder view items by dragging their names in the Quick Column Customization dropdown.

function SupportsItemsQuickCustomizationReordering: Boolean; virtual;

Description

This function returns True when reordering is enabled in the Quick Column Customization dropdown.

By default, True is returned if:

•	the dropdown is opened at design time;

•	an appropriate option is set via the View’s OptionsCustomize.ColumnsQuickCustomizationReordering property.


TcxCustomGridTableOptionsData
TcxCustomGridTableOptionsData Object

Hierarchy          Properties

Contains settings determining the functionality of a data-aware view.

Unit

cxGridCustomTableView

TcxCustomGridTableOptionsData = class(TcxCustomGridOptions);

Description

The properties of a TcxCustomGridTableOptionsData object are used to determine which actions can be performed for the data set providing the records for the current view.  These actions include inserting, appending, editing and deleting records.  The data options also indicate whether confirmation is required before record deletion and whether empty records can be posted into a data set.

Use the view’s OptionsData property to access this set of options.


TcxCustomGridTableOptionsData Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |


Properties for TcxCustomGridTableOptionsData
TcxCustomGridTableOptionsData Properties

TcxCustomGridTableOptionsData          Legend

In TcxCustomGridTableOptionsData

Appending

CancelOnExit

Deleting

DeletingConfirmation

Editing

GridView

Inserting

Derived from TcxCustomGridOptions

GridView


TcxCustomGridTableOptionsData.Appending

TcxCustomGridTableOptionsData          See Also

Determines whether a user can add a new record by pressing the down arrow on the keyboard when focus is on the last grid row.

property Appending: Boolean;

Description

Set the Appending property to True to allow a new record to be added by pressing the down arrow when focus is on the last grid row.

The default value of the Appending property is False.


TcxCustomGridTableOptionsData.CancelOnExit

TcxCustomGridTableOptionsData

Determines whether empty records are posted into a data set when the grid view loses focus.

property CancelOnExit: Boolean;

Description

Use the CancelOnExit property to determine whether empty records are posted into a data set when the grid view loses focus.  This situation occurs when a new record is inserted into a grid and focus is removed from the grid without entering any data into the record’s fields.  In this case, the empty record is not posted if the CancelOnExit property's value is True.

The default value of the CancelOnExit property is True.


TcxCustomGridTableOptionsData.Deleting

TcxCustomGridTableOptionsData          See Also

Determines whether a user is allowed to delete records within a view by pressing the Del or Ctrl+Del keys.

property Deleting: Boolean;

Description

Use the Deleting property to determine whether a user is allowed to delete records within a view via pressing the Del or Ctrl+Del keys.

The default value of the Deleting property is True.


TcxCustomGridTableOptionsData.DeletingConfirmation

TcxCustomGridTableOptionsData          See Also

Determines whether a message box appears requiring confirmation of the user’s request to delete a row.

property DeletingConfirmation: Boolean;

Description

Use the DeletingConfimation property to determine whether confirmation is required before deleting a row.

The default value of the DeletingConfirmation property is True.


TcxCustomGridTableOptionsData.Editing

TcxCustomGridTableOptionsData          See Also

Determines whether a user can edit records within a view.

property Editing: Boolean;

Description

Use the Editing property to determine whether a user can edit records within a view.  This property is not in effect if the GridTableOptionsSelection.CellSelect property value is False.

The default value of the Editing property is True.


TcxCustomGridTableOptionsData.GridView

TcxCustomGridTableOptionsData

Returns the view owning the current options set.

property GridView: TcxCustomGridTableView;

Description

The GridView property returns the view to which the current set of options is applied.  It can be used to access other sets of options, the styles collection and the columns collection, etc.

ReadOnly Property


TcxCustomGridTableOptionsData.Inserting

TcxCustomGridTableOptionsData          See Also

Determines whether a user can insert records by pressing the Insert key or via the new item row.

property Inserting: Boolean;

Description

Use the Inserting property to determine whether a user can insert records by pressing the Insert key or via the new item row.

The default value of the Inserting property is True.


TcxCustomGridTableOptionsSelection
TcxCustomGridTableOptionsSelection Object

Hierarchy          Properties          See Also

Contains settings affecting selections within a view.

Unit

cxGridCustomTableView

TcxCustomGridTableOptionsSelection = class(TcxCustomGridOptionsSelection);

Description

The properties of a TcxCustomGridOptionsSelection object determine the selection options for a view.  These options determine whether to select individual cells or whole rows, whether the focus rectangle is displayed around the focused row and whether multiple rows can be selected etc.

Use the OptionsSelection property to adjust this view’s group of options.


TcxCustomGridTableOptionsSelection Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |

TcxCustomGridOptionsSelection

     |


Properties for TcxCustomGridTableOptionsSelection
TcxCustomGridTableOptionsSelection Properties

TcxCustomGridTableOptionsSelection          Legend

In TcxCustomGridTableOptionsSelection

CellSelect

HideFocusRect

HideFocusRectOnExit

HideSelection

InvertSelect

MultiSelect

UnselectFocusedRecordOnExit

Derived from TcxCustomGridOptions

GridView


TcxCustomGridTableOptionsSelection.CellSelect

TcxCustomGridTableOptionsSelection

Determines whether individual cells can be selected within a view instead of whole rows.

property CellSelect: Boolean;

Description

Use the CellSelect property to determine whether individual cells can be selected within a view instead of whole rows.  Setting this property to False disables editing records within the current view.

The default value of the CellSelect property is True.


TcxCustomGridTableOptionsSelection.HideFocusRect

TcxCustomGridTableOptionsSelection          See Also

Determines whether the focus rectangle is displayed around the focused record when the grid loses its focus.

property HideFocusRect: Boolean;

Description

This property is obsolete and used for compatibility purposes.  Use the HideFocusRectOnExit property instead.


TcxCustomGridTableOptionsSelection.HideFocusRectOnExit

TcxCustomGridTableOptionsSelection          See Also

Determines whether the focus rectangle is displayed around the focused record when the grid loses its focus.

property HideFocusRectOnExit: Boolean;

Description

If the HideFocusRectOnExit property is set to True, the focus rectangle is hidden when the grid loses focus and the focused record is left highlighted.  Use the OptionsView.FocusRect property to control the focus rectangle's visibility when a grid is focused.

The default value of the HideFocusRectOnExit property is True.


TcxCustomGridTableOptionsSelection.HideSelection

TcxCustomGridTableOptionsSelection

Determines whether the selected rows are painted like other rows when focus leaves the grid control.

property HideSelection: Boolean;

Description

Use the HideSelection property to determine whether the selected rows are painted like other rows when focus leaves the grid control.  If this property is False, then the selected rows always appear highlighted within a view.

The default value of the HideSelection property is False.


TcxCustomGridTableOptionsSelection.InvertSelect

TcxCustomGridTableOptionsSelection

Determines whether a single cell within the focused row or the whole row is highlighted when focused.

property InvertSelect: Boolean;

Description

Use the InvertSelect property to determine whether a single cell within the focused row or the whole row is highlighted when focused.  The difference is demonstrated below:

The InvertSelect is set to True	The InvertSelect is set to False

The default value of the InvertSelect property is True.


TcxCustomGridTableOptionsSelection.MultiSelect

TcxCustomGridTableOptionsSelection          See Also

Determines whether multiple rows can be selected within a view.

property MultiSelect: Boolean;

Description

Use the MultiSelect property to determine whether multiple rows can be selected within a view.  This is implemented by navigating a view with the Ctrl or Shift keys pressed.  This applies to keyboard and mouse navigation.  The Shift key is used to select a range of rows, and the Ctrl key is used to select non-sequential rows.

Refer to the Selecting Records section for more information.

Use the CellMultiSelect property for extra selection customization.

The default value of the MultiSelect property is False.


TcxCustomGridTableOptionsSelection.UnselectFocusedRecordOnExit

TcxCustomGridTableOptionsSelection          See Also

Indicates whether to unselect the focused record when the current view loses focus.

property UnselectFocusedRecordOnExit: Boolean;

Description

When the MultiSelect property is True, a grid view enables you to select multiple records.  The focused record in this mode can either be selected or not (when MultiSelect is False, the focused record is always selected).  When a user clicks a specific record, it becomes focused and selected at the same time.

If the UnselectFocusedRecordOnExit property is True and no records are selected save the focused one, the record is automatically unselected on exiting the current view (when setting focus to another view or view clone).  If several records are selected, the selection of the focused record is not affected.

The selection of the focused record persists if the UnselectFocusedRecordOnExit property is set to False as well.

The default value of the UnselectFocusedRecordOnExit property is True.


TcxCustomGridTableOptionsView
TcxCustomGridTableOptionsView Object

Hierarchy          Properties          Methods          See Also

Contains settings determining the view’s appearance.

Unit

cxGridCustomTableView

TcxCustomGridTableOptionsView = class(TcxCustomGridOptionsView);

Description

The properties of the TcxCustomGridTableOptionsView object specify the view’s appearance options.  These options specify the editor buttons visibility and whether item captions and cell widths are automatically increased to display their full contents.

Use the view’s OptionsView property to access this set of options.


TcxCustomGridTableOptionsView Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |

TcxCustomGridOptionsView

     |


Properties for TcxCustomGridTableOptionsView
TcxCustomGridTableOptionsView Properties

TcxCustomGridTableOptionsView          Legend

In TcxCustomGridTableOptionsView

CellAutoHeight

CellEndEllipsis

CellTextMaxLineCount

FocusRect

GridView

Navigator

NavigatorOffset

NoDataToDisplayInfoText

ShowEditButtons

Derived from TcxCustomGridOptionsView

ScrollBars

Derived from TcxCustomGridOptions

GridView


Methods for TcxCustomGridTableOptionsView
TcxCustomGridTableOptionsView Methods

TcxCustomGridTableOptionsView          Legend

In TcxCustomGridTableOptionsView

 GetNoDataToDisplayInfoText


TcxCustomGridTableOptionsView.CellAutoHeight

TcxCustomGridTableOptionsView          See Also

Determines whether the height of item cells is automatically changed to display their contents in full.

property CellAutoHeight: Boolean;

Description

If the widths of the view’s columns are insufficient to display their entire content, then text clipping occurs.  Use the CellAutoHeight property to prevent this.  If this property value is True, then the cell content is displayed in multiple lines where necessary.

By default all grid rows have the same height.

Note that a grid which uses the image combo box control as an in-place editor is a special case.  The CellAutoHeight property has no effect on calculating the height of this editor since its height is determined by the height of the image displayed within the editor’s edit region.  The list of images that are available for displaying within the editor is accessible via the editor’s Properties.Images property.  As a result, the height of the editor (actually, the height of the images) also affects the minimal value of the DataRowHeight property so the image isn’t displayed clipped.

The default value of the CellAutoHeight property is False.


TcxCustomGridTableOptionsView.CellEndEllipsis

TcxCustomGridTableOptionsView          See Also

Specifies whether to display an ellipsis when cell text is clipped.

property CellEndEllipsis: Boolean;

Description

Set CellEndEllipsis to True to display an ellipsis when the entire text cannot be displayed within a cell.

The default value of the CellEndEllipsis property is False.


TcxCustomGridTableOptionsView.CellTextMaxLineCount

TcxCustomGridTableOptionsView          See Also

Determines the maximum number of lines for cells displayed within the current view.

property CellTextMaxLineCount: Integer;

Description

If the CellAutoHeight property is set to True, the height of cells is determined automatically based on the length of the field's contents.  In this case, you can limit the cell's height via the CellTextMaxLineCount property.  If the CellTextMaxLineCount property is 0, the cell's height is determined automatically.  If CellTextMaxLineCount is set to a value greater than 0, this specifies the maximum number of lines the view’s cells can occupy.

The default value of the CellTextMaxLineCount property is 0.


TcxCustomGridTableOptionsView.FocusRect

TcxCustomGridTableOptionsView          See Also

Determines whether the focus rectangle is displayed around the currently focused view record.

property FocusRect: Boolean;

Description

If the FocusRect property is set to True the focus rectangle will be displayed around the currently focused grid row while the grid has a focus.  Use the OptionsSelection.HideFocusRectOnExit property to control the focus rectangle's visibility when a grid loses its focus.

The default value of the FocusRect property is True.


TcxCustomGridTableOptionsView.GridView

TcxCustomGridTableOptionsView

Returns the view owning the current set of options.

property GridView: TcxCustomGridTableView;

Description

Use the GridView property to obtain the view owning the current set of options.  This property provides access to other view settings: the columns collection, styles and other sets of options etc.

ReadOnly Property


TcxCustomGridTableOptionsView.Navigator

TcxCustomGridTableOptionsView          See Also

Specifies the data navigator's visibility.

property Navigator: Boolean;

Description

Use the Navigator property to activate/deactivate the data navigator.  This navigator is displayed at the bottom of a view:

When an end-user presses one of the navigator’s buttons, an action occurs on the view’s data controller.  The actions consist of the following items:

•	Data navigation;

•	Inserting, deleting and editing records;

•	Posting and canceling changes;

•	Updating data;

•	Saving and switching to a bookmark;

•	Creating filter conditions using the Filter Builder dialog.

Note: The navigator provides functionality for all view types.  It works with data controllers bound to a dataset and with those working in unbound and provider modes.  See the IcxNavigatorControl topic for details.

The default value of the Navigator property is False.


TcxCustomGridTableOptionsView.NavigatorOffset

TcxCustomGridTableOptionsView

Specifies the distance (in pixels) between the data navigator and the horizontal view scrollbar.

property NavigatorOffset: Integer;

Description

Use the NavigatorOffset property to specify the distance (in pixels) between the data navigator and the horizontal scrollbar.  By default, the scrollbar adjoins the navigator.  Setting NavigatorOffset to a value greater than zero inserts an empty space between the elements and shrinks the scrollbar.

NavigatorOffset is set to 50

NavigatorOffset is set to 0

Use the OptionsView.Navigator property to activate/deactivate the data navigator.

When you change the width of a grid control, only the scrollbar is resized.  The width of the navigator remains constant.

The default value of the NavigatorOffset property is provided by the cxGridNavigatorDefaultOffset property.


TcxCustomGridTableOptionsView.NoDataToDisplayInfoText

TcxCustomGridTableOptionsView

Specifies a string that is displayed in the grid’s client area, if no rows are shown.

property NoDataToDisplayInfoText: string;

Description

Use the NoDataToDisplayInfoText property to provide an explanation to end-users, if no data is available in the grid’s client area.


TcxCustomGridTableOptionsView.ShowEditButtons

TcxCustomGridTableOptionsView          See Also

Determines the visibility of the editor buttons for the current view.

type TcxGridShowEditButtons = (gsebNever, gsebForFocusedRecord, gsebAlways);

property ShowEditButtons: TcxGridShowEditButtons;

Description

Use the ShowEditButtons property to specify which editor buttons are visible for the current view.

Value	Meaning
gsebNever	The editor buttons are displayed only for the focused item (column in a table view or row in a card view).
gsebForFocusedRecord	The editor buttons are visible for the focused record.
gsebAlways	The editor buttons are always visible within the current view

The item’s Options.ShowEditButtons property allows you to redefine these settings.

The default value of the ShowEditButtons property is gsebNever.


TcxCustomGridTableOptionsView.GetNoDataToDisplayInfoText

TcxCustomGridTableOptionsView

Returns a string specified by the OptionsView.NoDataToDisplayInfoText property.

function GetNoDataToDisplayInfoText: string;

Description

If the OptionsView.NoDataToDisplayInfoText property contains an empty string, the cxGridStrs.scxGridNoDataInfoText constant’s value will be retuned.


TcxGridItemFilterPopupOptions
TcxGridItemFilterPopupOptions Object

Hierarchy          Properties

The TcxGridItemFilterPopupOptions class provides options for a filter dropdown.

Unit

cxGridCustomTableView

TcxGridItemFilterPopupOptions = class(TcxCustomGridOptions)

Description

With the following options you can specify:

•	the mode in which the view is updated against the filter criteria (ApplyMultiSelectChanges);

•	the size of a filter dropdown – its width and the maximum number of items in the filter dropdown (DropDownWidth and MaxDropDownItemCount);

•	whether multiple selections of the filter dropdown’s items are available (MultiSelect).

The TcxGridItemFilterPopupOptions object is referenced by the view’s Filtering.ColumnPopup or Filtering.RowPopup properties for Table and Card views, respectively.


TcxGridItemFilterPopupOptions Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |

TcxGridItemFilterPopupOptions


Properties for TcxGridItemFilterPopupOptions
TcxGridItemFilterPopupOptions Properties

TcxGridItemFilterPopupOptions          Legend

In TcxGridItemFilterPopupOptions

ApplyMultiSelectChanges

DropDownWidth

MaxDropDownItemCount

MultiSelect


TcxGridItemFilterPopupOptions.ApplyMultiSelectChanges

TcxGridItemFilterPopupOptions          See Also

Specifies the manner the view is updated in.

property ApplyMultiSelectChanges: TcxGridItemFilterPopupApplyChangesMode;

Description

When applying a filter dropdown, you can specify the style the view is changed in.  This capability offers two modes to update the view with the filtered data:

•	fpacImmediately – the view is updated after the filter dropdown’s item has been clicked;

•	fpacOnButtonClick – in this mode, the Apply filter button appears at the bottom of the filter dropdown.  The view is only updated when the Apply filter button is clicked.  An end-user can select multiple items (if the MultiSelect property is set to True) prior to clicking the Apply filter button.

The default value of the ApplyMultiSelectChanges property is fpacImmediately.


TcxGridItemFilterPopupOptions.DropDownWidth

TcxGridItemFilterPopupOptions

Specifies the width of filter dropdowns.

property DropDownWidth: Integer;

Description

By default, the width of filter dropdowns is calculated automatically to fit all their items.  You can change this default behavior using the DropDownWidth property.  If this property is set to a positive integer, the width of filter dropdowns is calculated as the maximum of the item’s width and the DropDownWidth value.  Thus, if this property's value exceeds the item’s width, then it specifies the actual dropdown’s width.  Otherwise, the filter dropdown’s width will be equal to the item’s width.

The DropDownWidth property is useful if you need to display filter dropdowns in items whose values are long strings.  In such instances, you may need to limit the width of filter dropdowns using the DropDownWidth property.

The DropDownWidth property’s value is set in pixels.  Negative values are not accepted (the property is automatically set to 0).

The default value of the DropDownWidth property is 0.


TcxGridItemFilterPopupOptions.MaxDropDownItemCount

TcxGridItemFilterPopupOptions

Specifies the number of filter items simultaneously displayed within filter dropdowns.

property MaxDropDownItemCount: Integer;

Description

The MaxDropDownItemCount property sets the height of filter dropdowns for items as the number of filter items.  Note that the actual height may be less than that specified by the MaxDropDownItemCount property if the number set is greater than the total number of filter items to be displayed.

If the number of filter items to be displayed exceeds the MaxDropDownItemCount property’s value, filter dropdowns display scrollbars, which allow end-users to access all the filter items.

If the MaxDropDownItemCount property’s value is set to 0, filter dropdowns for items display all the filter items simultaneously.  Negative values are not accepted (the property’s value is automatically set to 0).

The default value of the MaxDropDownItemCount property is cxGridFilterDefaultItemPopupMaxDropDownItemCount.


TcxGridItemFilterPopupOptions.MultiSelect

TcxGridItemFilterPopupOptions          See Also

Specifies whether selection of multiple items in a filter dropdown is allowed.

property MultiSelect: Boolean;

Description

Set the MultiSelect property to False, to disable multiple selection of the filter dropdown’s items.

The default value of the MultiSelect property is True.


TcxGridItemFilterPopupApplyChangesMode
TcxGridItemFilterPopupApplyChangesMode type

See Also

Enumerates the mode in which the view is updated when using a filter dropdown.

Unit

cxGridCustomTableView

TcxGridItemFilterPopupApplyChangesMode = (fpacImmediately, fpacOnButtonClick);

Description

The following table contains the descriptions of the enumeration values:

Value	Meaning
fpacImmediately	The view is updated after clicking an item in a filter dropdown.
fpacOnButtonClick	The Apply filter button appears at the bottom of a filter dropdown.  The view is only updated when the Apply filter button is clicked.


cxGridFilterDefaultItemPopupMaxDropDownItemCount constant
cxGridFilterDefaultItemPopupMaxDropDownItemCount global constant

See Also

Specifies the default number of items in a filter dropdown.

Unit

cxGridCustomTableView

cxGridFilterDefaultItemPopupMaxDropDownItemCount = 15;

Description

Use the cxGridFilterDefaultItemPopupMaxDropDownItemCount constant to specify the default limit of the items available in a filter dropdown.


TcxGridShowItemFilterButtons
TcxGridShowItemFilterButtons type

See Also

Enumerates the visibility mode of the filter dropdown button.

Unit

cxGridCustomTableView

TcxGridShowItemFilterButtons = (sfbAlways, sfbWhenSelected);

Description

The following table contains descriptions of the enumeration values:

Value	Meaning
sfbAlways	Filter buttons are permanently visible in all rows (or columns)
sfbWhenSelected	A filter button is only shown in the selected row (or column)


TcxCustomGridTableDateTimeHandling
TcxCustomGridTableDateTimeHandling Object

Hierarchy          Properties          Methods          See Also

Represents a set of options that control the manner in which date/time item values are handled in a View and how these values are displayed when filtering or grouping is applied

Unit

cxGridCustomTableView

TcxCustomGridTableDateTimeHandling = class(TcxCustomGridOptions)

Description

The TcxCustomGridTableDateTimeHandling class introduces properties that control:

•	time periods to be included into an item’s filter dropdown as filter conditions (Filters);

•	time periods to be used in group rows as grouping values (Grouping);

•	appearance aspects of date/time item values in filter dropdowns and group rows when data is filtered or grouped by an item (HourFormat, DateFormat, MonthFormat, YearFormat, UseLongDateFormat, and UseShortTimeFormat);

•	the manner in which date/time values are filtered and grouped (IgnoreTimeForFiltering and Grouping properties, respectively).

TcxCustomGridTableDateTimeHandling descendants provide options relevant for their corresponding Views.  To access settings represented by a derived class, use a View’s DateTimeHandling property.


TcxCustomGridTableDateTimeHandling Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |

TcxCustomGridTableDateTimeHandling


Properties for TcxCustomGridTableDateTimeHandling
TcxCustomGridTableDateTimeHandling Properties

TcxCustomGridTableDateTimeHandling          Legend

In TcxCustomGridTableDateTimeHandling

DateFormat

Filters

GridView

Grouping

HourFormat

IgnoreTimeForFiltering

MonthFormat

UseLongDateFormat

UseShortTimeFormat

YearFormat


Methods for TcxCustomGridTableDateTimeHandling
TcxCustomGridTableDateTimeHandling Methods

TcxCustomGridTableDateTimeHandling          Legend

In TcxCustomGridTableDateTimeHandling

GetDateFormat

GetHourFormat

GetMonthFormat

GetYearFormat


TcxCustomGridTableDateTimeHandling.DateFormat

TcxCustomGridTableDateTimeHandling          See Also

Specifies the format pattern for grouping values created using the date part of item values.

property DateFormat: string;

Description

If this property is set to an empty string, the format pattern is determined automatically as specified by the GetDateFormat function.

Refer to the Date-Time Format Strings topic for additional information on specifiers that can be used to create the format string.

A View creates grouping values using the date part of item values provided that:

•	the Grouping property is set to dtgByDate and data is grouped by any of the items that display date/time values;

•	the DateTimeGrouping property of an item that displays date/time values is set to dtgByDate and data is grouped by this item.

These grouping values are displayed in the corresponding group rows.


TcxCustomGridTableDateTimeHandling.Filters

TcxCustomGridTableDateTimeHandling          See Also

Specifies a set of date/time filter options that determine time periods to be included into filter dropdowns as filter conditions.

type

  TcxGridDateTimeFilter = (dtfRelativeDays, dtfRelativeDayPeriods, dtfRelativeWeeks, dtfRelativeMonths, dtfRelativeYears, dtfPastFuture, dtfMonths, dtfYears);

  TcxGridDateTimeFilters = set of TcxGridDateTimeFilter;

property Filters: TcxGridDateTimeFilters;

Description

Refer to the description of the TcxGridDateTimeFilter type to learn about available date/time filter options.

Handle the OnInitFilteringDateRanges event of a View or an item to customize a collection of filter date ranges created for each item that displays date/time values.

The default value of the Filters property is [].


TcxCustomGridTableDateTimeHandling.GridView

TcxCustomGridTableDateTimeHandling

Provides access to the View to which the set of options is applied.

property GridView: TcxCustomGridTableView;

ReadOnly Property


TcxCustomGridTableDateTimeHandling.Grouping

TcxCustomGridTableDateTimeHandling          See Also

Specifies a date/time grouping option that determines time periods to be used as grouping values in group rows.

type

  TcxGridDateTimeGrouping = (dtgDefault, dtgByDateAndTime, dtgRelativeToToday, dtgByHour, dtgByDate, dtgByMonth, dtgByYear);

property Grouping: TcxGridDateTimeGrouping;

Description

Refer to the description of the TcxGridDateTimeGrouping type to learn about available date/time grouping options.

Note that setting the Grouping property to dtgDefault automatically assigns dtgByDateAndTime to this property.

To specify a date/time grouping option for a particular item, use the item’s DateTimeGrouping property.

Handle the OnInitGroupingDateRanges event of a View or an item to customize a collection of grouping date ranges created for each item.

The default value of the Grouping property is dtgByDateAndTime.


TcxCustomGridTableDateTimeHandling.HourFormat

TcxCustomGridTableDateTimeHandling          See Also

Specifies the format pattern for grouping values created using hours.

property HourFormat: string;

Description

If this property is set to an empty string, the format pattern is determined automatically as specified by the GetHourFormat function.

Refer to the Date-Time Format Strings topic for additional information on specifiers that can be used to create the format string.

A View creates grouping values using hours provided that:

•	the Grouping property is set to dtgByHour and data is grouped by any of the items that display date/time values;

•	the DateTimeGrouping property of an item that displays date/time values is set to dtgByHour and data is grouped by this item.

These grouping values are displayed in the corresponding group rows.


TcxCustomGridTableDateTimeHandling.IgnoreTimeForFiltering

TcxCustomGridTableDateTimeHandling

Specifies whether the time part of date/time item values is ignored when filtering by these values.

property IgnoreTimeForFiltering: Boolean;

Description

Set this property to True to specify that the time part of all items that display date/time values should be ignored when:

•	adding unique date/time values into a filter dropdown of these items;

•	applying a filter to any of these items.

Otherwise, the time part is taken into account when filtering by date/time values.

To provide this behavior for an individual item, use the item’s Options.IgnoreTimeForFiltering property.

The default value of the IgnoreTimeForFiltering property is False.


TcxCustomGridTableDateTimeHandling.MonthFormat

TcxCustomGridTableDateTimeHandling          See Also

Specifies the format pattern for filter conditions and grouping values created using months.

property MonthFormat: string;

Description

If this property is set to an empty string, the format pattern is determined automatically as specified by the GetMonthFormat function.

Refer to the Date-Time Format Strings topic for additional information on specifiers that can be used to create the format string.

A View creates filter conditions using months when the dtfMonths option is enabled in the Filters property and a filter dropdown is opened for any item that displays date/time values.

A View creates grouping values using months provided that:

•	the Grouping property is set to dtgByMonth, and data is grouped by any of the items which display date/time values;

•	the DateTimeGrouping property of an item that displays date/time values is set to dtgByMonth and data is grouped by this item.

These grouping values are displayed in corresponding group rows.


TcxCustomGridTableDateTimeHandling.UseLongDateFormat

TcxCustomGridTableDateTimeHandling

Specifies whether the LongDateFormat global variable provides the default format pattern for grouping values created using the date part of item values.

property UseLongDateFormat: Boolean;

Description

Set this property to True to specify that the LongDateFormat global variable provides the format pattern when the DateFormat property is set to an empty string.

The resulting format pattern that will be used to format grouping values created using the date part of date/time item values is determined by the GetDateFormat function.

The default value of the UseLongDateFormat property is True.


TcxCustomGridTableDateTimeHandling.UseShortTimeFormat

TcxCustomGridTableDateTimeHandling

Specifies whether the ShortTimeFormat global variable provides the default format pattern for grouping values created using hours.

property UseShortTimeFormat: Boolean;

Description

Set this property to True to specify that the ShortTimeFormat global variable provides the format pattern when the HourFormat property is set to an empty string.

The resulting format pattern that will be used to format grouping values created using hours is determined by the GetHourFormat function.

The default value of the UseShortTimeFormat property is True.


TcxCustomGridTableDateTimeHandling.YearFormat

TcxCustomGridTableDateTimeHandling          See Also

Specifies the format pattern for filter conditions and grouping values created using years.

property YearFormat: string;

Description

If this property is set to an empty string, the format pattern is determined automatically as specified by the GetYearFormat function.

Refer to the Date-Time Format Strings topic for additional information on specifiers which can be used to create the format string.

A View creates filter conditions using years when the dtfYears option is enabled in the Filters property, and a filter dropdown is opened for any item that displays date/time values.

A View creates grouping values using years provided that:

•	the Grouping property is set to dtgByYear, and data is grouped by any of the items that display date/time values;

•	the DateTimeGrouping property of an item that displays date/time values is set to dtgByYear and data is grouped by this item.

These grouping values are displayed in corresponding group rows.


TcxCustomGridTableDateTimeHandling.GetDateFormat

TcxCustomGridTableDateTimeHandling          See Also

Returns the format pattern used to display grouping values created using the date part of item values.

function GetDateFormat: string;

Description

If the DateFormat property is set to an empty string, the format pattern is determined automatically using the LongDateFormat global variable, provided that the UseLongDateFormat property is set to True.  Otherwise, an empty string is returned as the resulting format string.


TcxCustomGridTableDateTimeHandling.GetHourFormat

TcxCustomGridTableDateTimeHandling          See Also

Returns the format pattern used to display grouping values created using hours.

function GetHourFormat: string;

Description

If the HourFormat property is set to an empty string, the format pattern is determined automatically using the ShortTimeFormat global variable, provided that the UseShortTimeFormat property is set to True.  Otherwise, an empty string is returned as the resulting format string.


TcxCustomGridTableDateTimeHandling.GetMonthFormat

TcxCustomGridTableDateTimeHandling          See Also

Returns the format pattern used to display filter conditions and grouping values created using months.

function GetMonthFormat: string;

Description

If the MonthFormat property is set to an empty string, the resulting format pattern is determined by the scxGridMonthFormat resource string.


TcxCustomGridTableDateTimeHandling.GetYearFormat

TcxCustomGridTableDateTimeHandling          See Also

Returns the format pattern used to display filter conditions and grouping values created using years.

function GetYearFormat: string;

Description

If the YearFormat property is set to an empty string, the resulting format pattern is determined by the scxGridYearFormat resource string.


TcxCustomGridDateRange
TcxCustomGridDateRange Object

Hierarchy          Properties          Methods          See Also

Represents a generic date range for date/time item values.

Unit

cxGridCustomTableView

TcxCustomGridDateRange = class(TObject)

Description

You are able to filter and group data in a View by date/time item values combined into the following time periods:

•	relative to the current date (such as yesterday, tomorrow, next month, etc.);

•	absolute time periods (such as calendar days, months, and years);

•	absolute time periods created using specific portions of date/time values (such as the date part of date/time values, hours, etc.)

These time periods are derived from item values and are represented in a View as:

•	filter conditions in item filter dropdowns;

•	group values in group rows.

Note:	A filter condition or grouping value is created for an item, provided that there’s at least one item value that falls into the corresponding time period.

To determine whether an item value falls into a certain time period, a date range is used.

Each item contains date range collections that will be used to determine time periods to be created when data is:

•	filtered by the item (a collection of filter date ranges is accessible via the FilteringDateRanges property);

•	grouped by the item (a collection of grouping date ranges is accessible via the GroupingDateRanges property).

The TcxCustomGridDateRange class represents the base class for all classes that represent date ranges.  Members of this class allow you to:

•	determine whether a particular value falls into time periods associated with a date range (Contains);

•	access the corresponding date range collection and specify a date range’s position in this collection (Container and Index);

•	obtain the time span and a string representation of a particular time period associated with a date range (GetRangeValue and GetDisplayText),

•	obtain a grouping value associated with this time period (GetValue).

TcxCustomGridDateRange descendants override these members to return values specific to their corresponding date ranges.


TcxCustomGridDateRange Hierarchy
Hierarchy

TObject

     |

TcxCustomGridDateRange


Properties for TcxCustomGridDateRange
TcxCustomGridDateRange Properties

TcxCustomGridDateRange          Legend

In TcxCustomGridDateRange

Container

Index


Methods for TcxCustomGridDateRange
TcxCustomGridDateRange Methods

TcxCustomGridDateRange          Legend

In TcxCustomGridDateRange

Contains

GetDisplayText

GetRangeValue

GetSortingValue

GetValue

NeedsSortingByTime

NeedsTime


TcxCustomGridDateRange.Container

TcxCustomGridDateRange          See Also

Provides access to a zero-based indexed collection, which contains the date range.

property Container: TcxGridDateRanges;

Description

This property references one of the following item’s collections:

•	a collection of filter date ranges (FilteringDateRanges);

•	a collection of grouping date ranges (GroupingDateRanges).

ReadOnly Property


TcxCustomGridDateRange.Index

TcxCustomGridDateRange

Specifies the position of the date range in the owner collection accessible via the Container property.

property Index: Integer;


TcxCustomGridDateRange.Contains

TcxCustomGridDateRange          Example

Determines whether a specified item value falls into any time period associated with the date range.

function Contains(const ADate: TDateTime): Boolean; virtual; abstract;

Description

When implemented in a derived class, this function returns True provided that ADate falls into any time period associated with the date range.  Otherwise, False is returned.

Descendants of the TcxCustomGridDateRange class override this function to return values specific to their corresponding date ranges.  For instance, TcxGridYesterdayRange overrides the Contains function to return True only for the day before today.


TcxCustomGridDateRange.GetDisplayText

TcxCustomGridDateRange          Example

Determines a string representation of a particular time period associated with the date range.  This time period contains the ADate item value.

function GetDisplayText(const ADate: TDateTime): string; virtual; abstract;

Description

Descendants of the TcxCustomGridDateRange class override this function to return values specific to their corresponding date ranges.  For instance, TcxGridYesterdayRange returns the value of the scxGridYesterday resource string.  The TcxGridMonthRange class formats ADate as specified by a View’s DateTimeHandling.GetMonthFormat function.


TcxCustomGridDateRange.GetRangeValue

TcxCustomGridDateRange          Example

Returns a span of a particular time period associated with the date range.

function GetRangeValue(const ADate: TDateTime; AIgnoreTime: Boolean): Variant; virtual;

Description

This function returns a variant array whose elements represent the start and end dates of the time period respectively.  This time period contains the item value passed as the ADate parameter.

When the AIgnoreTime parameter is set to False, the time part of the end date is adjusted so that it represents the exact end of the day.  This is useful if the time part is taken into account when filtering date/time values.  Use the View’s DateTimeHandling.IgnoreTimeForFiltering and an item’s Options.IgnoreTimeForFiltering properties to enable this capability.

Descendants of the TcxCustomGridDateRange class override this function to return values specific to their corresponding date ranges.


TcxCustomGridDateRange.GetSortingValue

TcxCustomGridDateRange          See Also

Returns the sort value for a particular time period associated with the date range.  This time period contains the ADate item value.

function GetSortingValue(const ADate: TDateTime): Variant; virtual;

Description

Values returned by this function are used to compare time periods associated with the same date range.  These values affect the display order of

•	the corresponding filter conditions in item filter dropdowns;

•	the corresponding group rows in a View.

By default, this function returns the date passed as the ADate parameter unless the NeedsSortingByTime function returns True.  In the latter instance, the time part of the date is returned.


TcxCustomGridDateRange.GetValue

TcxCustomGridDateRange          See Also          Example

Returns the grouping value that corresponds to a particular time period associated with the date range.  This time period contains the ADate item value.

function GetValue(const ADate: TDateTime): Variant; virtual; abstract;


TcxCustomGridDateRange.NeedsSortingByTime

TcxCustomGridDateRange          See Also

Determines whether time periods associated with the date range are sorted by time.

function NeedsSortingByTime: Boolean; virtual;

Description

This function returns True when time periods associated with the date range are sorted by time (i.e. the date part of these time periods is ignored).  By default, this function returns False.

Descendants of the TcxCustomGridDateRange class that represent time ranges (for instance, TcxGridHourRange) override this function to enable sorting by corresponding time periods.


TcxCustomGridDateRange.NeedsTime

TcxCustomGridDateRange

Determines whether the time part of item values is used to create grouping values for time periods associated with the date range.

function NeedsTime: Boolean; virtual;

Description

When this function returns False, the time part of item values is ignored when grouping values are created via the GetValue function.

By default, this function returns the value which is returned by the NeedsSortingByTime function.


TcxGridDateRanges
TcxGridDateRanges Object

Hierarchy          Properties          Methods          See Also

Represents a generic collection of date ranges for date/time item values.

Unit

cxGridCustomTableView

TcxGridDateRanges = class(TObject)

Description

The TcxGridDateRanges class represents the base class for all classes that represent item date range collections used to determine time periods into which date/time item values are combined when data is filtered or grouped by a corresponding item.

Members of the TcxGridDateRanges class allow you to:

•	initialize service properties used to calculate relative time periods (Init);

•	manage date ranges within the collection (Add and Clear);

•	access a particular date range within the collection (Items and GetRange).

Descendants of the TcxGridDateRanges class represent:

•	An item’s collection of filter date ranges (TcxGridFilteringDateRanges).  Use the item’s FilteringDateRanges property to access an instance of this class.

•	An item’s collection of grouping date ranges (TcxGridGroupingDateRanges).  Use the item’s GroupingDateRanges property to access an instance of this class.


TcxGridDateRanges Hierarchy
Hierarchy

TObject

     |

TcxGridDateRanges


Properties for TcxGridDateRanges
TcxGridDateRanges Properties

TcxGridDateRanges          Legend

In TcxGridDateRanges

Count

DateTimeHandling

Items

StartOfThisWeek

ThisDay

ThisMonth

ThisMonthNumber

ThisYear

Today


Methods for TcxGridDateRanges
TcxGridDateRanges Methods

TcxGridDateRanges          Legend

In TcxGridDateRanges

Add

Clear

GetRange

Init

IsEmpty

NeedSortingByTime

NeedTime


TcxGridDateRanges.Count

TcxGridDateRanges          See Also

Returns the total number of date ranges that are contained within the collection.

property Count: Integer;

Description

Use the zero-based Items collection to access a specific date range by its index.

ReadOnly Property


TcxGridDateRanges.DateTimeHandling

TcxGridDateRanges          See Also

Provides access to a set of date/time handling settings (an object of the TcxCustomGridTableDateTimeHandling class or its descendant) used to initialize the collection.

property DateTimeHandling: TcxCustomGridTableDateTimeHandling;

Description

These settings are passed as the Init method’s parameter.

To access a set of date/time handling settings for a particular tabular or Card view, use the View’s DateTimeHandling property.

ReadOnly Property


TcxGridDateRanges.Items

TcxGridDateRanges          See Also

Provides indexed access to date ranges which are contained within the collection.

property Items[Index: Integer]: TcxCustomGridDateRange;

Description

Each date range represents an instance of the TcxCustomGridDateRange class or one of its descendants.

To add a date range into this collection, call the Add method.

Use the Count property to get a count of date ranges within the collection.

ReadOnly Property


TcxGridDateRanges.StartOfThisWeek

TcxGridDateRanges

Returns the first day of the current week.

property StartOfThisWeek: TDateTime;

Description

The StartOfThisWeek property’s value is used to determine whether a particular date falls into a week period relative to today.  A week period is represented by the TcxGridLastWeekRange, TcxGridThisWeekRange, or TcxGridNextWeekRange date range.

The time part of the return value is 0 (midnight).

Note:	This property is one of the service properties that are initialized by the Init method.  Values of these properties are relevant for initialization time.

ReadOnly Property


TcxGridDateRanges.ThisDay

TcxGridDateRanges

Returns the day portion of the current date.

property ThisDay: Word;

Description

This property returns values between 1 and 31.

Note:	This property is one of the service properties which are initialized by the Init method.  Values of these properties are relevant for the initialization time.

ReadOnly Property


TcxGridDateRanges.ThisMonth

TcxGridDateRanges

Returns the month portion of the current date.

property ThisMonth: Word;

Description

This property returns values between 1 and 12.

Note:	This property is one of the service properties which are initialized by the Init method.  Values of these properties are relevant for the initialization time.

ReadOnly Property


TcxGridDateRanges.ThisMonthNumber

TcxGridDateRanges

Returns an ordinal number of the current month.

property ThisMonthNumber: Integer;

Description

Compared with the ThisMonth property, the ThisMonthNumber property’s value is calculated as an ordinal number of the current month in a sequence of years starting from year 1.

The ThisMonthNumber property is used to determine whether a particular date falls into a month period relative to today.  A month period is represented by the TcxGridLastMonthRange, TcxGridThisMonthRange, or TcxGridNextMonthRange date range.

Note:	This property is one of the service properties that are initialized by the Init method.  Values of these properties are relevant for initialization time.

ReadOnly Property


TcxGridDateRanges.ThisYear

TcxGridDateRanges

Returns the year part of the current date.

property ThisYear: Word;

Description

This property returns values between 1 and 9999.

The ThisYear property value is used to determine whether a particular date falls into a year period relative to today.  A year period is represented by the TcxGridLastYearRange, TcxGridThisYearRange, or TcxGridNextYearRange date range.

Note:	This property is one of the service properties that are initialized by the Init method.  Values of these properties are relevant for initialization time.

ReadOnly Property


TcxGridDateRanges.Today

TcxGridDateRanges

Returns the current local date.

property Today: TDateTime;

Description

The Today property’s value is used to determine whether a particular date falls into a day period relative to today.  A day period is represented by the TcxGridYesterdayRange, TcxGridTodayRange, or TcxGridTomorrowRange date range.

The time part of this value is 0 (midnight).

Note:	This property is one of the service properties that are initialized by the Init method.  Values of these properties are relevant for initialization time.

ReadOnly Property


TcxGridDateRanges.Add

TcxGridDateRanges          See Also

Adds a specified date range or a specific date range type into the collection.

Overloaded Variants

type

  TcxCustomGridDateRangeClass = class of TcxCustomGridDateRange;

procedure Add(ARange: TcxCustomGridDateRange); overload;

procedure Add(ARangeClass: TcxCustomGridDateRangeClass); overload;

Description

The first overloaded variant of this method allows you to add the date range into the collection by passing it as the ARange parameter.

The second variant of the Add method allows you to pass date range type via the ARangeClass parameter.  This creates an instance of the specified type and adds it to the collection.

All date ranges that are contained within the collection can be accessed via the Items zero-based indexed collection.


TcxGridDateRanges.Clear

TcxGridDateRanges          See Also

Removes all the date ranges which are contained in the collection.

procedure Clear;

Description

This method removes all date ranges from the Items zero-based indexed collection.  The IsEmpty property returns True in this instance.

To add date ranges into the collection, call the Add method.


TcxGridDateRanges.GetRange

TcxGridDateRanges          See Also

Searches the collection for the date range either by its type or by the date that falls into a time period associated with this date range.

Overloaded Variants

type

  TcxCustomGridDateRangeClass = class of TcxCustomGridDateRange;

function GetRange(const ADate: TDateTime): TcxCustomGridDateRange;

function GetRange(ARangeClass: TcxCustomGridDateRangeClass): TcxCustomGridDateRange;

Description

The first overloaded variant of this function allows you to search the collection for the first date range that corresponds to a time period which the date passed as the ADate parameter falls into.

The second overloaded variant of the GetRange function allows you to find the date range within the collection by its type passed as the ARangeClass parameter.

If found, the GetRange function returns the date range.  Otherwise, nil is returned.


TcxGridDateRanges.Init

TcxGridDateRanges

Initializes the collection with settings required to determine the appearance of time periods associated with date ranges from the collection.

procedure Init(ADateTimeHandling: TcxCustomGridTableDateTimeHandling); virtual;

Description

This method performs the following:

•	Assigns formatting options passed as the ADateTimeHandling parameter - common to all date ranges and date/time values within a View - to the DateTimeHandling property.  Tabular and Card Views provide these options via the DateTimeHandling property.

•	Initializes service properties to calculate relative time periods.

•	Clears the collection.

Descendants of the TcxGridDateRanges class overload the Init method to provide additional information that determines the date ranges to be included into a corresponding collection.  Refer to the descriptions of the TcxGridFilteringDateRanges.Init and TcxGridGroupingDateRanges.Init methods for more information.


TcxGridDateRanges.IsEmpty

TcxGridDateRanges          See Also

Determines whether the collection contains any date ranges.

function IsEmpty: Boolean;

Description

This property returns True when the collection doesn’t contain any date ranges (i.e. the Count property’s value is equal to 0).

Use the Items zero-based collection to access a specific date range by its index.


TcxGridDateRanges.NeedSortingByTime

TcxGridDateRanges          See Also

Determines whether the collection uses the time part of time periods associated with date ranges in this collection to sort these time periods.

function NeedSortingByTime: Boolean;

Description

When the NeedsSortingByTime function of at least one date range from the collection returns True, the NeedSortingByTime function returns True.  Otherwise, False is returned.


TcxGridDateRanges.NeedTime

TcxGridDateRanges          See Also

Determines whether the collection uses the time part of item values to create grouping values for time periods associated with date ranges in this collection.

function NeedTime: Boolean;

Description

When the NeedsTime function of at least one date range from the collection returns True, the NeedTime function returns True.  Otherwise, False is returned.


TcxGridFilteringDateRanges
TcxGridFilteringDateRanges Object

Hierarchy          Properties          Methods          See Also

Represents a collection of filter date ranges for an item, which displays date/time values.

Unit

cxGridCustomTableView

TcxGridFilteringDateRanges = class(TcxGridDateRanges)

Description

Date ranges in this collection determine time periods by which date/time item values can be filtered out.  This collection is initialized as specified by the View’s DateTimeHandling.Filters property using the Init method.  You can handle the OnInitFilteringDateRanges events for a View and an item to customize this collection for all View items and an individual item, respectively.

Use an item’s FilteringDateRanges property to access a collection of filter date ranges created for this item.


TcxGridFilteringDateRanges Hierarchy
Hierarchy

TObject

     |

TcxGridDateRanges

     |

TcxGridFilteringDateRanges


Properties for TcxGridFilteringDateRanges
TcxGridFilteringDateRanges Properties

TcxGridFilteringDateRanges          Legend

Derived from TcxGridDateRanges

Count

DateTimeHandling

Items

StartOfThisWeek

ThisDay

ThisMonth

ThisMonthNumber

ThisYear

Today


Methods for TcxGridFilteringDateRanges
TcxGridFilteringDateRanges Methods

TcxGridFilteringDateRanges          Legend

In TcxGridFilteringDateRanges

Init

Derived from TcxGridDateRanges

Add

Clear

GetRange

Init

IsEmpty

NeedSortingByTime

NeedTime


TcxGridFilteringDateRanges.Init

TcxGridFilteringDateRanges          See Also

Initializes the collection of filter date ranges with settings required for date ranges to filter date/time item values.

type

  TcxGridDateTimeFilter = (dtfRelativeDays, dtfRelativeDayPeriods, dtfRelativeWeeks, dtfRelativeMonths, dtfRelativeYears, dtfPastFuture, dtfMonths, dtfYears);

  TcxGridDateTimeFilters = set of TcxGridDateTimeFilter;

procedure Init(ADateTimeHandling: TcxCustomGridTableDateTimeHandling; ADateTimeFilters: TcxGridDateTimeFilters); reintroduce; virtual;

Description

The Init method functions in the same manner as its ancestor method and also overloads it with a set of date/time filter conditions passed as the ADateTimeFilters parameter.  This set determines which of the date ranges should be included into the collection and populates accordingly the Items zero-based indexed collection.

Note:	Only the TcxGridMonthRange and TcxGridYearRange date ranges (which correspond to the dtfMonths and dtfYears filter options in the DateTimeHandling.Filters property, respectively) are included into the Items collection.

Handle the OnInitFilteringDateRanges event to customize the collection of filter date ranges.


TcxGridGroupingDateRanges
TcxGridGroupingDateRanges Object

Hierarchy          Properties          Methods          See Also

Represents a collection of grouping date ranges for an item, which displays date/time values.

Unit

cxGridCustomTableView

TcxGridGroupingDateRanges = class(TcxGridDateRanges)

Description

Date ranges in this collection determine time periods by which date/time item values can be grouped.  This collection is initialized as specified by the following properties:

•	the View’s DateTimeHandling.Grouping property;

•	an item’s DateTimeGrouping property.

The initialization is carried out using the Init method.  You can handle the OnInitGroupingDateRanges events for a View and an item to customize these collections.

Use an item’s GroupingDateRanges property to access a collection of grouping date ranges created for this item.


TcxGridGroupingDateRanges Hierarchy
Hierarchy

TObject

     |

TcxGridDateRanges

     |

TcxGridGroupingDateRanges


Properties for TcxGridGroupingDateRanges
TcxGridGroupingDateRanges Properties

TcxGridGroupingDateRanges          Legend

Derived from TcxGridDateRanges

Count

DateTimeHandling

Items

StartOfThisWeek

ThisDay

ThisMonth

ThisMonthNumber

ThisYear

Today


Methods for TcxGridGroupingDateRanges
TcxGridGroupingDateRanges Methods

TcxGridGroupingDateRanges          Legend

In TcxGridGroupingDateRanges

Init

Derived from TcxGridDateRanges

Add

Clear

GetRange

Init

IsEmpty

NeedSortingByTime

NeedTime


TcxGridGroupingDateRanges.Init

TcxGridGroupingDateRanges          See Also

Initializes the collection of grouping date ranges with settings required for date ranges to group date/time item values.

type

  TcxGridDateTimeGrouping = (dtgDefault, dtgByDateAndTime, dtgRelativeToToday, dtgByHour, dtgByDate, dtgByMonth, dtgByYear);

procedure Init(ADateTimeHandling: TcxCustomGridTableDateTimeHandling; ADateTimeGrouping: TcxGridDateTimeGrouping); reintroduce; virtual;

Description

The Init method functions in the same manner as its ancestor method and also overloads it with a set of date/time grouping conditions passed as the ADateTimeGrouping parameter.  This set determines which of the date ranges should be included into the collection and populates accordingly the Items zero-based indexed collection.

Handle the OnInitGroupingDateRanges event to customize the collection of grouping date ranges.


TcxGridDayRange
TcxGridDayRange Object

Hierarchy          Properties          Methods          See Also

Represents a one-day range.

Unit

cxGridCustomTableView

TcxGridDayRange = class(TcxCustomGridDateRange)

Description

This date range creates one-day periods for date/time item values.

To add this date range to an item’s GroupingDateRanges collection, assign dtgByDate to the View’s DateTimeHandling.Grouping property or the item’s DateTimeGrouping property.


TcxGridDayRange Hierarchy
Hierarchy

TObject

     |

TcxCustomGridDateRange

     |

TcxGridDayRange


Properties for TcxGridDayRange
TcxGridDayRange Properties

TcxGridDayRange          Legend

Derived from TcxCustomGridDateRange

Container

Index


Methods for TcxGridDayRange
TcxGridDayRange Methods

TcxGridDayRange          Legend

Derived from TcxCustomGridDateRange

Contains

GetDisplayText

GetRangeValue

GetSortingValue

GetValue

NeedsSortingByTime

NeedsTime


TcxGridHourRange
TcxGridHourRange Object

Hierarchy          Properties          Methods          See Also

Represents a one-hour range.

Unit

cxGridCustomTableView

TcxGridHourRange = class(TcxCustomGridDateRange)

Description

This date range creates one-hour periods for date/time item values.

To add this date range to an item’s DateTimeGrouping property, assign dtgByHour to the view’s DateTimeHandling.Grouping property or the item’s DateTimeGrouping property.


TcxGridHourRange Hierarchy
Hierarchy

TObject

     |

TcxCustomGridDateRange

     |

TcxGridHourRange


Properties for TcxGridHourRange
TcxGridHourRange Properties

TcxGridHourRange          Legend

Derived from TcxCustomGridDateRange

Container

Index


Methods for TcxGridHourRange
TcxGridHourRange Methods

TcxGridHourRange          Legend

Derived from TcxCustomGridDateRange

Contains

GetDisplayText

GetRangeValue

GetSortingValue

GetValue

NeedsSortingByTime

NeedsTime


TcxGridLastMonthRange
TcxGridLastMonthRange Object

Hierarchy          Properties          Methods          See Also

Represents a date range associated with the last month period.

Unit

cxGridCustomTableView

TcxGridLastMonthRange = class(TcxCustomGridDateRange)

Description

This date range creates the last month period for date/time item values.

To add this date range to an item’s GroupingDateRanges collection, assign dtgRelativeToToday to the View’s DateTimeHandling.Grouping property or the item’s DateTimeGrouping property.


TcxGridLastMonthRange Hierarchy
Hierarchy

TObject

     |

TcxCustomGridDateRange

     |

TcxGridLastMonthRange


Properties for TcxGridLastMonthRange
TcxGridLastMonthRange Properties

TcxGridLastMonthRange          Legend

Derived from TcxCustomGridDateRange

Container

Index


Methods for TcxGridLastMonthRange
TcxGridLastMonthRange Methods

TcxGridLastMonthRange          Legend

Derived from TcxCustomGridDateRange

Contains

GetDisplayText

GetRangeValue

GetSortingValue

GetValue

NeedsSortingByTime

NeedsTime


TcxGridLastWeekRange
TcxGridLastWeekRange Object

Hierarchy          Properties          Methods          See Also

Represents a date range associated with the last week period.

Unit

cxGridCustomTableView

TcxGridLastWeekRange = class(TcxCustomGridDateRange)

Description

This date range creates the last week period for date/time item values.

To add this date range to an item’s GroupingDateRanges collection, assign dtgRelativeToToday to the View’s DateTimeHandling.Grouping property or the item’s DateTimeGrouping property.


TcxGridLastWeekRange Hierarchy
Hierarchy

TObject

     |

TcxCustomGridDateRange

     |

TcxGridLastWeekRange


Properties for TcxGridLastWeekRange
TcxGridLastWeekRange Properties

TcxGridLastWeekRange          Legend

Derived from TcxCustomGridDateRange

Container

Index


Methods for TcxGridLastWeekRange
TcxGridLastWeekRange Methods

TcxGridLastWeekRange          Legend

Derived from TcxCustomGridDateRange

Contains

GetDisplayText

GetRangeValue

GetSortingValue

GetValue

NeedsSortingByTime

NeedsTime


TcxGridLastYearRange
TcxGridLastYearRange Object

Hierarchy          Properties          Methods          See Also

Represents a date range associated with the last year period.

Unit

cxGridCustomTableView

TcxGridLastYearRange = class(TcxCustomGridDateRange)

Description

This date range creates the last year period for date/time item values.

To add this date range to an item’s GroupingDateRanges collection, assign dtgRelativeToToday to the View’s DateTimeHandling.Grouping property or the item’s DateTimeGrouping property.


TcxGridLastYearRange Hierarchy
Hierarchy

TObject

     |

TcxCustomGridDateRange

     |

TcxGridLastYearRange


Properties for TcxGridLastYearRange
TcxGridLastYearRange Properties

TcxGridLastYearRange          Legend

Derived from TcxCustomGridDateRange

Container

Index


Methods for TcxGridLastYearRange
TcxGridLastYearRange Methods

TcxGridLastYearRange          Legend

Derived from TcxCustomGridDateRange

Contains

GetDisplayText

GetRangeValue

GetSortingValue

GetValue

NeedsSortingByTime

NeedsTime


TcxGridMonthRange
TcxGridMonthRange Object

Hierarchy          Properties          Methods          See Also

Represents a one-month range.

Unit

cxGridCustomTableView

TcxGridMonthRange = class(TcxCustomGridDateRange)

Description

This date range creates one-month periods for date/time item values.

To add this date range to an item’s GroupingDateRanges or FilteringDateRanges collection, assign dtgByMonth to the View’s DateTimeHandling.Grouping property or the item’s DateTimeGrouping property.

To add this date range to an item’s FilteringDateRanges collection, turn on the dtfMonths option via the View’s DateTimeHandling.Filters property.


TcxGridMonthRange Hierarchy
Hierarchy

TObject

     |

TcxCustomGridDateRange

     |

TcxGridMonthRange


Properties for TcxGridMonthRange
TcxGridMonthRange Properties

TcxGridMonthRange          Legend

Derived from TcxCustomGridDateRange

Container

Index


Methods for TcxGridMonthRange
TcxGridMonthRange Methods

TcxGridMonthRange          Legend

Derived from TcxCustomGridDateRange

Contains

GetDisplayText

GetRangeValue

GetSortingValue

GetValue

NeedsSortingByTime

NeedsTime


TcxGridNextMonthRange
TcxGridNextMonthRange Object

Hierarchy          Properties          Methods          See Also

Represents a date range associated with the next month period.

Unit

cxGridCustomTableView

TcxGridNextMonthRange = class(TcxCustomGridDateRange)

Description

This date range creates the next month period for date/time item values.

To add this date range to an item’s GroupingDateRanges collection, assign dtgRelativeToToday to the View’s DateTimeHandling.Grouping property or the item’s DateTimeGrouping property.


TcxGridNextMonthRange Hierarchy
Hierarchy

TObject

     |

TcxCustomGridDateRange

     |

TcxGridNextMonthRange


Properties for TcxGridNextMonthRange
TcxGridNextMonthRange Properties

TcxGridNextMonthRange          Legend

Derived from TcxCustomGridDateRange

Container

Index


Methods for TcxGridNextMonthRange
TcxGridNextMonthRange Methods

TcxGridNextMonthRange          Legend

Derived from TcxCustomGridDateRange

Contains

GetDisplayText

GetRangeValue

GetSortingValue

GetValue

NeedsSortingByTime

NeedsTime


TcxGridNextWeekRange
TcxGridNextWeekRange Object

Hierarchy          Properties          Methods          See Also

Represents a date range associated with the next week period.

Unit

cxGridCustomTableView

TcxGridNextWeekRange = class(TcxCustomGridDateRange)

Description

This date range creates the next week period for date/time item values.

To add this date range to an item’s GroupingDateRanges collection, assign dtgRelativeToToday to the View’s DateTimeHandling.Grouping property or the item’s DateTimeGrouping property.


TcxGridNextWeekRange Hierarchy
Hierarchy

TObject

     |

TcxCustomGridDateRange

     |

TcxGridNextWeekRange


Properties for TcxGridNextWeekRange
TcxGridNextWeekRange Properties

TcxGridNextWeekRange          Legend

Derived from TcxCustomGridDateRange

Container

Index


Methods for TcxGridNextWeekRange
TcxGridNextWeekRange Methods

TcxGridNextWeekRange          Legend

Derived from TcxCustomGridDateRange

Contains

GetDisplayText

GetRangeValue

GetSortingValue

GetValue

NeedsSortingByTime

NeedsTime


TcxGridNextYearRange
TcxGridNextYearRange Object

Hierarchy          Properties          Methods          See Also

Represents a date range associated with the next year period.

Unit

cxGridCustomTableView

TcxGridNextYearRange = class(TcxCustomGridDateRange)

Description

This date range creates the next year period for date/time item values.

To add this date range to an item’s GroupingDateRanges collection, assign dtgRelativeToToday to the View’s DateTimeHandling.Grouping property or the item’s DateTimeGrouping property.


TcxGridNextYearRange Hierarchy
Hierarchy

TObject

     |

TcxCustomGridDateRange

     |

TcxGridNextYearRange


Properties for TcxGridNextYearRange
TcxGridNextYearRange Properties

TcxGridNextYearRange          Legend

Derived from TcxCustomGridDateRange

Container

Index


Methods for TcxGridNextYearRange
TcxGridNextYearRange Methods

TcxGridNextYearRange          Legend

Derived from TcxCustomGridDateRange

Contains

GetDisplayText

GetRangeValue

GetSortingValue

GetValue

NeedsSortingByTime

NeedsTime


TcxGridThisMonthRange
TcxGridThisMonthRange Object

Hierarchy          Properties          Methods          See Also

Represents a date range associated with the current month period.

Unit

cxGridCustomTableView

TcxGridThisMonthRange = class(TcxCustomGridDateRange)

Description

This date range creates the current month period for date/time item values.

To add this date range to an item’s GroupingDateRanges collection, assign dtgRelativeToToday to the View’s DateTimeHandling.Grouping property or the item’s DateTimeGrouping property.


TcxGridThisMonthRange Hierarchy
Hierarchy

TObject

     |

TcxCustomGridDateRange

     |

TcxGridThisMonthRange


Properties for TcxGridThisMonthRange
TcxGridThisMonthRange Properties

TcxGridThisMonthRange          Legend

Derived from TcxCustomGridDateRange

Container

Index


Methods for TcxGridThisMonthRange
TcxGridThisMonthRange Methods

TcxGridThisMonthRange          Legend

Derived from TcxCustomGridDateRange

Contains

GetDisplayText

GetRangeValue

GetSortingValue

GetValue

NeedsSortingByTime

NeedsTime


TcxGridThisWeekRange
TcxGridThisWeekRange Object

Hierarchy          Properties          Methods          See Also

Represents a date range associated with the current week period.

Unit

cxGridCustomTableView

TcxGridThisWeekRange = class(TcxCustomGridDateRange)

Description

This date range creates the current week period for date/time item values.

To add this date range to an item’s GroupingDateRanges collection, assign dtgRelativeToToday to the View’s DateTimeHandling.Grouping property or the item’s DateTimeGrouping property.


TcxGridThisWeekRange Hierarchy
Hierarchy

TObject

     |

TcxCustomGridDateRange

     |

TcxGridThisWeekRange


Properties for TcxGridThisWeekRange
TcxGridThisWeekRange Properties

TcxGridThisWeekRange          Legend

Derived from TcxCustomGridDateRange

Container

Index


Methods for TcxGridThisWeekRange
TcxGridThisWeekRange Methods

TcxGridThisWeekRange          Legend

Derived from TcxCustomGridDateRange

Contains

GetDisplayText

GetRangeValue

GetSortingValue

GetValue

NeedsSortingByTime

NeedsTime


TcxGridThisYearRange
TcxGridThisYearRange Object

Hierarchy          Properties          Methods          See Also

Represents a date range associated with the current year period.

Unit

cxGridCustomTableView

TcxGridThisYearRange = class(TcxCustomGridDateRange)

Description

This date range creates the current year period for date/time item values.

To add this date range to an item’s GroupingDateRanges collection, assign dtgRelativeToToday to the View’s DateTimeHandling.Grouping property or the item’s DateTimeGrouping property.


TcxGridThisYearRange Hierarchy
Hierarchy

TObject

     |

TcxCustomGridDateRange

     |

TcxGridThisYearRange


Properties for TcxGridThisYearRange
TcxGridThisYearRange Properties

TcxGridThisYearRange          Legend

Derived from TcxCustomGridDateRange

Container

Index


Methods for TcxGridThisYearRange
TcxGridThisYearRange Methods

TcxGridThisYearRange          Legend

Derived from TcxCustomGridDateRange

Contains

GetDisplayText

GetRangeValue

GetSortingValue

GetValue

NeedsSortingByTime

NeedsTime


TcxGridTodayRange
TcxGridTodayRange Object

Hierarchy          Properties          Methods          See Also

Represents a date range associated with this day.

Unit

cxGridCustomTableView

TcxGridTodayRange = class(TcxCustomGridDateRange)

Description

This date range creates the period of this day for date/time item values.

To add this date range to an item’s GroupingDateRanges collection, assign dtgRelativeToToday to the View’s DateTimeHandling.Grouping property or the item’s DateTimeGrouping property.


TcxGridTodayRange Hierarchy
Hierarchy

TObject

     |

TcxCustomGridDateRange

     |

TcxGridTodayRange


Properties for TcxGridTodayRange
TcxGridTodayRange Properties

TcxGridTodayRange          Legend

Derived from TcxCustomGridDateRange

Container

Index


Methods for TcxGridTodayRange
TcxGridTodayRange Methods

TcxGridTodayRange          Legend

Derived from TcxCustomGridDateRange

Contains

GetDisplayText

GetRangeValue

GetSortingValue

GetValue

NeedsSortingByTime

NeedsTime


TcxGridTomorrowRange
TcxGridTomorrowRange Object

Hierarchy          Properties          Methods          See Also

Represents a date range associated with tomorrow.

Unit

cxGridCustomTableView

TcxGridTomorrowRange = class(TcxCustomGridDateRange)

Description

This date range creates the period of the day after today for date/time item values.

To add this date range to an item’s GroupingDateRanges collection, assign dtgRelativeToToday to the View’s DateTimeHandling.Grouping property or the item’s DateTimeGrouping property.


TcxGridTomorrowRange Hierarchy
Hierarchy

TObject

     |

TcxCustomGridDateRange

     |

TcxGridTomorrowRange


Properties for TcxGridTomorrowRange
TcxGridTomorrowRange Properties

TcxGridTomorrowRange          Legend

Derived from TcxCustomGridDateRange

Container

Index


Methods for TcxGridTomorrowRange
TcxGridTomorrowRange Methods

TcxGridTomorrowRange          Legend

Derived from TcxCustomGridDateRange

Contains

GetDisplayText

GetRangeValue

GetSortingValue

GetValue

NeedsSortingByTime

NeedsTime


TcxGridYearRange
TcxGridYearRange Object

Hierarchy          Properties          Methods          See Also

Represents a one-year range.

Unit

cxGridCustomTableView

TcxGridYearRange = class(TcxCustomGridDateRange)

Description

This date range creates one-year periods for date/time item values.

To add this date range to an item’s GroupingDateRanges or FilteringDateRanges collection, assign dtgByYear to the View’s DateTimeHandling.Grouping property or the item’s DateTimeGrouping property.

To add this date range to an item’s FilteringDateRanges collection, turn on the dtfYears option via the View’s DateTimeHandling.Filters property.


TcxGridYearRange Hierarchy
Hierarchy

TObject

     |

TcxCustomGridDateRange

     |

TcxGridYearRange


Properties for TcxGridYearRange
TcxGridYearRange Properties

TcxGridYearRange          Legend

Derived from TcxCustomGridDateRange

Container

Index


Methods for TcxGridYearRange
TcxGridYearRange Methods

TcxGridYearRange          Legend

Derived from TcxCustomGridDateRange

Contains

GetDisplayText

GetRangeValue

GetSortingValue

GetValue

NeedsSortingByTime

NeedsTime


TcxGridYesterdayRange
TcxGridYesterdayRange Object

Hierarchy          Properties          Methods          See Also

Represents a date range associated with yesterday.

Unit

cxGridCustomTableView

TcxGridYesterdayRange = class(TcxCustomGridDateRange)

Description

This date range creates the period of the day before today for date/time item values.

To add this date range to an item’s GroupingDateRanges collection, assign dtgRelativeToToday to the View’s DateTimeHandling.Grouping property or the item’s DateTimeGrouping property.


TcxGridYesterdayRange Hierarchy
Hierarchy

TObject

     |

TcxCustomGridDateRange

     |

TcxGridYesterdayRange


Properties for TcxGridYesterdayRange
TcxGridYesterdayRange Properties

TcxGridYesterdayRange          Legend

Derived from TcxCustomGridDateRange

Container

Index


Methods for TcxGridYesterdayRange
TcxGridYesterdayRange Methods

TcxGridYesterdayRange          Legend

Derived from TcxCustomGridDateRange

Contains

GetDisplayText

GetRangeValue

GetSortingValue

GetValue

NeedsSortingByTime

NeedsTime


TcxGridQuickCustomizationReordering
TcxGridQuickCustomizationReordering type

See Also

Enumerates options that control the end-user ability to reorder columns and bands by dragging their names in the Quick Column Customization dropdown and Quick Band Customization dropdown.

Unit

cxGridCustomTableView

type

  TcxGridQuickCustomizationReordering = (qcrDefault, qcrEnabled, qcrDisabled);

Description

To specify these options, use the View’s OptionsCustomize.ColumnsQuickCustomizationReordering and OptionsCustomize.BandsQuickCustomizationReordering properties.

All the available options are listed in the following table.

Value	Meaning
qcrDefault	End-users can drag columns/bands in the corresponding dropdown provided that the View’s OptionsCustomize.ColumnMoving or OptionsCustomize.BandMoving property is set to True.
qcrEnabled	End-users can drag columns/bands in the corresponding dropdown regardless of the settings specifies by the View’s OptionsCustomize.ColumnMoving and OptionsCustomize.BandMoving properties.
qcrDisabled	End-users cannot drag columns/bands in these dropdowns.


TcxCustomGridRecord
TcxCustomGridRecord Object

Hierarchy          Properties          Methods          See Also

Represents the base class for records in a view.

Unit

cxGridCustomTableView

TcxCustomGridRecord = class(TObject);

Description

TcxCustomGridRecord is the base class representing a single record displayed within a view.  Records can be accessed via the view’s ViewData object and this provides the Records collection (Cards in TcxGridCardViewViewData and Rows in TcxGridViewData).  Records retrieve information from a data controller assigned to the view but do not implement posting data back.  To change cell values in bound mode, use the methods of the TDataSet object.  In unbound mode, use the view’s DataController.Values property for this purpose.

A ViewData object reflects the current visual arrangement of records.  It contains only the records actually displayed within a view.  If record(s) are hidden within collapsed groups, they are not contained in the Records collection.

There are several types of records in a view.  They are all descendants of the TcxCustomGridRecord class.

•	a card (TcxGridCard) – represents a record in a card view.

•	a grid group row (TcxGridGroupRow) is a row displaying a value of an item (column) by which data is grouped. It can display group summaries, if any.

•	a grid data row (TcxGridDataRow) displaying the actual data

•	a grid master data row (TcxGridMasterDataRow) is a data (non-group) row in a master view

•	a new item row (TcxGridNewItemRow) represents a row for entering new data

Using members of the TcxCustomGridRecord class, you can:

•	access values of specific record fields;

•	determine the index, record index, and level of the record;

•	set focus to a record within a view;

•	expand the record (only for master and group rows);

•	etc.

TcxCustomGridRecord introduces base functionality common to all types of records.  First, a record is identified by its position.  The order in which records are retrieved from the data controller is determined by the record index.  Record indexes are not affected by sorting or grouping of data.  They always refer to the same data.  Unlike the record index, index defines the visible order of records within a view.

The following image shows a sample grid control with five records retrieved from the data without doing anything to change the display order.  Indexes and record indexes have the same values for every record.

When records are grouped by BirthCountry and sorted by the FirstName column in descending order, only the visual record order changes.  Index identifies the current visual position while the record index keeps its original value.

Every record displays values.  A data row, master data row and a card display values corresponding to data items (columns in a table view or rows in a card view).  A group row displays a value of the item (column) by which the view data is grouped.  The values presented by the record are defined by the Values property.  You can access the text version of a value via the DisplayTexts property.

When you group data, a hierarchical structure of records is created.  In this case, group records of the TcxGridGroupRow class are created.  The group level (the Level property) identifies the position of a record in this hierarchy.


TcxCustomGridRecord Hierarchy
Hierarchy

TObject

     |


Properties for TcxCustomGridRecord
TcxCustomGridRecord Properties

TcxCustomGridRecord          Legend

In TcxCustomGridRecord

DisplayTexts

Expandable

Expanded

Focused

HasCells

GridView

Index

IsData

IsEditing

IsFirst

IsLast

IsNewItemRecord

IsParentRecordLast

LastParentRecordCount

Level

ParentRecord

RecordIndex

Selected

ValueCount

Values

ViewData

Visible


Methods for TcxCustomGridRecord
TcxCustomGridRecord Methods

TcxCustomGridRecord          Legend

In TcxCustomGridRecord

CanFocus

Collapse

Expand

GetFirstFocusableChild

GetLastFocusableChild

Invalidate

MakeVisible


TcxCustomGridRecord.DisplayTexts

TcxCustomGridRecord          See Also

Provides indexed access to the text version of a field's value, in the current record.

property DisplayTexts[Index: Integer]: string;

Description

Use the DisplayTexts property to retrieve or set the text representation of the value stored in the field addressed by the Index parameter.  The Index parameter identifies the position of the corresponding item within the view’s Items collection.  You can obtain the item’s index by using the CustomGridTableItem.Index property.

Values and their text representations are retrieved from the data controller.  The number of field values is determined by the ValueCount property.  To retrieve or set actual values instead of text, see the Values property.

Note:	Although you are able to set the text version of a specific item’s value, use this ability for unbound views only.  In order to set the texts to display for data-aware views, use the appropriate methods of the underlying data set instead.


TcxCustomGridRecord.Expandable

TcxCustomGridRecord          See Also

Gets whether the record can be expanded and/or collapsed.

property Expandable: Boolean;

Description

The Expandable property is used to determine whether the current record can be expanded and/or collapsed.  If it returns True, then the record can be successfully expanded and collapsed using the record’s Expand, Collapse methods and the Expanded property.  The Expandable property also determines whether the view’s ViewData.Expand and ViewData.Collapse methods will affect the record.  At last, if this property returns False, the view will not paint visual elements that allow end users to expand and collapse records.

As implemented in the TcxCustomGridRecord class, the Expandable property simply returns False.  This property’s actual value depends on the record type (TcxCustomGridRecord descendant).  The table below lists record classes that support expanding and collapsing and provides information on the Expandable property return value.

Record class	The Expandable property’s return value
TcxGridGroupRow	Returns True except for the case when the data controller’s dcoGroupsAlwaysExpanded option is enabled.
TcxGridMasterDataRow	Returns True if at least one of the following conditions is met: • The master row has detail rows; • The view’s OptionsView.ExpandButtonsForEmptyDetails option is enabled; • The master row is already expanded.
TcxGridCard	Returns True if the view’s OptionsCustomize.CardExpanding property value is True.

ReadOnly Property


TcxCustomGridRecord.Expanded

TcxCustomGridRecord          See Also

Specifies whether the record is expanded.

property Expanded: Boolean;

Description

Read the Expanded property value to determine whether the record is currently expanded.  Assign True to this property to expand the record or False to collapse it.  Note that changing a record’s expanded state using the Expanded property doesn’t produce a recursive effect.  For instance, expanding a record by setting its Expanded property to True will not expand this record’s child records.  If you need to expand or collapse records recursively, use the Expand and Collapse methods.

Please refer to the Expand method description for details on which records support expanding and collapsing operations.  Additionally, see the Expandable property description to find out when records can be expanded or collapsed.


TcxCustomGridRecord.Focused

TcxCustomGridRecord          See Also

Specifies whether the current record is focused.

property Focused: Boolean;

Description

Use the Focused property to specify whether the record is focused.  Set Focused to True to move the focus to the current record.  You can access the currently focused record via the view’s Controller.FocusedRecord property.


TcxCustomGridRecord.GridView

TcxCustomGridRecord          See Also

Returns the view, which owns the current record.

property GridView: TcxCustomGridTableView;

Description

The GridView property specifies the view, which owns the current record.  Grid views represent records in a specific form (table views represent records as rows; card views represent them as cards).  Using the GridView object’s properties you can, for instance, access a collection of items (fields) for which the record provides values.

To access the collection of records displayed within a view, see the view's ViewData.Records property.  It contains the records currently visible or potentially visible when scrolling.

ReadOnly Property


TcxCustomGridRecord.HasCells

TcxCustomGridRecord

Determines whether the current record has cells displaying values.

property HasCells: Boolean;

Description

Only data rows, including master rows and the new item row, have cells.  A group row does not have cells and so its HasCells property then returns False.

ReadOnly Property


TcxCustomGridRecord.Index

TcxCustomGridRecord          See Also

Returns the visual position of the record within a view.

property Index: Integer;

Description

When a record’s position is changed because of sorting or grouping, its Index property reflects the change, but the RecordIndex property preserves its original value.

ReadOnly Property


TcxCustomGridRecord.IsData

TcxCustomGridRecord          See Also

Determines whether the record displays data in cells.

property IsData: Boolean;

Description

For all data rows, including master rows and the new item row, this property returns True.  For group rows, False is returned.

ReadOnly Property


TcxCustomGridRecord.IsEditing

TcxCustomGridRecord          See Also

Determines whether the record is currently being edited (the data controller is in edit mode).

property IsEditing: Boolean;

Description

This property returns True when an end-user starts modifying the record and it is not yet posted, or presses the Insert key to add a new record.

ReadOnly Property


TcxCustomGridRecord.IsFirst

TcxCustomGridRecord

Determines whether the record is displayed at the first position within a view.

property IsFirst: Boolean;

Description

The IsFirst property returns True for the first record displayed within a view.  It uses the Index property to retrieve the position of the record within a view.  If Index returns a value other than 0, False is returned.

ReadOnly Property


TcxCustomGridRecord.IsLast

TcxCustomGridRecord

Determines whether the current record is located at the last position within a view.

property IsLast: Boolean;

Description

The IsLast property returns True for the last record displayed within a view. It uses the Index property to retrieve the position of the record within a view.  If Index returns a value other than ViewData.RecordCount – 1, False is returned.

ReadOnly Property


TcxCustomGridRecord.IsNewItemRecord

TcxCustomGridRecord          See Also

Determines whether the current record is a "new item record" within a view.

property IsNewItemRecord: Boolean;

Description

The IsNewItemRecord property returns True if the current record identifies a "new item record" (used to enter new data within a view).  A new item record is referenced by the ViewData.NewItemRecord property.  You can enable displaying the new item record (implemented only in a table view) by setting the view’s OptionsView.NewItemRow property to True.

ReadOnly Property


TcxCustomGridRecord.IsParentRecordLast

TcxCustomGridRecord          See Also

Determines whether a group footer that corresponds to a specific group level can be displayed under the current record.

property IsParentRecordLast[AIndex: Integer]: Boolean;

Description

Group footers are displayed under the last record of the corresponding groups.  The IsParentRecordLast property returns True for these records.

To determine whether the current record is the last in a group at a particular group level, pass the level’s index as the AIndex parameter.  This index is relative to the record’s level.  For instance, 0 corresponds to the record’s group level, 1 corresponds to the immediate parent group level and so on.

Consider the following sample grid control.

Within the context of the first group at level 0 (‘EXCHANGE : NONE’), the record with the Index of 2 is the last record in its group and the immediate parent group (whose relative indexes are 0 and 1, respectively).

Within the context of the second group at level 0 (‘EXCHANGE : NYSE’), the record with the Index of 5 is the last record in its group only (its relative index is 0), while the record with the Index of 9 is the last record in its group and the immediate parent group (whose relative indexes are 0 and 1, respectively).

The following image demonstrates the sample grid control with group footers enabled via the OptionsView.GroupFooters property.

Use the LastParentRecordCount property to determine the number of group levels for which the current record can display group footers.

ReadOnly Property


TcxCustomGridRecord.LastParentRecordCount

TcxCustomGridRecord          See Also

Returns the number of group levels for which the current record can display group footers.

property LastParentRecordCount: Integer;

Description

To determine whether the current record can display a group footer for a particular group level, use the IsParentRecordLast property.

ReadOnly Property


TcxCustomGridRecord.Level

TcxCustomGridRecord          See Also

Returns the group level of the current record.

property Level: Integer;

Description

Use the Level property to determine the group level of the current record within a view. When data is grouped by items (columns), a hierarchical structure of groups is created and data is displayed at different levels.  Grouping is implemented for grid table views only.

The following image shows a grid view with two group levels:

ReadOnly Property


TcxCustomGridRecord.ParentRecord

TcxCustomGridRecord          See Also           Example

Returns an immediate parent record for the current record.

property ParentRecord: TcxCustomGridRecord;

Description

The ParentRecord property allows you to return an immediate parent record for the current record.  This allows you to traverse through records from a nesting level to an upper level.  To traverse through all visible records in any direction, see the view’s ViewData.Records property.

Suppose that grouping is applied to a view and the current record represents a row at nesting level greater than 0, i.e. it has a parent row.  In this case, ParentRecord returns the appropriate grouping row at the preceding level.

Also, if a record is displayed at the first nesting level and it belongs to a detail clone, the ParentRecord property returns the master row associated with the detail.

If a record is displayed at the first nesting level and does not belong to a detail clone, ParentRecord returns NIL.

ReadOnly Property


TcxCustomGridRecord.RecordIndex

TcxCustomGridRecord          See Also

Specifies the record index of the current record.

property RecordIndex: Integer;

Description

A record index identifies the position of the current record within a dataset.  The Record index is not changed when the visual position of a record within a view is changed.  You can access the Index property to determine where the record is displayed within a view.

ReadOnly Property


TcxCustomGridRecord.Selected

TcxCustomGridRecord          See Also

Specifies whether the current record is selected.

property Selected: Boolean;

Description

Use the Selected property to select/unselect the current record.  When GridMode is not active, all record(s) currently selected can be accessed via the view’s Controller.SelectedRecords property.

When GridMode is applied to a data-aware view, you can obtain selected records via the view’s DataController.GetSelectedBookmark function.


TcxCustomGridRecord.ValueCount

TcxCustomGridRecord          See Also

Specifies the number of values corresponding to items (fields) in the current record.

property ValueCount: Integer;

Description

The ValueCount property returns the number of items (fields) for which the current record provides values via the indexed Values member.  In a (banded)table view this property specifies the number columns, in a card view it refers to the number of card view rows.

ReadOnly Property


TcxCustomGridRecord.Values

TcxCustomGridRecord          See Also

Provides indexed access to the values of items (fields) in a record.

property Values[Index: Integer]: Variant;

Description

The Values property allows you to read and write a value to a specific item (field) identified by the Index parameter in the current record.  The Index parameter identifies the position of the corresponding item within the view’s Items collection.  You can obtain the item’s index by using the TcxCustomGridTableItem.Index property.

The number of values corresponding to items is determined by the ValueCount property.  To return the text representation of a value, see the DisplayTexts property.

Note:	Although you are able to set the actual value of a specific item in a record, use this ability for unbound views only.  In order to set values for data-aware views, use the appropriate methods of the underlying data set instead.


TcxCustomGridRecord.ViewData

TcxCustomGridRecord

Returns the ViewData object owning the current record.

property ViewData: TcxCustomGridTableViewData;

Description

ViewData returns a reference to the object owning the collection of records including the current record.  Using ViewData, you can obtain a reference to a view displaying the record.

ReadOnly Property


TcxCustomGridRecord.Visible

TcxCustomGridRecord          See Also

Returns the visibility of the current record.

property Visible: Boolean;

Description

The Visible property returns True if the record is currently visible in the view.  If the record is hidden due to scrolling, False is returned.

ReadOnly Property


TcxCustomGridRecord.CanFocus

TcxCustomGridRecord          See Also

Determines whether the record can be focused.

function CanFocus: Boolean; virtual;

Description

This function returns True when the record can be focused.  Otherwise, False is returned.

By default, this function returns True unless the View’s OnCanFocusRecord event is handled to prohibit this record from being focused.

Set the Focused property to True to move the focus to the current record.


TcxCustomGridRecord.Collapse

TcxCustomGridRecord          See Also

Collapses the record.

procedure Collapse(ARecurse: Boolean);

Description

The Collapse method call provides the invert result as compared to the Expand method.  Please refer to the Expand method description for details.


TcxCustomGridRecord.Expand

TcxCustomGridRecord          See Also

Expands the record.

procedure Expand(ARecurse: Boolean);

Description

As implemented in the TcxCustomGridRecord class, calling the Expand method produces no effect.  This method’s behavior depends on the record type (TcxCustomGridRecord descendant).  The table below lists the record classes that can use this method and describes the corresponding method calling results.

Record class	The Expand method’s behavior
TcxGridGroupRow	Expands the group row making its child rows visible.  The ARecurse parameter specifies whether child group rows at all nesting levels should be expanded also.
TcxGridMasterDataRow	Expands the master row making its corresponding detail visible.  The ARecurse parameter specifies whether master rows within details at all nesting levels should be expanded also.
TcxGridCard	Expands the card.  The ARecurse parameter has no effect.

Calling a record’s Expand method passing False is equivalent to setting this record’s Expanded property to True.

Note that a record can only be expanded if its Expandable property returns True.  Please refer to this property description for details.


TcxCustomGridRecord.GetFirstFocusableChild

TcxCustomGridRecord          See Also

Returns the first child record for the current record.

function GetFirstFocusableChild: TcxCustomGridRecord; virtual;

Description

The method is in effect only for a master row (TcxGridMasterDataRow) which identifies a particular detail view clone (see the Data Representation topic for additional information on clones and patterns).  For other records NIL is returned.  GetFirstFocusableChild returns the first record in the associated active detail view which can be focused.

Note that if a detail is not opened for the master record, GetFirstFocusableChild returns NIL.


TcxCustomGridRecord.GetLastFocusableChild

TcxCustomGridRecord          See Also

Gets the last child record for the current record.

function GetLastFocusableChild(ARecursive: Boolean): TcxCustomGridRecord; virtual;

Description

The method is implemented only in a master row (TcxGridMasterDataRow) which identifies a particular detail view clone (see the Data Representation topic for additional information on clones and patterns).  For other records NIL is returned.  GetLastFocusableChild obtains a reference to the last record within the corresponding active detail view.  If ARecursive is True, then children of the last expanded detail row are taken into account.


TcxCustomGridRecord.Invalidate

TcxCustomGridRecord

Updates a record or a record cell.

procedure Invalidate(AItem: TcxCustomGridTableItem = nil); virtual;

Description

The Invalidate method can be used to update a record or a particular cell.  If the AItem parameter is NIL the whole record is invalidated.  Otherwise, only a cell corresponding to the table item referenced by the AItem parameter is redrawn.


TcxCustomGridRecord.MakeVisible

TcxCustomGridRecord          See Also

Makes the current record visible.

procedure MakeVisible;

Description

The MakeVisible method scrolls the view so that the current record becomes visible.  To ascertain whether the record is currently visible, see the Visible property.

A view does not provide access to records hidden within collapsed groups.  In order to display such records, call the Expand method for the appropriate group row.


cxGridCustomTableView Unit Overview
cxGridCustomTableView Unit

Classes

TcxCustomGridDateRange

TcxCustomGridRecord

TcxCustomGridRecordViewInfo

TcxCustomGridTableBackgroundBitmaps

TcxCustomGridTableDateTimeHandling

TcxCustomGridTableItem

TcxCustomGridTableItemOptions

TcxCustomGridTableItemStyles

TcxCustomGridTableOptionsBehavior

TcxCustomGridTableOptionsCustomize

TcxCustomGridTableOptionsData

TcxCustomGridTableOptionsSelection

TcxCustomGridTableOptionsView

TcxCustomGridTableView

TcxCustomGridTableViewData

TcxCustomGridTableViewStyles

TcxGridCustomizationFormHitTest

TcxGridDataController

TcxGridDayRange

TcxGridDateRanges

TcxGridExpandButtonHitTest

TcxGridFilterActivateButtonHitTest

TcxGridFilterBox

TcxGridFilterCloseButtonHitTest

TcxGridFilterCustomizeButtonHitTest

TcxGridFilterDropDownButtonHitTest

TcxGridFilteringDateRanges

TcxGridFilterValueList

TcxGridGroupingDateRanges

TcxGridHourRange

TcxGridItemDataBinding

TcxGridItemFilterPopupOptions

TcxGridLastMonthRange

TcxGridLastWeekRange

TcxGridLastYearRange

TcxGridMonthRange

TcxGridNextMonthRange

TcxGridNextWeekRange

TcxGridNextYearRange

TcxGridRecordCellHitTest

TcxGridRecordHitTest

TcxGridThisMonthRange

TcxGridThisWeekRange

TcxGridThisYearRange

TcxGridTodayRange

TcxGridTomorrowRange

TcxGridYearRange

TcxGridYesterdayRange

Other Types

TcxGridDateTimeFilter

TcxGridDateTimeFilters

TcxGridDateTimeGrouping

TcxGridItemFilterPopupApplyChangesMode

TcxGridQuickCustomizationReordering

TcxGridShowItemFilterButtons

TcxGridSortOrder

Global Constants

cxGridFilterDefaultItemPopupMaxDropDownItemCount


TcxCustomGridTableView
TcxCustomGridTableView Object

Hierarchy          Properties          Methods          Events          See Also

Represents the base class for all view classes implementing tabular data representation.

Unit

cxGridCustomTableView

TcxCustomGridTableView = class(TcxCustomGridView);

Description

The TcxCustomGridTableView object defines the basic functionality for the view classes implementing tabular data representation.  This representation requires view elements representing a table structure – columns and rows.  Since the tabular data can be implemented in two manners –card view and the table, "column" and "row" terms can change meaning from one view type to another.  In the TcxCustomGridTableView class, these terms are replaced by a more common one – "item".

All the items of the current view are stored within the Items collection.  A user can iterate items, and change their properties, etc.  The item properties enable or disable item-specific features which include grouping, sorting, filtering, defining the editor for the contents of the item’s cell, etc.  See the description of the TcxCustomGridTableItem class for details on these features.

The item position within a view is determined by the Item.GroupIndex and Item.VisibleIndex property values.  The Item.GroupIndex property defines the item's position among grouping items and the Item.VisibleIndex property defines the item's position within the view itself.  All visible items of the current view are stored within the VisibleItems collection.  The collection of grouped items can be accessed via the GroupedItems property.

The grid table view has several option sets which control different aspects of the view's behavior and appearance.  These sets include:

•	OptionsBehavior which contains settings that determine the view’s response to end-user actions;

•	OptionsCustomize which determine the availability of the customization options to end-users at runtime;

•	OptionsData which determines the functionality of a data-aware View;

•	OptionsSelection which contains settings that are to do with selections within a View;

•	OptionsView which contains appearance options for a View;

•	FilterBox which contains appearance options of the filter box within a View;

•	DateTimeHandling which contains settings to control the manner in which date/time values are handled within a View.

The view’s Styles property identifies the set of styles defining the appearance of different view elements.


TcxCustomGridTableView Hierarchy
Hierarchy

TComponent

     |

TcxControlChildComponent

     |

TcxCustomGridView

     |


Properties for TcxCustomGridTableView
TcxCustomGridTableView Properties

TcxCustomGridTableView          Legend

In TcxCustomGridTableView

Control

Controller

DataController

DateTimeHandling

FilterBox

GroupedItemCount

GroupedItems

ItemCount

Items

MasterGridRecord

NavigatorButtons

OptionsBehavior

OptionsCustomize

OptionsData

OptionsSelection

OptionsView

SortedItemCount

SortedItems

Styles

ViewData

VisibleItemCount

VisibleItems

Derived from TcxCustomGridView

CloneCount

Clones

Controller

DataController

DragMode

Focused

IsControlFocused

IsDetail

IsMaster

IsPattern

Level

MasterGridRecordIndex

MasterGridView

MasterRecordIndex

OptionsSelection

OptionsView

PatternGridView

Site

Styles

ViewData

ViewInfo

Visible

Derived from TcxControlChildComponent

Control

IsDestroying

IsLoading


Methods for TcxCustomGridTableView
TcxCustomGridTableView Methods

TcxCustomGridTableView          Legend

In TcxCustomGridTableView

ApplyBestFit

ClearItems

CopyToClipboard

CreateItem

FindItemByID

FindItemByName

FindItemByTag

IndexOfItem

MakeMasterGridRecordVisible

RestoreDefaults

Derived from TcxCustomGridView

BeginUpdate

CancelUpdate

EndUpdate

GetHitTest

LayoutChanged

RestoreDefaults

RestoreFromIniFile

RestoreFromRegistry

RestoreFromStream

SizeChanged

StoreToIniFile

StoreToRegistry

StoreToStream

ViewChanged

Derived from TcxControlChildComponent

CreateEx

Destroy


Events for TcxCustomGridTableView
TcxCustomGridTableView Events

TcxCustomGridTableView          Legend

In TcxCustomGridTableView

OnCanFocusRecord

OnCanSelectRecord

OnCellClick

OnCellDblClick

OnCustomDrawCell

OnCustomDrawPartBackground

OnCustomization

OnEditChanged

OnEditing

OnEditValueChanged

OnFilterControlDialogShow

OnFilterCustomization

OnFilterDialogShow

OnFocusedItemChanged

OnFocusedRecordChanged

OnGetCellHeight

OnGetDragDropText

OnInitEdit

OnInitEditValue

OnInitFilteringDateRanges

OnInitGroupingDateRanges

OnSelectionChanged

OnTopRecordIndexChanged

Derived from TcxCustomGridView

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnGetStoredProperties

OnGetStoredPropertyValue

OnInitStoredObject

OnMouseDown

OnMouseEnter

OnMouseLeave

OnMouseUp

OnSetStoredPropertyValue

OnStartDrag


TcxCustomGridTableView.Control

TcxCustomGridTableView

Returns the grid control owning the current view.

property Control: TcxCustomGrid;

Description

The Control property returns the grid control which owns the current view.

ReadOnly Property


TcxCustomGridTableView.Controller

TcxCustomGridTableView

Determines the controller for the current view.

property Controller: TcxCustomGridTableController;

Description

Use the Controller property to access the view’s controller functionality.  It enables you to

-	control the editing of a record cell

-	set focus to a specific item (column in a table view or card in a card view) and record

-	start/cancel an incremental search

-	access the collection of selected records

-	perform scrolling

-	navigate records and items

The TcxCustomGridTableController class provides properties and members common to both (banded) table and card views.

ReadOnly Property


TcxCustomGridTableView.DataController

TcxCustomGridTableView

Identifies the data controller managing the current view’s data.

property DataController: TcxGridDataController;

Description

Use the DataController property to access the object managing the grid view's connection to a data store.  A data controller object implements the retrieval and posting of data, applies grouping, filtering, and calculates summaries.


TcxCustomGridTableView.DateTimeHandling

TcxCustomGridTableView          See Also

Provides a set of options to control the manner in which date/time values are handled in the current view.

property DateTimeHandling: TcxCustomGridTableDateTimeHandling;

Description

Use this property to access settings that determine the manner in which items (columns or card rows) that display date/time values are filtered or grouped and how their values are displayed when filtering or grouping is applied.  Refer to the description of the TcxCustomGridTableDateTimeHandling class for details on available options.


TcxCustomGridTableView.FilterBox

TcxCustomGridTableView

Contains settings that determine the appearance aspects of the grid view’s filter box.

property FilterBox: TcxGridFilterBox;

Description

Use the FilterBox property to access the settings that determine the various appearance aspects of the grid view’s filter box (such as its general appearance, position, the availability of the filter customization button, etc.).


TcxCustomGridTableView.GroupedItemCount

TcxCustomGridTableView          See Also

Returns the number of grouping items within the current view.

property GroupedItemCount: Integer;

Description

Use the GroupedItemCount property to obtain the number of grouping items within the current view.  All grouping items within a view are stored in the GroupedItems collection.  Grouping can be performed by end-users and via code.  An end-user can group a view by clicking and dragging items to the group panel of the current view.  In code, this can be done by setting the Item.GroupIndex property to a value greater than –1.

ReadOnly Property


TcxCustomGridTableView.GroupedItems

TcxCustomGridTableView          See Also

Represents a collection of grouping items within the current view.

property GroupedItems[Index: Integer]: TcxCustomGridTableItem;

Description

Use the GroupedItems property to gain access to the collection of grouping items within the current view.  In order to add an item to the GroupedItems collection programmatically, set the Item.GroupIndex property to a value greater than –1.  At runtime, the current view is grouped by specific item's values.

ReadOnly Property


TcxCustomGridTableView.ItemCount

TcxCustomGridTableView          See Also

Returns the total number of items within the current view.

property ItemCount: Integer;

Description

Use the ItemCount property to obtain the total number of items within the current view.  All items contained within the current view are stored within the Items collection.

ReadOnly Property


TcxCustomGridTableView.Items

TcxCustomGridTableView          See Also

Provides indexed access to the current view’s items.

property Items[Index: Integer]: TcxCustomGridTableItem;

Description

Use the Items property to gain indexed access to the items (columns for the table and banded table views or card view rows for card view) displayed within the current view.  Each grid view item is an instance of the TcxCustomGridTableItem class.  This class defines the functionality for the basic element of the tabular data representation.

A user can work with the properties of a specific item to enable or disable item-specific features.  These features include grouping, sorting, filtering, defining the editor for the item cell contents, data binding settings etc.  See the TcxCustomGridTableItem class description for details.


TcxCustomGridTableView.MasterGridRecord

TcxCustomGridTableView          See Also

Returns the master view record displaying the current view as a detail.

property MasterGridRecord: TcxCustomGridRecord;

Description

Use the MasterGridRecord property to access the record within a master view displaying the current view as a detail.  The visible position of this record within the master view is identified by the MasterGridRecordIndex property.

If the current view is not a detail, this property returns NIL.

ReadOnly Property


TcxCustomGridTableView.NavigatorButtons

TcxCustomGridTableView          See Also

Provides access to the view navigator’s settings.

property NavigatorButtons: TcxNavigatorControlButtons;

Description

If a view’s OptionsView.Navigator property value is True, the view displays the navigator at its bottom.  You can customize this navigator’s settings using the NavigatorButtons property.  This property provides access to the TcxNavigatorControlButtons object that allows you to customize the visible and enabled state of buttons, specify hints and images for them, etc.


TcxCustomGridTableView.OptionsBehavior

TcxCustomGridTableView

Contains settings that determine the grid view’s response to user actions.

property OptionsBehavior: TcxCustomGridTableOptionsBehavior;

Description

Use the OptionsBehavior property to access the settings that determine the grid view’s response to end-user actions via the mouse and keyboard.  These property settings determine whether cell editors are always active and whether focus can be moved using the Tab & Enter keys, etc.


TcxCustomGridTableView.OptionsCustomize

TcxCustomGridTableView

Contains settings that determine the availability of runtime operations on the view’s items.

property OptionsCustomize: TcxCustomGridTableOptionsCustomize;

Description

Use the OptionsCustomize property to access settings that determine the availability of runtime operations on view items.  These operations include moving, grouping and sorting.  All these features can be implemented programmatically, using the properties of view items.  The customization options control the availability of these features to end-users.  That means, if grouping is not available for the end-user (the corresponding option is deactivated), then a view can still be grouped via setting the GroupIndex property value of the required view items.


TcxCustomGridTableView.OptionsData

TcxCustomGridTableView

Contains settings that determine the functionality of a data-aware view.

property OptionsData: TcxCustomGridTableOptionsData;

Description

Use the OptionsData property to determine which actions can be performed for the data set which provides records for the current view.  These actions include inserting, appending, editing and deleting records.  The data options also indicate whether confirmation is required before record deletion and whether empty records can be posted into a data set.


TcxCustomGridTableView.OptionsSelection

TcxCustomGridTableView

Contains settings that affect the selection within a view.

property OptionsSelection: TcxCustomGridTableOptionsSelection;

Description

Use the OptionsSelection property to determine the selection options for a view.  These options indicate whether to select individual cells or a whole row, whether the focus rectangle is displayed around the focused row and whether multiple rows can be selected, etc.


TcxCustomGridTableView.OptionsView

TcxCustomGridTableView

Contains settings that determine the view appearance.

property OptionsView: TcxCustomGridTableOptionsView;

Description

Use the OptionsView property to access settings that determine the view's appearance.  These options specify the visibility of editor buttons and whether the item captions & cells are automatically enlarged to display their full contents.


TcxCustomGridTableView.SortedItemCount

TcxCustomGridTableView          See Also

Returns the total number of sorted items within the current view.

property SortedItemCount: Integer;

Description

Use the SortedItemCount property to obtain the total number of sorted items within the current view.  A user can access all sorted items within a view via the SortedItems property.  The sort order for an item is defined via the Item.SortOrder property's value.  The SortedItemCount property returns the number of items whose SortOrder property value is not soNone.

ReadOnly Property


TcxCustomGridTableView.SortedItems

TcxCustomGridTableView          See Also

Provides indexed access to the sorted items within a view.

property SortedItems[Index: Integer]: TcxCustomGridTableItem;

Description

Use the SortedItems property to gain indexed access to sorted items within a view.  The item sort order is defined via the Item.SortOrder property's value.  Set this property to a value other than soNone to enable sorting by that item’s values (in this case the SortedItemCount property value increases by 1).  If the SortOrder property value of a sorted item changes to soNone, the item is removed from the sorted items list and the SortedItemCount property value decreases by 1.

ReadOnly Property


TcxCustomGridTableView.Styles

TcxCustomGridTableView         See Also

Specifies the set of styles defining the appearance of the current view elements.

property Styles: TcxCustomGridTableViewStyles;

Description

Use the Styles property to gain access to the set of styles defining the appearance of the current view elements.  This set is expanded when the Styles property is redefined by the TcxCustomGridView descendants.  In the base class, the Styles set includes a style defining the appearance of the current view background.  In this class, the style collection contains styles for the cell contents, selection bar and other view elements.


TcxCustomGridTableView.ViewData

TcxCustomGridTableView

Identifies an object that adapts the values provided by a data controller for grid view data representation.

property ViewData: TcxCustomGridTableViewData;

Description

Use the ViewData property to access an object adapting values provided by a data controller for displaying within a grid view.  This property refers to an instance of the TcxCustomGridTableViewData class.  Members of this class provide access to the records currently visible within a view.  They also allow navigation between view records, expanding group rows and access to the new item row, etc.

ReadOnly Property


TcxCustomGridTableView.VisibleItemCount

TcxCustomGridTableView          See Also

Returns the total number of items visible within the current view.

property VisibleItemCount: Integer;

Description

Use the VisibleItemCount property to obtain the total number of items visible within the current view.  An item’s visibility is determined using the Item.Visible property.

ReadOnly Property


TcxCustomGridTableView.VisibleItems

TcxCustomGridTableView          See Also

Provides indexed access to the currently visible items within a view.

property VisibleItems[Index: Integer]: TcxCustomGridTableItem;

Description

Use the VisibleItems property to gain indexed access to the currently visible items within a view.  The item’s position within a view corresponds to the item position within the VisibleItems collection.  The item’s visibility is determined via the Item.Visible property.

ReadOnly Property


TcxCustomGridTableView.ApplyBestFit

TcxCustomGridTableView          See Also

Adjusts the width of the current view items in order to display their full contents.

procedure ApplyBestFit(AItem: TcxCustomGridTableItem = nil; ACheckSizingAbility: Boolean = False; AFireEvents: Boolean = False); virtual;

Description

Use the ApplyBestFit method to adjust the width of all the current view items (columns) in order to display their full contents.  If the AItem parameter is specified, then this method works in a similar manner to the Item.ApplyBestFit method.  Otherwise, it affects all the items that are visible within the current view.  The ACheckSizingAbility parameter specifies whether it’s necessary to check if the items can be resized prior to adjusting their widths.  Set the ACheckSizingAbility parameter to True to specify that the widths of the items can only be adjusted if resizing is permitted, i.e. no restrictive options are set.  Otherwise, the widths of the items can always be adjusted.

Set the AFireEvents parameter to True to specify that the events providing notifications about changes to the widths of the view items (such as the OnColumnSizeChanged event) should be fired.

The ApplyBestFit method iterates through data records and calculates the maximum width of item cells.  It also takes the width of the item caption and best fit maximum width value (see the Caption and BestFitMaxWidth property correspondingly) into account.  By default, all data records are processed in order to calculate the best width.  However, you can limit the number of records that are processed and thus improve performance via the BestFitMaxRecordCount property.

It is possible to adjust the width of a column in a grid table or banded table view by double-clicking the column’s right edge.  You can prevent an end-user from changing the column width either by setting the column’s Options.HorzSizing or the view’s OptionsCustomize.ColumnHorzSizing properties to False.


TcxCustomGridTableView.ClearItems

TcxCustomGridTableView          See Also

Removes all items from the current view.

procedure ClearItems;

Description

Use the ClearItems method to remove all items from the current view.  When all view items are destroyed, then a view displays nothing.  To remove a specific item, call its destructor.


TcxCustomGridTableView.CopyToClipboard

TcxCustomGridTableView          See Also

Copies the view’s contents to the clipboard as text.

procedure CopyToClipboard(ACopyAll: Boolean);

Description

Use the CopyToClipboard method to copy the view’s contents to the clipboard as text.

Records in the clipboard are separated by the line break character (#13#10).  The Tab character is used to separate values within a record.

CopyToClipboard copies only the values corresponding to visible items accessible via the view’s VisibleItems property.  For grouping rows, the method copies only the grouping column values.

The CopyToClipboard method allows you to copy only potentially visible records, i.e. records that can be made visible by scrolling.  Records, which are hidden under the collapsed grouping rows, are not included when copying.

The ACopyAll parameter determines whether the entire view or only selected entire records or particular cells are copied.

The OptionsBehavior.CopyCaptionsToClipboard and OptionsBehavior.CopyPreviewToClipboard determine whether the resulting text in the clipboard will contain the columns’ captions and the text which is displayed in the currently active preview section.

If you need to copy the contents of a detail view, you must not refer to a pattern view when calling CopyToClipboard.  Instead, apply the method to a specific detail clone.

The following example demonstrates copying the contents of the tvProducts detail table view:

//Delphi

//...

if tvProducts.CloneCount > 0 then

  TcxCustomGridTableView(tvProducts.Clones[0]).CopyToClipboard(True);

//C++ Builder

//...

if (tvProducts->CloneCount > 0) ((TcxCustomGridTableView*)tvProducts->Clones[0])->CopyToClipboard(true);


TcxCustomGridTableView.CreateItem

TcxCustomGridTableView          See Also

Creates an item and adds it to the current view.

function CreateItem: TcxCustomGridTableItem;

Description

Use the CreateItem method to create and add an item to the current view.  By default, an item is placed at the end of the item list (the Items property).  You can use the CreateColumn and CreateRow methods implemented in (banded) table and card views respectively to create items instead of the CreateItem method.

The DataBinding.ValueTypeClass property determines the type of a value a user can edit within the item.  In bound mode, ValueTypeClass is set automatically based on the type of the field to which an item is connected (the DataBinding.FieldName property).  In unbound and provider modes, you need to set ValueTypeClass manually.

In unbound mode, ValueTypeClass determines the default editor used to edit the item contents.  For instance, assigning it to TcxBooleanValueType results in using the TcxCheckBox editor for the item.  Refer to the FieldName property and TcxValueType class topics to learn about the default editors assigned to items in bound and unbound modes.

To explicitly specify an editor for the item, see the item’s RepositoryItem or PropertiesClass properties.

The following code shows how to create an item within the data-aware tvFilms view and connect it to the TAGLINE field from the view’s dataset.

// Delphi

  with tvFilms.CreateItem as TcxGridDBColumn do

  begin

    DataBinding.FieldName := 'TAGLINE';

    Width := 150;

    //specify TcxMemo as an in-place editor for the item

    PropertiesClass := TcxMemoProperties;

  end;

// C++ Builder

  TcxGridDBColumn *AColumn = (TcxGridDBColumn*)tvFilms->CreateItem();

  AColumn->DataBinding->FieldName = "TAGLINE";

  AColumn->Width = 150;

  //specify TcxMemo as an in-place editor for the item

  AColumn->PropertiesClass = __classid(TcxMemoProperties);

In data-aware views, you can create items for all dataset fields via the CreateAllItems method.


TcxCustomGridTableView.FindItemByID

TcxCustomGridTableView          See Also

Locates an item within the current view according to the item Item.ID property’s value.

function FindItemByID(AID: Integer): TcxCustomGridTableItem;

Description

Use the FindItemByID method to locate an item within the current view according to the item Item.ID property value.  This property value uniquely identifies items within a view.

Data-aware views provide methods to locate items connected to specific dataset fields.  In a (banded) table view, use the GetColumnByFieldName method.  The GetRowByFieldName method is its equivalent in a card view.

To refer to items by their indexes, use the Items property.  It provides access to all items regardless of their visibility.  The VisibleItems property allows you to access only visible items.


TcxCustomGridTableView.FindItemByName

TcxCustomGridTableView          See Also

Locates an item with the specified name.

function FindItemByName(const AName: string): TcxCustomGridTableItem;

Description

Use the FindItemByName method to locate an item with the specified name within the View.Items collection.  This can be useful when creating items and accessing them at runtime.

The following code demonstrates Form.OnCreate and Button.OnClick event handlers.  A column is created and set up in the Form.OnCreate event handler and in the Button.OnClick event handler this column is accessed by the FindItemByName method and its visibility is changed:

//Delphi

procedure TForm1.FormCreate(Sender: TObject);

var

  MyColumn: TcxGridDBColumn;

begin

  MyColumn := tvFilms.CreateColumn;

  MyColumn.Name := 'MyFavoriteColumn';

  MyColumn.DataBinding.FieldName := 'YEAR';

end;

procedure TForm1.Button1Click(Sender: TObject);

begin

  tvFilms.FindItemByName('MyFavoriteColumn').Visible := not tvFilms.FindItemByName('MyFavoriteColumn').Visible;

end;

//C++ Builder

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  TcxGridDBColumn *MyColumn;

  MyColumn = tvFilms->CreateColumn;

  MyColumn->Name = "MyFavoriteColumn";

  MyColumn->DataBinding->FieldName = "YEAR";

}

void __fastcall TForm1::tvFilmsDataControllerSortingChanged(      TObject *Sender)

{

  tvFilms->FindItemByName("MyFavoriteColumn")->Visible = !tvFilms->FindItemByName("MyFavoriteColumn")->Visible;

}


TcxCustomGridTableView.FindItemByTag

TcxCustomGridTableView          See Also

Locates an item with the specified tag value.

function FindItemByTag(ATag: Longint): TcxCustomGridTableItem;

Description

Use the FindItemByTag method to locate an item within the current view according to the item’s Tag property value.  This can be useful when creating items and accessing them at runtime.  This method finds an item with the specified tag value within the View.Items collection.


TcxCustomGridTableView.IndexOfItem

TcxCustomGridTableView          See Also

Returns the index of the first entry within the Items collection with the specified value.

function IndexOfItem(AItem: TcxCustomGridTableItem): Integer;

Description

Call IndexOfItem to get the index for an item in the Items collection.  The item whose index is located is specified via the AItem parameter.

The first item in the collection has index 0, the second item has index 1, and so on. If an item is not in the list, IndexOfItem returns -1.


TcxCustomGridTableView.MakeMasterGridRecordVisible

TcxCustomGridTableView          See Also

Makes the master view record owning the current view visible.

procedure MakeMasterGridRecordVisible;

Description

Use the MakeMasterGridRecordVisible method to display the master view record owning the current view as a detail.  This can be useful if the master view must be scrolled through to locate the required record.

Note:	If the MakeMasterGridRecordVisible method is called for the current view class instance, then it does nothing.  This happens due to the fact that when a master grid record has a visible detail view, then this view is represented via a clone of a view class instance assigned to an appropriate level of hierarchy.  Call the MakeMasterGridRecordVisible method for an appropriate clone for the correct results.


TcxCustomGridTableView.RestoreDefaults

TcxCustomGridTableView          See Also

Restores the default setting for all view items.

procedure RestoreDefaults; override;

Description

Use the RestoreDefaults method to restore the default settings of all view items.  For data-aware items connected to a dataset, the default values are defined by corresponding dataset field attributes.  In this case, the method just restores the default values for the Caption and Width properties.


TcxCustomGridTableView.OnCanFocusRecord

TcxCustomGridTableView          See Also

Occurs before focusing a grid record.

type

  TcxGridAllowRecordOperationEvent = procedure(Sender: TcxCustomGridTableView; ARecord: TcxCustomGridRecord; var AAllow: Boolean) of object;

property OnCanFocusRecord: TcxGridAllowRecordOperationEvent;

Description

Use the OnCanFocusRecord event to control focusing of a record.  The Sender parameter identifies the affected view and the ARecord parameter specifies the record to be focused.  To focus the record, set the AAllow parameter to True.  Otherwise, the record will not be focused and as a result, not selected also.

The following example disables focusing of a record if its tvItemsSTATUS field has a value of 'Fixed' string.  The value displayed by the item is determined by the indexed DisplayTexts property.

//Delphi

procedure TForm1.tvItemsCanFocusRecord(Sender: TcxCustomGridTableView; ARecord: TcxCustomGridRecord; var AAllow: Boolean);

begin

  if ARecord.DisplayTexts[tvItemsSTATUS.Index] = 'Fixed' then

    AAllow := False;

end;

//C++ Builder

void __fastcall TForm1::tvItemsCanFocusRecord(TcxCustomGridTableView *Sender, TcxCustomGridRecord *ARecord, bool &AAllow) {

  if (ARecord->DisplayTexts[tvItemsSTATUS->Index] == "Fixed")

    AAllow = false;

}


TcxCustomGridTableView.OnCanSelectRecord

TcxCustomGridTableView          See Also

Occurs before selecting a grid record.

type

  TcxGridAllowRecordOperationEvent = procedure(Sender: TcxCustomGridTableView; ARecord: TcxCustomGridRecord; var AAllow: Boolean) of object;

property OnCanSelectRecord: TcxGridAllowRecordOperationEvent;

Description

The OnCanSelectRecord event is fired only when the view’s OptionsSelection.MultiSelect property is set to True.  Use this event to control record selection.  The Sender parameter identifies the affected view and the ARecord parameter specifies the record to be selected.  To enable record selection, set the AAllow parameter to True.  This adds the current record to the collection of selected records.

Indexed access to selected records in default loading mode (when the GridMode property is set to False) is provided by the view’s Controller.SelectedRecords property.  When GridMode is applied, see the view’s DataController.GetSelectedBookmark function to obtain selected records.  While in GridMode mode, don’t use the ARecord parameter to refer to the record being selected.  Instead, use the bound dataset to access its values.

If the OnCanSelectRecord event handler sets AAllow to False, records will not be selected.  However, OnCanSelectRecord does not allow you to prevent record focusing.

The following example disables selection of a record if its tvItemsSTATUS field denotes the ‘Fixed’ string.  The value displayed by the item is determined by the indexed DisplayTexts property.

//Delphi

procedure TForm1.tvItemsCanSelectRecord(Sender: TcxCustomGridTableView; ARecord: TcxCustomGridRecord; var AAllow: Boolean);

begin

  if ARecord.DisplayTexts[tvItemsSTATUS.Index] = 'Fixed' then

    AAllow := False;

end;

//C++ Builder

void __fastcall TForm1::tvItemsCanSelectRecord(TcxCustomGridTableView *Sender, TcxCustomGridRecord *ARecord, bool &AAllow) {

  if (ARecord->DisplayTexts[tvItemsSTATUS->Index] == "Fixed")

    AAllow = false;

}


TcxCustomGridTableView.OnCellClick

TcxCustomGridTableView          See Also

Occurs when an end-user clicks a cell within a view.

type

  TcxGridCellClickEvent = procedure(Sender: TcxCustomGridTableView; ACellViewInfo: TcxGridTableDataCellViewInfo; AButton: TMouseButton; AShift: TShiftState; var AHandled: Boolean) of object;

property OnCellClick: TcxGridCellClickEvent;

Description

Handle the OnCellClick event to process clicks on cells within a view.  The Sender parameter specifies the view which contains the cell that was clicked.  The ACellViewInfo parameter contains information on the clicked cell: its display and edit values, its borders, and whether it can be edited or not, etc.  The AButton parameter identifies the mouse button which was clicked.  The AShift parameter determines the state of the Alt, Ctrl, and Shift keys and the state of the mouse buttons.  The AHandled parameter specifies whether the default handling of the click on the cell should be done after the event handler has been executed.  The default handling includes activating the cell’s editor according to the OptionsBehavior.ImmediateEditor property’s value.  Set the AHandled parameter to True to prevent the grid from handling clicks on the cells in the default way.  This parameter has no effect when the OptionsBehavior.AlwaysShowEditor property is set to True.


TcxCustomGridTableView.OnCellDblClick

TcxCustomGridTableView          See Also

Occurs when an end-user double-clicks on a cell within a view.

type

  TcxGridCellClickEvent = procedure(Sender: TcxCustomGridTableView; ACellViewInfo: TcxGridTableDataCellViewInfo; AButton: TMouseButton; AShift: TShiftState; var AHandled: Boolean) of object;

property OnCellDblClick: TcxGridCellClickEvent;

Description

Handle the OnCellDblClick event to process double-clicks on the cells within a view.  The Sender parameter specifies the view containing the cell.  The ACellViewInfo parameter contains information on the double-clicked cell: its display and edit values, its borders, and whether it can be edited or not, etc.  The AButton parameter identifies the mouse button which the double-clicked was performed with.  The AShift parameter determines the state of the Alt, Ctrl, and Shift keys and the state of the mouse buttons.  The AHandled parameter specifies whether the default handling of the double-click on the cell should be done after the event handler’s execution.  The default handling includes activating the cell’s editor according to the OptionsBehavior.ImmediateEditor and OptionsView.ShowEditButtons properties’ values.  Set the AHandled parameter to True to prevent the grid from handling double-clicks on the cells in the default way.  This parameter has no effect when the OptionsBehavior.AlwaysShowEditor property is set to True.


TcxCustomGridTableView.OnCustomDrawCell

TcxCustomGridTableView          See Also

Occurs when a cell within a table view needs to be painted.

type

  TcxGridTableDataCellCustomDrawEvent = procedure(Sender: TcxCustomGridTableView; ACanvas: TcxCanvas; AViewInfo: TcxGridTableDataCellViewInfo; var ADone: Boolean) of object;

property OnCustomDrawCell: TcxGridTableDataCellCustomDrawEvent;

Description

The OnCustomDrawCell event is raised every time a table cell or a card cell needs to be painted. As with other custom draw events it provides a canvas for the grid control (the ACanvas parameter), view info to get the bounding rectangle of the painted element (the AViewInfo parameter and its Bounds property). Sender is usually the element that caused the repaint.  When performing custom drawing of the element you should set the ADone parameter (which is initially False) to True to prevent the grid from drawing this element.


TcxCustomGridTableView.OnCustomDrawPartBackground

TcxCustomGridTableView          See Also

Enables you to custom paint a view element’s background.

type

  TcxGridPartCustomDrawBackgroundEvent = procedure(Sender: TcxCustomGridTableView; ACanvas: TcxCanvas; AViewInfo: TcxCustomGridCellViewInfo; var ADone: Boolean) of object;

property OnCustomDrawPartBackground: TcxGridPartCustomDrawBackgroundEvent;

Description

Use the OnCustomDrawPartBackground event to custom paint a view element’s background.  This event is raised for the following elements:

•	filter panel;

•	footer panel;

•	group footer panels;

•	Group By box.

The OnCustomDrawPartBackground event’s Sender parameter identifies the view whose element is to be painted.  The ACanvas parameter provides the drawing surface.  The ADone parameter specifies whether default painting should be done after the event handler's execution.  Set this parameter to True if you have painted the element and default processing is not required.

The AViewInfo parameter provides access to the object whose properties and method allow you to get information about the painted element.  For instance, you can determine the element to be painted and obtain the element’s bounds using this object’s Bounds property.

In the example below, the Group By box is custom painted by handling the OnCustomDrawPartBackground event.  The box is rendered with a custom image loaded from an external file.  For other view elements, the default painting is used.

//Delphi

//A brush used to fill the "group by" box

var

  APatternBrush: TBrush;

//Create the pattern brush by loading an image to it

procedure TForm1.FormCreate(Sender: TObject);

begin

  APatternBrush := TBrush.Create;

  APatternBrush.Bitmap := TBitmap.Create;

  APatternBrush.Bitmap.LoadFromFile('c:\texture1.bmp');

end;

//An OnCustomDrawPartBackground handler

procedure TForm1.cxGrid1DBTableView1CustomDrawPartBackground(

  Sender: TcxGridTableView; ACanvas: TcxCanvas;

  AViewInfo: TcxCustomGridCellViewInfo; var ADone: Boolean);

begin

  if AViewInfo is TcxGridGroupByBoxViewInfo then

  begin

    //Fill the "group by" box with the pattern brush

    ACanvas.Brush := APatternBrush;

    ACanvas.FillRect(AViewInfo.Bounds);

    //Disable the default painting of the "group by" box

    ADone := True;

    end else

      //Enable the default painting of other view elements

      ADone := False;

  end;

end;

//Dispose of the pattern brush

procedure TForm1.FormDestroy(Sender: TObject);

begin

  APatternBrush.Bitmap.Free;

  APatternBrush.Free;

end;

//C++ Builder

//A brush used to fill the "group by" box

TBrush * APatternBrush;

//Create the pattern brush by loading an image to it

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  APatternBrush = new TBrush();

  APatternBrush->Bitmap = new Graphics::TBitmap();

  APatternBrush->Bitmap->LoadFromFile("c:\\texture1.bmp");

}

//An OnCustomDrawPartBackground handler

void __fastcall TForm1::cxGrid1DBTableView1CustomDrawPartBackground(

      TcxGridTableView *Sender, TcxCanvas *ACanvas,

      TcxCustomGridCellViewInfo *AViewInfo, bool &ADone)

{

  if (dynamic_cast<TcxGridGroupByBoxViewInfo*>(AViewInfo)) {

    //Fill the "group by" box with the pattern brush

    ACanvas->Brush = APatternBrush;

    ACanvas->FillRect(AViewInfo->Bounds);

    //Disable the default painting of the "group by" box

    ADone = true;

  } else {

    ADone = false;

  }

}

//Dispose of the pattern brush

void __fastcall TForm1::FormDestroy(TObject *Sender)

{

  delete APatternBrush->Bitmap;

  delete APatternBrush;

}

The following screenshot shows the result of handling the event.


TcxCustomGridTableView.OnCustomization

TcxCustomGridTableView          See Also

Occurs when the visibility of the view customization form changes.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnCustomization: TNotifyEvent;

Description

Use the OnCustomization event handler to perform specific actions when the view customization form appears or disappears from the screen. You can check the Controller.Customization value to determine whether the form is currently displayed.

The customization form allows you to hide individual columns and bands at runtime by dragging them onto the form.  To display the customization form, set the view’s Controller.Customization property to True.


TcxCustomGridTableView.OnEditChanged

TcxCustomGridTableView          See Also

Occurs when a cell is edited within the current view.

type

  TcxGridCustomTableItemEvent = procedure(Sender: TcxCustomGridTableView; AItem: TcxCustomGridTableItem) of object;

property OnEditChanged: TcxGridCustomTableItemEvent;

Description

OnEditChanged is generated when changing the editor’s value and this event is equivalent to the editor’s Properties.OnChange event.

For text editors, this event is fired when a user types within an editor and thus changes the display text.  Image editors generate this event when changing images.  For check box controls, the event is generated when their state is changed.

The value being edited is assigned to the edit value when a user:

-	selects a value from the dropdown editor;

-	presses the Enter key within a cell if its text was modified;

-	changes an image in image editors;

-	changes the state of check box editors;

-	selects a specific radio button within a radio group.

In these cases, the OnEditValueChanged event is fired.


TcxCustomGridTableView.OnEditing

TcxCustomGridTableView          See Also

Occurs before activating a grid cell’s editor.

type

  TcxGridEditingEvent = procedure(Sender: TcxCustomGridTableView; AItem: TcxCustomGridTableItem; var AAllow: Boolean) of object;

property OnEditing: TcxGridEditingEvent;

Description

Handle the OnEditing event to enable or disable editing within a view.  The Sender parameter identifies the view and the AItem parameter identifies the grid item to be edited.  The AAllow parameter determines whether editing is permitted.  Set it to False to prevent it.


TcxCustomGridTableView.OnEditValueChanged

TcxCustomGridTableView          See Also

Occurs when changing the edit value of the active cell editor.

type

  TcxGridCustomTableItemEvent = procedure(Sender: TcxCustomGridTableView; AItem: TcxCustomGridTableItem) of object;

property OnEditValueChanged: TcxGridCustomTableItemEvent;

Description

The OnEditValueChanged event occurs after changing the edit value of the active editor in the current view.  The edit value indicates the data obtained from a dataset field and edited by the editor.  See the editor’s EditValue property to access the edit value.  The view’s Controller.EditingController.Edit property allows you to get a reference to the currently opened editor.

The edit value is changed when a user:

-	selects a value from the dropdown editor;

-	presses the Enter key within a cell if its text was modified;

-	changes an image in image editors;

-	changes the state of check box editors;

-	selects a specific radio button within a radio group.

The modified edit value is posted back to the corresponding dataset field in the following cases:

-	when setting focus to another record;

-	when posting data programmatically using the data controller’s or dataset’s Post method;

If the ImmediatePost property of the editor’s Properties object is set to True, the edit value will be posted immediately after it has been changed.

The OnEditValueChanged event is equivalent to the editor’s Properties.OnEditValueChanged event, i.e. it is generated every time the Properties.OnEditValueChanged event is fired.


TcxCustomGridTableView.OnFilterControlDialogShow

TcxCustomGridTableView

Enables you to customize the filter builder dialog before it is invoked.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnFilterControlDialogShow: TNotifyEvent;

Description

Handle the OnFilterControlDialogShow event if you need to customize the filter builder dialog's content before it is displayed.  The form representing the dialog is passed via the Sender parameter whose type is TfmFilterControlDialog.  Once the TfmFilterControlDialog object is obtained, you can use its properties to access the form’s settings or the controls that reside on this form.  For instance, you can use the FilterControl property to access the filter control (TcxFilterControl) that is used for filter criteria customization.

The sample code below handles the OnFilterControlDialogShow event to hide the dialog’s Save and Open buttons, change the dialog’s caption and disable the tree lines within the filter control.

//Delphi

procedure TForm1.tvCustomersFilterControlDialogShow(Sender: TObject);

var frm: TfmFilterControlDialog;

begin

  frm := Sender as TfmFilterControlDialog;

  frm.Caption := 'Filter Builder';

  frm.btOpen.Visible := False;

  frm.btSave.Visible := False;

  frm.FilterControl.ShowLevelLines := False;

end;

//C++ Builder

void __fastcall TForm1::tvCustomersFilterControlDialogShow(TObject *Sender)

{

  TfmFilterControlDialog* frm = (TfmFilterControlDialog*)Sender;

  frm->Caption := 'Filter Builder';

  frm->btOpen->Visible := false;

  frm->btSave->Visible := false;

  frm->FilterControl->ShowLevelLines := false;

}


TcxCustomGridTableView.OnFilterCustomization

TcxCustomGridTableView          See Also

Enables you to prevent the filter builder dialog from being displayed or substitute it with your own dialog.

type

  TcxGridFilterCustomizationEvent = procedure(Sender: TcxCustomGridTableView; var ADone: Boolean) of object;

property OnFilterCustomization: TcxGridFilterCustomizationEvent;

Description

The OnFilterCustomization event is raised by views whenever the filter builder dialog is about to be displayed. The view whose filter dialog is being displayed is identified by the Sender parameter.  The ADone parameter specifies whether the dialog should be displayed.  Set this parameter to True if you don’t need to show the dialog.  This can be used if you need to display your own form instead of the filter builder dialog.  The default value of this parameter is False.

If you don’t need to show your own dialog but need to customize the existing dialog before it is displayed, handle the OnFilterControlDialogShow event.

Note:	Normally, pressing the Custom item within a column’s filter dropdown invokes the custom filter dialog.  In such cases, the OnFilterCustomization event is not raised.  You should handle the OnFilterDialogShow event to perform the same tasks.  At the same time, if more than two filter conditions have already been applied to the column, pressing the dropdown’s Custom item invokes the filter builder dialog and raises the OnFilterCustomization event.


TcxCustomGridTableView.OnFilterDialogShow

TcxCustomGridTableView          See Also

Enables you to prevent filter dialogs from being displayed or substitute them with your own filter dialog(s).

type

  TcxGridFilterDialogShowEvent = procedure(Sender: TcxCustomGridTableView; AItem: TcxCustomGridTableItem; var ADone: Boolean) of object;

property OnFilterDialogShow: TcxGridFilterDialogShowEvent;

Description

Views support two built-in filter dialogs: custom filter dialog and filter builder dialog.  The OnFilterDialogShow event is raised each time any of these dialogs is about to be displayed.  The view that invokes the dialog is passed as the Sender parameter.  The AItem parameter identifies the item for which the dialog is displayed.  Normally, the AItem parameter's value is nil if the filter control dialog is about to be displayed.  This parameter’s value is not nil if the custom filter dialog is being invoked.  In this case, the parameter returns the item where the end-user invoked the filter dropdown and chose the Custom item.

Note:	If more than two filter conditions have been applied to a column and the end-user clicks the Custom item within the column’s filter dropdown, the filter builder dialog dialog is invoked instead of the custom filter dialog.  In such cases, the AItem parameter’s value is not nil.  Thus, you should use the IsFilterControlDialogNeeded function to determine which dialog will be displayed.  Pass the data controller’s Filter property value to this function.  You should handle the OnFilterCustomization event to perform the same tasks.

The ADone parameter specifies whether the dialog should be displayed.  Set this parameter to False if you don’t need to show the dialog.  This can be used, for instance, when you want to substitute the built-in dialogs with your own dialog.  You can also use this, for instance, if you need to display the Filter Builder dialog even in cases when the custom filter dialog should be invoked by default.  The sample code below shows how this can be implemented.

//Delphi

procedure TForm2.FilterDialogShow(Sender: TcxCustomGridTableView;

  AItem: TcxCustomGridTableItem; var ADone: Boolean);

begin

  if AItem <> nil then

  begin

    Sender.Filtering.RunCustomizeDialog(nil);

    ADone := True;

  end;

end;

//C++ Builder

void __fastcall TForm1::FilterDialogShow(TcxCustomGridTableView *Sender,

      TcxCustomGridTableItem *AItem, bool &ADone)

{

  if (AItem != NULL) {

    Sender->Filtering->RunCustomizeDialog(NULL);

    ADone = True;

  }

}

This sample code assumes that the procedure which handles the OnFilterDialogShow event is called ‘FilterDialogShow’.


TcxCustomGridTableView.OnFocusedItemChanged

TcxCustomGridTableView          See Also

Occurs when focus is changed to a different view item.

type

  TcxGridFocusedItemChangedEvent = procedure(Sender: TcxCustomGridTableView; APrevFocusedItem, AFocusedItem: TcxCustomGridTableItem) of object;

property OnFocusedItemChanged: TcxGridFocusedItemChangedEvent;

Description

Use the OnFocusedItemChanged event handler to process focus moving through the current view items.  The Sender parameter identifies the view where focus movement has occurred.  The APrevFocusedItem and AFocusedItem parameters identify the previously and currently focused items, respectively.


TcxCustomGridTableView.OnFocusedRecordChanged

TcxCustomGridTableView          See Also

Occurs after focus is moved to a different record.

type

  TcxGridFocusedRecordChangedEvent = procedure(Sender: TcxCustomGridTableView; APrevFocusedRecord, AFocusedRecord: TcxCustomGridRecord; ANewItemRecordFocusingChanged: Boolean) of object;

property OnFocusedRecordChanged: TcxGridFocusedRecordChangedEvent;

Description

Use the OnFocusedRecordChanged event handler to execute code when a record receives focus.  The Sender parameter identifies the view and the APrevFocusedRecord and AFocusedRecord parameters identify the previously and currently focused records, respectively.

If the new item row (the row used to insert new records) is involved in focus movement, the ANewItemRecordFocusingChanged parameter returns True.  When the new item record receives focus, the AFocusedRecord parameter returns nil.  When the new item record loses focus, the APrevFocusedRecord parameter returns nil.


TcxCustomGridTableView.OnGetCellHeight

TcxCustomGridTableView          See Also

Lets you adjust the height of a specific cell.

type

  TcxGridGetCellHeightEvent = procedure(Sender: TcxCustomGridTableView; ARecord: TcxCustomGridRecord; AItem: TcxCustomGridTableItem; ACellViewInfo: TcxGridTableDataCellViewInfo; var AHeight: Integer) of object;

property OnGetCellHeight: TcxGridGetCellHeightEvent;

Description

The OnGetCellHeight event enables you to customize the height of a specific cell.  Whenever the cell is about to be painted its height is calculated and this event is fired.

The view which fired this event is passed as the Sender parameter.  The ARecord and AItem parameters specify the table record and the item (cell) in this record which the height is calculated for.  The viewinfo of the cell is passed as the ACellViewInfo parameter.  The AHeight parameter specifies the new height for the cell.

Since the OptionsView.CellAutoHeight and OptionsView.CellTextMaxLineCount properties control the automatic calculation of a cell's height their values control whether the newly calculated height will be assigned to the cell.

Note:	By default all cells within a grid row have the same height in (banded) table views, thus setting a new height results in appropriate height adjustments for all the cells within the current grid row.  For a banded table view the OnGetCellHeight event is fired only when columns occupy a single row, i.e. they are not stacked vertically and have the Position.RowIndex property equal to 0.


TcxCustomGridTableView.OnGetDragDropText

TcxCustomGridTableView          See Also

Enables you to customize the text which is displayed during a drag operation.

type

  TcxGridGetDragDropTextEvent = procedure(Sender: TcxCustomGridTableView; ARecord: TcxCustomGridRecord; AItem: TcxCustomGridTableItem; var AText: string) of object;

property OnGetDragDropText: TcxGridGetDragDropTextEvent;

Description

The OnGetDragDropText event gives you the ability to customize the text which is displayed adjacent to the mouse pointer when a drag operation is started.  The OnGetDragDropText event is fired only when the view’s OptionsBehavior.DragDropText property is set to True.

The view which raised the event is passed as the Sender parameter.  The ARecord and AItem parameters specify the currently selected table record and item.  The item’s display value is passed as the AText parameter.  You can easily adjust the AText value according to your needs.


TcxCustomGridTableView.OnInitEdit

TcxCustomGridTableView          See Also

Occurs after the editor is invoked for a cell.

type

  TcxGridInitEditEvent = procedure(Sender: TcxCustomGridTableView; AItem: TcxCustomGridTableItem; AEdit: TcxCustomEdit) of object;

property OnInitEdit: TcxGridInitEditEvent;

Description

The OnInitEdit event gives you the ability to customize the cell editor opened for a particular view cell.  The view generating the event is passed as the Sender parameter.  AItem specifies the item whose cell is being edited.

The OnEditing event is generated before the OnInitEdit event thus allowing you to prevent editing based on record/item conditions.

The AEdit parameter represents the activated cell editor.  Use its properties to customize this editor as required.  When the editor is open, you can access it via the view’s Controller.EditingController.Edit property.

If you need to provide different editor types for individual records of a single item, handle the item’s OnGetProperties event.  To initialize the activated cell editor’s edit value, handle the OnInitEditValue event.

The OnInitEdit event handler shown in the following example enables automatic opening of the popup window of dropdown editors.

//Delphi

procedure TForm1.tvCustomersInitEdit(Sender: TcxCustomGridTableView; AItem: TcxCustomGridTableItem; AEdit: TcxCustomEdit);

begin

  if AEdit is TcxCustomDropDownEdit then

    TcxCustomDropDownEdit(AEdit).DroppedDown := True;

end;

//C++ Builder

void __fastcall TForm1::tvCustomersInitEdit(TcxCustomGridTableView *Sender, TcxCustomGridTableItem *AItem, TcxCustomEdit *AEdit)

{

  TcxCustomDropDownEdit * ADropDownEdit;

  if (ADropDownEdit = dynamic_cast<TcxCustomDropDownEdit*>(AEdit))

    ADropDownEdit->DroppedDown = true;

}


TcxCustomGridTableView.OnInitEditValue

TcxCustomGridTableView          See Also

Allows you to initialize the activated cell editor’s edit value for a particular cell.

type

  TcxGridInitEditEvent = procedure(Sender: TcxCustomGridTableView; AItem: TcxCustomGridTableItem; AEdit: TcxCustomEdit; var AValue: TcxEditValue) of object;

property OnInitEdit: TcxGridInitEditEvent;

Description

This event is fired after the OnInitEdit event and allows you to specify the activated cell editor’s edit value via the AValue parameter.  This parameter is pre-initialized by the cell value.

The View that fired this event is passed as the Sender parameter.

The AItem parameter provides access to the item whose cell is being edited.

The AEdit parameter represents the activated cell editor.  When the editor is open, you can access it via the View’s Controller.EditingController.Edit property.


TcxCustomGridTableView.OnInitFilteringDateRanges

TcxCustomGridTableView          See Also

Enables you to customize a collection of filter date ranges that are common to all View items.

type

  TcxGridInitDateRangesEvent = procedure(Sender: TcxCustomGridTableItem; ADateRanges: TcxGridDateRanges) of object;

property OnInitFilteringDateRanges: TcxGridInitDateRangesEvent;

Description

This event is fired before a collection of filter date ranges is determined for any View item that displays date/time values.  Once this event fires, an item’s collection of filter date ranges is initialized with filter date ranges common to all View items.  Refer to the description of the TcxGridFilteringDateRanges.Init method for details on the initialization.

The Sender parameter specifies an item whose collection of filter date ranges has been initialized.

The ADateRanges parameter provides access to the item’s collection.  You can access this collection via the item’s FilteringDateRanges property.  You can use this parameter to add and remove built-in and custom date ranges.  See the Adding Custom Filter and Grouping Date Ranges topic for an example of using this parameter.

An item’s OnInitFilteringDateRanges event is fired after the View’s OnInitFilteringDateRanges event and allows you to further adjust the item’s collection of filter date ranges.


TcxCustomGridTableView.OnInitGroupingDateRanges

TcxCustomGridTableView          See Also

Enables you to customize a collection of grouping date ranges that are common to all View items.

type

  TcxGridInitDateRangesEvent = procedure(Sender: TcxCustomGridTableItem; ADateRanges: TcxGridDateRanges) of object;

property OnInitGroupingDateRanges: TcxGridInitDateRangesEvent;

Description

This event is fired before a collection of grouping date ranges is determined for any View item that displays date/time values.  Once this event fires, an item’s collection of grouping date ranges is initialized with grouping date ranges common to all View items.  Refer to the description of the TcxGridGroupingDateRanges.Init method for details on the initialization.

The Sender parameter specifies an item whose collection of grouping date ranges has been initialized.

The ADateRanges parameter provides access to the item’s collection of grouping date ranges.  You can access this collection via the item’s GroupingDateRanges property.  You can use this parameter to add and remove built-in and custom date ranges.  See the Adding Custom Filter and Grouping Date Ranges topic for an example of using this parameter.

An item’s OnInitGroupingDateRanges event is fired after the View’s OnInitGroupingDateRanges event and allows you to further adjust the item’s collection of grouping date ranges.


TcxCustomGridTableView.OnSelectionChanged

TcxCustomGridTableView          See Also

Occurs after moving the selection to another grid record or column (its cells).

type

  TcxGridCustomTableViewEvent = procedure(Sender: TcxCustomGridTableView) of object;

property OnSelectionChanged: TcxGridCustomTableViewEvent;

Description

Use the OnSelectionChanged event handler to process selection changing within the current view.  The Sender parameter identifies the view where selection changes.  A user can access all the selected records and columns via the View.Controller.SelectedRecords and View.Controller.SelectedColumns.  This event occurs even for records for which selection is disabled via the OnCanSelectRecord event handler.

Note:	Keep in mind the difference between selected and focused records.  There can be only one focused record within a view at any time.  If the View.OptionsSelection.MultiSelect option is deactivated, then the focused record is the selected record.  In this case, the OnSelectionChanged event is not raised.  You need to handle the OnFocusedRecordChanged event instead.  If the View.OptionsSelection.MultiSelect option is active, then a view may not contain selections at all or, conversely, several records can be selected.  Set the View.OptionsSelection.CellMultiSelect property to True to enable the cell (column) selection within a (banded) table view.


TcxCustomGridTableView.OnTopRecordIndexChanged

TcxCustomGridTableView          See Also

Occurs when a view is scrolled vertically.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnTopRecordIndexChanged: TNotifyEvent;

Description

Use the OnTopRecordIndex event handler to process vertical scrolling of a view.  This event occurs when the view is scrolled either by keyboard navigation or by moving the view’s vertical scroll bar.


cxGridDBBandedTableView Unit Overview
cxGridDBBandedTableView Unit

Classes

TcxGridDBBandedColumn

TcxGridDBBandedTableView


TcxGridDBBandedColumn
TcxGridDBBandedColumn Object

Hierarchy          Properties          Methods          Events          See Also

A banded column in a data-aware banded table view.

Unit

cxGridDBBandedTableView

TcxGridDBBandedColumn = class(TcxGridBandedColumn);

Description

TcxGridDBBandedColumn represents a column in a data-aware banded table view (TcxGridDBBandedTableView class).  TcxGridDBBandedColumn is similar to the TcxGridBandedColumn class except that it works with a dataset.  The DataBinding property allows connection of a banded column with a dataset field.

A banded table view has a Columns property maintaining a collection of all columns belonging to the view.  For Columns to be visible they must be associated with a specific band.  You can access a collection of bands via the view’s Bands property.


TcxGridDBBandedColumn Hierarchy
Hierarchy

TComponent

     |

TcxCustomGridTableItem

     |

TcxGridColumn

     |

TcxGridBandedColumn

     |


Properties for TcxGridDBBandedColumn
TcxGridDBBandedColumn Properties

TcxGridDBBandedColumn          Legend

In TcxGridDBBandedColumn

DataBinding

Derived from TcxGridBandedColumn

GridView

Options

Position

Styles

Derived from TcxGridColumn

FooterAlignmentHorz

GridView

GroupSummaryAlignment

HeaderGlyph

HeaderGlyphAlignmentHorz

HeaderGlyphAlignmentVert

IsBottom

IsLeft

IsMostBottom

IsMostLeft

IsMostRight

IsPreview

IsRight

Options

Styles

Derived from TcxCustomGridTableItem

ActuallyVisible

Caption

DataBinding

DateTimeGrouping

Editing

EditValue

Filtered

Focused

GridView

GroupIndex

HeaderAlignmentHorz

HeaderAlignmentVert

Hidden

ID

IncSearching

Index

IsFirst

IsLast

MinWidth

Options

Properties

PropertiesClass

RepositoryItem

SortIndex

SortOrder

Styles

Visible

VisibleForCustomization

VisibleIndex

Width


Methods for TcxGridDBBandedColumn
TcxGridDBBandedColumn Methods

TcxGridDBBandedColumn          Legend

Derived from TcxCustomGridTableItem

 ApplyBestFit

 GetProperties

 RestoreDefaults


Events for TcxGridDBBandedColumn
TcxGridDBBandedColumn Events

TcxGridDBBandedColumn          Legend

Derived from TcxGridColumn

 OnCustomDrawFooterCell

 OnCustomDrawHeader

 OnHeaderClick

Derived from TcxCustomGridTableItem

 OnCustomDrawCell

 OnGetCellHint

 OnGetDataText

 OnGetDisplayText

 OnGetFilterDisplayText

 OnGetFilterValues

 OnGetProperties

 OnGetStoredProperties

 OnGetStoredPropertyValue

 OnInitFilteringDateRanges

 OnSetStoredPropertyValue

 OnUserFiltering


TcxGridDBBandedColumn.DataBinding

TcxGridDBBandedColumn

An object linking the banded column with a dataset field.

property DataBinding: TcxGridItemDBDataBinding;

Description

The DataBinding object has FieldName and Field attributes that reference the field name and TField object respectively from which the column retrieves data and posts data to.  You can use the DataBinding.Data property to set any data depending on your needs.

DataBinding can also refer to a filter condition set for the column and to the filter criteria for the whole view.


TcxGridDBBandedTableView
TcxGridDBBandedTableView Object

Hierarchy          Properties          Methods          Events          See Also

A data-aware banded table view of the Express Quantum Grid.

Unit

cxGridDBBandedTableView

TcxGridDBBandedTableView = class(TcxGridBandedTableView);

Description

The TcxGridDBBandedTableView object represents the data-aware descendant of the grid banded table view.  It inherits all functionality from its ancestor, and adds  data binding settings.

The DataController.DataSource property of the TcxGridDBBandedTableView establishes a connection between the current view and a TDataSet or its descendant.  Other data controller settings specify the key fields for implementing the master-detail relationships, filter and summary settings for the current view and the behavior options for the data controller.

The key element of both the data-aware BandedTableView and its ancestor is a column.  For the GridBandedTableView columns are TcxGridBandedColumn objects, for the data-aware view columns are TcxGridDBBandedColumn objects.

The only difference between a regular banded column and a data-aware banded column is the DataBinding property which provides the connection of the column to a data source field.


TcxGridDBBandedTableView Hierarchy
Hierarchy

TComponent

     |

TcxControlChildComponent

     |

TcxCustomGridView

     |

TcxCustomGridTableView

     |

TcxGridTableView

     |

TcxGridBandedTableView

     |


Properties for TcxGridDBBandedTableView
TcxGridDBBandedTableView Properties

TcxGridDBBandedTableView          Legend

In TcxGridDBBandedTableView

Columns

DataController

Derived from TcxGridBandedTableView

Bands

Columns

Controller

GroupedColumns

OptionsCustomize

OptionsView

Styles

VisibleColumns

Derived from TcxGridTableView

BackgroundBitmaps

ColumnCount

Columns

Controller

DateTimeHandling

Filtering

GroupedColumnCount

GroupedColumns

OptionsBehavior

OptionsCustomize

OptionsData

OptionsSelection

OptionsView

Preview

Styles

ViewData

VisibleColumnCount

VisibleColumns

Derived from TcxCustomGridTableView

Control

Controller

DataController

DateTimeHandling

FilterBox

GroupedItemCount

GroupedItems

ItemCount

Items

MasterGridRecord

OptionsBehavior

OptionsCustomize

OptionsData

OptionsSelection

OptionsView

Styles

SortedItemCount

SortedItems

ViewData

VisibleItemCount

VisibleItems

Derived from TcxCustomGridView

CloneCount

Clones

Controller

DragMode

DataController

Focused

IsControlFocused

IsDetail

IsMaster

IsPattern

Level

MasterGridRecordIndex

MasterGridView

MasterRecordIndex

OptionsSelection

OptionsView

PatternGridView

Styles

ViewData

Visible

Derived from TcxControlChildComponent

Control

IsDestroying

IsLoading


Methods for TcxGridDBBandedTableView
TcxGridDBBandedTableView Methods

TcxGridDBBandedTableView          Legend

In TcxGridDBBandedTableView

 CreateColumn

 GetColumnByFieldName

Derived from TcxGridBandedTableView

 CreateColumn

Derived from TcxGridTableView

 CreateColumn

Derived from TcxCustomGridTableView

 ApplyBestFit

 ClearItems

 CreateItem

 FindItemByID

 IndexOfItem

 MakeMasterGridRecordVisible

 RestoreDefaults

Derived from TcxCustomGridView

 BeginUpdate

 CancelUpdate

 EndUpdate

 LayoutChanged

 RestoreDefaults

 RestoreFromIniFile

 RestoreFromRegistry

 RestoreFromStream

 SizeChanged

 StoreToIniFile

 StoreToRegistry

 StoreToStream

 ViewChanged

Derived from TcxControlChildComponent

 CreateEx

 Destroy


Events for TcxGridDBBandedTableView
TcxGridDBBandedTableView Events

TcxGridDBBandedTableView          Legend

Derived from TcxGridBandedTableView

 OnBandPosChanged

 OnBandSizeChanged

 OnCustomDrawBandHeader

Derived from TcxGridTableView

 OnColumnHeaderClick

 OnColumnPosChanged

 OnColumnSizeChanged

 OnCustomDrawColumnHeader

 OnCustomDrawFooterCell

 OnCustomDrawIndicatorCell

 OnLeftPosChanged

Derived from TcxCustomGridTableView

 OnCanSelectRecord

 OnCellClick

 OnCustomDrawCell

 OnCustomDrawPartBackground

 OnCustomization

 OnEditChanged

 OnEditing

 OnEditValueChanged

 OnFilterControlDialogShow

 OnFocusedItemChanged

 OnFocusedRecordChanged

 OnGetCellHeight

 OnInitEdit

 OnInitEditValue

 OnSelectionChanged

 OnTopRecordIndexChanged

Derived from TcxCustomGridView

 OnDblClick

 OnDragDrop

 OnDragOver

 OnEndDrag

 OnGetStoredProperties

 OnGetStoredPropertyValue

 OnInitStoredObject

 OnMouseDown

 OnMouseEnter

 OnMouseLeave

 OnMouseUp

 OnSetStoredPropertyValue

 OnStartDrag


TcxGridDBBandedTableView.Columns

TcxGridDBBandedTableView          See Also

Provides indexed access to the collection of columns within the data-aware banded table view.

property Columns[Index: Integer]: TcxGridDBBandedColumn;

Description

Use the Columns property to access the current view columns.  Each column is a TcxGridDBBandedColumn object.  This class is a descendant of the TcxGridBandedColumn class so it inherits all its ancestor’s functionality and adds its own properties for implementing the columns connection to a data set field.  The banded columns connection to a data field is provided via its DBBandedColumn.DataBinding property.


TcxGridDBBandedTableView.DataController

TcxGridDBBandedTableView

Represents an object implementing the data-aware banded table views connection to its data storage.

property DataController: TcxGridDBDataController;

Description

Use the DataController property to manage the data-aware banded table views connection to its data storage.  The DataController.DataSource property specifies an object of the TDataSet type which manages the view’s connection to data storage.  Other data controller settings specify the key fields for implementing the master-detail relationships, filter and summary settings for the current view and the behavior options for data controller.


TcxGridDBBandedTableView.CreateColumn

TcxGridDBBandedTableView          See Also

Creates a column and adds it to the Columns collection of the data-aware banded table view, returning a pointer to the column created.

function CreateColumn: TcxGridDBBandedColumn;

Description

Use the CreateColumn method to create a column and add it to the views columns collection.  This collection can be accessed via the Columns property.  After a column is created a user can specify its settings: connection to a data field, behavior options and styles, position within a band, etc.

The following code shows how to use the CreateColumn method:

// Delphi

//...

with btvItems.CreateColumn do

begin

  Caption := 'Description';

  Name := 'btvItemsDescription';

  DataBinding.FieldName := 'DESCRIPTION';

  PropertiesClass := TcxMemoProperties;

  Position.BandIndex := 1;

  Position.RowIndex := 1;

  Visible := True;

end;

...

// C++ Builder

//...

  TcxGridDBBandedColumn *ADBColumn;

  ADBColumn = btvItems->CreateColumn();

  ADBColumn->Caption = "Description";

  ADBColumn->Name = "btvItemsDescription";

  ADBColumn->DataBinding->FieldName = "DESCRIPTION";

  ADBColumn->PropertiesClass = TcxMemoProperties;

  ADBColumn->Position->BandIndex = 1;

  ADBColumn->Position->RowIndex = 1;

  ADBColumn->Visible = True;

end;

...


TcxGridDBBandedTableView.GetColumnByFieldName

TcxGridDBBandedTableView          See Also

Locates a column by the Fieldname of the data it is displaying.

function GetColumnByFieldName(const AFieldName: string): TcxGridDBBandedColumn;

Description

Use the GetColumnByFieldName method to locate a column displaying a specific data field.  The data field name is specified via the AFieldName parameter.

The following code shows how to use the GetColumnByFieldName method:

// Delphi

...

btvUsersSchedule.GetColumnByFieldName('SATURDAY').Visible := False;

...

// C++ Builder

...

btvUsersSchedule->GetColumnByFieldName(″SATURDAY″)->Visible = False;

...


cxGridDBCardView Unit Overview
cxGridDBCardView Unit

Classes

TcxGridDBCardView

TcxGridDBCardViewRow


TcxGridDBCardView
TcxGridDBCardView Object

Hierarchy          Properties          Methods          Events          See Also

Represents a data-aware card view.

Unit

cxGridDBCardView

TcxGridDBCardView = class(TcxGridCardView);

Description

The TcxGridDBCardView object represents the data-aware version of the card grid view.  It inherits all the ancestor functionality except for the data binding settings (for information about view functionality features see the TcxGridCardView class description).  These settings are encapsulated in the DataController property.  The DataController.DataSource property specifies a TDataSet object or its descendant which manages the view connection to a data store.  Other data controller settings specify the key fields for implementing master-detail relationships, filter and summary settings for the current view and the behavior options of the data controller.

The key element of the data-aware CardView, like its ancestor, is a card view row.  However, the data-aware view uses the TcxGridDBCardViewRow class.  The only difference between a regular card view row and a data-aware card view row is the DataBinding property which provides the connection between a card row and a data source’s field.


TcxGridDBCardView Hierarchy
Hierarchy

TComponent

     |

TcxControlChildComponent

     |

TcxCustomGridView

     |

TcxCustomGridTableView

     |

TcxGridCardView

     |


Properties for TcxGridDBCardView
TcxGridDBCardView Properties

TcxGridDBCardView          Legend

In TcxGridDBCardView

DataController

Rows

Derived from TcxGridCardView

BackgroundBitmaps

Controller

DateTimeHandling

LayoutDirection

OptionsBehavior

OptionsData

OptionsSelection

OptionsView

RowCount

Rows

Styles

ViewData

VisibleRowCount

VisibleRows

Derived from TcxCustomGridTableView

Control

Controller

DataController

DateTimeHandling

FilterBox

GroupedItemCount

GroupedItems

ItemCount

Items

MasterGridRecord

OptionsBehavior

OptionsCustomize

OptionsData

OptionsSelection

OptionsView

Styles

SortedItemCount

SortedItems

ViewData

VisibleItemCount

VisibleItems

Derived from TcxCustomGridView

CloneCount

Clones

Controller

DataController

DragMode

Focused

IsControlFocused

IsDetail

IsMaster

IsPattern

Level

MasterGridRecordIndex

MasterGridView

MasterRecordIndex

OptionsSelection

OptionsView

PatternGridView

Styles

ViewData

Visible

Derived from TcxControlChildComponent

Control

IsDestroying

IsLoading


Methods for TcxGridDBCardView
TcxGridDBCardView Methods

TcxGridDBCardView          Legend

In TcxGridDBCardView

 CreateRow

 GetRowByFieldName

Derived from TcxGridCardView

 CreateRow

Derived from TcxCustomGridTableView

 ApplyBestFit

 ClearItems

 CreateItem

 FindItemByID

 IndexOfItem

 MakeMasterGridRecordVisible

 RestoreDefaults

Derived from TcxCustomGridView

 BeginUpdate

 CancelUpdate

 EndUpdate

 LayoutChanged

 RestoreDefaults

 RestoreFromIniFile

 RestoreFromRegistry

 RestoreFromStream

 SizeChanged

 StoreToIniFile

 StoreToRegistry

 StoreToStream

 ViewChanged

Derived from TcxControlChildComponent

 CreateEx

 Destroy


Events for TcxGridDBCardView
TcxGridDBCardView Events

TcxGridDBCardView          Legend

Derived from TcxGridCardView

 OnRowPosChanged

Derived from TcxCustomGridTableView

 OnCanSelectRecord

 OnCellClick

 OnCustomDrawCell

 OnEditChanged

 OnEditing

 OnEditValueChanged

 OnFocusedItemChanged

 OnFocusedRecordChanged

 OnGetCellHeight

 OnInitEdit

 OnInitEditValue

 OnSelectionChanged

 OnTopRecordIndexChanged

Derived from TcxCustomGridView

 OnDblClick

 OnDragDrop

 OnDragOver

 OnEndDrag

 OnGetStoredProperties

 OnGetStoredPropertyValue

 OnInitStoredObject

 OnMouseDown

 OnMouseEnter

 OnMouseLeave

 OnMouseUp

 OnSetStoredPropertyValue

 OnStartDrag


TcxGridDBCardView.DataController

TcxGridDBCardView

Identifies the data controller managing the view’s connection to a data storage.

property DataController: TcxGridDBDataController;

Description

Use the DataController property to access an object managing the view connection to a data storage.  The DataController.DataSource property specifies a TDataSet or its descendant managing the view connection to a data storage.  Other data controller settings specify the key fields for implementing the master-detail relationships, filter and summary settings for the current view and the behavior options for data controller.


TcxGridDBCardView.Rows

TcxGridDBCardView          See Also

Provides indexed access to the collection of card view rows contained within the current view.

property Rows[Index: Integer]: TcxGridDBCardViewRow;

Description

Use the Rows property to access the collection of current card view rows.  Each card view row is an instance of the TcxGridDBCardViewRow class.  This class is a descendant of the TcxGridCardViewRow class and it enhances the Item.DataBinding property so as to work with TDataSet and its descendants.  Row class also provides properties defining row behavior and appearance.


TcxGridDBCardView.CreateRow

TcxGridDBCardView          See Also

Creates a card view row and adds it to the view’s Rows collection.

function CreateRow: TcxGridDBCardViewRow;

Description

Use the CreateRow method to create and add a card view row to the view’s Rows collection.  After a row is created, you can specify its settings such as data binding, behavior options, styles, etc.


TcxGridDBCardView.GetRowByFieldName

TcxGridDBCardView          See Also

Locates a card view row displaying the specified data field values.

function GetRowByFieldName(const AFieldName: string): TcxGridDBCardViewRow;

Description

Use the GetRowByFieldName method to locate a card view row displaying the specified data set field values.  A data set field name, used to locate the required card view row, is specified by the AFieldName parameter.  If a card view row corresponding to the specified field name does not exist or the data set does not contain a field with the specified name, then this method returns nil.


TcxGridDBCardViewRow
TcxGridDBCardViewRow Object

Hierarchy          Properties          Methods          Events          See Also

Represents an item in a data-aware card view.

Unit

cxGridDBCardView

TcxGridDBCardViewRow = class(TcxGridCardViewRow);

Description

A TcxGridDBCardViewRow instance represents an item (a card view row) in a card view of the TcxGridDBCardView class.  This class has a Rows property which supports a collection of rows displayed in a card.  Every row is connected to a data storage via the DataBinding property.  The TcxGridDBCardViewRow class redefines the DataBinding property in order to work with a dataset field.

Ancestors of the TcxGridDBCardViewRow declare different attributes to adjust the appearance and behavior of a card view row.

You can assign editors to edit a card row data via the RepositoryItem or PropertiesClass objects.

To customize the appearance of card view rows, use the properties and events of the row’s Styles or the view’s Styles object.


TcxGridDBCardViewRow Hierarchy
Hierarchy

TComponent

     |

TcxCustomGridTableItem

     |

TcxGridCardViewRow

     |


Properties for TcxGridDBCardViewRow
TcxGridDBCardViewRow Properties

TcxGridDBCardViewRow          Legend

In TcxGridDBCardViewRow

DataBinding

Derived from TcxGridCardViewRow

CaptionAlignmentHorz

CaptionAlignmentVert

Kind

Options

Styles

Derived from TcxCustomGridTableItem

ActuallyVisible

Caption

DataBinding

DateTimeGrouping

Editing

EditValue

Filtered

Focused

GridView

GroupIndex

HeaderAlignmentHorz

HeaderAlignmentVert

Hidden

ID

IncSearching

Index

IsFirst

IsLast

MinWidth

Options

Properties

PropertiesClass

RepositoryItem

SortIndex

SortOrder

Styles

Visible

VisibleForCustomization

VisibleIndex

Width


Methods for TcxGridDBCardViewRow
TcxGridDBCardViewRow Methods

TcxGridDBCardViewRow          Legend

Derived from TcxGridCardViewRow

HasCardExpandButton

IsVisibleInCard

Derived from TcxCustomGridTableItem

ApplyBestFit

GetProperties

RestoreDefaults


Events for TcxGridDBCardViewRow
TcxGridDBCardViewRow Events

TcxGridDBCardViewRow          Legend

Derived from TcxCustomGridTableItem

 OnCustomDrawCell

 OnGetCellHint

 OnGetDataText

 OnGetDisplayText

 OnGetFilterDisplayText

 OnGetFilterValues

 OnGetProperties

 OnGetStoredProperties

 OnGetStoredPropertyValue

 OnInitFilteringDateRanges

 OnSetStoredPropertyValue

 OnUserFiltering


TcxGridDBCardViewRow.DataBinding

TcxGridDBCardViewRow

Specifies an object linking a card view row with a dataset field.

property DataBinding: TcxGridItemDBDataBinding;

Description

Use the properties of the DataBinding object to set and get the field from which data is retrieved.  The DataBinding member allows you to access the filter criteria set for a view containing the current row.


cxGridDBDataDefinitions Unit Overview
cxGridDBDataDefinitions Unit

Classes

TcxGridDBDataController

TcxGridItemDBDataBinding


TcxGridDBDataController
TcxGridDBDataController Object

Hierarchy          Properties          Methods          Events          See Also

Represents a data controller which manages data from a TDataSet.

Unit

cxGridDBDataDefinitions

TcxGridDBDataController = class(TcxDBDataController, IcxCustomGridDataController, IcxGridDataController);

Description

The TcxGridDBDataController provides data from a TDataSet to a data-aware view.  You can connect a view to a dataset via the DataController.DataSource property.

To create master-detail relationships between datasets, you should initialize the MasterKeyFieldNames and DetailKeyFieldNames properties of the detail data controller with the names of master and detail data set fields and their values are used to establish the relationship.

To synchronize the master and detail data controllers, you need to set their key field names via the KeyFieldNames property.

The DataModeController synchronizes the data displayed via the data controller and the corresponding dataset.  It also controls the manner in which data is obtained by the detail data controller when linked to a parameterized query.


TcxGridDBDataController Hierarchy
Hierarchy

TPersistent

     |

TcxCustomDataController

     |

TcxDBDataController

     |


Properties for TcxGridDBDataController
TcxGridDBDataController Properties

TcxGridDBDataController          Legend

Derived from 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 TcxGridDBDataController
TcxGridDBDataController Methods

TcxGridDBDataController          Legend

In TcxGridDBDataController

 AddItemToFilter

 CreateAllItems

Derived from TcxDBDataController

 BeginLocate

 ChangeFieldName

 EndLocate

 GetItemByFieldName

 GetItemField

 GetItemFieldName

 GetRecordId

 LocateByKey

 GetSelectedBookmark

Derived from TcxCustomDataController

 Append

 AppendRecord

 BeginFullUpdate

 BeginUpdate

 BeginUpdateFields

 Cancel

 ChangeDetailExpanding

 ChangeRowSelection

 CheckFocusedSelected

 ClearBookmark

 ClearDetailLinkObject

 ClearDetails

 ClearSelection

 ClearSorting

 CollapseDetails

 DeleteFocused

 DeleteRecord

 DeleteSelection

 Edit

 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 TcxGridDBDataController
TcxGridDBDataController Events

TcxGridDBDataController          Legend

Derived from TcxDBDataController

 OnDetailHasChildren

Derived from TcxCustomDataController

 OnAfterCancel

 OnAfterDelete

 OnAfterInsert

 OnAfterPost

 OnBeforeCancel

 OnBeforeDelete

 OnBeforeInsert

 OnBeforePost

 OnCompare

 OnDataChanged

 OnDetailCollapsed

 OnDetailCollapsing

 OnDetailExpanded

 OnDetailExpanding

 OnFilterRecord

 OnGroupingChanged

 OnRecordChanged

 OnNewRecord

 OnSortingChanged


TcxGridDBDataController.AddItemToFilter

TcxGridDBDataController          See Also

Adds a new filter condition for the specified item.

function AddItemToFilter(AParent: TcxFilterCriteriaItemList; AItem: TcxCustomGridTableItem; AOperatorKind: TcxFilterOperatorKind; const AValue: Variant; ADisplayText: string = ''; AReplaceExistent: Boolean = True): TcxFilterCriteriaItem;

Description

Use the AddItemToFilter method to add a new filter condition or replace the one that already exists for the item referenced by the AItem parameter.  If the AReplaceExistent parameter is True, the new condition replaces the existing condition for this item.

The new condition is added to the list specified by the AParent parameter.  If AParent is NIL, a new filter condition is inserted in the root list provided by the Filter.Root property.

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.


TcxGridDBDataController.CreateAllItems

TcxGridDBDataController          See Also

Creates items for fields in the linked dataset.

procedure CreateAllItems(AMissingItemsOnly: Boolean = False);

Description

To create items only for fields that are not linked to an item, pass True as the AMissingItemsOnly parameter.  Otherwise, items for all fields in the dataset will be created.

This method assigns an item’s DataBinding.FieldName property and adds the item to the View’s Items collection.  The visibility of the created item is defined by the Visible property of the corresponding TField object.


TcxGridItemDBDataBinding
TcxGridItemDBDataBinding Object

Hierarchy          Properties          Methods          See Also

Represents an object linking a data-aware item with a dataset field.

Unit

cxGridDBDataDefinitions

TcxGridItemDBDataBinding = class(TcxGridItemDataBinding);

Description

Every data-aware item (a column in a table view or a row in a card view) is linked to a dataset with the help of a DataBinding object.  When an item is created it is not connected to a dataset field.  In order to do this, the FieldName property must be initialized with the name of the required TField object from a dataset.  It is possible to change the FieldName later thus connecting an item to another field in a dataset.

The view’s DataController.CreateAllItems method allows you to create items for all dataset fields.  This method sets the items’ FieldName property automatically.  To access the data controller associated with the item, use the DataController property.


TcxGridItemDBDataBinding Hierarchy
Hierarchy

TPersistent

     |

TcxGridItemDataBinding

     |


Properties for TcxGridItemDBDataBinding
TcxGridItemDBDataBinding Properties

TcxGridItemDBDataBinding          Legend

In TcxGridItemDBDataBinding

DataController

Field

FieldName

Derived from TcxGridItemDataBinding

Data

Filter

FilterCriteriaItem

Filtered

Item

ValueTypeClass


Methods for TcxGridItemDBDataBinding
TcxGridItemDBDataBinding Methods

TcxGridItemDBDataBinding          Legend

Derived from TcxGridItemDataBinding

 AddToFilter

 Assign


TcxGridItemDBDataBinding.DataController

TcxGridItemDBDataBinding

Identifies the data controller which manages the current item’s data.

property DataController: TcxGridDBDataController;

Description

Use the DataController property to access the object which manages the current item's connection to a dataset.  A data controller object implements the retrieval and posting of data, applies grouping, filtering, and calculates summaries.


TcxGridItemDBDataBinding.Field

TcxGridItemDBDataBinding          See Also

Returns the field associated with the current item.

property Field: TField;

Description

The Field property references a TField object addressed by the FieldName attribute.  To change the field for the item, you can use the FieldName property.

ReadOnly Property


TcxGridItemDBDataBinding.FieldName

TcxGridItemDBDataBinding          See Also

Specifies the name of the item’s field.

property FieldName: string;

Description

The FieldName property addresses the field in a data controller to which the item is linked.  The field itself can be accessed via the Field object.

When FieldName is assigned, the ValueTypeClass property defining the type of value this item represents is set automatically based on the dataset field type.  This ensures the grid performs properly when accessing, sorting and validating item values.

The field type determines the default editor used to edit the contents of the item.  The following table lists the default editors corresponding to field types.  This correspondence is specified by the DBRepositoryItemClasses array declared in cxEditDBRegisteredRepositoryItems unit:

Field type	Default editor
ftBoolean	TcxCheckBox
ftCurrency, ftBCD, ftFMTBcd	TcxCurrencyEdit
ftDate, ftDateTime	TcxDateEdit
ftTime	TcxTimeEdit
ftBytes, ftVarBytes, ftBlob, ftFmtMemo, ftParadoxOle, ftDBaseOle, ftTypedBinary	TcxBlobEdit
ftMemo	TcxMemo
ftGraphic	TcxImage

For items connected to other fields, TcxMaskEdit is used.


cxGridDBTableView Unit Overview
cxGridDBTableView Unit

Classes

TcxGridDBColumn

TcxGridDBTableSummaryItem

TcxGridDBTableView


TcxGridDBColumn
TcxGridDBColumn Object

Hierarchy          Properties          Methods          Events          See Also

Represents a column in a data-aware table view.

Unit

cxGridDBTableView

TcxGridDBColumn = class(TcxGridColumn);

Description

The TcxGridDBColumn class represents a column in a data-aware table view (TcxGridDBTableView) that retrieves and displays data from a dataset.  TcxGridDBColumn redefines the DataBinding property to implement working with a dataset field.

The TcxGridDBColumn class allows you to change the column’s behavior via the Options property and its appearance (content region, footer and header panels) via Styles.  The TcxGridDBTableView class contains a set of options managing the behavior and appearance of all view columns.

Use the RepositoryItem or the PropertiesClass members to assign an editor to a column.


TcxGridDBColumn Hierarchy
Hierarchy

TComponent

     |

TcxCustomGridTableItem

     |

TcxGridColumn

     |


Properties for TcxGridDBColumn
TcxGridDBColumn Properties

TcxGridDBColumn          Legend

In TcxGridDBColumn

DataBinding

Derived from TcxGridColumn

FooterAlignmentHorz

GridView

GroupSummaryAlignment

HeaderGlyph

HeaderGlyphAlignmentHorz

HeaderGlyphAlignmentVert

IsBottom

IsLeft

IsMostBottom

IsMostLeft

IsMostRight

IsPreview

IsRight

Options

Styles

Derived from TcxCustomGridTableItem

ActuallyVisible

Caption

DataBinding

DateTimeGrouping

Editing

EditValue

Filtered

Focused

GridView

GroupIndex

HeaderAlignmentHorz

HeaderAlignmentVert

Hidden

ID

IncSearching

Index

IsFirst

IsLast

MinWidth

Options

Properties

PropertiesClass

RepositoryItem

SortIndex

SortOrder

Styles

Visible

VisibleForCustomization

VisibleIndex

Width


Methods for TcxGridDBColumn
TcxGridDBColumn Methods

TcxGridDBColumn          Legend

Derived from TcxCustomGridTableItem

 ApplyBestFit

 GetProperties

 RestoreDefaults


Events for TcxGridDBColumn
TcxGridDBColumn Events

TcxGridDBColumn          Legend

Derived from TcxGridColumn

 OnCustomDrawFooterCell

 OnCustomDrawHeader

 OnHeaderClick

Derived from TcxCustomGridTableItem

 OnCustomDrawCell

 OnGetCellHint

 OnGetDataText

 OnGetDisplayText

 OnGetFilterDisplayText

 OnGetFilterValues

 OnGetProperties

 OnGetStoredProperties

 OnGetStoredPropertyValue

 OnInitFilteringDateRanges

 OnSetStoredPropertyValue

 OnUserFiltering


TcxGridDBColumn.DataBinding

TcxGridDBColumn

Refers to the object which links a table column to a dataset field.

property DataBinding: TcxGridItemDBDataBinding;

Description

The DataBinding property provides an object connecting a column to a dataset field.  Use its Data attribute to store arbitrary data according to your needs.


TcxGridDBTableSummaryItem
TcxGridDBTableSummaryItem Object

Hierarchy          Properties          Methods          Events          See also

A summary calculated using values of a tabular View’s data field.

Unit

cxGridDBTableView

TcxGridDBTableSummaryItem = class(TcxDBDataSummaryItem);

Description

The TcxGridDBTableSummaryItem class represents a single summary in a data-aware tabular View.  Use the FieldName property to specify the dataset field against which the summary is calculated.  The summary result will be displayed in the column defined by the Column object (which may be different from the field actually displayed in the column).  If the FieldName property is not assigned, the summary will be evaluated against values displayed within the column.  Use the VisibleForCustomization and DisplayText properties to specify the general appearance and the caption for the Group Row Popup Menu item associated with the summary.

The TcxGridDBDataSummaryItem is an element of the collection represented by the TcxDataSummaryItems class, which is the base class for TcxDataFooterSummaryItems and TcxDataGroupSummaryItems implementing footer summaries and group summaries, respectively.

To add a summary to a View, use the View’s DataController.Summary property.

See the Create Summaries topic for additional information on summaries usage.


TcxGridDBTableSummaryItem Hierarchy
Hierarchy

TCollectionItem

     |

TcxCustomDataSummaryItem

     |

TcxDataSummaryItem

     |

TcxDBDataSummaryItem

     |


Properties for TcxGridDBTableSummaryItem
TcxGridDBTableSummaryItem Properties

TcxGridDBTableSummaryItem          Legend

In TcxGridDBTableSummaryItem

Column

DisplayText

VisibleForCustomization

Derived from TcxDBDataSummaryItem

FieldName

Derived from TcxDataSummaryItem

Format

Kind

Position

Sorted

SummaryItems

Derived from TcxCustomDataSummaryItem

DataController

ItemLink


Methods for TcxGridDBTableSummaryItem
TcxGridDBTableSummaryItem Methods

TcxGridDBTableSummaryItem          Legend

Derived from TcxDataSummaryItem

Assign

FormatValue

Derived from TcxCustomDataSummaryItem

Assign

BeginUpdate

EndUpdate


Events for TcxGridDBTableSummaryItem
TcxGridDBTableSummaryItem Events

TcxGridDBTableSummaryItem          Legend

Derived from TcxDataSummaryItem

OnGetText


TcxGridDBTableSummaryItem.Column

TcxGridDBTableSummaryItem

Refers to the column displaying the summary.

property Column: TcxGridColumn;

Description

The Column property defines the column which displays the summary.  The manner in which the Column and FieldName properties affect the summary is shown below:

FieldName property	Column property	Result
Not set	Not set	Summary is not available.
Not set	Set	The Column property identifies the view column whose values are used for summary calculations and where the summary value is displayed.
Set	Not set	The summary is calculated against the values of a data set field identified via the FieldName property, but it is not displayed.
Set	Set	The summary is calculated against the values of a data set field identified by the FieldName property and summary value is displayed at the footer of a view column identified by the Column property.


TcxGridDBTableSummaryItem.DisplayText

TcxGridDBTableSummaryItem

Specifies the caption of the Group Row Popup Menu item associated with the summary.

property DisplayText: string;

Description

This property is effective for group summaries only.

If this property is assigned an empty string, the item’s caption is determined automatically using the cxSGridSortBySummary resource string as a format pattern.  Refer to the corresponding section in the cxGridPopupMenu: Resource Strings topic for detailed information on this resource string.

Use the VisibleForCustomization property to control the general appearance of the menu item in this popup menu.


TcxGridDBTableSummaryItem.VisibleForCustomization

TcxGridDBTableSummaryItem

Specifies whether the menu item associated with the summary will be included into the Group Row Popup Menu.

property VisibleForCustomization: string;

Description

This property is effective for group summaries only.

To specify the caption for this item, use the DisplayText property.

The default value of the VisibleForCustomization property is True.


TcxGridDBTableView
TcxGridDBTableView Object

Hierarchy          Properties          Methods          Events          See Also

Represents the data-aware table grid view.

Unit

cxGridDBTableView

TcxGridDBTableView = class(TcxGridTableView);

Description

The TcxGridDBTableView object represents the data-aware version of the grid table view.  It inherits all functionality from its ancestor, except for data binding settings.  The DataController.DataSource property of the TcxGridDBTableView provides the connection between the view and a TDataSet or its descendant.  Other DataController’s properties specify the key fields for implementing master-detail relationships, filter and summary settings for the view and behavior options for the data controller.

The key element of the GridDBTableView is a column and for data-aware views, the column’s type is TcxGridDBColumn.  The only difference between a regular column and a data-aware column is the DataBinding property which provides the connection of the column to a data source’s field.


TcxGridDBTableView Hierarchy
Hierarchy

TComponent

     |

TcxControlChildComponent

     |

TcxCustomGridView

     |

TcxCustomGridTableView

     |

TcxGridTableView

     |


Properties for TcxGridDBTableView
TcxGridDBTableView Properties

TcxGridDBTableView          Legend

In TcxGridDBTableView

Columns

DataController

Derived from TcxGridTableView

BackgroundBitmaps

ColumnCount

Columns

Controller

DateTimeHandling

Filtering

GroupedColumnCount

GroupedColumns

OptionsBehavior

OptionsCustomize

OptionsData

OptionsSelection

OptionsView

Preview

Styles

ViewData

VisibleColumnCount

VisibleColumns

Derived from TcxCustomGridTableView

Control

Controller

DataController

DateTimeHandling

FilterBox

GroupedItemCount

GroupedItems

ItemCount

Items

MasterGridRecord

OptionsBehavior

OptionsCustomize

OptionsData

OptionsSelection

OptionsView

Styles

SortedItemCount

SortedItems

ViewData

VisibleItemCount

VisibleItems

Derived from TcxCustomGridView

CloneCount

Clones

Controller

DataController

DragMode

Focused

IsControlFocused

IsDetail

IsMaster

IsPattern

Level

MasterGridRecordIndex

MasterGridView

MasterRecordIndex

OptionsSelection

OptionsView

PatternGridView

Styles

ViewData

Visible

Derived from TcxControlChildComponent

Control

IsDestroying

IsLoading


Methods for TcxGridDBTableView
TcxGridDBTableView Methods

TcxGridDBTableView          Legend

In TcxGridDBTableView

 CreateColumn

 GetColumnByFieldName

Derived from TcxGridTableView

 CreateColumn

Derived from TcxCustomGridTableView

 ApplyBestFit

 ClearItems

 CreateItem

 FindItemByID

 IndexOfItem

 MakeMasterGridRecordVisible

 RestoreDefaults

Derived from TcxCustomGridView

 BeginUpdate

 CancelUpdate

 EndUpdate

 LayoutChanged

 RestoreDefaults

 RestoreFromIniFile

 RestoreFromRegistry

 RestoreFromStream

 SizeChanged

 StoreToIniFile

 StoreToRegistry

 StoreToStream

 ViewChanged

Derived from TcxControlChildComponent

 CreateEx

 Destroy


Events for TcxGridDBTableView
TcxGridDBTableView Events

TcxGridDBTableView          Legend

Derived from TcxGridTableView

 OnColumnHeaderClick

 OnColumnPosChanged

 OnColumnSizeChanged

 OnCustomDrawColumnHeader

 OnCustomDrawFooterCell

 OnCustomDrawIndicatorCell

 OnLeftPosChanged

Derived from TcxCustomGridTableView

 OnCanSelectRecord

 OnCellClick

 OnCustomDrawCell

 OnCustomDrawPartBackground

 OnCustomization

 OnEditChanged

 OnEditing

 OnEditValueChanged

 OnFilterControlDialogShow

 OnFocusedItemChanged

 OnFocusedRecordChanged

 OnGetCellHeight

 OnInitEdit

 OnInitEditValue

 OnSelectionChanged

 OnTopRecordIndexChanged

Derived from TcxCustomGridView

 OnDblClick

 OnDragDrop

 OnDragOver

 OnEndDrag

 OnGetStoredProperties

 OnGetStoredPropertyValue

 OnInitStoredObject

 OnMouseDown

 OnMouseEnter

 OnMouseLeave

 OnMouseUp

 OnSetStoredPropertyValue

 OnStartDrag


TcxGridDBTableView.Columns

TcxGridDBTableView         See Also

Provides indexed access to the collection of the view’s columns.

property Columns[Index: Integer]: TcxGridDBColumn;

Description

Use the Columns property to access the collection of columns.  Each column consists of an instance of the TcxGridDBColumn class.  This class is a TcxGridColumn class descendant and it redefines the Item.DataBinding property to work with the TDataSet and its descendants.  Each column also provides properties for defining sets of options & styles controlling the column’s look & feel, an editor for its values, etc.

The following code shows how to use the Columns property to access all view columns and to change their captions:

// Delphi

for I := 0 to OrdersView.ColumnCount - 1 do

  OrdersView.Columns[I].Caption := 'Column' + IntToStr(I + 1);

// C++ Builder

for (int I = 0; I < OrdersView.ColumnCount; I++)

  OrdersView->Columns[I]->Caption = "Column" + IntToStr(I + 1);


TcxGridDBTableView.DataController

TcxGridDBTableView

Refers to the data controller providing data for the view.

property DataController: TcxGridDBDataController;

Description

Use the DataController property to access a TcxGridDBDataController instance managing the view’s connection to a TDataSet.  You connect a view to a dataset via the DataController.DataSource property.

To create a master-detail relationship, create a data controller for every dataset and specify the master and detail key field names via the DataController.MasterKeyFieldNames and DataController.DetailKeyFieldNames properties of the detail data controller.

You may also need to set key field names via the DataController.KeyFieldNames property to get the grid to function properly. You should set the DataController.KeyFieldNames property in the following cases:

•	if you want to perform in-sync operations on the 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;

The DataController.DataModeController manages the synchronization between the data displayed and the corresponding dataset.  It also controls the way data is obtained by the detail data controller when it is linked to a parameterized query.


TcxGridDBTableView.CreateColumn

TcxGridDBTableView          See Also

Creates and adds a column to the view’s Columns collection.

function CreateColumn: TcxGridDBColumn;

Description

After a column is created, you can specify its settings, such as data binding, options, styles, etc.


TcxGridDBTableView.GetColumnByFieldName

TcxGridDBTableView          See Also

Locates the column displaying a particular field’s values.

function GetColumnByFieldName(const AFieldName: string): TcxGridDBColumn;

Description

Use the GetColumnByFieldName method to locate the column displaying values from the specified data set field.  The field name is specified via the AFieldName parameter.  If a column corresponding to the specified field name does not exist or the data set contains no field with the specified name, then this method returns nil.


cxGridLevel Unit Overview
cxGridLevel Unit

Classes

TcxGridLevel

TcxGridLevelOptions

TcxGridLevelStyles

Other Types

TcxGridDetailTabsPosition


TcxGridLevel
TcxGridLevel Object

Hierarchy          Properties          Methods          Events           See Also

Encapsulates the concept of grid level within a grid control.

Unit

cxGridLevel

TcxGridLevel = class(TComponent);

Description

The TcxGridLevel class introduces properties and methods which support the hierarchical representation of data within a grid control.  Levels are mostly used to create master-detail relations between tables.  To present a master-detail relation between two tables, you need to create two levels (the second level must be a child of the first level), associate a grid view (a TcxCustomGridView descendant) with each level and link tables via the DataController property of a view object.  Grid levels created in this manner are placed at different nesting levels.  The grid control also enables you to place several grid levels (views) at the same nesting level, thus supporting multiple details for one master table.

The following image shows a grid control with three grid levels.  Grid Level 2 and Grid Level 3 are children of Grid Level 1.  In other words, these grid levels are placed at two different nesting levels.

Grid Level 1 represents data from the Orders table.  Grid Level 2 and 3 are associated with the views retrieving data from the Customer and Employee tables respectively.  The Employee and Orders tables are linked by the EmpNo field.  The Customer and Orders tables are linked by the CustNo field.

A grid control allows the displaying of several grid levels (views) and you can switch between them.

A grid control contains the Levels property of class TcxGridLevel, thus providing you access to root grid levels.  Each level can have children.  To access child levels use the Items property.

A level itself merely provides the hierarchy. You assign a view to it in order to retrieve data from a particular data storage and represent it in a specific form (table, banded table, card, etc.).


TcxGridLevel Hierarchy
Hierarchy

TComponent

     |


Properties for TcxGridLevel
TcxGridLevel Properties

TcxGridLevel          Legend

In TcxGridLevel

Active

ActuallyVisible

Caption

Control

Count

GridView

ImageIndex

Index

IsMaster

IsTop

Items

MaxDetailHeight

Options

Parent

Styles

Visible

VisibleCount

VisibleIndex

VisibleItems


Methods for TcxGridLevel
TcxGridLevel Methods

TcxGridLevel          Legend

In TcxGridLevel

 Add

 Destroy

 GetAvailableItem

 HasAsChild

 MakeVisible


Events for TcxGridLevel
TcxGridLevel Events

TcxGridLevel          Legend

In TcxGridLevel

 OnGetGridView


TcxGridLevel.Active

TcxGridLevel          See Also

Specifies whether the current level is active.

property Active: Boolean;

Description

The level’s Active property returns True if the current level is the active root grid level.  Root grid levels are the levels displayed at the root nesting level.  This property is in effect only for root grid levels.

Note:	For child levels, this property always returns False.  To make a particular grid level (both root and child level) visible, call its MakeVisible method.

Use the grid’s ActiveLevel property and a data row’s ActiveDetailLevel property of a master view to determine the current active root grid level and active child level and the active child level, respectively.


TcxGridLevel.ActuallyVisible

TcxGridLevel          See Also

Specifies whether the current level and all its parent (master) levels can be displayed.

property ActuallyVisible: Boolean;

Description

Use the Visible property to hide a specific level.  If the property is set to False, the view associated with this level is not displayed.  Also all child levels are also hidden regardless their visibility.

The ActuallyVisible property returns True if the current level and all its parent (master) levels have the Visible property set to True.  Otherwise, ActuallyVisible returns False.

To make a particular grid level (both root and child level) visible, call its MakeVisible method.

ReadOnly Property


TcxGridLevel.Caption

TcxGridLevel          See Also

Specifies the caption for the current level.

property Caption: string;

Description

The Caption property defines the string identifying the current level when the tab panel is visible.  The tab panel allows switching between grid levels (views) at the same nesting level.  The caption will be displayed within the corresponding tab with the tab image specified by the ImageIndex property.

The tab panel at the root nesting level is designed for switching between root grid levels.  You can display it by changing the RootLevelOptions.DetailTabsPosition attribute value of a grid control from dtpNone to dtpLeft or dtpTop.  As a result, the tab panel will appear at the left grid edge or its top.

To display the tab panel for switching between child levels, do the same with the Options.DetailTabsPosition property of a parent (master) level.


TcxGridLevel.Control

TcxGridLevel

Represents the grid control containing the current grid level.

property Control: TcxControl;

Description

The level’s Control property refers to the grid control which contains it.


TcxGridLevel.Count

TcxGridLevel          See Also

Returns the number of child (detail) levels for the current grid level.

property Count: Integer;

Description

The Count property returns the number of child levels for the current TcxGridLevel instance.  The collection of levels is supported by the Items property.

ReadOnly Property


TcxGridLevel.GridView

TcxGridLevel          See Also

Specifies the view associated with the current level.

property GridView: TcxCustomGridView;

Description

Use the GridView property to assign a view to the current grid level.  Levels allow you to specify the data hierarchy only.  The retrieval of data from a data source and displaying it on screen is implemented by a view.  TcxCustomGridView is a base class for views.  ExpressQuantumGrid provides several views:

-	Table View (TcxGridTableView and TcxGridDBTableView) – displays data in a tabular form (similar to a standard TCustomGrid control)

-	Banded Table View (TcxGridBandedTableView and TcxGridDBBandedTableView) – similar to a table view but with the additional ability to group columns within bands

-	Card View (TcxGridCardView and TcxGridDBCardView) – displays data records in cards (data fields are displayed in rows instead of vertically in columns)

-	Chart View (TcxGridChartView and TcxGridDBChartView) – displays numerical data in the form of a chart diagram (for instance, a bar diagram or column diagram).


TcxGridLevel.ImageIndex

TcxGridLevel          See Also

Specifies the index of an image associated with the current grid level.

type

  TImageIndex = type Integer;

property Index: TImageIndex;

Description

Use this property to associate an image from the grid’s LevelTabs.Images zero-based indexed collection with the current grid level.  The image will be displayed to the left of the tab’s caption specified by the level’s Caption property.

The ImageIndex property’s value of -1 indicates that an image is not associated with the grid level.

The default value of the ImageIndex property is -1.


TcxGridLevel.Index

TcxGridLevel          See Also

Determines the position of the grid level within the collection of detail levels to which it belongs.

property Index: Integer;

Description

Use the Index property to get or set the position of the current grid level within a collection of detail levels.  You can get the master level containing the current grid level by accessing the Parent property.


TcxGridLevel.IsMaster

TcxGridLevel          See Also

Specifies whether a grid level has child levels that can be displayed.

property IsMaster: Boolean;

Description

The IsMaster property returns a Boolean value indicating whether the current grid level has detail levels that can be displayed to a user.  IsMaster returns True if there is any child level whose Visible property is set to True.  Otherwise, IsMaster returns False.

ReadOnly Property


TcxGridLevel.IsTop

TcxGridLevel

Specifies whether the grid level is at the root nesting level.

property IsTop: Boolean;

Description

The IsTop property returns a value indicating whether the grid level is placed at the root nesting level.  There can be several of these top grid level items and they are all directly accessible via the indexed TcxCustomGrid.Levels property.

ReadOnly Property


TcxGridLevel.Items

TcxGridLevel          See Also

Specifies the collection of child (detail) levels for the current grid level.

property Items[Index: Integer]: TcxGridLevel;

Description

Use the Items property to get references to child levels for the current grid level.  The number of levels is defined by the Count property.

Levels in this collection are used to create master-detail relations between datasets (data storages, stating it more generally).  The current level is linked with the help of a view to a master table, while each child grid level is linked to a detail table.

ReadOnly Property


TcxGridLevel.MaxDetailHeight

TcxGridLevel

Specifies the maximum height of views displayed by child levels.

property MaxDetailHeight: Integer;

Description

Use the MaxDetailHeight property to limit the height of views displayed by detail levels.  If MaxDetailHeight is set to zero, the height is not limited and is capable of displaying the complete detail view.

The default value of the MaxDetailHeight property is 0.


TcxGridLevel.Options

TcxGridLevel          See Also

Represents a set of options managing the general appearance of views displayed by child (detail) levels.

property Options: TcxGridLevelOptions;

Description

The Options property specifies general options managing the appearance of views displayed by child (detail) levels.  Child levels are accessible via the Items member.  You can specify the width of a frame around views and define the position for the tabs which control which particular detail view is currently displayed.

For settings which relate to top level views, use the TcxCustomGrid.RootLevelOptions property.


TcxGridLevel.Parent

TcxGridLevel          See Also

Specifies the parent grid level which owns the current grid level.

property Parent: TcxGridLevel;

Description

Use the Parent property to get or set the parent (master) grid level which contains the current grid level.  If the current grid level is at the root nesting level, the Parent property returns the TcxCustomGrid.Levels property value.

If the parent level is destroyed, it disposes of all child levels it contains.  See the Items property to access all child levels for a given parent.


TcxGridLevel.Styles

TcxGridLevel          See Also

Controls the appearance of child level elements.

property Styles: TcxGridLevelStyles;

Description

The Styles property provides attributes and events managing the style of tabs and the tabs panel.  Tabs are displayed on the tabs panel and enable switching between several views at the child nesting level.  By default the tab panel is hidden and only one view is visible.

The tab panel at the root nesting level is designed for switching between root grid levels.  You can display it by changing the RootLevelOptions.DetailTabsPosition attribute value of a grid control from dtpNone to dtpLeft or dtpTop.  As a result the tab panel will appear at the left grid edge or its top.

To display the tab panel for switching between child levels, do the same with the Options.DetailTabsPosition property of a parent (master) level.

In addition, you need to assign the Caption of a corresponding child grid level to identify it when displaying the tab panel.


TcxGridLevel.Visible

TcxGridLevel          See Also

Specifies whether the current level can be displayed.

property Visible: Boolean;

Description

The Visible property specifies the visibility of the current level.  If Visible is set to False, the level and the view associated with it will not be displayed.

If the current level is the child one and the Visible property of the parent level is set to False, the level will not be displayed.  See the ActuallyVisible property to know whether the current level can be actually displayed.  If the Visible property of the current level and all its parent levels is True, then ActuallyVisible returns True.

To make a particular grid level (both root and child level) visible, call its MakeVisible method.

The default value of the Visible property is True.


TcxGridLevel.VisibleCount

TcxGridLevel          See Also

Returns the number of child (detail) levels which can be displayed.

property VisibleCount: Integer;

Description

The VisibleCount property returns the number of child levels which have the Visible property set to True.  Visible child levels can be accessed via the VisibleItems collection.

ReadOnly Property


TcxGridLevel.VisibleIndex

TcxGridLevel          See Also

Determines the position of the grid level within a collection of visible detail levels.

property VisibleIndex: Integer;

Description

Use the VisibleIndex property to get or set the position of the current grid level within a collection of detail levels which can be displayed (the Visible property is set to True).  You can get the master level to which the current level belongs by reading the Parent property.

ReadOnly Property


TcxGridLevel.VisibleItems

TcxGridLevel          See Also

Specifies the collection of child (detail) levels which can be displayed.

property VisibleItems[Index: Integer]: TcxGridLevel;

Description

The VisibleItems property returns detail levels which have their Visible property set to True.  The number of items in the VisibleItems collection is defined by the VisibleCount attribute.  You can use the Items property to access all child grid levels for the current level.

ReadOnly Property


TcxGridLevel.Add

TcxGridLevel          See Also

Adds a new child (detail) level.

function Add: TcxGridLevel;

Description

The Add method creates a new instance of the TcxGridLevel class and adds it the collection of child (detail) grid levels available via the Items property.  The current grid level becomes the parent of the new TcxGridLevel instance created.


TcxGridLevel.Destroy

TcxGridLevel

Destroys an instance of the TcxGridLevel class.

destructor Destroy; override;

Description

The destructor destroys the current TcxGridLevel object by freeing all resources allocated by the object.  The destructor also destroys any detail grid levels it contains and removes itself from the collection of child levels in the parent (master) grid level.


TcxGridLevel.GetAvailableItem

TcxGridLevel          See Also

Returns the first visible child (detail) level which can be displayed by the current grid level.

function GetAvailableItem: TcxGridLevel;

Description

To access a particular child (detail) level, which is available for display by the current grid level, use the VisibleItems zero-based indexed collection.  The GetAvailableItem function returns the first visible detail level from this collection.  When no detail level exists (the VisibleCount property returns 0), this function returns nil.


TcxGridLevel.HasAsChild

TcxGridLevel

Specifies whether the current grid level has the specified TcxGridLevel as a child.

function HasAsChild(ALevel: TcxGridLevel): Boolean;

Description

Use the HasChild method to discover whether the current level contains a specific level as a child.

HasAsChild performs a recursive search of the child levels and returns True if the current grid level or one of its detail levels has ALevel as a child.  Otherwise, this function returns False.


TcxGridLevel.MakeVisible

TcxGridLevel          See Also

Makes the current grid level visible.

function MakeVisible: TcxCustomGridView;

Description

This function sequentially forces all parent (master) grid levels - of the current grid level - to display their detail grid levels.  This also activates the corresponding root grid level.

Note:	A grid level becomes visible provided that the Visible property of this level and all its immediate parent levels are set to True.

The MakeVisible function returns the clone view associated with the current grid level when it becomes visible in this manner.  Otherwise, nil is returned.


TcxGridLevel.OnGetGridView

TcxGridLevel

Enables you to substitute the view that will display detail data.

type

  TcxGridLevelGetGridViewEvent = procedure(Sender: TcxGridLevel; AMasterRecord: TcxCustomGridRecord; var AGridView: TcxCustomGridView) of object;

property OnGetGridView: TcxGridLevelGetGridViewEvent;

Description

Detail levels raise the OnGetGridView event when a row within the master level is expanded.  This event allows you to change the view that will display detail data corresponding to the master row being expanded.  Thus, you can provide different views for details corresponding to different master views.

The Sender parameter represents the detail level whose corresponding view can be changed.  The AMasterRecord parameter is the master record being expanded.  If you need to change the view that will represent detail data for that master record, assign the desired view to the AGridView parameter.

Note: the OnGetGridView event is raised only once when the detail is first expanded.  After the event handler has been executed, the specified view’s clone is created and cached so that the event doesn’t fire when expanding the same master record next times.  If you need the event to be raised later, you can clear all detail clones by calling the master data controller’s ClearDetails method.  If you need to recreate a particular detail clone, use the master data controller’s ClearDetailLinkObject method.


TcxGridLevelOptions
TcxGridLevelOptions Object

Hierarchy          Properties          See Also

Represents a set of options managing the general appearance of views displayed at child (detail) levels.

Unit

cxGridLevel

TcxGridLevelOptions = class(TPersistent);

Description

The TcxGridLevelOptions class contains options managing the appearance of views displayed at child (detail) levels.  To apply these settings, use the TcxCustomGrid.RootLevelOptions and TcxGridLevel.Options properties.


TcxGridLevelOptions Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxGridLevelOptions
TcxGridLevelOptions Properties

TcxGridLevelOptions          Legend

In TcxGridLevelOptions

DetailFrameColor

DetailFrameWidth

DetailTabsPosition

TabsForEmptyDetails


TcxGridLevelOptions.DetailFrameColor

TcxGridLevelOptions          See Also

Specifies the color of a frame around a view displayed at the detail level.

property DetailFrameColor: TColor;

Description

Use the DetailFrameColor property to define the color of the frame around a view displayed at the detail level.  The DetailFrameWidth property determines the width of this frame.

The following image shows the frame around the detail with a width of 4 pixels and its color set to soft blue ($00FF8000).

The default value of the DetailFrameColor property is clDefault.


TcxGridLevelOptions.DetailFrameWidth

TcxGridLevelOptions          See Also

Specifies the width of a frame around a view displayed at the detail grid level.

property DetailFrameWidth: Integer;

Description

Use the DetailFrameWidth property to specify the width of the frame around a view displayed at the detail grid level.  The DetailFrameColor property determines the color of this frame.

The following image shows the frame around the detail with a width of 4 pixels and its color set to soft blue ($00FF8000).


TcxGridLevelOptions.DetailTabsPosition

TcxGridLevelOptions          See Also

Specifies the position of tabs controlling the actual child view currently visible.

property DetailTabsPosition: TcxGridDetailTabsPosition;

Description

The DetailTabsPosition property determines whether and where to display tabs controlling the actual child view currently visible.  Tabs display child level captions set via the Caption property.  An end-user can switch to a view corresponding to one of the child levels by clicking the relevant tab.

If DetailTabsPosition is set to dtpNone, tabs are not displayed and a user cannot switch to a particular view. In this case, only one detail view is visible.  Otherwise, tabs are visible and their position is determined by the DetailTabsPosition property value.


TcxGridLevelOptions.TabsForEmptyDetails

TcxGridLevelOptions          See Also

Specifies whether tabs in the tab panel should be displayed for empty detail Views.

property TabsForEmptyDetails: Boolean;

Description

Set this property to False to hide tabs for detail Views which don’t display any data (i.e. their ViewData.IsEmpty property returns True).  Otherwise, tabs will be displayed for all detail Views.

The default value of the TabsForEmptyDetails property is True.


TcxGridLevelStyles
TcxGridLevelStyles Object

Hierarchy          Properties          Methods          Events          See Also

Represents the settings managing the style of child nesting level elements.

Unit

cxGridLevel

TcxGridLevelStyles = class(TcxStyles);

Description

The TcxGridLevelStyles class provides properties and events relating to the style of tabs and the tab panel displayed at the child (detail) grid levels.  Tabs are displayed within the tab panel and enable switching between the display of several child views.  To display a tab for a particular view, assign the Caption of the corresponding child grid level and ensure that the TcxGridLevelOptions.DetailTabsPosition flag of the parent grid level is not set to dtpNone.  If DetailTabsPosition is set to dtpNone, only one detail view is visible.

To set styles for a tab panel, use the TcxCustomGrid.RootLevelStyles and TcxGridLevel.Styles properties for root and detail levels respectively.


TcxGridLevelStyles Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomStyles

     |

TcxStyles

     |


Properties for TcxGridLevelStyles
TcxGridLevelStyles Properties

TcxGridLevelStyles          Legend

In TcxGridLevelStyles

Level

Tab

TabsBackground

Derived from TcxCustomStyles

StyleSheet


Methods for TcxGridLevelStyles
TcxGridLevelStyles Methods

TcxGridLevelStyles          Legend

Derived from TcxCustomStyles

 Assign

 Create

 Destroy


Events for TcxGridLevelStyles
TcxGridLevelStyles Events

TcxGridLevelStyles          Legend

In TcxGridLevelStyles

 OnGetOwnTabStyle

 OnGetTabStyle


TcxGridLevelStyles.Level

TcxGridLevelStyles

Specifies the grid level for which the current TcxGridLevelStyles instance provides style settings.

property Level: TcxGridLevel;

Description

Use the Level property to refer to the grid level to which its style is applied.

ReadOnly Property


TcxGridLevelStyles.Tab

TcxGridLevelStyles          See Also

Specifies the style for all tabs within a tab panel.

property Tab: TcxStyle;

Description

Use the Tab property to specify the style for tabs controlling which particular detail view is actually displayed.  You can handle the OnGetTabStyle and OnGetOwnTabStyle events to define different styles for individual tabs.


TcxGridLevelStyles.TabsBackground

TcxGridLevelStyles          See Also

Specifies the style for a tab panel background.

property TabsBackground: TcxStyle;

Description

Use the TabsBackground property to set the style for a tab panel background.  To define the style for tabs themselves, assign a style to the Tab attribute.


TcxGridLevelStyles.OnGetTabStyle

TcxGridLevelStyles          See Also

Occurs before a view tab is redrawn.

type

  TcxGridLevelGetTabStyleEvent = procedure(Sender, ATabLevel: TcxGridLevel; out AStyle: TcxStyle) of object;

property OnGetTabStyle: TcxGridLevelGetTabStyleEvent;

Description

Use the OnGetTabStyle event to define a style for an individual tab within a tab panel.  The style common to all tabs is defined via the level’s Styles.Tab property.  You can redefine the style for an individual tab by handling the OnGetTabStyle event and returning the style for this tab via the AStyle parameter.  The Sender parameter defines the grid level containing the detail levels displayed using the tabs.  The ATabLevel parameter specifies the specific detail level whose tab is to be drawn.  The style returned via the AStyle parameter will be used to draw this tab.


TcxGridLevelStyles.OnGetOwnTabStyle

TcxGridLevelStyles          See Also

Occurs before a view tab at the current level is redrawn.

type

  TcxGridLevelGetOwnTabStyleEvent = procedure(Sender: TcxGridLevel; AMasterRecord: TcxCustomGridRecord; var AStyle: TcxStyle) of object;

property OnGetOwnTabStyle: TcxGridLevelGetOwnTabStyleEvent;

Description

You can define the style of an individual tab by handling the OnGetTabStyle event of the object (the view or the current level) which displays the current level.  The current level’s OnGetOwnTabStyle event lets you redefine the style which is introduced by this object.

The Sender parameter specifies the grid level whose tab style will be redefined.  The AMasterRecord parameter denotes the master record for which the detail tab is to be drawn.  The style that will be used to draw this tab is returned via the AStyle parameter.


TcxGridDetailTabsPosition
TcxGridDetailTabsPosition type

Enumerates values defining the position of the tabs panel.

Unit

cxGridLevel

TcxGridDetailTabsPosition = (dtpNone, dtpLeft, dtpTop);

Description

A tabs panel is displayed within a child nesting level and displays tabs for switching to a particular child level (and the relevant view).  To define the position of a tabs panel, use the TcxGridLevelOptions.DetailTabsPosition property.  The possible values are:

Value	Meaning
dtpNone	A tabs panel is not displayed.  Only one child view is visible.
dtpLeft	A tabs panel is displayed at the left edge of a child nesting level.
dtpTop	A tabs panel is displayed at the right edge of a child nesting level.


cxGridPopupMenu Unit Overview
cxGridPopupMenu Unit

Classes

TcxGridPopupMenu


TcxGridPopupMenu
 TcxGridPopupMenu Object

Hierarchy          Properties          Methods          Events

Allows you to implement menus for specific ExpressQuantumGrid views.

Unit

cxGridPopupMenu

TcxGridPopupMenu = class(TcxCustomGridPopupMenu);

Description

The cxGridPopupMenu component was created to give you the ability to implement different menus for your grid control.  The TcxPopupMenuInfo.HitTypes property allows you to specify the elements that respond to a right mouse click.  You can create an appropriate menu for each grid view element.  The collection of these menus can be accessed via the PopupMenus property.  The Grid property is used to specify the ExpressQuantumGrid control that uses a given cxGridPopupMenu.

The BuiltInPopupMenus property specifies whether to activate default built-in menus.  There are three default built-in menus available in the cxGridPopupMenu component:

•	column header popup menu;

•	footer popup menu;

•	group row popup menu.

Though these menus are built-in, you can insert your own items – see the GridMenuViewsDemo shipped with the ExpressQuantumGrid for more information.


TcxGridPopupMenu Hierarchy
Hierarchy

TComponent

     |

TcxCustomGridPopupMenu

     |


Properties for TcxGridPopupMenu
TcxGridPopupMenu Properties

TcxGridPopupMenu          Legend

In TcxGridPopupMenu

AlwaysFireOnPopup

BuiltInPopupMenus

Grid

HitGridView

HitPoint

HitTest

HitType

PopupMenus

UseBuiltInPopupMenus

Derived from TcxCustomGridPopupMenu

Count


Methods for TcxGridPopupMenu
TcxGridPopupMenu Methods

TcxGridPopupMenu          Legend

In TcxGridPopupMenu

RegisterPopupMenu

UnregisterPopupMenu


Events for TcxGridPopupMenu
TcxGridPopupMenu Events

TcxGridPopupMenu          Legend

In TcxGridPopupMenu

OnPopup


TcxGridPopupMenu.AlwaysFireOnPopup

TcxGridPopupMenu

Determines whether the component’s OnPopup event precedes the custom menu’s OnPopup event.

property AlwaysFireOnPopup: Boolean;

Description

The custom popup menu’s OnPopup event is only raised when the popup menu is assigned via the PopupMenu property.  Set the AlwaysFireOnPopup property to True to ensure that the component’s OnPopup event is always raised prior to the custom menu’s OnPopup event being raised, even when the custom popup menu is unassigned.


TcxGridPopupMenu.BuiltInPopupMenus

TcxGridPopupMenu

Provides access to built-in menus.

property BuiltInPopupMenus: TcxGridDefaultPopupMenu;

Description

Use the BuiltInPopupMenus property to work with the default menus supplied with your grid control.  You can add your own new items to them or redefine the default actions of existing items.  For more information on using this property, refer to the GridMenuViewsDemo shipped with the ExpressQuantumGrid.

Refer to the Managing Grid Menus topic, for detailed information and sample code on how to add custom menu items to built-in popup menus.

ReadOnly Property


TcxGridPopupMenu.Grid

TcxGridPopupMenu

Specifies the ExpressQuantumGrid control to which the current popup menu belongs.

property Grid: TcxGrid;

Description

Use the Grid property to specify the grid for which the current TcxGridPopupMenu object provides built-in and custom menus.  You should remember that built-in menus are applied to the entire grid control, while custom menus are applied to specific grid views.


TcxGridPopupMenu.HitGridView

TcxGridPopupMenu

Indicates which grid view was clicked.

property HitGridView: TcxCustomGridView;

Description

Use the HitGridView property to access the right-clicked grid view.

ReadOnly Property


TcxGridPopupMenu.HitPoint

TcxGridPopupMenu

Indicates the clicked point.

property HitPoint: TPoint;

Description

Use the HitPoint property to obtain the exact coordinates of a right-click’s occurrence.

ReadOnly Property


TcxGridPopupMenu.HitTest

TcxGridPopupMenu

Provides hit test information.

property HitTest: TcxCustomGridHitTest;

Description

Use the HitTest property to access all information provided by the grid control on each click and obtain the view info of the appropriate element.

ReadOnly Property


TcxGridPopupMenu.HitType

TcxGridPopupMenu

Indicates which element was clicked.

property HitType: TcxGridViewHitType;

Description

Use the HitType property to ascertain which grid view element the menu is to be invoked against.  Unlike the HitTest property, it provides the element name without any additional information.

ReadOnly Property


TcxGridPopupMenu.PopupMenus

TcxGridPopupMenu

Provides a list of available custom menus.

property PopupMenus: TcxPopupMenuInfos;

Description

The PopupMenus property is used to maintain a collection of custom menus.  You can add, delete and insert new menus both at design and runtime.

After adding a new menu you should modify its properties in order to provide proper actions when right-clicking specific grid view elements.


TcxGridPopupMenu.UseBuiltInPopupMenus

TcxGridPopupMenu

Specifies whether built-in menus are available.

property UseBuiltInPopupMenus: Boolean;

Description

Set the UseBuiltInPopupMenus property to True to provide default menus for column header and footer elements.  If other custom menus are assigned to these elements within specific grid views, the default menus are disabled.  Unlike custom menus, which are applied to certain grid views, built-in menus are applied to the entire grid control.

Refer to the Managing Grid Menus topic, for detailed information and sample code on how to add custom menu items to built-in popup menus.

The default value of the UseBuiltInPopupMenus property is True.


TcxGridPopupMenu.RegisterPopupMenu

TcxGridPopupMenu          See Also

Registers a custom menu.

Overloaded Variants

type

  TcxGridOnPopupProc = procedure (ASenderMenu: TComponent; AHitTest: TcxCustomGridHitTest; X,Y: Integer) of object;

  TcxGridViewHitTypes = set of TcxGridViewHitType;

procedure RegisterPopupMenu(const AMenu: TComponent; AHitTypes: TcxGridViewHitTypes; ADoPopupProc: TcxGridOnPopupProc; const AView: TcxCustomGridView); overload; virtual;

procedure RegisterPopupMenu(const AMenu: TComponent; AHitTypes: TcxGridViewHitTypes; ADoPopupProc: TcxGridOnPopupProc; AViewClass: TcxCustomGridViewClass); overload; virtual;

Description

The cxGridPopupMenu component allows you to add custom menus.  At design time, you should use the PopupMenus property in the Object Inspector.  At runtime, you should call the RegisterPopupMenu method, which adds the menu specified by the AMenu parameter.  The AHitTypes parameter determines the grid view elements for which the menu, activated by the mouse right click, is assigned.  Custom menus have a higher priority than built-in menus.  For instance, if you assign a custom menu to a footer element, the default menu with summary types will be disabled.  Unlike built-in menus, custom menus are applied to grid views specified by the AView parameter.

The overloaded method allows you to apply a custom menu to all views of a certain type via the AViewClass parameter.

New custom menus are handled according to the procedure specified by the ADoPopupProc parameter.


TcxGridPopupMenu.UnregisterPopupMenu

TcxGridPopupMenu          See Also

Un-registers a custom menu.

type

  TcxGridViewHitTypes = set of TcxGridViewHitType;

procedure UnregisterPopupMenu(const AMenu: TComponent; const AGridView: TcxCustomGridView; AHitTypes: TcxGridViewHitTypes = []); virtual;

procedure UnregisterPopupMenu(const AMenu: TComponent; AGridViewClass: TcxCustomGridViewClass; AHitTypes: TcxGridViewHitTypes = []); virtual;

Description

The cxGridPopupMenu component allows you to add and remove custom menus.  At design time, you should use the PopupMenus property in the Object Inspector.  At runtime, you should call the UnregisterPopupMenu method to remove the menu specified by the AMenu parameter from the grid view element specified by the AHitTypes parameter.  The AGridView parameter determines the grid view from which the menu is removed.  The overloaded method allows you to remove a custom menu from all view elements of a certain type via the AViewClass parameter.


TcxGridPopupMenu.OnPopup

TcxGridPopupMenu          See Also

Occurs each time a user right-clicks within the grid view element which has an assigned menu.

type

  TcxGridBeforePopupProc = procedure (ASenderMenu: TComponent; AHitTest: TcxCustomGridHitTest; X,Y: Integer; var AllowPopup: Boolean) of object;

property OnPopup: TcxGridBeforePopupProc;

Description

Write an OnPopup event handler to specify the custom action for the invoked menu determined by the ASenderMenu parameter.  It equals to nil when the PopupMenu property is not assigned for the custom popup menu.  The AHitTest parameter provides complete information on the clicked view element.  The X and Y parameters determine the exact right mouse click point.  Set the AllowPopup parameter to True to indicate that a custom popup menu for the specified grid view element should be displayed.  Otherwise, set it to False.  The AlwaysFireOnPopup property determines the order in which the OnPopup events (see also the custom popup menu’s OnPopup event) are fired.

This event is quite similar to the TcxPopupMenuInfo.OnPopup event, but it allows you to handle built-in menus.  You can use this event handler to add new items to the default menus or change their default behavior.


Grid3 and Grid4 Equivalents

See Also

This topic provides a conversion guide for ExpressQuantumGrid4 equivalents to the following ExpressQuantumGrid3 elements:

Grid control	Summary items
TdxDBGrid Properties Methods Events	TdxDBGridSummaryGroups Properties Methods
	TdxDBGridSummaryGroup Properties Methods Events
Bands
TdxTreeListBand Properties Methods	TdxDBGridSummaryItems Properties Methods
TdxTreeListBands Properties Methods	TdxDBGridSummaryItem Properties Methods Events
Columns	Filter
TdxDBGridColumn Properties Methods Events	TdxDBGridFilter Properties Methods
Nodes/Records
TdxDBGridNode Properties Methods

Grid control

The main difference between versions 3 and 4 of the ExpressQuantumGrid is that the latter is capable of displaying data within multiple views.  ExpressQuantumGrid4 provides different views (table, banded table and card views) for displaying data while ExpressQuantumGrid3 provides just one basic table view (which can be displayed with or without bands).  Most of the TdxDBGrid functionality is now implemented by view objects.  Views present data from data fields by means of "items". An Item represents a column in table views and a row in card views.  Refer to the Views and Items sections for more details.

A data controller represented by the view’s DataController property implements data-aware operations such as loading data, filtering, grouping and calculating summaries.  Customizing colors and fonts has been delegated to Style objects and so is implemented now by assigning styles to grid elements.

These changes mean that the multitude of top level properties in the grid have been replaced by a small collection of objects. While these changes provide for a more efficient and extensible product, we recognize that users of ExpressQuantumGrid3 will have initial difficulty in finding the properties required while converting event handlers for ExpressQuantumGrid4 and hence the reason for this topic.

Note: the two technologies are very different so there isn’t always a simple replacement available. While we have tried to cover as many options as possible, the following lists can never be totally complete (you may be using our product in ways we haven’t considered!). If you still have difficulty in replacing your ExpressQuantumGrid3 code because your needs are not covered here, please write to support@devexpress.com and we will help you.

ExpressQuantumGrid3 members	ExpressQuantumGrid4 equivalents

TdxDBGrid Object

Properties
In TCustomdxDBGrid
DataSetChangedBusy	The view’s DataController.Provider.IsDataSetBusy property.
DefaultFields	Fields in ExpressQuantumGrid4 are not automatically retrieved from a data source.  You can use the Retrieve Fields button in the Columns panel of the Component Editor or call the view’s DataController.CreateAllItems method.
Filter	The view’s DataController.Filter and Filtering properties.
GroupColumnCount	The view’s GroupedItemCount property
GroupColumns	The view’s GroupedItems property.
GroupPanelColor	The view’s Styles.GroupByBox property.
GroupPanelFontColor	The view’s Styles.GroupByBox property.
GroupPanelHeight	–
LockRefresh	The view’s DataController.BeginLocate and EndLocate methods allow you to prevent a grid control from excessive reloading of data when navigating through dataset records.  If you need to call the TDataSet.Locate method, enclose this part of the code with BeginLocate and EndLocate. Calling the BeginLocate and EndLocate methods is equivalent to setting the LockRefresh property to True and False respectively.
OptionsBehavior TdxDBGridOptionBehavior = (edgoAnsiSort, edgoAutoCopySelectedToClipboard, edgoAutoSearch, edgoAutoSort, edgoBandButtonClicking, edgoCaseInsensitive, edgoCellMultiSelect, edgoCollapsedReload, edgoDblClick, edgoDragCollapse, edgoDragExpand, edgoDragScroll, edgoEditing, edgoEnterShowEditor, edgoEnterThrough, edgoExtMultiSelect, edgoHeaderButtonClicking, edgoHorzThrough, edgoImmediateEditor, edgoMouseScroll, edgoMultiSelect, edgoMultiSort, edgoSeekDetail, edgoShowHourGlass, edgoStoreToIniFile, edgoStoreToRegistry, edgoTabs, edgoTabThrough, edgoVertThrough);	Equivalents for the various options are described below.
edgoAnsiSort	The dcoAnsiSort option of the view’s DataController.Options property
edgoAutoCopySelectedToClipboard	–
edgoAutoSearch	The view’s OptionsBehavior.IncSearch and item’s Options.IncSearch properties
edgoAutoSort	The view’s OptionsCustomize.ItemSorting (ColumnSorting in a grid table view) and item’s Options.Sorting property.
edgoBandButtonClicking	–
edgoCaseInsensitive	The dcoCaseInsensitive option of the view’s DataController.Options property
edgoCellMultiSelect	–
edgoCollapsedReload	–
edgoDblClick	–
edgoDragCollapse	–
edgoDragExpand	The view’s OptionsBehavior.DragOpening property.
edgoDragScroll	See the view’s OptionsBehavior.DragFocusing and OptionsBehavior.DragScrolling properties.
edgoEditing	The view’s OptionsData.Editing and item’s Options.Editing properties
edgoEnterShowEditor	– If end users are allowed to edit cell values, they can initiate editing of the focused cell by pressing the Enter or Space key, or by typing a new cell value directly.
edgoEnterThrough	The view’s OptionsBehavior.GoToNextCellOnEnter property
edgoExtMultiSelect	End users are allowed to select multiple records from different groups provided that the OptionsSelection.MultiSelect property is set to True.  Setting this property to True is equivalent to enabling both the edgoMultiSelect and edgoExtMultiSelect options in Grid 3.
edgoHeaderButtonClicking	–
edgoHorzThrough	The view’s OptionsBehavior.FocusCellOnCycle property
edgoImmediateEditor	The view’s OptionsBehavior.ImmediateEditor property.
edgoMouseScroll	–
edgoMultiSelect	The view’s OptionsSelection.MultiSelect property.  Setting this property to True is equivalent to enabling both the edgoMultiSelect and edgoExtMultiSelect options in Grid 3.
edgoMultiSort	– End users are allowed to sort the view data by values of multiple columns if the view’s OptionsCustomize.ColumnSorting property is set to True. Setting this property to True is equivalent to enabling both the edgoMultiSort And edgoAutoSort options in Grid 3).
edgoSeekDetail	–
edgoShowHourGlass	–
edgoStoreToIniFile	– See the view’s StoreToIniFile method.
edgoStoreToRegistry	– See the view’s StoreToRegistry method.
edgoTabs	The view’s OptionsBehavior.FocusCellOnTab property
edgoTabThrough	The view’s OptionsBehavior.FocusCellOnCycle and OptionsBehavior.FocusCellOnTab properties
edgoVertThrough	–
OptionsCustomize TdxDBGridOptionCustomize = (edgoBandMoving, edgoBandPanelSizing, edgoBandSizing, edgoColumnMoving, edgoColumnSizing, edgoExtCustomizing, edgoFullSizing, edgoHeaderPanelSizing, edgoKeepColumnWidth, edgoNotHideColumn, edgoRowSizing);	Equivalents for the various options are described below.
edgoBandMoving	The banded table view’s OptionsCustomize.BandMoving and band’s Options.Moving properties.
edgoBandPanelSizing	–
edgoBandSizing	The banded table view’s OptionsCustomize.BandSizing and the band’s Options.Sizing properties.
edgoColumnMoving	The view’s OptionsCustomize.ItemMoving (OptionsCustomize.ColumnMoving in a grid table view) and item’s Options.Moving properties.
edgoColumnSizing	The view’s OptionsCustomize.ColumnHorzSizing and column’s Options.HorzSizing properties.  See also the OptionsCustomize.ColumnVertSizing and Options.VertSizing properties which are available for banded table views.
edgoExtCustomizing	The (banded) table view’s OptionsCustomize.ColumnHiding property.
edgoFullSizing	–
edgoHeaderPanelSizing	–
edgoKeepColumnWidth	–
edgoNotHideColumn	See the view’s OptionsCustomize.ColumnHidingOnGrouping property.
edgoRowSizing	In a banded table view, the row height can be adjusted by changing the height of column headers displayed within the bands.  To enable this, set the OptionsCustomize.ColumnVertSizing property of a banded table view to True.
OptionsDB TdxDBGridOptionDB = (edgoCanAppend, edgoCancelOnExit, edgoCanDelete, edgoCanInsert, edgoCanNavigation, edgoConfirmDelete, edgoLoadAllRecords, edgoPartialLoad, edgoResetColumnFocus, edgoSmartRefresh, edgoSmartReload, edgoSyncSelection, edgoUseBookmarks, edgoUseLocate);	Equivalents for the various options are described below.
edgoCanAppend	The view’s OptionsData.Appending property
edgoCancelOnExit	The view’s OptionsData.CancelOnExit property
edgoCanDelete	The view’s OptionsData.Deleting property
edgoCanInsert	The view’s OptionsData.Inserting property
edgoCanNavigation	The view’s DataController.DataModeController.SyncMode property.
edgoConfirmDelete	The view’s OptionsData.DeletingConfirmation property
edgoLoadAllRecords	By default, ExpressQuantumGrid4 loads all records into memory.  To limit the number of records loaded at a time, see the view’s DataController.DataModeController.GridMode property
edgoPartialLoad	You can use the Grid Mode to limit the number of records loaded into memory at a time.  See the view’s DataController.DataModeController.GridMode property
edgoResetColumnFocus	The view’s OptionsBehavior.FocusFirstCellOnNewRecord property
edgoSmartRefresh	The view’s DataController.DataModeController.SmartRefresh property
edgoSmartReload	–
edgoSyncSelection	The view’s DataController.DataModeController.SyncMode property
edgoUseBookmarks	–
edgoUseLocate	– The Locate method is always used if key field names are specified via the view’s DataController.KeyFieldNames property.
OptionsView TdxDBGridOptionView = (edgoAutoCalcPreviewLines, edgoAutoHeaderPanelHeight, edgoAutoWidth, edgoBandHeaderWidth, edgoDrawEndEllipsis, edgoHideFocusRect, edgoHotTrack, edgoIndicator, edgoInvertSelect, edgoPreview, edgoRowAutoHeight, edgoRowSelect, edgoShowButtonAlways, edgoUseBitmap);	Equivalents for the various options are described below.
edgoAutoCalcPreviewLines	The (banded) table view’s Preview.AutoHeight property.
edgoAutoHeaderPanelHeight	–
edgoAutoWidth	The (banded) table view’s OptionsView.ColumnAutoWidth property.
edgoBandHeaderWidth	–
edgoDrawEndEllipsis	The following properties affect ellipsis displaying when clipping occurs: OptionsView.BandHeaderEndEllipsis OptionsView.HeaderEndEllipsis OptionsView.RowCaptionEndEllipsis OptionsView.CellEndEllipsis
edgoHideFocusRect	–
edgoHotTrack	–
edgoIndicator	The view’s OptionsView.Indicator property
edgoInvertSelect	The view’s OptionsSelection.InvertSelect property
edgoPreview	The view’s Preview.Visible property
edgoRowAutoHeight	The view’s OptionsView.CellAutoHeight property
edgoRowSelect	The view’s OptionsSelection.CellSelect property
edgoShowButtonAlways	The view’s OptionsView.ShowEditButtons property
edgoUseBitmap	–
PartialLoad	ExpressQuantumGrid4 does not provide PartialLoad mode. You can use the Grid Mode to limit the number of records loaded into memory at a time.  See the view’s DataController.DataModeController.GridMode property.
PartialLoadBufferCount	ExpressQuantumGrid4 does not provide PartialLoad mode. ExpressQuantumGrid4 provides the Grid mode for limiting the number of records loaded into memory at a time.  Use the DataController.DataModeController.GridModeBufferCount to specify the buffer size.
ShowGroupPanel	The view’s OptionsView.GroupByBox property
ShowSummaryFooter	The view’s OptionsView.Footer property.
SummaryGroups	All summaries are set via the view’s DataController.Summary property.  Summary groups are provided by the Summary.SummaryGroups collection.  To create default summary groups, use the Summary.DefaultGroupSummaryItems property.
SummarySeparator	The TcxDataGroupSummaryItems.Separator property.
UseBookmarks	When in grid mode, bookmarks are stored automatically for the selected records and can be accessed via the view’s DataController.GetSelectedBookmark function. When not in grid mode, bookmarks are not stored.
Derived from TCustomdxDBTreeListControl
Columns	The Items property declared in a base view class. Specific view classes provide the Columns (in a grid table and banded table views) and Rows properties (in a card view) as equivalents (the Items collection).
DataLink	–
DataSource	The view’s DataController.DataSource property in data-aware views and DataController.CustomDataSource in non data-aware views.
FocusedField	You can access a focused item (column in a grid table view or row in a card view) using the view’s Controller.FocusedItem property.  To access the field linked to the item, see the item’s DataBinding.Field property.
GrIndicatorWidth	The view’s OptionsView.IndicatorWidth property.
KeyField	The view’s DataController.KeyFieldNames property.
PreviewFieldName	The view’s Preview.Column property.
PreviewMaxLength	–
SelectedRows	The view’s DataController.GetSelectedBookmark function (in grid mode only).
SortedColumn	The first element of the SortedItems collection.
SortedColumns	The (banded) table view’s SortedItems property.
VisibleColumns	The view’s VisibleItems property.  Views publish the VisibleColumns (in grid table and grid banded table views) and VisibleRows (in a card view) properties and these provide access to the same items as VisibleItems.
Derived from TCustomdxTreeListControl
BandMaxRowCount	–
BandRowCount	The BandHeaderLineCount property (banded table views only).
Bands	The Bands property (banded table views only).
ColumnCount	The view’s ItemCount property.
DefaultLayout	–
HeaderMinRowCount	– See the view’s HeaderHeight property.
HeaderPanelMaxRowCount	–
HeaderPanelRowCount	The (banded) table view’s OptionsView.HeaderHeight property.
IniFileName	–
IniSectionName	–
RegistryPath	–
SortedColumnCount	The view’s SortedItemCount property.
VisibleColumnCount	The VisibleItemCount property in a base view class.  In a grid (banded) table view and card view, you can use the VisibleColumnCount and VisibleRowCount properties respectively.
Derived from TCustomdxTreeList	Note: Grid3 provided a treelist control also and the grid itself was based on nodes. Grid4 does not use nodes and the ExpressQuantumTreeList is now a separate product (under development – Sept 2002).
ArrowsColor	–
AutoExpandOnSearch	Group rows are always expanded on finding a record during an incremental search.
AutoSearchColor	The view’s Styles.IncSearch property.
BandButtonPushed	–
BandColor	The Styles.BandHeader property (banded table views only) and the band’s Styles.Header property.
BandFont	The Styles.BandHeader property (banded table views only) and the band’s Styles.Header property.
BandPanelHeight	–
BorderStyle	–
Count	– See the view’s ViewData.Records property to get the collection of all records currently displayed.  To know whether a particular record is at the root nesting level, see its Level property.
CustomizingBandListBox	–
CustomizingForm	The view’s Controller.CustomizationForm property.
CustomizingHeaderListBox	–
CustomizingPos	The view’s Controller.CustomizationFormBounds property. You can also use the Left, Top, Width and Height properties of the object obtained via the Controller.CustomizationForm property.
CustomizingRowCount	–
DblClkExpanding	Double-clicking group rows always expands/collapse the corresponding group. The view’s TcxGridTableOptionsBehavior.ExpandMasterRowOnDblClick property allows you to prevent expanding/collapsing of master rows on a double-click event.
DefaultRowHeight	The view’s OptionsView.DataRowHeight property.
DescTextHeight	–
DownBandIndex	–
DownBandPushed	–
DownColumnIndex	–
DownColumnPushed	–
DragAbsoluteBandIndex	–
DragAbsoluteHeaderIndex	–
DragNode	–
EditingText	Use the view’s Controller.EditingItem property to access the item (column in a grid table view or card in a card view) being edited.  The EditValue property of the item specifies its value. Alternatively you can use the view’s Controller.FocusedRecord.DisplayTexts property to get the text representation of an individual item’s value within the currently focused record.
FixedBandLineColor	The view’s OptionsView.FixedBandSeparatorColor property.
FixedBandLineWidth	The view’s OptionsView.FixedBandSeparatorWidth property.
FocusedAbsoluteIndex	The view’s Controller.FocusedItemIndex property.
FocusedColumn	The view’s Controller.FocusedItem property.
FocusedNode	The view’s Controller.FocusedRecord property.
FocusedNumber	The view’s Controller.FocusedRecord.Index property.
FooterPanelHeight	–
FooterRowHeight	–
FooterRowNodeHeight	–
GridLineColor	The view’s OptionsView.GridLineColor property.
GroupNodeColor	The view’s Styles.Group property.
GroupNodeTextColor	The view’s Styles.Group property.
HeaderButtonPushed	–
HeaderColor	The view’s Styles.Header and the column’s Styles.Header properties
HeaderFont	The view’s Styles.Header and the column’s Styles.Header properties
HeaderHeight	The view’s HeaderHeight property.
HeaderPanelHeight	The view’s HeaderHeight property.
HeaderRowHeight	–
HideFocusRect	The view’s OptionsSelection.HideFocusRect property.
HideSelection	The view’s OptionsSelection.HideSelection property.
HideSelectionColor	The view’s Styles.Inactive property.
HideSelectionTextColor	The view’s Styles.Inactive property.
HighlightColor	The view’s Styles.Selection property.
HighlightTextColor	The view’s Styles.Selection property.
IndentDesc	The Preview.LeftIndent and Preview.RightIndent properties provide the two indents.
InplaceColumnIndex	The view’s Controller.EditingItem.Index property. Check the Controller.IsEditing property to see whether a cell is currently being edited.
InplaceEditor	The view’s Controller.EditingController.Edit property. The view’s Controller.EditingItem.GetProperties method provides access to the properties of the editor (and these vary depending on the editor’s type).
IsCustomizing	The view’s Controller.Customization property.
Items	The view’s ViewData.Records property.
LastNode	Use the view’s ViewData.Records property to access any record within a view.
LeftCoord	The view’s Controller.LeftPos property.
LookAndFeel	The LookAndFeel property.
MaxRowLineCount	The view’s OptionsView.CellTextMaxLineCount property.
NewItemRowHeight	–
PreviewFont	The view’s Styles.Preview property.
PreviewLines	The (banded) table view’s Preview.MaxLineCount property.
RowFooterColor	The Styles.Footer property specifies the style for both the footer and group footer panels.  You can specify different styles for these panels by handling the Styles.OnGetFooterStyle event.
RowFooterTextColor	The Styles.Footer property specifies the style for both footer and group footer panels.  You can specify different styles for these panels by handling the Styles.OnGetFooterStyle event.
RowHeight	Use the view’s ViewInfo.RecordsViewInfo[ARowIndex].Height property. ARowIndex specifies the position of the required record among all visible records within a view
RowSeparatorLineWidth	The view’s OptionsView.RowSeparatorWidth property.
ScrollBars	The view’s OptionsView.ScrollBars property.
SelectedCount	The view’s Controller.SelectedRecordCount property.
SelectedNodes	The view’s Controller.SelectedRecords property.
ShowBands	The OptionsView.BandHeaders property of a banded table view.
ShowGrid	The view’s OptionsView.GridLines property allows you to specify which grid lines to display.
ShowHeader	The view’s OptionsView.Header property.
ShowHiddenInCustomizeBox	–
ShowNewItemRow	The view’s OptionsView.NewItemRow property.
ShowPreviewGrid	The view’s OptionsView.GridLines property allows you to specify which grid lines to display.
ShowRowFooter	The view’s OptionsView.GroupFooters property.
SimpleCustomizeBox	–
State	–
TopIndex	The view’s Controller.TopRecordIndex property.
TopNode	The view’s ViewData.Records[0] value.
TopVisibleNode	The view’s ViewData.Records[GridView1.Controller.TopRecordIndex] value.
WaitForExpandNodeTime	The grid’s DragOpeningWaitTime property.
Methods
In TdxDBGrid
SaveToHTML	The global ExportGridToHTML procedure.
SaveToText	The global ExportGridToText procedure.
SaveToXLS	The global ExportGridToExcel procedure.
SaveToXML	The global ExportGridToXML procedure.
Derived from TCustomdxDBGrid
AddGroupColumn	Set the GroupIndex property of the desired column to a value greater than or equal to the GroupedColumnCount property value.
BeginGrouping	The view’s BeginUpdate method.
CanAddGroupColumn	–
DeleteGroupColumn	– Set the column’s GroupIndex property to –1 for that purpose.
EndGrouping	The view’s EndUpdate method.
FindNodeByKeyValue	The view’s DataController.FindRecordIndexByKey function.
GetGroupColumnAt	Use the ViewInfo.GetHitTest method. This returns an object with information on the grid element containing the specified coordinates. The following code shows how you can determine whether a given point belongs to the header of a column.  If so, AColumn is assigned to this column. var   AHitTest: TcxCustomGridHitTest;   AColumn: TcxGridColumn; //... AHitTest := cxGrid1.ViewInfo.GetHitTest(X, Y); if AHitTest is TcxGridColumnHeaderHitTest then   AColumn := TcxGridColumnHeaderHitTest(AHitTest).Column; See the column’s GroupIndex property value to see whether data is grouped by this column.
GetNodeFooterColumnAt	Use the ViewInfo.GetHitTest method. This returns an object with information on the grid element containing the specified coordinates. The following code determines the column referenced within the group footer. var   AHitTest: TcxCustomGridHitTest;   AColumn: TcxGridColumn; //... AHitTest := cxGrid1.ViewInfo.GetHitTest(X, Y); if AHitTest is TcxGridGroupFooterCellHitTest then   AColumn := TcxGridGroupFooterCellHitTest(AHitTest).Column;
GetSummaryGroupByName	–
GetSummaryItemAt	–
InsertGroupColumn	Set the column’s GroupIndex property to a value between 0 and GroupedColumnCount – 1.
IsGridMode	The view’s DataController.IsGridMode function.
IsPartialLoad	ExpressQuantumGrid4 does not provide the PartialLoad mode.  Use Grid Mode to limit the number of records loaded into memory at once.
PointInFooterPanel	See the view’s ViewInfo.GetHitTest.HitTestCode function.  If the specified point belongs to the footer panel, it returns htFooter.
PointInGroupPanel	See the view’s ViewInfo.GetHitTest.HitTestCode function.  If the specified point belongs to the group panel, it returns htGroupByBox.
RebuildGroupIndexes	–
RefreshGroupColumns	The view’s DataController.Summary.Calculate method.
Derived from TCustomdxDBTreeListControl
ClearGroupColumns	The view’s DataController.Groups.ClearGrouping method.
ColumnByFieldName	In (banded) table views, see the GetColumnByFieldName method.  In card views, the equivalent is GetRowByFieldName.  Note that these methods do not throw an exception if no items found linked to the specified field.
ColumnByName	The view’s FindItemByName method.
CreateColumnEx	– Use the view’s CreateItem (CreateColumn in a grid (banded) table view, CreateRow in a card view) method to add a new column.  To specify an editor for the item, see the PropertiesClass and RepositoryItem properties.
CreateColumn	– See the view’s CreateItem method to add a new item.  In table and card views, you use the CreateColumn and CreateRow methods respectively. These implement the same functionality, but differ from CreateItem by the class of the returned object.
FindColumnByFieldName	In (banded) table views, see the GetColumnByFieldName method.  In card views, the equivalent is GetRowByFieldName.
FullRefresh	Call the view’s DataController.UpdateItems method with False as a parameter.
GetColumnAt	Use the ViewInfo.GetHitTest method. This returns an object with information on the grid element with the coordinates specified. For instance, the following code determines the item (column) at point (X,Y) if the point relates to a record or to the column header panel. var   AHitTest: TcxCustomGridHitTest;   AItem: TcxCustomGridTableItem; //... AHitTest := cxGrid1.ViewInfo.GetHitTest(X, Y); if AHitTest is TcxGridRecordCellHitTest then   AItem := TcxGridRecordCellHitTest(AHitTest).Item else   if AHitTest is TcxGridColumnHeaderHitTest then     AItem := TcxGridColumnHeaderHitTest(AHitTest).Column;
GetDefaultColumnClass	When the item’s ValueTypeClass property is set, this value determines the default editor assigned to the item.  An example of registering a default editor follows: GetDefaultEditDataRepositoryItems.RegisterItem(TcxBooleanValueType, cxEditRegisteredItemsStandardVersion, GetDefaultEditRepository.CreateItem(TcxEditRepositoryCheckBoxItem)); Here, a check box is registered as the editor for items with the value type of TcxBooleanValueType. To redefine the default editor for this value type, call the RegisterItem procedure passing it the required repository item instead of TcxEditRepositoryCheckBoxItem.  The second parameter of the procedure specifies the priority of the registered editor.  To redefine the existing editor, you must set the parameter to a value greater than the cxEditRegisteredItemsStandardVersion. If an item is assigned to a value type not registered by RegisterItem, its editor is determined by the RegisterDefaultItem method: GetDefaultEditDataRepositoryItems.RegisterDefaultItem(cxEditRegisteredItemsStandardVersion, GetDefaultEditRepository.CreateItem(TcxEditRepositoryTextItem)); If you need to use a different editor, call RegisterDefaultItem passing it another repository item instead of TcxEditRepositoryTextItem.  Like the RegisterItem method, set the first parameter to a value greater than the cxEditRegisteredItemsStandardVersion constant.
GetDefaultFieldColumnClass	In data-aware views, items (columns in a table view and cards in a card view) are assigned default editors based on the field type. An example of registering a default editor follows: GetDefaultEditDBRepositoryItems.RegisterItem(ftCurrency, cxEditRegisteredItemsStandardVersion, GetDefaultEditRepository.CreateItem(TcxEditRepositoryCurrencyItem)); Here, a currency editor represented by the TcxEditRepositoryCurrencyItem class is registered as an editor for currency fields. The first parameter specifies a value of the TFieldType enumerator.  The second parameter specifies the priority of the registered editor.  To redefine the existing editor, you must set the parameter to a value greater than the cxEditRegisteredItemsStandardVersion. If an item is assigned to a field not registered by the RegisterItem method, its editor is determined by the RegisterDefaultItem method: GetDefaultEditDBRepositoryItems.RegisterDefaultItem(cxEditRegisteredItemsStandardVersion, GetDefaultEditRepository.CreateItem(TcxEditRepositoryMaskItem)); If you need to use a different editor, call RegisterDefaultItem passing it a another repository item instead of TcxEditRepositoryMaskItem.  Like the RegisterItem method, set the first parameter to a value greater than the cxEditRegisteredItemsStandardVersion constant.
GetFooterColumnAt	Use the ViewInfo.GetHitTest method. This returns an object with information on the grid element containing the specified coordinates. The following code determines a particular column within the footer panel. var   AHitTest: TcxCustomGridHitTest;   AColumn: TcxGridColumn; //... AHitTest := cxGrid1.ViewInfo.GetHitTest(X, Y); if AHitTest is TcxGridFooterCellHitTest then   AColumn := TcxGridFooterCellHitTest(AHitTest).Column;
GetHeaderColumnAt	Use the ViewInfo.GetHitTest method. This returns an object with information on the grid element containing the specified coordinates. The following code shows how you can determine whether a given point is within a column header.  If so, AColumn is assigned to this column: var   AHitTest: TcxCustomGridHitTest;   AColumn: TcxGridColumn; //... AHitTest := cxGrid1.ViewInfo.GetHitTest(X, Y); if AHitTest is TcxGridColumnHeaderHitTest then   AColumn := TcxGridColumnHeaderHitTest(AHitTest).Column;
RefreshBookmarks	–
Derived from TCustomdxTreeListControl
ApplyBestFit	The item’s ApplyBestFit method.  To adjust the width of all view columns, call the view’s ApplyBestFit method.
AssignColumns	The view’s Assign method.
BeginSorting	The view’s BeginUpdate method.
DestroyColumns	The view’s ClearItems method.
EndSorting	The view’s EndUpdate method.
GetAbsoluteColumnIndex	The Index property of the desired item.  To access an item by its position among the visible items, use the view’s VisibleItems property.
GetBandAt	Use the ViewInfo.GetHitTest method. This returns an object with information on the grid element containing the specified coordinates. The following code gets the band at a specific point provided that it is within the band header panel: var   AHitTest: TcxCustomGridHitTest;   ABand: TcxGridBand; //... AHitTest := cxGrid1.ViewInfo.GetHitTest(X, Y); if AHitTest is TcxGridBandHeaderHitTest then   ABand := TcxGridBandHeaderHitTest(AHitTest).Band;
GetColumnAt	Use the ViewInfo.GetHitTest method. This returns an object with information on the grid element containing the specified coordinates. For instance, the following code determines the item (column) at point (X,Y) if the point is within a record or the column header panel. var   AHitTest: TcxCustomGridHitTest;   AItem: TcxCustomGridTableItem; //... AHitTest := cxGrid1.ViewInfo.GetHitTest(X, Y); if AHitTest is TcxGridRecordCellHitTest then   AItem := TcxGridRecordCellHitTest(AHitTest).Item else   if AHitTest is TcxGridColumnHeaderHitTest then     AItem := TcxGridColumnHeaderHitTest(AHitTest).Column;
GetDisplayValue	The TcxCustomGridRecord.DisplayTexts property provides the text representation of a value stored in a particular record field.
GetVisibleColumnIndex	The VisibleIndex property of the desired item.  To access an individual item by its absolute index, see the view’s Items property (Columns in a (banded) table view or Rows in a card view).
LoadFromIniFile	The view’s RestoreFromIniFile method.
LoadFromRegistry	The view’s RestoreFromRegistry method.
RefreshDefaultColumnsWidths	– The RestoreDefaults method, declared in view and item classes, allows you to restore the default column widths.
RefreshSorting	–
RestoreColumnsDefaults	– The RestoreDefaults method declared in the view and item classes allows you to restore the default column widths and captions.
SaveToIniFile	The view’s StoreToIniFile method.
SaveToRegistry	The view’s StoreToRegistry method.
Derived from TCustomdxTreeList
Add	The view’s DataController.AppendRecord method.
AddFirst	–
AdjustColumnsWidth	– The view’s OptionsView.ColumnAutoWidth property
BeginSelection	–
BeginUpdate	The BeginUpdate method declared in the TcxCustomGrid, TcxCustomGridView, TcxCustomDataController, TcxDataSummary and TcxFilterCriteria classes.
CalcDrawInfo	–
CancelEditor	Call the view’s Controller.EditingController.HideEdit method passing False as the Accept parameter.
CellRect	Use code like this to access a particular cell region within a record: (cxGrid1TableView1.ViewInfo.RecordsViewInfo[AIndex] as TcxGridDataRowViewInfo).GetBoundsForItem(AItem); AIndex specifies the TcxCustomGridRecord.Index property value.  AItem is an item (column in a (banded) table view and row in a card view) to which the required cell belongs.
ClearColumnsSorted	The view’s DataController.ClearSorting method.
ClearNodes	In unbound mode, set the view’s DataController.RecordCount property to 0.
CloseEditor	Call the view’s Controller.EditingController.HideEdit method passing True as the Accept parameter.
ColumnCalcLineCount	–
ColumnsCustomizing	The view’s Controller.Customization property.
CopyAllToClipboard	Call the view’s CopyToClipboard method passing True as the ACopyAll parameter.
CopySelectedToClipboard	Call the view’s CopyToClipboard method passing False as the ACopyAll parameter.
EndColumnsCustomizing	The view’s Controller.Customization property.
EndSearch	The view’s Controller.CancelIncSearching method.
EndSelection	–
EndUpdate	The EndUpdate method declared in the TcxCustomGrid, TcxCustomGridView, TcxCustomDataController, TcxDataSummary and TcxFilterCriteria classes.
FreeDrawInfo	–
FullCollapse	The view’s ViewData.Collapse method lets you collapse group and master rows within a view. The view’s DataController.Groups.FullCollapse method collapses group rows.
FullExpand	The view’s ViewData.Expand method lets you expand group and master rows within a view. The view’s DataController.Groups.FullExpand method expands group rows.
GetEditRect	Use the code as follows (cxGrid1TableView1.ViewInfo.RecordsViewInfo[AIndex] as TcxGridDataRowViewInfo).GetCellViewInfoByItem(AItem).ContentBounds; AIndex specifies the record index defined by the TcxCustomGridRecord.Index property.  AItem refers to the item (column in a (banded)table view and row in a card view).
GetFocusedAbsoluteIndex	Use the view’s Controller.FocusedItem.Index property.
GetFocusedVisibleIndex	Use the view’s Controller.FocusedItemIndex or Controller.FocusedItem.VisibleIndex property.
GetHitInfo	See the view’s ViewInfo.GetHitTest method. This returns an object with information on a grid element (a TcxCustomGridHitTest class descendant) at specific coordinates.  You can determine the type of the element via the HitTestCode function of the object obtained.
GetHitTestInfoAt	See the view’s ViewInfo.GetHitTest method. This returns an object with information on a grid element (a TcxCustomGridHitTest class descendant) at specific coordinates.  You can determine the type of the element via the HitTestCode function of the object returned.
GetNextVisible	– The view’s ViewData.Records property provides access to all records currently displayed within a view.  A record can be obtained from this collection by its Index property as it identifies the visual position of the record within a view.  For instance, you can use the code below to access the record following the ACurrentRecord: ANextRecord := view1.ViewData.Records[ACurrentRecord.Index + 1];
GetNodeAt	Use the ViewInfo.GetHitTest method. This returns an object with information on the grid element containing the specified coordinates. The following code determines the record at the (X,Y) point if it falls within the content area: var   AHitTest: TcxCustomGridHitTest;   ARecord: TcxCustomGridRecord; //... AHitTest := cxGrid1.ViewInfo.GetHitTest(X, Y); if AHitTest is TcxGridRecordHitTest then   ARecord := TcxGridRecordHitTest(AHitTest).GridRecord;
GotoFirst	The view’s Controller.GoToFirst method.
GotoLast	The view’s Controller.GoToLast method.
GotoNext	The view’s Controller.GoToNext method.
GotoPrev	The view’s Controller.GoToPrev method.
HeaderPanelBestFit	–
HideEditor	– Call the view’s Controller.EditingController.HideEdit method passing True as the Accept parameter.
IndexOf	– Use the Index property of a TcxCustomGridRecord object to get the position of the record.
Insert	In unbound mode, use the view’s DataController.InsertRecord method to insert a new record above the record specified as the method’s parameter. In bound mode, you should use the methods of the dataset object to which the view is connected by means of a TDataSource object (for instance, the Insert method of a TDataSet descendant).
IsInvertSelect	The view’s OptionsSelection.InvertSelect property.
IsNodeVisible	The Visible property of a TcxCustomGridRecord object.
MakeBandVisible	–
MakeColumnVisible	The view’s Controller.MakeItemVisible method.
MakeNodeVisible	1. The view’s Controller.MakeRecordVisible method. 2. The MakeVisible method of a TcxCustomGridRecord object. You can also make a master row owning a specific detail view visible via the MakeMasterGridRecordVisible method.
PointInCustomizingForm	See the view’s ViewInfo.GetHitTest.HitTestCode function.  If the specified point belongs to the customization form, it returns the htCustomizationForm constant value.
SaveAllToStrings	–
SaveAllToTextFile	–
SaveSelectedToStrings	–
SaveSelectedToTextFile	See the ExportGridToText procedure.
ShowButtonEditorMouse	See the view’s Controller.EditingController.ShowEdit method.
ShowEditorChar	See the view’s Controller.EditingController.ShowEdit method.
ShowEditor	See the view’s Controller.EditingController.ShowEdit method. Alternatively, you can set the view’s Controller.EditingItem property to open the editor for a specific item within the currently focused record.
ShowEditorMouse	See the view’s Controller.EditingController.ShowEdit method.
StartSearch	To start an incremental search, assign a string to the view’s Controller.IncSearchingText property.
Derived from TCustomdxContainer
HideDrawFocusRect	The view’s OptionsSelection.HideFocusRect property.
IsShowButtonAlways	The view’s OptionsView.ShowEditButtons property.
Events
Derived from TCustomdxDBGrid
OnAddGroupColumn	ExpressQuantumGrid4 does not provide an event to allow you to control column grouping.  You can prevent grouping by a particular column though by using the column’s Options.Grouping property.
OnBackgroundDrawEvent	See the view’s OnCustomDrawPartBackground event.
OnClearNodeData	–
OnColumnClick	The column’s OnHeaderClick event.
OnColumnSorting	ExpressQuantumGrid4 does not provide an event to allow you to control column sorting. The column’s Options.Sorting property can be used to prevent a user from sorting by the column.
OnCustomDraw	The OnCustomDrawCell event provided by view and item objects.
OnEndDragGroupColumn	ExpressQuantumGrid4 does not provide an event to allow you to control column grouping. Use the column’s Options.Grouping property to prevent the grouping by that column.
OnFilterChanged	The view’s DataController.Filter.OnBeforeChange event.
OnEnumFilterValues	The column’s OnGetFilterValues or view’s DataController.Filter.OnGetValueList event.
OnGetCustomSummaryText	–
OnHideColumn	The view’s OnColumnPosChanged event.
OnReloadGroupList	The view’s DataController.OnGroupingChanged event.
OnShowColumn	The view’s OnColumnPosChanged event.
OnSummaryNode	The TcxDataSummaryItems.OnSummary event provided by the FooterSummaryItems, DefaultGroupSummaryItems properties and by every summary group in the SummaryGroups collection.
Derived from TCustomdxDBTreeListControl
OnBeforeCalcSummary	–
OnCalcSummary	The view’s DataController.Summary.OnAfterSummary event.
OnChangeNodeEx	– The view’s OnFocusedRecordChanged event.
OnGetEditColor	See the Styles.OnGetContentStyle event provided by view and item objects.
OnGetPreviewText	The OnGetDisplayText event of the column assigned to the (banded) table view’s Preview.Column property.
OnRefreshNodeData	–
Derived from TCustomdxTreeListControl
OnBandButtonClick	–
OnBandClick	The TcxGridBand.OnHeaderClick event.
OnCalcRowLineHeight	–
OnCanBandDragging	ExpressQuantumGrid4 does not provide an event allowing you to control band dragging. You can prevent a user from a dragging a band by setting the view’s OptionsCustomize.BandMoving or the band’s Options.Moving property to False.
OnCanHeaderDragging	ExpressQuantumGrid4 does not provide an event allowing you to control column dragging. The view’s OptionsCustomize.ColumnMoving and the item’s Options.Moving properties can be set to False to prevent the dragging of column(s).
OnChangedColumnsWidth	The view’s OnColumnSizeChanged event.
OnColumnClick	The column’s OnHeaderClick event.
OnColumnMoved	The column’s OnColumnPosChanged event.
OnCustomDraw	The OnCustomDrawCell event provided by view and item objects.
OnCustomDrawBand	The view’s OnCustomDrawBandHeader event.
OnCustomDrawCell	The OnCustomDrawCell event provided by view and item objects.
OnCustomDrawColumnHeader	The view’s OnCustomDrawColumnHeader event.
OnCustomDrawFooter	The view’s OnCustomDrawFooterCell event.
OnCustomDrawFooterNode	The view’s OnCustomDrawFooterCell event.
OnCustomDrawPreview	The OnCustomDrawCell event provided by view and item objects.
OnCustomDrawPreviewCell	The OnCustomDrawCell event provided by view and item objects.
OnDragEndBand	– Handle the view’s OnBandPosChanged event for writing code after a band’s position has changed.
OnDragEndHeader	– Handle the view’s OnColumnPosChanged event for writing code after a column’s position has changed
OnDragOverBand	–
OnDragOverHeader	–
OnEndDragColumn	–
OnGetLevelColor	The view’s Styles.OnGetGroupStyle event.
OnGetNodeDragText	–
OnHeaderButtonClick	–
OnHeaderMoved	The view’s OnColumnPosChanged event.
OnHideBand	– The OnBandPosChanged event declared in a banded table view.
OnHideHeader	– The view’s OnColumnPosChanged event.
OnIsExistFooterCell	–
OnShowBand	– The OnBandPosChanged event declared in a banded table view.
OnShowHeader	– The view’s OnColumnPosChanged event.
OnStartBandDragging	–
OnStartHeaderDragging	–
Derived from TCustomdxTreeList
OnBeginDragNode	–
OnCanNodeSelected	The view’s OnCanSelectRecord event.
OnChangeColumn	The view’s OnFocusedItemChanged event.
OnChangeLeftCoord	The view’s OnLeftPosChanged event.
OnChangeNode	The view’s OnFocusedRecordChanged event.
OnChangeTopVisibleNode	The view’s OnTopRecordIndexChanged event.
OnCollapsed	–
OnCollapsing	–
OnCompare	The view’s DataController.OnCompare event.
OnDeletion	–
OnEditChange	The view’s OnEditChanged event.
OnEdited	–
OnEditing	The view’s OnEditing event.
OnEditValidate	Handle the OnValidate event of the editor assigned to an item.
OnEndColumnsCustomizing	–
OnExpanded	–
OnExpanding	–
OnHotTrackNode	–
OnSelectedCountChange	The view’s OnSelectionChanged event.
Bands

Unlike the previous version of the grid control, ExpressQuantumGrid4 does not contain bands by default.  Instead, it provides banded table views (TcxGridBandedTableView and TcxGridDBBandedTableView).  A banded table view contains the Bands property providing a collection of TcxGridBand objects.

ExpressQuantumGrid3 members	ExpressQuantumGrid4 equivalents
TdxTreeListBand Object

Properties
In TdxTreeListBand
Alignment	The TcxGridBand.Alignment property.
Caption	The TcxGridBand.Caption property.
DisableCustomizing	The TcxGridBand.VisibleForCustomization property.
DisableDragging	The band’s Options.Moving property.
Fixed	The TcxGridBand.FixedKind property.
HeaderColCount	The Count property of a band row within a banded table view.  To access a particular band’s row, use code as follows bandedTableView1.Bands[ABandIndex].Rows[RowIndex]
HeaderColumn	The Items property of a band row within a banded table view.  To access a particular band’s row, use code as follows: bandedTableView1.Bands[ABandIndex].Rows[RowIndex]
HeaderRowCount	The band’s Rows.Count property.
MinWidth	To specify the minimum width of a band, set the minimum width (the MinWidth property) of the columns displayed within the band.
OnlyOwnColumns	–
Sizing	The band’s Options.Sizing property.
Visible	The Visible property of a band within a banded table view.  Individual bands can be accessed via the banded table view’s Bands property.
VisibleIndex	The VisibleIndex property of a band within a banded table view.  Individual bands can be accessed via the banded table view’s Bands property.
Width	The Width property of a band within a banded table view.  Individual bands can be accessed via the banded table view’s Bands property.
Methods
In TdxTreeListBand
RestoreDefaults	–
TdxTreeListBands Object

Properties
In TdxTreeListBands
Items	The TcxGridBands.Items property.
TreeList	Bands belong to a view specified by the TcxGridBands.GridView property.
VisibleCount	The TcxGridBands.VisibleCount property.
VisibleItems	The TcxGridBands.VisibleItems property.
Methods
In TdxTreeListBands
Add	The TcxGridBands.Add method.
GetAbsoluteIndex	–
GetVisibleIndex	–
RestoreDefaults	–

Columns

Every view provided by ExpressQuantumGrid4 contains a collection of view specific items (columns in a (banded) table view and rows in a card view) displaying data from particular fields.  Unlike the previous version of the grid control, ExpressQuantumGrid4 does not provide different column types.  Instead, you should use the item’s properties (RepositoryItem or PropertiesClass) to specify the editor type used to edit the item’s data.  You can refer to the Data Editing Using Inplace Editors section for more information.

ExpressQuantumGrid4 provides different repository items corresponding to the ExpressQuantumGrid3 columns. These repository items can be used to specify the in-place editor type:

ExpressQuantumGrid3 members	ExpressQuantumGrid4 equivalents
ExpressQuantumGrid3 columns	Repository items
TdxDBGridColumn	TcxEditRepositoryTextItem
TdxDBGridBlobColumn	TcxEditRepositoryBlobItem
TdxDBGridButtonColumn	TcxEditRepositoryButtonItem
TdxDBGridCalcColumn	TcxEditRepositoryCalcItem
TdxDBGridCheckColumn	TcxEditRepositoryCheckBoxItem
TdxDBGridCurrencyColumn	TcxEditRepositoryCurrencyItem
TdxDBGridDateColumn	TcxEditRepositoryDateItem
TdxDBGridDropDownColumn	–
TdxDBGridExtLookupColumn	TcxEditRepositoryExtLookupComboBoxItem
TdxDBGridGraphicColumn	TcxEditRepositoryImageItem
TdxDBGridHyperLinkColumn	TcxEditRepositoryHyperLinkItem
TdxDBGridImageColumn	TcxEditRepositoryImageComboBoxItem
TdxDBGridLookupColumn	TcxEditRepositoryLookupComboBoxItem
TdxDBGridMaskColumn	TcxEditRepositoryMaskItem
TdxDBGridMemoColumn	TcxEditRepositoryMemoItem
TdxDBGridMRUColumn	TcxEditRepositoryMRUItem
TdxDBGridPickColumn	TcxEditRepositoryComboBoxItem
TdxDBGridPopupColumn	TcxEditRepositoryPopupItem
TdxDBGridSpinColumn	TcxEditRepositorySpinItem
TdxDBGridTimeColumn	TcxEditRepositoryTimeItem
TdxDBGridWrapperColumn	– Use any repository item listed above and handle the OnGetProperties event to specify the type of editor used to edit values of individual item cells.

Footer summary properties were removed from the columns and moved into the TcxDataSummary class. This class maintains the calculation of all summaries (footer, group summaries and summary groups).

The next table lists members of the TdxDBGridColumn class and the ExpressQuantumGrid4 equivalents:

TdxDBGridColumn Object

Properties
Derived from TdxDBTreeListColumn
ATreeList	Items belong to a view specified by the GridView property.
DisableGrouping	The column’s Options.Grouping property.
Field	The item’s DataBinding.Field property.
FieldName	The item’s DataBinding.FieldName property.
GroupIndex	The column’s GroupIndex property.
SortBySummary	–
SummaryField	– The ItemLink (Column in table views) and/or FieldName properties of a summary item. To calculate summaries when data is grouped by the current column, 1. create a summary group via the view’s DataController.Summary.SummaryGroups object, 2. add summary item(s) using the TcxDataSummaryGroup.SummaryItems.Add method and specify their ItemLink or FieldName property.  Use the Position property to specify whether the summary values will be displayed in the group footers or in group rows. 3. add a new element to the TcxDataSummaryGroup.Links collection and set its ItemLink (Column in table views) property to the current column.
SummaryFooterField	– The ItemLink and/or FieldName properties of a summary item within the view’s DataController.Summary.FooterSummaryItems collection.
SummaryFooterFormat	– The Format property of a summary item within the view’s DataController.Summary.FooterSummaryItems collection.
SummaryFooterText	– Use the FooterSummaryTexts property of the view’s DataController.Summary object.
SummaryFooterType	– The Kind property of a summary item within the view’s DataController.Summary.FooterSummaryItems collection.
SummaryFooterValue	– To get the footer summary results, use the FooterSummaryValues property of the view’s DataController.Summary object.
SummaryFormat	– The Format property of a summary item.
SummaryGroup	–
SummaryGroupName	– To calculate a set of summaries when data is grouped by the current column: 1. create a summary group via the view’s DataController.Summary.SummaryGroups object. 2. add summary items (the TcxDataSummaryGroup.SummaryItems.Add method) corresponding to the summaries you want to display. 3. add a new element to the TcxDataSummaryGroup.Links collection and set its ItemLink property to the current column.
SummaryType	– The Kind property of a summary item. See the SummaryField entry for details.
VariantType	The item’s DataBinding.ValueTypeClass.GetVarType method
Derived from TdxTreeListColumn
Alignment	The Alignment attribute of the in-place editor properties.  To access the column editor properties, use the RepositoryItem.Properties, Properties objects or the GetProperties method.
AssignedValues	–
BandIndex	The banded column’s Position.BandIndex property.
Caption	The item’s Caption property.
CharCase	The CharCase attribute of the in-place editor properties.  To access the column editor properties, use the RepositoryItem.Properties, Properties objects or the GetProperties method.
ColIndex	The banded column’s Position.ColIndex property.
Color	The item’s Styles.Content property.
DisableCaption	–
DisableCustomizing	The column’s VisibleForCustomization property.
DisableDragging	The column’s Options.Moving property.
DisableEditor	The item’s Options.Editing property.
DisableFilter	The item’s Options.Filtering property.
Font	The item’s Styles.Content property.
HeaderAlignment	The HeaderAlignmentHorz and HeaderAlignmentVert properties of columns; the CaptionAlignmentHorz and CaptionAlignmentVert properties of card view rows.
HeaderGlyph	– The view’s BackgroundBitmaps.Header property allows you to specify the bitmap used to render all column headers.
HeaderMaxLineCount	The banded column’s Position.LineCount property.
Index	The item’s Index property.
MaxLength	The MaxLength attribute of the in-place editor properties.  To access the column editor properties, use the RepositoryItem.Properties, Properties objects or the GetProperties method.
MinWidth	The column’s MinWidth property.
PasswordChar	– You can use the EchoMode attribute of the in-place editor properties to specify how characters are displayed. To access the column editor properties, use the RepositoryItem.Properties, Properties objects or the GetProperties method.
ReadOnly	The ReadOnly attribute of the in-place editor properties.  To access the column editor properties, use the RepositoryItem.Properties, Properties objects or the GetProperties method.
RowIndex	The banded column’s Position.RowIndex property.
Sizing	The column’s Options.HorzSizing property.
Sorted	The column’s SortOrder property.
TabStop	–
VertAlignment	The Alignment attribute of the in-place editor properties.  To access the column editor properties, use the RepositoryItem.Properties, Properties objects or the GetProperties method.
Visible	The item’s Visible property.
Width	The item’s Width property.
Methods
Derived from TdxTreeListColumn
Assign	The item’s Assign method.
DefaultAlignment	The item’s DefaultValuesProvider.DefaultAlignment method.
DefaultCaption	The item’s DataBinding.DefaultCaption method.
DefaultColor	–
DefaultFont	–
DefaultReadOnly	The item’s DefaultValuesProvider.DefaultReadOnly method.
DefaultWidth	The item’s DataBinding.DefaultWidth method.
GetBestFit	–
RestoreDefaults	The item’s RestoreDefaults method.
RestoreDefaultWidth	–
Events
Derived from TdxDBTreeListColumn
OnCustomDraw	The item’s OnCustomDrawCell event.
OnCustomDrawHeader	The item’s OnCustomDrawHeader event.
OnDrawSummaryFooter	The column’s OnCustomDrawFooterCell event.
OnGetText	The item’s OnGetDisplayText event.
OnSummary	The OnSummary event of the view’s DataController.Summary.DefaultGroupSummaryItems and DataController.DataSummary.SummaryGroups[ASummaryGroupIndex].SummaryItems objects.
OnSummaryFooter	The OnSummary event of the view’s DataController.Summary.FooterSummaryItems object.
Derived from TdxTreeListColumn
OnChange	– See the view’s OnEditChanged event.
OnCustomDrawCell	The item’s OnCustomDrawCell event.
OnCustomDrawColumnHeader	The item’s OnCustomDrawHeader event.
OnValidate	– Specify an editor for an item via the PropertiesClass or RepositoryItem property and handle the Properties.OnValidate or RepositoryItem.Properties.OnValidate event respectively.
Nodes/records

Records provided by an ExpressQuantumGrid4 view can be accessed via the ViewData property (e.g. TcxGridTableView.ViewData).  TcxCustomGridRecord is the base class for items available via the ViewData object and these items consist of group rows, master and data rows, the new item row and cards.  ViewData contains only those records which are currently visible or potentially visible by scrolling.  It does not contain records hidden under collapsed group rows.

TdxDBGridNode Object

ExpressQuantumGrid3 members	ExpressQuantumGrid4 equivalents
Properties
In TdxDBGridNode
GroupId	The TcxGridGroupRow.Value property.
RecNo	The TcxCustomGridRecord.RecordIndex property.
SummaryValue	– SummaryValue represents a value of a group summary set via the column’s SummaryType and SummaryField properties.  There are no equivalents to these three properties.  In ExpressQuantumGrid4, you use summary groups to calculate summaries when grouping by particular column(s). Summary groups are supported by the view’s DataController.Summary.SummaryGroups property.  To get a group summary value for a particular data group, use the DataController.Summary.GroupSummaryValues property.
SummaryValues	– Use the view’s DataController.Summary.GroupSummaryValues property to get a summary value for a particular data group.
Derived from TdxDBTreeListControlNode
Description	–
Id	– See TcxCustomGridRecord.RecordIndex property.
VariantData	–
VariantValues	The view’s DataController.Values property and the TcxCustomGridRecord.Values property.
Derived from TdxTreeListNode
AbsoluteIndex	The TcxCustomGridRecord.Index property.
Count	–
CountValues	The TcxCustomGridRecord.ValueCount property.
Data	–
Deleting	–
Expanded	The TcxCustomGridRecord.Expanded property.
Focused	The TcxCustomGridRecord.Focused property.
HasChildren	– You can determine whether the current row is a group row by analyzing the row class.  A group row contains an object of the TcxGridGroupRow class.
ImageIndex	–
Index	–
IsLast	–
IsVisible	The TcxCustomGridRecord.Visible property.
Items	– TcxGridGroupRow does not maintain a collection of child rows.  Instead, you can use the view’s ViewData property to access the list of all records currently displayed within the view.
Level	The TcxCustomGridRecord.Level property.
Owner	Use the TcxCustomGridRecord.ViewData property to access the object owning the current record.
Parent	–
Selected	The TcxCustomGridRecord.Selected property.
SelectedIndex	–
StateIndex	–
Strings	The TcxCustomGridRecord.DisplayTexts property. For group rows, use the TcxGridGroupRow.DisplayText property.
Values	The TcxCustomGridRecord.Values property.
Methods
Derived from TdxDBTreeListControlNode
Delete	– In unbound mode, use the view’s DataController.DeleteRecord method passing it the record’s RecordIndex property value as a parameter. To delete records from views connected to datasets, use the view’s DataController.DeleteFocused or DeleteSelection methods.
Derived from TdxTreeListNode
AddChild	–
AddChildFirst	–
AddNodesToList	–
Collapse	The TcxCustomGridRecord.Collapse method.
DeleteChildren	–
Expand	The TcxCustomGridRecord.Expand method.
GetNext	–
GetNextNode	–
GetNextSibling	–
GetPrev	–
GetPrevSibling	–
GetPriorNode	–
GetPriorParentNode	–
HasAsParent	–
IndexOf	–
InsertChild	–
MakeVisible	The TcxCustomGridRecord.MakeVisible method.
MoveTo	–
Summary items

ExpressQuantumGrid provides summary groups (as in the previous version), thus enabling you to calculate summaries when grouping by particular columns.  Default summary groups are now available via the view’s DataController.Summary.DefaultGroupSummaryItems property.

ExpressQuantumGrid3 members	ExpressQuantumGrid4 equivalents
TdxDBGridSummaryGroups Object

Properties
In TdxDBGridSummaryGroups
DBGrid	The collection of summary groups belongs to a TcxDataSummary object that can be obtained via the TcxDataSummaryGroups.Summary property.
Items	The TcxDataSummaryGroups.Items property.
Methods
In TdxDBGridSummaryGroups
Add	The TcxDataSummaryGroups.Add method.
GetDefaultGroup	– Default groups are provided by the view’s DataController.Summary.DefaultGroupSummaryItems property.
TdxDBGridSummaryGroup Object

Properties
In TdxDBGridSummaryGroup
BeginSummaryText	The TcxDataGroupSummaryItems.BeginText property.
DefaultGroup	ExpressQuantumGrid4 provides a collection of default summary items supported by the view’s DataController.Summary.DefaultGroupSummaryItems property.  Default summary items specify summaries to calculate when data is grouped by any grid column except for those columns associated with summary groups in the DataController.Summary.SummaryGroups property.
EndSummaryText	The TcxDataGroupSummaryItems.EndText property.
Name	–
SummaryItems	The TcxDataSummaryGroup.SummaryItems property.
Methods
In TdxDBGridSummaryGroup
GetSummaryGroups	See the TcxDataSummaryGroup.SummaryGroups property.
Events
In TdxDBGridSummaryGroup
OnChangeName	–
TdxDBGridSummaryItems Object

Properties
In TdxDBGridSummaryItems
Items	The Items property of the TcxDataSummaryGroup.SummaryItems object. You can access a particular summary group via the view’s DataController.Summary.SummaryGroups property.
SummaryGroup	–
Methods
In TdxDBGridSummaryItems
Add	The TcxDataSummaryItems.Add method.
TdxDBGridSummaryItem Object

Properties
In TdxDBGridSummaryItem
ColumnName	The ItemLink property of a summary item contained in the TcxDataSummaryGroup.SummaryItems collection. Table views and banded table views provide summary items. These declare the Column property (TcxGridTableSummaryItem.Column, for instance) which can be used instead of ItemLink.
SummaryField	The FieldName property of a summary item contained in the TcxDataSummaryGroup.SummaryItems collection.
SummaryFormat	The Format property of a summary item contained in the TcxDataSummaryGroup.SummaryItems collection.
SummaryType	The Kind property of a summary item contained in the TcxDataSummaryGroup.SummaryItems collection.
Methods
In TdxDBGridSummaryItem
GetSummaryItems	– See the TcxDataSummaryItem.SummaryItems property.
Events
In TdxDBGridSummaryItem
OnSummary	See the TcxDataSummaryItems.OnSummary event.
Filter

Filtering data in ExpressQuantumGrid4 is implemented by the TcxDataFilterCriteria class.  It allows you to create complex filter conditions, enable/disable filter criteria and customize the filter drop-down list.

ExpressQuantumGrid3 members	ExpressQuantumGrid4 equivalents
TdxDBGridFilter Object

Properties
In TdxDBGridFilter
Active	The view’s OptionsCustomize.ColumnFiltering property.
AutoDataSetFilter	The view’s DataController.Filter.AutoDataSetFilter property.
CaseInsensitive	The fcoCaseInsensitive option in the view’s DataController.Filter.AutoDataSetFilter property.
DropDownCount	The view’s Filtering.MaxDropDownCount property.
FilterCaption	The view’s DataController.Filter.FilterCaption property.
FilterStatus	The view’s Filtering.Visible property.
FilterText	The view’s DataController.Filter.FilterText property.
MaxDropDownCount	The view’s DataController.Filter.MaxValueListCount property.
Methods
In TdxDBGridFilter
Add	1. The item’s DataBinding.AddToFilter method. 2. The view’s DataController.AddItemToFilter method. 3. The view’s DataController.Filter.AddItem method. 4. The view’s DataController.Filter.Root.AddItem method
AddNull	When creating a filter condition using the TcxFilterCriteriaItemList.AddItem method, you can specify NULL as a value for the AValue parameter.
Clear	The view’s DataController.Filter.Clear method. You can temporarily disable filtering via the DataController.Filter.Active property.
Remove	The view’s DataController.Filter.RemoveItemByItemLink method.  Pass the column object as the AItemLink parameter.
ShowCustomDialog	The view’s Filtering.RunCustomizeDialog method.


Grid3 and Grid4 Equivalents (alphabetically)

See Also

This topic provides a conversion guide between ExpressQuantumGrid3 and ExpressQuantumGrid4 members.  All members are grouped into four categories: Options, Properties, Methods and Events.  Use the links under each category to access the equivalents to ExpressQuantumGrid3 members (provided in alphabetical order).

Options

All option names have the edgo prefix – so the alphabetical order refers to option names excluding this prefix.

A  B  C  D  E  F  H  I  K  L  M  N  P  R  S  T  U  V

Properties

A  B  C  D  E  F  G  H  I  K  L  M  N  O  P  R  S  T  U  V  W

Methods

A  B  C  D  E  F  G  H  I  L  M  P  R  S

Events

All event names have the On prefix – so the alphabetical order refers to event names excluding this prefix.

A  B  C  D  E  F  G  H  I  R  S  V

Grid control

The main difference between versions 3 and 4 of the ExpressQuantumGrid is that the latter is capable of displaying data within multiple views.  ExpressQuantumGrid4 provides different views (table, banded table and card views) for displaying data while ExpressQuantumGrid3 provides just one basic table view (which can be displayed with or without bands).  Most of the TdxDBGrid functionality is now implemented by view objects.  Views present data from data fields by means of "items". An Item represents a column in table views and a row in card views.  Refer to the Views and Items sections for more details.

A data controller represented by the view’s DataController property implements data-aware operations such as loading data, filtering, grouping and calculating summaries.  Customizing colors and fonts has been delegated to Style objects and so is implemented now by assigning styles to grid elements.

These changes mean that the multitude of top level properties in the grid have been replaced by a small collection of objects. While these changes provide for a more efficient and extensible product, we recognize that users of ExpressQuantumGrid3 will have initial difficulty in finding the properties required while converting event handlers for ExpressQuantumGrid4 and hence the reason for this topic.

Note: the two technologies are very different so there isn’t always a simple replacement available. While we have tried to cover as many options as possible, the following lists can never be totally complete (you may be using our product in ways we haven’t considered!). If you still have difficulty in replacing your ExpressQuantumGrid3 code because your needs are not covered here, please write to support@devexpress.com and we will help you.

Bands

Unlike the previous version of the grid control, ExpressQuantumGrid4 does not contain bands by default.  Instead, it provides banded table views (TcxGridBandedTableView and TcxGridDBBandedTableView).  A banded table view contains the Bands property providing a collection of TcxGridBand objects.

Columns

Every view provided by ExpressQuantumGrid4 contains a collection of view specific items (columns in a (banded) table view and rows in a card view) displaying data from particular fields.  Unlike the previous version of the grid control, ExpressQuantumGrid4 does not provide different column types.  Instead, you should use the item’s properties (RepositoryItem or PropertiesClass) to specify the editor type used to edit the item’s data.  You can refer to the Data Editing Using Inplace Editors section for more information.

ExpressQuamtumGrid4 provides different repository items corresponding to the ExpressQuantumGrid3 columns. These repository items can be used to specify the in-place editor type:

ExpressQuantumGrid3 members	ExpressQuantumGrid4 equivalent
ExpressQuantumGrid3 columns	Repository items
TdxDBGridColumn	TcxEditRepositoryTextItem
TdxDBGridBlobColumn	TcxEditRepositoryBlobItem
TdxDBGridButtonColumn	TcxEditRepositoryButtonItem
TdxDBGridCalcColumn	TcxEditRepositoryCalcItem
TdxDBGridCheckColumn	TcxEditRepositoryCheckBoxItem
TdxDBGridCurrencyColumn	TcxEditRepositoryCurrencyItem
TdxDBGridDateColumn	TcxEditRepositoryDateItem
TdxDBGridDropDownColumn	–
TdxDBGridExtLookupColumn	TcxEditRepositoryExtLookupComboBoxItem
TdxDBGridGraphicColumn	TcxEditRepositoryImageItem
TdxDBGridHyperLinkColumn	TcxEditRepositoryHyperLinkItem
TdxDBGridImageColumn	TcxEditRepositoryImageComboBoxItem
TdxDBGridLookupColumn	TcxEditRepositoryLookupComboBoxItem
TdxDBGridMaskColumn	TcxEditRepositoryMaskItem
TdxDBGridMemoColumn	TcxEditRepositoryMemoItem
TdxDBGridMRUColumn	TcxEditRepositoryMRUItem
TdxDBGridPickColumn	TcxEditRepositoryComboBoxItem
TdxDBGridPopupColumn	TcxEditRepositoryPopupItem
TdxDBGridSpinColumn	TcxEditRepositorySpinItem
TdxDBGridTimeColumn	TcxEditRepositoryTimeItem
TdxDBGridWrapperColumn	– Use any repository item listed above and handle the OnGetProperties event to specify the type of editor used to edit values of individual item cells.

Nodes/records

Records provided by an ExpressQuantumGrid4 view can be accessed via the ViewData property (e.g. TcxGridTableView.ViewData).  TcxCustomGridRecord is the base class for items available via the ViewData object and these items consist of group rows, master and data rows, the new item row and cards.  ViewData contains only those records which are currently visible or potentially visible by scrolling.  It does not contain records hidden under collapsed group rows.

Summary items

ExpressQuantumGrid provides summary groups (as in the previous version), thus enabling you to calculate summaries when grouping by particular columns.  Default summary groups are now available via the view’s DataController.Summary.DefaultGroupSummaryItems property.

Filter

Filtering data in ExpressQuantumGrid4 is implemented by the TcxDataFilterCriteria class.  It allows you to create complex filter conditions, enable/disable filter criteria and customize the filter drop-down list.

Options

Option	Property which contains the option	ExpressQuantumGrid4 equivalent

A

edgoAnsiSort	TCustomdxDBGrid.OptionsBehavior	The dcoAnsiSort option of the view’s DataController.Options property
edgoAutoCalcPreviewLines	TCustomdxDBGrid.OptionsView	The (banded) table view’s Preview.AutoHeight property.
edgoAutoCopySelectedToClipboard	TCustomdxDBGrid.OptionsBehavior	–
edgoAutoHeaderPanelHeight	TCustomdxDBGrid.OptionsView	–
edgoAutoSearch	TCustomdxDBGrid.OptionsBehavior	The view’s OptionsBehavior.IncSearch and item’s Options.IncSearch properties
edgoAutoSort	TCustomdxDBGrid.OptionsBehavior	The view’s OptionsCustomize.ItemSorting (ColumnSorting in a grid table view) and item’s Options.Sorting property.
edgoAutoWidth	TCustomdxDBGrid.OptionsView	The (banded) table view’s OptionsView.ColumnAutoWidth property.
B
edgoBandButtonClicking	TCustomdxDBGrid.OptionsBehavior	–
edgoBandHeaderWidth	TCustomdxDBGrid.OptionsView	–
edgoBandMoving	TCustomdxDBGrid.OptionsCustomize	The banded table view’s OptionsCustomize.BandMoving and band’s Options.Moving properties.
edgoBandPanelSizing	TCustomdxDBGrid.OptionsCustomize	–
edgoBandSizing	TCustomdxDBGrid.OptionsCustomize	The banded table view’s OptionsCustomize.BandSizing and the band’s Options.Sizing properties.
C
edgoCanAppend	TCustomdxDBGrid.OptionsDB	The view’s OptionsData.Appending property
edgoCancelOnExit	TCustomdxDBGrid.OptionsDB	The view’s OptionsData.CancelOnExit property
edgoCanDelete	TCustomdxDBGrid.OptionsDB	The view’s OptionsData.Deleting property
edgoCanInsert	TCustomdxDBGrid.OptionsDB	The view’s OptionsData.Inserting property
edgoCanNavigation	TCustomdxDBGrid.OptionsDB	The view’s DataController.DataModeController.SyncMode property.
edgoCaseInsensitive	TCustomdxDBGrid.OptionsBehavior	The dcoCaseInsensitive option of the view’s DataController.Options property
edgoCellMultiSelect	TCustomdxDBGrid.OptionsBehavior	–
edgoCollapsedReload	TCustomdxDBGrid.OptionsBehavior	–
edgoColumnMoving	TCustomdxDBGrid.OptionsCustomize	The view’s OptionsCustomize.ItemMoving (OptionsCustomize.ColumnMoving in a grid table view) and item’s Options.Moving properties.
edgoColumnSizing	TCustomdxDBGrid.OptionsCustomize	The view’s OptionsCustomize.ColumnHorzSizing and column’s Options.HorzSizing properties.  See also the OptionsCustomize.ColumnVertSizing and Options.VertSizing properties which are available for banded table views.
edgoConfirmDelete	TCustomdxDBGrid.OptionsView	The view’s OptionsData.DeletingConfirmation property
D
edgoDblClick	TCustomdxDBGrid.OptionsBehavior	–
edgoDragCollapse	TCustomdxDBGrid.OptionsBehavior	–
edgoDragExpand	TCustomdxDBGrid.OptionsBehavior	The view’s OptionsBehavior.DragOpening property.
edgoDragScroll	TCustomdxDBGrid.OptionsBehavior	See the view’s OptionsBehavior.DragFocusing and OptionsBehavior.DragScrolling properties.
edgoDrawEndEllipsis	TCustomdxDBGrid.OptionsView	The following properties affect ellipsis displaying when clipping occurs: OptionsView.BandHeaderEndEllipsis OptionsView.HeaderEndEllipsis OptionsView.RowCaptionEndEllipsis OptionsView.CellEndEllipsis
E
edgoEditing	TCustomdxDBGrid.OptionsBehavior	The view’s OptionsData.Editing and item’s Options.Editing properties
edgoEnterShowEditor	TCustomdxDBGrid.OptionsBehavior	– If end users are allowed to edit cell values, they can initiate editing of the focused cell by pressing the Enter or Space key, or by typing a new cell value directly.
edgoEnterThrough	TCustomdxDBGrid.OptionsBehavior	The view’s OptionsBehavior.GoToNextCellOnEnter property
edgoExtCustomizing	TCustomdxDBGrid.OptionsCustomize	The (banded) table view’s OptionsCustomize.ColumnHiding property.
edgoExtMultiSelect	TCustomdxDBGrid.OptionsBehavior	End users are allowed to select multiple records from different groups provided that the OptionsSelection.MultiSelect property is set to True.  Setting this property to True is equivalent to enabling both the edgoMultiSelect and edgoExtMultiSelect options in Grid 3.
F
edgoFullSizing	TCustomdxDBGrid.OptionsCustomize	–
H
edgoHeaderButtonClicking	TCustomdxDBGrid.OptionsBehavior	–
edgoHeaderPanelSizing	TCustomdxDBGrid.OptionsCustomize	–
edgoHideFocusRect		–
edgoHorzThrough	TCustomdxDBGrid.OptionsBehavior	The view’s OptionsBehavior.FocusCellOnCycle property
edgoHotTrack	TCustomdxDBGrid.OptionsView	–
I
edgoImmediateEditor	TCustomdxDBGrid.OptionsBehavior	The view’s OptionsBehavior.ImmediateEditor property.
edgoIndicator	TCustomdxDBGrid.OptionsView	The view’s OptionsView.Indicator property
edgoInvertSelect	TCustomdxDBGrid.OptionsView	The view’s OptionsSelection.InvertSelect property
K
edgoKeepColumnWidth	TCustomdxDBGrid.OptionsCustomize	–
L
edgoLoadAllRecords	TCustomdxDBGrid.OptionsDB	By default, ExpressQuantumGrid4 loads all records into memory.  To limit the number of records loaded at a time, see the view’s DataController.DataModeController.GridMode property
M
edgoMouseScroll	TCustomdxDBGrid.OptionsBehavior	–
edgoMultiSelect	TCustomdxDBGrid.OptionsBehavior	The view’s OptionsSelection.MultiSelect property.  Setting this property to True is equivalent to enabling both the edgoMultiSelect and edgoExtMultiSelect options in Grid 3.
edgoMultiSort	TCustomdxDBGrid.OptionsBehavior	– End users are allowed to sort the view data by values of multiple columns if the view’s OptionsCustomize.ColumnSorting property is set to True. Setting this property to True is equivalent to enabling both the edgoMultiSort And edgoAutoSort options in Grid 3).
N
edgoNotHideColumn	TCustomdxDBGrid.OptionsCustomize	See the view’s OptionsCustomize.ColumnHidingOnGrouping property.
P
edgoPartialLoad	TCustomdxDBGrid.OptionsDB	You can use the Grid Mode to limit the number of records loaded into memory at a time.  See the view’s DataController.DataModeController.GridMode property
edgoPreview	TCustomdxDBGrid.OptionsView	The view’s Preview.Visible property
R
edgoResetColumnFocus	TCustomdxDBGrid.OptionsDB	The view’s OptionsBehavior.FocusFirstCellOnNewRecord property
edgoRowAutoHeight	TCustomdxDBGrid.OptionsView	The view’s OptionsView.CellAutoHeight property
edgoRowSelect	TCustomdxDBGrid.OptionsView	The view’s OptionsSelection.CellSelect property
edgoRowSizing	TCustomdxDBGrid.OptionsCustomize	In a banded table view, the row height can be adjusted by changing the height of column headers displayed within the bands.  To enable this, set the OptionsCustomize.ColumnVertSizing property of a banded table view to True.
S
edgoSeekDetail	TCustomdxDBGrid.OptionsBehavior	–
edgoShowButtonAlways	TCustomdxDBGrid.OptionsView	The view’s OptionsView.ShowEditButtons property
edgoShowHourGlass	TCustomdxDBGrid.OptionsBehavior	–
edgoSmartRefresh	TCustomdxDBGrid.OptionsDB	The view’s DataController.DataModeController.SmartRefresh property
edgoSmartReload	TCustomdxDBGrid.OptionsDB	–
edgoStoreToIniFile	TCustomdxDBGrid.OptionsBehavior	– See the view’s StoreToIniFile method.
edgoStoreToRegistry	TCustomdxDBGrid.OptionsBehavior	– See the view’s StoreToRegistry method.
edgoSyncSelection	TCustomdxDBGrid.OptionsDB	The view’s DataController.DataModeController.SyncMode property
T
edgoTabs	TCustomdxDBGrid.OptionsBehavior	The view’s OptionsBehavior.FocusCellOnTab property
edgoTabThrough	TCustomdxDBGrid.OptionsBehavior	The view’s OptionsBehavior.FocusCellOnCycle and OptionsBehavior.FocusCellOnTab properties
U
edgoUseBitmap	TCustomdxDBGrid.OptionsView	–
edgoUseBookmarks	TCustomdxDBGrid.OptionsDB	–
edgoUseLocate	TCustomdxDBGrid.OptionsDB	– The Locate method is always used if key field names are specified via the view’s DataController.KeyFieldNames property.
V
edgoVertThrough	TCustomdxDBGrid.OptionsBehavior	–

Properties

Property	Class	ExpressQuantumGrid4 equivalent
A
AbsoluteIndex	TdxTreeListNode	The TcxCustomGridRecord.Index property.
Active	TdxDBGridFilter	The view’s OptionsCustomize.ColumnFiltering property.
Alignment	TdxTreeListBand	The TcxGridBand.Alignment property.
Alignment	TdxTreeListColumn	The Alignment attribute of the in-place editor properties.  To access the column editor properties, use the RepositoryItem.Properties, Properties objects or the GetProperties method.
ArrowsColor	TCustomdxTreeList	–
AssignedValues	TdxTreeListColumn	–
ATreeList	TdxDBTreeListColumn	Items belong to a view specified by the GridView property.
AutoDataSetFilter	TdxDBGridFilter	The view’s DataController.Filter.AutoDataSetFilter property.
AutoExpandOnSearch	TCustomdxTreeList	Group rows are always expanded on finding a record during an incremental search.
AutoSearchColor	TCustomdxTreeList	The view’s Styles.IncSearch property.
B
BandButtonPushed	TCustomdxTreeList	–
BandColor	TCustomdxTreeList	The Styles.BandHeader property (banded table views only) and the band’s Styles.Header property.
BandFont	TCustomdxTreeList	The Styles.BandHeader property (banded table views only) and the band’s Styles.Header property.
BandIndex	TdxTreeListColumn	The banded column’s Position.BandIndex property.
BandMaxRowCount	TCustomdxTreeListControl	–
BandPanelHeight	TCustomdxTreeList	–
BandRowCount	TCustomdxTreeListControl	The BandHeaderLineCount property (banded table views only).
Bands	TCustomdxTreeListControl	The Bands property (banded table views only).
BeginSummaryText	TdxDBGridSummaryGroup	The TcxDataGroupSummaryItems.BeginText property.
BorderStyle	TCustomdxTreeList	–
C
Caption	TdxTreeListBand	The TcxGridBand.Caption property.
Caption	TdxTreeListColumn	The item’s Caption property.
CaseInsensitive	TdxDBGridFilter	The fcoCaseInsensitive option in the view’s DataController.Filter.AutoDataSetFilter property.
CharCase	TdxTreeListColumn	The CharCase attribute of the in-place editor properties.  To access the column editor properties, use the RepositoryItem.Properties, Properties objects or the GetProperties method.
ColIndex	TdxTreeListColumn	The banded column’s Position.ColIndex property.
Color	TdxTreeListColumn	The item’s Styles.Content property.
ColumnCount	TCustomdxTreeListControl	The view’s ItemCount property.
ColumnName	TdxDBGridSummaryItem	The ItemLink property of a summary item contained in the TcxDataSummaryGroup.SummaryItems collection. Table views and banded table views provide summary items. These declare the Column property (TcxGridTableSummaryItem.Column, for instance) which can be used instead of ItemLink.
Columns	TCustomdxDBTreeListControl	The Items property declared in a base view class. Specific view classes provide the Columns (in a grid table and banded table views) and Rows properties (in a card view) as equivalents (the Items collection).
Count	TCustomdxTreeList	– See the view’s ViewData.Records property to get the collection of all records currently displayed.  To know whether a particular record is at the root nesting level, see its Level property.
Count	TdxTreeListNode	–
CountValues	TdxTreeListNode	The TcxCustomGridRecord.ValueCount property.
CustomizingBandListBox	TCustomdxTreeList	–
CustomizingForm	TCustomdxTreeList	The view’s Controller.CustomizationForm property.
CustomizingHeaderListBox	TCustomdxTreeList	–
CustomizingPos	TCustomdxTreeList	The view’s Controller.CustomizationFormBounds property. You can also use the Left, Top, Width and Height properties of the object obtained via the Controller.CustomizationForm property.
CustomizingRowCount	TCustomdxTreeList	–
D
Data	TdxTreeListNode	–
DataLink	TCustomdxDBTreeListControl	–
DataSetChangedBusy	TCustomdxDBGrid	The view’s DataController.Provider.IsDataSetBusy property.
DataSource	TCustomdxDBTreeListControl	The view’s DataController.DataSource property in data-aware views and DataController.CustomDataSource in non data-aware views.
DblClkExpanding	TCustomdxTreeList	Double-clicking group rows always expands/collapse the corresponding group. The view’s TcxGridTableOptionsBehavior.ExpandMasterRowOnDblClick property allows you to prevent expanding/collapsing of master rows on a double-click event.
DBGrid	TdxDBGridSummaryGroups	The collection of summary groups belongs to a TcxDataSummary object that can be obtained via the TcxDataSummaryGroups.Summary property.
DefaultFields	TCustomdxDBGrid	Fields in ExpressQuantumGrid4 are not automatically retrieved from a data source.  You can use the Retrieve Fields button in the Columns panel of the Component Editor or call the view’s DataController.CreateAllItems method.
DefaultGroup	TdxDBGridSummaryGroup	ExpressQuantumGrid4 provides a collection of default summary items supported by the view’s DataController.Summary.DefaultGroupSummaryItems property.  Default summary items specify summaries to calculate when data is grouped by any grid column except for those columns associated with summary groups in the DataController.Summary.SummaryGroups property.
DefaultLayout	TCustomdxTreeListControl	–
DefaultRowHeight	TCustomdxTreeList	The view’s OptionsView.DataRowHeight property.
Deleting	TdxTreeListNode	–
DescTextHeight	TCustomdxTreeList	–
Description	TdxDBTreeListControlNode	–
DisableCaption	TdxTreeListColumn	–
DisableCustomizing	TdxTreeListBand	The TcxGridBand.VisibleForCustomization property.
DisableCustomizing	TdxTreeListColumn	The column’s VisibleForCustomization property.
DisableDragging	TdxTreeListBand	The band’s Options.Moving property.
DisableDragging	TdxTreeListColumn	The column’s Options.Moving property.
DisableEditor	TdxTreeListColumn	The item’s Options.Editing property.
DisableFilter	TdxTreeListColumn	The item’s Options.Filtering property.
DisableGrouping	TdxDBTreeListColumn	The column’s Options.Grouping property.
DownBandIndex	TCustomdxTreeList	–
DownBandPushed	TCustomdxTreeList	–
DownColumnIndex	TCustomdxTreeList	–
DownColumnPushed	TCustomdxTreeList	–
DragAbsoluteBandIndex	TCustomdxTreeList	–
DragAbsoluteHeaderIndex	TCustomdxTreeList	–
DragNode	TCustomdxTreeList	–
DropDownCount	TdxDBGridFilter	The view’s Filtering.MaxDropDownCount property.
E
EditingText	TCustomdxTreeList	Use the view’s Controller.EditingItem property to access the item (column in a grid table view or card in a card view) being edited.  The EditValue property of the item specifies its value. Alternatively you can use the view’s Controller.FocusedRecord.DisplayTexts property to get the text representation of an individual item’s value within the currently focused record.
EndSummaryText	TdxDBGridSummaryGroup	The TcxDataGroupSummaryItems.EndText property.
Expanded	TdxTreeListNode	The TcxCustomGridRecord.Expanded property.
F
Field	TdxDBTreeListColumn	The item’s DataBinding.Field property.
FieldName	TdxDBTreeListColumn	The item’s DataBinding.FieldName property.
Filter	TCustomdxDBGrid	The view’s DataController.Filter and Filtering properties.
FilterCaption	TdxDBGridFilter	The view’s DataController.Filter.FilterCaption property.
FilterStatus	TdxDBGridFilter	The view’s Filtering.Visible property.
FilterText	TdxDBGridFilter	The view’s DataController.Filter.FilterText property.
Fixed	TdxTreeListBand	The TcxGridBand.FixedKind property.
FixedBandLineColor	TCustomdxTreeList	The view’s OptionsView.FixedBandSeparatorColor property.
FixedBandLineWidth	TCustomdxTreeList	The view’s OptionsView.FixedBandSeparatorWidth property.
Focused	TdxTreeListNode	The TcxCustomGridRecord.Focused property.
FocusedAbsoluteIndex	TCustomdxTreeList	The view’s Controller.FocusedItemIndex property.
FocusedColumn	TCustomdxTreeList	The view’s Controller.FocusedItem property.
FocusedField	TCustomdxDBTreeListControl	You can access a focused item (column in a grid table view or row in a card view) using the view’s Controller.FocusedItem property.  To access the field linked to the item, see the item’s DataBinding.Field property.
FocusedNode	TCustomdxTreeList	The view’s Controller.FocusedRecord property.
FocusedNumber	TCustomdxTreeList	The view’s Controller.FocusedRecord.Index property.
Font	TdxTreeListColumn	The item’s Styles.Content property.
FooterPanelHeight	TCustomdxTreeList	–
FooterRowHeight	TCustomdxTreeList	–
FooterRowNodeHeight	TCustomdxTreeList	–
G
GrIndicatorWidth	TCustomdxDBTreeListControl	The view’s OptionsView.IndicatorWidth property.
GridLineColor	TCustomdxTreeList	The view’s OptionsView.GridLineColor property.
GroupColumnCount	TCustomdxDBGrid	The view’s GroupedItemCount property
GroupColumns	TCustomdxDBGrid	The view’s GroupedItems property.
GroupId	TdxDBGridNode	The TcxGridGroupRow.Value property.
GroupIndex	TdxDBTreeListColumn	The column’s GroupIndex property.
GroupNodeColor	TCustomdxTreeList	The view’s Styles.Group property.
GroupNodeTextColor	TCustomdxTreeList	The view’s Styles.Group property.
GroupPanelColor	TCustomdxDBGrid	The view’s Styles.GroupByBox property.
GroupPanelFontColor	TCustomdxDBGrid	The view’s Styles.GroupByBox property.
GroupPanelHeight	TCustomdxDBGrid	–
H
HasChildren	TdxTreeListNode	– You can determine whether the current row is a group row by analyzing the row class.  A group row contains an object of the TcxGridGroupRow class.
HeaderAlignment	TdxTreeListColumn	The HeaderAlignmentHorz and HeaderAlignmentVert properties of columns; the CaptionAlignmentHorz and CaptionAlignmentVert properties of card view rows.
HeaderButtonPushed	TCustomdxTreeList	–
HeaderColCount	TdxTreeListBand	The Count property of a band row within a banded table view.  To access a particular band’s row, use code as follows bandedTableView1.Bands[ABandIndex].Rows[RowIndex]
HeaderColor	TCustomdxTreeList	The view’s Styles.Header and the column’s Styles.Header properties
HeaderColumn	TdxTreeListBand	The Items property of a band row within a banded table view.  To access a particular band’s row, use code as follows: bandedTableView1.Bands[ABandIndex].Rows[RowIndex]
HeaderFont	TCustomdxTreeList	The view’s Styles.Header and the column’s Styles.Header properties
HeaderGlyph	TdxTreeListColumn	– The view’s BackgroundBitmaps.Header property allows you to specify the bitmap used to render all column headers.
HeaderHeight	TCustomdxTreeList	The view’s HeaderHeight property.
HeaderMaxLineCount	TdxTreeListColumn	The banded column’s Position.LineCount property.
HeaderMinRowCount	TCustomdxTreeListControl	– See the view’s HeaderHeight property.
HeaderPanelHeight	TCustomdxTreeList	The view’s HeaderHeight property.
HeaderPanelMaxRowCount	TCustomdxTreeListControl	–
HeaderPanelRowCount	TCustomdxTreeListControl	The Bands.VisibleRowCount property (banded table views only).
HeaderRowCount	TdxTreeListBand	The band’s Rows.Count property.
HeaderRowHeight	TCustomdxTreeList	–
HideFocusRect	TCustomdxTreeList	The view’s OptionsSelection.HideFocusRect property.
HideSelection	TCustomdxTreeList	The view’s OptionsSelection.HideSelection property.
HideSelectionColor	TCustomdxTreeList	The view’s Styles.Inactive property.
HideSelectionTextColor	TCustomdxTreeList	The view’s Styles.Inactive property.
HighlightColor	TCustomdxTreeList	The view’s Styles.Selection property.
HighlightTextColor	TCustomdxTreeList	The view’s Styles.Selection property.
I
Id	TdxDBTreeListControlNode	– See TcxCustomGridRecord.RecordIndex property.
ImageIndex	TdxTreeListNode	–
IndentDesc	TCustomdxTreeList	The Preview.LeftIndent and Preview.RightIndent properties provide the two indents.
Index	TdxTreeListColumn	The item’s Index property.
Index	TdxTreeListNode	–
IniFileName	TCustomdxTreeListControl	–
IniSectionName	TCustomdxTreeListControl	–
InplaceColumnIndex	TCustomdxTreeList	The view’s Controller.EditingItem.Index property. Check the Controller.IsEditing property to see whether a cell is currently being edited.
InplaceEditor	TCustomdxTreeList	The view’s Controller.EditingController.Edit property. The view’s Controller.EditingItem.GetProperties method provides access to the properties of the editor (and these vary depending on the editor’s type).
IsCustomizing	TCustomdxTreeList	The view’s Controller.Customization property.
IsLast	TdxTreeListNode	–
IsVisible	TdxTreeListNode	The TcxCustomGridRecord.Visible property.
Items	TCustomdxTreeList	The view’s ViewData.Records property.
Items	TdxTreeListBands	The TcxGridBands.Items property.
Items	TdxTreeListNode	– TcxGridGroupRow does not maintain a collection of child rows.  Instead, you can use the view’s ViewData property to access the list of all records currently displayed within the view.
Items	TdxDBGridSummaryGroups	The TcxDataSummaryGroups.Items property.
Items	TdxDBGridSummaryItems	The Items property of the TcxDataSummaryGroup.SummaryItems object. You can access a particular summary group via the view’s DataController.Summary.SummaryGroups property.
K
KeyField	TCustomdxDBTreeListControl	The view’s DataController.KeyFieldNames property.
L
LastNode	TCustomdxTreeList	Use the view’s ViewData.Records property to access any record within a view.
LeftCoord	TCustomdxTreeList	The view’s Controller.LeftPos property.
Level	TdxTreeListNode	The TcxCustomGridRecord.Level property.
LockSelection	TCustomdxTreeList
LockRefresh	TCustomdxDBGrid	The view’s DataController.BeginLocate and EndLocate methods allow you to prevent a grid control from excessive reloading of data when navigating through dataset records.  If you need to call the TDataSet.Locate method, enclose this part of the code with BeginLocate and EndLocate. Calling the BeginLocate and EndLocate methods is equivalent to setting the LockRefresh property to True and False respectively.
LookAndFeel	TCustomdxTreeList	The LookAndFeel property.
M
MaxDropDownCount	TdxDBGridFilter	The view’s DataController.Filter.MaxValueListCount property.
MaxLength	TdxTreeListColumn	The MaxLength attribute of the in-place editor properties.  To access the column editor properties, use the RepositoryItem.Properties, Properties objects or the GetProperties method.
MaxRowLineCount	TCustomdxTreeList	The view’s OptionsView.CellTextMaxLineCount property.
MinWidth	TdxTreeListBand	To specify the minimum width of a band, set the minimum width (the MinWidth property) of the columns displayed within the band.
MinWidth	TdxTreeListColumn	The column’s MinWidth property.
N
Name	TdxDBGridSummaryGroup	–
NewItemRowHeight	TCustomdxTreeList	–
O
OnlyOwnColumns	TdxTreeListBand	–
Owner	TdxTreeListNode	Use the TcxCustomGridRecord.ViewData property to access the object owning the current record.
P
Parent	TdxTreeListNode	–
PartialLoad	TCustomdxDBGrid	ExpressQuantumGrid4 does not provide PartialLoad mode. You can use the Grid Mode to limit the number of records loaded into memory at a time.  See the view’s DataController.DataModeController.GridMode property.
PartialLoadBufferCount	TCustomdxDBGrid	ExpressQuantumGrid4 does not provide PartialLoad mode. ExpressQuantumGrid4 provides the Grid mode for limiting the number of records loaded into memory at a time.  Use the DataController.DataModeController.GridModeBufferCount to specify the buffer size.
PasswordChar	TdxTreeListColumn	– You can use the EchoMode attribute of the in-place editor properties to specify how characters are displayed. To access the column editor properties, use the RepositoryItem.Properties, Properties objects or the GetProperties method.
PreviewFieldName	TCustomdxDBTreeListControl	The view’s Preview.Column property.
PreviewFont	TCustomdxTreeList	The view’s Styles.Preview property.
PreviewLines	TCustomdxTreeList	The (banded) table view’s Preview.MaxLineCount property.
PreviewMaxLength	TCustomdxDBTreeListControl	–
R
ReadOnly	TdxTreeListColumn	The ReadOnly attribute of the in-place editor properties.  To access the column editor properties, use the RepositoryItem.Properties, Properties objects or the GetProperties method.
RecNo	TdxDBGridNode	The TcxCustomGridRecord.RecordIndex property.
RegistryPath	TCustomdxTreeListControl	–
RowFooterColor	TCustomdxTreeList	The Styles.Footer property specifies the style for both the footer and group footer panels.  You can specify different styles for these panels by handling the Styles.OnGetFooterStyle event.
RowFooterTextColor	TCustomdxTreeList	The Styles.Footer property specifies the style for both footer and group footer panels.  You can specify different styles for these panels by handling the Styles.OnGetFooterStyle event.
RowHeight	TCustomdxTreeList	Use the view’s ViewInfo.RecordsViewInfo[ARowIndex].Height property. ARowIndex specifies the position of the required record among all visible records within a view
RowIndex	TdxTreeListColumn	The banded column’s Position.RowIndex property.
RowSeparatorLineWidth	TCustomdxTreeList	The view’s OptionsView.RowSeparatorWidth property.
S
ScrollBars	TCustomdxTreeList	The view’s OptionsView.ScrollBars property.
Selected	TdxTreeListNode	The TcxCustomGridRecord.Selected property.
SelectedCount	TCustomdxTreeList	The view’s Controller.SelectedRecordCount property.
SelectedIndex	TdxTreeListNode	–
SelectedNodes	TCustomdxTreeList	The view’s Controller.SelectedRecords property.
SelectedRows	TCustomdxDBTreeListControl	The view’s DataController.GetSelectedBookmark function (in grid mode only).
ShowBands	TCustomdxTreeList	The OptionsView.BandHeaders property of a banded table view.
ShowGrid	TCustomdxTreeList	The view’s OptionsView.GridLines property allows you to specify which grid lines to display.
ShowGroupPanel	TCustomdxDBGrid	The view’s OptionsView.GroupByBox property
ShowHeader	TCustomdxTreeList	The view’s OptionsView.Header property.
ShowHiddenInCustomizeBox	TCustomdxTreeList	–
ShowNewItemRow	TCustomdxTreeList	The view’s OptionsView.NewItemRow property.
ShowPreviewGrid	TCustomdxTreeList	The view’s OptionsView.GridLines property allows you to specify which grid lines to display.
ShowRowFooter	TCustomdxTreeList	The view’s OptionsView.GroupFooters property.
ShowSummaryFooter	TCustomdxDBGrid	The view’s OptionsView.Footer property.
SimpleCustomizeBox	TCustomdxTreeList	–
Sizing	TdxTreeListBand	The band’s Options.Sizing property.
Sizing	TdxTreeListColumn	The column’s Options.HorzSizing property.
SortBySummary	TdxDBTreeListColumn	–
Sorted	TdxTreeListColumn	The column’s SortOrder property.
SortedColumn	TCustomdxDBTreeListControl	The first element of the SortedItems collection.
SortedColumnCount	TCustomdxTreeListControl	The view’s SortedItemCount property.
SortedColumns	TCustomdxDBTreeListControl	The (banded) table view’s SortedItems property.
State	TCustomdxTreeList	–
StateIndex	TdxTreeListNode	–
Strings	TdxTreeListNode	The TcxCustomGridRecord.DisplayTexts property. For group rows, use the TcxGridGroupRow.DisplayText property.
SummaryField	TdxDBTreeListColumn	– The ItemLink (Column in table views) and/or FieldName properties of a summary item. To calculate summaries when data is grouped by the current column, 1. 1. create a summary group via the view’s DataController.Summary.SummaryGroups object, 2. 2. add summary item(s) using the TcxDataSummaryGroup.SummaryItems.Add method and specify their ItemLink or FieldName property.  Use the Position property to specify whether the summary values will be displayed in the group footers or in group rows. 3. 3. add a new element to the TcxDataSummaryGroup.Links collection and set its ItemLink (Column in table views) property to the current column.
SummaryField	TdxDBGridSummaryItem	The FieldName property of a summary item contained in the TcxDataSummaryGroup.SummaryItems collection.
SummaryFooterField	TdxDBTreeListColumn	– The ItemLink and/or FieldName properties of a summary item within the view’s DataController.Summary.FooterSummaryItems collection.
SummaryFooterFormat	TdxDBTreeListColumn	– The Format property of a summary item within the view’s DataController.Summary.FooterSummaryItems collection.
SummaryFooterText	TdxDBTreeListColumn	– Use the FooterSummaryTexts property of the view’s DataController.Summary object.
SummaryFooterType	TdxDBTreeListColumn	– The Kind property of a summary item within the view’s DataController.Summary.FooterSummaryItems collection.
SummaryFooterValue	TdxDBTreeListColumn	– To get the footer summary results, use the FooterSummaryValues property of the view’s DataController.Summary object.
SummaryFormat	TdxDBTreeListColumn	– The Format property of a summary item.
SummaryFormat	TdxDBGridSummaryItem	The Format property of a summary item contained in the TcxDataSummaryGroup.SummaryItems collection.
SummaryGroup	TdxDBTreeListColumn	–
SummaryGroup	TdxDBGridSummaryItems	–
SummaryGroupName	TdxDBTreeListColumn	– To calculate a set of summaries when data is grouped by the current column: 1. 1. create a summary group via the view’s DataController.Summary.SummaryGroups object. 2. 2. add summary items (the TcxDataSummaryGroup.SummaryItems.Add method) corresponding to the summaries you want to display. 3. 3. add a new element to the TcxDataSummaryGroup.Links collection and set its ItemLink property to the current column.
SummaryGroups	TCustomdxDBGrid	All summaries are set via the view’s DataController.Summary property.  Summary groups are provided by the Summary.SummaryGroups collection.  To create default summary groups, use the Summary.DefaultGroupSummaryItems property.
SummaryItems	TdxDBGridSummaryGroup	The TcxDataSummaryGroup.SummaryItems property.
SummarySeparator	TCustomdxDBGrid	The TcxDataGroupSummaryItems.Separator property.
SummaryType	TdxDBTreeListColumn	– The Kind property of a summary item. See the SummaryField entry for details.
SummaryType	TdxDBGridSummaryItem	The Kind property of a summary item contained in the TcxDataSummaryGroup.SummaryItems collection.
SummaryValue	TdxDBGridNode	– SummaryValue represents a value of a group summary set via the column’s SummaryType and SummaryField properties.  There are no equivalents to these three properties.  In ExpressQuantumGrid4, you use summary groups to calculate summaries when grouping by particular column(s). Summary groups are supported by the view’s DataController.Summary.SummaryGroups property.  To get a group summary value for a particular data group, use the DataController.Summary.GroupSummaryValues property.
SummaryValues	TdxDBGridNode	– Use the view’s DataController.Summary.GroupSummaryValues property to get a summary value for a particular data group.
T
TabStop	TdxTreeListColumn	–
TopIndex	TCustomdxTreeList	The view’s Controller.TopRecordIndex property.
TopNode	TCustomdxTreeList	The view’s ViewData.Records[0] value.
TopVisibleNode	TCustomdxTreeList	The view’s ViewData.Records[GridView1.Controller.TopRecordIndex] value.
TreeList	TdxTreeListBands	Bands belong to a view specified by the TcxGridBands.GridView property.
U
UseBookmarks	TCustomdxDBGrid	When in grid mode, bookmarks are stored automatically for the selected records and can be accessed via the view’s DataController.GetSelectedBookmark function. When not in grid mode, bookmarks are not stored.
V
Values	TdxTreeListNode	The TcxCustomGridRecord.Values property.
VariantData	TdxDBTreeListControlNode	–
VariantType	TdxDBTreeListColumn	The item’s DataBinding.ValueTypeClass.GetVarType method
VariantValues	TdxDBTreeListControlNode	The view’s DataController.Values property and the TcxCustomGridRecord.Values property.
VertAlignment	TdxTreeListColumn	The Alignment attribute of the in-place editor properties.  To access the column editor properties, use the RepositoryItem.Properties, Properties objects or the GetProperties method.
Visible	TdxTreeListBand	The Visible property of a band within a banded table view.  Individual bands can be accessed via the banded table view’s Bands property.
Visible	TdxTreeListColumn	The item’s Visible property.
VisibleColumnCount	TCustomdxTreeListControl	The VisibleItemCount property in a base view class.  In a grid (banded) table view and card view, you can use the VisibleColumnCount and VisibleRowCount properties respectively.
VisibleColumns	TCustomdxDBTreeListControl	The view’s VisibleItems property.  Views publish the VisibleColumns (in grid table and grid banded table views) and VisibleRows (in a card view) properties and these provide access to the same items as VisibleItems.
VisibleCount	TdxTreeListBands	The TcxGridBands.VisibleCount property.
VisibleIndex	TdxTreeListBand	The VisibleIndex property of a band within a banded table view.  Individual bands can be accessed via the banded table view’s Bands property.
VisibleItems	TdxTreeListBands	The TcxGridBands.VisibleItems property.
W
WaitForExpandNodeTime	TCustomdxTreeList	The grid’s DragOpeningWaitTime property.
Width	TdxTreeListBand	The Width property of a band within a banded table view.  Individual bands can be accessed via the banded table view’s Bands property.
Width	TdxTreeListColumn	The item’s Width property.

Methods

Method	Class	ExpressQuantumGrid4 equivalent
A
Add	TCustomdxTreeList	The view’s DataController.AppendRecord method.
Add	TdxTreeListBands	The TcxGridBands.Add method.
Add	TdxDBGridSummaryGroups	The TcxDataSummaryGroups.Add method.
Add	TdxDBGridSummaryItems	The TcxDataSummaryItems.Add method.
Add	TdxDBGridFilter	1. The item’s DataBinding.AddToFilter method. 2. The view’s DataController.AddItemToFilter method. 3. The view’s DataController.Filter.AddItem method. 4. The view’s DataController.Filter.Root.AddItem method
AddNull	TdxDBGridFilter	When creating a filter condition using the TcxFilterCriteriaItemList.AddItem method, you can specify NULL as a value for the AValue parameter.
AddChild	TdxTreeListNode	–
AddChildFirst	TdxTreeListNode	–
AddFirst	TCustomdxTreeList	–
AddGroupColumn	TCustomdxDBGrid	Set the GroupIndex property of the desired column to a value greater than or equal to the GroupedColumnCount property value.
AddNodesToList	TdxTreeListNode	–
AdjustColumnsWidth	TCustomdxTreeList	– The view’s OptionsView.ColumnAutoWidth property
ApplyBestFit	TCustomdxTreeListControl	The item’s ApplyBestFit method.  To adjust the width of all view columns, call the view’s ApplyBestFit method.
Assign	TdxTreeListColumn	The item’s Assign method.
AssignColumns	TCustomdxTreeListControl	The view’s Assign method.
B
BeginGrouping	TCustomdxDBGrid	The view’s BeginUpdate method.
BeginSelection	TCustomdxTreeList	–
BeginSorting	TCustomdxTreeListControl	The view’s BeginUpdate method.
BeginUpdate	TCustomdxTreeList	The BeginUpdate method declared in the TcxCustomGrid, TcxCustomGridView, TcxCustomDataController, TcxDataSummary and TcxFilterCriteria classes.
C
CalcDrawInfo	TCustomdxTreeList	–
CanAddGroupColumn	TCustomdxDBGrid	–
CancelEditor	TCustomdxTreeList	Call the view’s Controller.EditingController.HideEdit method passing False as the Accept parameter.
CellRect	TCustomdxTreeList	Use code like this to access a particular cell region within a record: (cxGrid1TableView1.ViewInfo.RecordsViewInfo[AIndex] as TcxGridDataRowViewInfo).GetBoundsForItem(AItem); AIndex specifies the TcxCustomGridRecord.Index property value.  AItem is an item (column in a (banded) table view and row in a card view) to which the required cell belongs.
Clear	TdxDBGridFilter	The view’s DataController.Filter.Clear method. You can temporarily disable filtering via the DataController.Filter.Active property.
ClearColumnsSorted	TCustomdxTreeList	The view’s DataController.ClearSorting method.
ClearGroupColumns	TCustomdxDBTreeListControl	The view’s DataController.Groups.ClearGrouping method.
ClearNodes	TCustomdxTreeList	In unbound mode, set the view’s DataController.RecordCount property to 0.
CloseEditor	TCustomdxTreeList	Call the view’s Controller.EditingController.HideEdit method passing True as the Accept parameter.
Collapse	TdxTreeListNode	The TcxCustomGridRecord.Collapse method.
ColumnByFieldName	TCustomdxDBTreeListControl	In (banded) table views, see the GetColumnByFieldName method.  In card views, the equivalent is GetRowByFieldName.  Note that these methods do not throw an exception if no items found linked to the specified field.
ColumnByName	TCustomdxDBTreeListControl	The view’s FindItemByName method.
ColumnCalcLineCount	TCustomdxTreeList	–
ColumnsCustomizing	TCustomdxTreeList	The view’s Controller.Customization property.
CopyAllToClipboard	TCustomdxTreeList	Call the view’s CopyToClipboard method passing True as the ACopyAll parameter.
CopySelectedToClipboard	TCustomdxTreeList	Call the view’s CopyToClipboard method passing False as the ACopyAll parameter.
CreateColumn	TCustomdxDBTreeListControl	– See the view’s CreateItem method to add a new item.  In table and card views, you use the CreateColumn and CreateRow methods respectively. These implement the same functionality, but differ from CreateItem by the class of the returned object.
CreateColumnEx	TCustomdxDBTreeListControl	– Use the view’s CreateItem (CreateColumn in a grid (banded) table view, CreateRow in a card view) method to add a new column.  To specify an editor for the item, see the PropertiesClass and RepositoryItem properties.
D
DefaultAlignment	TdxTreeListColumn	The item’s DefaultValuesProvider.DefaultAlignment method.
DefaultCaption	TdxTreeListColumn	The item’s DataBinding.DefaultCaption method.
DefaultColor	TdxTreeListColumn	–
DefaultFont	TdxTreeListColumn	–
DefaultReadOnly	TdxTreeListColumn	The item’s DefaultValuesProvider.DefaultReadOnly method.
DefaultWidth	TdxTreeListColumn	The item’s DataBinding.DefaultWidth method.
Delete	TdxDBTreeListControlNode	– In unbound mode, use the view’s DataController.DeleteRecord method passing it the record’s RecordIndex property value as a parameter. To delete records from views connected to datasets, use the view’s DataController.DeleteFocused or DeleteSelection methods.
DeleteChildren	TdxTreeListNode	–
DeleteGroupColumn	TCustomdxDBGrid	– Set the column’s GroupIndex property to –1 for that purpose.
DestroyColumns	TCustomdxTreeListControl	The view’s ClearItems method.
E
EndColumnsCustomizing	TCustomdxTreeList	The view’s Controller.Customization property.
EndGrouping	TCustomdxDBGrid	The view’s EndUpdate method.
EndSearch	TCustomdxTreeList	The view’s Controller.CancelIncSearching method.
EndSelection	TCustomdxTreeList	–
EndSorting	TCustomdxTreeListControl	The view’s EndUpdate method.
EndUpdate	TCustomdxTreeList	The EndUpdate method declared in the TcxCustomGrid, TcxCustomGridView, TcxCustomDataController, TcxDataSummary and TcxFilterCriteria classes.
Expand	TdxTreeListNode	The TcxCustomGridRecord.Expand method.
F
FindNodeByKeyValue	TCustomdxDBGrid	The view’s DataController.FindRecordIndexByKey function.
FindColumnByFieldName	TCustomdxDBTreeListControl	In (banded) table views, see the GetColumnByFieldName method.  In card views, the equivalent is GetRowByFieldName.
FreeDrawInfo	TCustomdxTreeList	–
FullCollapse	TCustomdxTreeList	The view’s ViewData.Collapse method lets you collapse group and master rows within a view. The view’s DataController.Groups.FullCollapse method collapses group rows.
FullExpand	TCustomdxTreeList	The view’s ViewData.Expand method lets you expand group and master rows within a view. The view’s DataController.Groups.FullExpand method expands group rows.
FullRefresh	TCustomdxDBTreeListControl	Call the view’s DataController.UpdateItems method with False as a parameter.
G
GetAbsoluteColumnIndex	TCustomdxTreeListControl	The Index property of the desired item.  To access an item by its position among the visible items, use the view’s VisibleItems property.
GetAbsoluteIndex	TdxTreeListBands	–
GetBandAt	TCustomdxTreeListControl	Use the ViewInfo.GetHitTest method. This returns an object with information on the grid element containing the specified coordinates. The following code gets the band at a specific point provided that it is within the band header panel: var   AHitTest: TcxCustomGridHitTest;   ABand: TcxGridBand; //... AHitTest := cxGrid1.ViewInfo.GetHitTest(X, Y); if AHitTest is TcxGridBandHeaderHitTest then   ABand := TcxGridBandHeaderHitTest(AHitTest).Band;
GetBestFit	TdxTreeListColumn	–
GetColumnAt	TCustomdxDBTreeListControl	Use the ViewInfo.GetHitTest method. This returns an object with information on the grid element with the coordinates specified. For instance, the following code determines the item (column) at point (X,Y) if the point relates to a record or to the column header panel. var   AHitTest: TcxCustomGridHitTest;   AItem: TcxCustomGridTableItem; //... AHitTest := cxGrid1.ViewInfo.GetHitTest(X, Y); if AHitTest is TcxGridRecordCellHitTest then   AItem := TcxGridRecordCellHitTest(AHitTest).Item else   if AHitTest is TcxGridColumnHeaderHitTest then     AItem := TcxGridColumnHeaderHitTest(AHitTest).Column;
GetColumnAt	TCustomdxTreeListControl	Use the ViewInfo.GetHitTest method. This returns an object with information on the grid element containing the specified coordinates. For instance, the following code determines the item (column) at point (X,Y) if the point is within a record or the column header panel. var   AHitTest: TcxCustomGridHitTest;   AItem: TcxCustomGridTableItem; //... AHitTest := cxGrid1.ViewInfo.GetHitTest(X, Y); if AHitTest is TcxGridRecordCellHitTest then   AItem := TcxGridRecordCellHitTest(AHitTest).Item else   if AHitTest is TcxGridColumnHeaderHitTest then     AItem := TcxGridColumnHeaderHitTest(AHitTest).Column;
GetDefaultColumnClass	TCustomdxDBTreeListControl	When the item’s ValueTypeClass property is set, this value determines the default editor assigned to the item.  An example of registering a default editor follows: GetDefaultEditDataRepositoryItems.RegisterItem(TcxBooleanValueType, cxEditRegisteredItemsStandardVersion, GetDefaultEditRepository.CreateItem(TcxEditRepositoryCheckBoxItem)); Here, a check box is registered as the editor for items with the value type of TcxBooleanValueType. To redefine the default editor for this value type, call the RegisterItem procedure passing it the required repository item instead of TcxEditRepositoryCheckBoxItem.  The second parameter of the procedure specifies the priority of the registered editor.  To redefine the existing editor, you must set the parameter to a value greater than the cxEditRegisteredItemsStandardVersion. If an item is assigned to a value type not registered by RegisterItem, its editor is determined by the RegisterDefaultItem method: GetDefaultEditDataRepositoryItems.RegisterDefaultItem( cxEditRegisteredItemsStandardVersion, GetDefaultEditRepository.CreateItem(TcxEditRepositoryTextItem)); If you need to use a different editor, call RegisterDefaultItem passing it a another repository item instead of TcxEditRepositoryTextItem.  Like the RegisterItem method, set the first parameter to a value greater than the cxEditRegisteredItemsStandardVersion constant.
GetDefaultFieldColumnClass	TCustomdxDBTreeListControl	In data-aware views, items (columns in a table view and cards in a card view) are assigned default editors based on the field type. An example of registering a default editor follows: GetDefaultEditDBRepositoryItems.RegisterItem(ftCurrency, cxEditRegisteredItemsStandardVersion, GetDefaultEditRepository.CreateItem(TcxEditRepositoryCurrencyItem)); Here, a currency editor represented by the TcxEditRepositoryCurrencyItem class is registered as an editor for currency fields. The first parameter specifies a value of the TFieldType enumerator.  The second parameter specifies the priority of the registered editor.  To redefine the existing editor, you must set the parameter to a value greater than the cxEditRegisteredItemsStandardVersion. If an item is assigned to a field not registered by the RegisterItem method, its editor is determined by the RegisterDefaultItem method: GetDefaultEditDBRepositoryItems.RegisterDefaultItem( cxEditRegisteredItemsStandardVersion, GetDefaultEditRepository.CreateItem(TcxEditRepositoryMaskItem)); If you need to use a different editor, call RegisterDefaultItem passing it a another repository item instead of TcxEditRepositoryMaskItem.  Like the RegisterItem method, set the first parameter to a value greater than the cxEditRegisteredItemsStandardVersion constant.
GetDefaultGroup	TdxDBGridSummaryGroups	– Default groups are provided by the view’s DataController.Summary.DefaultGroupSummaryItems property.
GetDisplayValue	TCustomdxTreeListControl	The TcxCustomGridRecord.DisplayTexts property provides the text representation of a value stored in a particular record field.
GetEditRect	TCustomdxTreeList	Use the code as follows (cxGrid1TableView1.ViewInfo.RecordsViewInfo[AIndex] as TcxGridDataRowViewInfo).GetCellViewInfoByItem(AItem).ContentBounds; AIndex specifies the record index defined by the TcxCustomGridRecord.Index property.  AItem refers to the item (column in a (banded)table view and row in a card view).
GetFocusedAbsoluteIndex	TCustomdxTreeList	Use the view’s Controller.FocusedItem.Index property.
GetFocusedVisibleIndex	TCustomdxTreeList	Use the view’s Controller.FocusedItemIndex or Controller.FocusedItem.VisibleIndex property.
GetFooterColumnAt	TCustomdxDBTreeListControl	Use the ViewInfo.GetHitTest method. This returns an object with information on the grid element containing the specified coordinates. The following code determines a particular column within the footer panel. var   AHitTest: TcxCustomGridHitTest;   AColumn: TcxGridColumn; //... AHitTest := cxGrid1.ViewInfo.GetHitTest(X, Y); if AHitTest is TcxGridFooterCellHitTest then   AColumn := TcxGridFooterCellHitTest(AHitTest).Column;
GetHeaderColumnAt	TCustomdxDBTreeListControl	Use the ViewInfo.GetHitTest method. This returns an object with information on the grid element containing the specified coordinates. The following code shows how you can determine whether a given point is within a column header.  If so, AColumn is assigned to this column: var   AHitTest: TcxCustomGridHitTest;   AColumn: TcxGridColumn; //... AHitTest := cxGrid1.ViewInfo.GetHitTest(X, Y); if AHitTest is TcxGridColumnHeaderHitTest then   AColumn := TcxGridColumnHeaderHitTest(AHitTest).Column;
GetHitInfo	TCustomdxTreeList	See the view’s ViewInfo.GetHitTest method. This returns an object with information on a grid element (a TcxCustomGridHitTest class descendant) at specific coordinates.  You can determine the type of the element via the HitTestCode function of the object obtained.
GetHitTestInfoAt	TCustomdxTreeList	See the view’s ViewInfo.GetHitTest method. This returns an object with information on a grid element (a TcxCustomGridHitTest class descendant) at specific coordinates.  You can determine the type of the element via the HitTestCode function of the object returned.
GetGroupColumnAt	TCustomdxDBGrid	Use the ViewInfo.GetHitTest method. This returns an object with information on the grid element containing the specified coordinates. The following code shows how you can determine whether a given point belongs to the header of a column.  If so, AColumn is assigned to this column. var   AHitTest: TcxCustomGridHitTest;   AColumn: TcxGridColumn; //... AHitTest := cxGrid1.ViewInfo.GetHitTest(X, Y); if AHitTest is TcxGridColumnHeaderHitTest then   AColumn := TcxGridColumnHeaderHitTest(AHitTest).Column; See the column’s GroupIndex property value to see whether data is grouped by this column.
GetNext	TdxTreeListNode	–
GetNextNode	TdxTreeListNode	–
GetNextSibling	TdxTreeListNode	–
GetNextVisible	TCustomdxTreeList	– The view’s ViewData.Records property provides access to all records currently displayed within a view.  A record can be obtained from this collection by its Index property as it identifies the visual position of the record within a view.  For instance, you can use the code below to access the record following the ACurrentRecord: ANextRecord := view1.ViewData.Records[ACurrentRecord.Index + 1];
GetNodeAt	TCustomdxTreeList	Use the ViewInfo.GetHitTest method. This returns an object with information on the grid element containing the specified coordinates. The following code determines the record at the (X,Y) point if it falls within the content area: var   AHitTest: TcxCustomGridHitTest;   ARecord: TcxCustomGridRecord; //... AHitTest := cxGrid1.ViewInfo.GetHitTest(X, Y); if AHitTest is TcxGridRecordHitTest then   ARecord := TcxGridRecordHitTest(AHitTest).GridRecord;
GetNodeFooterColumnAt	TCustomdxDBGrid	Use the ViewInfo.GetHitTest method. This returns an object with information on the grid element containing the specified coordinates. The following code determines the column referenced within the group footer. var   AHitTest: TcxCustomGridHitTest;   AColumn: TcxGridColumn; //... AHitTest := cxGrid1.ViewInfo.GetHitTest(X, Y); if AHitTest is TcxGridGroupFooterCellHitTest then   AColumn := TcxGridGroupFooterCellHitTest(AHitTest).Column;
GetPrev	TdxTreeListNode	–
GetPrevSibling	TdxTreeListNode	–
GetPriorNode	TdxTreeListNode	–
GetPriorParentNode	TdxTreeListNode	–
GetSummaryGroupByName	TCustomdxDBGrid	–
GetSummaryGroups	TdxDBGridSummaryGroup	See the TcxDataSummaryGroup.SummaryGroups property.
GetSummaryItemAt	TCustomdxDBGrid	–
GetSummaryItems	TdxDBGridSummaryItem	– See the TcxDataSummaryItem.SummaryItems property.
GetVisibleColumnIndex	TCustomdxTreeListControl	The VisibleIndex property of the desired item.  To access an individual item by its absolute index, see the view’s Items property (Columns in a (banded) table view or Rows in a card view).
GetVisibleIndex	TdxTreeListBands	–
GotoFirst	TCustomdxTreeList	The view’s Controller.GoToFirst method.
GotoLast	TCustomdxTreeList	The view’s Controller.GoToLast method.
GotoNext	TCustomdxTreeList	The view’s Controller.GoToNext method.
GotoPrev	TCustomdxTreeList	The view’s Controller.GoToPrev method.
H
HasAsParent	TdxTreeListNode	–
HeaderPanelBestFit	TCustomdxTreeList	–
HideDrawFocusRect	TCustomdxContainer	The view’s OptionsSelection.HideFocusRect property.
HideEditor	TCustomdxTreeList	– Call the view’s Controller.EditingController.HideEdit method passing True as the Accept parameter.
I
IndexOf	TCustomdxTreeList	– Use the Index property of a TcxCustomGridRecord object to get the position of the record.
IndexOf	TdxTreeListNode	–
Insert	TCustomdxTreeList	In unbound mode, use the view’s DataController.InsertRecord method to insert a new record above the record specified as the method’s parameter. In bound mode, you should use the methods of the dataset object to which the view is connected by means of a TDataSource object (for instance, the Insert method of a TDataSet descendant).
InsertChild	TdxTreeListNode	–
InsertGroupColumn	TCustomdxDBGrid	Set the column’s GroupIndex property to a value between 0 and GroupedColumnCount – 1.
IsGridMode	TCustomdxDBGrid	The view’s DataController.IsGridMode function.
IsInvertSelect	TCustomdxTreeList	The view’s OptionsSelection.InvertSelect property.
IsNodeVisible	TCustomdxTreeList	The Visible property of a TcxCustomGridRecord object.
IsPartialLoad	TCustomdxDBGrid	ExpressQuantumGrid4 does not provide the PartialLoad mode.  Use Grid Mode to limit the number of records loaded into memory at once.
IsShowButtonAlways	TCustomdxContainer	The view’s OptionsView.ShowEditButtons property.
L
LoadFromIniFile	TCustomdxTreeListControl	The view’s RestoreFromIniFile method.
LoadFromRegistry	TCustomdxTreeListControl	The view’s RestoreFromRegistry method.
M
MakeBandVisible	TCustomdxTreeList	–
MakeColumnVisible	TCustomdxTreeList	The view’s Controller.MakeItemVisible method.
MakeNodeVisible	TCustomdxTreeList	1. The view’s Controller.MakeRecordVisible method. 2. The MakeVisible method of a TcxCustomGridRecord object. You can also make a master row owning a specific detail view visible via the MakeMasterGridRecordVisible method.
MakeVisible	TdxTreeListNode	The TcxCustomGridRecord.MakeVisible method.
MoveTo	TdxTreeListNode	–
P
PointInFooterPanel	TCustomdxDBGrid	See the view’s ViewInfo.GetHitTest.HitTestCode function.  If the specified point belongs to the footer panel, it returns htFooter.
PointInGroupPanel	TCustomdxDBGrid	See the view’s ViewInfo.GetHitTest.HitTestCode function.  If the specified point belongs to the group panel, it returns htGroupByBox.
PointInCustomizingForm	TCustomdxTreeList	See the view’s ViewInfo.GetHitTest.HitTestCode function.  If the specified point belongs to the customization form, it returns the htCustomizationForm constant value.
R
RefreshBookmarks	TCustomdxDBTreeListControl	–
RefreshDefaultColumnsWidths	TCustomdxTreeListControl	– The RestoreDefaults method, declared in view and item classes, allows you to restore the default column widths.
RebuildGroupIndexes	TCustomdxDBGrid	–
RefreshGroupColumns	TCustomdxDBGrid	The view’s DataController.Summary.Calculate method.
RefreshSorting	TCustomdxTreeListControl	–
Remove	TdxDBGridFilter	The view’s DataController.Filter.RemoveItemByItemLink method.  Pass the column object as the AItemLink parameter.
RestoreColumnsDefaults	TCustomdxTreeListControl	– The RestoreDefaults method declared in the view and item classes allows you to restore the default column widths and captions.
RestoreDefaults	TdxTreeListBand	–
RestoreDefaults	TdxTreeListBands	–
RestoreDefaults	TdxTreeListColumn	The item’s RestoreDefaults method.
RestoreDefaultWidth	TdxTreeListColumn	–
S
SaveAllToStrings	TCustomdxTreeList	–
SaveAllToTextFile	TCustomdxTreeList	–
SaveSelectedToStrings	TCustomdxTreeList	–
SaveSelectedToTextFile	TCustomdxTreeList	See the ExportGridToText procedure.
SaveToHTML	TdxDBGrid	The global ExportGridToHTML procedure.
SaveToIniFile	TCustomdxTreeListControl	The view’s StoreToIniFile method.
SaveToRegistry	TCustomdxTreeListControl	The view’s StoreToRegistry method.
SaveToText	TdxDBGrid	The global ExportGridToText procedure.
SaveToXLS	TdxDBGrid	The global ExportGridToExcel procedure.
SaveToXML	TdxDBGrid	The global ExportGridToXML procedure.
ShowButtonEditorMouse	TCustomdxTreeList	See the view’s Controller.EditingController.ShowEdit method.
ShowCustomDialog	TdxDBGridFilter	The view’s Filtering.RunCustomizeDialog method.
ShowEditorChar	TCustomdxTreeList	See the view’s Controller.EditingController.ShowEdit method.
ShowEditor	TCustomdxTreeList	See the view’s Controller.EditingController.ShowEdit method. Alternatively, you can set the view’s Controller.EditingItem property to open the editor for a specific item within the currently focused record.
ShowEditorMouse	TCustomdxTreeList	See the view’s Controller.EditingController.ShowEdit method.
StartSearch	TCustomdxTreeList	To start an incremental search, assign a string to the view’s Controller.IncSearchingText property.

Events

Event	Class	ExpressQuantumGrid4 equivalent
A
OnAddGroupColumn	TCustomdxDBGrid	ExpressQuantumGrid4 does not provide an event to allow you to control column grouping.  You can prevent grouping by a particular column though by using the column’s Options.Grouping property.
B
OnBackgroundDrawEvent	TCustomdxDBGrid	See the view’s OnCustomDrawPartBackground event.
OnBandButtonClick	TCustomdxTreeListControl	–
OnBandClick	TCustomdxTreeListControl	The TcxGridBand.OnHeaderClick event.
OnBeforeCalcSummary	TCustomdxDBTreeListControl	–
OnBeginDragNode	TCustomdxTreeList	–
C
OnCalcRowLineHeight	TCustomdxTreeListControl	–
OnCalcSummary	TCustomdxDBTreeListControl	The view’s DataController.Summary.OnAfterSummary event.
OnCanBandDragging	TCustomdxTreeListControl	ExpressQuantumGrid4 does not provide an event allowing you to control band dragging. You can prevent a user from a dragging a band by setting the view’s OptionsCustomize.BandMoving or the band’s Options.Moving property to False.
OnCanHeaderDragging	TCustomdxTreeListControl	ExpressQuantumGrid4 does not provide an event allowing you to control column dragging. The view’s OptionsCustomize.ColumnMoving and the item’s Options.Moving properties can be set to False to prevent the dragging of column(s).
OnCanNodeSelected	TCustomdxTreeList	The view’s OnCanSelectRecord event.
OnChange	TdxTreeListColumn	– See the view’s OnEditChanged event.
OnChangeColumn	TCustomdxTreeList	The view’s OnFocusedItemChanged event.
OnChangedColumnsWidth	TCustomdxTreeListControl	The view’s OnColumnSizeChanged event.
OnChangeLeftCoord	TCustomdxTreeList	The view’s OnLeftPosChanged event.
OnChangeName	TdxDBGridSummaryGroup	–
OnChangeNode	TCustomdxTreeList	The view’s OnFocusedRecordChanged event.
OnChangeNodeEx	TCustomdxDBTreeListControl	– The view’s OnFocusedRecordChanged event.
OnChangeTopVisibleNode	TCustomdxTreeList	The view’s OnTopRecordIndexChanged event.
OnClearNodeData	TCustomdxDBGrid	–
OnCollapsed	TCustomdxTreeList	–
OnCollapsing	TCustomdxTreeList	–
OnColumnClick	TCustomdxDBGrid	The column’s OnHeaderClick event.
OnColumnClick	TCustomdxTreeListControl	The column’s OnHeaderClick event.
OnColumnMoved	TCustomdxTreeListControl	The column’s OnColumnPosChanged event.
OnColumnSorting	TCustomdxDBGrid	ExpressQuantumGrid4 does not provide an event to allow you to control column sorting. The column’s Options.Sorting property can be used to prevent a user from sorting by the column.
OnCompare	TCustomdxTreeList	The view’s DataController.OnCompare event.
OnCustomDraw	TCustomdxDBGrid	The OnCustomDrawCell event provided by view and item objects.
OnCustomDraw	TCustomdxTreeListControl	The OnCustomDrawCell event provided by view and item objects.
OnCustomDraw	TdxDBTreeListColumn	The item’s OnCustomDrawCell event.
OnCustomDrawBand	TCustomdxTreeListControl	The view’s OnCustomDrawBandHeader event.
OnCustomDrawCell	TCustomdxTreeListControl	The OnCustomDrawCell event provided by view and item objects.
OnCustomDrawCell	TdxTreeListColumn	The item’s OnCustomDrawCell event.
OnCustomDrawColumnHeader	TCustomdxTreeListControl	The view’s OnCustomDrawColumnHeader event.
OnCustomDrawColumnHeader	TdxTreeListColumn	The item’s OnCustomDrawHeader event.
OnCustomDrawFooter	TCustomdxTreeListControl	The view’s OnCustomDrawFooterCell event.
OnCustomDrawFooterNode	TCustomdxTreeListControl	The view’s OnCustomDrawFooterCell event.
OnCustomDrawHeader	TdxDBTreeListColumn	The item’s OnCustomDrawHeader event.
OnCustomDrawPreview	TCustomdxTreeListControl	The OnCustomDrawCell event provided by view and item objects.
OnCustomDrawPreviewCell	TCustomdxTreeListControl	The OnCustomDrawCell event provided by view and item objects.
D
OnDeletion	TCustomdxTreeList	–
OnDragEndBand	TCustomdxTreeListControl	– Handle the view’s OnBandPosChanged event for writing code after a band’s position has changed.
OnDragEndHeader	TCustomdxTreeListControl	– Handle the view’s OnColumnPosChanged event for writing code after a column’s position has changed
OnDragOverBand	TCustomdxTreeListControl	–
OnDragOverHeader	TCustomdxTreeListControl	–
OnDrawSummaryFooter	TdxDBTreeListColumn	The column’s OnCustomDrawFooterCell event.
E
OnEditChange	TCustomdxTreeList	The view’s OnEditChanged event.
OnEdited	TCustomdxTreeList	–
OnEditing	TCustomdxTreeList	The view’s OnEditing event.
OnEditValidate	TCustomdxTreeList	Handle the OnValidate event of the editor assigned to an item.
OnEndColumnsCustomizing	TCustomdxTreeList	–
OnEndDragColumn	TCustomdxTreeListControl	–
OnEndDragGroupColumn	TCustomdxDBGrid	ExpressQuantumGrid4 does not provide an event to allow you to control column grouping. Use the column’s Options.Grouping property to prevent the grouping by that column.
OnEnumFilterValues	TCustomdxDBGrid	The column’s OnGetFilterValues or view’s DataController.Filter.OnGetValueList event.
OnExpanded	TCustomdxTreeList	–
OnExpanding	TCustomdxTreeList	–
F
OnFilterChanged	TCustomdxDBGrid	The view’s DataController.Filter.OnBeforeChange event.
G
OnGetCustomSummaryText	TCustomdxDBGrid	–
OnGetEditColor	TCustomdxDBTreeListControl	See the Styles.OnGetContentStyle event provided by view and item objects.
OnGetLevelColor	TCustomdxTreeListControl	The view’s Styles.OnGetGroupStyle event.
OnGetNodeDragText	TCustomdxTreeListControl	–
OnGetPreviewText	TCustomdxDBTreeListControl	The OnGetDisplayText event of the column assigned to the (banded) table view’s Preview.Column property.
OnGetText	TdxDBTreeListColumn	The item’s OnGetDisplayText event.
H
OnHeaderButtonClick	TCustomdxTreeListControl	–
OnHeaderMoved	TCustomdxTreeListControl	The view’s OnColumnPosChanged event.
OnHideBand	TCustomdxTreeListControl	– The OnBandPosChanged event declared in a banded table view.
OnHideColumn	TCustomdxDBGrid	The view’s OnColumnPosChanged event.
OnHideHeader	TCustomdxTreeListControl	– The view’s OnColumnPosChanged event.
OnHotTrackNode	TCustomdxTreeList	–
I
OnIsExistFooterCell	TCustomdxTreeListControl	–
R
OnReloadGroupList	TCustomdxDBGrid	The view’s DataController.OnGroupingChanged event.
OnRefreshNodeData	TCustomdxDBTreeListControl	–
S
OnSelectedCountChange	TCustomdxTreeList	The view’s OnSelectionChanged event.
OnShowBand	TCustomdxTreeListControl	– The OnBandPosChanged event declared in a banded table view.
OnShowColumn	TCustomdxDBGrid	The view’s OnColumnPosChanged event.
OnShowHeader	TCustomdxTreeListControl	– The view’s OnColumnPosChanged event.
OnStartBandDragging	TCustomdxTreeListControl	–
OnStartHeaderDragging	TCustomdxTreeListControl	–
OnSummary	TdxDBTreeListColumn	The OnSummary event of the view’s DataController.Summary.DefaultGroupSummaryItems and DataController.DataSummary.SummaryGroups[ASummaryGroupIndex].SummaryItems objects.
OnSummary	TdxDBGridSummaryItem	See the TcxDataSummaryItems.OnSummary event.
OnSummaryFooter	TdxDBTreeListColumn	The OnSummary event of the view’s DataController.Summary.FooterSummaryItems object.
OnSummaryNode	TCustomdxDBGrid	The TcxDataSummaryItems.OnSummary event provided by the FooterSummaryItems, DefaultGroupSummaryItems properties and by every summary group in the SummaryGroups collection.
V
OnValidate	TdxTreeListColumn	– Specify an editor for an item via the PropertiesClass or RepositoryItem property and handle the Properties.OnValidate or RepositoryItem.Properties.OnValidate event respectively.


Overview

What's New in v6          Known Issues and Important Changes List

Simply the Best - Let Us Show You Why

Introducing ExpressQuantumGrid Suite v6, the most capable Grid and Data Editors Library ever created for Delphi and C++ Builder. With the ExpressQuantumGrid Suite, you can create visually stunning interfaces and deliver incredible features/flexibility to your end-users - without writing a single line of code.

From standard two-dimensional tables to runtime grouping and column customization; from master/detail relationships to unbound mode; from concise card views to illustrative chart views; from typical appearance to XP themes... the ExpressQuantumGrid Suite has been engineered to fully address your development requirements and help you compete and win in the marketplace - without compromise or hassles.

Remember, it's Not Just a Grid Control!

The ExpressQuantumGrid Suite includes the best grid control in the business - so good in fact, in a review by Delphi Informant Magazine it was said of the QuantumGrid, "After my experience with ExpressQuantumGrid and ExpressInspector... I can't imagine developing a Delphi database application without these tools. The grid is the most capable VCL grid I've found. Just by using a small part of its capabilities and customization options, my applications seem more professional, and the users enjoy the editing capabilities."

But...

The Suite is far more than this powerful grid control... the suite is also comprised of over 70 standalone field editors and individual controls - many available in data-aware and non data-aware editions.

Total Control, Flexibility and Power
The Only No Limits Grid and Data Editors Library Available for the VCL


What's New in v6
What’s New in v6

Known Issues and Important Changes List

This topic provides a brief overview of the new features introduced in the ExpressQuantumGrid Suite v6.  Click a link below to jump to the corresponding section.

Data Handling Enhancements

Charting Capabilities

Card View Features

Table View and Banded Table View Features

Common Features

Design-Time Experience

Data Handling Enhancements

Filtering UI Innovations:

•	Filter Row.  A specially designed Filter Row allows you to apply a filter condition directly within the grid.  Use the View’s FilterRow.Visible and FilterRow.ApplyChanges options to activate the Filter Row and specify its filter update mode.

•	Checked Lists in Column Filter Dropdowns.  Column filter dropdowns now use checked lists.  Use the View's Filtering.ColumnPopup.MultiSelect and Filtering.ColumnPopup.ApplyMultiSelectChanges options to activate checked lists and specify their filter update mode.  A grid item’s Options.FilteringPopupMultiSelect property allows you to control the appearance of a checked list for individual columns and card rows.

•	Synchronized Filter Dropdowns.  Filter dropdowns can now be populated only with currently available items (that have not been filtered out).  To enable this feature for an entire View, use the View’s Filtering.RowFilteredItemsList and Filtering.ColumnFilteredItemsList properties.  To enable this feature for individual columns and card rows, use a grid item’s Options.FilteringFilteredItemsList property.

Improved Date/Time Value Handling:

•	More flexible filtering capabilities:

o	You can set the View’s DateTimeHandling.IgnoreTimeForFiltering property to True to force the View to ignore the time portion of date/time values.  This means that filter dropdowns will be populated with dates without their corresponding time element.  In either case, the time element is taken into consideration when you sort data.

o	Time intervals and time ranges relative to the current date (such as a year, month, previous week, etc.) in filter dropdowns displayed for date/time columns.  The availability of these advanced filter items is controlled by the View's DateTimeHandling.Filters property.

o	You can extend the built-in collection of date ranges with your own, by handling the OnInitFilteringDateRanges events for a View and an item.

•	More flexible grouping capabilities:

o	The View’s DateTimeHandling.Grouping property allows you to specify how date/time values should be combined into groups.  You can specify grouping options for each column, using the column’s DateTimeGrouping property.

o	Similar to the filtering capabilities, the most frequently needed group types are built-in.  You can easily add custom grouping types by handling a specially designed OnInitGroupingDateRanges event for a View and a column.  As with filter conditions, group types are represented by the same date range classes.  Once created, a custom date range can be used both to filter and group data.

•	Customizable formats for dates in filter dropdowns and group rows (via the View’s DateTimeHandling sub-properties).

Charting Capabilities

•	Three New Chart Types: Line, Pie, and Area Charts.  Use the View’s DiagramLine, DiagramPie, and DiagramArea properties to access their appearance settings.

•	Data Mining Using Data Groups and Drill Down.  This feature has much in common with group summaries in Table Views.  You can specify a field whose values will be used to group data.  The chart will display values calculated against each group instead of each individual value.  Refer to the Creating Data Groups in Chart Views topic, to learn about this feature.

•	End-User Chart Customization Capabilities.  A new UI element – a Toolbox – allows straightforward end-user chart customization by means of the following tools: data level navigator, chart customization button, and diagram type selector.  Use the View’s ToolBox property to control the general appearance of the Toolbox.

•	Paging – Category Scrolling.  You can specify the maximum number of categories simultaneously displayed in a chart, via the View’s OptionsView.CategoriesPerPage property.

•	Customizable Value Axis Display Range.  You can restrict the display range of value axes based upon plotted chart values, and also provide arbitrary upper/lower axis limits (via the diagram’s AxisValue.MinMaxValues, AxisValue.MinValue, and AxisValue.MaxValue properties).

Card View Features

•	Expandable Category Rows.  To create a category, add a new row and set its Kind property to rkCategory.  Data rows that follow a category automatically become its children.  If there is another category row, it starts its own new category, etc.  Collapsing a category within a card affects all cards.  This allows end-users to hide unnecessary fields with just a single click.

•	More Flexible Row Layout.  You can use the View’s RowLayout property to specify whether rows should be arranged vertically, one under another, or horizontally from left to right.  At design time, you can create whatever layout you need by simply dragging rows to their desired position.  And you can allow end-users to do the same.  For this purpose, enable the View’s OptionsCustomize.RowMoving and OptionsCustomize.LayeredRows properties.

•	Automatic Card Width Adjustment.  If the View’s OptionsView.CardAutoWidth option is enabled, cards are automatically resized to fit into the View.  So, you can resize the View to display more or less cards.

•	Show Hidden Empty Fields While Editing.  When the View’s OptionsView.EmptyRows option is disabled, the View automatically displays all fields when an end-user enters edit mode.

•	Customizable Card Spacing.  Use the View’s OptionsView.CardIndent property to create space between cards based upon your requirements.

•	Selection Frame Around a Selected Card.  To enable this feature, activate the View's OptionsSelection.CardBorderSelection option.

Table View and Banded Table View Features

•	Easy Column and Band Reordering.  The Quick Column Customization dropdown now allows you to reorder columns.  Simply drag the desired entry to a new position.  The same is true for the Quick Band Customization dropdown.  Use the View’s OptionsCustomize.ColumnsQuickCustomizationReordering and OptionsCustomize.BandsQuickCustomizationReordering options to enable this feature.

•	Customizable Group Summary Layout.  With v6, you can display group row summaries under corresponding columns (via the View’s OptionsView.GroupSummaryLayout option) and also control their horizontal alignment (via the desired column’s GroupSummaryAlignment option).

•	Group Footer Availability at the Column Level.  Use a grouping column's Options.GroupFooters property to display footers for the corresponding groups.

•	Sorting Data Groups by Group Summary Values.  Refer to the Sorting Data by Group Summaries topic, for more information on this feature.

•	Multiple Summaries per Column in the View's Footer and Group Footers.  To enable this feature, use the View’s OptionsView.FooterMultiSummaries and OptionsView.GroupFooterMultiSummaries options.

Common Features

This section lists features which are common to all or some Views.  These features are shown in no particular order.

•	The ExpressQuantumGrid now uses the ExpressPageControl to display detail tabs.  This means, that detail tabs now offer you the same appearance and end-user features as our advanced page control.  Use the grid’s LevelTabs property to access appearance settings of detail tabs.

•	Images in Detail Level Tabs.  Use the grid’s LevelTabs.Images and LevelTabs.CaptionAlignment properties to specify the source image list and the position of tab captions.  To assign images to individual tabs, use the appropriate level’s ImageIndex property.

•	To hide detail tabs whose corresponding details are empty, set a master level's Options.TabsForEmptyDetails property to False.

•	To change the "No data to display" text, which is displayed by default in an empty View, assign the desired View’s OptionsView.NoDataToDisplayInfoText property.

•	You can handle a column or card row's OnGetCellHint event to manually provide hint text, size and position for each cell of this column or row.

•	Alternate Captions for Columns and Card Rows.  With v6, you have two options to distinguish columns and card rows that have the same caption, if they were moved to the Customization Form, Group By box or used to customize a filter condition in a filter builder dialog.  You can choose from the automatic caption update dependent on the column header position (via the View’s OptionsView.BandCaptionsInColumnAlternateCaption or OptionsView.CategoryRowCaptionInRowAlternateCaption property) or manually specify their captions via the corresponding column or row’s AlternateCaption property.

•	New Filter Button Behavior.  By default, filter buttons are now displayed only when the mouse pointer hovers over a column header.  Use the View’s OptionsView.ShowColumnFilterButtons option to enable the old-style filter button behavior.

•	Optional Column Caption Display.  You can hide a column's caption within a View by setting this column's Options.ShowCaption property to False.

•	Use the View’s OptionsCustomize.ColumnFiltering option to disable filter dropdowns independently of other interface elements.

Design-Time Experience

•	Easier Access to Objects

o	Each View now displays a triangular selector in the top-left corner.  So, you can access a View directly by clicking it, instead of locating the appropriate label within the Structure Navigator.

o	The Structure Navigator now highlights the selected View.  If you select a Level by clicking the appropriate level tab, or if you select the entire grid control, the corresponding label within the Structure Navigator will be highlighted as well.  Of course, highlighting also takes place when you use the Object Inspector or the Component Editor to select an object.  In addition, the Structure Navigator now allows you to select multiple objects by clicking View or Level labels while holding the SHIFT key.

o	If you select a Level or View using the Object Inspector or the grid's Structure Navigator, the corresponding View will automatically become visible within the grid control.

o	With v6, you can access summary item properties by clicking the corresponding footer cells and summary values in group rows.

•	Improved Context Menus.  For your convenience, grid control, View and level context menus are extended with the most frequently used actions.

•	Column and Band Quick Customization.  Column and Band Quick Customization dropdowns are now available not only to your end-users, but to you as well.  These simple and effective column and band arrangement mechanisms help you get your job done quickly, without aggravation.


Known Issues and Important Changes List

What's New in v6

All entries in the following list are grouped by Views.

Common Changes

Table Views and Banded Table Views

Banded Table Views

Card Views

Chart Views

Common Changes

1. Package files, package source files, and resource files have been renamed as follows:

•	cxGridVCLC6/D6/D7 -> cxGridC6/D6/D7

•	dclcxGridVCLC6/D6/D7 -> dclcxGridC6/D6/D7.

2. Report Link for the ExpressQuantumGrid.  The name of the Report Link's unit now includes the version number of the ExpressQuantumGrid – to prevent code changes when migrating to a new major version of the ExpressQuantumGrid.  This means that you should use the following units:

•	dxPScxGrid4Lnk for ExpressQuantumGrid v4

•	dxPScxGridLnk for ExpressQuantumGrid v5 (we have decided to leave it "as is" because v5 is the current version of the Grid as of the release date)

•	dxPScxGrid6Lnk for ExpressQuantumGrid v6.

3. In TcxCustomGridRecord:

•	The DoKeyPress and KeyPress methods have been removed.

•	The KeyDown method and the IsParentRecordLast, IsValid and LastParentRecordCount properties are now protected.

Table Views and Banded Table Views

1. The following properties are now obsolete (public).  Use their new published substitutes instead:

•	TcxCustomGridTableItem.Hidden -> TcxCustomGridTableItem.VisibleForCustomization

•	TcxGridColumn.Hidden -> TcxGridColumn.VisibleForCustomization

•	TcxCustomGridTableFiltering.CustomizeDialog -> TcxGridFilterBox.CustomizeDialog

•	TcxCustomGridTableFiltering.MRUItemsListDropDownCount -> TcxGridFilterBox.MRUItemsListDropDownCount

•	TcxCustomGridTableFiltering.Position -> TcxGridFilterBox.Position

•	TcxCustomGridTableFiltering.Visible -> TcxGridFilterBox.Visible

Implementation Note: for example, instead of using the View's Filtering.CustomizeDialog property, use the View's FilterBox.CustomizeDialog property.

•	TcxGridTableFiltering.ColumnPopupDropDownWidth -> TcxGridTableFiltering.ColumnPopup.DropDownWidth

•	TcxGridTableFiltering.ColumnPopupMaxDropDownItemCount -> TcxGridTableFiltering.ColumnPopup.MaxDropDownItemCount

Implementation Note: for example, instead of using the View's Filtering.ColumnPopupDropDownWidth property, use the View's Filtering.ColumnPopup.DropDownWidth property.

•	TcxGridTableOptionsView.NewItemRow -> TcxGridNewItemRowOptions.Visible

•	TcxGridTableOptionsView.NewItemRowInfoText -> TcxGridNewItemRowOptions.InfoText

•	TcxGridTableOptionsView.NewItemRowSeparatorColor -> TcxGridNewItemRowOptions.SeparatorColor

•	TcxGridTableOptionsView.NewItemRowSeparatorWidth -> TcxGridNewItemRowOptions.SeparatorWidth

Implementation Note: for example, instead of using the View's OptionsView.NewItemRow property, use the View's NewItemRow.Visible property.

2. The cxGridViewData unit has been removed.  You should remove this unit from the 'uses' clause in your projects.

3. The cxExportGrid4Link unit has been renamed to cxGridExportLink.  The procedures it contains have been renamed as well:

•	ExportGrid4ToExcel -> ExportGridToExcel

•	ExportGrid4ToHTML -> ExportGridToHTML

•	ExportGrid4ToText -> ExportGridToText

•	ExportGrid4ToXML -> ExportGridToXML

Implementation Note: you should change the unit name in the 'uses' clause in your projects, and in addition, correct the calls to the procedures mentioned above.

Banded Table Views

1. The following properties are now obsolete (public).  Use their new published substitutes instead:

•	TcxGridBand.Hidden -> TcxGridBand.VisibleForCustomization

•	TcxGridBandedColumn.Hidden -> TcxGridBandedColumn.VisibleForCustomization

Card Views

1. The following properties are now obsolete (public).  Use their new published substitutes instead:

•	TcxGridCardViewRow.Hidden -> TcxGridCardViewRow.VisibleForCustomization

•	TcxGridCardViewFiltering.RowPopupDropDownWidth -> TcxGridCardViewFiltering.RowPopup.DropDownWidth

•	TcxGridCardViewFiltering.RowPopupMaxDropDownItemCount -> TcxGridCardViewFiltering.RowPopup.MaxDropDownItemCount

Implementation Note: for example, instead of using the View's Filtering.RowPopupDropDownWidth property, use the View's Filtering.RowPopup.DropDownWidth property.

Chart Views

1. The View's ViewData.ValueCount property has been removed, use the View's ViewData.CategoryCount property instead.

2. The diagram's AxisValue.GetTickMarkLabelFormat method now requires a boolean parameter.  You should pass True to get the same results as in previous versions.

3. Series - The GetValueCaption(AIndex) function has been removed.  Instead, use GetValueDisplayText(Values[AIndex]) for all series values and VisibleDisplayTexts[AIndex] for the values of visible series.


Resource Strings

Strings displayed in various message boxes, dialogs and control elements of Developer Express VCL products are stored as resources.  This allows you to easily substitute them with custom strings based upon your specific business needs (such as 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 Developer Express VCL Controls.  When controls need a specific string to display, they call the cxGetResourceString function, which returns either the overridden string or the default (if the string was not overridden).

Resource strings are declared in separate files for individual Developer Express VCL products.  Use the links below to obtain information on resource strings available for specific products.  These sections provide resource string identifiers (required by cxSetResourceString) and default values:

ExpressEditors

ExpressQuantumGrid

ExpressDataController

TcxGridPopupMenu

TcxFilterControl

Example

A date editor displays a 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, 'Loschen');

//C++ Builder

cxSetResourceString(&_cxSDatePopupClear, "Loschen");

This code changes the caption of the Clear button for all date editors in the current application.


ExpressQuantumGrid: Resource Strings

See Also

This section describes the resource strings used by the ExpressQuantumGrid in message boxes and control elements and explains how to override default resource string values at runtime.  Refer to the Resource Strings topic for general information on their use.

Resource strings used by the ExpressQuantumGrid are declared in the cxGridStrs unit.

Unsorted resource strings

Resource identifier	Value	Description
scxCantCreateExportOutputFi le	'Can''t create the export output file'	This error message occurs while exporting the contents of the EQGrid to MS Excel® format if the file has already been opened in MS Excel. See the ExportGridToExcel procedure to export EQGrid.
scxGridConverterIntermediar yMissing	'Missing an intermediary component!'#13 #10' Please add a %s component to the form.'	Specifies the error message, which might occur when importing a TdxDBGridLayout component.  When converting from TdxDBGridLayout to EQGrid, a separate TdxDBGrid component must be present on the form.  It will be used as an intermediary when importing. If this error occurs, you must add a TdxDBGrid control to the form and repeat the conversion steps.
scxGridCustomizationFormB andsPageCaption	'Bands'	Specifies the caption of the Bands tabbed page in the Customization form (available only in a banded table view). See the view’s Controller.Customization property.
scxGridCustomizationFormC aption	'Customization'	Specifies the title of the Customization form. See the view’s Controller.Customization property for more information.
scxGridCustomizationFormC olumnsPageCaption	'Columns'	Specifies the caption of the Columns tabbed page in the Customization form. See the view’s Controller.Customization property.
scxGridCustomizationFormRowsPage Caption	'Rows'	Specifies the Rows tab caption in the Customization Form under a card view.
scxGridDeletingConfirmation Caption	'Confirm'	The caption of the message box to confirm deletion of a record(s). The view’s OptionsData.DeletingConfirmation property determines whether the message box is displayed before deleting a record(s).
scxGridDeletingFocusedConfi rmationText	'Delete record?'	The text of the message box to confirm deletion of a single (focused) record. The view’s OptionsData.DeletingConfirmation property determines whether the message box is displayed before deleting a record.
scxGridDeletingSelectedConfi rmationText	'Delete all selected records?'	The text of the message box to confirm deletion of selected records. The view’s OptionsData.DeletingConfirmation property determines whether the message box is displayed before deleting records. To enable multiple selection, set the view’s OptionsSelection.MultiSelect property to True.
scxGridFilterApplyButtonCaption	'Apply Filter'	Specifies the caption of the Apply Filter button in the filter dropdown. See the description on the view’s Filtering.ColumnPopup.ApplyMultiSelectChanges (or Filtering.RowPopup.ApplyMultiSelectChanges) property.
scxGridFilterCustomizeButto nCaption	'Customize...'	Specifies the caption of the Customize button in the filter panel.  See the view’s FilterBox.CustomizeDialog property for more information.
scxGridFilterIsEmpty	'<Filter is Empty>'	A string is displayed in the filter panel when filter criteria for the current view are empty.  If they are not, this string is replaced by a text representation of filter conditions. See the view’s FilterBox.Visible property to make the filter panel visible.
scxGridFilterRowInfoText	'Click here to define a filter'	Specifies the descriptive text of the Filter Row.
scxGridGroupByBoxCaption	'Drag a column header here to group by that column'	Specifies the string displayed within the group panel when data is not grouped by any column.  Set the view’s OptionsView.GroupByBox property to True to make the panel visible.
scxGridNewItemRowInfoText	'Click here to add a new row'	Specifies the descriptive text of the New Item Row
scxGridNoDataInfoText	'<No data to display>'	This string is displayed in the center of a view if it has no data to display.  Note that this may occur as a result of filtering.
scxGridRecursiveLevels	'You cannot create recursive levels'	The error occurs when assigning any child of a specific grid level or the grid level itself to its Parent property.
scxImportErrorCaption	'Import error'	Specifies the caption of the error message, which can occur when importing a TdxDBGridLayout component.  When converting from TdxDBGridLayout to EQGrid, a separate TdxDBGrid component must be present on the form.  It will be used as an intermediary during data import. If this error occurs, you must add a TdxDBGrid control to the form and repeat the conversion steps.
scxNotExistGridLevel	'Active grid level does not exist'	The error occurs when the grid control does not contain any active root grid level during data export (the ActiveLevel property is NIL).  This can occur when the grid control does not contain any level or the level’s Visible property is set to False.

Chart View resource strings

Resource identifier	Value	Description
scxGridChartCategoriesDisplayText	'Data'	Specifies the descriptive text for default categories. See the View’s Categories.DisplayText property for details.
scxGridChartValueHintFormat	'%s for %s is %s'	Specifies the format string for value hints. See the View’s OptionsBehavior.ValueHints property for details.
scxGridChartPercentValueTickMark LabelFormat	'0%'	Specifies the value’s format of the tick-mark label.
scxGridChartToolBoxDataLevels	'Data Levels:'	Specifies the default label caption, which identifies data levels in the data level navigator.
scxGridChartToolBoxDataLevelSele ctValue	'select value'	Specifies the string representation of a data group’s active value. See the View’s ActiveDataGroup.ActiveValueDisplayText property.
scxGridChartToolBoxCustomizeBu ttonCaption	'Customize Chart'	Specifies the caption of the chart customization button. See the View’s ToolBox.CustomizeButton property.
scxGridChartNoneDiagramDisplayT ext	'No diagram'	This string is displayed within the diagram selector when no diagram is currently active within the Chart View. See the View’s ActiveDiagram property for details.
scxGridChartColumnDiagramDispla yText	'Column diagram'	Specifies the descriptive text of the column diagram. See the View’s ActiveDiagram.DisplayText property.
scxGridChartBarDiagramDisplayText	'Bar diagram'	Specifies the descriptive text of the bar diagram. See the View’s ActiveDiagram.DisplayText property.
scxGridChartLineDiagramDisplayText	'Line diagram'	Specifies the descriptive text of the line diagram. See the View’s ActiveDiagram.DisplayText property.
scxGridChartAreaDiagramDisplayText	'Area diagram'	Specifies the descriptive text of the area diagram. See the View’s ActiveDiagram.DisplayText property.
scxGridChartPieDiagramDisplayText	'Pie diagram'	Specifies the descriptive text of the pie diagram. See the View’s ActiveDiagram.DisplayText property.
scxGridChartCustomizationFormSe riesPageCaption	'Series'	Specifies the caption of the Series tab in the Customization Form. See the description on the TcxGridChartSeries class.
scxGridChartCustomizationFormSort BySeries	'Sort by:'	Specifies the title of the Series list in the Customization Form.
scxGridChartCustomizationFormNo SortedSeries	'<none series>'	Specifies the descriptive text for an item in the Series list of the Customization Form.
scxGridChartCustomizationFormDa taGroupsPageCaption	'Data Groups'	Specifies the caption of the Data Groups tab in the Customization Form. See the description on the TcxGridChartSeries class.
scxGridChartCustomizationFormOpti onsPageCaption	'Options'	Specifies the caption of the Options tab in the Customization Form. See the description on the TcxGridChartSeries.
scxGridChartLegend	'Legend'	Specifies the Legend category’s caption at the Options page of the Customization Form.
scxGridChartLegendKeyBorder	'Key Border'	Specifies the caption of the Key Border check box under the Legend category at the Options page of the Customization Form.
scxGridChartPosition	'Position'	Specifies the Position subcategory’s caption at the Options page of the Customization Form.
scxGridChartPositionDefault	'Default'	Specifies the Default radio button’s caption under the Position subcategory at the Options page of the Customization Form.
scxGridChartPositionNone	'None'	Specifies the None radio button’s caption under the Position subcategory at the Options page of the Customization Form.
scxGridChartPositionLeft	'Left'	Specifies the Left radio button’s caption under the Position subcategory at the Options page of the Customization Form.
scxGridChartPositionTop	'Top'	Specifies the Top radio button’s caption under the Position subcategory at the Options page of the Customization Form.
scxGridChartPositionRight	'Right'	Specifies the Right radio button’s caption under the Position subcategory at the Options page of the Customization Form.
scxGridChartPositionBottom	'Bottom'	Specifies the Bottom radio button’s caption under the Position subcategory at the Options page of the Customization Form.
scxGridChartAlignment	'Alignment'	Specifies the Alignment subcategory’s caption at the Options page of the Customization Form.
scxGridChartAlignmentDefault	'Default'	Specifies the Default radio button’s caption under the Alignment subcategory at the Options page of the Customization Form.
scxGridChartAlignmentStart	'Start'	Specifies the Start radio button’s caption under the Alignment subcategory at the Options page of the Customization Form.
scxGridChartAlignmentCenter	'Center'	Specifies the Center radio button’s caption under the Alignment subcategory at the Options page of the Customization Form.
scxGridChartAlignmentEnd	'End'	Specifies the End radio button’s caption under the Alignment subcategory at the Options page of the Customization Form.
scxGridChartOrientation	'Orientation'	Specifies the Orientation subcategory’s caption at the Options page of the Customization Form.
scxGridChartOrientationDefault	'Default'	Specifies the Default radio button’s caption under the Orientation subcategory at the Options page of the Customization Form.
scxGridChartOrientationHorizontal	'Horizontal'	Specifies the Horizontal radio button’s caption under the Orientation subcategory at the Options page of the Customization Form.
scxGridChartOrientationVertical	'Vertical'	Specifies the Vertical radio button’s caption under the Orientation subcategory at the Options page of the Customization Form.
scxGridChartBorder	'Border'	Specifies the caption of the Border check box at the Options page of the Customization Form.
scxGridChartTitle	'Title'	Specifies the Title category’s caption at the Options page of the Customization Form.
scxGridChartToolBox	'ToolBox'	Specifies the ToolBox category’s caption at the Options page of the Customization Form.
scxGridChartDiagramSelector	'Diagram Selector'	Specifies the caption of the Diagram Selector check box under the ToolBox category at the Options page of the Customization Form.
scxGridChartOther	'Other'	Specifies the Other category’s caption at the Options page of the Customization Form.
scxGridChartValueHints	'Value Hints'	Specifies the caption of the Value Hints check box under the Other category at the Options page of the Customization Form.

Date ranges resource strings

Resource identifier	Value	Description
scxGridYesterday	'Yesterday'	Specifies the Yesterday time range’s caption. See the TcxGridYesterdayRange and the View's DateTimeHandling.Filters property.
scxGridToday	'Today'	Specifies the Today time range’s caption. See the TcxGridTodayRange and the View's DateTimeHandling.Filters property.
scxGridTomorrow	'Tomorrow'	Specifies the Tomorrow time range’s caption. See the TcxGridTomorrowRange and the View's DateTimeHandling.Filters property.
scxGridLast30Days	'Last 30 days'	Specifies the Last 30 days time range’s caption. See the View's DateTimeHandling.Filters property.
scxGridLast14Days	'Last 14 days'	Specifies the Last 14 days time range’s caption. See the View's DateTimeHandling.Filters property.
scxGridLast7Days	'Last 7 days'	Specifies the Last 7 days time range’s caption. See the View's DateTimeHandling.Filters property.
scxGridNext7Days	'Next 7 days'	Specifies the Next 7 days time range’s caption. See the View's DateTimeHandling.Filters property.
scxGridNext14Days	'Next 14 days'	Specifies the Next 14 days time range’s caption. See the View's DateTimeHandling.Filters property.
scxGridNext30Days	'Next 30 days'	Specifies the Next 30 days time range’s caption. See the View's DateTimeHandling.Filters property.
scxGridLastTwoWeeks	'Last two weeks'	Specifies the Last two weeks time range’s caption. See the View's DateTimeHandling.Filters property.
scxGridLastWeek	'Last week'	Specifies the Last week time range’s caption. See the TcxGridLastWeekRange and the View's DateTimeHandling.Filters property.
scxGridThisWeek	'This week'	Specifies the This week time range’s caption. See the TcxGridThisWeekRange and the View's DateTimeHandling.Filters property.
scxGridNextWeek	'Next week'	Specifies the Next week time range’s caption.  See the TcxGridNextWeekRange and the View's DateTimeHandling.Filters property.
scxGridNextTwoWeeks	'Next two weeks'	Specifies the Next two weeks time range’s caption. See the View's DateTimeHandling.Filters property.
scxGridLastMonth	'Last month'	Specifies the Last month time range’s caption. See the TcxGridLastMonthRange and the View's DateTimeHandling.Filters property.
scxGridThisMonth	'This month'	Specifies the This month time range’s caption. See the TcxGridThisMonthRange and the View's DateTimeHandling.Filters property.
scxGridNextMonth	'Next month'	Specifies the Next month time range’s caption. See the TcxGridNextMonthRange and the View's DateTimeHandling.Filters property.
scxGridLastYear	'Last year'	Specifies the Last year time range’s caption. See the TcxGridLastYearRange and the View's DateTimeHandling.Filters property.
scxGridThisYear	'This year'	Specifies the This year time range’s caption. See the TcxGridThisYearRange and the View's DateTimeHandling.Filters property.
scxGridNextYear	'Next year'	Specifies the Next year time range’s caption. See the TcxGridNextYearRange and the View's DateTimeHandling.Filters property.
scxGridPast	'Past'	Specifies the Past time range’s caption. See the View's DateTimeHandling.Filters property.
scxGridFuture	'Future'	Specifies the Future time range’s caption. See the View's DateTimeHandling.Filters property.
scxGridMonthFormat	'mmmm yyyy'	Specifies the format pattern of the date/time values grouped by month. See the View’s DateTimeHandling.GetMonthFormat method.
scxGridYearFormat	'yyyy'	Specifies the format pattern of the date/time values grouped by year. See the View’s DateTimeHandling.GetYearFormat method.


cxGridPopupMenu: Resource Strings

See Also

This section describes the resource strings used by the TcxGridPopupMenu component for built-in menu items.  TcxGridPopupMenu provides standard popup menus for column headers, View footer panels, group footer panels, and group rows.  To enable built-in menu items, set the TcxGridPopupMenu.UseBuiltInPopupMenus property to True.

Refer to the Resource Strings topic for general information on resource strings.

Resource identifier	Value	Description
cxSGridNone	'None'	Specifies the default caption for the custom menu operation inherited from the TcxGridPopupMenuOperation.

Column Header Popup Menu

Resource identifier	Value	Description
cxSGridAlignCenter	'Align Center'	Specifies an action, which aligns a column’s contents to the center.
cxSGridAlignLeft	'Align Left'	Specifies an action, which aligns a column’s contents to the left.
cxSGridAlignmentSubMenu	'Alignment'	The caption for the menu item to combine alignment relevant options (Align Center, Align Left, Align Right).
cxSGridAlignRight	'Align Right'	Specifies an action, which aligns a column’s contents to the right.
cxSGridBestFit	'Best Fit'	Specifies an action, which changes the width of a column so that all its values are displayed entirely. The program equivalent of this option is the item’s ApplyBestFit method.
cxSGridBestFitAllColumns	'Best Fit (all columns)'	Specifies an action, which changes the widths of all columns so that their values are displayed entirely. The program equivalent of this option is the View's ApplyBestFit method.
cxSGridClearSorting	'Clear Sorting'	Specifies an action, which clears sorting against a column. The program equivalent of this option is setting the column’s SortOrder property to soNone.
cxSGridFieldChooser	'Field Chooser'	Specifies an action, which toggles the visibility of the View’s Customization form. The program equivalent of this option is setting the column’s SortOrder property to soNone.
cxSGridGroupByBox	'Group By Box'	Specifies an action, which toggles the visibility of the View’s Group By box. The program equivalent of this option is the View’s Controller.Customization property.
cxSGridGroupByThisField	'Group By This Field'	The caption for the menu item used to group data by a specific column. When you click the menu item, the current column is added to the collection of grouping columns (the column will be displayed within the group panel). The program equivalent of the option is the view’s OptionsView.GroupByBox property. The menu is invoked by right-clicking a column header.
cxSGridRemoveColumn	'Remove This Column'	The caption for the menu item used to hide the current column. Selecting the option hides the column by setting its Visible property to False.
cxSGridSortColumnAsc	'Sort Ascending'	The caption for the menu item used to specify the ascending sort order for the current column. Selecting this option in turn activates the ascending sort order or disables sorting. The program equivalent of the option is setting the column’s SortOrder property to soAscending or soNone. The menu is invoked by right-clicking a column header.
cxSGridSortColumnDesc	'Sort Descending'	The caption for the menu item used to specify the ascending sort order for the current column. Selecting the option in turn activates the descending sort order or disables sorting. The program equivalent of the option is setting the column’s SortOrder property to soDescending or soNone. The menu is invoked by right-clicking a column header.
cxSGridRemoveThisGroup Item	'Remove from grouping'	The caption for the menu item used to hide the current column. Selecting the option hides the column by setting its Visible property to False.
cxSGridShowFooter	'Footer'	The caption for the menu item used to display/hide the Footer panel. The Footer panel is used to display footer summaries (summaries calculated against all records of the current view). Selecting the option in turn sets the view’s OptionsView.Footer property to False (if the panel is visible) or True (if the panel is hidden). The menu is invoked by right-clicking a column header.
cxSGridShowGroupFooter	'Group Footers'	The caption for the menu item used to display/hide Group Footers. Group Footers allow displaying group summaries (summaries calculated against data groups when grouping is applied). Selecting the option in turn sets the view’s OptionsView.GroupFooters property to False (if group footers are visible) or True (if they are hidden). The menu is invoked by right-clicking a column header.

Footer Popup Menu

Resource identifier	Value	Description
cxSGridAvgMenuItem	'Average'	The caption for the menu item used to calculate an Average summary value against a specific column. Selecting this option removes the existing summary item or creates a new one to calculate the average value against the column.
cxSGridCountMenuItem	'Count'	The caption for the menu item used to calculate a Count summary value against a specific column. Selecting this option removes the existing summary item or creates a new one to calculate the number of records within a group or the total number of records in the current view.
cxSGridMaxMenuItem	'Max'	The caption for the menu item used to calculate a Max summary value against a specific column. Selecting this option removes the existing summary item or creates a new one to calculate the maximum value against the column.
cxSGridMinMenuItem	'Min'	The caption for the menu item used to calculate a Min summary value against a specific column. Selecting this option removes the existing summary item or creates a new one to calculate the minimum value against the column. The menu is invoked by right-clicking the view’s Footer and Group Footer panels.
cxSGridNoneMenuItem	'None'	The caption for the menu item used to remove a summary, if any, for the current column.
cxSGridSumMenuItem	'Sum'	The caption for the menu item used to calculate a Sum summary value against a specific column. Selecting this option removes the existing summary item or creates a new one to calculate a sum of values against the column.

Group Row Popup Menu

Resource identifier	Value	Description
cxSGridSortByGroupValues	'Sort by Group Value'	The caption for the menu item used to sort group rows by group values. Selecting this option sorts group rows at the same level by their values.
cxSGridSortBySummary	'%s for %s'	The format pattern used to create the default caption for menu items associated with group summary objects available at this level. The first format specifier denotes the summary function used to calculate the group summary.  The second format specifier denotes the column for which the group summary is calculated. Selecting any of these menu items specifies a group summary whose values are used to sort group rows at the same level.
cxSGridSortBySummary Caption	'Sort by Group Summary:'	The caption for the menu item used as a label before a list of menu items that correspond to all available group summaries at this level.


Area Diagram

An area diagram emphasizes the magnitude of a chart value change over time or another continuous scale represented by categories.  In area diagrams, a data marker consists of the following elements:

•	a value marker;

•	a value area;

•	a line that connects a value point with the previous.


Axis

An axis is a fixed line that provides a description and a measurement for data displayed within diagrams.  In Chart Views, there are two types of axes: a category axis and a value axis.

Column, bar, line, and area diagrams provide axes for chart value measurements and comparisons.

The following image demonstrates category and value axes in a column diagram.


Bar Diagram

In bar diagrams, a bar represents a data marker.  The length of a bar is determined by the corresponding chart value.


Category

In Chart Views, categories classify chart values for comparison purposes.  Categories and their values correspond to group rows and grouping values in tabular Views.

A category displays one or more related chart values.  The number of chart values displayed per category depends upon the diagram type (a simple or multiple diagram).

Default categories display chart values at the highest data level and provide a simple classification of chart values without aggregation.  In terms of databases, default categories stand for a data column, which uniquely identifies and refers to the values within a data record.


Category Axis

A category axis is displayed horizontally in column, line and area diagrams and vertically in a bar diagram.  A category axis is perpendicular to a value axis.

The following image demonstrates a category axis in a column diagram.

The default plotting order of categories depends upon diagram type.  In column, line, and area diagrams, categories are displayed from left to right.  In bar diagrams, they are plotted from bottom to top.


Chart Gridline

A chart gridline is a line that improves viewing and evaluating data displayed within diagrams.  A chart gridline begins at a tick mark and extends across the chart's plot area.  Gridlines associated with the same axis are parallel to each other.

The following image demonstrates chart gridlines in a column diagram.


Chart Value

Chart values represent data visualized by data markers.  The magnitude of a chart value determines the size of the corresponding data marker.

At the highest data level, a chart value represents a series value.  At lower data levels, a chart value is an aggregate value made up of series values within the same category.


Column Diagram

In column diagrams, a column represents a data marker.  The length of a column is determined by the corresponding chart value.


Data Group

A data group represents a set of records combined by a certain condition.  Grouping grid data by items in tabular Views or data levels in Chart Views creates data groups.  The following image displays data in the Table View 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.


Data Group Active Value

A data group’s active value identifies a category with chart values.  These chart values are drilled by categories associated with an active data group at a higher data level.

In terms of data groups in tabular Views, data group active values correspond to grouping values at the same level.

A data level active value is a graphical representation of a data group active value in the data level navigator.


Data Level

End-users are able to slice and dice data displayed in a Chart View by controlling the level of detail using data levels.  A data level is a graphical representation of a visible data group in the data level navigator.

Note that data levels and visible data groups are interdependent and are interchangeable in this help documentation.

Graphically a data level consists of the following elements:

•	A data level’s label.  Clicking this label activates the data level.  The data level navigator highlights the label of the currently active data level.

•	A data level's active value.  An end-user can click it to invoke the data level's dropdown.

The only exception is the highest data level, which does not correspond to any data group.  This level is associated with default categories and thus is represented only by a label.  The scxGridChartCategoriesDisplayText resource string determines the default caption of this label.

At design time, you can click a data level to access settings of the corresponding data group or default categories.


Data Level Active Value

A data level active value visually represents a data group active value in the data level navigator.  End-users can click a data level’s active value to open the data level’s dropdown and select an appropriate active value from this dropdown.


Data Level Dropdown

Data level dropdowns are displayed in the data level navigator and are used to implement the "drill-down on a value" functionality for data levels.  A data level’s dropdown is populated with unique category values associated with this data level.  These category values represent all the possible active values for this data level.

Once the data level is activated, these category values produce categories into which chart values are arranged in a chart.

End-users can select a value from a data level’s dropdown to specify the data level’s active value and drill down on this value.


Data Level Navigator

The data level navigator is one of the end-user customization tools in the chart toolbox.  This tool displays a hierarchy of data levels and provides an interactive data mining mechanism.

With the data level navigator, end-users are able to:

•	drill down into more detailed charts by selecting active values from data level dropdowns;

•	switch the level of detail by activating data levels with assigned active values.  A data level can be activated by clicking its label;

•	customize a hierarchy of data levels by repositioning and temporarily hiding data levels using drag and drop.

The scxGridChartToolBoxDataLevels resource string determines the default label caption (‘Data Levels:’) which identifies data levels in the data level navigator.


Data Marker

A data marker is a graphical representation of a chart value in a specific category.  Generally, the shape of data markers depends on the diagram type.  Within bar diagrams, bars represent data markers.


Diagram

A chart diagram represents a way of displaying data in a Chart View in the form of graphical shapes (for instance, bars or columns) which determine the type of the diagram and compose its name accordingly.

It is possible to plot one or more data series within a chart diagram to produce both simple and multiple diagrams.

Here are the samples of all the diagrams available in the ExpressQuantumGrid.

Bar Diagram	Column Diagram
Line Diagram	Area Diagram
Pie Diagram

You can also produce line and area stacked diagrams.


Diagram Selector

The diagram selector is one of the end-user customization tools in the chart toolbox.  This tool is used to change the diagram type on the fly both at design time and runtime.

The diagram selector displays the currently active diagram type.  Clicking the diagram selector invokes a list of all the available diagram types.  Selecting an item from the list activates the corresponding diagram type and renders a chart using the selected diagram.

The default item captions that correspond to diagram types are determined by the scxGridChartNoneDiagramDisplayText, scxGridChartColumnDiagramDisplayText, scxGridChartBarDiagramDisplayText, scxGridChartLineDiagramDisplayText, scxGridChartAreaDiagramDisplayText and scxGridChartPieDiagramDisplayText resource strings.


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.


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 in tabular Views.

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.

In Chart Views, group summaries are calculated for each series at any data level associated with the visible data group.


HitTest

HitTests are used to identify a Grid View element by its position within a Grid View.  Every ViewInfo has a GetHitTest method which receives the X and Y coordinates of a specific point within the Grid View and returns the HitTest of the Grid View element whose bounding rectangle includes this point.

HitTest class instances are used internally by the grid control infrastructure.  A developer can use only the HitTestCode method.  This method returns the unique hit code of Grid View elements.


Item

Data in the ExpressQuantumGrid is internally represented in a table.  Individual columns from the table are visually represented by grid items (items for short).

In a tabular View, an item is a grid column.

In a Card View, an item is a card row.

In a Chart View, items are series, data groups, and default categories.


Layer

In a Card View, a layer is either a row (in a horizontal card layout) or a column (in a vertical card layout) that can contain any number of card items.

In a simple card layout, a chain of items can take one of two available orientations: all items can be arranged either in a single row (the horizontal layout – the View’s RowLayout property is set to rlHorizontal) or in a single column (the vertical layout – the View’s RowLayout property is set to rlVertical).

Layers are used when a split layout is applied to a card.  A card can be split into the specified number of horizontal or vertical layers, using the item’s Position.BeginsLayer property.

This property is a toggle.  When active, the next layer (a row or a column) is created.  The new layer begins with the current item and includes all subsequent items until the next item with the Position.BeginsLayer property activated is matched.


Level

Grid data is presented via levels.  In tabular Views, 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.

In Chart Views, levels correspond to data levels.


Line Diagram

A line diagram connects neighboring value points with lines to display a trend in chart values.  In line diagrams, a data marker consists of a value point and a line that connects this value point with the previous.


Multiple Diagram

Unlike simple diagrams, multiple (or grouped) diagrams plot the values of several data series.

Here is a sample of a multiple column diagram.


Pie Diagram

A pie shows the proportional sizes of chart values that make up a total for each series.  Each series produces a pie chart, which is displayed in a rectangular series site.  Pie slices represent data markers.


Record Index

Data in a grid control is internally represented in a tabular form.  One coordinate specifies the record; the other specifies the item.  A record index is an integer number used to address a specific record.  Record indexes are not changed due to sorting.  They always point to same data.


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.


Series

A series in a Chart View represents related data points that are plotted in a chart diagram.  Each data series in a chart has a unique color or pattern (unless specified otherwise) and is represented in the chart legend.  Normally the data (series values) displayed in Chart Views are grouped in categories.  It's possible to plot one or more data series in a chart to produce both simple and multiple (or grouped) diagrams.


Series Site

A series site encloses a pie chart in a rectangular area and provides a descriptive caption for the pie.

At design time, you can click a series site to access the properties of the corresponding series.


Simple Diagram

Unlike multiple diagrams, simple diagrams plot values of a single data series.

Here is a sample of a simple column diagram.


Stacked Diagram

Unlike standard diagrams (also called clustered diagrams), stacked diagrams display the contribution of each chart value to the sum of chart values within the same category.  This may be useful when several series are displayed in a diagram.

Here are samples of stacked diagrams.

Normal stacked diagram		100% stacked diagram


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.


Tick Mark

Similar to divisions on a ruler, tick marks are displayed on an axis to provide a scale by which axis values (category values and chart values) can be more easily seen in a diagram.


Tick-Mark Label

Tick-mark labels identify axis values in diagrams.  Tick-mark labels are displayed near the corresponding tick marks and outside of a chart’s plot area.


Value Area

A value area is the area between the category axis and the line that connects a value point with the previous.

Value areas for all value points constitute an area diagram’s value area.


Value Axis

A value axis represents an axis where chart values are labeled.  A value axis is displayed vertically in column, line and area diagrams and horizontally in a bar diagram.  A value axis is perpendicular to a category axis.

The following image demonstrates a value axis in a column diagram.


Value Hotspot

A value hotspot is a non-visual element, which represents a rectangular area that includes a value marker and the area under the corresponding value point.  The size of the value marker and the distance between a category axis and the value point determine value hotspot dimensions.

Value hotspots are used to determine whether a particular area corresponds to a data marker (for instance, when displaying value hints for chart values).

At design time you can highlight the borders of all value hotspots associated with a particular series by:

•	selecting this series within the Object Inspector or the Component Editor;

•	clicking within value hotspot areas of this series.


Value Marker

A value marker is a symbol that identifies a value point in a data marker.  A value marker is displayed in a legend key.

The following image demonstrates circular and triangular value markers.


Value Point

A value point corresponds to a chart value and represents the outermost point of the corresponding data marker.  You can visually identify value points in a chart using value markers.

The following image demonstrates value points which are identified using circular value markers.


View

A grid control cannot represent data itself.  Data is represented by "Grid Views", while the grid control is a container for these "Grid Views".

For instance, the Card View (one of the four standard Views of a grid control) enables you to arrange a database as a set of cards, each of which is a database record, while the Table View provides a standard tabular database representation (each database record corresponds to its table row).  To display data in a more logical manner, table columns can be arranged in bands with the help of the Banded Table View.  The Chart View allows you to visualize data using various diagrams which represent values in the form of data markers.

The Grid View is a structure representing a database in a convenient and user-friendly manner.

Each Grid View consists of Grid View elements.  They have different functionality:

•	Data representation (Cells, Data Markers)

•	Navigation (Indicator)

•	Data arrangement (Bands, Columns, Group By Box, Filter Panel, Card, Categories, Series)

•	Analysis and summary (Group and grid Footer Panels)

•	Description (Preview Section, Chart Legend)

The set of these Grid View elements available is determined by the View’s type.


ViewInfo

Each Grid View element has its own painter and is painted based on specific settings.  These settings are stored within the ViewInfo property of a Grid View element.  ViewInfo attributes provide a lot of useful information on an element:

•	Bounding Rectangle and other size and position parameters

•	Colors and fonts

•	Specific parameters of an element (such as the indicator type of the Table View indicator).

ViewInfos can be used when you want to completely redraw a specific grid element.  For this purpose, every type of a Grid View element has the custom draw feature implemented by the OnCustomDraw events (check the desired View reference for detailed information).


TcxCustomGridCellViewInfo
TcxCustomGridCellViewInfo Object

Hierarchy          Properties          Methods

Provides the basic functionality for cell viewinfos.

Unit

cxGridCustomView

TcxCustomGridCellViewInfo = class(TObject, IcxMouseCaptureObject, IcxMouseTrackingCaller, IUnknown)

Description

The term "Cell" within this topic means not exactly a cell of a table grid view, but an abstract cell.

Cell means:

•	a table header

•	a column header

•	a band header

•	a footer

•	a footer cell

•	a group footer

•	a group footer cell

•	an indicator

•	an indicator cell

The TcxCustomGridCellViewInfo class provides basic information on cell painting. ViewInfos are used in the custom draw of a grid control. Custom drawing is performed via the OnCustomDraw events.


TcxCustomGridCellViewInfo Hierarchy
Hierarchy

TObject

     |


Properties for TcxCustomGridCellViewInfo
TcxCustomGridCellViewInfo Properties

TcxCustomGridCellViewInfo          Legend

In TcxCustomGridCellViewInfo

AlignmentHorz

AlignmentVert

BackgroundBitmap

BorderBounds

BorderColor

Borders

BorderSize

Bounds

ContentBounds

ContentHeight

ContentWidth

Height

State

Text

TextAreaBounds

TextAreaHeight

TextAreaWidth

TextHeight

TextWidth

Transparent

Visible

Width


Methods for TcxCustomGridCellViewInfo
TcxCustomGridCellViewInfo Methods

TcxCustomGridCellViewInfo          Legend

In TcxCustomGridCellViewInfo

 GetHitTest

 Invalidate

 Paint


TcxCustomGridCellViewInfo.AlignmentHorz

TcxCustomGridCellViewInfo          See Also

Specifies the horizontal alignment of a cell’s content.

property AlignmentHorz: TAlignment;

Description

The AlignmentHorz property allows a developer to set the horizontal alignment of a cell’s content.


TcxCustomGridCellViewInfo.AlignmentVert

TcxCustomGridCellViewInfo          See Also

Specifies the vertical alignment of a cell’s content.

type

  TcxAlignmentVert = (vaTop, vaBottom, vaCenter);

property AlignmentVert: TcxAlignmentVert;

Description

The AlignmentVert property allows a developer to set the vertical alignment of a cell’s content.

It can be one of the following values:

Value	Description
vaTop	Content is aligned to the upper cell edge.
vaCenter	Content is vertically centered within a cell.
vaBottom	Content is aligned to the lower cell edge.


TcxCustomGridCellViewInfo.BackgroundBitmap

TcxCustomGridCellViewInfo

Contains the background bitmap assigned to the current grid element.

property BackgroundBitmap: TBitmap;

Description

The BackgroundBitmap property enables you to obtain the background bitmap of the corresponding grid view element.  This bitmap can be assigned to the element via the element style of via the BackgroundBitmaps property of the grid view containing the element.

ReadOnly Property


TcxCustomGridCellViewInfo.BorderBounds

TcxCustomGridCellViewInfo          See Also

Contains the bounding rectangle of a specific cell.

property BorderBounds[AIndex: TcxBorder]: TRect;

Description

The BorderBounds property contains the borders bounding rectangle. This rectangle is equal to the bounds of a cell.

ReadOnly Property


TcxCustomGridCellViewInfo.BorderColor

TcxCustomGridCellViewInfo

Obtains the border color of a cell.

property BorderColor[AIndex: TcxBorder]: TColor;

Description

The BorderColor property allows you to obtain a cell’s border color. The AIndex parameter specifies the cell border (left, right, top or bottom) whose color should be obtained.

ReadOnly Property


TcxCustomGridCellViewInfo.Borders

TcxCustomGridCellViewInfo

Specifies the displayed borders of a cell.

property Borders: TcxBorders;

Description

The Borders property enables a developer to specify the borders to display at runtime.  This property can be useful for writing OnCustomDraw event handlers.


TcxCustomGridCellViewInfo.BorderSize

TcxCustomGridCellViewInfo

Obtains the size of a cell border in pixels.

property BorderSize[AIndex: TcxBorder]: Integer;

Description

The BorderSize property allows a developer to obtain the size of a cell border in pixels.  If a border is set, its size is always equal to 1, otherwise the property contains zero. A border can be set or removed via the Borders property.

ReadOnly Property


TcxCustomGridCellViewInfo.ContentBounds

TcxCustomGridCellViewInfo

Contains a specific cell bounding rectangle excluding the border size.

property ContentBounds: TRect;

Description

The ContentBounds property contains a specific cell bounding rectangle.  The bounding rectangle is calculated relative to the upper left corner of the grid control.  The cell border width is not included in the cell bounding rectangle.

To get the width or height of a cell’s content, use the ContentWidth and ContentHeight properties correspondingly.

ReadOnly Property


TcxCustomGridCellViewInfo.ContentHeight

TcxCustomGridCellViewInfo

Contains the height of a specific cell excluding the border size, in pixels.

property ContentHeight: Integer;

Description

The ContentHeight property contains the height of a specific cell in pixels.  The cell border height is not included in the content’s height.

ReadOnly Property


TcxCustomGridCellViewInfo.ContentWidth

TcxCustomGridCellViewInfo

Contains the width of a specific cell excluding the border size.

property ContentWidth: Integer;

Description

The ContentWidth property contains the width of a specific cell.  The cell border width is not included in the content width.

ReadOnly Property


TcxCustomGridCellViewInfo.Height

TcxCustomGridCellViewInfo

Contains the height of a specific cell in pixels.

property Height: Integer;

Description

The Height property contains the height of a specific cell including the border size in pixels.

There are several property groups providing useful information on cell position and size.

The following properties provide information on cell position within a grid control and its size:

•	Bounds,

•	Width,

•	Height.

The following properties provide information on cell content position within a grid control and its size:

•	ContentBounds,

•	ContentWidth,

•	ContentHeight.

The following properties provide information on cell text area position within a grid control and its size:

•	TextAreaBounds,

•	TextAreaWidth,

•	TextAreaHeight.

The following properties provide information on cell text size:

•	TextWidth,

•	TextHeight.

ReadOnly Property


TcxCustomGridCellViewInfo.State

TcxCustomGridCellViewInfo

Allows users to change the cell state at runtime.

type

  TcxGridCellState = (gcsNone, gcsSelected, gcsPressed);

property State: TcxGridCellState;

Description

The cell state affects the appearance of cells and their editing properties.  According to this property cells can be in three states:

•	Selected (gcsSelected) - a cell is currently selected or is located within a selected row.

•	Pressed (gcsPressed) - a user has pressed a cell. This state excludes the selected state.

The third state is the default one (the gcsNone state) when a cell is neither selected nor pressed.


TcxCustomGridCellViewInfo.Text

TcxCustomGridCellViewInfo

Specifies cell text.

property Text: string;

Description

The Text property specifies the displayed cell text.  Keep in mind that data cells (grid view cells) store their text within viewinfos of in-place editors.  Such class descendants as column headers and footer cells viewinfos use this property to store captions.


TcxCustomGridCellViewInfo.TextAreaBounds

TcxCustomGridCellViewInfo

Contains the rectangle bounding a cell’s text area.

property TextAreaBounds: TRect;

Description

The TextAreaBounds property contains the rectangle bounding a cell’s text area. This rectangle specifies the space assigned to cell text.  The bounding rectangle is calculated relative to the upper left corner of the grid control.

The text area bounding rectangle is somewhat smaller than the cell content bounding rectangle. The difference is specified by the cxGridCellTextOffset constant.

ReadOnly Property


TcxCustomGridCellViewInfo.TextAreaHeight

TcxCustomGridCellViewInfo

Contains the height of a cell’s text area.

property TextAreaHeight: Integer;

Description

The TextAreaHeight property contains the height of a cell’s text area in pixels. The height specifies the space assigned to cell text.

The text area height is somewhat smaller than the cell height. The difference is specified by the cxGridCellTextOffset constant.

ReadOnly Property


TcxCustomGridCellViewInfo.TextAreaWidth

TcxCustomGridCellViewInfo

Contains the width of a cell’s text area.

property TextAreaWidth: Integer;

Description

The TextAreaWidth property contains the width of a cell’s text area in pixels. The width specifies the space allowed for cell text.

The text area width is somewhat smaller than the cell width. The difference is specified by the cxGridCellTextOffset constant.

ReadOnly Property


TcxCustomGridCellViewInfo.TextHeight

TcxCustomGridCellViewInfo

Contains the cell text height.

property TextHeight: Integer;

Description

The TextHeight property contains the cell text height specified by the Text property.  The TextAreaHeight property specifies the maximum allowed text height within a cell while the TextHeight specifies the actual cell text height.  Keep in mind that data cells (grid view cells) store their text within viewinfos of in-place editors.  Such class descendants as column headers and footer cells viewinfos use this property to store captions.

ReadOnly Property


TcxCustomGridCellViewInfo.TextWidth

TcxCustomGridCellViewInfo

Contains the cell text width.

property TextWidth: Integer;

Description

The TextWidth property contains the cell text width specified by the Text property.  The TextAreaWidth property specifies the maximum allowed text width within a cell, while the TextWidth specifies the actual cell text width.  Keep in mind that data cells (grid view cells) store their text within viewinfos of in-place editors.  Such class descendants as column headers and footer cells viewinfos use this property to store captions.

ReadOnly Property


TcxCustomGridCellViewInfo.Transparent

TcxCustomGridCellViewInfo

Indicates whether the background bitmap is assigned to the corresponding grid element.

property Transparent: Boolean;

Description

The Transparent property indicates whether the background bitmap is assigned to the corresponding grid element.  If bitmap is assigned the property is True, otherwise it is False.  The background bitmap can be assigned to the element via the element style of via the BackgroundBitmaps property of the grid view containing the element.

ReadOnly Property


TcxCustomGridCellViewInfo.Visible

TcxCustomGridCellViewInfo

Specifies whether a cell is painted within a grid view.

property Visible: Boolean;

Description

The Visible property specifies whether a cell is painted within a grid view.  If the property is false, the cell with its content is not painted within the grid view. But the in-place cell editor still activates when a user clicks on the place where this cell is supposed to be drawn.

Note: If you set the Visible property of a specific cell viewinfo to false, you must perform custom draw of the cell bounding rectangle. Otherwise, the invisible cell will look like a hole displaying everything behind the grid control.


TcxCustomGridCellViewInfo.Width

TcxCustomGridCellViewInfo

Contains the width of a specific cell.

property Width: Integer;

Description

The Width property contains the width of a specific cell including the border size in pixels.

There are several property groups providing useful information concerning cell position and size.

The

•	Bounds,

•	Width,

•	Height

properties provide information on cell position within a grid control and its size.

The

•	ContentBounds,

•	ContentWidth,

•	ContentHeight

properties provide information on cell content position within a grid control and the content size.

The

•	TextAreaBounds,

•	TextAreaWidth,

•	TextAreaHeight

properties provide information on cell text area position within a grid control and the text area

size.

The

•	TextWidth,

•	TextHeight

properties provide information on cell text size.


TcxCustomGridCellViewInfo.GetHitTest

TcxCustomGridCellViewInfo

Returns the hit test for a cell.

function GetHitTest(const P: TPoint): TcxCustomGridHitTest; virtual;

DescriptionThe GetHitTest method returns the hit test class corresponding to a point of the inspected grid view. The hit test allows you to identify grid elements. It can be done via the TcxCustomGridHitTest.HitTestCode method. The method returns the hit code representing a grid element.  To use the GetHitTest method, call it with the P parameter specifying the inspected grid view’s point. The point coordinates are calculated relative to the upper left corner of the grid control.

See the Grid View Elements topic for detailed information on grid views and their elements. See the OnCustomDrawPartBackground for an example of using the TcxCustomGridHitTest.HitTestCode method.


TcxCustomGridCellViewInfo.Invalidate

TcxCustomGridCellViewInfo

Invalidates a specific cell.

procedure Invalidate; virtual;

Description

The Invalidate method enables a developer to invalidate a specific cell whenever it is needed.


TcxCustomGridCellViewInfo.Paint

TcxCustomGridCellViewInfo

Paints a specific cell on a specific canvas.

procedure Paint(ACanvas: TcxCanvas = nil); virtual;

Description

The Paint method enables a developer to paint a specific grid cell on the canvas determined by the ACanvas parameter whenever it is needed.  If the ACanvas parameter is nil, the cell is painted on the grid control canvas.The major difference between the Paint and Invalidate methods is that the Paint method allows users to paint cells on another canvas.


TcxCustomGridCellViewInfo.Bounds

TcxCustomGridCellViewInfo

Contains the bounding rectangle of a specific cell.

Bounds: TRect;

Description

The Bounds field contains the bounding rectangle of a specific cell.


TcxCustomGridViewCellViewInfo
TcxCustomGridViewCellViewInfo Object

Hierarchy          Properties          Methods

Provides common information necessary for grid element painting.

Unit

cxGridCustomView

TcxCustomGridViewCellViewInfo = class(TcxCustomGridCellViewInfo)

Description

The TcxCustomGridViewCellViewInfo class provides painting information common for all grid view elements.  The main purpose of this class is to connect the ViewInfo to the grid view.  All TcxCustomGridViewCellViewInfo descendants are created by the grid view (and can be accessed via the GridView property) that owns grid view elements.  So you shouldn’t create instances of the TcxCustomGridViewCellViewInfo class or its descendants directly.

ViewInfos can be used when you want to redraw a grid element completely.  For this purpose, every type of grid view element has custom draw implemented by the OnCustomDraw events (check the appropriate View reference for detailed information).


TcxCustomGridViewCellViewInfo Hierarchy
Hierarchy

TObject

     |

TcxCustomGridCellViewInfo

     |


Properties for TcxCustomGridViewCellViewInfo
TcxCustomGridViewCellViewInfo Properties

TcxCustomGridViewCellViewInfo          Legend

In TcxCustomGridViewCellViewInfo

GridView

Derived from TcxCustomGridCellViewInfo

AlignmentHorz

AlignmentVert

BackgroundBitmap

BorderBounds

BorderColor

Borders

BorderSize

ContentBounds

ContentHeight

ContentWidth

Height

State

Text

TextAreaBounds

TextAreaHeight

TextAreaWidth

TextHeight

TextWidth

Transparent

Visible

Width


Methods for TcxCustomGridViewCellViewInfo
TcxCustomGridViewCellViewInfo Methods

TcxCustomGridViewCellViewInfo          Legend

Derived from TcxCustomGridCellViewInfo

 GetHitTest

 Paint


TcxCustomGridViewCellViewInfo.GridView

TcxCustomGridViewCellViewInfo

Accesses the owning grid view’s properties and methods.

property GridView: TcxCustomGridView;

Description

The property allows a developer to paint a grid cell based on the owning grid view’s settings.

ReadOnly Property


TcxCustomGridRecordViewInfo
TcxCustomGridRecordViewInfo Object

Hierarchy

Provides common information necessary for painting grid records.

Unit

cxGridCustomTableView

TcxCustomGridRecordViewInfo = class(TcxCustomGridViewCellViewInfo)

Description

The TcxCustomGridRecordViewInfo class provides painting information for grid records.  The main purpose of this class is to connect the ViewInfo to the grid view.  All TcxCustomGridRecordViewInfo descendants are created by the grid view (and can be accessed via the GridView property) that displays grid records.  So you shouldn’t create instances of the TcxCustomGridRecordViewInfo class or its descendants directly.


TcxCustomGridRecordViewInfo Hierarchy
Hierarchy

TObject

     |

TcxCustomGridCellViewInfo

     |

TcxCustomGridViewCellViewInfo

     |


TcxCustomGridViewInfo
TcxCustomGridViewInfo Object

Hierarchy          Properties          Methods

Serves as the base for classes that hold information used to paint views.

Unit

cxGridCustomView

TcxCustomGridViewInfo = class(TcxGridViewHandler)

Description

Grid views introduce the ViewInfo property that can be used to obtain an object holding all the information required to paint a view.  The TcxCustomGridViewInfo class serves as the base for objects that can be returned by the ViewInfo property of actual views.  This class provides a number of properties that hold the information common for all views that can be used within the grid control.

Along with providing painting information, the TcxCustomGridViewInfo object declares the GetHitTest method that can be used to identify which element is located at a view’s particular point.  For instance, this method is useful when you need to response to mouse clicks on view elements.


TcxCustomGridViewInfo Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxGridViewHandler

     |


Properties for TcxCustomGridViewInfo
TcxCustomGridViewInfo Properties

TcxCustomGridViewInfo          Legend

Derived from TcxGridViewHandler

Control

Controller

DataController

GridView

ViewData


Methods for TcxCustomGridViewInfo
TcxCustomGridViewInfo Methods

TcxCustomGridViewInfo          Legend

In TcxCustomGridViewInfo

 GetHitTest

Derived from TcxGridViewHandler

 BeginUpdate

 Create

 EndUpdate


TcxCustomGridViewInfo.GetHitTest

TcxCustomGridViewInfo

Returns an object identifying the view’s element located at a particular point.

Overloaded Variants

function GetHitTest(const P: TPoint): TcxCustomGridHitTest; virtual;

function GetHitTest(X, Y: Integer): TcxCustomGridHitTest; virtual;

Description

Use the GetHitTest method to determine which view element is located under a particular point.  The method has two overloads that allow you to specify the test point either via a TPoint structure or via integer values specifying the horizontal and vertical coordinates.  Note that the coordinates should be specified relatively to the view’s top-left corner.

The GetHitTest method returns a TcxCustomGridHitTest descendant whose properties and methods allow you to identify the element under the test point.  You can use the returned object’s HitTestCode method to determine the element’s type.  The complete list of values that can be returned by this method can be found in the Grid View Elements topic.  In some cases, you will not only need to determine the element’s type.  For instance, if the test point is over a column header, you may want to determine the column whose header it is.  TcxCustomGridHitTest descendants provide additional properties for that purpose.  Please refer to the TcxCustomGridHitTest class description for details.


TcxBorder type

Specifies the cell border.

Unit

ñxGridCustomView

TcxBorder = (bLeft, bTop, bRight, bBottom);

Description

Possible TcxBorder values include:

Kind	Description
bLeft	Specifies the left border.
bTop	Specifies the top border.
bRight	Specifies the right border.
bBottom	Specifies the bottom border.


TcxBorders type

Specifies a set of cell borders.

Unit

cxGridCustomView

TcxBorders = set of TcxBorder;

Description

The TcxBorders is used to specify a set of cell borders.  This type can contain any combination of TcxBorder values.


cxGridCellTextOffset constant

Specifies the offset of the text area relative to cell borders.

Unit

cxGridCommon

const cxGridCellTextOffset = 2;

Description

The cxGridCellTextOffset constant specifies the offset of the text area relative to cell borders.  To determine the size of the text area, use the TcxCustomGridCellViewInfo.TextAreaBounds, TcxCustomGridCellViewInfo.TextAreaWidth and TcxCustomGridCellViewInfo.TextAreaWidth properties.


Incremental Search example

This example shows how incremental searching can be done programmatically.  To allow searching, the view should not be in edit mode.  Thus, the edit controller’s HideEdit method is used to close the currently active editor, if any.  The search starts from the currently focused record.  Thus, the sample below focuses the first record to start searching from it.  The text to search is obtained from a TEdit control.

//Delphi

var

  AView: TcxCustomGridTableView;

//...

  AView := TcxCustomGridTableView(Grid.FocusedView);

  //Close an open editor if any

  AView.Controller.EditingController.HideEdit(True);

  //set focus to the first record

  //to start the search from the beginning

  AView.DataController.GotoFirst;

  //start an incremental search within the tvFilmsCAPTION column

  AView.DataController.Search.Locate(tvFilmsCAPTION.Index, Edit1.Text);

//...

  //continue the search forward

  AView.DataController.Search.LocateNext(True);

//...

  //cancel the search

  AView.DataController.Search.Cancel;

//C++ Builder

  TcxCustomGridTableView * AView =

    (TcxCustomGridTableView*)Grid->FocusedView;

  //Close an open editor if any

  AView->Controller->EditingController->HideEdit(true);

  //set focus to the first record

  //to start the search from the beginning

  AView->DataController->GotoFirst();

  //start an incremental search

  AView->DataController->Search->Locate(tvFilmsCAPTION->Index, Edit1->Text);

//...

  //continue the search

  AView->DataController->Search->LocateNext(true);

//...

  //cancel the search

  AView->DataController->Search->Cancel();


Example: Starting Drag-And-Drop Manually

The following example shows how you can start drag-and-drop manually within the tvCustomers view by handling its OnMouseDown event.  To start a drag-and-drop operation for a view, you should call the BeginDrag method of the view’s grid site object (the BeginDrag method is inherited from the TControl class).  The grid site (TcxGridSite) represents the control which contains and displays the view.  It is passed as the Sender parameter to the OnMouseDown event.  Note: the grid site can also be accessed via the view’s Site property.

To enable starting drag-and-drop manually, you should set the view’s DragMode property to dmManual.

The following OnMouseDown handler starts drag-and-drop if the user clicks within a grid record.

//Delphi

procedure TForm1.tvCustomersMouseDown(Sender: TObject;

  Button: TMouseButton; Shift: TShiftState; X, Y: Integer);

begin

  with TcxGridSite(Sender) do

  begin

    if ViewInfo.GetHitTest(X, Y).HitTestCode = htRecord then

      BeginDrag(False);

  end;

end;

//C++ Builder

void __fastcall TForm1::tvCustomersMouseDown(TObject *Sender,

      TMouseButton Button, TShiftState Shift, int X, int Y)

{

  TcxGridSite * ASite = (TcxGridSite *)Sender;

  if (dynamic_cast<TcxGridRecordHitTest*>
    (ASite->ViewInfo->GetHitTest(X, Y)))

    ASite->BeginDrag(false);

}


Example: StoreToRegistry, RestoreFromRegistry
Example: TcxCustomGridView.StoreToRegistry, TcxCustomGridView.RestoreFromRegistry

See Also

Assume that we have two data-aware views (tvSource and tvTarget) and we need the second view to display the same data as the first (using the same view layout).

The settings of the first view are stored using the StoreToRegistry procedure.  In order to be able to restore view settings to another view, set the ASaveViewName parameter to a non-empty string.  This name will be used in the RestoreFromRegistry procedure when loading settings to the target view.

If you specify a name for the ASaveViewName parameter, items will be stored by their IDs.  The restore procedure reads entries in the registry and applies them to corresponding items based on their ID values.

In order for the following code to work properly, items in the tvSource and tvTarget views must have the same IDs.

When you are running the program, all items within a view are assigned unique zero-based IDs.  The ID of the first item is 0, the ID of the second one is 1, etc.  IDs provide the unique identity of the items within the view.  When an item is deleted, a newly created item might get the ID of the deleted item.  Thus the IDs of items won't be reused within the current state of the view, but may be reused within the lifetime of the view.  This is a limit unique to these IDs.

The code below is created with the following assumption:

•	IDs of the tvSource view items are sequential numbers.  The ID of the first item is zero.

•	the tvTarget view contains no items before running the program.  This ensures that the items created at runtime will get sequential zero-based IDs as well (the same as in the tvSource view).

//Delphi

var

  AStoreKey, ASaveViewName: string;

  I: Integer;

  AOptions: TcxGridStorageOptions;

//...

  //The path to the layout

  AStoreKey := 'Software\MyProjects\TestStoring';

  //The name to refer to the stored settings

  ASaveViewName := 'tvSource Layout';

  AOptions := [];

  //Create items in the tvTarget view

  for I := 0 to tvSource.ItemCount - 1 do

    tvTarget.CreateItem;

  //Save settings of the tvSource view

  tvSource.StoreToRegistry(AStoreKey, True, AOptions, ASaveViewName);

  //Apply settings to the tvTarget view

  tvTarget.RestoreFromRegistry(AStoreKey, False, False, AOptions, ASaveViewName);

  //Make certain that the tvTarget view displays the same data
  //as the tvSource view

  tvTarget.DataController.DataSource :=
    tvSource.DataController.DataSource;

//C++ Builder

  //The path to the layout

  String AStoreKey = "Software\\MyProjects\\TestStoring";

  //The name to refer to the stored settings

  String ASaveViewName = "tvSource Layout";

  TcxGridStorageOptions AOptions;

  //Create items in the tvTarget view

  for(int I = 0; I<tvSource->ItemCount; I++)

    tvTarget->CreateItem();

  //Save settings of the tvSource view

  tvSource->StoreToRegistry(AStoreKey, true, AOptions, ASaveViewName);

  //Apply settings to the tvTarget view

  tvTarget->RestoreFromRegistry(AStoreKey, false, false, AOptions, ASaveViewName);

  //Make certain that the tvTarget view displays the same data
  //as the tvSource view

  tvTarget->DataController->DataSource =
    tvSource->DataController->DataSource;


Example: TcxCustomGridView.OnStartDrag

This example shows how to create a custom drag object for drag-and-drop.  The drag object will provide a drag image to display while dragging records of the tvItems view.  If a user starts dragging within the view with the multi-selection feature enabled (the OptionsSelection.MultiSelect property is set to True), the drag image will display information on the number of selected records:

If the multi-selection feature is disabled, the drag image will look as follows:

To provide a custom drag object, you need to:

•	implement your own class for the drag object by deriving from the TDragObject class or its descendants (TDragControlObjectEx, TDragControlObject)

•	handle the OnStartDrag event of the view within which drag-and-drop starts

•	assign an instance of the custom drag object to the DragObject parameter in the OnStartDrag event handler

The following is an example of implementing a custom drag object when dragging from the tvItems view.  The OnStartDrag event handler just creates a drag object of the TMyDragControlObject class and assigns it to the DragObject parameter.

//Delphi

procedure TForm1.tvItemsStartDrag(Sender: TObject;

  var DragObject: TDragObject);

begin

  DragObject := TMyDragControlObject.Create(Sender as TcxGridSite);

end;

//C++ Builder

void __fastcall TForm1::tvItemsStartDrag(TObject *Sender, TDragObject *&DragObject) {

  DragObject = new TMyDragControlObject((TcxGridSite*)Sender);

}

The TMyDragControlObject class overrides the GetDragImages method inherited from TDragControlObject.  This method should return a list containing the image to be displayed while dragging.  The drag image is created by the private CreateImageList method, which will display information regarding the selected/focused records of the view in the form shown above.

//Delphi

  TMyDragControlObject = class(TDragControlObjectEx)

  private

    FImageList: TImageList;

    procedure CreateImageList;

  protected

    function GetDragImages: TDragImageList; override;

  public

    constructor Create(AControl: TControl); override;

    destructor Destroy; override;

  end;

//...

{ TMyDragControlObject }

constructor TMyDragControlObject.Create(AControl: TControl);

begin

  inherited Create(AControl);

end;

procedure TMyDragControlObject.CreateImageList;

var

  AView: TcxCustomGridTableView;

  s: string;

  ABmp: TBitmap;

begin

  if (FImageList = nil) and (Control is TcxGridSite)then

  begin

    //Get the current view

    AView := TcxCustomGridTableView(TcxGridSite(Control).GridView);

    //Prepare the text to display within the drag image

    if AView.OptionsSelection.MultiSelect then

      s := '      Dragging ' + IntToStr(AView.Controller.SelectedRecordCount) + ' selected records from the ' + AView.Name + ' view'

    else

      s := '      Dragging the focused record from the ' + AView.Name + ' view';

    //Create the drag image

    ABmp := TBitmap.Create();

    try

      with ABmp.Canvas do

      begin

        ABmp.Width := TextWidth(s);

        ABmp.Height := TextHeight(s);

        TextOut(0, 0, s);

      end;

      FImageList := TImageList.CreateSize(ABmp.Width, ABmp.Height);

      FImageList.AddMasked(ABmp, clNone);

    finally

      ABmp.Free();

    end;

  end;

end;

destructor TMyDragControlObject.Destroy;

begin

  if FImageList <> nil then

    FImageList.Free;

  inherited;

end;

function TMyDragControlObject.GetDragImages: TDragImageList;

begin

  if FImageList = nil then

    CreateImageList();

  Result := FImageList;

end;

//C++ Builder

class TMyDragControlObject: public TDragControlObjectEx {

  private:

    TImageList * FImageList;

    void CreateImageList();

  protected:

    TDragImageList * __fastcall GetDragImages();

  public:

    __fastcall TMyDragControlObject(TControl * AControl);

    __fastcall ~TMyDragControlObject();

};

//...

void TMyDragControlObject::CreateImageList() {

  String s;

  TcxGridSite * ASite;

  if ((!FImageList) && (ASite = dynamic_cast<TcxGridSite*>(Control))) {

    //Get the current view

    TcxCustomGridTableView * AView =

      (TcxCustomGridTableView*)ASite->GridView;

    //Prepare the text to display within the drag image

    if (AView->OptionsSelection->MultiSelect)

      s = "      Dragging " +

IntToStr(AView->Controller->SelectedRecordCount) + " selected records from the " + AView->Name + " view";

    else

      s = "      Dragging the focused record from the " +

AView->Name + " view";

    //Create the drag image

    Graphics::TBitmap * ABmp = new Graphics::TBitmap();

    try {

      ABmp->Width = ABmp->Canvas->TextWidth(s);

      ABmp->Height = ABmp->Canvas->TextHeight(s);

      ABmp->Canvas->TextOut(0, 0, s);

      FImageList = new TImageList(ABmp->Width, ABmp->Height);

      FImageList->AddMasked(ABmp, clNone);

    }

    __finally {

      delete ABmp;

    }

  }

}

TDragImageList * __fastcall TMyDragControlObject::GetDragImages() {

  if (!FImageList)

    CreateImageList();

  return FImageList;

}

__fastcall TMyDragControlObject::TMyDragControlObject(TControl * AControl) : TDragControlObjectEx(AControl) {

  FImageList = NULL;

}

__fastcall TMyDragControlObject::~TMyDragControlObject() {

  if (FImageList)

    delete FImageList;

}


Example: TcxCustomGridView.OnGetStoredProperties, OnGetStoredPropertyValue, OnSetStoredProperty, OnInitStoredObject
Example: TcxCustomGridView.OnGetStoredProperties, TcxCustomGridView.OnGetStoredPropertyValue, TcxCustomGridView.OnSetStoredPropertyValue, TcxCustomGridView.OnInitStoredObject

See Also

This example assumes that we have a banded table view named BandedTableView.  Suppose we want to save the view's layout in order to restore it at a later point.  The layout is all the view's properties (property names and their values) along with the properties of the grid columns and card view rows and bands (for a banded table view) which are owned by the view.  There are plenty of different formats/storage types that the view's properties can be stored in, this example uses an INI file.

To save the view’s properties in an INI file, we will use the StoreToIniFile procedure using the default options.  ‘BandedTableViewProperties.ini’ is the file name specified for the INI file.

//Delphi

//...

  BandedTableView.StoreToIniFile('BandedTableViewProperties.ini');

//C++ Builder

//...

  BandedTableView->StoreToIniFile("BandedTableViewProperties.ini");

At a later point, the view’s properties will be restored from the BandedTableViewProperties.ini file using the following code.

//Delphi

//...

  BandedTableView.RestoreFromIniFile('BandedTableViewProperties.ini');

//C++ Builder

//...

  BandedTableView->RestoreFromIniFile("BandedTableViewProperties.ini");

The list of properties that will be saved in external storage needs to be customized as only a few of the view's properties are saved by default.  Whenever the storing procedure (StoreToIniFile, StoreToRegistry or StoreToStream) is called a list of the properties that will be saved is created.  When the list is complete (it contains all the view properties that are saved by default), the OnGetStoredProperties event is fired.

At this point you can easily customize the list, if required.  For instance, let us add the properties which control the appearance of the indicator panel in a view, the Indicator and IndicatorWidth.  In addition to that, we will prevent the saving of unwanted properties, in this case a property which controls the visibility of the footer panel and is named ‘Footer’.

Let us add the OnGetStoredProperties event handling procedure and name it ‘GetStoredProperties’.  The properties’ names are returned by the AProperties parameter which represents the list we need to modify.  Adjust the list as shown in the following code.

//Delphi

procedure TForm1.GetStoredProperties(Sender: TcxCustomGridView;

  AProperties: TStrings);

begin

  AProperties.Add('Indicator');

  AProperties.Add('IndicatorWidth');

  AProperties.Delete(AProperties.IndexOf('Footer'));

end;

//C++ Builder

void __fastcall TForm1::GetStoredProperties(TcxCustomGridView *Sender,

      TStrings *AProperties)

{

  AProperties->Add("Indicator");

  AProperties->Add("IndicatorWidth");

  AProperties->Delete(AProperties->IndexOf("Footer"));

}

The properties to save in the INI file have been specified, but the actual view to which the Indicator and IndicatorWidth properties correspond has not been.  Now it is time to define the link between them.  All you have to do is to handle the OnGetStoredPropertyValue event which is fired when the property's values are stored in external storage (an INI file in this case).

Let us add the handling procedure for this event and name it ‘GetStoredPropertyValue’.  In the following code we assign the actual properties’ values to the stored properties according to their names.  Nothing needs to be done here for the Footer stored property as we previously removed it from the list of the properties that will be saved.

//Delphi

procedure TForm1.GetStoredPropertyValue(Sender: TcxCustomGridView;

  const AName: String; var AValue: Variant);

begin

  if AName = 'Indicator' then

    if Sender is TcxGridTableView then

    begin

      AValue := TcxGridTableView(Sender).OptionsView.Indicator;

      Exit;

    end;

  if AName = 'IndicatorWidth' then

    if Sender is TcxGridTableView then

    begin

      AValue := TcxGridTableView(Sender).OptionsView.IndicatorWidth;

      Exit;

    end;

end;

//C++ Builder

void __fastcall TForm1::GetStoredPropertyValue(TcxCustomGridView *Sender,

      const AnsiString AName, Variant &AValue)

{

  if(AName == "Indicator") {

    if(dynamic_cast<TcxGridTableView*>(Sender)) {

      AValue = TcxGridTableView(Sender).OptionsView->Indicator;

      return;

    }

  }

  if(AName == "IndicatorWidth") {

    if(dynamic_cast<TcxGridTableView*>(Sender)) {

      AValue = TcxGridTableView(Sender).OptionsView->IndicatorWidth;

      return;

    }

  }

}

As a result, the BandedTableViewProperties.ini file will contain only the view properties (names and values) that we specified.  To restore these properties with the values stored in external storage (a file in this case), we have to perform the reverse operation, i.e. initialize the view's properties with the stored property's values.  When the restoration is started, the OnSetStoredPropertyValue event is fired for the view.  Add a handling procedure for this event and name it ‘SetStoredPropertyValue’.  In the following code we reassign the stored properties’ values to the actual view properties according to their names, thus restoring them.

//Delphi

procedure TForm1.SetStoredPropertyValue(Sender: TcxCustomGridView;

  const AName: String; const AValue: Variant);

begin

  if AName = 'Indicator' then

    if Sender is TcxGridTableView then

    begin

      TcxGridTableView(Sender).OptionsView.Indicator := AValue;

      Exit;

    end;

  if AName = 'IndicatorWidth' then

    if Sender is TcxGridTableView then

    begin

      TcxGridTableView(Sender).OptionsView.IndicatorWidth := AValue;

      Exit;

    end;

end;

//C++ Builder

void __fastcall TForm1::SetStoredPropertyValue(TcxCustomGridView *Sender,

      const AnsiString AName, const Variant &AValue)

{

  if(AName == "Indicator") {

    if(dynamic_cast<TcxGridTableView*>(Sender)) {

      TcxGridTableView(Sender).OptionsView->Indicator = AValue;

      return;

    }

  }

  if(AName == "IndicatorWidth") {

      TcxGridTableView(Sender).OptionsView->IndicatorWidth = AValue;

      return;

    }

  }

}

Since the view storing process includes storing the complete set of the view properties along with the properties of the grid view elements (columns, card view rows and bands) which are owned by the view, appropriate events are also fired for these elements thus enabling you to completely customize the entire storing process.

In order to tweak the storing of the grid column or card row properties, use the following events: Item.OnGetStoredProperties, Item.OnGetStoredPropertyValue and Item.OnSetStoredPropertyValue.

For band properties in banded table views use the following events:

Band.OnGetStoredProperties, Band.OnGetStoredPropertyValue and Band.OnSetStoredPropertyValue.

The property storing and restoring customization process for columns and bands is similar to the customization process for a view.

Important Note:	When a grid view element such as a band, column or card row is restored from storage within the view where the object that corresponds to the element is destroyed, the element is re-created and thus the object requires that its events are re-associated with existing event handlers.  This can be accomplished by handling the OnInitStoredObject event.

The following code represents the OnInitStoredObject event handler and demonstrates how to re-associate the events of all the columns (no specific identification is made) whose property storing and restoring is customized by handling the Item.OnGetStoredProperties, Item.OnGetStoredPropertyValue and Item.OnSetStoredPropertyValue events with existing event handlers (the colGetStoredProperties, colGetStoredPropertyValue and colSetStoredPropertyValue procedures, respectively).

//Delphi

procedure TForm1.InitStoredObject(

  Sender: TcxCustomGridView;  AObject: TObject);

begin

  if AObject is TcxGridBandedColumn then

    with TcxGridBandedColumn(AObject) do

    begin

      OnGetStoredProperties := colGetStoredProperties;

      OnGetStoredPropertyValue := colGetStoredPropertyValue;

      OnSetStoredPropertyValue := colSetStoredPropertyValue;

    end;

end;

//C++ Builder

void __fastcall TForm1::InitStoredObject(

  TcxCustomGridView *Sender, TObject *AObject)

{

  if(dynamic_cast<TcxGridBandedColumn*>(AObject)) {

    TcxGridBandedColumn* AGridColumn = dynamic_cast<TcxGridBandedColumn*>(AObject);

    AGridColumn->OnGetStoredProperties = colGetStoredProperties;

    AGridColumn->OnGetStoredPropertyValue = colGetStoredPropertyValue;

    AGridColumn->OnSetStoredPropertyValue = colSetStoredPropertyValue;

  }

}


Example: Invoke an edit dialog on double-clicking

The following example shows how you can open your EditRecord dialog when the end-user double-clicks within a grid view.

The view’s OnDblClick event is fired on double-clicking.  The GetCursorPos function provides the current coordinates of the event.  However, these coordinates are calculated relative to the top-left corner of the screen and you need to convert them to the view’s client coordinates.  For this purpose, you should use the ScreenToClient method of the grid site containing the view.

After the coordinates are obtained, the clicked record is determined by using hit test functionality.  The GetHitTest function returns an object containing information on the grid element at a particular position.  If a user has clicked a record or its cell, GetHitTest will return a TcxGridRecordHitTest object or its descendant and the GridRecord property will identify the record itself.

//Delphi

procedure TForm1.tvCustomersDblClick(Sender: TObject);

var

  APoint: TPoint;

  AHitTest: TcxCustomGridHitTest;

  ARecord: TcxCustomGridRecord;

begin

  GetCursorPos(APoint);

  with Grid.FocusedView.Site do

  begin

    APoint := ScreenToClient(APoint);

    AHitTest := ViewInfo.GetHitTest(APoint);

    if AHitTest is TcxGridRecordHitTest then

    begin

      ARecord := TcxGridRecordHitTest(AHitTest).GridRecord;

      //Call your procedure to activate an edit dialog

      //for the clicked record

      OpenEditRecordDialog(ARecord);

    end;

  end;

end;

//C++ Builder

void __fastcall TForm1::tvCustomersDblClick(TObject *Sender)

{

  TcxGridRecordHitTest * AHitTest;

  TcxCustomGridRecord * ARecord;

  TPoint APoint;

  GetCursorPos(&APoint);

  TcxGridSite * ASite = Grid->FocusedView->Site;

  APoint = ASite->ScreenToClient(APoint);

  if (AHitTest = dynamic_cast<TcxGridRecordHitTest *>

       (ASite->ViewInfo->GetHitTest(APoint)))

  {

    ARecord = AHitTest->GridRecord;

    //Call your procedure to activate an edit dialog

    //for the clicked record

    OpenEditRecordDialog(ARecord);

  }

}


Example: Walking through Levels

The following example shows how you can move focus between nesting levels in a grid control.

Assume that you have two buttons on your form: ButtonLevelUp and ButtonLevelDown.  Clicking these buttons moves focus to upper and lower levels respectively.

Clicking the ButtonLevelUp button moves focus from a nesting level to an upper level.  If the currently focused record belongs to a detail, this action moves focus to the master row owning the detail.  If grouping is applied and the current record belongs to a data group, a click on this button moves focus to the immediate group row containing the record.

The following code shows the OnClick event handler of the ButtonLevelUp button.  To get a parent record for the focused record, we use the ParentRecord property.  The Focused property of a record allows you to move focus to this record.

//Delphi

procedure TForm1.ButtonLevelUpClick(Sender: TObject);

var

  ARecord: TcxCustomGridRecord;

begin

  with TcxCustomGridTableView(Grid.FocusedView) do

  begin

    ARecord := Controller.FocusedRecord;

    if Assigned(ARecord) then

    begin

      ARecord := ARecord.ParentRecord;

      if Assigned(ARecord) then

        ARecord.Focused := True;

    end;

  end;

end;

//C++ Builder

void __fastcall TForm1::ButtonLevelUpClick(TObject *Sender)

{

  TcxCustomGridRecord * ARecord;

  TcxCustomGridTableView * AView =
    (TcxCustomGridTableView *)Grid->FocusedView;

  ARecord = AView->Controller->FocusedRecord;

  if (ARecord != NULL)

  {

    ARecord = ARecord->ParentRecord;

    if (ARecord != NULL)

      ARecord->Focused = true;

  }

}

When the end-user clicks the ButtonLevelDown button, focus moves from an upper level to a nesting level.  If a group row is focused, it is expanded first and then the next record is focused.  If a master row is focused, it is also expanded and then the focus moves to the first record in the corresponding detail view.

The following code shows the OnClick event for the ButtonLevelDown button.  The GetFirstChild function returns the first child for a given record.  Note that before GetFirstChild is called, the record is expanded first.  This ensures that the GetFirstFocusableChild function and the Records[ARecord.Index + 1] statement will return the appropriate child records.

GetFirstFocusableChild returns a child record for a master row.  The Records[ARecord.Index + 1] statement returns a child record for a group row.

//Delphi

procedure TForm1.ButtonLevelDownClick(Sender: TObject);

  function GetFirstChild(ARecord: TcxCustomGridRecord): TcxCustomGridRecord;

  begin

    if ARecord is TcxGridMasterDataRow then

      Result := ARecord.GetFirstFocusableChild

    else

      if ARecord is TcxGridGroupRow then

        Result := ARecord.ViewData.Records[ARecord.Index + 1]

      else

        Result := nil;

  end;

var

  ARecord: TcxCustomGridRecord;

begin

  with TcxCustomGridTableView(Grid.FocusedView) do

  begin

    ARecord := Controller.FocusedRecord;

    if Assigned(ARecord) then

    begin

      ARecord.Expand(False);

      ARecord := Controller.FocusedRecord;

      ARecord := GetFirstChild(ARecord);

      if Assigned(ARecord) then

        ARecord.Focused := True;

    end;

  end;

end;

//C++ Builder

TcxCustomGridRecord * GetFirstChild(TcxCustomGridRecord * ARecord);

void __fastcall TForm1::ButtonLevelDownClick(TObject *Sender)

{

  TcxCustomGridRecord * ARecord;

  TcxCustomGridTableView * AView =
    (TcxCustomGridTableView *)Grid->FocusedView;

  ARecord = AView->Controller->FocusedRecord;

  if (ARecord != NULL) {

    ARecord->Expand(false);

    ARecord = AView->Controller->FocusedRecord;

    ARecord = GetFirstChild(ARecord);

    if (ARecord != NULL)

      ARecord->Focused = true;

  }

}

TcxCustomGridRecord * GetFirstChild(TcxCustomGridRecord * ARecord)

{

  TcxCustomGridRecord * AResult;

  if (dynamic_cast<TcxGridMasterDataRow *>(ARecord))

    AResult = ARecord->GetFirstFocusableChild();

  else

    if (dynamic_cast<TcxGridGroupRow *>(ARecord))

      AResult = ARecord->ViewData->Records[ARecord->Index + 1];

    else

      AResult = NULL;

  return AResult;

}


TcxGridBandedTableBackgroundBitmaps
TcxGridBandedTableBackgroundBitmaps Object

Hierarchy          Properties          Methods

Provides background bitmaps for elements of a banded table view.

Unit

cxGridBandedTableView

TcxGridBandedTableBackgroundBitmaps = class(TcxGridTableBackgroundBitmaps)

Description

The TcxGridBandedTableBackgroundBitmaps object provides a number of properties that specify background bitmaps for elements of banded table views.  These properties and their corresponding elements are:

•	The background of the view (the Background property);

•	Data cells (the Content property);

•	The filter box (the FilterBox property),

•	The view’s footer (the Footer property),

•	Grouping rows (the Group property),

•	The group by box (the GroupByBox property),

•	Column headers (the Header property),

•	Indicator (the Indicator property),

•	Preview sections (the Preview property).

•	The background of the bands panel (the BandBackground property),

•	Band headers (the BandHeader property).

To locate these elements within a grid view, please refer to the Grid View Elements topic.

The TcxGridBandedTableBackgroundBitmaps property can be accessed via the BackgroundBitmaps property of banded table views (TcxGridBandedTableView and TcxGridDBBandedTableView objects).  Most of its properties (see the list above) are inherited from the TcxGridTableBackgroundBitmaps class since table views and banded table views differ only in the availability of the bands feature.  Thus, the TcxGridBandedTableBackgroundBitmaps class introduces only two properties – BandBackground and BandHeader.


TcxGridBandedTableBackgroundBitmaps Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |

TcxCustomGridBackgroundBitmaps

     |

TcxCustomGridTableBackgroundBitmaps

     |

TcxGridTableBackgroundBitmaps

     |


Properties for TcxGridBandedTableBackgroundBitmaps
TcxGridBandedTableBackgroundBitmaps Properties

TcxGridBandedTableBackgroundBitmaps          Legend

In TcxGridBandedTableBackgroundBitmaps

BandBackground

BandHeader

Derived from TcxGridTableBackgroundBitmaps

Footer

Group

GroupByBox

Header

Indicator

Preview

Derived from TcxCustomGridTableBackgroundBitmaps

FilterBox

Content

Derived from TcxCustomGridBackgroundBitmaps

Background

Values


Methods for TcxGridBandedTableBackgroundBitmaps
TcxGridBandedTableBackgroundBitmaps Methods

TcxGridBandedTableBackgroundBitmaps          Legend

Derived from TcxCustomGridBackgroundBitmaps

 Assign


TcxGridBandedTableBackgroundBitmaps.BandBackground

TcxGridBandedTableBackgroundBitmaps

Specifies the background bitmap for the band panel.

property BandBackground: TBitmap;

Description

The grid control enables you to create complex structures of bands so that bands differ in height.  In this case, part of the band panel background is visible under shorter bands.  Use the BandBackground property to specify a bitmap for these areas.

For more information on grid elements’ location, please refer to the Grid View Elements topic.  The Banded Table View Tutorial. Step 2: Bands And Columns topic provides additional information on customizing the bands structure.


TcxGridBandedTableBackgroundBitmaps.BandHeader

TcxGridBandedTableBackgroundBitmaps

Specifies the background bitmap for band headers.

property BandHeader: TBitmap;

Description

Use the BandHeader property to specify the bitmap displayed as the background for band headers.  The image below shows an example.

To locate band headers within a grid view, please refer to the Grid View Elements topic.  The Banded Table View Tutorial. Step 2: Bands And Columns topic provides additional information on customizing the bands structure.


TcxGridBandedTableController
TcxGridBandedTableController Object

Hierarchy          Properties          Methods

Controller for a banded table view.

Unit

cxGridBandedTableView

TcxGridBandedTableController = class(TcxGridTableController)

Description

A controller represents a helper class implementing various functions on behalf of a grid view.  TcxGridBandedTableController provides methods specific to a banded table view.  Its functionality can be accessed via the view’s Controller property.

You can use members of a view controller to:

-	control editing of a record cell

-	set focus to a specific column and record

-	start/cancel an incremental search

-	access the collection of selected records

-	perform scrolling

-	navigate records and items

-	display/hide the customization form


TcxGridBandedTableController Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxGridViewHandler

     |

TcxCustomGridController

     |

TcxCustomGridTableController

     |

TcxGridTableController

     |


Properties for TcxGridBandedTableController
TcxGridBandedTableController Properties

TcxGridBandedTableController          Legend

Derived from TcxGridTableController

Customization

CustomizationForm

CustomizationFormBounds

FocusedColumn

FocusedColumnIndex

FocusedRow

FocusedRowIndex

LeftPos

SelectedRowCount

SelectedRows

TopRowIndex

Derived from TcxCustomGridTableController

EditingController

EditingItem

FocusedItem

FocusedItemIndex

FocusedRecord

FocusedRecordIndex

IncSearchingItem

IncSearchingText

IsEditing

IsIncSearching

SelectedRecordCount

SelectedRecords

TopRecordIndex

Derived from TcxGridViewHandler

Control

Controller

DataController

GridView

ViewData


Methods for TcxGridBandedTableController
TcxGridBandedTableController Methods

TcxGridBandedTableController          Legend

In TcxGridBandedTableController

FindNextColumnVertically

FocusNextColumnVertically

Derived from TcxGridTableController

ClearCellSelection

IsFilterRowFocused

IsNewItemRowFocused

IsSpecialRowFocused

SelectAllCells

SelectAllColumns

SelectCells

SelectColumns

Derived from TcxCustomGridTableController

CancelIncSearching

ClearSelection

CreateNewRecord

DeleteSelection

FindNextItem

FindNextRecord

FocusFirstAvailableItem

FocusNextCell

FocusNextItem

FocusNextRecord

FocusNextRecordWithSelection

GoToFirst

GoToLast

GoToNext

GoToPrev

MakeFocusedItemVisible

MakeFocusedRecordVisible

MakeItemVisible

MakeRecordVisible

Derived from TcxCustomGridController

Scroll

Derived from TcxGridViewHandler

BeginUpdate

Create

EndUpdate


TcxGridBandedTableController.FindNextColumnVertically

TcxGridBandedTableController          See Also

Returns the index of the upper/lower focusable column in the in the current data row.

function FindNextColumnVertically(AFocusedItemIndex: Integer; AGoForward, AGoOnCycle: Boolean): Integer; virtual;

Description

A banded table views enables you to arrange columns in several lines by setting their Position.RowIndex properties.  When a user focuses a column in the top line of the current record and presses the Down arrow key, the focus is moved to a relative column in a lower line of the same record.  Pressing the Up arrow key in the last line focuses a relative column in an upper line.

The FindNextColumnVertically function is used in such cases to locate a column in the upper or lower line(s) relative to the AFocusedItemIndex column.  The direction of the search is defined by the AGoForward property.  If AGoForward is set to True, a column in a lower line is located.  Otherwise, it returns the index of an upper column.

The position of a column within a line is specified by its Position.ColIndex property.  The FindNextColumnVertically function locates a focusable column with Position.ColIndex set to the same value as the Position.ColIndex property of the AFocusedItemIndex column.  If such a column is not found in the following/preceding line(s), the function returns –1.

When the function returns –1, this indicates that the focus should be moved to another record.

The AGoOnCycle parameter specifies whether the search will cycle to the beginning once it has reached the end of the data.  If AGoOnCycle is False, a forward search will stop when reaching the last line and a backward search will stop when reaching the first line.

If AGoOnCycle is True and AGoForward is True, the search of the focusable column will continue from the beginning when reaching the last line.  For a backward search, it will continue from the last line when reaching the first one.


TcxGridBandedTableController.FocusNextColumnVertically

TcxGridBandedTableController          See Also

Focuses the upper/lower focusable column in the current data row.

function FocusNextColumnVertically(AFocusedColumnIndex: Integer; AGoForward, AGoOnCycle: Boolean): Boolean;

Description

A banded table views enables you to arrange columns in several lines by setting their Position.RowIndex properties.  When a user focuses a column in the top line of the current record and presses the Down arrow key, the focus is moved to a relative column in a lower line of the same record.  Pressing the Up arrow key in the last line focuses a relative column in an upper line.

The FocusNextColumnVertically function is used to focus the upper/lower column in these cases.  It looks for a column relative to the AFocusedColumnIndex column in the following/preceding line(s) based on the AGoForward parameter.  AGoForward specifies the direction of the search.

FocusNextColumnVertically calls the FindNextColumnVertically function to get the index of a required column.  If the returned index is a valid, the corresponding column is focused.  Refer to the FindNextColumnVertically description for more details.

FocusNextColumnVertically returns True, if a focusable column was found and focused.  Otherwise, it returns False.


cxGridBandedTableView Unit Overview
cxGridBandedTableView Unit

Classes

TcxGridBand

TcxGridBandedColumn

TcxGridBandedColumnOptions

TcxGridBandedColumnPosition

TcxGridBandedColumnStyles

TcxGridBandedTableBackgroundBitmaps

TcxGridBandedTableController

TcxGridBandedTableOptionsCustomize

TcxGridBandedTableOptionsView

TcxGridBandedTableView

TcxGridBandedTableViewStyles

TcxGridBandedTableViewStyleSheet

TcxGridBandCustomOptions

TcxGridBandHeaderHitTest

TcxGridBandHeaderSizingEdgeHitTest

TcxGridBandHitTest

TcxGridBandOptions

TcxGridBandPosition

TcxGridBandRow

TcxGridBandRows

TcxGridBands

TcxGridBandStyles

TcxGridColumnHeaderVertSizingEdgeHitTest

TcxGridIndicatorBandHeaderHitTest

Global Constants

cxGridBandedTableViewAlternateCaptionSeparator


TcxGridBand
TcxGridBand Object

Hierarchy          Properties          Methods          Events          See Also

Represents a grid view band.

Unit

cxGridBandedTableView

TcxGridBand = class(TCollectionItem);

Description

The TcxGridBand represents a band – an object which can combine several columns.  Combined columns can be positioned into several rows within a band.  Bands are used to group columns in the banded table view of class TcxGridBandedTableView.  This class provides the Bands property supporting the collection of bands in the view.

Column positions within a band are specified via the BandedColumn.Position property values.  End users can move bands within a view by clicking the band headers and moving them to the required position.  When bands are moved, the associated columns are moved also.  To move bands programmatically, use the Index property inherited from the TCollectionItem class.

Band objects provide a user with access to all their columns via the Columns property.  They also provide a set of options controlling the band behavior and this is accessed via the Options property.  The Styles property allows you to define the appearance of the band elements.


TcxGridBand Hierarchy
Hierarchy

TCollectionItem

     |


Properties for TcxGridBand
TcxGridBand Properties

TcxGridBand          Legend

In TcxGridBand

ActuallyVisible

Alignment

Bands

BandLevelIndex

Caption

ChildBandCount

ChildBands

ColumnCount

Columns

FixedKind

FirstChildBottomBand

FirstVisibleChildBottomBand

HeaderAlignmentHorz

HeaderAlignmentVert

GridView

Hidden

IsBottom

IsEmpty

IsFirst

IsLast

IsLastAsChild

IsMostRight

IsRoot

IsVisibleBottom

MinWidth

Options

ParentBand

Position

RootIndex

RootParentBand

Rows

Styles

Tag

Visible

VisibleBandLevelCount

VisibleBottomIndex

VisibleChildBandCount

VisibleChildBands

VisibleForCustomization

VisibleIndex

VisibleRootIndex

Width


Methods for TcxGridBand
TcxGridBand Methods

TcxGridBand          Legend

In TcxGridBand

ApplyBestFit

Assign

Create

Destroy

HasAsParent

MoveBand

MoveColumn

MoveColumns


Events for TcxGridBand
TcxGridBand Events

In TcxGridBand

OnGetStoredProperties

OnGetStoredPropertyValue

OnHeaderClick

OnSetStoredPropertyValue


TcxGridBand.ActuallyVisible

TcxGridBand          See Also

Determines whether the current band is visible within the banded table view.

property ActuallyVisible: Boolean;

Description

Use the ActuallyVisible property to determine the visibility of the current band within the view.  Unlike the Visible property, this property indicates the band’s actual visible state when its parent band (if any) gets hidden and as a result the current band gets hidden too.  For a band which is not explicitly hidden, the ActuallyVisible property in this case returns False, while the Visible property returns True.

ReadOnly Property


TcxGridBand.Alignment

TcxGridBand          See Also

Specifies the band caption text alignment.

property Alignment: TAlignment;

Description

Use the alignment property to specify the band caption text alignment.

Value	Meaning
taCenter	The band caption text is centered within the band header
taLeftJustify	The band caption text is left aligned within the band header
taRightJustify	The band caption text is right aligned within the band header

The default value of the Alignment property is taCenter.

Note: This property is provided for backward compatibility with earlier versions of the ExpressQuantumGrid.  To specify the horizontal alignment for a band’s caption, you should use the TcxGridBand.HeaderAlignmentHorz property.  The TcxGridBand.HeaderAlignmentVert property allows you to specify the vertical alignment for a band’s caption.


TcxGridBand.Bands

TcxGridBand

Returns the band collection which the current band belongs to.

property Bands: TcxGridBands;

Description

Use the Bands property to access the band collection which owns the current band.

ReadOnly Property


TcxGridBand.BandLevelIndex

TcxGridBand          See Also

Returns the nesting (band) level of the current band within a banded table view.

property BandLevelIndex: Integer;

Description

Use the BandLevelIndex property to obtain the nesting (band) level of the current band (number of parent bands up to the root band).  For a root band (one which has no parent band), the BandLevelIndex property returns 0.

ReadOnly Property


TcxGridBand.Caption

TcxGridBand          See Also

Specifies the text representing a band within a view.

property Caption: string;

Description

Use the Caption property to specify the text representing a band within a view.  This text is displayed within the band tabs of a view.  The Caption text position within the band header is determined via the Alignment property.


TcxGridBand.ChildBandCount

TcxGridBand          See Also

Returns the number of immediate child bands which are assigned to the current band.

property ChildBandCount: Integer;

Description

Use the ChildBandCount property to obtain the number of immediate child bands which are assigned to the current band.  The nested bands’ child bands are not taken into account.  For a band which is not a parent band, the ChildBandCount property returns 0.

ReadOnly Property


TcxGridBand.ChildBands

TcxGridBand          See Also

Provides indexed access to the child bands which are assigned to the current band.

property ChildBands[Index: Integer]: TcxGridBand;

Description

Use the ChildBands property to gain access to the collection of child bands which are assigned to the current band.  Each child band is an instance of the TcxGridBand class.  To designate a parent band for a band, you should specify the parent band’s index via the Position.BandIndex property.

End users can move bands within a view by dragging band headers to the required position in the parent band, generally the parent band header’s bottom edge.

ReadOnly Property


TcxGridBand.ColumnCount

TcxGridBand          See Also

Returns the number of columns belonging to the current band.

property ColumnCount: Integer;

Description

Use the ColumnCount property to obtain the number of columns associated with the current band.  All columns belonging to a single band can be accessed via the Columns property.

ReadOnly Property


TcxGridBand.Columns

TcxGridBand          See Also

Provides indexed access to the columns associated with the current band.

property Columns[Index: Integer]: TcxGridBandedColumn;

Description

Use the Columns property to gain access to the collection of columns associated with the current band.  Each column is an instance of the TcxGridBandedColumn class.  The number of columns in a band is determined by the ColumnCount property.  To associate a column with a band, you should specify the column’s position via the BandedColumn.Position property.

End users can move bands within a view by clicking the band headers and moving them to the required position.

ReadOnly Property


TcxGridBand.FirstChildBottomBand

TcxGridBand          See Also

Returns the first (left-most) child band, which is displayed at the bottom of the current band.

property FirstChildBottomBand: TcxGridBand;

Description

Use the FirstChildBottomBand property to obtain the first (left-most) child band, which is displayed at the bottom of the current band.  This child band is the first in the current band which displays view columns (unless it is hidden from a view).

ReadOnly Property


TcxGridBand.FirstVisibleChildBottomBand

TcxGridBand          See Also

Returns the first (leftmost) visible child band, which is displayed at the bottom of the current band.

property FirstVisibleChildBottomBand: TcxGridBand;

Description

Use the FirstVisibleChildBottomBand property to obtain the first (leftmost) child band, which is displayed at the bottom of the current band.  This band is the first in the current band which actually displays view columns and is visible in a view.

ReadOnly Property


TcxGridBand.FixedKind

TcxGridBand          See Also

Specifies whether the band scrolls horizontally or is in a fixed position.

type TcxGridBandFixedKind = (fkNone, fkLeft, fkRight);

property FixedKind: TcxGridBandFixedKind;

Description

Use the FixedKind property to specify where the current band is located horizontally within the view.  The band can be fixed to the left or right of the view or it scrolls horizontally. Fixed bands cannot be moved (i.e. re-ordered in respect of other bands), but they can be hidden from view by drag/dropping to the customization form.  This form allows runtime editing of the view structure and can be activated by setting the View.Controller.Customization property to True.

Value	Meaning
fkNone	The band is not fixed
fkLeft	The band is fixed to the view’s left side
fkRight	The band is fixed to the view’s right side

Whenever a band gets fixed, it automatically becomes a root band.

See the Bands topic for more information about fixed bands.

The default value of the FixedKind property is fkNone.


TcxGridBand.GridView

TcxGridBand

Returns the view owning the Bands collection to which the current band belongs.

property GridView: TcxGridBandedTableView;

Description

Use the GridView property to access the view owning the Bands collection to which the current band belongs.  Properties of this view provide access to the collections of columns and bands, the styles and sets of options and other view settings.

ReadOnly Property


TcxGridBand.HeaderAlignmentHorz

TcxGridBand          See Also

Specifies the horizontal alignment of a band’s caption.

property HeaderAlignmentHorz: TAlignment;

Description

Use the HeaderAlignmentHorz property to specify the horizontal alignment of a band’s Caption.

Value	Meaning
taLeftJustify	The caption is aligned to the left side of a band.
taCenter	The caption is centered within a band.
taRightJustify	The caption is aligned to the right side of a band.

The default value of the HeaderAlignmentHorz property is taCenter.


TcxGridBand.HeaderAlignmentVert

TcxGridBand          See Also

Specifies the vertical alignment of a band’s caption.

type

  TcxAlignmentVert = (vaTop, vaBottom, vaCenter);

property HeaderAlignmentVert: TcxAligmentVert;

Description

Use the HeaderAlignmentVert property to specify the vertical alignment of a band’s Caption.

Value	Meaning
vaTop	The caption is aligned to the top of a band.
vaCenter	The caption is centered within a band.
vaBottom	The caption is aligned to the bottom of a band.

The default value of the HeaderAlignmentVert property is vaCenter.


TcxGridBand.Hidden

TcxGridBand          See Also

Determines whether the current band is visible within the banded table view’s customization form (i.e. hidden from the view).

property Hidden: Boolean;

Description

Note: this property is obsolete.  Use the VisibleForCustomization property instead.


TcxGridBand.IsBottom

TcxGridBand          See Also

Specifies whether the band is at the bottom of the view’s band hierarchy.

property IsBottom: Boolean;

Description

The IsBottom property returns True for a band which has no child bands.  Only these bands have columns assigned.  To access all bottom bands, use the Bands.BottomItems property,

ReadOnly Property


TcxGridBand.IsEmpty

TcxGridBand

Indicates whether the current band displays information within a view.

property IsEmpty: Boolean;

Description

Use the IsEmpty property to determine whether the current band displays information within a view.  This property returns True for the bands which contain visual elements (child bands or columns) that are visible in a view.

ReadOnly Property


TcxGridBand.IsFirst

TcxGridBand

Indicates whether the current band is the left-most bottom band within a view.

property IsFirst: Boolean;

Description

Use the IsFirst property to determine whether the current band is the left-most bottom band within a view.  The band’s position within a view can be changed by clicking the band header followed by dragging it to the required position.  The band is then moved together with all associated columns.

ReadOnly Property


TcxGridBand.IsLast

TcxGridBand

Indicates whether the current band is the right-most bottom band within a view.

property IsLast: Boolean;

Description

Use the IsLast property to determine whether the current band is the right-most bottom band within a view.  The band’s position within a view can be changed by clicking the band header followed by dragging it to the required position.  The band is then moved together with all associated columns.

ReadOnly Property


TcxGridBand.IsLastAsChild

TcxGridBand          See Also

Indicates whether the current band is the last (rightmost) band within the current band hierarchy level.

property IsLastAsChild: Boolean;

Description

Use the IsLastAsChild property to determine whether the current band is the right-most band within the current band hierarchy level (a parent band or a view for the root band).  Unlike the IsLast property, this property indicates the band’s position for any band, not only the bottom one.

ReadOnly Property


TcxGridBand.IsMostRight

TcxGridBand          See Also

Indicates whether the current band is the last (rightmost) visible band within a view.

property IsMostRight: Boolean;

Description

Use the IsMostRight property to determine whether the current band is the rightmost visible band within a view.

ReadOnly Property


TcxGridBand.IsRoot

TcxGridBand          See Also

Specifies whether the band is at the top of the view’s band hierarchy.

property IsRoot: Boolean;

Description

The IsRoot property returns True for a band which has no parent bands.  To access all root bands, use the Bands.RootItems property,

ReadOnly Property


TcxGridBand.IsVisibleBottom

TcxGridBand          See Also

Specifies whether the band is visible as a bottom band.

property IsVisibleBottom: Boolean;

Description

The IsVisibleBottom property returns True for a band which is visible as a bottom band in a view.  A parent band with the IsBottom property set to False is visible as a bottom band when all its child bands are hidden in a view.  To access all visible bottom bands, use the Bands.VisibleBottomItems property,

ReadOnly Property


TcxGridBand.MinWidth

TcxGridBand          See Also

Specifies the minimum width of a band.

property MinWidth: Integer;

Description

The MinWidth property returns the minimum width of a band.  This value cannot exceed the sum of the columns’ minimum widths.  To set the band’s width, use the Width property.


TcxGridBand.Options

TcxGridBand          See Also

Contains settings defining the possibility of the runtime band manipulations, such as moving and resizing.

property Options: TcxGridBandOptions;

Description

The Options settings affect band moving and resizing.  The end user can move a band by clicking and dragging its header.  All columns associated with the band are moved also.  Band sizing can be performed via code by setting the Band.Width property.  The end user can change the band’s width via dragging the appropriate vertical edge of the band.  Band moving and sizing are affected by the banded table view’s OptionsCustomize set of options.


TcxGridBand.ParentBand

TcxGridBand          See Also

Returns the parent band for the current band.

property ParentBand: TcxGridBand;

Description

The ParentBand property returns the parent band for the current band.  If the current band is a root band (has no parent band specified, i.e. its Position.BandIndex property is set to –1), NIL is returned.

ReadOnly Property


TcxGridBand.Position

TcxGridBand          See Also

Specifies the position of a band within a banded table view.

property Position: TcxGridBandPosition;

Description

Use the Position property to specify the nesting level (the band in which the current band will be displayed, also called the parent band) and sequential position (column) within this band.  To assign a band to a parent band you have to set the Position.BandIndex property to a parent band index in the view’s Bands collection.  The Position.ColIndex and Position.RowIndex specify the coordinates of the column within the band.


TcxGridBand.RootIndex

TcxGridBand          See Also

Specifies the band’s position among the view’s root bands.

property RootIndex: Integer;

Description

Use the RootIndex property to specify the current band's horizontal position within the collection of the view’s root bands.  The collection can be accessed via the Bands.RootItems property.  To access all visible root bands within a view, see Bands.VisibleRootItems.

The RootIndex property is applicable to root bands only.  For all other bands, this property returns –1.

End users can change a band's position by clicking the band header and dragging it to the required position.  Moving bands can be restricted by setting the Band.Options.Moving or the BandedTableView.OptionsCustomize.BandMoving properties to False.


TcxGridBand.RootParentBand

TcxGridBand          See Also

Returns the root parent band for the current band.

property RootParentBand: TcxGridBand;

Description

The RootParentBand property returns the root parent (the top-most in the parent band hierarchy) band for the current band.  If the current band is a root band (has no parent band specified, i.e. its Position.BandIndexproperty is set to –1), NIL is returned.

ReadOnly Property


TcxGridBand.Rows

TcxGridBand          See Also

Returns the band rows collection associated with the current band.

property Rows: TcxGridBandRows;

Description

Use the Rows property to gain access to the collection of the band rows associated with the current band.

The column position within its band is represented by two attributes of the GridBandedColumn.Position property: RowIndex and ColIndex.  These properties can be used to specify the column position programmatically.

The end user can change column positions within bands by clicking and dragging column headers.  Column moving can be disabled by setting the BandedTableView.OptionsCustomize.ColumnMoving property to False.

ReadOnly Property


TcxGridBand.Styles

TcxGridBand          See Also

Specifies the set of styles defining the appearance of elements of the current band.

property Styles: TcxGridBandStyles;

Description

Use the Styles property to access the set of styles defining the appearance of elements of the current band.  These elements include: band background, header, band column(s) contents.


TcxGridBand.Tag

TcxGridBand

Stores a value associated with the current band.

property Tag: Longint;

Description

The Tag property has no predefined meaning.  You can use it when it is necessary to store additional values associated with bands or when you need to have an additional band identification mechanism.


TcxGridBand.Visible

TcxGridBand          See Also

Specifies the current band’s visibility.

property Visible: Boolean;

Description

Use the Visible property to specify whether the current band is visible within a view.  To make the band invisible, set this property value to False.  If the band is hidden, then all columns within it are not visible also.

Non-visible bands are displayed in the customization form unless VisibleForCustomization is set to True.

The default value of the Visible property is True.


TcxGridBand.VisibleBandLevelCount

TcxGridBand          See Also

Returns the number of nesting (band) levels occupied by the current band and all its nested bands which are visible within a view.

property VisibleBandLevelCount: Integer;

Description

Use the VisibleBandLevelCount property to obtain the number of nesting (band) levels occupied by the current band and all its nested bands which are visible within a view.  For a bottom band or a parent bar with no child bands visible in a view, the VisibleBandLevelCount property returns 1.

ReadOnly Property


TcxGridBand.VisibleBottomIndex

TcxGridBand          See Also

Returns the band’s horizontal position from amongst the view’s bottom bands which are visible within a view.

property VisibleBottomIndex: Integer;

Description

The VisibleBottomIndex property returns the band’s horizontal position from amongst the view’s bottom bands which are actually visible within a view.  For a band which is not a bottom band, the VisibleBottomIndex property returns -1.  To access all the visible bottom bands, use the Bands.VisibleBottomItems property,

ReadOnly Property


TcxGridBand.VisibleChildBandCount

TcxGridBand          See Also

Returns the number of the current band’s immediate child bands which are visible in a view.

property VisibleChildBandCount: Integer;

Description

Unlike the ChildBandCount property, the VisibleChildBandCount property returns only a count of the current band’s immediate child bands that are visible in the view.  The nested bands’ child bands are not taken into account.  For a band which is not a parent band, the VisibleChildBandCount property returns 0.

ReadOnly Property


TcxGridBand.VisibleChildBands

TcxGridBand          See Also

Provides indexed access to the current band’s child bands which are visible within a view.

property VisibleChildBands[Index: Integer]: TcxGridBand;

Description

Use the VisibleChildBands property to gain access to the collection of child bands which are assigned to the current band.  Unlike the ChildBands property, this property addresses bands that are visible within a view.  Each child band is an instance of the TcxGridBand class.  To designate a parent band for a band, you should specify the parent band’s index via the Position.BandIndex property.

End users can move bands within a view by dragging the band's headers to the required position in the parent band, generally the parent band header’s bottom edge.

ReadOnly Property


TcxGridBand.VisibleForCustomization

TcxGridBand

Specifies whether a band is shown in the Customization Form when moved into the form.

property VisibleForCustomization: Boolean;

Description

The Customization Form is visible onscreen, if the view’s Controller.Customization property is set to True.

A band is moved into the Customization Form, if its Visible property is set to False.  When in the Customization Form, a band is invisible in a View.  It’s also invisible in the Customization Form, if the VisibleForCustomization property is set to False.

Set the VisibleForCustomization property to True to show the currently processed band in the Customization Form.

An end-user can remove a band from a View by dragging its header into the Customization Form.  The band’s OptionsCustomize.BandHiding property specifies the manner in which bands can be hidden.

The default value of the VisibleForCustomization property is True.


TcxGridBand.VisibleIndex

TcxGridBand          See Also

Returns the band’s position within a view.

property VisibleIndex: Integer;

Description

Use the VisibleIndex property to obtain the current band position within a view.  To access all visible bands within a view, see Bands.VisibleItems.

End users can change the band position by clicking the band header and dragging it to the required position.  Band moving can be restricted by setting the Band.Options.Moving or the BandedTableView.OptionsCustomize.BandMoving properties to False.

ReadOnly Property


TcxGridBand.VisibleRootIndex

TcxGridBand          See Also

Returns the root band’s horizontal position from amongst the view’s root bands which are visible within a view.

property VisibleRootIndex: Integer;

Description

Use the VisibleRootIndex property to obtain the current root band’s horizontal position within the collection of the view’s root bands which are visible in the view.  This collection can be accessed via the Bands.VisibleRootItems property.  To access all the root bands within a view, see Bands.RootItems.  Unlike the RootIndex property, this property addresses the root bands which are visible in a view.

End users can change a band's position by clicking the band header and dragging it to the required position.  Moving bands can be restricted by setting the Band.Options.Moving or the BandedTableView.OptionsCustomize.BandMoving properties to False.

ReadOnly Property


TcxGridBand.Width

TcxGridBand

Specifies the current band’s width.

property Width: Integer;

Description

Use the Width property to set the current band’s width.  When a band is resized, all contained columns are resized also.  The column’s MinWidth property affects the band’s minimum width.  The end user can also resize bands by clicking and dragging a vertical edge of the band’s header.  Band resizing availability is determined via the Band.Options.Sizing and BandedTableView.OptionsCustomize.BandSizing properties.

The default value of the Width property is 0.


TcxGridBand.ApplyBestFit

TcxGridBand          See Also

Adjusts the width of the band in order to display its full content.

procedure ApplyBestFit(ACheckSizingAbility: Boolean = False; AFireEvents: Boolean = False); virtual;

Description

Use the ApplyBestFit method to adjust the width of the band in order to display its columns’ cell contents entirely.  The ACheckSizingAbility parameter specifies whether it’s necessary to check if the current band can be resized prior to adjusting its width.  Set the ACheckSizingAbility parameter to True to specify that the width of the current band can only be adjusted if resizing is permitted, i.e. no restrictive options are set.  Otherwise, the current band’s width can always be adjusted.

Set the AFireEvents parameter to True to specify that the events providing notifications about changes to the widths of the current band’s columns (such as the OnColumnSizeChanged event) should be fired.

The ApplyBestFit method iterates through data records and calculates the maximum width of column cells.  It also takes the width of the column caption (see the Caption property) into account.  By default, all data records are processed in order to calculate the best width.  However, you can limit the number of records to process and thus improve performance via the BestFitMaxRecordCount property.

It is possible to adjust a band’s width by double-clicking its right edge.  You can prevent an end-user from changing the band width either by setting the band’s Options.Sizing or the view’s OptionsCustomize.BandSizing properties to False.


TcxGridBand.Assign

TcxGridBand

Copies the attributes of the specified band to the current band.

procedure Assign(Source: TPersistent); override;

Description

The Assign method copies the attributes and event handlers of the band specified by the Source parameter to the current band.  These attributes include Alignment, Caption, FixedKind, VisibleForCustomization, Options, Position, Styles, Visible and Width.


TcxGridBand.Create

TcxGridBand

Creates a new band and adds it to the specified band collection.

constructor Create(Collection: TCollection); override;

Description

The constructor creates a new TcxGridBand instance and adds it to the band collection specified by the Collection parameter.


TcxGridBand.Destroy

TcxGridBand

Destroys the current band.

destructor Destroy; override;

Description

The destructor destroys the current TcxGridBand object and removes itself from the band collection to which it is assigned.


TcxGridBand.HasAsParent

TcxGridBand          See Also

Indicates whether the current band has the specified TcxGridBand as a parent band.

function HasAsParent(ABand: TcxGridBand): Boolean;

Description

Use the HasAsParent method to determine whether the current band has a specific band as its parent band.

HasAsParent performs a recursive search of the parent bands and returns True if the current band or one of its parent bands has the band specified by the ABand parameter as a parent band.  Otherwise, this function returns False.


TcxGridBand.MoveBand

TcxGridBand

Moves the specified band with respect to the other child bands within the current band.

procedure MoveBand(ABand: TcxGridBand; AColIndex: Integer);

Description

Use the MoveBand method to move the band specified by the ABand parameter into the required  horizontal position amongst the other child bands.  The AColIndex parameter specifies the Position.ColIndex property value of the required position.


TcxGridBand.MoveColumn

TcxGridBand

Moves the specified column in respect to other columns within the band.

procedure MoveColumn(AColumn: TcxGridBandedColumn; ARowIndex, AColIndex: Integer);

Description

Use the MoveColumn method to specify the required column position among the other band columns.  The AColumn parameter identifies the column to move, the ARowIndex and the AColIndex parameters specify the values of the RowIndex and ColIndex properties of the required position.


TcxGridBand.MoveColumns

TcxGridBand          See Also

Moves all columns from the current band to the specified band.

procedure MoveColumns(ABand: TcxGridBand);

Description

Use the MoveColumns method to move all the columns in the current band to the one specified by the ABand parameter.  This method moves all the items row by row and column by column thus preserving their hierarchy and visual appearance within the specified band.  Consider this method to be a way of changing the band that owns the columns.


TcxGridBand.OnGetStoredProperties

TcxGridBand          See Also          Example

Occurs when the list of the current band’s properties that will be stored in external storage is produced.

type

  TcxGridBandGetStoredPropertiesEvent = procedure(Sender: TcxGridBand; AProperties: TStrings) of object;

property OnGetStoredProperties: TcxGridBandGetStoredPropertiesEvent;

Description

Handle the OnGetStoredProperties event to customize the list of the current band’s properties that will be stored in external storage such as a file, registry or stream as a part of the owner view.  Whenever the storing process is started, a list of the properties to be stored is produced.  When this event is fired, the list already consists of the names of the band’s properties, which are stored by default.

The Sender parameter specifies the band object whose properties will be stored.

The AProperties parameter specifies the list of properties to be stored.

As for the guiding principles on how to use this event, see the example on how to handle the TcxCustomGridView.OnGetStoredProperties event.


TcxGridBand.OnGetStoredPropertyValue

TcxGridBand          See Also          Example

Occurs when the values of the current band’s properties are stored in external storage.

type

  TcxGridBandGetStoredPropertyValueEvent = procedure(Sender: TcxGridBand; const AName: string; var AValue: Variant) of object;

property OnGetStoredPropertyValue: TcxGridBandGetStoredPropertyValueEvent;

Description

Whenever you have customized the list of properties to be stored in external storage in the OnGetStoredProperties event you should handle the OnGetStoredPropertyValue event to specify their values.  These values will be saved in the resulting output.

The Sender parameter specifies the band object whose properties will be stored.

The AName parameter denotes the name of the current band’s property in the resulting output.

In order to store a specific value for the AName property, set its value to the AValue parameter.

As for the guiding principles on how to use this event, see the example on how to handle the TcxCustomGridView.OnGetStoredPropertyValue event.


TcxGridBand.OnHeaderClick

TcxGridBand          See Also

Occurs on clicking the band header.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnHeaderClick: TNotifyEvent;

Description

Use the OnHeaderClick event to perform specific actions when a band header is clicked.


TcxGridBand.OnSetStoredPropertyValue

TcxGridBand          See Also          Example

Occurs when the values of the current band’s properties are restored from external storage.

type

  TcxGridBandSetStoredPropertyValueEvent = procedure(Sender: TcxGridBand; const AName: string; const AValue: Variant) of object;

property OnSetStoredPropertyValue: TcxGridBandSetStoredPropertyValueEvent;

Description

In order to restore the values of the current band’s properties whose values are not stored by default and whose names and values were explicitly specified in the OnGetStoredProperties and OnGetStoredPropertyValue events correspondingly, handle the OnSetStoredPropertyValue event.  These values will be saved in the resulting output.

The Sender parameter specifies the band object whose properties are being restored.

The AName parameter denotes the name of the current band’s property in the resulting output whose value is being restored from storage and is returned by the AValue parameter.

As for the guiding principles on how to use this event, see the example on how to handle the TcxCustomGridView.OnSetStoredPropertyValue event.


TcxGridBandOptions
TcxGridBandOptions Object

Hierarchy          Properties          See Also

Represents a set of options controlling band manipulations.

Unit

cxGridBandedTableView

TcxGridBandOptions = class(TPersistent);

Description

The TcxGridBandOptions class declares a number of options moving and resizing of bands in a banded table view.  To control this band behavior, use the TcxGridBand.Options property.  This option set controls runtime band manipulation.  If moving and/or resizing is disabled for a band (the corresponding options are deactivated), these actions can still be performed via code.  You can use the Band.Index property to move a band.  The band size is defined via its Width property.

The TcxGridBandedTableView.OptionsCustomize property allows you to specify options common to all bands in a banded table view.


TcxGridBandOptions Hierarchy
Hierarchy

TPersistent

     |

TcxGridBandCustomOptions

     |


Properties for TcxGridBandOptions
TcxGridBandOptions Properties

TcxGridBandOptions          Legend

In TcxGridBandOptions

HoldOwnColumnsOnly

Moving

Sizing

Derived from TcxGridBandCustomOptions

Band


TcxGridBandOptions.HoldOwnColumnsOnly

TcxGridBandOptions

Specifies whether columns can be moved to or from a band.

property HoldOwnColumnsOnly: Boolean;

Description

If you need a band to hold a fixed column set, change the band’s HoldOwnColumnsOnly property to True.  In this case, end users will not be able to drag columns away from this band or add new columns to this band except in the case when nested bands which contain columns are added to this band.  End users will only be allowed to reorder columns within the owning band.  Note that by default, end users are allowed to move columns between any bands.

You can change a column’s owning band via code using the column’s Position.BandIndex property.  This doesn’t depend on the HoldOwnColumnOnly property value.

The default value of the HoldOwnColumnsOnly property is False.


TcxGridBandOptions.Moving

TcxGridBandOptions          See Also

Specifies whether a user can move a band to another position.

property Moving: Boolean;

Description

If Moving is True, a user can move a band to another position by dragging its caption.  Otherwise, band moving is disabled.  You can use the view’s OptionsCustomize.BandMoving property to disable moving of all the bands in a banded table view.

The default value of the Moving property is True.


TcxGridBandOptions.Sizing

TcxGridBandOptions          See Also

Specifies whether a user can resize a band.

property Sizing: Boolean;

Description

The Sizing property specifies whether a user can change the band’s width.  If Sizing is True, a user can drag a band edge to resize the band.  To prevent a user from changing sizes of all bands within a banded table view, use the view’s OptionsCustomize.BandSizing property.

The default value of the Sizing property is True.


TcxGridBands
TcxGridBands Object

Hierarchy          Properties          Methods          See Also

Represents the bands collection of a specific banded table view.

Unit

cxGridBandedTableView

TcxGridBands = class(TOwnedCollection);

Description

A banded table view structure is based on bands.  A band is an object containing columns according to the user’s needs.  All bands within a view can be accessed via the GridBandedTableView.Bands property.  This property identifies an instance of the TcxGridBands class whose Items property indexes the current view bands.

Columns to be displayed within a banded table view must be assigned to an existing band.


TcxGridBands Hierarchy
Hierarchy

TOwnedCollection

     |


Properties for TcxGridBands
TcxGridBands Properties

TcxGridBands          Legend

In TcxGridBands

BottomItemCount

BottomItems

Count

GridView

Items

Layout

RootItemCount

RootItems

VisibleBottomItemCount

VisibleBottomItems

VisibleCount

VisibleItems

VisibleRootItemCount

VisibleRootItems

VisibleRootLeftFixedCount

VisibleRootRightFixedCount

VisibleRowCount


Methods for TcxGridBands
TcxGridBands Methods

TcxGridBands          Legend

In TcxGridBands

Add

AreNested

GetFirstVisibleRootIndex

GetLastVisibleRootIndex

HaveFixedItems


TcxGridBands.BottomItemCount

TcxGridBands          See Also

Returns the number of bottom bands contained within the current collection.

property BottomItemCount: Integer;

Description

Use the BottomItemCount property to obtain the number of bottom bands contained within the current band collection.

ReadOnly Property


TcxGridBands.BottomItems

TcxGridBands          See Also

Provides indexed access to all the bottom bands in the current collection.

property BottomItems[Index: Integer]: TcxGridBand;

Description

Use the BottomItems property to gain access to the collection of bottom bands contained within the current band collection.  Each bottom band is an instance of the TcxGridBand class.  This class contains settings for a specific band: caption, caption text alignment, sets of options & styles, the columns collection, etc.

ReadOnly Property


TcxGridBands.Count

TcxGridBands          See Also

Returns the number of bands in the current collection.

property Count: Integer;

Description

Use the Count property to get the total number of bands within the current collection.  To access a particular band, use the Items zero-based indexed collection.

Use the VisibleCount property to obtain the number of bands which are currently visible.

ReadOnly Property


TcxGridBands.GridView

TcxGridBands

Returns the view owning the current collection of bands.

property GridView: TcxGridBandedTableView;

Description

Use the GridView property to access the banded table view owning the current collection.  The View class provides access to the collections of bands, columns, styles, sets of option and other attributes managing the view.

ReadOnly Property


TcxGridBands.Items

TcxGridBands          See Also

Provides indexed access to all bands in the current collection.

property Items[Index: Integer]: TcxGridBand;

Description

Use the Items property to access bands within the current collection.  Each band is an instance of the TcxGridBand class.  This class contains settings for a specific band: caption, caption text alignment, sets of options & styles, the columns collection, etc.


TcxGridBands.Layout

TcxGridBands          See Also

Indicates whether any bands within the current view are fixed horizontally.

type

  TcxGridBandsLayout = (blNonFixed, blLeftFixed, blRightFixed, blLeftRightFixed);

property Layout: TcxGridBandsLayout;

Description

Use the Layout property to determine whether any of the current view’s bands are fixed.  The possible values are:

Value	Meaning
blLeftFixed	At least one band is fixed to the left side of the view,but none on the right.
blLeftRightFixed	There is at least one band fixed to each of the left and right sides of the view.
blNonFixed	There are no fixed bands within the view.
blRightFixed	At least one band is fixed to the right side of the view, but none on the left.

For more information about fixed bands see the Bands and the Band.FixedKind topics.

ReadOnly Property


TcxGridBands.RootItemCount

TcxGridBands          See Also

Returns the number of root bands contained within the current collection.

property RootItemCount: Integer;

Description

Use the RootItemCount property to obtain the number of root bands contained within the current band collection.

ReadOnly Property


TcxGridBands.RootItems

TcxGridBands          See Also

Provides indexed access to all the root bands in the current collection.

property RootItems[Index: Integer]: TcxGridBand;

Description

Use the RootItems property to gain access to the collection of root bands contained within the current band collection.  Each root band is an instance of the TcxGridBand class.  This class contains settings for a specific band: caption, caption text alignment, sets of options & styles, the columns collection, etc.

ReadOnly Property


TcxGridBands.VisibleCount

TcxGridBands          See Also

Returns the number of visible bands within a view which owns the current collection.

property VisibleCount: Integer;

Description

Use the VisibleCount property to obtain the number of visible bands within the view.  The band visibility is determined by the Band.Visible property.  If that property value is False, then a band is not visible within the view.

ReadOnly Property


TcxGridBands.VisibleBottomItemCount

TcxGridBands          See Also

Returns the number of bottom bands contained within the current collection which are visible in a view.

property VisibleBottomItemCount: Integer;

Description

Unlike the BottomItemCount property, the VisibleBottomItemCount property returns only a count of the bottom bands contained within the current band collection that are visible in the view.

ReadOnly Property


TcxGridBands.VisibleBottomItems

TcxGridBands          See Also

Provides indexed access to the bottom bands in the current collection which are visible in a view.

property VisibleBottomItems[Index: Integer]: TcxGridBand;

Description

Use the VisibleBottomItems property to gain access to the collection of bottom bands contained within the current band collection which are visible in a view.  Unlike the BottomItems property, this property addresses bottom bands that are visible within a view.  Each bottom band is an instance of the TcxGridBand class.  This class contains settings for a specific band: caption, caption text alignment, sets of options & styles, the columns collection, etc.

ReadOnly Property


TcxGridBands.VisibleItems

TcxGridBands          See Also

Provides indexed access to the collection of visible bands.

property VisibleItems[Index: Integer]: TcxGridBand;

Description

Use the VisibleItems property to access the collection of visible bands within the view which owns the collection.  The band visibility is determined by the Band.Visible property.  If that property value is False, then a band is not visible within the view.

ReadOnly Property


TcxGridBands.VisibleRootItemCount

TcxGridBands          See Also

Returns the number of root bands contained within the current collection which are visible in a view.

property VisibleRootItemCount: Integer;

Description

Unlike the RootItemCount property, the VisibleRootItemCount property returns only a count of the root bands contained within the current band collection that are visible in a view.

ReadOnly Property


TcxGridBands.VisibleRootItems

TcxGridBands          See Also

Provides indexed access to the root bands in the current collection which are visible in a view.

property VisibleRootItems[Index: Integer]: TcxGridBand;

Description

Use the VisibleRootItems property to gain access to the collection of root bands contained within the current band collection which are visible in the view.  Unlike the RootItems property, this property addresses the root bands that are visible within the view.  Each root band is an instance of the TcxGridBand class.  This class contains settings for a specific band: caption, caption text alignment, sets of options & styles, the columns collection, etc.

ReadOnly Property


TcxGridBands.VisibleRootLeftFixedCount

TcxGridBands          See Also

Returns the number of root bands in the current collection which are visible and fixed to the left side of a view.

property VisibleRootLeftFixedCount: Integer;

Description

Use the VisibleRootLeftFixedCount property to obtain the number of root bands which are visible and fixed to the left side of the view.  In order to fix a band to a specific side of the view, set its Band.FixedKind property.

For more information about fixed bands see the Bands and the Band.FixedKind topics.

ReadOnly Property


TcxGridBands.VisibleRootRightFixedCount

TcxGridBands          See Also

Returns the number of root bands in the current collection which are visible and fixed to the right side of a view.

property VisibleRootRightFixedCount: Integer;

Description

Use the VisibleRootRightFixedCount property to obtain the number of root bands which are visible and fixed to the right side of the view.  In order to fix a band to a specific side of a view, set its Band.FixedKind property.

For more information about fixed bands see the Bands and the Band.FixedKind topics.

ReadOnly Property


TcxGridBands.VisibleRowCount

TcxGridBands          See Also

Returns the number of grid band rows visible within the view.

property VisibleRowCount: Integer;

Description

Use the VisibleRowCount property to obtain the number of visible rows within the view which owns the collection.  The grid band row visibility is determined by the GridBandRow.Visible property.

ReadOnly Property


TcxGridBands.Add

TcxGridBands          See Also

Adds a new band into the current collection.

function Add: TcxGridBand;

Description

Use the Add method to add a new band to the current collection.  After a band is added, a user can specify its settings, such as caption, options and styles, etc.  Columns can be added to the created band by setting its BandedColumn.Position.BandIndex property to the index of the created band.

The following code adds a new band to a view and adds the Description column to it (this may move it from another band):

//Delphi

...

With btvItems.Bands.Add do

begin

  Caption := 'Additional Info';

  Index := 2;

  Width := 200;

  btvItemsDESCRIPTION.Position.BandIndex := Index;

  btvItemsDESCRIPTION.Visible := True;

end;

...

// C++ Builder

...

TcxGridBand *ABand

ABand = btvItems->Bands->Add()

ABand->Caption = "Additional Info";

ABand->Index = 2;

ABand->Width = 200;

btvItemsDESCRIPTION->Position->BandIndex = Index;

btvItemsDESCRIPTION->Visible = true;

...


TcxGridBands.AreNested

TcxGridBands          See Also

Determines whether the current collection contains nested (child) bands.

function AreNested: Boolean;

Description

The AreNested function returns False when the current collection contains only bands which have no nested (child) bands.  To determine whether a particular band has child bands, use its IsBottom property.


TcxGridBands.GetFirstVisibleRootIndex

TcxGridBands          See Also

Returns the position of the first visible band in the current collection by its fixed kind.

type

  TcxGridBandFixedKind = (fkNone, fkLeft, fkRight);

function GetFirstVisibleRootIndex(AFixedKind: TcxGridBandFixedKind): Integer;

Description

Use the GetFirstVisibleRootIndex method to obtain the position of the first visible band in the current band collection.  The AFixedKind parameter specifies the fixed kind of the band to search for.

For more information about fixed bands, see the Bands and the Band.FixedKind topics.


TcxGridBands.GetLastVisibleRootIndex

TcxGridBands          See Also

Returns the position of the last visible band in the current collection by its fixed kind.

type

  TcxGridBandFixedKind = (fkNone, fkLeft, fkRight);

function GetLastVisibleRootIndex(AFixedKind: TcxGridBandFixedKind): Integer;

Description

Use the GetLastVisibleRootIndex method to obtain the position of the last visible band in the current band collection.  The AFixedKind parameter specifies the fixed kind of the band to search for.

For more information about fixed bands, see the Bands and the Band.FixedKind topics.


TcxGridBands.HaveFixedItems

TcxGridBands          See Also

Returns True when the current collection contains at least one fixed band.

function HaveFixedItems: Boolean;

Description

For more information about fixed bands, see the Bands and the Band.FixedKind topics.


TcxGridBandStyles
TcxGridBandStyles Object

Hierarchy          Properties          Methods          Events          See Also

Represents a set of styles managing the appearance of band elements.

Unit

cxGridBandedTableView

TcxGridBandStyles = class(TcxCustomGridStyles);

Description

The TcxGridBandStyles property defines a set of properties and events allowing you to specify the appearance of a band’s content region, header and footer panels.  By handling styles events, it is possible to define different styles for individual records.  To set the styles for a band, see the TcxGridBand.Styles property.

You can define the default appearance of banded columns via the view’s Styles object and then redefine styles for individual columns as necessary.


TcxGridBandStyles Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomStyles

     |

TcxStyles

     |

TcxCustomGridStyles

     |


Properties for TcxGridBandStyles
TcxGridBandStyles Properties

TcxGridBandStyles          Legend

In TcxGridBandStyles

Background

Band

Content

GridView

Header

Derived from TcxCustomGridStyles

GridView

Derived from TcxCustomStyles

StyleSheet


Methods for TcxGridBandStyles
TcxGridBandStyles Methods

TcxGridBandStyles          Legend

Derived from TcxCustomStyles

Assign

Create

Destroy


Events for TcxGridBandStyles
TcxGridBandStyles Events

TcxGridBandStyles          Legend

In TcxGridBandStyles

OnGetHeaderStyle


TcxGridBandStyles.Background

TcxGridBandStyles          See Also

Specifies the style for the band background.

property Background: TcxStyle;

Description

The Background property allows you to define the style (font, background color) for the band background.

The following image shows a grid control with the second band background painted in yellow.


TcxGridBandStyles.Band

TcxGridBandStyles

Returns the band to which the current set of styles is applied.

property Band: TcxGridBand;

Description

Use the Band property to return the band which uses the current set of styles.

ReadOnly Property


TcxGridBandStyles.Content

TcxGridBandStyles          See Also

Specifies the style for the band’s content.

property Content: TcxStyle;

Description

The Content property allows you to define the style (font, background color) for cells within the current band.

The following image shows a grid control with the second band’s content painted in yellow:


TcxGridBandStyles.GridView

TcxGridBandStyles

Specifies the view containing the band for which the style is applied.

property GridView: TcxGridBandedTableView;

Description

Use the GridView property to get the band’s view to which the current style is assigned.

ReadOnly Property


TcxGridBandStyles.Header

TcxGridBandStyles          See Also

Specifies the style for the band’s header.

property Header: TcxStyle;

Description

The Header property allows you to define the style (font, background color) of the band’s header. It is possible to redefine the style for a band header at runtime by handling the OnGetHeaderStyle event.

The following image shows a grid control with the first band’s header painted in coral ($00507FFF).


TcxGridBandStyles.OnGetHeaderStyle

TcxGridBandStyles          See Also

Occurs whenever the band header is to be redrawn.

type

  TcxGridBandGetHeaderStyle = procedure(Sender: TcxGridBandedTableView; ABand: TcxGridBand; out AStyle: TcxStyle) of object;

property OnGetHeaderStyle: TcxGridBandGetHeaderStyle;

Description

You can handle the OnGetHeaderStyle event to redefine the style of a specific band’s header.  This event occurs every time it is necessary to redraw the header of the band defined by the ABand parameter.  By returning a style via the AStyle parameter, you can override the style for the band’s header as defined by the view’s Styles.BandHeader.

The Sender parameter determines the view containing the band.


TcxGridBandCustomOptions
TcxGridBandCustomOptions Object

Hierarchy          Properties          See Also

Represents the base class for all classes which manage the behavior of a band.

Unit

cxGridBandedTableView

TcxGridBandCustomOptions = class(TPersistent);

Description

The TcxGridBandCustomOptions class provides general information for band related classes.  Descendants of the TcxGridBandCustomOptions class (TcxGridBandOptions and TcxGridBandPosition) declare additional band specific properties.

The TcxGridBandOptions class represents a set of options that affect the band’s behavior, these can be accessed via the band's Options property.

The TcxGridBandPosition class provides properties to specify the position of a band (TcxGridBand) within a banded table view.  The TcxGridBand.Position object defines these properties.


TcxGridBandCustomOptions Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxGridBandCustomOptions

TcxGridBandCustomOptions          Legend

In TcxGridBandCustomOptions

Band


TcxGridBandCustomOptions.Band

TcxGridBandCustomOptions          See Also

Identifies the band which owns the set of options.

property Band: TcxGridBand;

Description

Use the Band property to access the band which owns the current options set.  This property provides access to the band columns, styles sets, etc.

ReadOnly Property


TcxGridBandPosition
TcxGridBandPosition Object

Hierarchy          Properties          Methods          See Also

Represents the position of a band within a banded table view.

Unit

cxGridBandedTableView

TcxGridBandPosition = class(TcxGridBandCustomOptions);

Description

The TcxGridBandPosition class defines attributes specifying the nesting level and horizontal position of the band within a banded table view or parent band.  To set the band's position, use the TcxGridBand.Position property.

You can allocate a band to the view (root nesting level) or a specific band (called a parent band) by setting the BandIndex property.  This designates the parent band or view (when no parent band is selected) that will display the current band.  The horizontal position of a band in a parent band or view can be set via the ColIndex property.


TcxGridBandPosition Hierarchy
Hierarchy

TPersistent

     |

TcxGridBandCustomOptions

     |


Properties for TcxGridBandedColumnPosition
TcxGridBandPosition Properties

TcxGridBandPosition          Legend

In TcxGridBandPosition

BandIndex

ColIndex

GridView

ParentBand

VisibleColIndex

Derived from TcxGridBandCustomOptions

Band


Methods for TcxGridBandPosition

TcxGridBandPosition          Legend

In TcxGridBandPosition

Create


TcxGridBandPosition.BandIndex

TcxGridBandPosition          See Also

Specifies the parent band of the current band.

property BandIndex: Integer;

Description

Use the BandIndex property to designate the parent band which will display the current band.  The BandIndex property addresses the parent band by its index in the view’s Bands collection.  To specify the horizontal position of a band within a view or parent band, you need to set the ColIndex property.

If you set the BandIndex property to –1, the band will be a root band.


TcxGridBandPosition.ColIndex

TcxGridBandPosition          See Also

Specifies the horizontal position of the current band in a band row.

property ColIndex: Integer;

Description

The ColIndex property allows you to define the band’s horizontal position in a view or parent band row specified by the BandIndex property's value.  The leftmost position in a row has a ColIndex value of 0.


TcxGridBandPosition.GridView

TcxGridBandPosition

Gets the banded table view which contains the current band.

property GridView: TcxGridBandedTableView;

Description

The GridView property provides access to the view containing the current band.  You can use this property to adjust general view settings such as the number of bands or columns, etc.

ReadOnly Property


TcxGridBandPosition.ParentBand

TcxGridBandPosition          See Also

Returns the parent band which displays the current band.

property ParentBand: TcxGridBand;

Description

The ParentBand property returns the parent band which displays the current band.  If the current band is a root band (it has no parent band specified, i.e. its BandIndex property is set to –1), NIL is returned.

ReadOnly Property


TcxGridBandPosition.VisibleColIndex

TcxGridBandPosition          See Also

Gets the horizontal position of the current band from amongst the visible bands.

property VisibleColIndex: Integer;

Description

Unlike the ColIndex property, the VisibleColIndex returns –1 if the band is not displayed in a view (the band’s Visible property is set to False).

ReadOnly Property


TcxGridBandPosition.Create

TcxGridBandPosition

Creates an instance of the TcxGridBandPosition class.

constructor Create(ABand: TcxGridBand); override;

Description

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


TcxGridBandedTableViewStyles
TcxGridBandedTableViewStyles Object

Hierarchy          Properties          Methods          Events          See Also

Represents a set of styles that manage the appearance of visual elements in Banded Table Views.

Unit

cxGridBandedTableView

TcxGridBandedTableViewStyles = class(TcxGridTableViewStyles);

Description

In addition to the settings inherited from the base TcxGridTableViewStyles class, the TcxGridBandedTableViewStyles class introduces members that allow you to specify and dynamically customize style attributes for:

•	band backgrounds (BandBackground);

•	band headers (the BandHeader property and the OnGetBandHeaderStyle event).

To apply style settings to a Banded Table View, use the View’s Styles property.

You can specify the default appearance of all bands via the View’s Styles and then redefine style settings for each individual band via its Styles property.


TcxGridBandedTableViewStyles Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomStyles

     |

TcxStyles

     |

TcxCustomGridStyles

     |

TcxCustomGridViewStyles

     |

TcxCustomGridTableViewStyles

     |

TcxGridTableViewStyles

     |


Properties for TcxGridBandedTableViewStyles
TcxGridBandedTableViewStyles Properties

TcxGridBandedTableViewStyles          Legend

In TcxGridBandedTableViewStyles

BandBackground

BandHeader

GridView

Derived from TcxGridTableViewStyles

Footer

GridView

Group

GroupByBox

GroupFooterSortedSummary

GroupSortedSummary

GroupSummary

Header

Indicator

NewItemRowInfoText

Preview

Derived from TcxCustomGridTableViewStyles

Content

ContentEven

ContentOdd

FilterBox

GridView

Inactive

Selection

Derived from TcxCustomGridViewStyles

Background

Derived from TcxCustomGridStyles

GridView

Derived from TcxCustomStyles

StyleSheet


Methods for TcxGridBandedTableViewStyles
TcxGridBandedTableViewStyles Methods

TcxGridBandedTableViewStyles          Legend

Derived from TcxGridTableViewStyles

GetContentParams

GetFooterParams

GetGroupParams

GetGroupSummaryParams

GetHeaderParams

GetPreviewParams

GetRecordContentParams

Derived from TcxCustomStyles

Assign

Create

Destroy


Events for TcxGridBandedTableViewStyles
TcxGridBandedTableViewStyles Events

TcxGridBandedTableViewStyles          Legend

In TcxGridBandedTableViewStyles

OnGetBandHeaderStyle

Derived from TcxGridTableViewStyles

OnGetFooterStyle

OnGetFooterStyleEx

OnGetFooterSummaryStyle

OnGetGroupStyle

OnGetGroupSummaryStyle

OnGetHeaderStyle

OnGetPreviewStyle

Derived from TcxCustomGridTableViewStyles

OnGetContentStyle


TcxGridBandedTableViewStyles.BandBackground

TcxGridBandedTableViewStyles          See Also

The view level style for band backgrounds.

property BandBackground: TcxStyle;

Description

The BandBackground property allows you to specify the style (font settings and the background color or bitmap) for all band backgrounds in a Banded Table View.

You can override this style for an individual band by setting it’s Styles.Background property.


TcxGridBandedTableViewStyles.BandHeader

TcxGridBandedTableViewStyles          See Also

Specifies the style for band headers.

property BandHeader: TcxStyle;

Description

The BandHeader property allows you to define the style (font settings and the background color) of all band headers for the banded table view.  It is possible to redefine the style for a specific band header by handling the OnGetBandHeaderStyle event or by changing the band’s Styles.Header property.


TcxGridBandedTableViewStyles.GridView

TcxGridBandedTableViewStyles

Specifies the view for which the style is applied.

property GridView: TcxGridBandedTableView;

Description

Use the GridView property to get the banded view for which the current style is applied.  You can use this property to access various view parameters, such as columns and bands lists, options and style sets, data binding settings, etc.

ReadOnly Property


TcxGridBandedTableViewStyles.OnGetBandHeaderStyle

TcxGridBandedTableViewStyles          See Also

Occurs whenever the band header should be redrawn.

type

  TcxGridBandGetHeaderStyle = procedure(Sender: TcxGridBandedTableView; ABand: TcxGridBand; out AStyle: TcxStyle) of object;

property OnGetBandHeaderStyle: TcxGridBandGetHeaderStyle;

Description

You can handle the OnGetBandHeaderStyle event to redefine the style for a specific band header.  This event occurs every time it is necessary to redraw a band header.

The ABand parameter is the band object that requires the style.  By returning the style via the AStyle parameter you can override the style for the band header defined by the Styles.BandHeader property.

The Sender parameter is the banded table view containing the band.

Note: You can also customize the header style of a band directly by using the Styles.Header property, or the Styles.OnGetHeaderStyle of the Band object.


TcxGridBandedTableViewStyleSheet
TcxGridBandedTableViewStyleSheet Object

Hierarchy          Properties          Methods          See Also

Represents the stylesheet for the banded table view.

Unit

cxGridBandedTableView

TcxGridBandedTableViewStyleSheet = class(TcxCustomStyleSheet);

Description

A StyleSheet contains a collection of styles that can be applied to a view, setting multiple styles in one step.  The TcxGridBandedTableViewStyleSheet provides a stylesheet collection for the banded table view. The banded table view has specific elements such as bands also have styles. These styles along with table specific styles are included into the banded table view styles collection.


TcxGridBandedTableViewStyleSheet Hierarchy
Hierarchy

TComponent

     |

TcxCustomStyleSheet

     |


Properties for TcxGridBandedTableViewStyleSheet
TcxGridBandedTableViewStyleSheet Properties

TcxGridBandedTableViewStyleSheet          Legend

In TcxGridBandedTableViewStyleSheet

Styles

Derived from TcxCustomStyleSheet

Caption

StyleRepository


Methods for TcxGridBandedTableViewStyleSheet
TcxGridBandedTableViewStyleSheet Methods

TcxGridBandedTableViewStyleSheet          Legend

Derived from TcxCustomStyleSheet

 Create

 Destroy


TcxGridBandedTableViewStyleSheet.Styles

TcxGridBandedTableViewStyleSheet          See Also

Represents a set of styles managing the appearance of banded table view.

property Styles: TcxGridBandedTableViewStyles;

Description

The Styles property defines a number of properties and events that allow you to specify the appearance of all banded table view elements.  These include background, bands backgrounds, bands headers, content, filter box, footer, group, group-by box, header, inactive, indicator, preview and selection styles.

By handling the styles events it is possible to override the property styles and define different styles for records on the fly.


TcxGridBandedTableOptionsCustomize
TcxGridBandedTableOptionsCustomize Object

Hierarchy          Properties          Methods          See Also

Settings that control the runtime manipulations possible for columns and bands of a banded table view.  These view level settings may be overridden in the Options property of individual Bands or Columns.

Unit

cxGridBandedTableView

TcxGridBandedTableOptionsCustomize = class(TcxGridTableOptionsCustomize);

Description

The properties of a TcxGridBandedTableViewCustomize object define the features that can be implemented at runtime for manipulating columns and bands.  Band manipulations include moving and resizing, and are accessed by clicking and dragging the band header or a band side.

Most column features are inherited from the TcxGridTableOptionsCustomize class.

The banded table view columns have an additional feature, which allows the height of a column within a band to be changed by clicking and dragging its bottom border.  See the OptionsCustomize property for more information.

The ExpressQuantumGrid supports nested bands within a banded table view – a band can be displayed and arranged within a parent band.  This feature is enabled by the view’s OptionsCustomize.NestedBands property.

Each band and column also has an Options property (Band Options and Column Options correspondingly) allowing you to override the global behavior and settings locally.


TcxGridBandedTableOptionsCustomize Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |

TcxCustomGridTableOptionsCustomize

     |

TcxGridTableOptionsCustomize

     |


Properties for TcxGridBandedTableOptionsCustomize
TcxGridBandedTableOptionsCustomize Properties

TcxGridBandedTableOptionsCustomize          Legend

In TcxGridBandedTableOptionsCustomize

BandHiding

BandMoving

BandSizing

BandsQuickCustomization

BandsQuickCustomizationMaxDropDownCount

BandsQuickCustomizationReordering

ColumnVertSizing

NestedBands

Derived from TcxGridTableOptionsCustomize

ColumnFiltering

ColumnGrouping

ColumnHiding

ColumnHidingOnGrouping

ColumnHorzSizing

ColumnMoving

ColumnSorting

DataRowSizing

GroupBySorting

GroupRowSizing

Derived from TcxCustomGridTableOptionsCustomize

ItemFiltering

ItemGrouping

ItemHiding

ItemMoving

ItemSorting

Derived from TcxCustomGridOptions

GridView


Methods for TcxGridBandedTableOptionsCustomize
TcxGridBandedTableOptionsCustomize Methods

TcxGridBandedTableOptionsCustomize          Legend

In TcxGridBandedTableOptionsCustomize

SupportsBandsQuickCustomizationReordering

Derived from TcxCustomGridTableOptionsCustomize

SupportsItemsQuickCustomizationReordering


TcxGridBandedTableOptionsCustomize.BandHiding

TcxGridBandedTableOptionsCustomize

Determines the manner in which view bands can be hidden from a view.

property BandHiding: Boolean;

Description

Use the BandHiding property to determine the manner in which the view bands can be hidden from a view.  When set to False, bands can only be hidden by dragging them to the active customization form.  When BandHiding is True, bands can also be hidden by dragging their headers, even if the customization form is not displayed.  If a band is displayed within the customization form, it is not visible within a view (i.e. the Visible property value of that band is False).  A band can also be made invisible within the customization form.  Set the Band.VisibleForCustomization property value to True and then a band can only be returned to a view programmatically.  The default value of the BandHiding property is False.


TcxGridBandedTableOptionsCustomize.BandMoving

TcxGridBandedTableOptionsCustomize          See Also

Determines whether a user can move a Band in the banded table view.

property BandMoving: Boolean;

Description

Use the BandMoving property to determine whether the views bands can be moved.  If this option is turned off, then band moving can be accomplished programmatically by changing the Band.Index property value, which represents the band position within a view.

At runtime band moving is implemented by clicking and dragging band header.

This view level setting can be overridden for an individual band via the bands Band.Options.Moving property.

Note:	Setting the BandMoving property to False disables the view’s band reordering via the Quick Band Customization dropdown provided that the ColumnsQuickCustomizationReordering property is set to qcrDefault.

The default value of the BandMoving property is True.


TcxGridBandedTableOptionsCustomize.BandSizing

TcxGridBandedTableOptionsCustomize          See Also

Determines whether a user can resize a Band in the banded table view.

property BandSizing: Boolean;

Description

Use the BandSizing property to determine whether the views bands can be sized.  If this option is turned off, then bands sizing can be accomplished programmatically by changing the Band.Width property value.

At runtime band sizing is implemented via clicking and dragging the required band side.

This view level setting can be overridden for an individual band via the bands Band.Options.Sizing property.

The default value of the BandSizing property is True.


TcxGridBandedTableOptionsCustomize.BandsQuickCustomization

TcxGridBandedTableOptionsCustomize          See Also

Specifies whether the Quick Band Customization button is displayed.

property BandsQuickCustomization: Boolean;

Description

Set the BandsQuickCustomization property to True, which displays the Quick Band Customization button in the indicator.  This automatically makes the indicator visible if it is not currently displayed.  Otherwise, the button is not displayed.

The default value of the BandsQuickCustomization property is False.


TcxGridBandedTableOptionsCustomize.BandsQuickCustomizationMaxDropDownCount

TcxGridBandedTableOptionsCustomize          See Also

Specifies the maximum number of band names displayed in the Quick Band Customization dropdown list at any one time.

property BandsQuickCustomizationMaxDropDownCount: Integer;

Description

When an end user clicks the Quick Band Customization button, a dropdown list is displayed.  The band names defined within the view populate this list.  Set the BandsQuickCustomizationMaxDropDownCount property to specify the number of band names displayed in the list at any one time.  If this property's value is 0, the visible portion of the dropdown list displays all the bands defined within the view.

The default value of the BandsQuickCustomizationMaxDropDownCount property is 0.


TcxGridBandedTableOptionsCustomize.BandsQuickCustomizationReordering

TcxGridBandedTableOptionsCustomize          See Also

Specifies whether bands in a Banded Table View can be reordered by dragging band names in the Quick Band Customization dropdown.

type

  TcxGridQuickCustomizationReordering = (qcrDefault, qcrEnabled, qcrDisabled);

property BandsQuickCustomizationReordering: TcxGridQuickCustomizationReordering;

Description

Users can reorder bands in a Banded Table View by selecting and dragging the corresponding band names in the Quick Band Customization dropdown provided that the SupportsBandsQuickCustomizationReordering function returns True.  Multiple band names can be selected by clicking them while holding down the Shift and Ctrl keys.

Use the BandsQuickCustomizationReordering property to control the availability of this feature for end-users.  All possible values for this property are listed in the TcxGridQuickCustomizationReordering topic.

The default value of the BandsQuickCustomizationReordering property is qcrDefault.


TcxGridBandedTableOptionsCustomize.ColumnVertSizing

TcxGridBandedTableOptionsCustomize          See Also

Determines whether a user can resize Column heights in the current banded table view.

property ColumnVertSizing: Boolean;

Description

Use the ColumnVertSizing property to determine whether column heights can be changed within a banded table view.

These view settings can be overridden for an individual column via the Column.Options.VertSizing property.

A user can change the columns height in order to make a view more representative.  For instance, the height of a column containing an image can be increased to display the entire image.

The default value of the ColumnVertSizing property is True.


TcxGridBandedTableOptionsCustomize.NestedBands

TcxGridBandedTableOptionsCustomize          See Also

Determines whether an end user can arrange the bands in the current banded table view as nested bands.

property NestedBands: Boolean;

Description

Use the NestedBands property to determine whether an end user can nest bands into a tree like structure in the banded table view at runtime.  Even when this property is set to False bands in the current view can be nested programmatically via the band’s Position.BandIndex property.

The default value of the NestedBands property is True.


TcxGridBandedTableOptionsCustomize.SupportsBandsQuickCustomizationReordering

TcxGridBandedTableOptionsCustomize          See Also

Determines whether bands can be reordered by dragging their names in the Quick Band Customization dropdown.

function SupportsItemsQuickCustomizationReordering: Boolean; virtual;

Description

This function returns True when reordering is enabled in the Quick Band Customization dropdown.

By default, True is returned when the following conditions are met:

•	there are no nested and fixed bands in a View;

•	an appropriate option is set via the View’s OptionsCustomize.BandsQuickCustomizationReordering property.

Note:	At design time, the second condition is ignored.


TcxGridBandedTableOptionsView
TcxGridBandedTableOptionsView Object

Hierarchy          Properties          Methods          See Also

Settings that determine the banded table view appearance.

Unit

cxGridBandedTableView

TcxGridBandedTableOptionsView = class(TcxGridTableOptionsView);

Description

The properties of the TcxGridBandedTableOptionsView object specify how the banded table view will look.  These options include the table view appearance options (TcxGridTableOptionsView) but they also include settings specific to a banded view such as band header visibility and fixed band separator width and color (see the Bands topic in this help system for more information about fixed bands).

Use the OptionsView property to access these options.


TcxGridBandedTableOptionsView Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |

TcxCustomGridOptionsView

     |

TcxCustomGridTableOptionsView

     |

TcxGridTableOptionsView

     |


Properties for TcxGridBandedTableOptionsView
TcxGridBandedTableOptionsView Properties

TcxGridBandedTableOptionsView          Legend

In TcxGridBandedTableOptionsView

BandCaptionsInColumnAlternateCaption

BandHeaderEndEllipsis

BandHeaderHeight

BandHeaderLineCount

BandHeaders

FixedBandSeparatorColor

FixedBandSeparatorWidth

Derived from TcxGridTableOptionsView

ColumnAutoWidth

DataRowHeight

ExpandButtonsForEmptyDetails

Footer

FooterAutoHeight

FooterMultiSummaries

GridLineColor

GridLines

GridView

GroupByBox

GroupFooterMultiSummaries

GroupFooters

GroupRowHeight

Header

HeaderAutoHeight

HeaderEndEllipsis

HeaderHeight

Indicator

IndicatorWidth

NewItemRow

NewItemRowInfoText

NewItemRowSeparatorColor

NewItemRowSeparatorWidth

RowSeparatorColor

RowSeparatorWidth

Derived from TcxCustomGridTableOptionsView

CellAutoHeight

CellEndEllipsis

CellTextMaxLineCount

GridView

Navigator

NavigatorOffset

ShowEditButtons

Derived from TcxCustomGridOptionsView

ScrollBars

Derived from TcxCustomGridOptions

GridView


Methods for TcxGridBandedTableOptionsView
TcxGridBandedTableOptionsView Methods

TcxGridBandedTableOptionsView          Legend

Derived from TcxGridTableOptionsView

CanShowFooterMultiSummaries

CanShowGroupFooterMultiSummaries

GetGridLineColor

GetGroupSummaryLayout

Derived from TcxCustomGridTableOptionsView

GetNoDataToDisplayInfoText


TcxGridBandedTableOptionsView.BandCaptionsInColumnAlternateCaption

TcxGridBandedTableOptionsView

Specifies whether a band caption is included as the leading portion of the column header’s caption.

property BandCaptionsInColumnAlternateCaption: Boolean;

Description

Set the BandCaptionsInColumnAlternateCaption property to True to display a compound caption in the column header (or in the Filter Builder dialog’s drop-down list) so that it contains the band’s caption (see the TcxGridBand.Caption property) and is followed by the column’s caption (see the TcxGridBandedColumn.Caption property).  To delimit captions, a string character specified by the cxGridBandedTableViewAlternateCaptionSeparator constant is used.

The default value of the BandCaptionsInColumnAlternateCaption property is False.


TcxGridBandedTableOptionsView.BandHeaderEndEllipsis

TcxGridBandedTableOptionsView          See Also

Specifies whether to display an ellipsis when the band caption is clipped.

property BandHeaderEndEllipsis: Boolean;

Description

Use the BandHeaderEndEllipsis property to display an ellipsis in the band header panel when the band caption specified by the TcxGridBand.Caption property is clipped.

The default value of the BandHeaderEndEllipsis property is False.


TcxGridBandedTableOptionsView.BandHeaderHeight

TcxGridBandedTableOptionsView          See Also

Specifies the height of band headers (in pixels).

property BandHeaderHeight: Integer;

Description

Use the BandHeaderHeight property to specify the height (in pixels) of the view’s band headers.  Using its default property value results in the band headers’ height being set according to the OptionsView.BandHeaderLineCount property.  Set the BandHeaderHeight property to a value other than the default to specify this height in pixels.

The default value of the BandHeaderHeight property is 0.


TcxGridBandedTableOptionsView.BandHeaderLineCount

TcxGridBandedTableOptionsView          See Also

Specifies the height of band headers (in text lines).

property BandHeaderLineCount: Integer;

Description

Use the BandHeaderLineCount property to specify the height (in text lines) of  the view’s band headers.  This value will be overridden if the BandHeaderHeight property is set to any value other than the default.  The BandHeaderHeight property specifies the height of band headers in pixels.

The default value of the BandHeaderLineCount property is 1.


TcxGridBandedTableOptionsView.BandHeaders

TcxGridBandedTableOptionsView          See Also

Determines whether band headers are visible within the banded table view.

property BandHeaders: Boolean;

Description

Use the BandHeaders property to determine whether band headers are visible within the current view.  If the band headers are not visible, then band moving can only be implemented programatically changing the Band.Index property value, which represents the band position within a view..

The default value of the BandHeaders property is True.


TcxGridBandedTableOptionsView.FixedBandSeparatorColor

TcxGridBandedTableOptionsView          See Also

Specifies the color of the fixed band separator.

property FixedBandSeparatorColor: TColor;

Description

Bands within a banded table view can be fixed to either the left or right side of the view, fixed band columns are not included in the horizontal view scrolling.  Use the FixedBandSeparatorColor property to specify the separator color for these fixed bands.

See the Bands topic in this help system for more information about the Express Quantum Grid bands.

The default value of the FixedBandSeparatorColor property is clDefault.


TcxGridBandedTableOptionsView.FixedBandSeparatorWidth

TcxGridBandedTableOptionsView          See Also

Specifies the width of the fixed band separator.

property FixedBandSeparatorWidth: Integer;

Description

Bands within a banded table view can be fixed to either the left or right side of the view, fixed band columns are not included in the horizontal view scrolling.  Use the FixedBandSeparatorWidth property to specify the separator width between these bands.

See the Bands topic in this help system for more information about the Express Quantum Grid bands.

The default value of the FixedBandSeparatorWidth property is cxGridDefaultFixedBandSeparatorWidth.


TcxGridBandedTableOptionsBehavior
TcxGridBandedTableOptionsBehavior Object

Hierarchy           Properties          See Also

Represents settings that determine how the banded grid table view responds to end user actions.

Unit

cxGridBandedTableView

TcxGridBandedTableOptionsBehavior = class(TcxGridTableOptionsBehavior);

Description

The TcxGridBandedTableOptionsBehavior object contains settings determining the grid view’s response to user actions via the mouse or keyboard.  These options determine whether the cell editors are always active and whether focus can be moved using the Tab and Enter keys, if hints are displayed for columns and bands, etc.

Use the OptionsBehavior property to access these options.


TcxGridBandedTableOptionsBehavior Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |

TcxCustomGridTableOptionsBehavior

     |

TcxGridTableOptionsBehavior

     |


Properties for TcxGridBandedTableOptionsBehavior
TcxGridBandedTableOptionsBehavior Properties

TcxGridBandedTableOptionsBehavior          Legend

In TcxGridBandedTableOptionsBehavior

BandHeaderHints

Derived from TcxGridTableOptionsBehavior

ColumnHeaderHints

CopyPreviewToClipboard

ExpandMasterRowOnDblClick

Derived from TcxCustomGridTableOptionsBehavior

AlwaysShowEditor

BestFitMaxRecordCount

CellHints

DragFocusing

DragHighlighting

DragOpening

DragScrolling

ExpandMasterRowOnDblClick

FocusCellOnCycle

FocusCellOnTab

FocusFirstCellOnNewRecord

GoToNextCellOnEnter

ImmediateEditor

IncSearch

IncSearchItem

NavigatorHints

PullFocusing

Derived from TcxCustomGridOptions

GridView


TcxGridBandedTableOptionsBehavior.BandHeaderHints

TcxGridBandedTableOptionsBehavior          See Also

Indicates whether a hint box is displayed when hovering over a band containing a clipped caption.

property BandHeaderHints: Boolean;

Description

Set the BandHeaderHints property to True to display a hint box when moving the mouse pointer over partially visible bands or bands which have their captions clipped by their bounds.  The hint box will contain the underlying band's caption.

The following image shows a banded table view with two bands.  The band hint is displayed for the second one:

The default value of the BandHeaderHints property is True.


cxGridBandedTableViewAlternateCaptionSeparator constant
cxGridBandedTableViewAlternateCaptionSeparator global constant

See Also

Specifies a string to be used as a splitter between band and column captions in column headers and in the Filter Builder dialog’s drop-down list.

Unit

cxGridBandedTableView

cxGridBandedTableViewAlternateCaptionSeparator : string = '-';

Description

If the OptionsView.BandCaptionsInColumnAlternateCaption property is set to True, the column header contains a compound caption with two concatenated captions– the caption of the band that the current column belongs to and the column’s caption. A string specified by the cxGridBandedTableViewAlternateCaptionSeparator constant separates these captions in the column header.

The same separator is also used as a band-column caption separator in the drop-down list of the Filter Builder dialog.

Use the cxGridBandedTableViewAlternateCaptionSeparator constant to specify a different string to use for the caption separator within column headers and in the Filter Builder dialog’s drop-down list (when the grid uses a banded table view).


cxGridCardView Unit Overview
cxGridCardView Unit

Classes

TcxCustomGridCardRowLayoutObject

TcxGridCard

TcxGridCardRowCaptionHitTest

TcxGridCardRowCellHitTest

TcxGridCardRowExpandButtonHitTest

TcxGridCardRowFilterButtonHitTest

TcxGridCardRowIndentHitTest

TcxGridCardRowLayoutObject

TcxGridCardScrollButtonDownHitTest

TcxGridCardScrollButtonUpHitTest

TcxGridCardView

TcxGridCardViewBackgroundBitmaps

TcxGridCardViewController

TcxGridCardViewDateTimeHandling

TcxGridCardViewFiltering

TcxGridCardViewOptionsBehavior

TcxGridCardViewOptionsData

TcxGridCardViewOptionsSelection

TcxGridCardViewOptionsView

TcxGridCardViewRow

TcxGridCardViewRowOptions

TcxGridCardViewRowPosition

TcxGridCardViewRowLayoutController

TcxGridCardViewRowLayoutObject

TcxGridCardViewRowStyles

TcxGridCardViewSeparatorHitTest

TcxGridCardViewSeparatorsViewInfo

TcxGridCardViewStyles

TcxGridCardViewStyleSheet

TcxGridCardViewViewData

TcxGridCardViewVisibleRowLayoutObject

TcxGridCardVisibleRowLayoutObject

Other Types

TcxGridCardRowCoordinates

TcxGridCardRowInsertionPos

TcxGridCardRowPosition

TcxGridCardViewRowLayout

Global Constants

cxGridCardBorderMinWidth

cxGridCardDefaultCategoryIndent

cxGridCardDefaultCategorySeparatorWidth

cxGridCardDefaultIndent

cxGridCardDefaultLayerSeparatorWidth

cxGridCardDefaultWidth

cxGridCardMinWidth

cxGridCardViewAlternateCaptionSeparator

cxGridDefaultCardBorderWidth


TcxGridCardView
TcxGridCardView Object

Hierarchy          Properties          Methods          Events          See Also

Represents a card view.

Unit

cxGridCardView

TcxGridCardView = class(TcxCustomGridTableView);

Description

The TcxGridCardView object represents a card view.  Card view is a suitable way of displaying root and child levels of the hierarchy but it can never be a master view.  It lacks the grid table view functionality (grouping and filtering), but sometimes it is more informative, for instance, for displaying personal information.

The key element of a card view is the card view row.  All rows can be accessed via the Rows property.  Each card view row is an instance of the TcxGridCardViewRow class.  Members of this class allow you to specify the row caption, caption alignment, row representation (caption row, category or data row), row width, editor for the row value, sort order for the cards within the current view, the type of row layering in a card, etc.  Rows corresponding to fields in a single record are combined into cards.  The number of cards to display within a card view is determined via the card width settings (accessible via the OptionsView.CardWidth property).  A card’s placement orientation within a view is specified via the LayoutDirection property.

The grid card view has several option sets controlling different aspects of the view behavior and appearance.  These sets include:

•	OptionsBehavior which contains settings that determine a Card view’s response to user actions;

•	OptionsCustomize which contains settings that allow an end-user to manipulate view items at runtime;

•	OptionsData which determine the functionality of a data-aware Card view;

•	OptionsSelection which contains settings that are to do with selections within a Card view;

•	OptionsView which contains appearance options for a Card view;

•	FilterBox which contains appearance options of the filter box within a Card view;

•	DateTimeHandling which contains settings that control the manner in which date/time values are handled within a Card view.

The card view also owns a set of styles defining the appearance of the card view elements.


TcxGridCardView Hierarchy
Hierarchy

TComponent

     |

TcxControlChildComponent

     |

TcxCustomGridView

     |

TcxCustomGridTableView

     |


Properties for TcxGridCardView
TcxGridCardView Properties

TcxGridCardView          Legend

In TcxGridCardView

BackgroundBitmaps

Controller

DateTimeHandling

LayoutDirection

OptionsBehavior

OptionsCustomize

OptionsData

OptionsSelection

OptionsView

RowCount

Rows

RowLayout

RowLayoutController

Styles

ViewData

ViewInfo

VisibleRowCount

VisibleRows

Derived from TcxCustomGridTableView

Control

Controller

DataController

DateTimeHandling

FilterBox

GroupedItemCount

GroupedItems

ItemCount

Items

MasterGridRecord

NavigatorButtons

OptionsBehavior

OptionsCustomize

OptionsData

OptionsSelection

OptionsView

SortedItemCount

SortedItems

Styles

ViewData

VisibleItemCount

VisibleItems

Derived from TcxCustomGridView

CloneCount

Clones

Controller

DataController

DragMode

Focused

IsControlFocused

IsDetail

IsMaster

IsPattern

Level

MasterGridRecordIndex

MasterGridView

MasterRecordIndex

OptionsSelection

OptionsView

PatternGridView

Site

Styles

ViewData

ViewInfo

Visible

Derived from TcxControlChildComponent

Control

IsDestroying

IsLoading


Methods for TcxGridCardView
TcxGridCardView Methods

TcxGridCardView          Legend

In TcxGridCardView

 CreateRow

Derived from TcxCustomGridTableView

 ApplyBestFit

 ClearItems

 CopyToClipboard

 CreateItem

 FindItemByID

 FindItemByName

 IndexOfItem

 MakeMasterGridRecordVisible

 RestoreDefaults

Derived from TcxCustomGridView

 BeginUpdate

 CancelUpdate

 EndUpdate

      GetHitTest

 LayoutChanged

 RestoreDefaults

 RestoreFromIniFile

 RestoreFromRegistry

 RestoreFromStream

 SizeChanged

 StoreToIniFile

 StoreToRegistry

 StoreToStream

 ViewChanged

Derived from TcxControlChildComponent

 CreateEx

 Destroy


Events for TcxGridCardView
TcxGridCardView Events

TcxGridCardView          Legend

In TcxGridCardView

 OnRowCollapsed

 OnRowCollapsing

 OnRowExpanded

 OnRowExpanding

 OnRowPosChanged

Derived from TcxCustomGridTableView

 OnCanSelectRecord

 OnCellClick

 OnCustomDrawCell

 OnCustomDrawPartBackground

 OnCustomization

 OnEditChanged

 OnEditing

 OnEditValueChanged

 OnFilterControlDialogShow

 OnFilterCustomization

 OnFilterDialogShow

 OnFocusedItemChanged

 OnFocusedRecordChanged

 OnGetCellHeight

 OnInitEdit

 OnInitEditValue

 OnSelectionChanged

 OnTopRecordIndexChanged

Derived from TcxCustomGridView

 OnDblClick

 OnDragDrop

 OnDragOver

 OnEndDrag

 OnGetStoredProperties

 OnGetStoredPropertyValue

 OnInitStoredObject

 OnMouseEnter

 OnMouseLeave

 OnSetStoredPropertyValue

 OnStartDrag


TcxGridCardView.BackgroundBitmaps

TcxGridCardView

Specifies background bitmaps for the visual elements of a card view.

property BackgroundBitmaps: TcxGridCardViewBackgroundBitmaps;

Description

Use the BackgroundBitmaps property to specify background images for elements of a card view.  This property returns the TcxGridCardViewBackgroundBitmaps object whose properties specify images for specific element types.  Please refer to the TcxGridCardViewBackgroundBitmaps class description for details.

Note that images can also be assigned to elements of views using styles.  For this purpose, you need to specify the Bitmap property value of a style applied to an element.  Styles can be applied to view elements via the Styles property of the view.


TcxGridCardView.Controller

TcxGridCardView

Returns a controller object encapsulating card view specific operations.

property Controller: TcxGridCardViewController;

Description

Use the Controller property to access the functionality of the view controller.  A view controller provides properties and methods to:

-	control editing of a record cell

-	set focus to a specific card row and record

-	start/cancel an incremental search

-	access the collection of selected records

-	perform scrolling

-	navigate records and card rows

ReadOnly Property


TcxGridCardView.DateTimeHandling

TcxGridCardView

Provides a set of options that control the manner in which date/time values are handled in the current Card view.

property DateTimeHandling: TcxGridCardViewDateTimeHandling;

Description

Use this property to access settings that determine the manner in which date/time card row values are filtered, and how their values are displayed when filtering is applied.  Refer to the description of the TcxGridCardViewDateTimeHandling class for details on available options.

Note:	To override the view’s DateTimeHandling.IgnoreTimeForFiltering option for a particular card row, use the card row’s Options.IgnoreTimeForFiltering property.


TcxGridCardView.Filtering

TcxGridCardView

Provides filtering options for the view.

property Filtering: TcxGridCardViewFiltering;

Description

Use the Filtering property to access settings specifying the filtering functionality available to end-users.  The object available via the Filtering property also declares the RunCustomizeDialog method allowing you to invoke filter customization dialogs.  Please refer to the TcxGridCardViewFiltering class description for details on the filtering options and methods available.

Note: the Filtering property provides settings that control filtering at the view level.  You can override some of these settings for individual card rows.  Use the desired card row’s Options property for this purpose.


TcxGridCardView.LayoutDirection

TcxGridCardView          See Also

Specifies the orientation of the cards within the current view.

type

  TcxGridCardViewLayoutDirection = (ldHorizontal, ldVertical);

property LayoutDirection: TcxGridCardViewLayoutDirection;

Description

Use the layout direction to specify the placement order of cards within the current view.  The possible values are listed below:

Value	Meaning
ldHorizontal	Cards placement order is down, then across.
ldVertical	Cards placement order is across, then down.

The default value of the LayoutDirection property is ldHorizontal.


TcxGridCardView.OptionsBehavior

TcxGridCardView

Contains settings which determine the card view’s response to user actions.

property OptionsBehavior: TcxGridCardViewOptionsBehavior;

Description

Use the OptionsBehavior property to specify settings which determine the card view response to the user actions.  These settings determine whether the cell editors are always active, whether the focus can be moved using the Tab and Enter keys, etc.


TcxGridCardView.OptionsCustomize

TcxGridCardView

Provides access to the view’s customization options.

property OptionsCustomize: TcxGridCardViewOptionsCustomize;

Description

The OptionsCustomize property provides access to the TcxGridCardViewOptionsCustomize object whose properties define how end-users can interact with the view.  For instance, it contains properties defining whether end-users can resize cards; rearrange card rows using drag and drop, etc.  Please refer to the description of the TcxGridCardViewOptionsCustomize class to for details on available options.


TcxGridCardView.OptionsData

TcxGridCardView

Contains settings which determine the data-aware functionality of the view.

property OptionsData: TcxGridCardViewOptionsData;

Description

Use the OptionsData property to determine which actions can be performed on the data set which provides records for the current view.  These actions include inserting, appending, editing and deleting records.  The data options also indicate whether confirmation is required before record deletion and whether empty records can be posted into a data set.


TcxGridCardView.OptionsSelection

TcxGridCardView

Contains selection settings for the current view.

property OptionsSelection: TcxGridCardViewOptionsSelection;

Description

Use the OptionsSelection property to specify the options that are to do with selections within the current view.  These options indicate whether to select individual cells or whole rows, whether the focus rectangle is displayed around the focused row and whether multiple rows can be selected, etc.


TcxGridCardView.OptionsView

TcxGridCardView

Contains appearance options for the current view.

property OptionsView: TcxGridCardViewOptionsView;

Description

Use the OptionsView property to access settings which define the appearance aspects of the current view.  These settings determine:

•	the width of cards, card captions, card borders and card separators;

•	the visibility of editor buttons within the current view;

•	whether the card row caption and cell are automatically resized in order to display their full content.

Note:	Changing the OptionsView.CardWidth property affects the total number of cards displayed within the current view.


TcxGridCardView.RowCount

TcxGridCardView          See Also

Returns the number of rows within the current card.

property RowCount: Integer;

Description

Use the RowCount property to obtain the number of rows within the current card.  Use the Rows property to access all card view rows.

ReadOnly Property


TcxGridCardView.Rows

TcxGridCardView          See Also

Provides indexed access to all card view rows.

property Rows[Index: Integer]: TcxGridCardViewRow;

Description

Use the Rows property to gain access to all card view rows.  Each card view row is an instance of the TcxGridCardViewRow class.  Members of this class allow you to specify the row caption, caption alignment, row representation (caption row, category row or data row), row width, editor for the row value, sort order for the cards within the current view, etc.  Rows corresponding to fields in a single record are combined into cards.


TcxGridCardView.RowLayout

TcxGridCardView          See Also

property RowLayout: TcxGridCardViewRowLayout;

Description

A Card View allows you to specify one of two types of card row layout:

•	RowLayout property set to rlHorizontal – card rows are collected in a row, from left to right:

•	RowsLayout property set to rlVertical – card rows are collected in a column, one under another:

Additionally, a card can be split into an arbitrary number of rows or columns.  When using a split layout, rows and columns are named "layers".  To create multiple layers in a card, set the Position.BeginsLayer property of card rows that start new layers to True.

The default value of the RowLayout property is rlHorizontal.


TcxGridCardView.RowLayoutController

TcxGridCardView          See Also

Represents a card layout dispatcher.

property RowLayoutController: TcxGridCardViewRowLayoutController;

Description

The dispatcher represented by the RowsLayoutController property provides access both to the entire structure of the card and to the structure of the card’s visual layout.  It allows you to manage card layout dynamically, obtain information on different layouts, navigate in a card matrix and reposition items within a card.

ReadOnly Property


TcxGridCardView.Styles

TcxGridCardView          See Also

Specifies the set of styles defining the appearance of the current view elements.

property Styles: TcxGridCardViewStyles;

Description

Use the Styles property to gain access to the set of styles defining the appearance of the current view elements.  This set can be expanded as the Styles property is redefined by TcxCustomGridView descendants.  In the base class, the Styles set includes a style defining the appearance of the current view background.  In this class, the style collection contains styles for the cell contents, selection bar, row captions, cards border etc.

You can use the Styles of a card view row to redefine the appearance of an individual row.


TcxGridCardView.ViewData

TcxGridCardView          See Also

Identifies an object adapting values provided by a data controller for grid view data representation.

property ViewData: TcxGridCardViewViewData;

Description

Use the ViewData property to access an object adapting values provided by a data controller for displaying within a grid view.  This property refers to an instance of the TcxGridCardViewViewData class.  Members of this class provide access to the records currently visible within a view.  They also allow moving focus through the current view records, selecting records, etc.

The following code shows how to use the ViewData property to select records (cards) from the cvCustomers card view.  Only the cards with cvCustomersState set to ‘CA’ are selected and these cards are then removed from the dataset.

// Delphi

...

var

  I: Integer;

begin

  cvCustomers.OptionsSelection.MultiSelect := True;

  with cvCustomers.ViewData do

  begin

    for I := 0 to RecordCount - 1 do

    if Records[I].Values[cvCustomersState.Index] = 'CA' then

      Records[I].Selected := True;

  end;

  cvCustomers.DataController.DeleteSelection;

end;

...

// C++ Builder

...

{

  cvCustomers->OptionsSelection->MultiSelect = true;

  for (int I = 0; I < cvCustomers->ViewData->RecordCount; I++)

    if (cvCustomers->ViewData->Records[I]->Values[cvCustomersState->Index] = "CA") cvCustomers->ViewData->Records[I]->Selected = true;

  cvCustomers->DataController->DeleteSelection;

}

...

ReadOnly Property


TcxGridCardView.ViewInfo

TcxGridCardView          See Also

Provides access to the object holding the information used to paint the card view.

property ViewInfo: TcxGridCardViewInfo;

Description

Use the ViewInfo property to access the object that adapts the values provided by the data controller, so that they can be displayed within a grid view.  This property refers to an instance of the TcxGridCardViewViewData class.  Members of this class provide access to the records currently visible within a view.  They also allow focus to be moved through the current view records, records to be selected, etc.

The following code shows how to use the ViewInfo property to select records (cards) from the cvCustomers card view.  Only the cards with cvCustomersState set to ‘CA’ are selected and these cards are then removed from the dataset.

ReadOnly Property


TcxGridCardView.VisibleRowCount

TcxGridCardView          See Also

Returns the number of currently visible card rows.

property VisibleRowCount: Integer;

Description

Use the VisibleRowCount property to obtain the number of the currently visible card view rows.  The card view row visibility is determined via the CardViewRow.Visible property value.  All visible card view rows can be accessed via the VisibleRows property.

ReadOnly Property


TcxGridCardView.VisibleRows

TcxGridCardView          See Also

Provides indexed access to visible card rows.

property VisibleRows[Index: Integer]: TcxGridCardViewRow;

Description

Use the VisibleRows property to gain indexed access to the currently visible card view rows.  The card view row visibility is determined by the CardViewRow.Visible property value.  The number of the currently visible card view rows can be obtained via the VisibleRowCount property.

ReadOnly Property


TcxGridCardView.CreateRow

TcxGridCardView          See Also

Creates a card view row and adds it to the current card view.

function CreateRow: TcxGridCardViewRow;

Description

Use the CreateRow method to create a card view row and add it to the current view.  After the card view row is added to the current view, a user can specify its settings: connection to a data storage, behavior options and styles, etc.

The following code shows the creation of a card row within the cxGridCardView1 view.  In provider mode, you need to assign the DataBinding.ValueTypeClass and DataBinding.Data properties.  Refer to the Provider Mode section for details.

// Delphi

const

  PostalCodeID = 7;  //unique ID

//...

  with cxGridCardView1.CreateRow do

  begin

    Caption := 'Postal Code';

    DataBinding.ValueTypeClass := TcxIntegerValueType;

    DataBinding.Data := PostalCodeID;

  end;

// C++ Builder

const PostalCodeID = 7;  //unique ID

//...

cxGridCardView1->CreateRow->Caption = "Postal Code";

cxGridCardView1->CreateRow->ValueTypeClass = TcxIntegerValueType;

cxGridCardView1->CreateRow->Data = PostalCodeID;


TcxGridCardView.OnRowCollapsed

TcxGridCardView          See Also

Fires after a category row has collapsed.

type

  TcxGridCardRowEvent = procedure(Sender: TcxGridCardView; ARow: TcxGridCardViewRow) of object;

property OnRowCollapsed: TcxGridCardRowEvent;

Description

The OnRowCollapsed event fires when the category row has been collapsed by an end-user or programmatically (by setting the row’s Expanded property to False).

Implement the OnRowCollapsed event handler to provide custom behavior after the category row has been collapsed.

The Sender parameter specifies the card view to which the category row belongs;

ARow specifies the category row that has been collapsed.


TcxGridCardView.OnRowCollapsing

TcxGridCardView          See Also

Fires when a category row is about to be collapsed.

type

  TcxGridCardRowChangingEvent = procedure(Sender: TcxGridCardView; ARow: TcxGridCardViewRow; var AAllow: Boolean) of object;

property OnRowCollapsing: TcxGridCardRowChangingEvent;

Description

The OnRowCollapsing event fires when the category row starts collapsing either by end-user action or via code (by setting the row’s Expanded property to False).

Implement the OnRowCollapsing event handler to provide custom behavior when the category row is about to be collapsed.  For instance, you can handle this event to prevent the category row from unnecessarily collapsing.

The Sender parameter specifies the card view to which the category row belongs;

ARow specifies the category row that is about to be collapsed;

The AAllow parameter specifies whether ARow will be collapsed.  Set the AAllow parameter to False to prevent ARow from collapsing.


TcxGridCardView.OnRowExpanded

TcxGridCardView          See Also

Fires after a category row has expanded.

type

  TcxGridCardRowEvent = procedure(Sender: TcxGridCardView; ARow: TcxGridCardViewRow) of object;

property OnRowExpanded: TcxGridCardRowEvent;

Description

The OnRowExpanded event fires when the category row has been expanded by an end-user or programmatically (by setting the row’s Expanded property to True).

Implement the OnRowExpanded event handler to provide custom behaviors after a category row has been expanded.  For instance, you can handle this event to update a list of the row’s children and recalculate the layout, if required.

The Sender parameter specifies the card view to which the category row belongs;

The ARow parameter specifies a category row that has been expanded.


TcxGridCardView.OnRowExpanding

TcxGridCardView          See Also

Fires when a category row is about to be expanded.

type

  TcxGridCardRowChangingEvent = procedure(Sender: TcxGridCardView; ARow: TcxGridCardViewRow; var AAllow: Boolean) of object;

property OnRowExpanding: TcxGridCardRowChangingEvent;

Description

The OnRowExpanding event fires when the category row starts expanding either by end-user action or via code (by setting the row’s Expanded property to True).

Implement the OnRowExpanding event handler to provide custom behavior when the category row is about to be expanded.  For instance, you can handle this event to prevent the category row from unnecessarily expanding.

The Sender parameter specifies the card view to which the category row belongs;

The ARow parameter specifies the category row that is about to be expanded;

The AAllow parameter specifies whether ARow will be expanded.  Set the AAllow parameter to False to prevent ARow from expanding.


TcxGridCardView.OnRowPosChanged

TcxGridCardView          See Also

Occurs when an end-user changes the visibility or position of a card view row within the current view.

type

  TcxGridCardRowEvent = procedure(Sender: TcxGridCardView; ARow: TcxGridCardViewRow) of object;

property OnRowPosChanged: TcxGridCardRowEvent;

Description

The OnRowPosChanges event is fired when an end-user moves a card view row or changes its visibility within the current view (for instance, by dragging it to the Customization Form).  The Sender parameter specifies the view in which a card view row’s position or visibility has been changed.  The ARow parameter identifies the card view row that is being moved or shown/hidden.


cxGridCardBorderMinWidth constant
cxGridCardBorderMinWidth global constant

See Also

Specifies the default minimum width of a card’s border.

Unit

cxGridCardView

cxGridCardBorderMinWidth = 1;


cxGridCardDefaultWidth constant
cxGridCardDefaultWidth global constant

See Also

Specifies the default width of a card.

Unit

cxGridCardView

cxGridCardDefaultWidth = 200;


cxGridCardMinWidth constant
cxGridCardMinWidth global constant

See Also

Specifies the minimum default width of a card.

Unit

cxGridCardView

cxGridCardMinWidth = 40;


cxGridDefaultCardBorderWidth constant
cxGridDefaultCardBorderWidth global constant

See Also

Specifies the default width of a card’s border.

Unit

cxGridCardView

cxGridDefaultCardBorderWidth = 3;


TcxGridCardViewStyles
TcxGridCardViewStyles Object

Hierarchy          Properties          Methods          Events          See Also

Represents a set of styles managing the appearance of a card view.

Unit

cxGridCardView

TcxGridCardViewStyles = class(TcxCustomGridTableViewStyles);

Description

The TcxGridCardViewStyles property defines a set of properties and events, which allow you to specify the appearance of all card view elements.  By handling the styles events, it is possible to define different styles for individual records (cards).  To set the styles for a card view, see the TcxGridCardView.Styles property.


TcxGridCardViewStyles Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomStyles

     |

TcxStyles

     |

TcxCustomGridStyles

     |

TcxCustomGridViewStyles

     |

TcxCustomGridTableViewStyles

     |


Properties for TcxGridCardViewStyles
TcxGridCardViewStyles Properties

TcxGridCardViewStyles          Legend

In TcxGridCardViewStyles

CaptionRow

CardBorder

CategoryRow

CategorySeparator

GridView

LayerSeparator

RowCaption

Derived from TcxCustomGridTableViewStyles

Content

ContentEven

ContentOdd

FilterBox

GridView

Inactive

IncSearch

Selection

Derived from TcxCustomGridViewStyles

Background

Derived from TcxCustomGridStyles

GridView

Derived from TcxCustomStyles

StyleSheet


Methods for TcxGridCardViewStyles
TcxGridCardViewStyles Methods

TcxGridCardViewStyles          Legend

In TcxGridCardViewStyles

 GetCaptionRowParams

 GetCardBorderParams

 GetCardBorderVisualParams

 GetCategoryRowParams

 GetDataCellContentParams

 GetRowCaptionParams

Derived from TcxCustomStyles

 Assign

 Create

 Destroy


Events for TcxGridCardViewStyles
TcxGridCardViewStyles Events

TcxGridCardViewStyles          Legend

In TcxGridCardViewStyles

 OnGetCaptionRowStyle

 OnGetCardBorderStyle

 OnGetCategoryRowStyle

 OnGetRowCaptionStyle

Derived from TcxCustomGridTableViewStyles

 OnGetContentStyle


TcxGridCardViewStyles.CaptionRow

TcxGridCardViewStyles          See Also

Specifies the style for caption rows.

property CaptionRow: TcxStyle;

Description

The CaptionRow property allows you to define the style (font, background color) of all caption rows within the card view.  A caption row is a row with its Kind attribute set to rkCaption.

It is possible to redefine the style for a specific caption row by handling the OnGetCaptionRowStyle event.


TcxGridCardViewStyles.CardBorder

TcxGridCardViewStyles          See Also

Specifies the style for the card border.

property CardBorder: TcxStyle;

Description

The CardBorder property allows you to define the style (font, background color) of all card borders within the card view.  It is possible to redefine the style for specific card borders by handling the OnGetCardBorderStyle event.

The card border on the following image is highlighted with the clFuchsia color:


TcxGridCardViewStyles.CategoryRow

TcxGridCardViewStyles          See Also

Specifies style attributes for a category row and its children’s indentation.

property CategoryRow: TcxStyle;

Description

Use the CategoryRow property to specify the style common to all the category rows in a card view.


TcxGridCardViewStyles.CategorySeparator

TcxGridCardViewStyles          See Also

Specifies style attributes for the category row’s separator.

property CategorySeparator: TcxStyle;

Description

Use the CategorySeparator property to specify the style common to all the category row separators shown in the card view.


TcxGridCardViewStyles.GridView

TcxGridCardViewStyles

Represents a card view whose elements the current styles are applied to.

property GridView: TcxGridCardView;

Description

Use the GridView property to access the card view instance.

ReadOnly Property


TcxGridCardViewStyles.LayerSeparator

TcxGridCardViewStyles          See Also

Specifies style attributes for a layer separator.

property LayerSeparator: TcxStyle;

Description

A layer separator is a bar that visually divides layered rows in a card:

Use the LayerSeparator property to apply the required style to the layer separator.


TcxGridCardViewStyles.RowCaption

TcxGridCardViewStyles          See Also

Specifies the style for row captions.

property RowCaption: TcxStyle;

Description

The RowCaption property allows you to define the style (font, background color) of the current row caption.  It is possible to redefine the style for a specific row caption by handling the OnGetRowCaptionStyle event.


TcxGridCardViewStyles.GetCaptionRowParams

TcxGridCardViewStyles          See Also

Gets the TcxViewParams record containing information on the caption row’s style attributes.

procedure GetCaptionRowParams(ARecord: TcxCustomGridRecord; AItem: TcxCustomGridTableItem; out AParams: TcxViewParams); virtual;

Description

The ARecord parameter specifies the record that the currently processed row corresponds to;

The AItem parameter specifies the row to be processed;

The AParams parameter specifies style attributes that the method results in.


TcxGridCardViewStyles.GetCardBorderParams

TcxGridCardViewStyles          See Also

Gets the TcxViewParams record containing information on the card border’s style attributes.

procedure GetCardBorderParams(ARecord: TcxCustomGridRecord; out AParams: TcxViewParams); virtual;

Description

The ARecord parameter specifies the record that the currently processed row corresponds to;

The AParams parameter specifies style attributes that the method results in.


TcxGridCardViewStyles.GetCardBorderVisualParams

TcxGridCardViewStyles

Gets the TcxViewParams record containing information on the border’s style attributes when the card is focused.

procedure GetCardBorderVisualParams(ARecord: TcxCustomGridRecord; out AParams: TcxViewParams); virtual;

Description

The GetCardBorderVisualParams method obtains the style of the focus rectangle if it’s drawn.  The focus rectangle is shown if the card is currently selected and the view’s OptionsSelection.CardBorderSelection property is set to True.

Otherwise, the style of the card border (specified by the CardBorder property, or by the OnGetCardBorderStyle event handler if implemented) will be obtained.

The ARecord parameter specifies the record that the currently processed row corresponds to;

The AParams parameter specifies style attributes that the method results in.


TcxGridCardViewStyles.GetCategoryRowParams

TcxGridCardViewStyles          See Also

Gets the TcxViewParams record containing information on the category row’s style attributes.

procedure GetCategoryRowParams(ARecord: TcxCustomGridRecord; AItem: TcxCustomGridTableItem; out AParams: TcxViewParams); virtual;

Description

The ARecord parameter specifies the record that the currently processed row corresponds to;

The AItem parameter specifies the row to be processed;

The AParams parameter specifies style attributes that the method results in.


TcxGridCardViewStyles.GetDataCellContentParams

TcxGridCardViewStyles

Gets the TcxViewParams record containing information on the data row value’s style attributes.

procedure GetDataCellContentParams(ARecord: TcxCustomGridRecord; AItem: TcxCustomGridTableItem; out AParams: TcxViewParams); override;

Description

The ARecord parameter specifies the record that the currently processed row corresponds to;

The AItem parameter specifies the row to be processed;

The AParams parameter specifies style attributes that the method results in.


TcxGridCardViewStyles.GetRowCaptionParams

TcxGridCardViewStyles          See Also

Gets the TcxViewParams record containing information on the row caption’s style attributes.

procedure GetRowCaptionParams(ARecord: TcxCustomGridRecord; AItem: TcxCustomGridTableItem; out AParams: TcxViewParams); virtual;

Description

The ARecord parameter specifies the record that the currently processed row corresponds to;

The AItem parameter specifies the row to be processed;

The AParams parameter specifies style attributes that the method results in.


TcxGridCardViewStyles.OnGetCaptionRowStyle

TcxGridCardViewStyles          See Also

Occurs when a row of the "caption" type should be redrawn.

type

  TcxGridGetCellStyleEvent = procedure(Sender: TcxCustomGridTableView; ARecord: TcxCustomGridRecord; AItem: TcxCustomGridTableItem; out AStyle: TcxStyle) of object;

property OnGetCaptionRowStyle: TcxGridGetCellStyleEvent;

Description

You can handle the OnGetCaptionRowStyle event to redefine the style for specific caption rows (a card view row with its Kind property set to rkCaption).  This event occurs when it is necessary to redraw the caption row of the specific card defined by the ARecord parameter.  The item (card row) is specified by the AItem parameter.

The Sender parameter determines the view containing the card.


TcxGridCardViewStyles.OnGetCardBorderStyle

TcxGridCardViewStyles          See Also

Occurs whenever the card border should be redrawn.

type

  TcxGridGetRecordStyleEvent = procedure(Sender: TcxCustomGridTableView; ARecord: TcxCustomGridRecord; out AStyle: TcxStyle) of object;

property OnGetCardBorderStyle: TcxGridGetRecordStyleEvent;

Description

You can handle the OnGetCardBorderStyle event to redefine the style of specific card borders.  This event occurs when it is necessary to redraw the card border of the grid record defined by the ARecord parameter.

The Sender parameter determines the view containing the item.


TcxGridCardViewStyles.OnGetCategoryRowStyle

TcxGridCardViewStyles          See Also

Fires each time the category row is about to be drawn.

type

  TcxGridGetCellStyleEvent = procedure(Sender: TcxCustomGridTableView; ARecord: TcxCustomGridRecord; AItem: TcxCustomGridTableItem; out AStyle: TcxStyle) of object;

property OnGetCategoryRowStyle: TcxGridGetCellStyleEvent;

Description

Implement the OnGetCategoryRowStyle event handler to manually apply a custom style to the specific category row.

The Sender parameter specifies a card view containing the currently processed category row;

The ARecord parameter specifies a record that the currently processed category row corresponds to;

The AItem parameter specifies the currently processed category row;

The AStyle parameter specifies style attributes to be applied to the category row.


TcxGridCardViewStyles.OnGetRowCaptionStyle

TcxGridCardViewStyles          See Also

Occurs whenever the row caption should be redrawn.

type

  TcxGridGetCellStyleEvent = procedure(Sender: TcxCustomGridTableView; ARecord: TcxCustomGridRecord; AItem: TcxCustomGridTableItem; out AStyle: TcxStyle) of object;

property OnGetRowCaptionStyle: TcxGridGetCellStyleEvent;

Description

You can handle the OnGetRowCaptionStyle event to redefine the style of specific row captions.  This event occurs when it is necessary to redraw a row caption of the grid record defined by the ARecord parameter.  The item is specified by the AItem parameter.

The Sender parameter determines the view containing the item.


TcxGridCardViewStyleSheet
TcxGridCardViewStyleSheet Object

Hierarchy          Properties          Methods          See Also

Represents a style sheet for a card view.

Unit

cxGridCardView

TcxGridCardViewStyleSheet = class(TcxCustomStyleSheet);

Description

A StyleSheet contains a collection of styles that can be applied to a view, setting multiple styles in one step.  The TcxGridCardViewStyleSheet provides a style sheet collection for the card view.


TcxGridCardViewStyleSheet Hierarchy
Hierarchy

TComponent

     |

TcxCustomStyleSheet

     |


Properties for TcxGridCardViewStyleSheet
TcxGridCardViewStyleSheet Properties

TcxGridCardViewStyleSheet          Legend

In TcxGridCardViewStyleSheet

Styles

Derived from TcxCustomStyleSheet

Caption

StyleRepository


Methods for TcxGridCardViewStyleSheet
TcxGridCardViewStyleSheet Methods

TcxGridCardViewStyleSheet          Legend

Derived from TcxCustomStyleSheet

 Create

 Destroy


TcxGridCardViewStyleSheet.Styles

TcxGridCardViewStyleSheet          See Also

Represents a set of styles managing the appearance of card view.

property Styles: TcxGridCardViewStyles;

Description

The Styles property defines a set of properties and events that allow you to specify the appearance of all card view elements.

By handling the styles events it is possible to override the property styles and define different styles for records (cards) on the fly.

To set the styles to a card view, see the TcxGridCardView.Styles property.


TcxCustomGridTableViewStyles
TcxCustomGridTableViewStyles Object

Hierarchy          Properties          Methods          Events          See Also

Represents the settings controlling the style of view elements.

Unit

cxGridCustomTableView

TcxCustomGridTableViewStyles = class(TcxCustomGridViewStyles);

Description

The TcxCustomGridTableViewStyles class declares properties and events so you can customize the appearance of view elements.  Descendants of TcxCustomGridTableViewStyles publish additional properties specific to particular views (table or card).  To adjust the appearance of a view, see the TcxCustomGridTableView.Styles property.


TcxCustomGridTableViewStyles Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomStyles

     |

TcxStyles

     |

TcxCustomGridStyles

     |

TcxCustomGridViewStyles

     |


Properties for TcxCustomGridTableViewStyles
TcxCustomGridTableViewStyles Properties

TcxCustomGridTableViewStyles          Legend

In TcxCustomGridTableViewStyles

Content

ContentEven

ContentOdd

FilterBox

GridView

Inactive

IncSearch

Selection

Derived from TcxCustomGridViewStyles

Background

Derived from TcxCustomGridStyles

GridView

Derived from TcxCustomStyles

StyleSheet


Methods for TcxCustomGridTableViewStyles
TcxCustomGridTableViewStyles Methods

TcxCustomGridTableViewStyles          Legend

Derived from TcxCustomStyles

 Assign

 Create

 Destroy


Events for TcxCustomGridTableViewStyles
TcxCustomGridTableViewStyles Events

TcxCustomGridTableViewStyles          Legend

In TcxCustomGridTableViewStyles

 OnGetContentStyle


TcxCustomGridTableViewStyles.Content

TcxCustomGridTableViewStyles          See Also

Specifies the style for the grid view content.

property Content: TcxStyle;

Description

The Content property allows you to define the style (font, background color or background bitmap) of all cells within the current grid view. It is possible to redefine the style for a specific cell by handling the OnGetContentStyle event.

Note that the background bitmap cannot be assigned by handling the OnGetContentStyle event.

The following image shows a grid control with the content region painted in lightskyblue color ($00FACE87):


TcxCustomGridTableViewStyles.ContentEven

TcxCustomGridTableViewStyles          See Also

Specifies a style for even grid view rows.

property ContentEven: TcxStyle;

Description

The ContentEven property allows you to define the style (font, background color) of even grid view rows.  Set this property to a different style than the style associated with ContentOdd to create alternating row styles.

Note that the background bitmap cannot be assigned via the ContentEven property as this is relevant only to all the cells within the grid.

The next image demonstrates even rows painted in the khaki color (008CE6F0):


TcxCustomGridTableViewStyles.ContentOdd

TcxCustomGridTableViewStyles          See Also

Specifies a style for odd grid view rows.

property ContentOdd: TcxStyle;

Description

The ContentOdd property allows you to define the style (font, background color) of the odd grid view rows.  Set this property to a different style than the style associated with ContentEven to create alternating row styles.

Note that the background bitmap cannot be assigned via the ContentOdd property as this is relevant only to all the cells within the grid.

The next image demonstrates odd rows painted in cornsilk color (00DCF8FF):


TcxCustomGridTableViewStyles.FilterBox

TcxGridTableViewStyles          See Also

Specifies the style for the filter box.

property FilterBox: TcxStyle;

Description

The FilterBox property allows you to define the style (font, background color) for the filter box.

The filter box in the following image is painted in deepskyblue ($00FFBF00):


TcxCustomGridTableViewStyles.GridView

TcxCustomGridTableViewStyles

Specifies the view to which the style is applied.

property GridView: TcxCustomGridTableView;

Description

Use the GridView property to get the grid view to which the current style is applied.

ReadOnly Property


TcxCustomGridTableViewStyles.Inactive

TcxCustomGridTableViewStyles          See Also

Specifies the style for the inactive selection of a grid view.

property Inactive: TcxStyle;

Description

The Inactive property lets you define the style (font, background color) of the selection within the current grid view when it is not focused.


TcxCustomGridTableViewStyles.IncSearch

TcxCustomGridTableViewStyles          See Also

Specifies the style of text in an incremental search mode.

property IncSearch: TcxStyle;

Description

Use the IncSearch property to specify the style applied to the incremental search request.    Only the font color and background color are used in this style.


TcxCustomGridTableViewStyles.Selection

TcxCustomGridTableViewStyles          See Also

Specifies the style for the active selection of a grid view.

property Selection: TcxStyle;

Description

The Selection property lets you define the style (font, background color) of the selection within the current grid view when it is focused.


TcxCustomGridTableViewStyles.OnGetContentStyle

TcxCustomGridTableViewStyles          See Also

Occurs when it is necessary to paint the table view cell.

type

  TcxGridGetCellStyleEvent = procedure(Sender: TcxCustomGridTableView; ARecord: TcxCustomGridRecord; AItem: TcxCustomGridTableItem; out AStyle: TcxStyle) of object;

property OnGetContentStyle: TcxGridGetCellStyleEvent;

Description

Use the OnGetContentStyle event handler when it is necessary to override the default style of a cell for specific items and/or records.  The event is fired before any cell is repainted.  The cell being painted is addressed by its record (ARecord) and item (AItem).  The Sender parameter determines the table view for which the content is being repainted.

The default cell style is determined based on the view’s Styles.Content, Styles.ContentEven and Styles.ContentOdd properties.

To redefine the style for a specific item/record, you need to assign it to the AStyle parameter.  Use the TcxStyleRepository component as a convenient way to create, delete and modify individual styles.

Note that the background bitmap cannot be assigned by handling the OnGetContentStyle event as this is relevant only to all the cells within the grid.

The following code sets different styles (cxStyle1 and cxStyle2) for odd and even card view items (card rows).  The styles are created via the style repository.  They specify different background and text colors:

// Delphi

procedure Form1.cxGridUsersDBCardViewStylesGetContentStyle(

  Sender: TcxCustomGridTableView; ARecord: TcxCustomGridRecord;

  AItem: TcxCustomGridTableItem; out AStyle: TcxStyle);

begin

  if (Assigned(AItem) And Odd(AItem.VisibleIndex)) then

    AStyle := cxStyle1

  else

    AStyle := cxStyle2;

end;

// C++ Builder

void Form1::cxGridUsersDBCardViewStylesGetContentStyle(

  TcxCustomGridTableView *Sender, TcxCustomGridRecord *ARecord,

  TcxCustomGridTableItem *AItem,  TcxStyle &AStyle)

{

  if ((AItem != NULL)  && ((AItem->VisibleIndex)%2 != 0))

    AStyle = cxStyle1;

  else

    AStyle = cxStyle2;

}


TcxGridSortOrder
TcxGridSortOrder type

Enumerates the available sort orders.

Unit

cxGridCustomTableView

type

  TcxDataSortOrder = (soNone, soAscending, soDescending)

TcxGridSortOrder = TcxDataSortOrder;

Description

The TcxGridSortOrder type defines the available sort orders when sorting items by their values.  To sort items, use the TcxCustomGridTableItem.SortOrder property.  The next table describes the possible item’s sort orders:

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


TcxGridDateTimeFilter
TcxGridDateTimeFilter type

See Also

Enumerates date/time filter options for items (columns and card rows) that display date/time values.

Unit

cxGridCustomTableView

type

  TcxGridDateTimeFilter = (dtfRelativeDays, dtfRelativeDayPeriods, dtfRelativeWeeks, dtfRelativeMonths, dtfRelativeYears, dtfPastFuture, dtfMonths, dtfYears);

  TcxGridDateTimeFilters = set of TcxGridDateTimeFilter;

Description

These options determine time periods to be included into item filter dropdown as filter conditions.  A filter condition is added into an item’s filter dropdown, provided that there’s at least one item value that falls into the corresponding time period.

Time periods used as filter conditions include:

•	relative to the current date (such as yesterday, tomorrow, next month, etc.);

•	absolute time periods derived from item values using date ranges (such as calendar days, months, and years).  In this instance, the corresponding date range is added to an item’s FilteringDateRanges collection.

To specify date/time filter options, use the View’s DateTimeHandling.Filters property.

All available date/time filter options are listed in the following table.

Value	Date Range Used	Meaning
dtfRelativeDays	N/A	Filter conditions represent days relative to the current date, as follows: • Yesterday, • Today, • Tomorrow. String representations of these filter conditions are specified by the scxGridYesterday, scxGridToday, and scxGridTomorrow resource strings, respectively.
dtfRelativeDayPeriods	N/A	Filter conditions represent day periods relative to the current date, as follows: • Last 30 days, • Last 14 days, • Last 7 days, • Next 7 days, • Next 14 days, • Next 30 days. String representations of these filter conditions are specified by the scxGridLast30Days, scxGridLast30Days, scxGridLast7Days, scxGridNext7Days, scxGridNext14Days, and scxGridNext30Days resource strings, respectively.
dtfRelativeWeeks	N/A	Filter conditions represent week periods relative to the current date, as follows: • Last two weeks, • Last week, • This week, • Next week, • Next two weeks. String representations of these filter items are specified by the scxGridLastTwoWeeks, scxGridLastWeek, scxGridThisWeek, scxGridNextWeek, and scxGridNextTwoWeeks resource strings, respectively.
dtfRelativeMonths	N/A	Filter conditions represent month periods relative to the current date, as follows: • Last month, • This month, • Next month. String representations of these filter items are specified by the scxGridLastMonth, scxGridThisMonth, and scxGridNextMonth resource strings, respectively.
dtfRelativeYears	N/A	Filter conditions represent year periods relative to the current date, as follows: • Last year, • Last year, • Next year. String representations of these filter items are specified by the scxGridLastYear, scxGridThisYear, and scxGridNextYear resource strings, respectively.
dtfPastFuture	N/A	Filter conditions represent future or past periods relative to the current date, as follows: • Future, • Past. String representations of these filter items are specified by the scxGridFuture, and scxGridPast resource strings, respectively.
dtfMonths	TcxGridMonthRange	Filter conditions represent individual months derived from item values.  Note that the year portion is also taken into account. Use the View’s DateTimeHandling.MonthFormat property to customize the appearance of these filter conditions in filter dropdowns.
dtfYears	TcxGridYearRange	Filter conditions represent individual years derived from item values. Use the View’s DateTimeHandling.YearFormat property to customize the appearance of these filter conditions in filter dropdowns.

Note:	To customize an item’s FilteringDateRanges collection, handle the OnInitFilteringDateRanges event.


TcxGridDateTimeGrouping
TcxGridDateTimeGrouping type

Enumerates date/time grouping options for items (columns and card rows) that display date/time values.

Unit

cxGridCustomTableView

type

  TcxGridDateTimeGrouping = (dtgDefault, dtgByDateAndTime, dtgRelativeToToday, dtgByHour, dtgByDate, dtgByMonth, dtgByYear);

Description

These options determine time periods to be used in group rows as grouping values.  A grouping value is created for an item, provided that there’s at least one item value that falls into the corresponding time period.

Time periods used as grouping values include:

•	time periods relative to the current date and derived from item values using date ranges (such as yesterday, tomorrow, next month, etc.);

•	absolute time periods derived from item values using date ranges (such as calendar days, months, and years);

•	absolute time periods derived from the date and time portions of item values using date ranges (such as the date portion of date/time values, hours, etc.)

For the last two types of time periods, the corresponding date range is added to an item’s GroupingDateRanges collection.

To specify date/time grouping options, use the View’s DateTimeHandling.Grouping property.

All available date/time grouping options are listed in the following table.

Value	Date Range Used	Meaning
dtgDefault	As specified by the View’s DateTimeHandling.Grouping property.	Indicates that an item's date/time grouping options are specified by the View’s DateTimeHandling.Grouping property. The dtgDefault option is relevant for an item’s grouping options only.  Setting the View’s DateTimeHandling.Grouping property to dtgDefault automatically assigns dtgByDateAndTime to this property.
dtgByDateAndTime		Grouping values represent individual item values.  Both the date and time portions of item values are taken into account.
dtgRelativeToToday	• One-day date ranges: TcxGridYesterdayRange, TcxGridTodayRange, TcxGridTomorrowRange. • One-week date ranges: TcxGridLastWeekRange, TcxGridThisWeekRange, TcxGridNextWeekRange. • One-month date ranges: TcxGridLastMonthRange, TcxGridThisMonthRange, TcxGridNextMonthRange. • One-year date ranges: TcxGridLastYearRange, TcxGridThisYearRange, TcxGridNextYearRange.	Grouping values represent time periods relative to the current date derived from item values using the following date ranges: • one-day date ranges: • Yesterday, • Today, • Tomorrow; • one-week date ranges: • Last week, • This week, • Next week; • one-month date ranges: • Last month, • This month, • Next month; • one-year date ranges: • Last year, • This year, • Next year.
dtgByHour	TcxGridHourRange	Grouping values represent individual hours derived from item values.  The date portion of item values is ignored. Use the View’s DateTimeHandling.HourFormat property to customize the appearance of these grouping values in group rows.
dtgByDate		Grouping values represent unique dates derived from item values.  The time portion of item values is ignored. Use the View’s DateTimeHandling.DateFormat property to customize the appearance of these grouping values in group rows.
dtgByMonth	TcxGridMonthRange	Grouping values represent individual months derived from item values.  Note that the year portion is also taken into account. Use the View’s DateTimeHandling.MonthFormat property to customize the appearance of these grouping values in group rows.
dtgByYear	TcxGridYearRange	Grouping values represent individual years derived from item values. Use the View’s DateTimeHandling.YearFormat property to customize the appearance of these grouping values in group rows.


TcxCustomGridTableController
TcxCustomGridTableController Object

Hierarchy          Properties          Methods

Implements common operations for card and (banded) table views and serves as a base class for view controllers.

Unit

cxGridCustomTableView

TcxCustomGridTableController = class(TcxCustomGridController)

Description

A view controller is a helper object which encapsulates various view specific operations.  To access the view controller's functionality, see the view’s Controller property.

TcxCustomGridTableController is the base class for TcxGridTableController and TcxGridCardViewController which introduce new functionality specific to the TcxGridTableView and TcxGridCardView views respectively.

You can use the members of a view controller to:

-	control editing of a record cell

-	set focus to a specific item (column in a table view or card in a card view) and record

-	start/cancel an incremental search

-	access the collection of selected records

-	perform scrolling

-	navigate through records and items

-	display/hide the customization form


TcxCustomGridTableController Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxGridViewHandler

     |

TcxCustomGridController

     |


Properties for TcxCustomGridTableController
TcxCustomGridTableController Properties

TcxCustomGridTableController          Legend

In TcxCustomGridTableController

Customization

CustomizationForm

CustomizationFormBounds

EditingController

EditingItem

FocusedItem

FocusedItemIndex

FocusedRecord

FocusedRecordIndex

IncSearchingItem

IncSearchingText

IsEditing

IsIncSearching

SelectedRecordCount

SelectedRecords

TopRecordIndex

Derived from TcxGridViewHandler

Control

Controller

DataController

GridView

ViewData


Methods for TcxCustomGridTableController
TcxCustomGridTableController Methods

TcxCustomGridTableController          Legend

In TcxCustomGridTableController

 CancelIncSearching

 ClearSelection

 CreateNewRecord

 DeleteSelection

 FindNextItem

 FindNextRecord

 FocusFirstAvailableItem

 FocusNextCell

 FocusNextItem

 FocusNextRecord

 FocusNextRecordWithSelection

 GoToFirst

 GoToLast

 GoToNext

 GoToPrev

 MakeFocusedItemVisible

 MakeFocusedRecordVisible

 MakeItemVisible

 MakeRecordVisible

Derived from TcxCustomGridController

 Scroll

Derived from TcxGridViewHandler

 BeginUpdate

 Create

 EndUpdate


TcxCustomGridTableController.Customization

TcxCustomGridTableController          See Also

Indicates whether the View's customization form is currently visible.

property Customization: Boolean;

Description

The customization form is a separate form which lists items (columns in tabular Views, card rows in Card Views, series and data groups in Chart Views), and bands (in Banded Table Views) that are not displayed within the view (i.e. their Visible property is set to False).  The customization form allows you to temporarily hide specific items/bands and then restore them.

To display the customization form, set the Customization property to True.  Setting it to False hides the form.  When the form is being displayed or hidden, the View’s OnCustomization event is fired.

By default, the customization form appears in the bottom right corner of the view.  However, you can modify its position via the CustomizationFormBounds property.  You can access the form via the CustomizationForm property when the Customization property is set to True.

Drag an item/band by its caption onto the customization form to hide it.  If a table view’s OptionsCustomize.ColumnHiding (the OptionsCustomize.RowHiding property for a card view or, the OptionsCustomize.DataGroupHiding, OptionsCustomize.SeriesCustomization and OptionsCustomize.OptionsCustomization properties for a chart view) or OptionsCustomize.BandHiding property is set to False, the customization form must be visible onscreen to enable the hiding of items/bands.  If the OptionsCustomize.ColumnHiding, OptionsCustomize.RowHiding or OptionsCustomize.DataGroupHiding property is set to True, items can be hidden (dragged away from their places) regardless of the customization form’s visibility.

To restore an item/band, drag it from the customization form onto the column header panel (card or chart toolbox) or band header panel.

The customization form does not display items/bands, if the VisibleForCustomization property (TcxGridColumn.VisibleForCustomization, TcxGridCardViewRow.VisibleForCustomization, TcxGridBand.VisibleForCustomization, TcxGridChartItem.VisibleForCustomization) is set to True.  When you drag items/bands away from their header panel or card, it will be hidden from the view and will not be placed in the customization form.  You can then restore these items only programmatically.


TcxCustomGridTableController.CustomizationForm

TcxGridTableController          See Also

Gets the customization form.

property CustomizationForm: TcxGridTableCustomizationForm;

Description

The customization form for the current view can be accessed via the CustomizationForm property.  If the form is not visible onscreen, CustomizationForm returns NIL.  To display the form, set the Customization property to True.  Setting it to False hides the form.  When the form is being displayed or hidden, the view’s OnCustomization event is fired.

To get more information on the customization form, see the Customization property topic.

The TcxCustomGridTableCustomizationForm class derives from TForm.  To get the dimensions and position of the form, you can use the members inherited from TForm (for instance, the BoundsRect property) or the CustomizationFormBounds property.  The properties of the form can be set only when the form is opened but the CustomizationFormBounds property can be set at any time.

The following code opens the customization form and makes it translucent:

//Delphi

  if Grid.FocusedView is TcxCustomGridTableView then

    with TcxCustomGridTableController(Grid.FocusedView.Controller) do

      begin

        Customization := True;

        CustomizationForm.AlphaBlendValue := 200;

        CustomizationForm.AlphaBlend := True;

      end;

//C++ Builder

  if (dynamic_cast< TcxCustomGridTableView *>(Grid->FocusedView)) {

    TcxCustomGridTableController * AController =

      ((TcxCustomGridTableView *)Grid->FocusedView)->Controller;

    AController->Customization = true;

    AController->CustomizationForm->AlphaBlendValue = 200;

    AController->CustomizationForm->AlphaBlend = true;

  }

ReadOnly Property


TcxCustomGridTableController.CustomizationFormBounds

TcxGridTableController          See Also

Specifies the bounding rectangle of the customization form.

property CustomizationFormBounds: TRect;

Description

Use the CustomizationFormBounds property to specify the coordinates of all the corners of the customization form.  The position of the form is relative to the screen.

To get information on the customization form, see the Customization property.

The following code example positions the customization form in the top right corner of the screen:

//Delphi

  if Grid.FocusedView is TcxCustomGridTableView then

    with TcxCustomGridTableView(Grid.FocusedView).Controller do

      begin

        CustomizationFormBounds :=

          Rect(Screen.Width - 200, 0, Screen.Width, 300);

        Customization := True;

      end;

//C++ Builder

  if (dynamic_cast< TcxCustomGridTableView *>(Grid->FocusedView)) {

    TcxCustomGridTableController * AController =

      ((TcxCustomGridTableView *)Grid->FocusedView)->Controller;

    AController->CustomizationFormBounds =

      Rect(Screen->Width - 200, 0, Screen->Width, 300);

    AController->Customization = true;

  }


TcxCustomGridTableController.EditingController

TcxCustomGridTableController

Returns the object that controls active cell editing within the current view.

property EditingController: TcxGridEditingController;

Description

Use the EditingController property to access the functionality of the editing controller for the current view.  An editing controller allows you to:

-	get the in-place editor used to edit the active cell

-	open/close an editor while posting or discarding changes

ReadOnly Property


TcxCustomGridTableController.EditingItem

TcxCustomGridTableController          See Also

References the item currently being edited.

property EditingItem: TcxCustomGridTableItem;

Description

You can use the EditingItem property to open/close an editor for a specific item (column in a (banded) table view and row in a card view) of the focused record.

The EditingItem returns NIL, if a cell editor is not opened.  To open the editor programmatically, you can assign a specific view item to EditingItem.  For instance, the following code opens the editor for the tvOrdersDescription column of the focused record within the tvOrders view:

//Delphi

  tvOrders.Controller.EditingItem := tvOrdersDescription;

//C++ Builder

  tvOrders->Controller->EditingItem = tvOrdersDescription;

The EditingItem property actually refers to the EditingItem property of EditingController.  EditingController provides several methods and properties to control cell editing.

ExpressQuantumGrid provides several properties to disable editing.  See the TcxCustomGridTableItem.Editing topic for details.


TcxCustomGridTableController.FocusedItem

TcxCustomGridTableController          See Also

Specifies the item of the current record being focused.

property FocusedItem: TcxCustomGridTableItem;

Description

Use the FocusedItem property to focus a specific item (column in a (banded) table view and row in a card view) within the active record.

You can use the item’s Options.Focusing and view’s OptionsSelection.CellSelect property to prevent focusing any view items.  If no item is focused at the moment, FocusedItem returns NIL.  To test whether a specific item is focused, see its Focused property.

The FocusedItemIndex property allows you to access/specify the focused item by its visual index (the position within the view’s VisibleItems collection).

Every time focus set to another item, the view’s OnFocusedItemChanged event is generated.

The following code sets focus to tvOrdersProductID item of the tvOrders view:

//Delphi

tvOrders.Controller.FocusedItem := tvOrdersProductID;

//C++ Builder

tvOrders->Controller->FocusedItem = tvOrdersProductID;


TcxCustomGridTableController.FocusedItemIndex

TcxCustomGridTableController          See Also

Identifies the index of the currently focused item.

property FocusedItemIndex: Integer;

Description

Similar to the FocusedItem property, FocusedItemIndex can be used to specify the focused item (column in a (banded) table view and row in a card view) of the current view record.  FocusedItemIndex identifies the position of the item within the view’s VisibleItems collection.

Refer to the FocusedItem topic for additional information.

The following code, sets focus to the first visible item within a view:

//Delphi

  AView.Controller.FocusedItemIndex := 0;

//C++ Builder

  AView->Controller->FocusedItemIndex = 0;


TcxCustomGridTableController.FocusedRecord

TcxCustomGridTableController          Concepts           See Also

Refers to a record being focused within a view.

property FocusedRecord: TcxCustomGridRecord;

Description

You can use the FocusedRecord property to access the record being focused within the current view.  FocusedRecord represents a TcxCustomGridRecord object which is the base class for all record types in ExpressQuatumGrid: data rows, master data rows, group rows, cards.  Refer to the Records section to learn more about this.

The Focused/Selected Records document provides more information.

The following example checks whether a group row is focused.  If so, it is expanded and the first data row under the group row is focused.

//Delphi

var

  AView: TcxCustomGridTableView;

//...

  AView := TcxCustomGridTableView(Grid.FocusedView);

  with AView.Controller do

    if FocusedRecord is TcxGridGroupRow then

    begin

      FocusedRecord.Expand(True);

      FocusedRecordIndex := FocusedRecordIndex +

        AView.GroupedItemCount - FocusedRecord.Level;

    end;

//C++ Builder

TcxCustomGridTableView * AView =

  (TcxCustomGridTableView*) Grid->FocusedView;

TcxCustomGridTableController * AController = AView->Controller;

if (dynamic_cast<TcxGridGroupRow*>(AController->FocusedRecord)) {

  AController->FocusedRecord->Expand(true);

  AController->FocusedRecordIndex = AController->FocusedRecordIndex +

    AView->GroupedItemCount - AController->FocusedRecord->Level;

}


TcxCustomGridTableController.FocusedRecordIndex

TcxCustomGridTableController          Concepts           See Also

Returns the index of the focused record.

property FocusedRecordIndex: Integer;

Description

You can use the FocusedRecordIndex property to get/set the focused record within the current view.  FocusedRecordIndex addresses the focused record by its visual position within the view.

When the view loads all records from a datasource (the GridMode property is set to False), FocusedRecordIndex specifies the record position relative to the top view record.

In GridMode, a data controller loads only a fixed number of records into a memory buffer.  When you scroll the view contents and reach the end of the buffer, the data controller loads the next portion of records and focus is moved to a record within the new buffer.

Use the FocusedRecord property to access the record rather than its index.  The Focused/Selected Records document provides more information related to focused records.

The following example checks whether a group row is focused.  If so, it is expanded and the first data row under the group row is focused.

//Delphi

var

  AView: TcxCustomGridTableView;

//...

  AView := TcxCustomGridTableView(Grid.FocusedView);

  with AView.Controller do

    if FocusedRecord is TcxGridGroupRow then

    begin

      FocusedRecord.Expand(True);

      FocusedRecordIndex := FocusedRecordIndex +

        AView.GroupedItemCount - FocusedRecord.Level;

    end;

//C++ Builder

TcxCustomGridTableView * AView =

  (TcxCustomGridTableView*) Grid->FocusedView;

TcxCustomGridTableController * AController = AView->Controller;

if (dynamic_cast<TcxGridGroupRow*>(AController->FocusedRecord)) {

  AController->FocusedRecord->Expand(true);

  AController->FocusedRecordIndex = AController->FocusedRecordIndex +

    AView->GroupedItemCount - AController->FocusedRecord->Level;

}


TcxCustomGridTableController.IncSearchingItem

TcxCustomGridTableController          Concepts           See Also           Example

Returns the item on which an incremental search is being performed.

property IncSearchingItem: TcxCustomGridTableItem;

Description

ExpressQuantumGrid supports an incremental search feature with which a user can locate a required record by a specific item value (an item stands for a column in a (banded) table view and row in a card view).

To start an incremental search, focus the view item against which the search is to be performed (the focused item cell must not be in edit mode).  Then type the text to search for and this locates the first record whose item value matches the text.  Modifying the search text locates another record with a corresponding item value.

If cell focusing is disabled by setting the view’s OptionsSelection.CellSelect property to False, you can specify the search item explicitly with the help of the view’s OptionsBehavior.IncSearchItem property.  In other cases, OptionsBehavior.IncSearchItem is not effective.

To enable an incremental search, set the view’s OptionsBehavior.IncSearch property to True.  In addition, make certain, that the item’s Options.IncSearch property is also set to True.

The IncSearchingItem property refers to the item on which an incremental search is being performed.  When no search is being performed (the IsIncSearching property returns False), IncSearchingItem returns nil.

To get/set the text for the search, see the IncSearchingText property.  Assigning a non-empty string to IncSearchingText starts the search from the currently focused record to the bottom.

The view’s DataController.Search.LocateNext method allows you to continue the search in the required direction.  To cancel the search, see the CancelIncSearching method.

ReadOnly Property


TcxCustomGridTableController.IncSearchingText

TcxCustomGridTableController          Concepts           See Also           Example

Specifies the text being searched.

property IncSearchingText: string;

Description

You can use the IncSearchingText property to specify the text for the incremental search.  Assigning a non-empty string to the property starts the search from the currently focused record to the bottom.  The view’s DataController.Search.LocateNext method allows you to continue the search in the required direction.  To cancel the search, see the CancelIncSearching method.  An empty string assigned to IncSearchingText also stops the search.

The search is performed on the item (a column in a (banded) table view and row in a card view) being focused.  However, if cell focusing is disabled by setting the view’s OptionsSelection.CellSelect property to False, you can specify the search item explicitly with the help of the view’s OptionsBehavior.IncSearchItem property.  In other cases, OptionsBehavior.IncSearchItem is not effective.

To start an incremental search, focus a view item against which the search will be performed (the focused item cell must not be in edit mode) or specify the search item via the view’s OptionsBehavior.IncSearchItem property (see notes above).  Then type in the text to search for and this locates the first record whose item value matches the text.  Modifying the search text locates another record with a corresponding item value.

To enable an incremental search, set the view’s OptionsBehavior.IncSearch property to True.  In addition, make certain, that the item’s Options.IncSearch property is also set to True.


TcxCustomGridTableController.IsEditing

TcxCustomGridTableController          See Also

Indicates whether a cell within the view is being edited.

property IsEditing: Boolean;

Description

The IsEditing property returns True if some of the focused record cells is being edited using an in-place editor.  Otherwise, False is returned.  The in-place editor can be accessed via the EditingController.Edit property.

To specify the item (a column in a (banded) table view and row in a card view) to edit, you can use the EditingItem property.

You can disable editing within the view in a number of ways.  Refer to the TcxCustomGridTableItem.Editing topic for more information.

ReadOnly Property


TcxCustomGridTableController.IsIncSearching

TcxCustomGridTableController          Concepts           See Also           Example

Indicates whether an incremental search is being performed.

property IsIncSearching: Boolean;

Description

ExpressQuantumGrid supports an incremental search feature with which a user can locate a required record by typing characters (an item is a column in a (banded) table view and row in a card view).  The Incremental search topic provides more information on the incremental search feature.

You can use the IsIncSearching property to test whether the current view is in incremental search mode.  The text being searched is specified by the IncSearchingText property

By default, incremental search is not available.  To enable this feature, set the view’s OptionsBehavior.IncSearch property to True.

ReadOnly Property


TcxCustomGridTableController.SelectedRecordCount

TcxCustomGridTableController          See Also

Returns the number of selected records within the view.

property SelectedRecordCount: Integer;

Description

A grid control allows you to select multiple records within a view if its OptionsSelection.MultiSelect property is set to True.

You can use the SelectedRecordCount property to get the number of selected records.

Access to selected records is implemented differently in GridMode and default mode.

When GridMode is applied to a data-aware view, you can get selected records via the view’s DataController.GetSelectedBookmark function.  This returns a TBookmarkStr object which can be used in the dataset’s GotoBookmark method, for instance.

If GridMode is disabled (by default), use the SelectedRecords collection to get selected record objects.

ReadOnly Property


TcxCustomGridTableController.SelectedRecords

TcxCustomGridTableController          See Also

Provides indexed access to selected records.

property SelectedRecords[Index: Integer]: TcxCustomGridRecord;

Description

Use the SelectedRecords property to obtain selected records when GridMode is not applied.

When GridMode is applied to a data-aware view, you can get selected records via the view’s DataController.GetSelectedBookmark function.  This returns a TBookmarkStr object which can be used in the dataset’s GotoBookmark method, for instance.

The number of records is defined by the SelectedRecordCount property.

To enable a user to select multiple records, set the view’s OptionsSelection.MultiSelect property to True.  The Focused/Selected Records section gives you more information relating to this topic.

ReadOnly Property


TcxCustomGridTableController.TopRecordIndex

TcxCustomGridTableController          See Also

Addresses the topmost visible record within the current view.

property TopRecordIndex: Integer;

Description

You can use the TopRecordIndex property to scroll the view contents.  TopRecordIndex specifies the index of the record displayed at the top of the visible view portion.  The index is relative to the first record within the view.  TopRecordIndex allows you to scroll the view both in GridMode and in default mode.

In GridMode, only a fixed number of records is loaded into a memory buffer at a time.  When scrolling, a grid control loads another portion of records into the buffer to reflect the current scroll location.  In this mode, TopRecordIndex maintains a record index relative to the first record within the current buffer.

The Scroll method also enables you to scroll the view contents by simulating user actions with a scrollbar.

Table and banded table views are capable of displaying vertical and horizontal scroll bars.  To scroll vertically, use TopRecordIndex.  To scroll horizontally, see the LeftPos property provided by the TcxGridTableController class.  In card views, this property is not implemented; use TopRecordIndex instead.

The following example scrolls the view contents by 10 records forward.

//Delphi

  with TcxCustomGridTableView(Grid.FocusedView).Controller do

    TopRecordIndex := TopRecordIndex + 10;

//C++ Builder

  TcxCustomGridTableController * AController =

    ((TcxCustomGridTableView*)Grid->FocusedView)->Controller;

  AController->TopRecordIndex = AController->TopRecordIndex + 10;


TcxCustomGridTableController.CancelIncSearching

TcxCustomGridTableController          Concepts           See Also           Example

Stops an incremental search.

procedure CancelIncSearching;

Description

The CancelIncSearching method assigns an empty string to the IncSearchingText property and this stops an incremental search started programmatically or by a user.

Refer to the Incremental search section to get more details on this feature.


TcxCustomGridTableController.ClearSelection

TcxCustomGridTableController          See Also

Unselects records within the current view.

procedure ClearSelection;

Description

Use the ClearSelection method to unselect records selected within the view.  You can refer to the Focused/Selected Records section for more information on selected records.

When GridMode is not applied, selected records can be obtained from the SelectedRecords collection.  When a view works in bound GridMode, use its DataController.GetSelectedBookmark function instead.


TcxCustomGridTableController.CreateNewRecord

TcxCustomGridTableController          See Also

Creates a new record within the view.

procedure CreateNewRecord(AtEnd: Boolean); virtual;

Description

You can use the CreateNewRecord method to add a new record within the current view.  This method calls either the Insert or Append method of the view’s DataController object depending on the AtEnd parameter.  If AtEnd is False, the new record is inserted above the focused one.  If AtEnd is True, the new record is inserted at the end.  Note that the position of the record can change after entering its cell values if sorting is applied).

The view’s OptionsBehavior.FocusFirstCellOnNewRecord property determines whether the record’s first focusable cell is focused when creating a new record.  You can disable focusing a specific cell via the item’s Options.Focusing property.


TcxCustomGridTableController.DeleteSelection

TcxCustomGridTableController          See Also

Deletes selected records within the current view.

procedure DeleteSelection; virtual;

Description

If the view’s OptionsSelection.MultiSelect property is set to True, a grid view allows you to select multiple records.  These records can be accessed via the SelectedRecords collection (when GridMode is not used) and the view’s DataController.GetSelectedBookmark function (in GridMode applied to a data-aware view).

Use the DeleteSelection method to delete selected records.  You can refer to the Focused/Selected Records and Selecting Records sections for more information.


TcxCustomGridTableController.FindNextItem

TcxCustomGridTableController          See Also

Gets the index of the focusable item next/prior to the specified one.

function FindNextItem(AFocusedItemIndex: Integer; AGoForward, AGoOnCycle: Boolean; out ACycleChanged: Boolean; ARecord: TcxCustomGridRecord): Integer; virtual;

Description

A grid control allows you to prevent focusing a specific item by setting its Options.Focusing property to False.  Such non-focusable items are skipped during keyboard navigation (using the arrow keys).

You can use the FindNextItem method to locate the first focusable item next to or prior to the item specified by the AFocusedItemIndex parameter.  ARecord specifies the table record in which the search will be performed (can be nil for (banded) table views, should represent a specific card for card views).  The direction of the search is set by the AGoForward parameter.  FindNextItem does not change focus but returns the index of the item found.  If no item is found, -1 is returned.

If the AGoOnCycle parameter is False, a forward search will stop when reaching the last visible item and a backward search will stop when reaching the first visible view item.

If AGoOnCycle is True and AGoForward is True, the search for the focusable item will continue from the beginning when reaching the last visible item.  For a backward search, it will continue from the last item when reaching the first one.  On these actions the ACycleChanged parameter is set to True.  Otherwise, it is set to False.


TcxCustomGridTableController.FindNextRecord

TcxCustomGridTableController          See Also

Returns the position of the next or previous record.

function FindNextRecord(AFocusedRecordIndex: Integer; AGoForward, AGoOnCycle: Boolean; out ACycleChanged: Boolean): Integer;

Description

You can use the FindNextRecord method to get the index (visual position) of a record next to or prior to the record addressed by the AFocusedRecordIndex parameter.  This method is also used internally when a user navigates records using the keyboard Arrow keys.  To focus the next/previous record, see the FocusNextRecord method.

The direction of the search is defined by the AGoForward parameter.  If it is set to False, FindNextRecord locates the previous record.  If AGoForward is True, the index of the next record is returned.

FindNextRecord will cycle once it reaches the last record if you set the AGoOnCycle parameter to True.  In a forward search, the navigation will be continued from the first record when it reaches the last record.  Similarly, when searching backward, the FindNextRecord function returns the index of the last record if AFocusedRecordIndex addresses the first record.  By default the ACycleChanged argument is set to True.  Otherwise, it is set to False.


TcxCustomGridTableController.FocusFirstAvailableItem

TcxCustomGridTableController          See Also

Focuses the first focusable cell in the current record.

function FocusFirstAvailableItem: Boolean;

Description

The FocusFirstAvailableItem method focuses the first focusable cell (item) in the current record.  It returns True if such a cell was found.

You can prevent a specific item from being focused by setting its Options.Focusing property to False.


TcxCustomGridTableController.FocusNextCell

TcxCustomGridTableController          See Also

Focuses the cell/record next to or prior to the current one.

function FocusNextCell(AGoForward: Boolean; AProcessCellsOnly: Boolean = True; AAllowCellsCycle: Boolean = True): Boolean;

Description

You can use the FocusNextCell function to navigate through the cells within the current view.  The FocusNextCell function calls the FocusNextItem method to implement its functionality.

The AGoForward parameter specifies whether the next or previous cell is focused.

The AAllowCellsCycle parameter indicates whether the FocusNextCell function can move focus to the next/previous row after it passes the rightmost/leftmost cell within the current row and cell focus cycling is enabled (the view’s OptionsBehavior.FocusCellOnCycle property is set to True).  If this property is set to True and AGoForward is True, the FocusNextCell function moves focus to the next record when passing the last cell in the current record.  If AGoForward is set to False, the previous record is focused.

The AProcessCellsOnly parameter specifies the function’s behavior when cell selection is disabled (the view’s OptionsSelection.CellSelect property set to False).  In this case, navigation fails if the AProcessCellsOnly parameter is set to True or cell focus cycling is disabled (the view’s OptionsBehavior.FocusCellOnCycle property is set to False).  Otherwise, the next/previous record (depends on the AGoForward parameter’s value) is focused.

The FocusNextCell function returns True if the focusable cell (or record in case the cell selection is disabled) was found.  Otherwise, False is returned.


TcxCustomGridTableController.FocusNextItem

TcxCustomGridTableController          See Also

Focuses the cell next to or prior to the specified one.

function FocusNextItem(AFocusedItemIndex: Integer; AGoForward, AGoOnCycle, AGoToNextRecordOnCycle: Boolean): Boolean;

Description

You can use the FocusNextItem method to navigate cells (items) within the current view.

FocusNextItem moves focus to an item next to or prior to the one specified by the AFocusedItemIndex parameter.  If an item cannot be focused (its Options.Focusing property is set to False), it is skipped by the method.  The direction of the search is determined by the AGoForward parameter.

If the AGoOnCycle parameter is False, a forward search will stop when reaching the last visible item and a backward search will stop when reaching the first visible view item.

The FocusNextItem method will cycle once it reaches the last item If the AGoOnCycle parameter is True.  If AGoOnCycle is True and AGoForward is True, the search of the focusable item will continue from the first item when reaching the last visible item.  In a backward search, it will continue from the last item when reaching the first one.  On such actions, the focus remains in the current record if AGoToNextRecordOnCycle is set to False and moves to an adjacent record if AGoToNextRecordOnCycle is set to True.

The function of the AGoToNextRecordOnCycle parameter is equivalent to that of the view’s OptionsBehavior.FocusCellOnCycle property.

The FocusNextItem function returns True if the focusable cell was found.  Otherwise, False is returned.


TcxCustomGridTableController.FocusNextRecord

TcxCustomGridTableController          See Also

Moves focus to the next or previous record while preserving the existing selection.

function FocusNextRecord(AFocusedRecordIndex: Integer; AGoForward, AGoOnCycle, AGoIntoDetail, AGoOutOfDetail: Boolean): Boolean;

Description

You can use the FocusNextRecord method to navigate records within the current view.  The FocusNextRecord method is called internally when a user navigates a view using the keyboard arrow keys.  The method does not change the selection within the view.

FocusNextRecord moves focus relatively to the record identified by the AFocusedRecordIndex parameter.  If AGoForward is True, FocusNextRecord focuses the next record.  Otherwise, the previous record is focused.  If a new record was focused successfully, FocusNextRecord returns True.

The method will cycle once it reaches the last item if the AGoOnCycle parameter is True. A forward search, will be continued from the first record when it reaches the last record.  Similarly, when searching backward, the FocusNextRecord function returns the index of the last record if AFocusedRecordIndex addresses the first record.

To set focus to the first record, you can use the GoToFirst method.  The FocusNextRecord(-1, True, False, AGoIntoDetail, AGoOutOfDetail) also focuses the first record.  The FocusNextRecord(-1, False, True, AGoIntoDetail, AGoOutOfDetail) will set focus to the last record.  Use also the GoToLast method for this purpose.

Set the AGoIntoDetail parameter to True to enable moving focus from a master view to a detail view (the detail view must be expanded).  For instance, if the currently focused record is a master row, the following code focuses the first detail record.

//Delphi

var AGoOnCycle: Boolean;

//...

AGoOnCycle := ...;

with AView.Controller do

  FocusNextRecord(FocusedRecordIndex, True, AGoOnCycle, True, False);

//C++ Builder

bool AGoOnCycle = ...;

TcxCustomGridTableController * AController = AView->Controller;

AController->FocusNextRecord(AController->FocusedRecordIndex, true, AGoOnCycle, true, false);

Set the AGoOutOfDetail parameter to True to enable moving focus from the last record in a detail view to the master row which is next to the master row that corresponds to the detail view.


TcxCustomGridTableController.FocusNextRecordWithSelection

TcxCustomGridTableController          See Also

Moves focus to and selects the next or previous record.

function FocusNextRecordWithSelection(AFocusedRecordIndex: Integer; AGoForward, AGoOnCycle, AGoIntoDetail: Boolean; ASyncSelection: Boolean = True): Boolean;

Description

FocusNextRecordWithSelection is similar to the FocusNextRecord method.  See its description for more information on parameter values.

The ASyncSelection parameter is optional.  It specifies whether the selection should be preserved when moving focus.  When this parameter is omitted, it is considered to be True and this implies clearing the previous selection and synchronizing it with the focused record.  Set this parameter to False to preserve the selection when navigating.

The FocusNextRecordWithSelection method selects the record it focuses and this deselects all other records.  To enable multiple selected records, see the view’s OptionsSelection.MultiSelect property.


TcxCustomGridTableController.FocusRecord

TcxCustomGridTableController          See Also

Moves focus to and selects a particular record.

function FocusRecord(AFocusedRecordIndex: Integer; ASyncSelection: Boolean): Boolean;

Description

The FocusRecord function moves focus to the record identified by the AFocusedRecordIndex parameter.

Use the ASyncSelection parameter to specify whether the selection should be preserved when moving focus.  When this parameter’s value is equal to True the previous selection is cleared and it’s synchronized with the focused record.  Set the ASyncSelection parameter to False to preserve the selection when navigating.

The FocusRecord function returns True if the specified record was successfully focused.  Otherwise, False is returned.


TcxCustomGridTableController.GoToFirst

TcxCustomGridTableController          See Also

Moves focus to the first record (grouping row or data record) within the View.

function GoToFirst(ASyncSelection: Boolean = True): Boolean;

Description

The ASyncSelection parameter is optional.  If this parameter is omitted, it is considered to be True.  In this instance, this function clears the previous selection and synchronizes it with the first record.  Set this parameter to False if you need to preserve selection when moving focus.

On a successful focus move, the GoToFirst function returns True.


TcxCustomGridTableController.GoToLast

TcxCustomGridTableController          See Also

Moves focus to the last record (grouping row or data record) within the view.

function GoToLast(AGoIntoDetail: Boolean; ASyncSelection: Boolean = True): Boolean;

Description

If the last record designates a master row and it is expanded, you can set the AGoIntoDetail parameter to True to jump to the last record of its detail.  Otherwise, GoToLast will focus only the last record within the current View.

The ASyncSelection parameter is optional.  If this parameter is omitted, it is considered to be True.  In this instance, this function clears the previous selection and synchronizes it with the last record.  Set this parameter to False if you need to preserve selection when moving focus.

On a successful focus move, the GoToLast function returns True.


TcxCustomGridTableController.GoToNext

TcxCustomGridTableController          See Also

Moves focus to the record following the current one.

function GoToNext(AGoIntoDetail: Boolean; ASyncSelection: Boolean = True): Boolean;

Description

You can use the GoToNext method to focus the record following the currently active one.  The AGoIntoDetail parameter is in effect when GoToNext is applied to a master view.  If the current record is a master row (a TcxGridMasterDataRow object) and its detail is opened, the AGoIntoDetail parameter set to True makes a grid view move focus to the first detail record.  If AGoIntoDetail is False, focus is moved to the next master row following the current one.

If the view allows appending records (the OptionsData.Appending property is set to True), the GoToNext method appends a new record when the current record is the last one within the view.

The ASyncSelection parameter is optional.  It allows you to specify whether the selection should be preserved when moving focus.  If this parameter is omitted, it is considered to be True and this implies clearing the previous selection and synchronizing it with the focused record.  Set this parameter to False if you need to preserve the selection when navigating.

If the method was a success, it returns True.


TcxCustomGridTableController.GoToPrev

TcxCustomGridTableController          See Also

Moves focus to the record preceding the current one.

function GoToPrev(AGoIntoDetail: Boolean; ASyncSelection: Boolean = True): Boolean;

Description

You can use the GoToPrev method to focus the record preceding the currently active one.

The AGoIntoDetail parameter is in effect when GoToPrev is applied to a master view.  If the current record is a master row (a TcxGridMasterDataRow object) and the previous master row is expanded, then GoToPrev with the AGoIntoDetail parameter set to True makes a grid view move focus to the last detail record.  If AGoIntoDetail is False, focus is moved to the master row preceding the current one.

The ASyncSelection parameter is optional.  It allows you to specify whether the selection should be preserved when moving focus.  If this parameter is omitted, it is considered to be True and this implies clearing the previous selection and synchronizing it with the focused record.  Set this parameter to False if you need to preserve the selection when navigating.

If the method was a success, it returns True.


TcxCustomGridTableController.MakeFocusedItemVisible

TcxCustomGridTableController          See Also

Scrolls the view contents to make the focused item visible.

procedure MakeFocusedItemVisible;

Description

You can use the MakeFocusedItemVisible method to make the focused item (the FocusedItem property) visible.  The method scrolls the view until the item cell is entirely visible.

To make a specific item visible, see the MakeItemVisible method.  There are also other methods to scroll the view contents:

•	The Scroll method allows you to simulate user actions with scrollbars

•	The TopRecordIndex property specifies the index of the topmost visible record and this enables scrolling

•	The LeftPos property (available in (banded) table views) allows you scroll horizontally by a specific amount of pixels

These methods do not move focus when scrolling.  To move focus to a specific item and record, see the FocusNextItem, FocusNextRecord methods and TcxCustomGridTableItem.Focused , TcxCustomGridRecord.Focused properties, for instance.


TcxCustomGridTableController.MakeFocusedRecordVisible

TcxCustomGridTableController          See Also

Scrolls the view to make the focused record visible.

procedure MakeFocusedRecordVisible;

Description

Use the MakeFocusedRecordVisible method to scroll the view contents to make the focused record visible.  The focused record can be obtained from the FocusedRecord property.

To make a specific record visible, see the view’s MakeRecordVisible method.

There are also another methods to scroll the view contents:

•	The Scroll method allows you to simulate user actions with scrollbars

•	The TopRecordIndex property specifies the index of the topmost visible record and this enables scrolling

•	The LeftPos property (available in (banded) table views) allows you scroll horizontally by a specific amount of pixels

These methods do not move focus when scrolling.  To move focus to a specific item and record, see the FocusNextItem, FocusNextRecord methods and TcxCustomGridTableItem.Focused , TcxCustomGridRecord.Focused properties, for instance.


TcxCustomGridTableController.MakeItemVisible

TcxCustomGridTableController          See Also

Makes a specific item visible.

procedure MakeItemVisible(AItem: TcxCustomGridTableItem); virtual; abstract;

Description

In (banded) table views, when the OptionsView.ColumnAutoWidth property is set to False, the total column width can be greater than the width of a view window.  In this case, a horizontal scrollbar will appear thus enabling scrolling.  To make a specific column visible, call the MakeItemVisible method and pass a required column object as a parameter.  Columns can be obtained from the view’s Items collection.

In card views, MakeItemVisible just makes the currently focused record (card) visible.

The MakeFocusedItemVisible makes the focused item visible.

There are also another methods to scroll the view contents:

•	The Scroll method allows you to simulate user actions with scrollbars

•	The TopRecordIndex property specifies the index of the topmost visible record and this enables scrolling

•	The LeftPos property (available in (banded) table views) allows you scroll horizontally by a specific amount of pixels

These methods do not move focus when scrolling.  To move focus to a specific item and record, see the FocusNextItem, FocusNextRecord methods and TcxCustomGridTableItem.Focused , TcxCustomGridRecord.Focused properties, for instance.

In the following example, the tvCustomers view is scrolled, if needed, to make the tvCustomersCity column visible:

//Delphi

tvCustomers.Controller.MakeItemVisible(tvCustomersCity);

//C++ Builder

tvCustomers->Controller->MakeItemVisible(tvCustomersCity);


TcxCustomGridTableController.MakeRecordVisible

TcxCustomGridTableController          See Also

Makes a specific record visible.

procedure MakeRecordVisible(ARecord: TcxCustomGridRecord); virtual;

Description

The MakeRecordVisible method scrolls the view to make a record identified by the ARecord parameter visible.

Records displayed within the view can be accessed via the view’s ViewData.Records property.  Note that the view does not provide record objects for rows hidden within collapsed groups.

In GridMode, only a fixed amount of records is loaded into a memory buffer at a time.  Therefore, a view provides access only to these records via the ViewData.Records property.

Other methods to scroll the view contents are:

•	The Scroll method allows you to simulate user actions with scrollbars

•	The TopRecordIndex property specifies the index of the topmost visible record and this enables scrolling

•	The LeftPos property (available in (banded) table views) allows you scroll horizontally by a specific amount of pixels

These methods do not move focus when scrolling.  To move focus to a specific item and record, see the FocusNextItem, FocusNextRecord methods and TcxCustomGridTableItem.Focused , TcxCustomGridRecord.Focused properties, for instance.


TcxGridEditingController
TcxGridEditingController Object

Hierarchy          Properties          Methods          See Also

Editing controller for the current view.

Unit

cxGridCustomTableView

TcxGridEditingController = class(TObject)

Description

A grid control does not contain an editor object for every cell it displays.  It creates an editor object when a user is about to edit the selected cell.  A specific editor is created based on the assigned editor type or default settings.  To assign an editor to a column, use the RepositoryItem or PropertiesClass members.  Default editors are discussed in the FieldName (for bound mode) and TcxValueType (for unbound mode) topics.

TcxGridEditingController provides members to access a cell editor, open and close it.  To test whether an editor exists, see the IsEditing property.

The functionality of the editing controller can be accessed via the view’s Controller.EditingController property.


TcxGridEditingController Hierarchy
Hierarchy

TObject

     |


Properties for TcxGridEditingController
TcxGridEditingController Properties

TcxGridEditingController          Legend

In TcxGridEditingController

Edit

EditingItem

IsEditing


Methods for TcxGridEditingController
TcxGridEditingController Methods

TcxGridEditingController          Legend

In TcxGridEditingController

 HideEdit

 ShowEdit


TcxGridEditingController.Edit

TcxGridEditingController          See Also

Specifies an edit control used to edit the active cell.

property Edit: TcxCustomEdit;

Description

When a user is about to edit a cell within a view, a grid control creates an edit control of a specific type.  During editing, you can use the Edit property to access the cell editor.  To test whether an editor is accessible, see the IsEditing property.

A grid control enables you to specify the editor type for any item in a view and even define different editors for individual cells of a single item.  Please refer to the Data Editing Using Inplace Editors section for more details.

The Edit property returns an editor of a corresponding type based on the assigned editor type or default settings.  Default editors are discussed in the FieldName (for bound mode) and TcxValueType (for unbound mode) topics.

You can access various properties defining the appearance and behavior of an editor via its Properties member.  Changing any of these properties affects only the currently opened editor.  Changes will be discarded as soon as the editor is closed.

The following example assumes that an active cell is assigned an editor with a dropdown window (TcxCustomDropDownEdit descendant).  The DroppedDown property is used to open the popup window:

//Delphi

  with TcxCustomGridTableView(Grid.FocusedView).Controller.EditingController do

    if IsEditing then

      if Edit is TcxCustomDropDownEdit then

        TcxCustomDropDownEdit(Edit).DroppedDown := True;

//C++ Builder

  TcxGridEditingController * AEdController =
    ((TcxCustomGridTableView*)Grid->FocusedView)->
    Controller->EditingController;

  if (AEdController->IsEditing) {

    TcxCustomDropDownEdit * ADDEdit;

    if (ADDEdit = dynamic_cast<TcxCustomDropDownEdit *>(AEdController->Edit))

      ADDEdit->DroppedDown = true;

  }

ReadOnly Property


TcxGridEditingController.EditingItem

TcxGridEditingController          See Also

Specifies an item being edited in the focused record.

property EditingItem: TcxCustomGridTableItem;

Description

You can use the EditingItem property to specify an item (column in a (banded) table view and row in a card view) being edited in the focused record.  If EditingItem is NIL, no cell is being edited at the moment.  To open the editor programmatically, you can assign a specific view item to EditingItem.  For instance, the following code opens the editor for the tvOrdersDescription column of the focused record within the tvOrders view:

//Delphi

  tvOrders.Controller.EditingController.EditingItem := tvOrdersDescription;

//C++ Builder

  tvOrders->Controller->EditingController->EditingItem =
    tvOrdersDescription;

Another way to open the cell editor is to use the ShowEdit method.


TcxGridEditingController.IsEditing

TcxGridEditingController          See Also

Indicates whether a cell within the view is being edited.

property IsEditing: Boolean;

Description

You can use the IsEditing property to test whether an in-place editor is opened to edit the selected cell.  The editor can be accessed via the Edit property.  The item whose cell is being edited is specified by EditingItem.

ReadOnly Property


TcxGridEditingController.HideEdit

TcxGridEditingController          See Also

Closes an active in-place editor.

procedure HideEdit(Accept: Boolean); virtual;

Description

You can use the HideEdit method to close an active in-place editor being used for editing of the contents of the selected cell.  To know whether an editor is opened, see the IsEditing property.

The HideEdit method allows you to post and discard changes of the edit value.  To accept and post changes, set the Accept parameter to True.  In this case, the edit value is validated by the editor first and then posted to a dataset.  If the validation failed or the edit value cannot be stored by a data controller, an exception will occur.  If Accept is False, changes are discarded and an old value is restored.

To open an editor for a specific item, you can use the EditingItem property and ShowEdit method.


TcxGridEditingController.ShowEdit

TcxGridEditingController          See Also

Opens an editor for a specific item.

Overloaded Variants

procedure ShowEdit(AItem: TcxCustomGridTableItem = nil);

procedure ShowEdit(AItem: TcxCustomGridTableItem; Key: Char);

procedure ShowEdit(AItem: TcxCustomGridTableItem; Shift: TShiftState; X, Y: Integer);

Use the ShowEdit method to open an editor for the item specified by the AItem parameter.  ShowEdit opens an editor within the focused record provided that no other cell is being edited at the moment.

A cell editor can be activated in several ways:

-	a user focuses a cell and presses the Enter key.  The editor is opened and its contents are selected.

-	a user focuses a cell and presses any other key.  The editor is opened while replacing cell contents with this key.

-	If the view’s OptionsView.ShowEditButtons property is set to gsebForFocusedRecord, the editor will be opened immediately after clicking any cell in the currently focused record.  If ShowEditButtons is set to gsebAlways, clicking any cell within the view will immediately activate the editor.  This can be useful, for instance, if a cell is assigned an editor with buttons (dropdown editors).  You can click the button within the cell and this will activate the editor and open the dropdown window.

The three overloaded variants of the ShowEdit method enable you to simulate these methods of activating a cell editor.

procedure ShowEdit(AItem: TcxCustomGridTableItem = nil);

Description

Opens an editor for a given item within the focused record.  If AItem is NIL, the editor is opened for the currently focused item.

procedure ShowEdit(AItem: TcxCustomGridTableItem; Key: Char);

Description

Opens an editor for a given item within the focused record and passes it the key specified by the Key parameter.

procedure ShowEdit(AItem: TcxCustomGridTableItem; Shift: TShiftState; X, Y: Integer);

Description

Opens an editor for a specific item within the focused record.  This method is called internally when a user clicks a cell within a view.  The state of mouse buttons is defined by the Shift parameter.  X and Y identify the coordinates of the mouse relative to the top left corner of a grid view.


TcxGridDataController
TcxGridDataController Object

Hierarchy          Properties          Methods          Events          See Also

Represents a data controller.

Unit

cxGridCustomTableView

TcxGridDataController = class(TcxDataController, IcxCustomGridDataController, IcxGridDataController);

Description

A data controller mediates between the view and the underlying data store.  It handles requests between them and provides comprehensive data processing (grouping, sorting, filtering, and summaries calculation).

Use the view’s DataController property to get direct access to the data layer.

The TcxGridDataController is responsible for provider and unbound modes.

In provider mode, you need to create your own data source by deriving it from the TcxCustomDataSource class and by assigning its instance to the CustomDataSource property.  A data controller will retrieve data from or post data to the CustomDataSource by calling its methods internally.  You must override them in the subclass to supply a data controller with information on the custom data structure.

In contrast, for unbound mode, you have to populate a data controller’s cache record by record.  First, set the number of records via the RecordCount property.  Then each record value should be set manually using the Values property.

In bound mode, use the TcxDBGridDataController class instead.

Refer to the Data Loading Modes, Provider Mode and Unbound Mode sections for more information.


TcxGridDataController Hierarchy
Hierarchy

TPersistent

     |

TcxCustomDataController

     |

TcxDataController

     |


Properties for TcxGridDataController
TcxGridDataController Properties

TcxGridDataController          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 TcxGridDataController
TcxGridDataController Methods

TcxGridDataController          Legend

In TcxGridDataController

 AddItemToFilter

Derived from TcxCustomDataController

 Append

 AppendRecord

 BeginFullUpdate

 BeginUpdate

 BeginUpdateFields

 Cancel

 ChangeDetailExpanding

 ChangeRowSelection

 CheckFocusedSelected

 ClearBookmark

 ClearDetailLinkObject

 ClearDetails

 ClearSelection

 ClearSorting

 CollapseDetails

 DeleteFocused

 DeleteRecord

 DeleteSelection

 Edit

 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 TcxGridDataController
TcxGridDataController Events

TcxGridDataController          Legend

Derived from TcxCustomDataController

 OnAfterCancel

 OnAfterDelete

 OnAfterInsert

 OnAfterPost

 OnBeforeCancel

 OnBeforeDelete

 OnBeforeInsert

 OnBeforePost

 OnCompare

 OnDataChanged

 OnDetailCollapsed

 OnDetailCollapsing

 OnDetailExpanded

 OnDetailExpanding

 OnFilterRecord

 OnGroupingChanged

 OnNewRecord

 OnRecordChanged

 OnSortingChanged


TcxGridDataController.AddItemToFilter

TcxGridDataController

Adds a new filter condition for the specified item.

function AddItemToFilter(AParent: TcxFilterCriteriaItemList; AItem: TcxCustomGridTableItem; AOperatorKind: TcxFilterOperatorKind; const AValue: Variant; ADisplayText: string = ''; AReplaceExistent: Boolean = True): TcxFilterCriteriaItem;

Description

Use the AddItemToFilter method to add a new filter condition or replace the one already existing for the item referenced by the AItem parameter.  If the AReplaceExistent parameter is True, the new condition replaces the existing condition for this item.

A new condition is added to the list specified by the AParent parameter.  If this parameter is NIL, a new filter condition is inserted in the root list provided by the Filter.Root property.

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.


TcxCustomGridTableViewData
TcxCustomGridTableViewData Object

Hierarchy          Properties          Methods          See Also

Represents the base class which provides data from a data store as an array of records.

Unit

cxGridCustomTableView

TcxCustomGridTableViewData = class(TcxCustomGridViewData);

Description

The TcxCustomGridTableViewData class is a bridge between the data controller and the view’s data representation.  It adapts values provided by the data controller for displaying within a view.  The Records property provides the collection of records currently displayed within a view.  This collection references both data rows and group rows (in a table view).  If a record is hidden under a collapsed row, it is not accessible via the Records collection.  When you group data by column(s) or change the record order, the collection is recreated to reflect the current record arrangement.

Every record represents an object of the TcxCustomGridRecord class.  It provides the ability to get record values, display values as text, provide indexes (record indexes and record level).  Using properties of the TcxCustomGridRecord class, it is possible to focus, select a record and expand/collapse a record (the latter only for group and master records though).

There are several types of records derived from the TcxCustomGridRecord class: data row, master data row, new item row, group row, and card (in a card view).  For more information refer to the TcxCustomGridRecord class topic.

If the view contains a new item record (a new item row in a grid view), the NewItemRecord property refers to the corresponding record in the ViewData.

The view’s ViewData property allows you to access properties of the TcxCustomGridTableViewData class for this view.


TcxCustomGridTableViewData Hierarchy
Hierarchy

TObject

     |

TcxGridViewHandler

     |

TcxCustomGridViewData

     |


Properties for TcxCustomGridTableViewData
TcxCustomGridTableViewData Properties

TcxCustomGridTableViewData          Legend

In TcxCustomGridTableViewData

NewItemRecord

RecordCount

Records

Derived from TcxGridViewHandler

Control

Controller

DataController

GridView

ViewData


Methods for TcxCustomGridTableViewData
TcxCustomGridTableViewData Methods

TcxCustomGridTableViewData          Legend

In TcxCustomGridTableViewData

 AddItemToFilter

 Collapse

 Expand

 HasNewItemRecord

Derived from TcxGridViewHandler

 BeginUpdate

 Create

 EndUpdate


TcxCustomGridTableViewData.NewItemRecord

TcxCustomGridTableViewData          See Also

References a new item record in the view.

property NewItemRecord: TcxCustomGridRecord;

Description

The NewItemRecord property identifies a record used to enter new data in the view.  The NewItemRecord references a valid object if the HasNewItemRecord function returns True.  A new item record (row) is implemented only in a grid view and can be displayed via the OptionsView.NewItemRow property.

ReadOnly Property


TcxCustomGridTableViewData.RecordCount

TcxCustomGridTableViewData          See Also

Specifies the number of records in the current ViewData object.

property RecordCount: Integer;

Description

The RecordCount property returns the number of records presented by the current ViewData instance.  To obtain a record at a specific position use the Records property.

ReadOnly Property


TcxCustomGridTableViewData.Records

TcxCustomGridTableViewData          See Also

Specifies a collection of records presented in a ViewData.

property Records[Index: Integer]: TcxCustomGridRecord;

Description

The Records property supports a collection of records presented by the ViewData object.  The number of records is determined by the RecordCount property.

ReadOnly Property


TcxCustomGridTableViewData.AddItemToFilter

TcxCustomGridTableViewData

Adds a filter condition to a list of filter conditions.

function AddItemToFilter(AParent: TcxFilterCriteriaItemList; AItem: TcxCustomGridTableItem; AOperatorKind: TcxFilterOperatorKind; const AValue: Variant; ADisplayText: string = ''; AReplaceExistent: Boolean = True): TcxFilterCriteriaItem;

Description

The added filter condition can be used to filter values of AItem.

The AParent parameter specifies a list of criteria in the filter dropdown that the AValue filter condition is added to.  Note: to add a new filter condition to the root filter list (see the Filter.Root property), set the AParent parameter to nil.  The data is selected against filter items combined by a logical operator (if two or more of them are present).  To specify a logical operator, use the view’s DataController.Filter.Root.BoolOperatorKind property;

The AItem parameter specifies the item (a column or a row) whose values are to be filtered;

The AOperatorKind parameter specifies the type of relational operator (see the TcxFilterCriteriaItem.OperatorKind property);

The AValue parameter specifies the filter condition to be added to the list (see the TcxFilterCriteriaItem.Value property);

The ADisplayText parameter specifies the display text of the AValue filter condition in the filter status bar (see the TcxFilterCriteriaItem.DisplayValue property);

The AReplaceExistent parameter specifies whether to clear AParent before a new criterion is added.  Set the AReplaceExistent to True to remove existing filter items.  Otherwise, a new filter item will be added to the existing list.

The AddItemToFilter method returns a reference to the added filter item.


TcxCustomGridTableViewData.Collapse

TcxCustomGridTableViewData          See Also

Collapses all records within the current view recursively.

procedure Collapse(ARecurse: Boolean);

Description

Use the Collapse method to collapse all rows within the view.  Only master rows, group rows and cards (TcxGridMasterDataRow, TcxGridGroupRow and TcxGridCard) implement the collapse/expand operations.

The Collpase method applied to a master view enables you to collapse all records within corresponding detail views.  To do this, set the ARecurse parameter to True.  If ARecurse is False, only rows within a master view are affected.

A detail view will have instances created ("clones") for each visible detail.  To collapse rows within all open details of a particular view, you need to iterate through all clones and call their Collapse methods.  Refer to the Data Representation topic for information on view clones.  The following code performs a recursive collapse of rows within all instances of the detail tvOrders view:

//Delphi

var

  I: Integer;

//...

  with tvOrders do

    for I := 0 to CloneCount - 1 do

      TcxGridTableView(Clones[I]).ViewData.Collapse(True);

//C++ Builder

  for(int i = 0; i < tvOrders->CloneCount; i++)

    ((TcxGridTableView*)tvOrders->Clones[i])->
      ViewData->Collapse(true);


TcxCustomGridTableViewData.Expand

TcxCustomGridTableViewData          See Also

Expands all records within the current view recursively.

procedure Expand(ARecurse: Boolean);

Description

The Expand method performs a recursive expansion of all records within the current view.

The ARecurse parameter is in effect only when the Expand method is applied to a master view in a master-detail relationship.  It specifies whether rows of a detail view are also recursively expanded after expanding rows of the master view.

The collapse/expand operations are implemented only by master rows, group rows and cards (TcxGridMasterDataRow, TcxGridGroupRow and TcxGridCard respectively).


TcxCustomGridTableViewData.HasNewItemRecord

TcxCustomGridTableViewData          See Also

Specifies whether the view has the "new item record".

function HasNewItemRecord: Boolean; virtual;

Description

The HasNewItemRecord function returns True if the view contains the "new item record" ("new item row" in a grid view) enabling a user to enter new data.  The new item record is implemented only in a grid view and can be displayed via the OptionsView.NewItemRow property.  The record corresponding to the "new item row" is retrieved by the NewItemRecord property.


TcxCustomGridTableBackgroundBitmaps
TcxCustomGridTableBackgroundBitmaps Object

Hierarchy          Properties

Serves as the base for classes providing background bitmaps for elements of grid views that display data in tabular form (by means of cells).

Unit

cxGridCustomTableView

TcxCustomGridTableBackgroundBitmaps = class(TcxCustomGridBackgroundBitmaps)

Description

The TcxCustomGridTableBackgroundBitmaps class extends the functionality of the TcxCustomGridBackgroundBitmaps object.  It introduces a single property to specify the background bitmap for elements displaying data – data cells.  Please refer to the Content property description for details.

The TcxCustomGridTableBackgroundBitmaps class is the direct ancestor of classes providing background images for elements of views displaying data by means of cells.  These descendants can be accessed via the BackgroundBitmaps property of objects representing views.

You have no need to create objects of the TcxCustomGridTableBackgroundBitmaps class in applications.  Appropriate descendants are automatically created by views when they initialize their Bitmaps property.


TcxCustomGridTableBackgroundBitmaps Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |

TcxCustomGridBackgroundBitmaps

     |


Properties for TcxCustomGridTableBackgroundBitmaps
TcxCustomGridTableBackgroundBitmaps Properties

TcxCustomGridTableBackgroundBitmaps          Legend

In TcxCustomGridTableBackgroundBitmaps

Content

FilterBox

Derived from TcxCustomGridBackgroundBitmaps

Background

Values


TcxCustomGridTableBackgroundBitmaps.Content

TcxCustomGridTableBackgroundBitmaps

Specifies the background bitmap for a grid view content.

property Content: TBitmap;

Description

The Content property allows you to set the background bitmap for grid views cells.  See the image below for an example.


TcxCustomGridTableBackgroundBitmaps.FilterBox

TcxCustomGridTableBackgroundBitmaps

Specifies the background bitmap for the filter box.

property FilterBox: TBitmap;

Description

Use the FilterBox property to specify an image for the filter panel.   The image below shows an example.


TcxGridRecordHitTest
TcxGridRecordHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the grid record which is located at the point being tested.

Unit

cxGridCustomTableView

TcxGridRecordHitTest = class(TcxCustomGridViewHitTest)

Description

The TcxGridRecordHitTest class provides general information on the grid view record (a card of the card view or row of the table view) which is located at the grid view’s point that is being tested.  The GridRecord property provides access to the properties and methods of the grid record being inspected.  The TcxGridRecordHitTest class introduces the CanClick function which determines whether the inspected grid record can initiate record management operations (such as drag-and-drop, focusing and selection) and also designates the hit code (which is equal to htRecord) of the grid record.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridRecordHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |


Properties for TcxGridRecordHitTest
TcxGridRecordHitTest Properties

TcxGridRecordHitTest          Legend

In TcxGridRecordHitTest

GridRecord

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridRecordHitTest
TcxGridRecordHitTest Methods

TcxGridRecordHitTest          Legend

In TcxGridRecordHitTest

CanClick

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridRecordHitTest.GridRecord

TcxGridRecordHitTest

Provides access to the grid record being inspected.

property GridRecord: TcxCustomGridRecord;

Description

Use the GridRecord property to access the properties and method of the grid record being inspected.


TcxGridRecordHitTest.CanClick

TcxGridRecordHitTest

Determines whether a click on the inspected grid record can initiate record management operations.

class function CanClick: Boolean; virtual;

Description

When a click on the inspected grid element can initiate record management operations (such as drag-and-drop, focusing and selection) the CanClick function returns True.  Otherwise, False is returned.

The CanClick function returns True for grid records by default.  TcxGridRecordHitTest descendants override the CanClick function to provide return values specific to the grid elements which they’re associated with.


TcxGridRecordCellHitTest
TcxGridRecordCellHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the cell which is located at the point being tested.

Unit

cxGridCustomTableView

TcxGridRecordCellHitTest = class(TcxGridRecordHitTest)

Description

The TcxGridRecordCellHitTest class designates the hit code (which is equal to htCell) of the cell located at the grid view’s point that is being tested and also provides general information on the cell.  The Item and GridRecord properties provide access to the properties and methods of the grid item and record which correspond to the cell being inspected, respectively.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridRecordCellHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxGridRecordHitTest

     |


Properties for TcxGridRecordCellHitTest
TcxGridRecordCellHitTest Properties

TcxGridRecordCellHitTest          Legend

In TcxGridRecordCellHitTest

Item

Derived from TcxGridRecordHitTest

GridRecord

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridRecordCellHitTest
TcxGridRecordCellHitTest Methods

TcxGridRecordCellHitTest          Legend

Derived from TcxGridRecordHitTest

CanClick

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridRecordCellHitTest.Item

TcxGridRecordCellHitTest

Provides access to the grid item which corresponds to the inspected cell.

Item: TcxCustomGridTableItem;

Description

Use the Item field to access the properties and methods of the grid item (a column in the Table View or a row in the Card View) which corresponds to the cell that is located at the grid view’s point being tested.


TcxCustomGridTableItem
TcxCustomGridTableItem Object

Hierarchy          Properties          Methods          Events          See Also

Represents a table item for a tabular data representation.

Unit

cxGridCustomTableView

TcxCustomGridTableItem = class(TComponent, IcxEditRepositoryItemListener)

Description

The TcxCustomGridTableItem encapsulates the concept of a table item within a grid control.  In terms of databases, an item stands for a data table column (field) from which a database is composed.  Items are interpreted as columns in the TcxGridColumn class and as rows in card views (the TcxGridCardViewRow class).

A grid control allows you to display data using several views.  The TcxCustomGridTableView class provides the Items property which supports a collection of items represented in a tabular form by a table view.  Descendants of the TcxCustomGridTableView class arrange items in different ways thus forming appropriate data presentations.  In a table view (TcxGridTableView), table items are displayed horizontally, while in a card view (TcxGridCardView), they are displayed vertically.

An item has a number of attributes and options which control its appearance and operation (grouping, filtering, sorting, moving, editing).  A view containing the item also has options which affect the item's behavior.

An item retrieves data from and posts it to a storage with the help of a DataBinding object.  You can use the DataBinding properties to define filter criteria, associate an arbitrary value (DataBinding.Data) with an item and perform other operations.

To assign an editor to an item, you can use either the mechanism of a repository and repository items or the PropertiesClass and Properties objects.

The TcxCustomGridTableItem class provides the base functionality for TcxGridCardViewRow and TcxGridColumn.


TcxCustomGridTableItem Hierarchy
Hierarchy

TComponent

     |


Properties for TcxCustomGridTableItem
TcxCustomGridTableItem Properties

TcxCustomGridTableItem          Legend

In TcxCustomGridTableItem

ActuallyVisible

AlternateCaption

BestFitMaxWidth

Caption

DataBinding

DateTimeGrouping

Editing

EditValue

Filtered

FilteringDateRanges

Focused

GridView

GroupIndex

GroupingDateRanges

HeaderAlignmentHorz

HeaderAlignmentVert

Hidden

ID

IncSearching

Index

IsFirst

IsLast

MinWidth

Options

Properties

PropertiesClass

RepositoryItem

SortIndex

SortOrder

Styles

Visible

VisibleForCustomization

VisibleIndex

Width


Methods for TcxCustomGridTableItem
TcxCustomGridTableItem Methods

TcxCustomGridTableItem          Legend

In TcxCustomGridTableItem

 ApplyBestFit

 FocusWithSelection

 GetAlternateCaption

 GetProperties

 GetRepositoryItem

 MakeVisible

 RestoreDefaults


Events for TcxCustomGridTableItem
TcxCustomGridTableItem Events

TcxCustomGridTableItem          Legend

In TcxCustomGridTableItem

 OnCustomDrawCell

 OnGetCellHint

 OnGetDataText

 OnGetDisplayText

 OnGetFilterDisplayText

 OnGetFilterValues

 OnGetProperties

 OnGetStoredProperties

 OnGetStoredPropertyValue

 OnInitFilteringDateRanges

 OnInitGroupingDateRanges

 OnSetStoredPropertyValue

 OnUserFiltering


TcxCustomGridTableItem.ActuallyVisible

TcxCustomGridTableItem          See Also

Specifies whether an item can be displayed.

property ActuallyVisible: Boolean;

Description

The ActuallyVisible property returns the visibility status of an item taking into account other properties which may affect the item’s visibility.  By default, ActuallyVisible returns the Visible property value.

In a banded table view a column can only be displayed if it is assigned to a visible band.

ReadOnly Property


TcxCustomGridTableItem.AlternateCaption

TcxCustomGridTableItem          See Also

Specifies an alternative caption for the currently processed item.

property AlternateCaption: string;

Description

Use the AlternateCaption property to change the caption specified by the Caption property with a different value in dialog boxes – including the Filter Builder dialog (in the drop-down list), Custom Filter dialog (as the field’s label), Filter Panel (a caption in a filter criteria), Customization Form , Quick Customization dropdown and Group By Box (the dropped column header’s caption).


TcxCustomGridTableItem.BestFitMaxWidth

TcxCustomGridTableItem          See Also

Specifies the maximum value of the best fit width for the item (column).

property BestFitMaxWidth: Integer;

Description

The BestFitMaxWidth property limits the maximum width of the item (column), its width is set when the ApplyBestFit procedure is used.  A value of 0 indicates that any width calculated by the ApplyBestFit procedure will be set as the new item’s width.

The default value of the BestFitMaxWidth property is 0.


TcxCustomGridTableItem.Caption

TcxCustomGridTableItem          See Also

Specifies the caption for the current table item.

property Caption: string;

Description

The Caption property describes data provided by the current table item.  Item captions are displayed within the table view’s column header panel or within the card view’s caption column.


TcxCustomGridTableItem.DataBinding

TcxCustomGridTableItem

Represents an object linking the current item to data storage.

property DataBinding: TcxGridItemDataBinding;

Description

The DataBinding property implements data retrieval and posting to data storage.  You can use the DataBinding properties to access the filter criteria set for a view, specify the dataset field to which the item is connected (for a view linked to a dataset) and perform other operations.  The Data attribute of a DataBinding object allows you to associate arbitrary data with the item.

At design time, you can select a data type for a non data-aware view item from its DataBinding.ValueType property which is represented by a list of the available data types.


TcxCustomGridTableItem.DateTimeGrouping

TcxCustomGridTableItem          See Also

Specifies a date/time grouping option, which determines time periods to be used as grouping values in group rows.

type

  TcxGridDateTimeGrouping = (dtgDefault, dtgByDateAndTime, dtgRelativeToToday, dtgByHour, dtgByDate, dtgByMonth, dtgByYear);

property DateTimeGrouping: TcxGridDateTimeGrouping;

Description

Refer to the description of the TcxGridDateTimeGrouping type to learn about available date/time grouping options.

To specify a date/time grouping option for all View items, use the View’s DateTimeHandling.Grouping property.

Note:	The DateTimeGrouping property overrides this property.  A value of dtgDefault indicates that item values are grouped by time periods as specified by the View’s DateTimeHandling.Grouping property.

The default value of the DateTimeGrouping property is dtgDefault.


TcxCustomGridTableItem.Editing

TcxCustomGridTableItem          See Also

Specifies whether the current item is in edit mode.

property Editing: Boolean;

Description

The Editing property specifies the edit status of the item.  If Editing is True, the cell corresponding to the item in the current row is in edit mode.  You can prevent a user from setting an item to edit mode in a number of ways:

•	set the Editing and/or Focusing attribute of the item’s Options object to False;

•	set Editing of the view’s OptionsData property (TcxGridTableView.OptionsData or TcxGridCardView.OptionsData) to False;

•	set CellSelect of the view’s OptionsSelection property to False.


TcxCustomGridTableItem.EditValue

TcxCustomGridTableItem          See Also

Specifies the value stored in the item’s cell in the currently focused record.

property EditValue: Variant;

Description

Use the EditValue property to work with a cell value.  Edit values for a cell can be retrieved only for the items contained within non-pattern views (the TcxCustomGridView.IsPattern property is False).


TcxCustomGridTableItem.Filtered

TcxCustomGridTableItem          See Also

Specifies whether filter criteria are set for the current item (column).

property Filtered: Boolean;

Description

The Filtered property returns True if any filter conditions were set for the current item (column).  Otherwise, the Filtered property returns False.  You can clear the existing filter conditions by assigning Filtered to False.

To set filter criteria for an item, you can use either the item’s DataBinding.Filter property or the view’s DataController.Filter property.


TcxCustomGridTableItem.FilteringDateRanges

TcxCustomGridTableItem          See Also

Provides access to the item’s collection of filter date ranges.

property FilteringDateRanges: TcxGridFilteringDateRanges;

Description

Refer to the description of the TcxGridFilteringDateRanges class for additional information on this collection.

Use the OnInitFilteringDateRanges event to customize this collection.

ReadOnly Property


TcxCustomGridTableItem.Focused

TcxCustomGridTableItem          See Also

Specifies whether the cell is focused.

property Focused: Boolean;

Description

The Focused property returns True if the cell corresponding to the item in the current record is focused.  Otherwise, Focused returns False.

You can prevent items from being focused in a number of ways:

•	set the Options.Focusing property to False

•	set OptionsSelection.CellSelect of a view to False


TcxCustomGridTableItem.GridView

TcxCustomGridTableItem

Returns a view containing the current item.

property GridView: TcxCustomGridTableView;

Description

Use the GridView property to return a view which contains the current item.  The view derived from the TcxCustomGridTableView class has a collection of items supported by the Items property.

ReadOnly Property


TcxCustomGridTableItem.GroupIndex

TcxCustomGridTableItem          See Also

Specifies the group index of the item (column).

property GroupIndex: Integer;

Description

Grouping is only implemented in table and banded table views.  Use the GroupIndex property to group data by the view’s current column.  If GroupIndex is set to –1, then data is not grouped by the column.  Otherwise, GroupIndex specifies the position of the column amongst the other group columns.

To control the visibility state of an item (column) within a view, use the column’s Visible property.

To prevent an end-user from grouping/ungrouping data by the column,

•	set the column’s Options.Grouping property to False

•	set the view’s OptionsCustomize.ItemGrouping property (OptionsCustomize.ColumnGrouping in a table view) to False

The TcxDataControllerGroups class implements grouping operations on data in a data controller.  You can address a specific group by the index of the row it contains and then get the summary values calculated against this group via TcxDataSummary.GroupSummaryValues, for instance.  You can access TcxDataControllerGroups class functionality via the view’s DataController.Groups object.

The default value of the GroupIndex property is –1.


TcxCustomGridTableItem.GroupingDateRanges

TcxCustomGridTableItem          See Also

Provides access to the item’s collection of grouping date ranges.

property GroupingDateRanges: TcxGridGroupingDateRanges;

Description

Use the OnInitGroupingDateRanges event to customize this collection.

ReadOnly Property


TcxCustomGridTableItem.HeaderAlignmentHorz

TcxCustomGridTableItem          See Also

Defines the horizontal alignment of the item caption.

property HeaderAlignmentHorz: TAlignment;

Description

Use the HeaderAlignmentHorz property to define the horizontal alignment of the item caption.  You can align the text to the left, right or center it.

The item caption identified by the Caption member is displayed within the column header panel in a table view and within a caption column in a card view.


TcxCustomGridTableItem.HeaderAlignmentVert

TcxCustomGridTableItem          See Also

Specifies the vertical alignment of the item caption.

type

  TcxAlignmentVert = (vaTop, vaBottom, vaCenter);

property HeaderAlignmentVert: TcxAlignmentVert;

Description

The HeaderAlignmentVert property specifies the vertical alignment of the item caption.  The TcxAlignmentVert type enumerates values for setting the vertical alignment.

Value	Meaning
vaTop	Text is aligned to the top.
vaBottom	Text is aligned to the bottom.
vaCenter	Text is centered vertically.

You can see the effect of vertical alignment when setting different size fonts for item captions.

The item caption is defined by the Caption property.


TcxCustomGridTableItem.Hidden

TcxCustomGridTableItem          See Also

Specifies whether the item can be displayed within the Customization form.

property Hidden: Boolean;

Description

Note: this property is obsolete.  Use the VisibleForCustomization property instead.

Items in a grid view, whose TcxCustomGridTableItem.Visible property is False, are displayed in the view’s Customization form.  To activate the Customization form, you can set the view’s TcxCustomGridTableController.Customization property to True.  By setting the item’s Hidden property to True you can prevent it from appearing in the Customization form.  In this case, if the column or row is dragged to the Customization form, it disappears completely and can only be made visible programmatically.  The TcxCustomGridTableOptionsCustomize.ItemHiding property specifies the manner in which an end-user can remove an item from a view by dragging it off the column header panel or card.


TcxCustomGridTableItem.ID

TcxCustomGridTableItem          See Also

Specifies the unique identifier assigned to an item.

property ID: Integer;

Description

Items in a view can be distinguished by their IDs.  IDs provide the unique identity of the items within the view.  When an item is deleted, a newly created item might get the ID of the deleted item.  Thus the IDs of items won't be reused within the current state of the view, but may be reused within the lifetime of the view.  This is a limit unique to these IDs.

You can get an item by its ID by calling the TcxCustomGridTableView.FindItemByID method.

ReadOnly Property


TcxCustomGridTableItem.IncSearching

TcxCustomGridTableItem          See Also

Indicates whether an incremental search is currently in progress on the current item.

property IncSearching: Boolean;

Description

If an end-user is currently performing an incremental search on the current item, the IncSearching property returns True.  Otherwise, IncSearching is False.

ReadOnly Property


TcxCustomGridTableItem.Index

TcxCustomGridTableItem          See Also

Specifies the position of the item within the view’s item collection.

property Index: Integer;

Description

A view (a TcxCustomGridTableView descendant) provides the Items property which supports a collection of all the items contained within a view.  The Index property defines the position of the item within the collection.  You can access the items whose data is displayed in a view via the view’s VisibleItems collection.  The position of the item in this collection is defined by the VisibleIndex property.


TcxCustomGridTableItem.IsFirst

TcxCustomGridTableItem          See Also

Specifies whether the item is the first within the collection of visible items.

property IsFirst: Boolean;

Description

The IsFirst property returns True if the item is the first within the visible item collection.  Otherwise, False is returned.  You can determine the position of the item within the collection via the VisibleIndex property.

ReadOnly Property


TcxCustomGridTableItem.IsLast

TcxCustomGridTableItem          See Also

Specifies whether the item is the last within the collection of visible items.

property IsLast: Boolean;

Description

Use the IsLast property to determine whether the item is the last within the visible item collection.  Items are displayed according to their visible indexes within a view.  See the VisibleIndex member to define the visible index of the item.

ReadOnly Property


TcxCustomGridTableItem.MinWidth

TcxCustomGridTableItem          See Also

Specifies the minimum width of the cell wherein item data is displayed.

property MinWidth: Integer;

Description

The MinWidth property defines the minimum width of an item cell.  To set the item cell's width, use the Width property.  Note that the item width can be specified only for table and banded table views.

The default value of the MinWidth property is cxGridItemDefaultMinWidth.


TcxCustomGridTableItem.Options

TcxCustomGridTableItem

Contains a set of options controlling the user’s ability to change the item’s contents and the appearance of item cells.

property Options: TcxCustomGridTableItemOptions;

Description

The Options object contains a number of attributes which allow or disallow various operations to be performed by an end user on an item at runtime.  These operations include:

-	editing the item's data;

-	focusing the item;

-	grouping by the item;

-	resizing and moving the item;

-	sorting data by the item.

and others.

Descendants of the TcxCustomGridTableItem class publish the necessary options and declare other attributes specific to them.

You can use the OptionsCustomize, OptionsSelection and OptionsView properties of a view to define different options that are common to all the items within a view.


TcxCustomGridTableItem.Properties

TcxCustomGridTableItem          See Also

Specifies the properties of the editor available for editing item data.

property Properties: TcxCustomEditProperties;

Description

You can assign a particular editor to edit the contents of item cells in two ways.  The first is to set the PropertiesClass member.  The second is to assign a repository item to the RepositoryItem property.  If an editor is assigned via RepositoryItem, the values of the Properties and PropertiesClass members are ignored.

Assigning PropertiesClass results in creating a Properties object with settings specific to the corresponding editor.  Do not create Properties directly.  Use PropertiesClass instead.  The Properties object allows you to adjust editor properties once created.

At design time, you can select an editor for the item from the dropdown list invoked via the Properties item in the Object Inspector.


TcxCustomGridTableItem.PropertiesClass

TcxCustomGridTableItem          See Also

Specifies the class of the editor used to edit item data.

type

  TcxCustomEditPropertiesClass = class of TcxCustomEditProperties;

property PropertiesClass: TcxCustomEditPropertiesClass;

Description

Use the PropertiesClass member to assign a particular editor to edit item cell data.  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 the available editor settings.

The following code shows how to specify the BLOB editor to edit the cxGrid1DBTableView1Graph1 item data.  Its type is set to bekPict to enable displaying graphics via the editor.

//Delphi

  cxGrid1DBTableView1Graph1.PropertiesClass := TcxBLOBEditProperties;

  TcxBLOBEditProperties(cxGrid1DBTableView1Graph1.Properties).BlobEditKind := bekPict;

The RepositoryItem property also allows you to assign an editor to the item.  If an editor is assigned via RepositoryItem, 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 this item.


TcxCustomGridTableItem.RepositoryItem

TcxCustomGridTableItem          See Also

Specifies the repository item for an editor.

property RepositoryItem: TcxEditRepositoryItem;

Description

A repository item refers to the editor used to edit item data.  If you set an editor for an item via RepositoryItem, the values of Properties and PropertiesClass are ignored.  Working with a repository and creating repository items is discussed in the repository and 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 to this item.


TcxCustomGridTableItem.SortIndex

TcxCustomGridTableItem          See Also

Represents the index of the current item among sorted items within the current view.

property SortIndex: Integer;

Description

Use the SortIndex property to determine the current item’s position among the sorted items of the current view.  The sorting order for an item is defined via the Item.SortOrder property.  In order to clear sorting by a specific item’s values, set this property to soNone.

ReadOnly Property


TcxCustomGridTableItem.SortOrder

TcxCustomGridTableItem          See Also

Defines the sort order for the item.

type

  TcxDataSortOrder = (soNone, soAscending, soDescending);

  TcxGridSortOrder = TcxDataSortOrder;

property SortOrder: TcxGridSortOrder;

Description

You can define the sort order for the item by assigning the SortOrder member to one of the TcxGridSortOrder values.  You can sort in ascending, descending order or clear the sorting by the item.

A grid control enables you to sort data by multiple columns.  Sorting is performed in the same sequence as when the SortOrder member is assigned to items.  You can clear the current sorting by the DataController.ClearSorting method.

The default value of the SortOrder property is soNone.


TcxCustomGridTableItem.Styles

TcxCustomGridTableItem          See Also

Defines a set of styles for different item elements.

property Styles: TcxCustomGridTableItemStyles;

Description

The Styles property lets you set the style for individual item elements.  Descendants of the TcxCustomGridTableItem class declare additional attributes of a Styles object.


TcxCustomGridTableItem.Visible

TcxCustomGridTableItem          See Also

Specifies whether the item is displayed within a view.

property Visible: Boolean;

Description

If the Visible property is set to True, a view containing the item displays item data; otherwise, the item is hidden.  The item’s visibility does not affect grouping by this item.  You can group by the item even if Visible is set to False.

The collection of visible items is provided by the view’s VisibleItems property.  See the VisibleIndex attribute of an item to determine the position of this item within the collection.

Items in a grid view, whose Visible attribute is False, are displayed in the Customization form.  To activate the Customization form, you can set the view’s TcxCustomGridTableController.Customization property to True.  It is possible to prevent a column's appearance in the Customization form via the TcxCustomGridTableItem.VisibleForCustomization member.


TcxCustomGridTableItem.VisibleForCustomization

TcxCustomGridTableItem

Specifies whether an item is shown in the Customization Form when moved into it.

property VisibleForCustomization: Boolean;

Description

The Customization Form is visible onscreen if the view’s Controller.Customization property is set to True.

To move an item (a row or a column) into the Customization Form, set the item’s Visible property to False.  Once it’s in the Customization Form, the item is hidden in a View.  If the VisibleForCustomization property’s value is False, the item is also invisible in the Customization Form.  As such, it’s unavailable to the end-user.

An end-user can remove an item from a View by dragging its header into the Customization Form.  The View’s OptionsCustomize.ItemHiding property specifies the manner in which items can be hidden.


TcxCustomGridTableItem.VisibleIndex

TcxCustomGridTableItem          See Also

Specifies the position of an item within the collection of items.

property VisibleIndex: Integer;

Description

The collection of items displayed within a view is determined by the TcxCustomGridTableView.VisibleItems property.  VisibleIndex defines the position of an item within this collection.  Visible indexes specify the order in which items are displayed within a view.

ReadOnly Property


TcxCustomGridTableItem.Width

TcxCustomGridTableItem          See Also

Determines the width of the cell where the item data is displayed.

property Width: Integer;

Description

Use the Width property to set the width of the cell where the item data is displayed.  You cannot set the item width to a value less than that defined by the MinWidth property.  Note that the item width can be specified only for table and banded table views.


TcxCustomGridTableItem.ApplyBestFit

TcxCustomGridTableItem         See Also

Adjusts the width of the item according to the contents of item cells.

procedure ApplyBestFit(ACheckSizingAbility: Boolean = False; AFireEvents: Boolean = False); virtual;

Description

Use the ApplyBestFit method to adjust the width of an item (column) in order to display the full contents of all item cells.  The ACheckSizingAbility parameter specifies whether it’s necessary to check if the current item can be resized prior to adjusting its width.  Set the ACheckSizingAbility parameter to True to specify that the width of the current item can only be adjusted if resizing is permitted, i.e. no restrictive options are set.  Otherwise, the current item’s width can always be adjusted.

Set the AFireEvents parameter to True to specify that the events providing notifications about changes to the item’s width (such as the OnColumnSizeChanged event) should be fired.

The ApplyBestFit method iterates through records and calculates the maximum width of the field corresponding to the current item.  If the calculated maximum width does not exceed the BestFitMaxWidth property's value it is then assigned to the item’s Width property.  The number of records processed is determined by the BestFitMaxRecordCount property (this can improve performance for large datasets).

Note:	ApplyBestFit takes the width of the item’s caption specified by the Caption property into account.

It is possible to adjust the column's width in a grid table view (TcxGridTableView) by double-clicking the column’s right edge.  You can prevent an end-user from changing the column's width either by setting the column’s Options.HorzSizing or the view’s OptionsCustomize.ColumnHorzSizing properties to False.

A view also provides the ApplyBestFit method which can be used to adjust the widths of all columns in a view.  This method simply calls the ApplyBestFit method for all view columns.


TcxCustomGridTableItem.FocusWithSelection

TcxCustomGridTableItem

Selects the currently processed item.

procedure FocusWithSelection; virtual;

Description

To provide custom logic for this operation, the FocusWithSelection method can be overridden in subclasses.


TcxCustomGridTableItem.GetAlternateCaption

TcxCustomGridTableItem

Returns a string that represents an alternative caption for the currently processed item.

function GetAlternateCaption: string;

Description

The GetAlternateCaption method retrieves the caption specified by the AlternateCaption property. If the AlternateCaption property contains an empty string, the Caption property value will be returned.


TcxCustomGridTableItem.GetProperties

TcxCustomGridTableItem          See Also

Returns the properties of an editor used to edit the values of the current item.

Overloaded Variants

function GetProperties: TcxCustomEditProperties; overload;

function GetProperties(ARecord: TcxCustomGridRecord): TcxCustomEditProperties; overload;

Description

The GetProperties method returns the properties of the editor used to edit the values of the current item.  You can use the object returned by the GetProperties method to adjust specific settings of the item’s editor.  For instance, if the item uses a currency editor, GetProperties returns an object of the TcxCurrencyEditProperties class.  It provides properties such as DisplayFormat, DecimalPlaces, MaxValue, MinValue etc.

By default, an item is assigned a specific editor based on the DataBinding.ValueTypeClass value (in unbound mode) and the field type (in bound mode).  Please refer to the FieldName property and the TcxValueType class topic for details.

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.  See the corresponding topics for more details.

The GetProperties method returns editor properties regardless of whether the default or an explicitly assigned editor is used.

The OnGetProperties event allows you to specify different editors for individual cells of the current item.  In this instance, you should call the second overloaded method to ascertain the actual item editor being used for a particular record.


TcxCustomGridTableItem.GetRepositoryItem

TcxCustomGridTableItem

Returns a reference to the assigned repository item.

function GetRepositoryItem: TcxEditRepositoryItem;

Description

The GetRepositoryItem method returns a reference to a repository item specified through the RepositoryItem property.  If no repository item is specified, the default repository item (based upon associated data item type) will be assigned.


TcxCustomGridTableItem.MakeVisible

TcxCustomGridTableItem

Scrolls the view’s content to bring the currently processed item into view.

procedure MakeVisible;

Description

If the currently processed item is beyond the view’s boundaries, use the MakeVisible method to show this item in the view.


TcxCustomGridTableItem.RestoreDefaults

TcxCustomGridTableItem          See Also

Restores the item’s Caption and Width properties to their default values.

procedure RestoreDefaults; virtual;

Description

The method restores the default values of the item’s Caption and Width properties.  For data-aware items connected to a dataset, the default values are defined by corresponding dataset field attributes.  For non data-aware items, the method sets Width to 64 (the default value) and the Caption property to an empty string.


TcxCustomGridTableItem.OnCustomDrawCell

TcxCustomGridTableItem          See Also

Occurs when a table cell or a card cell needs to be painted.

type

  TcxGridTableDataCellCustomDrawEvent = procedure(Sender: TcxCustomGridTableView; ACanvas: TcxCanvas; AViewInfo: TcxGridTableDataCellViewInfo; var ADone: Boolean) of object;

property OnCustomDrawCell: TcxGridTableDataCellCustomDrawEvent;

Description

The OnCustomDrawCell occurs every time a table cell or a card cell needs to be painted. As with other custom draw events it provides a canvas for the grid control (ACanvas parameter), view info to get the bounding rectangle of the painted element (AViewInfo parameter and its Bounds property). Sender is usually the element that caused the repaint. The ADone parameter is initially False you should set it to True to tell the grid that you have chosen to custom draw this item.


TcxCustomGridTableItem.OnGetCellHint

TcxCustomGridTableItem

Fires before the item’s hint is shown when an end-user positions the mouse pointer over the item’s data cell.

type

  TcxGridGetCellHintEvent = procedure(Sender: TcxCustomGridTableItem; ARecord: TcxCustomGridRecord; ACellViewInfo: TcxGridTableDataCellViewInfo; const AMousePos: TPoint; var AHintText: TCaption; var AIsHintMultiLine: Boolean; var AHintTextRect: TRect) of object;

property OnGetCellHint: TcxGridGetCellHintEvent;

Description

Implement the OnGetCellHint event handler to customize an item’s hint.

The Sender parameter specifies the currently processed item;

The ARecord parameter specifies the record in a card view that the item belongs to;

The ACellViewInfo parameter provides information on the item’s data cell;

The AMousePos parameter specifies relative onscreen coordinates of the mouse pointer;

The AHintText parameter specifies the text to be drawn in the hint window;

The AIsHintMultiLine parameter specifies whether the text can be wrapped.

The AHintTextRect parameter specifies relative onscreen coordinates of the hint window.


TcxCustomGridTableItem.OnGetDataText

TcxCustomGridTableItem          See Also

Enables you to specify custom text for cells.  The text specified is used for displaying, sorting and grouping purposes.

type

  TcxGridGetDataTextEvent = procedure(Sender: TcxCustomGridTableItem; ARecordIndex: Integer; var AText: string) of object;

property OnGetDataText: TcxGridGetDataTextEvent;

Description

Handle the OnGetDataText event to provide custom text for cells within a column or a card view row.  The cell whose text is to be set can be identified via the Sender and ARecordIndex parameters.  The first parameter specifies the column/row where the cell is displayed while the second identifies the cell’s record index.  These two parameters allow you to obtain the cell’s actual value.

To change the currently processed cell’s text, assign the desired string to the AText parameter.  Note that this parameter initially holds the cell’s actual value.

Use the item’s Options.SortByDisplayText property to specify whether the display texts of its cells affect sorting.

Note: the text specified by handling the OnGetDataText event is displayed within cells and also affects sorting and grouping operations and operations associated with calculating the cell's size, such as calculating a cell’s height and the table item’s width.  If you only need to set the cell's displayed text, handle the OnGetDisplayText event instead.  The latter event also enables you to override the display text specified in the OnGetDataText event handler.


TcxCustomGridTableItem.OnGetDisplayText

TcxCustomGridTableItem

Occurs when an item value is displayed.

type

  TcxGridGetDisplayTextEvent = procedure(Sender: TcxCustomGridTableItem; ARecord: TcxCustomGridRecord; var AText: string) of object;

property OnGetDisplayText: TcxGridGetDisplayTextEvent;

Description

Use the OnGetDisplayText event to specify the text representation of an item value.  The item is addressed by the Sender parameter.  ARecord defines the record for which an item value is displayed.  When this event occurs, the AText argument already contains the string to be displayed, but you are able to change it as needed.


TcxCustomGridTableItem.OnGetFilterDisplayText

TcxCustomGridTableItem          See Also

Occurs when retrieving the text representation of items (columns) in the filter dropdown list.

type

  TcxGridGetFilterDisplayTextEvent = procedure(Sender: TcxCustomGridTableItem; const AValue: Variant; var ADisplayText: string) of object;

property OnGetFilterDisplayText: TcxGridGetFilterDisplayTextEvent;

Description

When a user clicks the filter arrow on the column header, a values list appears.  By selecting an item from this list, a user is able to set the filter criteria for this column.  The OnGetFilterDisplayText event allows you to replace the text displayed for individual items within the list.  This event is generated for every item within the list.  To customize the list (add or delete new items), you can handle the TcxDataFilterCriteria.OnGetValueList or TcxCustomGridTableItem.OnGetFilterValues event.

The Sender parameter defines the column for which the OnGetFilterDisplayText is generated.  The AValue and ADisplayValue parameters specify the value and display value representing a list item respectively.  To modify the display text for the item, assign a new value to the ADisplayValue argument.


TcxCustomGridTableItem.OnGetFilterValues

TcxCustomGridTableItem          See Also

Occurs before displaying a filter popup list.

type

  TcxGridGetFilterValuesEvent = procedure(Sender: TcxCustomGridTableItem; AValueList: TcxDataFilterValueList) of object;

property OnGetFilterValues: TcxGridGetFilterValuesEvent;

Description

Use the OnGetFilterValues event to customize the list of values displayed within the item’s filter dropdown.  Handle this event if you need particular items to be added to or removed from the dropdown.

The Sender parameter defines the item (table column or card row) where the filter dropdown is about to be displayed.  The AValueList parameter provides access to the TcxDataFilterValueList object holding the list of values that will be displayed.  Use this object’s properties and method to add or remove individual items.

The OnGetFilterValues event is generated after the TcxDataFilterCriteria.OnGetValueList event.  This event is available via the data controller’s Filter property.  It also allows you to customize filter dropdowns within items in a similar manner.  Consider handling this event if particular filter items should be added to or removed from filter dropdowns in all or most of the items.

Note: the OnGetFilterValues event allows you to add filter items that don’t have any associated filter condition.  In such a case, the OnUserFiltering event is raised when selecting such an item.  Handle this event to apply the desired filter to the view.


TcxCustomGridTableItem.OnGetProperties

TcxCustomGridTableItem          See Also

This event is fired when getting the properties of an editor used to display and edit the contents of an item cell for a specific record.

type

  TcxGridGetPropertiesEvent = procedure(Sender: TcxCustomGridTableItem; ARecord: TcxCustomGridRecord; var AProperties: TcxCustomEditProperties) of object;

property OnGetProperties: TcxGridGetPropertiesEvent;

Description

The OnGetProperties and OnGetPropertiesForEdit events allow you to implement the MultiEditors feature, i.e. provide different editors to display and edit the cells of a single item.  Generally, the MultiEditors feature is used in unbound mode, when you know the type of data stored in a specific item cell.

You can handle the OnGetProperties event to change the default item editor that is used to display the contents of an item cell for a specific record.  If the OnGetPropertiesForEdit event is not handled, the OnGetProperties event handler also specifies the default item editor which will be used to edit the contents of an item cell when in-place editing is initiated.

The ARecord parameter specifies the record for which an item editor should be determined.  The RepositoryItem and PropertiesClass properties can be used to specify the default item editor (the editor used to edit all the cells of the current item).  If they are not specified, the item is assigned an editor based on the field type (in bound mode) or on the DataBinding.ValueTypeClass property (in unbound mode).  Refer to the FieldName property and TcxValueType class properties for details.

The properties of the default item editor are passed in the AProperties parameter.  To redefine the default editor, assign another properties object (a TcxCustomEditProperties descendant) which corresponds to the required editor to the AProperties parameter.

If you need to provide different edit properties within an event, you can use the edit repository (the TcxEditRepository component) as a storage for particular edit properties.  Create repository items corresponding to specific editors and adjust their edit properties.  Then use the Properties object of these repository items to return it in the AProperties parameter.

Note:	You must avoid situations which require modifying edit properties passed in the AProperties parameter within the OnGetProperties event.  Assume you need to disable editing of the first item cell while allowing a user to edit the other item cells.  When handling the OnGetProperties event, you should not use the following code:

//Delphi

if ARecord.RecordIndex = 0 then

  AProperties.ReadOnly := True

else

  AProperties.ReadOnly := False;

//C++ Builder

if (ARecord->RecordIndex == 0)

  AProperties->ReadOnly = true

else

  AProperties->ReadOnly = false;

Instead, you should create two repository items and modify their ReadOnly property as required outside the OnGetProperties event handler; then return edit properties of these repository items in the OnGetProperties event handler.  The correct code for the OnGetProperties event is as follows:

//Delphi

if ARecord.RecordIndex = 0 then

  AProperties := RepositoryItem1.Properties

else

  AProperties := RepositoryItem2.Properties;

//C++ Builder

if (ARecord->RecordIndex == 0)

  AProperties = RepositoryItem1->Properties

else

  AProperties = RepositoryItem2->Properties;

The following code assumes that the required repository items were created and modified via the edit repository.  Different edit properties are specified for the Grade column based on the record index:

//Delphi

const

  SkillCount = 6;

procedure TColumnsMultiEditorsDemoMainForm.clnGradeGetProperties(

  Sender: TcxCustomGridTableItem; ARecord: TcxCustomGridRecord;

  var AProperties: TcxCustomEditProperties);

begin

  case ARecord.RecordIndex mod SkillCount of

    //specify the spin editor for records 0, 6, 12, etc.

    0: AProperties := SpinRepositoryItemYears.Properties;

    //specify the image combo box for records 1,2, 7,8, etc.

    1, 2: AProperties := ImageComboRepositoryItemLanguages.Properties;

    //specify another image combo box for records 3, 9, 15, etc.

    3: AProperties := ImageComboRepositoryItemCommunication.Properties;

    //specify the date edit for records 4, 10, 16, etc

    4: AProperties := DateRepositoryItemStartWorkFrom.Properties;

    //for records 5, 11, 17 etc, the default editor

    //(text edit in unbound mode) is used

  end;

end;

//C++ Builder

const

  SkillCount = 6;

void __fastcall TColumnsMultiEditorsDemoMainForm::clnGradeGetProperties(

  TcxCustomGridTableItem *Sender, TcxCustomGridRecord *ARecord,

  TcxCustomEditProperties *&AProperties) {

  switch(ARecord->RecordIndex % SkillCount) {

    //specify the spin editor for records 0, 6, 12, etc.

    case 0:

      AProperties = SpinRepositoryItemYears->Properties;

      break;

    //specify the image combo box for records 1,2, 7,8, etc.

    case 1, 2:

      AProperties = ImageComboRepositoryItemLanguages->Properties;

      break;

    //specify another image combo box for records 3, 9, 15, etc.

    case 3:

      AProperties = ImageComboRepositoryItemCommunication->Properties;

      break;

    //specify the date edit for records 4, 10, 16, etc

    case 4:

      AProperties = DateRepositoryItemStartWorkFrom->Properties;

      break;

    //for records 5, 11, 17 etc, the default editor

    //(text edit in unbound mode) is used

  }

end;

For the complete example, see the ColumnsMultiEditorsDemo.


TcxCustomGridTableItem.OnGetPropertiesForEdit

TcxCustomGridTableItem          See Also

This event is fired when getting the properties of an editor which is used to display and edit the contents of an item cell for a specific record when in-place editing is initiated.

type

  TcxGridGetPropertiesEvent = procedure(Sender: TcxCustomGridTableItem; ARecord: TcxCustomGridRecord; var AProperties: TcxCustomEditProperties) of object;

property OnGetPropertiesForEdit: TcxGridGetPropertiesEvent;

Description

The OnGetPropertiesForEdit and OnGetProperties events allow you to implement the MultiEditors feature, i.e. provide different editors to display and edit the cells of a single item.  Generally, the MultiEditors feature is used in unbound mode, when you know the type of data stored in a specific item cell.

Compared to the OnGetProperties event, the OnGetPropertiesForEdit event handler lets you change the default item editor that is used to edit the contents of an item cell for a specific record when in-place editing is initiated.  This is the only difference between these two events.  Also note that if the OnGetPropertiesForEdit event is not handled, the OnGetProperties event (if handled) also specifies the default item editor that will be used to edit the contents of an item cell when in-place editing is initiated as if the OnGetPropertiesForEdit event is handled.

Please refer to the description of the OnGetProperties event to learn about the parameters and restrictions on modifying the properties of the in-place editor when handling the OnGetPropertiesForEdit and OnGetProperties events.


TcxCustomGridTableItem.OnGetStoredProperties

TcxCustomGridTableItem          See Also          Example

Occurs when the list of the current table item’s properties that will be stored in external storage is produced.

type

  TcxGridTableItemGetStoredPropertiesEvent = procedure(Sender: TcxCustomGridTableItem; AProperties: TStrings) of object;

property OnGetStoredProperties: TcxGridTableItemGetStoredPropertiesEvent;

Description

Handle the OnGetStoredProperties event to customize the list of the current table item’s properties that will be stored in external storage such as a file, registry or stream as a part of the owner view.  Whenever the storing process is started, the list of the properties to be stored is produced.  When the event is fired, the list already consists of the table item’s properties’ names which are stored by default. The set of properties in the list depends on the table item type (whether it is a column, banded column or band).

The Sender parameter specifies the table item object whose properties will be stored.

The AProperties parameter specifies the list of properties to be stored.

As for the guiding principles on how to use this event, see the example on how to handle the TcxCustomGridView.OnGetStoredProperties event.


TcxCustomGridTableItem.OnGetStoredPropertyValue

TcxCustomGridTableItem          See Also          Example

Occurs when values of the current table item’s properties are stored to external storage.

type

  TcxGridTableItemGetStoredPropertyValueEvent = procedure(Sender: TcxCustomGridTableItem; const AName: string; var AValue: Variant) of object;

property OnGetStoredPropertyValue: TcxGridTableItemGetStoredPropertyValueEvent;

Description

Whenever you have customized the list of the properties to be stored to external storage on the OnGetStoredProperties event you should handle the OnGetStoredPropertyValue event to specify their values.  These values will be saved in the resulting output.

The Sender parameter specifies the table item object whose properties will be stored.

The AName parameter denotes the name of the current table item’s property in the resulting output.

In order to store a specific value for the AName property, set the value to the AValue parameter.

As for the guiding principles on how to use this event, see the example on how to handle the TcxCustomGridView.OnGetStoredPropertyValue event.


TcxCustomGridTableItem.OnInitFilteringDateRanges

TcxCustomGridTableItem          See Also

Allows you to customize the item’s collection of filter date ranges.

type

  TcxGridInitDateRangesEvent = procedure(Sender: TcxCustomGridTableItem; ADateRanges: TcxGridDateRanges) of object;

property OnInitFilteringDateRanges: TcxGridInitDateRangesEvent;

Description

Once this event fires, the item’s collection of filter date ranges is initialized with base filter date ranges that are common to all View items.  Use the View’s OnInitFilteringDateRanges event to customize the base collection.  An item’s OnInitFilteringDateRanges event allows you to further adjust the item’s collection of filter date ranges.

The Sender parameter references the item.

The ADateRanges parameter provides access to the item’s collection of filter date ranges.  You can access this collection via the item’s FilteringDateRanges property.  You can use this parameter to add and remove built-in and custom date ranges.  See the Adding Custom Filter and Grouping Date Ranges topic for an example.


TcxCustomGridTableItem.OnInitGroupingDateRanges

TcxCustomGridTableItem          See Also

Enables you to customize the item’s collection of grouping date ranges.

type

  TcxGridInitDateRangesEvent = procedure(Sender: TcxCustomGridTableItem; ADateRanges: TcxGridDateRanges) of object;

property OnInitGroupingDateRanges: TcxGridInitDateRangesEvent;

Description

Once this event fires, the item’s collection of grouping date ranges is initialized with base grouping date ranges that are common to all View items.  Use the View’s OnInitGroupingDateRanges event to customize the base collection.  An item’s OnInitGroupingDateRanges event allows you to further adjust the item’s collection of grouping date ranges.

The Sender parameter references the item.

The ADateRanges parameter provides access to the item’s collection of grouping date ranges.  You can access this collection via the item’s GroupingDateRanges property.  You can use this parameter to add and remove built-in and custom date ranges.  See the Adding Custom Filter and Grouping Date Ranges topic for an example of using this parameter.


TcxCustomGridTableItem.OnSetStoredPropertyValue

TcxCustomGridTableItem          See Also          Example

Occurs when values of the current table item’s properties are restored from external storage.

type

  TcxGridTableItemSetStoredPropertyValueEvent = procedure(Sender: TcxCustomGridTableItem; const AName: string; const AValue: Variant) of object;

property OnSetStoredPropertyValue: TcxGridTableItemSetStoredPropertyValueEvent;

Description

In order to restore values of the current table item’s properties whose values are not stored by default and whose names and values were explicitly specified on the OnGetStoredProperties and OnGetStoredPropertyValue events correspondingly, handle the OnSetStoredPropertyValue event.  These values will be saved in the resulting output.

The Sender parameter specifies the table item object whose properties are being restored.

The AName parameter denotes the name of the current table item’s property in the resulting output whose value is being restored from storage and is returned by the AValue parameter.

As for the guiding principles on how to use this event, see the example on how to handle the TcxCustomGridView.OnSetStoredPropertyValue event.


TcxCustomGridTableItem.OnUserFiltering

TcxCustomGridTableItem          See Also

Enables you to apply a proper filter when an end user selects a custom created item from the filter dropdown.

type

  TcxGridUserFilteringEvent = procedure(Sender: TcxCustomGridTableItem; const AValue: Variant; const ADisplayText: string) of object;

property OnUserFiltering: TcxGridUserFilteringEvent;

Description

You can add custom items to filter dropdowns by handling the OnGetFilterValues event.  One of the item types that can be added is an item that has no predefined filter criteria associated with it.  When the end user clicks such an item, the OnUserFiltering event is raised.  Handle this event to apply an appropriate filter to the view.

The OnUserFiltering event’s Sender parameter identifies the view item whose filter dropdown’s item has been clicked.  The AValue and ADisplayText parameters identify the clicked item.  These parameter values are initialized in the OnGetFilterValues event handler when adding an item.

Please refer to the OnGetFilterValues event for information about adding item without predefined filter criteria to the filter dropdown.

Consider an example of using the OnGetFilterValues and OnUserFiltering events.  The first will add the ‘Filter TODAY’ and ‘Filter YESTERDAY’ items to the filter dropdown.  The second will apply the corresponding filter conditions.

First, consider the OnGetFilterValues event handler.

// Delphi

const

  filterTodayID = 0;

  filterYesterdayID = 1;

//An OnGetFilterValues event handler

//Add the ‘Filter TODAY’ and ‘Filter YESTERDAY’ elements

//for the tvOrdersPurchaseDate column

procedure TSummaryFooterDemoMainForm.tvOrdersPurchaseDateGetFilterValues(

  Sender: TcxCustomGridTableItem; AValueList: TcxDataFilterValueList);

begin

  AValueList.Add(fviUser, filterTodayID, 'Filter TODAY', True);

  AValueList.Add(fviUser, filterYesterdayID, 'Filter YESTERDAY', True);

end;

// C++ Builder

const  filterTodayID = 0;

const  filterYesterdayID = 1;

//An OnGetFilterValues event handler

//Add the "Filter TODAY" and "Filter YESTERDAY" elements

//for the tvOrdersPurchaseDate column

void TSummaryFooterDemoMainForm::tvOrdersPurchaseDateGetFilterValues(

  TcxCustomGridTableItem *Sender; TcxDataFilterValueList *AValueList)

{

  AValueList->Add(fviUser, filterTodayID, "Filter TODAY", true);

  AValueList->Add(fviUser, filterYesterdayID, "Filter YESTERDAY", true);

}

As a result, you will see two new elements in the filter drop down list for the tvOrdersPurchaseDate column:

The following code creates and applies appropriate filters when a user selects the 'Filter TODAY' or 'Filter YESTERDAY' entries from the list.

// Delphi

//An OnUserFiltering event handler

procedure TSummaryFooterDemoMainForm.tvOrdersPurchaseDateUserFiltering(

  Sender: TcxCustomGridTableItem; const AValue: Variant;

  const ADisplayText: String);

var

  ADate: TDateTime;

  ADateStr: string;

begin

  case AValue of

    filterTodayID:

    begin

      ADate := Today;

      ADateStr := 'Today';

    end;

    filterYesterdayID:

    begin

      ADate := Yesterday;

      ADateStr := 'Yesterday'

    end;

  end;

  Sender.DataBinding.AddToFilter(nil, foEqual, ADate, ADateStr, True);

end;

// C++ Builder

//An OnUserFiltering event handler

void TSummaryFooterDemoMainForm::tvOrdersPurchaseDateUserFiltering(

  TcxCustomGridTableItem *Sender, const Variant AValue,

  const String ADisplayText)

{

  TDateTime ADate;

  string ADateStr;

  switch (AValue) {

    case filterTodayID:

      ADate = Today;

      ADateStr = "Today";

      break;

    case filterYesterdayID:

      ADate = Yesterday;

      ADateStr = "Yesterday";

  }

  Sender->DataBinding->AddToFilter(NULL, foEqual, ADate, ADateStr, true);

}

The following image shows a sample grid control after selecting the ‘Filter YESTERDAY’ entry.


TcxCustomGridTableItemCustomOptions
TcxCustomGridTableItemCustomOptions Object

Hierarchy          See Also

Provides general information for item related classes.

Unit

cxGridCustomTableView

TcxCustomGridTableItemCustomOptions = class(TPersistent)

Description

This class is the base class for the TcxCustomGridTableItemOptions, TcxGridColumnSummary, TcxGridCardViewRowPosition, and TcxGridBandedColumnPosition classes.

The TcxCustomGridTableItemOptions class represents a set of options affecting items’ behavior, which can be accessed via an item's Options property.

TcxGridBandedColumnPosition provides properties to specify the position of a banded column (TcxGridBandedColumn) within a banded table view.  These properties are specified by the TcxGridBandedColumn.Position object.


TcxCustomGridTableItemCustomOptions Hierarchy
Hierarchy

TPersistent

     |


TcxCustomGridTableItemOptions
TcxCustomGridTableItemOptions Object

Hierarchy          Properties          See Also

Represents a set of options for an item.

Unit

cxGridCustomTableView

TcxCustomGridTableItemOptions = class(TcxCustomGridTableItemCustomOptions);

Description

The TcxCustomGridTableItemOptions class provides settings controlling users’ capability to manipulate items and item cells and specify the appearance of an item.  To customize settings for an item, see the TcxCustomGridTableItem.Options

You can set options common to all items within a view via the view’s OptionsCustomize, OptionsSelection and OptionsView properties.


TcxCustomGridTableItemOptions Hierarchy
Hierarchy

TPersistent

     |

TcxCustomGridTableItemCustomOptions

     |


Properties for TcxCustomGridTableItemOptions
TcxCustomGridTableItemOptions Properties

TcxCustomGridTableItemOptions          Legend

In TcxCustomGridTableItemOptions

Editing

Filtering

FilteringFilteredItemsList

FilteringMRUItemsList

FilteringPopup

FilteringPopupMultiSelect

Focusing

Grouping

IgnoreTimeForFiltering

IncSearch

Moving

ShowCaption

ShowEditButtons

SortByDisplayText

Sorting


TcxCustomGridTableItemOptions.Editing

TcxCustomGridTableItemOptions          See Also

Defines whether the editing of item cells is enabled.

property Editing: Boolean;

Description

Set the Editing property to False to prevent a user from modifying item data.  Otherwise, a user can modify data unless this option is disabled by another item or view options.  For instance, you can prevent a user from editing item content by setting one of the following:

•	the Focusing attribute of the item’s Options object to False;

•	Editing of the view’s OptionsData property (TcxGridTableView.OptionsData or TcxGridCardView.OptionsData) to False;

•	CellSelect of the view’s OptionsSelection property to False.

The default value of the Editing property is True.


TcxCustomGridTableItemOptions.Filtering

TcxGridColumnOptions          See Also

Specifies whether the item displays the filter dropdown button.

property Filtering: Boolean;

Description

By default, each item displays a filter dropdown button within its caption.  You can hide this button within a particular item by setting the Filtering property to False.

Note:	To prevent filter dropdown buttons from being displayed within all the view’s items at once, set the view’s OptionsCustomize.ColumnFiltering property to False for a (banded) table view and the view’s OptionsCustomize.RowFiltering property to False for a card view.

If filter dropdown buttons are prevented from being displayed by the view, the Filtering option of individual items has no effect.

The default value of the Filtering property is True.


TcxCustomGridTableItemOptions.FilteringFilteredItemsList

TcxCustomGridTableItemOptions          See Also

Specifies whether to display all filter items or only selected ones in a filter dropdown.

property FilteringFilteredItemsList: Boolean;

Description

Unlike the view’s Filtering.RowFilteredItemsList and Filtering.ColumnFilteredItemsList properties that specify the above condition for a card view and a table view respectively, the FilteringFilteredItemsList property is applied to a particular row or column.

Set the FilteringFilteredItemsList property to True, to display only selected filter items in the filter dropdown.

The default value of the FilteringFilteredItemsList property is True.


TcxCustomGridTableItemOptions.FilteringMRUItemsList

TcxCustomGridTableItemOptions          See Also

Specifies whether this item’s filter dropdown displays the most recently used item list.

property FilteringMRUItemsList: Boolean;

Description

Use the FilteringMRUItemsList property to disable the most recently used list in a particular item’s filter dropdown.  Set this property to False for this purpose.  Note that you can disable the most recently used lists for filter dropdowns in all items at once.  Set the table view’s Filtering.ColumnMRUItemsList property (the Filtering.RowMRUItemsList property for a card view) to False for this purpose.  If this property’s value is True, the most recently used list’s availability in each item is specified by that item’s Options.FilteringMRUItemsList property.

The default value of the FilteringMRUItemsList property is True.


TcxCustomGridTableItemOptions.FilteringPopup

TcxCustomGridTableItemOptions

Specifies whether a filter dropdown for a specific row or column is available to an end-user.

property FilteringPopup: Boolean;

Description

Set the FilteringPopup property to False to prevent the current item from filtering through the filter dropdown.  The dropdown button is not drawn in this instance.

The default value of the FilteringPopup property is True.


TcxCustomGridTableItemOptions.FilteringPopupMultiSelect

TcxCustomGridTableItemOptions

Specifies whether an end-user can select multiple filter items in the filter dropdown (a row or a column).

property FilteringPopupMultiSelect: Boolean;

Description

Set the FilteringPopup property to False to disable multiple selections.  Selection boxes in the dropdown are not drawn in this instance.

The default value of the FilteringPopupMultiSelect property is True.


TcxCustomGridTableItemOptions.Focusing

TcxCustomGridTableItemOptions          See Also

Specifies whether an item cell can be focused.

property Focusing: Boolean;

Description

Set the Focusing property to False to prevent item cell focusing.  A user cannot then set focus to an item via a mouse click etc.  Otherwise, focusing an item cell is enabled unless the view’s OptionsSelection.CellSelect property is set to False.

The default value of the Focusing property is True.


TcxCustomGridTableItemOptions.Grouping

TcxCustomGridTableItemOptions          See Also

Defines whether a user can group view data by the item (column).

property Grouping: Boolean;

Description

Set the Grouping property to False to prevent a user from grouping/ungrouping data by the item (column).  That is, a user cannot move the column (in a table view) to the group panel or remove it from the group panel (although this can be accomplished programmatically).  Grouping does not affect column movement within a view.  See TcxCustomGridTableItemOptions.Moving to disable moving a column.  Other options which can restrict grouping and moving an item are defined by the view’s OptionsCustomize property.

The default value of the Grouping property is True.


TcxCustomGridTableItemOptions.IgnoreTimeForFiltering

TcxCustomGridTableItemOptions

Specifies whether to truncate the time portion of the date/time filter criteria in the filter dropdown.

property IgnoreTimeForFiltering: Boolean;

Description

If the date portion is a unique condition in the filter dropdown, set the IgnoreTimeForFiltering property to True so as to remove the time portion from the filter criteria list.  The values of the corresponding item will be filtered by date.

The default value of the IgnoreTimeForFiltering property is True.


TcxCustomGridTableItemOptions.IncSearch

TcxCustomGridTableItemOptions          See Also

Specifies whether an incremental search can be performed on the current item.

property IncSearch: Boolean;

Description

The IncSearch property specifies whether a user can search incrementally on the current item.  If IncSearch is True and the view’s OptionsBehavior.IncSearch is also set to True, then a user can simply start typing when a record cell is selected and the grid will navigate to the row that contains the closest partial match in the same column.

To determine the item on which the incremental search is performed, see the view’s Controller.IncSearchingItem property.

The default value of the IncSearch property is True.


TcxCustomGridTableItemOptions.Moving

TcxCustomGridTableItemOptions          See Also

Specifies whether a user can move an item (column).

property Moving: Boolean;

Description

Column movement is enabled only in table and banded table views.  Use the Moving property to define whether a column can be moved either within a view or to the group panel.  If Moving is set to False, a user cannot change the column’s position by dragging.  Other restrictions on moving the column are imposed by the Grouping attribute and the view’s options set via OptionsCustomize.

The default value of the Moving property is True.


TcxCustomGridTableItemOptions.ShowCaption

TcxCustomGridTableItemOptions          See Also

Specifies whether the row’s caption will be shown in a card view.

property ShowCaption: Boolean;

Description

Set the ShowCaption property to False to hide the row’s caption.

The default value of the ShowCaption property is True.


TcxCustomGridTableItemOptions.ShowEditButtons

TcxCustomGridTableItemOptions          See Also

Identifies the manner in which editors are displayed within item cells.

type

  TcxGridItemShowEditButtons = (isebDefault, isebNever, isebAlways);

property ShowEditButtons: TcxGridItemShowEditButtons;

Description

The ShowEditButtons property determines how editors are displayed within item cells.  If an editor has buttons, you can enable their display for a focused cell or for all item cells in a view.

Value	Meaning
isebDefault	Button visibility is determined for the view by the OptionsView.ShowEditButtons property.
isebNever	Editor buttons are visible only when the item is focused.
isebAlways	Editor buttons are visible for all records within the view.

The default value of the ShowEditButtons property is isebDefault.


TcxCustomGridTableItemOptions.SortByDisplayText

TcxCustomGridTableItemOptions          See Also

Specifies whether the column/row is sorted by its values or display texts.

type

  TcxGridItemSortByDisplayText = (isbtDefault, isbtOn, isbtOff);

property SortByDisplayText: TcxGridItemSortByDisplayText;

Description

Set the SortByDisplayText property to specify how the column/row will be sorted.  The table below lists all the possible values for this property.

Value	Meaning
isbtDefault	The column/row is sorted by the display texts of its cells when the dcoSaveExpanding option is included into the view’s DataController.Options property or custom text is provided for the cells within a column or card view row by handling the OnGetDataText event.  Otherwise, the column is sorted by the values of its cells.
isbtOn	The column/row is sorted by the display texts of its cells.  Handle the OnGetDataText event to provide custom display text for the cells within a column or card view row.
isbtOff	The column/row is sorted by the values of its cells.  Any display text provided by the OnGetDataText event does not affect sorting.

The default value of the SortByDisplayText property is isbtDefault.


TcxCustomGridTableItemOptions.Sorting

TcxCustomGridTableItemOptions          See Also

Specifies whether a user can sort view data against the item.

property Sorting: Boolean;

Description

If the Sorting property is True and sorting is enabled for a view (the view’s OptionsCustomize.ItemSorting property), a user can sort view data against the column by clicking the column header (in a table view).  A second click reverses the sort order (ascending order is changed to descending and vice versa).  The small arrow displayed in the column header indicates the current sort order.  The up-arrow indicates the ascending sort order, the down-arrow – descending.

To sort against multiple columns, a user can click these column headers while holding down the SHIFT key.  To clear sorting for a column, you need to click the column header combined with the CTRL key.

The default value of the Sorting property is True.


TcxCustomGridTableItemStyles
TcxCustomGridTableItemStyles Object

Hierarchy          Properties          Methods          Events          See Also

Represents settings controlling the style of item elements.

Unit

cxGridCustomTableView

TcxCustomGridTableItemStyles = class(TcxCustomGridStyles);

Description

The TcxCustomGridTableItemStyles class declares properties and events which allow you to customize the appearance of item elements.  TcxCustomGridTableItemStyles descendants publish other properties appropriate for particular items (table columns or card view rows).  To adjust the appearance of an item, see the TcxCustomGridTableItem.Styles property.  It is possible to define the style for all items contained within a view via the TcxCustomGridTableView.Styles member.


TcxCustomGridTableItemStyles Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomStyles

     |

TcxStyles

     |

TcxCustomGridStyles

     |


Properties for TcxCustomGridTableItemStyles
TcxCustomGridTableItemStyles Properties

TcxCustomGridTableItemStyles          Legend

In TcxCustomGridTableItemStyles

Content

GridView

Item

Derived from TcxCustomGridStyles

GridView

Derived from TcxCustomStyles

StyleSheet


Methods for TcxCustomGridTableItemStyles
TcxCustomGridTableItemStyles Methods

TcxCustomGridTableItemStyles          Legend

Derived from TcxCustomStyles

Assign

Create

Destroy


Events for TcxCustomGridTableItemStyles
TcxCustomGridTableItemStyles Events

TcxCustomGridTableItemStyles          Legend

In TcxCustomGridTableItemStyles

OnGetContentStyle


TcxCustomGridTableItemStyles.Content

TcxCustomGridTableItemStyles          See Also

Specifies the style for item cells.

property Content: TcxStyle;

Description

The Content property allows you to define the style (font, background color) for displaying item data.  It is possible to modify the style of individual item cells by handling the OnGetContentStyle event.  Note that the background bitmap for the cells of a specific item cannot be specified via the Content property as this is relevant only to all the cells within the grid.

Descendants of the TcxCustomGridTableItemStyles class use the value of the Content property to render other item elements.  For instance, the Content property specifies the default style of the caption region in a card view row.


TcxCustomGridTableItemStyles.GridView

TcxCustomGridTableItemStyles

Specifies the view containing the item for which the style is applied.

property GridView: TcxCustomGridTableView;

Description

Use the GridView property to get the item view for which the current style is applied.  The current style is a TcxCustomGridTableItemStyles class instance.

ReadOnly Property


TcxCustomGridTableItemStyles.Item

TcxCustomGridTableItemStyles

Gets the item for which the style is applied.

property Item: TcxCustomGridTableItem;

Description

The Item property returns the item for which the current TcxCustomGridTableItemStyles instance defines style settings.

ReadOnly Property


TcxCustomGridTableItemStyles.OnGetContentStyle

TcxCustomGridTableItemStyles          See Also

Occurs whenever an item cell should be redrawn.

type

  TcxGridGetCellStyleEvent = procedure(Sender: TcxCustomGridTableView; ARecord: TcxCustomGridRecord; AItem: TcxCustomGridTableItem; out AStyle: TcxStyle) of object;

property OnGetContentStyle: TcxGridGetCellStyleEvent;

Description

You can handle the OnGetContentStyle event to modify the style for individual item cells.  This event occurs every time it is necessary to redraw an item cell of the grid record defined by the ARecord parameter.  The item is specified by the AItem parameter.  Returning the style via the AStyle parameter overrides the style for the content defined by the view’s Styles.Content property and the item’s Styles.Content property by default.

The Sender parameter determines a view containing the item.

Note that the background bitmap cannot be assigned by handling the OnGetContentStyle event as this is relevant only to all the cells within the grid.


TcxGridItemDataBinding
TcxGridItemDataBinding Object

Hierarchy          Properties          Methods

Represents an object linking a grid view item with a dataset field.

Unit

cxGridCustomTableView

TcxGridItemDataBinding = class(TPersistent);

Description

Every grid view item (a column in a table view or a row in a card view) is linked to a dataset with the help of a DataBinding object.  Generally, data binding is used to determine the value type.  The value type is identified by the ValueTypeClass property.  ValueTypeClass determines the manner in which data is represented (as string, integer, date, boolean etc.).  In bound mode, ValueTypeClass is assigned automatically based on the field type.  In unbound and provider modes, you have to specify the ValueTypeClass manually to ensure that the item works correctly. The ValueTypeClass and ValueType properties also provide the way to implement the unbound items in data-aware views.

The Data property is extremely useful in Provider Mode, e.g. for indexing columns.  When in provider mode, the custom data source cannot track display changes (moving items, for instance) so data referencing can be inadequate.  Use the Data property to assign a unique value to items.  While using your custom data source, refer to the Data property to recognize the items.  See the Provider Mode topic for more information.


TcxGridItemDataBinding Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxGridItemDataBinding
TcxGridItemDataBinding Properties

TcxGridItemDataBinding          Legend

In TcxGridItemDataBinding

Data

Filter

FilterCriteriaItem

Filtered

Item

ValueType

ValueTypeClass


Methods for TcxGridItemDataBinding
TcxGridItemDataBinding Methods

TcxGridItemDataBinding          Legend

In TcxGridItemDataBinding

 AddToFilter

 Assign

 GetFilterActiveValueIndexes

 GetFilterStrings

 GetFilterValues

 SetFilterActiveValueIndexes


TcxGridItemDataBinding.Data

TcxGridItemDataBinding

Allows you to store additional data within the data binding.

property Data: TObject;

Description

Use this property to store additional data within the TcxGridItemDataBinding class instance.

The Data property can be used to identify items when implementing a custom data source in provider mode.  A custom data source cannot recognize items by reading their indexes because they do not reflect any display changes such as changing the order of items.  Assign a unique value to the Data property and use it when getting/setting a value from/to a custom data source.  Refer to the Provider Mode topic for an example.


TcxGridItemDataBinding.Filter

TcxGridItemDataBinding

Refers to the filter provided by the view’s data controller.

property Filter: TcxDataFilterCriteria;

Description

The Filter property specifies the filter of the view containing the current item, i.e. the view’s DataController.Filter property.  Using its members, you can add/remove filter conditions, customize the filter dropdown list and thus control the filtering.

ReadOnly Property


TcxGridItemDataBinding.FilterCriteriaItem

TcxGridItemDataBinding

Refers to the first filter condition of the corresponding grid view item.

property FilterCriteriaItem: TcxFilterCriteriaItem;

Description

Use the FilterCriteriaItem property to access to the first filter condition of the grid view item.  The filter criteria provided by the Filter and the view’s DataController.Filter properties can contain several filter conditions involving the current item.  If so, only the first filter condition is retrieved.  Each filter condition represents an object of the TcxFilterCriteriaItem class and refers to the current item (the TcxFilterCriteriaItem.ItemLink property), a comparison operator (the TcxFilterCriteriaItem.OperatorKind property) and the value with which data is compared (the TcxFilterCriteriaItem.Value property).

To remove any filters applied to the current item, set the Filtered property to False.

ReadOnly Property


TcxGridItemDataBinding.Filtered

TcxGridItemDataBinding

Specifies whether filter criteria are active.

property Filtered: Boolean;

Description

The Filtered property returns True if the filter criteria provided by the Filter property contains a filter condition applied for the corresponding item.  Otherwise, the property returns False.

You can clear the existing filter conditions that were set for the item by assigning Filtered to False.  This removes all filter conditions from the filter which applied to the item.


TcxGridItemDataBinding.Item

TcxGridItemDataBinding

Represents the grid view item to which the current data binding belongs.

property Item: TcxCustomGridTableItem;

Description

Use the Item property, to gain access to the grid view item to which the current data binding object belongs.

ReadOnly Property


TcxGridItemDataBinding.ValueType

TcxGridItemDataBinding

Specifies the string representation of the value type class.

property ValueType: String;

Description

The ValueType property specifies the string representation of the data type which the data binding provides.  Usually, you should only set the ValueType for the unbound and provider modes.  This automatically designates the ValueTypeClass associated with this data type.  At design time, each item of a view has the DataBinding.ValueType property which is represented by a list of the available data types.

In bound mode, the ValueTypeClass and ValueType properties are automatically assigned based on the field type.  To create an unbound item of the specified type in your data-aware views, customize these properties as needed.  This also requires the DataBinding.FieldName property to be unassigned, the DataController.DataModeController.SmartRefresh property be set to True and the DataController.KeyFieldNames property to have a value.

For unbound items, the ValueTypeClass and ValueType properties also determine the type of the default editor used to edit the contents of item.  For instance, by selecting ‘Boolean’ value from the ValueType list the TcxCheckBox editor is assigned to the item.  See the TcxValueType class topic for more details.

For items in bound mode, the default item editor is determined by the field type.  Please refer to the FieldName property topic.


TcxGridItemDataBinding.ValueTypeClass

TcxGridItemDataBinding

Determines the data type which the data binding provides.

property ValueTypeClass: TcxValueTypeClass;

Description

The ValueTypeClass property specifies the data type which the data binding provides, thus determining the type of value an item represents.  Usually, you should only set ValueTypeClass for the unbound and provider modes. This provides correct memory allocation, validation and sorting of item values.  The ValueType property specifies the string representation of the data type.  This property can be used to set an item’s data type at design time.

In bound mode, the ValueTypeClass and ValueType properties are assigned automatically based on the field type.  To create an unbound item of the specified type in your data-aware views, customize these properties as needed.  This also requires the DataBinding.FieldName property to be unassigned, the DataController.DataModeController.SmartRefresh property be set to True and the DataController.KeyFieldNames property to have a value.

For unbound items, the ValueTypeClass and ValueType properties also determine the type of the default editor used to edit the contents of the item.  For instance, assigning ValueTypeClass to TcxBooleanValueType results in using the TcxCheckBox editor for the item.  See to the TcxValueType class topic for more details.

For items in bound mode, the default item editor is determined by the field type.  Please refer to the FieldName property topic.


TcxGridItemDataBinding.AddToFilter

TcxGridItemDataBinding          See Also

Adds a filter condition to the filters list.

function AddToFilter(AParent: TcxFilterCriteriaItemList; AOperatorKind: TcxFilterOperatorKind; const AValue: Variant; const ADisplayText: string = ''; AReplaceExistent: Boolean = True): TcxFilterCriteriaItem;

Description

Use the AddToFilter method to add a filter condition to the filter list determined by the AParent parameter.  If AParent is NIL, a new filter condition is inserted in the root list provided by the Filter.Root property.  This filter condition affects the item determined by the Item property.

The AOperatorKind parameter specifies the filter operator. For the list of available operators, see the TcxFilterOperatorKind type.

The Sender parameter defines the item for which the OnGetFilterDisplayText is generated.

The AValue and ADisplayText parameters specify the values for the Value and DisplayValue properties of the new filter condition.  If the AReplaceExistent parameter is True, all filtering conditions for a given item are cleared first, otherwise the new filtering condition is appended to the existing ones.


TcxGridItemDataBinding.Assign

TcxGridItemDataBinding

Copies the contents of the source data binding to a new data binding.

procedure Assign(Source: TPersistent); override;

Description

Assign copies the Data, and ValueTypeClass property values from the Source object to the current TcxGridItemDataBinding instance.  The TcxGridItemDBDataBinding class overrides the Assign method and copies the FieldName property in addition to Data and ValueTypeClass.

Use this method, for instance, when you want to link the current item to the same field as the specified data binding object of another item.


TcxGridItemDataBinding.GetFilterActiveValueIndexes

TcxGridItemDataBinding          See Also

Populates the AIndexes collection with corresponding indexes of filter conditions that are currently applied to the item (a row or a column).

TcxGridIndexes = array of Integer;

procedure GetFilterActiveValueIndexes(AValueList: TcxGridFilterValueList; var AIndexes: TcxGridIndexes);

Description

The AValueList parameter specifies a list of filter conditions;

The AIndexes parameter specifies a list to be populated with indexes of the currently applied filter conditions.


TcxGridItemDataBinding.GetFilterStrings

TcxGridItemDataBinding          See Also

Populates AStrings with the display text of filter conditions that are currently applied to the item (a row or a column).

procedure GetFilterStrings(AStrings: TStrings; AValueList: TcxGridFilterValueList);

Description

The AStrings parameter specifies a list that is to be populated with the display text of filter conditions;

The AValueList parameter specifies a list of filter conditions.


TcxGridItemDataBinding.GetFilterValues

TcxGridItemDataBinding          See Also

Populates the AValueList with the filter conditions of the corresponding item (a row or a column).

procedure GetFilterValues(AValueList: TcxGridFilterValueList; AValuesOnly: Boolean = True; AInitSortByDisplayText: Boolean = False; ACanUseFilteredValues: Boolean = False);

Description

The AValueList parameter specifies a list to be populated with filter conditions;

The AValuesOnly parameter specifies whether to add fviValue type filter conditions only (see the TcxFilterValueList class).  Set the AValuesOnly parameter to False, to add all types of filter conditions;

The AInitSortByDisplayText parameter specifies whether filter items in the list are ordered by the display text or by value (see the SortByDisplayText property).  Set the AInitSortByDisplayText parameter to True to sort items by the display text;

The ACanUseFilteredValues parameter specifies whether all filter conditions, or only those that were applied to the item prior to the call, are added to the list.  Set the ACanUseFilteredValues parameter to True to only add criteria from the previously used filter.


TcxGridItemDataBinding.SetFilterActiveValueIndexes

TcxGridItemDataBinding          See Also

Applies filter conditions specified by their indexes to the currently processed item (a row or a column).

procedure SetFilterActiveValueIndexes(AValueList: TcxGridFilterValueList; const AIndexes: TcxGridIndexes);

Description

The AValueList parameter specifies a list of filter conditions;

The AIndexes parameter specifies a list of indexes that identify filter conditions to be applied to the item.


TcxCustomGridView
TcxCustomGridView Object

Hierarchy          Properties          Methods          Events          See Also

Represents the base class for all view classes.

Unit

cxGridCustomView

TcxCustomGridView = class(TcxControlChildComponent);

Description

The TcxCustomGridView class is the base class for all view classes.  It implements the base functionality for all views.  The main purpose of all view types is to specify the manner in which to display data.  A view class also encapsulates the master-detail data representation concept.

A master-detail data representation requires the presence of two views, connected to data sets linked by specific field values (see the Master-Detail topic for details).  Each time a particular master row gets expanded, the corresponding portion of the detail dataset is displayed.  A view representing that portion is called a "clone" view.  All "clone" views copy settings from the view corresponding to the detail hierarchy level.  That view is called "pattern" and represents the template for all detail views which appear when master rows are expanded.

"Pattern" views are not displayed at runtime, they only provide their settings for the creation of "clone" views.  However, each "clone" view may have individual settings, different from "pattern" view settings.  This may happen if a "pattern" view’s settings have been changed since a "clone" view appeared on the screen.  In order to recreate your "clone" views with new "pattern" settings, call DataController.ClearDetails.

The TcxCustomGridView members provide a user with information about the current view:

•	whether it is a detail or master view;

•	whether it is a pattern;

•	whether it has focus, etc.

They also specify the master view record for which the current view is displayed as a detail view, the grid level the current view belongs to, etc.  The TcxCustomGridView members allow you to:

•	access the current view’s collections of clones and styles;

•	define the appearance of the current view;

•	set the options managing the view selection and its visual settings;

•	specify the popup menu associated with the current view.


TcxCustomGridView Hierarchy
Hierarchy

TComponent

     |

TcxControlChildComponent

     |


Properties for TcxCustomGridView
TcxCustomGridView Properties

TcxCustomGridView          Legend

In TcxCustomGridView

CloneCount

Clones

Controller

DataController

DragMode

Focused

IsControlFocused

IsDetail

IsMaster

IsPattern

Level

MasterGridRecordIndex

MasterGridView

MasterRecordIndex

OptionsSelection

OptionsView

PatternGridView

PopupMenu

Site

Styles

Synchronization

ViewData

ViewInfo

Visible

Derived from TcxControlChildComponent

Control

IsDestroying

IsLoading


Methods for TcxCustomGridView
TcxCustomGridView Methods

TcxCustomGridView          Legend

In TcxCustomGridView

 BeginUpdate

 CancelUpdate

 EndUpdate

      GetHitTest

 LayoutChanged

 RestoreDefaults

 RestoreFromIniFile

 RestoreFromRegistry

 RestoreFromStream

 SizeChanged

 StoreToIniFile

 StoreToRegistry

 StoreToStream

 ViewChanged

Derived from TcxControlChildComponent

 CreateEx

 Destroy


Events for TcxCustomGridView
TcxCustomGridView Events

TcxCustomGridView          Legend

In TcxCustomGridView

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnGetStoredProperties

OnGetStoredPropertyValue

OnInitStoredObject

OnMouseDown

OnMouseEnter

OnMouseLeave

OnMouseUp

OnSetStoredPropertyValue

OnStartDrag


TcxCustomGridView.CloneCount

TcxCustomGridView          See Also

Returns the total number of copies of the current view.

property CloneCount: Integer;

Description

The CloneCount property contains the number of copies of the current view.  A copy of the current view is created each time the detail view, represented by the current TcxCustomGridView  (or its descendant) instance, becomes visible.  This instance is not removed from the Clones collection when the associated detail level is hidden.

ReadOnly Property


TcxCustomGridView.Clones

TcxCustomGridView          See Also

Represents the copies collection of the current view.

property Clones[Index: Integer]: TcxCustomGridView;

Description

Use the Clones property to gain access to the copies collection of the current view.  A copy of the current view is created each time the view, represented by the current TcxCustomGridView  (or its descendant) instance, becomes visible.  This instance is not removed from the Clones collection when the associated detail level is hidden.  The total number of created copies is stored in the CloneCount property.

ReadOnly Property


TcxCustomGridView.Controller

TcxCustomGridView

Specifies a view controller.

property Controller: TcxCustomGridController;

Description

The Controller property references a view controller encapsulating various operations on the current view.

TcxCustomGridController class implements only base operations common to all grid views.  Other view classes override the Controller property and use their own controllers.

ReadOnly Property


TcxCustomGridView.DataController

TcxCustomGridView

Specifies the data controller managing the current view’s data.

property DataController: TcxCustomDataController;

Description

Use the DataController property to access the object providing the connection between a grid view and data storage.  A data controller object implements the following features:

-	retrieving and posting data;

-	applying grouping;

-	applying filtering;

-	summary calculation.

ReadOnly Property


TcxCustomGridView.DragMode

TcxCustomGridView          See Also           Example

Specifies the manner in which views initiate drag-and-drop operations.

property DragMode: TDragMode;

Description

Set the DragMode property to dmAutomatic to start a drag-and-drop operation automatically when a user clicks and drags records within the current view.

When DragMode is set to dmManual, you need to start a drag-and-drop operation manually by handling the view’s OnMouseDown event.  dmManual mode gives you more capabilities as you can determine where drag-and-drop should start.  For instance, you can enable drag-and-drop only for odd/even records, specific items, etc.

To start drag-and-drop in dmManual mode, use the BeginDrag method of the view’s Site object.  The Site object (TcxGridSite class) represents a control incorporating a grid view.  It receives mouse and keyboard events, which are then passed as messages to the view, and it is responsible for painting the view.

See the OnDragOver and OnDragDrop events to implement the current view’s response to drag-and-drop operations.

The default value of the DragMode property is dmManual.


TcxCustomGridView.Focused

TcxCustomGridView          See Also

Determines whether the current view has focus.

property Focused: Boolean;

Description

Use the Focused property to determine whether the current view has focus.  If this property value is True, the current view has focus.  You can move focus from one view to another by changing the Focused property values for these views.


TcxCustomGridView.IsControlFocused

TcxCustomGridView

Indicates whether the grid control owning the current view has focus.

property IsControlFocused: Boolean;

Description

The IsControlFocused property indicates whether the grid control owning the current view has focus.

ReadOnly Property


TcxCustomGridView.IsDetail

TcxCustomGridView          See Also

Indicates whether the current view is placed at a child grid level.

property IsDetail: Boolean;

Description

The IsDetail property indicates whether the current view is placed at the child grid level.

ReadOnly Property


TcxCustomGridView.IsMaster

TcxCustomGridView          See also

Indicates whether the current view level has child views which can be displayed.

property IsMaster: Boolean;

Description

The IsMaster property indicates whether the current view level has child levels that can be displayed to a user.  IsMaster returns True if there are any detail levels whose Visible property is set to True.  Otherwise, IsMaster returns False.

ReadOnly Property


TcxCustomGridView.IsPattern

TcxCustomGridView          See Also

Indicates whether the current view is a "pattern" view.

property IsPattern: Boolean;

Description

The IsPattern property indicates whether the current view is a "pattern" view.  "Pattern" views are not displayed at runtime, they only provide settings for creating "clone" views.

Master-detail data representation requires the presence of two levels assigned to master and detail views respectively, connected to the data sets linked by field values (see the Master-Detail topic for details).  Each time a master row gets expanded, the corresponding portion of the detail data set is displayed.  A view representing that portion is called a "clone" view.  All "clone" views copy the settings from a view corresponding to the detail hierarchy level.  That view is called a "pattern" and represents a template for all detail views appearing when the master rows are expanded.

ReadOnly Property


TcxCustomGridView.Level

TcxCustomGridView

Returns the level owning the current view.

property Level: TComponent;

Description

The Level property returns the level owning the current view.  A grid level is an element of the hierarchical structure representing data within a view.  Levels are never displayed within the grid control; they only arrange associated views in the required order.  See the TcxGridLevel class description for details.

ReadOnly Property


TcxCustomGridView.MasterGridRecordIndex

TcxCustomGridView          See Also

Returns the index of the master view record for which the current view is displayed as a detail view.

property MasterGridRecordIndex: Integer;

Description

The MasterGridRecordIndex property returns the index of a master view record for which the current view is displayed as a detail view.  This index represents the master record position within a view, not within a data controller, i.e. this index is not necessarily equal to MasterRecordIndex property value.  The record’s position within a view may differ from that record’s position within a data controller after actions like sorting, grouping, expanding/collapsing of group rows, etc.

ReadOnly Property


TcxCustomGridView.MasterGridView

TcxCustomGridView          See Also

Returns a master view for the current view.

property MasterGridView: TcxCustomGridView;

Description

The MasterGridView property returns a view, which is the master view for the current one.  To determine whether the current view is a detail view, use the IsDetail property.  If this property value for the current view is False, the MasterGridView property returns nil.

ReadOnly Property


TcxCustomGridView.MasterRecordIndex

TcxCustomGridView          See Also

Returns the index of the master dataset record corresponding to a master view record.  The current view is displayed as a detail view.

property MasterRecordIndex: Integer;

Description

The MasterRecordIndex property returns the index of the master dataset record corresponding to a master view record.  The current view is displayed as a detail view.  This index is not necessarily equal to the MasterGridRecordIndex property value, which represents the master record position within a view, not within a data controller.  The record’s position within a view may differ from that record’s position within a data controller after actions like sorting, grouping, expanding/collapsing of group rows, etc.

ReadOnly Property


TcxCustomGridView.OptionsSelection

TcxCustomGridView

Contains selection options for the current view.

property OptionsSelection: TcxCustomGridOptionsSelection;

Description

The OptionsSelection property contains selection options for the current view.  These options indicate:

-	whether to select individual cells or entire rows;

-	whether a focus rectangle is displayed around the focused row;

-	whether multiple rows can be selected.


TcxCustomGridView.OptionsView

TcxCustomGridView

Contains view options for the current view.

property OptionsView: TcxCustomGridOptionsView;

Description

The OptionsView property provides access to the collection of options defining the appearance of the current view.  Generally, these options specify the visibility, color, width and other visual settings of the current view elements.  Sometimes these settings affect the view functionality by restricting operations associated with a grid view item (for instance, grouping, sorting, etc.).


TcxCustomGridView.PatternGridView

TcxCustomGridView          See Also

Returns the view whose copy is the current view.

property PatternGridView: TcxCustomGridView;

Description

The ParentGridView property represents a "pattern" view for the current view.  "Pattern" views are not displayed at runtime, they only provide settings for creating "clone" views.

Master-detail data representation requires the presence of two levels assigned to master and detail views respectively, connected to data sets linked by field values (see the Master-Detail topic for details).  Each time a master row gets expanded, the corresponding portion of the detail data set is displayed.  A view representing that portion is called a "clone" view.  All "clone" views copy the settings from a view corresponding to the detail hierarchy level.  That view is called a "pattern" and represents a template for all detail views appearing when the master rows are expanded.

ReadOnly Property


TcxCustomGridView.PopupMenu

TcxCustomGridView

Specifies the popup menu associated with the current view.

property PopupMenu: TComponent;

Description

In order to make a pop-up menu appear when the view is selected and an end user clicks it with the right mouse button, assign a value to the PopupMenu property.  This does not specify the current view as the popup menu's manager.  Instead, the popup menu is assigned to the site object associated with the view (see the Site property).


TcxCustomGridView.Site

TcxCustomGridView

Provides access to the control that holds the view.

property Site: TcxGridSite;

Description

Views in a grid control are arranged on specially designed controls represented by TcxGridSite objects.  This allows views to provide their own mouse and keyboard event handling.  Thus, view events that fire in response to mouse and keyboard actions together with drag and drop events pass the view’s owner site as their sender parameter.  When you obtain a grid site via an event’s parameter, you can determine the view that it holds using the site’s GridView property.

Use the Site property when you need to access the underlying control’s properties and methods.  For instance, you can use this property to access methods that allow you to start drag and drop operations.

In order to make a popup menu appear when the view is selected and an end user clicks it with the right mouse button, assign a value to the view’s PopupMenu property.

ReadOnly Property


TcxCustomGridView.Styles

TcxCustomGridView          See Also

Specifies the set of styles defining the appearance of the current view elements.

property Styles: TcxCustomGridStyles;

Description

Use the Styles property to gain access to a set of styles defining the appearance of the current view elements.  This set is expanded as the Styles property is overridden by TcxCustomGridView descendants.  In the base class, the Styles set includes a style defining the appearance of the current view background.


TcxCustomGridView.Synchronization

TcxCustomGridView          See Also

Determines whether all the "clone" views of the current detail view should be synchronized automatically with a "pattern" view.

property Synchronization: Boolean;

Description

Use the Synchronization property to determine whether all the "clone" views of the current detail view should be synchronized automatically with the "pattern" view.  If this property's value is set to True, all the "clone" views’ settings are kept synchronized with the "pattern" view, i.e. customizing a clone view’s settings (properties, event handlers) immediately affects the pattern view along with all the existing clones as all "clone" views will be synchronized with the "pattern" view since the "pattern" view’s settings have been changed. The synchronization process can take a significant amount of time to complete if there are a lot of "clone" views.  Set the detail view’s OptionsBehavior.PostponedSynchronization property to True to improve the performance of the synchronization as in this case only visible "clone" views will be synchronized.

Note:	When the Synchronization property is set to True, you should not call the DataController.ClearDetails method to recreate "clone" views with new "pattern" settings thus keeping all the clones synchronized.

The default value of the Synchronization property is True.  You can change this property's value for detail views only.


TcxCustomGridView.ViewData

TcxCustomGridView          See Also

Specifies the object adapting values provided by a data controller for the grid view’s data representation.

property ViewData: TcxCustomGridViewData;

Description

Use the ViewData property to access an object adapting the values provided by a data controller to display within a grid view.  This property refers to a TcxCustomGridViewData class instance.

ReadOnly Property


TcxCustomGridView.ViewInfo

TcxCustomGridView

Provides access to the object holding the information used to paint the view.

property ViewInfo: TcxCustomGridViewInfo;

Description

The information provided by the ViewInfo property’s return value is used internally and you will generally have no need to use this property in applications.

Note: Along with providing the view’s painting information, the returned object allows you to determine the view element located at a particular point.  Since version 5 of the grid control, this can also be performed using a view’s GetHitTest method.

ReadOnly Property


TcxCustomGridView.Visible

TcxCustomGridView

Indicates whether the current view is displayed.

property Visible: Boolean;

Description

Use the Visible property to indicate whether the current view is visible.  A view is visible when it is displayed on screen.

ReadOnly Property


TcxCustomGridView.BeginUpdate

TcxCustomGridView

Prevents the current view’s updates until the EndUpdate or CancelUpdate method is called.

procedure BeginUpdate;

Description

Calling the BeginUpdate method prevents the current view from repainting until the EndUpdate or the CancelUpdate method is called.  This mechanism helps improve the application’s performance.  To accept changes and to invalidate a view, call the EndUpdate method.  To accept changes without view invalidation, call the CancelUpdate method.


TcxCustomGridView.CancelUpdate

TcxCustomGridView

Enables the current view’s updates after calling the BeginUpdate method.

procedure CancelUpdate;

Description

After the BeginUpdate method is called, the grid view updates stop.  When all changes are complete, you should call the EndUpdate method, which enables updates.  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 view.


TcxCustomGridView.EndUpdate

TcxCustomGridView

Enables the current view’s updates after calling the BeginUpdate method.

procedure EndUpdate;

Description

Calling this method after the BeginUpdate method accepts all subsequent changes made to the current view and updates it.  Use the CancelUpdate method if the applied changes do not require view invalidation.


TcxCustomGridView.GetHitTest

TcxCustomGridViewInfo

Returns an object identifying the view’s element located at a particular point.

Overloaded Variants

function GetHitTest(const P: TPoint): TcxCustomGridHitTest; virtual;

function GetHitTest(X, Y: Integer): TcxCustomGridHitTest; virtual;

Description

Use the GetHitTest method to determine which view element is located under a particular point.  The method has two overloads that allow you to specify the test point either via a TPoint structure or via integer values specifying the horizontal and vertical coordinates.  Note that the coordinates should be specified relatively to the view’s top-left corner.

The GetHitTest method returns a TcxCustomGridHitTest descendant whose properties and methods allow you to identify the element under the test point.  First, you can use the returned object’s HitTestCode method to determine the element’s type.  The complete list of values that can be returned by this method can be found in the Grid View Elements topic.  In some cases, you will not only need to determine the element’s type.  For instance, if the test point is over a column header, you may want to determine the column whose header it is.  TcxCustomGridHitTest descendants provide additional properties for that purpose.  Please refer to the TcxCustomGridHitTest class description for details.


TcxCustomGridView.LayoutChanged

TcxCustomGridView

Updates the view in response to layout changes.

procedure LayoutChanged(AUpdateSelfOnly: Boolean = True;

Description

Use the LayoutChanged method to respond to layout changes.  The AUpdateSelfOnly parameter determines whether the current view only or all grid views within an appropriate grid control are updated.


TcxCustomGridView.RestoreDefaults

TcxCustomGridView          See Also

Restores the default view settings.

procedure RestoreDefaults; virtual;

Description

The RestoreDefaults method returns a view to its default settings.  For TcxCustomGridView descendants, this method restores the default settings for all view items.


TcxCustomGridView.RestoreFromIniFile

TcxCustomGridView          See Also           Example

Restores view-specific information from an INI file.

type

  TcxGridStorageOption = (gsoUseFilter, gsoUseSummary);

  TcxGridStorageOptions = set of TcxGridStorageOption;

procedure RestoreFromIniFile(const AStorageName: string; AChildrenCreating: Boolean = True; AChildrenDeleting: Boolean = False; AOptions: TcxGridStorageOptions = [gsoUseFilter, gsoUseSummary]; const ARestoreViewName: string = '');

Description

Use the RestoreFromIniFile method to restore the view-specific information from an INI file.  Restoring the view structure can be useful after changes have been applied to a view.  Before restoring the view structure, ensure that the view is connected to a data set containing fields assigned to the same view items as saved in the INI file.  Use the StoreToIniFile method to save view settings to an INI file.

View structure information includes: view class and instance names, bands, column or row settings (according to the view type).  Settings of grid view elements (bands, columns, card rows, etc.) specify the position and visibility within a view, caption, sort order, data binding settings etc.

The AStorageName parameter specifies the path and name of the INI file.

The AChildrenCreating parameter determines whether non-existent view elements (bands, columns and card view rows) that are present within an INI file are created within the view (this is done by default).  Conversely, the AChildrenDeleting parameter determines whether existing view elements that are not present within the INI file are deleted during restoring.  If the ARestoreViewName parameter defines a non-empty string, the AChildrenCreating and AChildrenDeleting parameters are ignored.

The AOptions parameter represents a set of options controlling whether the current filter and/or summaries should be restored.  By default, summaries and filter settings are restored from the INI file.  Although the restoring procedure allows you to recreate columns which have been deleted or which were not present in the view, summaries and filter settings for these columns cannot be restored correctly.

The ARestoreViewName parameter corresponds to the ASaveViewName parameter of the storing procedure.

If ASaveViewName is set to an empty string, the storing procedure saves the current view name in the storage.  Use this mode to store settings of a single view and then restore them in the same view.  Items are also saved by their names.  If an item is not assigned a name, its settings are not saved.  The AChildrenCreating and AChildrenDeleting parameters of the restoring procedure are in effect in this mode.

If the ASaveViewName parameter of the storing procedure specifies a non-empty string, the current view name is ignored and the view settings are stored under the specified name.  Items in this case are stored by their IDs.  ID is a unique identifier assigned to an item.  When you run the program, all items within a view are assigned unique zero-based IDs.  The ID of the first item is 0, the ID of the second one is 1, etc.  IDs provide the unique identity of the items within the view.  When an item is deleted, a newly created item might get the ID of the deleted item.  Thus the IDs of items won't be reused within the current state of the view, but may be reused within the lifetime of the view.  This is a limit unique to these IDs.

This mode allows you to save settings of one view and then apply them to (restore in) another view.  In this case, you have to set the ARestoreViewName parameter to the same value as ASaveViewName in the storing procedure.  The restoring procedure recognizes items in the view by their IDs, i.e. if the storage contains settings for items with IDs equal to 0, 1, and 4, for instance, they are applied to the items in the current view with the same IDs (0, 1,and 4).  Note that the view, to which settings are applied, must be connected to the same dataset as the original view.  In this mode, no new items are created and no existing items are deleted when restoring (the AChildrenCreating and AChildrenDeleting parameters are not in effect).  See the example.

To customize the list of the view’s properties which are restored from an INI file, use the OnSetStoredPropertyValue event.

Note:	You can handle the OnInitStoredObject event to properly initialize the object which corresponds to the re-created view element (provided that the RestoreFromIniFile method is called with True passed for the AChildrenCreating parameter) by re-associating its events with existing event handlers and assigning its properties.


TcxCustomGridView.RestoreFromRegistry

TcxCustomGridView          See Also           Example

Restores view-specific information from the registry.

type

  TcxGridStorageOption = (gsoUseFilter, gsoUseSummary);

  TcxGridStorageOptions = set of TcxGridStorageOption;

procedure RestoreFromRegistry(const AStorageName: string; AChildrenCreating: Boolean = True; AChildrenDeleting: Boolean = False; AOptions: TcxGridStorageOptions = [gsoUseFilter, gsoUseSummary]; const ARestoreViewName: string = '');

Description

Use the RestoreFromRegistry method to restore view-specific information from the registry.  Restoring the view structure can be useful after changes have been applied to a view.  Before restoring the view structure, ensure that the view is connected to a data set containing the same fields as were assigned to the view items saved in a registry key (by using the StoreToRegistry method).

View structure information includes: view class and instance names, bands, column or row settings (according to the view type).  Settings of grid view elements (bands, columns, card rows, etc.) specify the position and visibility within a view, caption, sort order, data binding settings etc.

The registry path for the view information is formed by adding the AStorageName suffix to the HKEY_CURRENT_USER key.

For the information on the other parameters, see the description of the RestoreFromIniFile method.

To customize the list of the view’s properties which are restored from the registry, use the OnSetStoredPropertyValue event.

Note:	You can handle the OnInitStoredObject event to properly initialize the object which corresponds to the re-created view element (provided that the RestoreFromRegistry method is called with True passed for the AChildrenCreating parameter) by re-associating its events with existing event handlers and assigning its properties.


TcxCustomGridView.RestoreFromStream

TcxCustomGridView          See Also           Example

Restores view-specific information from a stream.

type

  TcxGridStorageOption = (gsoUseFilter, gsoUseSummary);

  TcxGridStorageOptions = set of TcxGridStorageOption;

procedure RestoreFromStream(AStream: TStream; AChildrenCreating: Boolean = True; AChildrenDeleting: Boolean = False; AOptions: TcxGridStorageOptions = [gsoUseFilter, gsoUseSummary]; const ARestoreViewName: string = '');

Description

Use the RestoreFromStream method to restore view-specific information from a stream.  Restoring the view structure can be useful after changes have been applied to a view.  Before restoring the view structure, ensure that the view is connected to a data set containing the same fields as were assigned to the view items saved in a stream (by using the StoreToStream method).

View structure information includes: view class and instance names, bands, column or row settings (according to the view type).  Settings of grid view elements (bands, columns, card rows, etc.) specify the position and visibility within a view, caption, sort order, data binding settings and etc.

The AStream parameter identifies an instance of the TStream class or its descendant where the view information is stored.

For the information on the other parameters, see the description of the RestoreFromIniFile method.

To customize the list of the view’s properties which are restored from a stream, use the OnSetStoredPropertyValue event.

Note:	You can handle the OnInitStoredObject event to properly initialize the object which corresponds to the re-created view element (provided that the RestoreFromStream method is called with True passed for the AChildrenCreating parameter) by re-associating its events with existing event handlers and assigning its properties.


TcxCustomGridView.SizeChanged

TcxCustomGridView

Responds to view resizing.

procedure SizeChanged(AUpdateSelfOnly: Boolean = False);

Description

The SizeChanged method responds to view resizing.  For internal use only.


TcxCustomGridView.StoreToIniFile

TcxCustomGridView          See Also           Example

Saves view-specific information to an INI file.

type

  TcxGridStorageOption = (gsoUseFilter, gsoUseSummary);

  TcxGridStorageOptions = set of TcxGridStorageOption;

procedure StoreToIniFile(const AStorageName: string; AReCreate: Boolean = True; AOptions: TcxGridStorageOptions = []; const ASaveViewName: string = '');

Description

Use the StoreToIniFile method to save view-specific information to an INI file.  This information can be restored after changes have been applied to a view.  View structure is restored after the RestoreFromIniFile method call.  Before restoring the view structure, ensure that the view is connected to a data set containing data fields assigned to the same view items as saved in the INI file.

View structure information includes: view class and instance names, bands, column or row settings (according to the view type).  View element (bands, grid columns, card rows, etc.) settings specify the position and visibility within a view, caption, sort order, data binding settings etc.

The AStorageName parameter specifies the path and name of the file where to store view settings.

The AReCreate parameter determines whether the required INI file is recreated via each call of the StoreToIniFile method.  If this parameter value is True, then the existing INI file is deleted and then created again.  Otherwise, information is appended to the end of the existing file.

For information on the AOptions and ASaveViewName parameters, see the description of the RestoreFromIniFile method.

To customize the list of the view’s properties which are saved to an INI file, use the OnGetStoredProperties and OnGetStoredPropertyValue events.


TcxCustomGridView.StoreToRegistry

TcxCustomGridView          See Also           Example

Stores view-specific information to the registry.

type

  TcxGridStorageOption = (gsoUseFilter, gsoUseSummary);

  TcxGridStorageOptions = set of TcxGridStorageOption;

procedure StoreToRegistry(const AStorageName: string; AReCreate: Boolean = True; AOptions: TcxGridStorageOptions = []; const ASaveViewName: string = '');

Description

Use the StoreToRegistry method to save view-specific information to the registry.  This information can be restored after the changes have been applied to a view.  Use the RestoreFromRegistry method to restore the view structure.  Before restoring the view structure, ensure that the view is connected to a data set containing the same fields assigned to the view items as were saved in a registry key.

View structure information includes: view class and instance names, bands, column or row settings (according to the view type).  View element (bands, columns, card rows, etc.) settings specify the position and visibility within a view, caption, sort order, data binding settings and etc.

The registry path for the view information is formed by adding the AStorageName suffix to the HKEY_CURRENT_USER key.

The AReCreate parameter determines whether the required key is recreated via each call of the StoreToRegistry method.  If this parameter value is True, then the existing registry key is deleted and then created again.  Otherwise, information is appended to the existing key.

For information on the AOptions and ASaveViewName parameters, see the description of the RestoreFromIniFile method.

To customize the list of the view’s properties which are saved to the registry, use the OnGetStoredProperties and OnGetStoredPropertyValue events.


TcxCustomGridView.StoreToStream

TcxCustomGridView          See Also           Example

Saves the view-specific information to a stream.

type

  TcxGridStorageOption = (gsoUseFilter, gsoUseSummary);

  TcxGridStorageOptions = set of TcxGridStorageOption;

procedure StoreToStream(AStream: TStream; AOptions: TcxGridStorageOptions = []; const ASaveViewName: string = '')

Description

Use the StoreToStream method to save view-specific information to a stream.  This information can be restored after changes have been applied to a view.  Use the RestoreFromStream method to restore the view structure.  Before restoring the view structure, ensure that the view is connected to a data set containing the same fields as were assigned to the view items when saved to the stream.

View structure information includes: view class and instance names, bands, column or row settings (according to the view type).  View element (bands, columns, card rows, etc.) settings specify the position and visibility within a view, caption, sort order, data binding settings and etc.

The AStream parameter identifies an instance of the TStream class or its descendant where the view information is stored.

For information on the AOptions and ASaveViewName parameters, see the description of the RestoreFromIniFile method.

To customize the list of the view’s properties which are saved to a stream, use the OnGetStoredProperties and OnGetStoredPropertyValue events.


TcxCustomGridView.ViewChanged

TcxCustomGridView

Invalidates a view or view area.

Overloaded Variants

procedure ViewChanged; overload;

procedure ViewChanged(const AUpdateRect: TRect); overload;

Description

The ViewChanged method invalidates a view or view region.  Use the first variant of this method to update the entire view.  Use the second overloaded variant of this method to invalidate a view region.  The AUpdateRect parameter specified the region to invalidate.


TcxCustomGridView.OnDblClick

TcxCustomGridView          See Also          Example

Occurs when an end-user double-clicks within the current view.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnDblClick: TNotifyEvent;

Description

Handle the OnDblClick event to perform specific actions when an end user double-clicks within the current view.  See the example on how to invoke a dialog in response to a double-click.


TcxCustomGridView.OnDragDrop

TcxCustomGridView          See Also

Occurs when a user drops the object being dragged within the current view.

type

  TDragDropEvent = procedure(Sender, Source: TObject; X, Y: Integer) of object;

property OnDragDrop: TDragDropEvent;

Description

Handle the OnDragDrop event to perform actions when a user drops the object being dragged within the current view.  The Source parameter represents the object being dropped and the Sender parameter indirectly refers to the current view. The X and Y parameters are the coordinates of the mouse positioned over the view.

Grid views are not controls (i.e. do not descend from TControl), so they cannot receive keyboard and mouse messages and thus cannot be involved in drag-and-drop directly.  To overcome this problem, grid views are placed onto grid sites (TControl descendants), which interact with the user and pass appropriate messages to views.  A grid site is an object of the TcxGridSite class.  The view owned by a site is addressed by the TcxGridSite.GridView property.

In drag-and-drop operations, grid views are represented by their grid sites.  The Sender parameter identifies the grid site containing the current view.

If the source of a drag-and-drop operation is a grid view, the Source parameter refers to a TcxDragControlObject object with the Control property set to a grid site.  If the source is a grid control itself, the Source parameter is still a TcxDragControlObject object, but its Control property refers to the TcxGrid object.

You can use the following code to get the grid view which is the source of a drag-and-drop operation:

//Delphi

procedure TForm1.tvTargetDragDrop(Sender, Source: TObject; X, Y: Integer);

var

  ADroppedView: TcxCustomGridView;

begin

  if Source is TcxDragControlObject then

    with TcxDragControlObject(Source) do

      if Control is TcxGridSite then

        with TcxGridSite(Control) do

        begin

          ADroppedView := GridView;

          //...

        end;

end;

//C++ Builder

void __fastcall TForm1::tvTargetDragDrop(TObject *Sender, TObject *Source, int X, int Y)

{

  TcxCustomGridView * ADroppedView;

  TcxDragControlObject * DragObject;

  TcxGridSite * GSite;

  if (DragObject = dynamic_cast<TcxDragControlObject*>(Source))

    if (GSite = dynamic_cast<TcxGridSite*>(DragObject->Control))

    {

      ADroppedView = GSite->GridView;

      //...

    }

}

To implement drag-and-drop, you need to handle the OnDragOver event as well.  Use this event to decide whether drag-and-drop is possible at a given point.


TcxCustomGridView.OnDragOver

TcxCustomGridView          See Also

Occurs when a user drags an object over the current view.

type

  TDragOverEvent = procedure(Sender, Source: TObject; X, Y: Integer; State: TDragState; var Accept: Boolean) of object;

property OnDragOver: TDragOverEvent;

Description

Write an OnDragOver handler to enable/disable a drag and drop operation at a given point.  Set the Accept property to False to reject the object being dragged.  Set Accept to True to enable object dropping.  In this case, when a user drops an object, the OnDragDrop event is fired.  The Source parameter is the object being dragged.  Sender refers indirectly to the grid site (a TcxGridSite object) containing the current view.  Refer to the OnDragDrop event description for more information on the Sender and Source parameters.

The X and Y parameters are the coordinates of the mouse positioned over the control.

The State parameter specifies the manner in which the dragged object moves over the control.

The following example shows an OnDragOver event handler which accepts a dragged object if the source of the drag-and-drop operation is the tvCustomers view:

//Delphi

procedure TForm1.tvTargetDragOver(Sender, Source: TObject; X, Y: Integer; State: TDragState; var Accept: Boolean);

begin

  Accept := False;

  if Source is TcxDragControlObject then

    with TcxDragControlObject(Source) do

      if Control is TcxGridSite then

        with TcxGridSite(Control) do

          Accept := (GridView.PatternGridView = tvCustomers) ;

end;

//C++ Builder

void __fastcall TForm1::tvTargetDragOver(TObject *Sender, TObject *Source, int X, int Y, TDragState State, bool &Accept)

{

  Accept = false;

  TcxDragControlObject * DragObject;

  TcxGridSite * GSite;

  if (DragObject = dynamic_cast<TcxDragControlObject*>(Source))

    if (GSite = dynamic_cast<TcxGridSite*>(DragObject->Control))

      Accept = (GSite->GridView->PatternGridView == tvCustomers);

}


TcxCustomGridView.OnEndDrag

TcxCustomGridView          See Also

Occurs when finishing dragging an object.

type

  TEndDragEvent = procedure(Sender, Target: TObject; X, Y: Integer) of object;

property OnEndDrag: TEndDragEvent;

Description

The OnEndDrag event occurs when the dragging of an object ends, either by dropping the object or by canceling the dragging.  Use the OnEndDrag event handler to specify any special processing that occurs when dragging stops.

X and Y specify the coordinates of the event relative to the target control which has accepted the dropped object.  The target control is passed as the Target parameter.  If Target is set to NIL, the dragged object was rejected.

The Sender parameter provides the grid site (TcxGridSite) object referring to the current view.  If the target of the drag-and-drop event is a grid view, the Target parameter is also a grid site.  A grid site is a control which owns views, processes mouse and keyboard events and paints views.  To access the view displayed by a site object, see the TcxGridSite.GridView property.


TcxCustomGridView.OnGetStoredProperties

TcxCustomGridView          See Also          Example

Occurs when the list of the current view’s properties that will be stored in external storage is produced.

type

  TcxGridViewGetStoredPropertiesEvent = procedure(Sender: TcxCustomGridView; AProperties: TStrings) of object;

property OnGetStoredProperties: TcxGridViewGetStoredPropertiesEvent;

Description

Handle the OnGetStoredProperties event to customize the list of the current view’s properties that will be stored in external storage, e.g. a file, the registry or a stream.  Whenever the storing process is started, a list of the properties to store is produced.  When this event is fired, the list already consists of the view properties’ names which are stored by default. The set of properties in the list depends on the view type (whether it is a (banded) table, card view or chart view, its version and whether it is data-aware or not).

The Sender parameter specifies the grid view object whose properties will be stored.

The AProperties parameter specifies the list of properties to be stored.

See the example on how to use this event.


TcxCustomGridView.OnGetStoredPropertyValue

TcxCustomGridView          See Also          Example

Occurs when the values of the current view’s properties are stored in external storage.

type

  TcxGridViewGetStoredPropertyValueEvent = procedure(Sender: TcxCustomGridView; const AName: string; var AValue: Variant) of object;

property OnGetStoredPropertyValue: TcxGridViewGetStoredPropertyValueEvent;

Description

Whenever you have customized the list of the properties to be stored in external storage in the OnGetStoredProperties event you should handle the OnGetStoredPropertyValue event to specify their values.  These values will be saved in the resulting output.

The Sender parameter specifies the grid view object whose properties will be stored.

The AName parameter denotes the name of the current view’s property in the resulting output.

In order to store a specific value for the AName property, set its value to the AValue parameter.

See the example on how to use this event.


TcxCustomGridView.OnInitStoredObject

TcxCustomGridView          See Also          Example

Occurs when a non-existent view element that is present within storage is created within the view.

type

  TcxGridInitStoredObjectEvent = procedure(Sender: TcxCustomGridView; AObject: TObject) of object;

property OnInitStoredObject: TcxGridInitStoredObjectEvent;

Description

When the view is restored from storage (an INI file, stream or the registry) by calling the corresponding method (RestoreFromIniFile, RestoreFromStream or RestoreFromRegistry) and a non-existent view element (a band, column, card row, etc.) is present within storage, the element is created within the view (provided that the method is called with True passed as the AChildrenCreating parameter).  After it’s been created, the OnInitStoredObject event is fired.  You can handle this event to properly initialize the object which corresponds to the created view element by re-associating its events with existing event handlers and assigning its properties.

The view being restored from storage and the view element that has been created are passed as the Sender and AObject parameters of the OnInitStoredObject event, respectively.

See the example on how to use this event.


TcxCustomGridView.OnMouseDown

TcxCustomGridView          See Also

Occurs when an end-user presses a mouse button and the mouse pointer is located over the current view.

type

  TMouseEvent = procedure(Sender: TObject; Button: TMouseButton; Shift: TShiftState; X, Y: Integer) of object;

property OnMouseDown: TMouseEvent;

Description

Handle the OnMouseDown event to perform specific actions when an end-user presses a mouse button and the mouse pointer is located over the current view.

Refer to the Understanding HitTests topic for general tips on implementing responses to mouse clicks when the mouse pointer is located over a particular grid view element.

Note:	You can also handle the view’s OnMouseUp event to perform specific actions when an end-user releases the pressed mouse button.


TcxCustomGridView.OnMouseEnter

TcxCustomGridView          See Also

Occurs when the mouse pointer moves over the current view.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnMouseEnter: TNotifyEvent;

Description

Handle the OnMouseEnter event to perform specific actions when an end-user moves the mouse over the current view.  For example, you can use this event to highlight the elements in the current view when the mouse pointer is over the view, and then use the OnMouseLeave event to reverse its appearance back to the default when the mouse leaves the current view.


TcxCustomGridView.OnMouseLeave

TcxCustomGridView          See Also

Occurs when the mouse pointer leaves the current view.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnMouseLeave: TNotifyEvent;

Description

Handle the OnMouseLeave event to perform specific actions when an end-user moves the mouse pointer off the current view.  For example, you can use this event to undo any changes that were made in the OnMouseEnter event handler.


TcxCustomGridView.OnMouseUp

TcxCustomGridView          See Also

Occurs when an end-user releases a mouse button that was pressed and the mouse pointer is located over the current view.

type

  TMouseEvent = procedure(Sender: TObject; Button: TMouseButton; Shift: TShiftState; X, Y: Integer) of object;

property OnMouseUp: TMouseEvent;

Description

Handle the OnMouseUp event to perform specific actions (for instance, showing popup menus) when an end-user releases a mouse button that was pressed and the mouse pointer is located over the current view.

Refer to the Understanding HitTests topic for general tips on implementing responses to mouse clicks when the mouse pointer is located over a particular grid view element.

Note:	You can also handle the view’s OnMouseDown event to perform specific actions when an end-user presses a mouse button.


TcxCustomGridView.OnSetStoredPropertyValue

TcxCustomGridView          See Also          Example

Occurs when the values of the current view’s properties are restored from external storage.

type

  TcxGridViewSetStoredPropertyValueEvent = procedure(Sender: TcxCustomGridView; const AName: string; const AValue: Variant) of object;

property OnSetStoredPropertyValue: TcxGridViewSetStoredPropertyValueEvent;

Description

In order to restore the values of the current view’s properties which are not stored by default and whose names and values were explicitly specified in the OnGetStoredProperties and OnGetStoredPropertyValue events correspondingly, handle the OnSetStoredPropertyValue event.  These values will be saved in the resulting output.

The Sender parameter specifies the grid view object whose properties are being restored.

The AName parameter denotes the name of the current view’s property in the resulting output whose value is being restored from storage and is returned by the AValue parameter.

See the example on how to use this event.


TcxCustomGridView.OnStartDrag

TcxCustomGridView          See Also           Example

Occurs when a user starts dragging by left-clicking the current view.

type

  TStartDragEvent = procedure(Sender: TObject; var DragObject: TDragObject) of object;

property OnStartDrag: TStartDragEvent;

Description

Handle the OnStartDrag event to perform special processing when a user starts dragging within the current view.

The Sender parameter specifies the grid site (TcxGridSite) object referring to the current view.  A grid site is a control which owns views and processes mouse and keyboard events.  To access the view displayed by a site object, see the TcxGridSite.GridView property.

During drag-and-drop, a drag object is created.  It refers to the control within which the operation was started.  The drag object is passed as the Source parameter to the OnDragOver and OnDragDrop event handlers of the target control.

By default, the drag object represents an instance of the TcxDragControlObject class.  If drag-and-drop starts within a grid view, the Control property of the drag object refers to the grid site owning the view.  If drag-and-drop starts within root level tabs of a grid, the Control property refers to the grid control itself.

The OnStartDrag event allows you to use a custom drag object.  You can implement your own type of drag object by deriving from TDragObject or its descendants (TDragControlObjectEx, TDragControlObject).  The drag object can provide the target control with more information on the source control.  A custom drag object can also be implemented to provide a specific drag cursor or drag image list to display while dragging.  In the OnStartDrag event handler, create an instance of your drag object and assign it to the DragObject parameter.

The initial value of DragObject is NIL.  If the OnStartDrag event handler sets DragObject to NIL, a TcxDragControlObject object is automatically created and subsequently available to the source control.


TcxGridStorageOption
TcxGridStorageOption type

See Also

Enumerates the options controlling the storing/restoring of view settings.

Unit

cxGridCustomView

type

  TcxGridStorageOption = (gsoUseFilter, gsoUseSummary);

Description

Use the StoreToIniFile, StoreToStream and StoreToRegistry methods to store view specific information in an INI file, stream or the registry use the view’s, respectively.

The following table lists all the possible options which control the parts of a view saved and restored:

Value	Description
gsoUseFilter	Indicates whether to store/restore filter settings and criteria.
gsoUseSummary	Indicates whether to store/restore summaries.


TcxGridStorageOptions
TcxGridStorageOptions type

See Also

Represents the set of options controlling storing/restoring view specific.

Unit

cxGridCustomView

type

  TcxGridStorageOption = (gsoUseFilter, gsoUseSummary);

  TcxGridStorageOptions = set of TcxGridStorageOption;

Description

You can use the view’s StoreToIniFile, StoreToRegistry and StoreToStream methods to save view specific settings to an INI file, registry and stream respectively.

The TcxGridStorageOptions type specifies a set of options which control the storing of filter settings and summaries when using these methods.


TcxCustomGridHitTest
TcxCustomGridHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information about a point in the grid.

Unit

cxGridCustomView

TcxCustomGridHitTest = class(TObject)

Description

The HitTest objects contain information on a specific point in the grid such as:

•	Hit test position (offset in pixels from the upper left corner of the grid, equal to the ViewInfo.GetHitTest method's parameters) which is accessible via the Pos property.

•	Hit test code (unique identifier for the grid element) which is accessible via the HitTestCode function.

•	Mouse pointer (default image used to represent the mouse pointer at the inspected point) which is accessible via the Cursor function.

•	Element-specific information (depends upon the HitTest class).

The value returned by the HitTestCode method is called hit code.  A full list of the Hit Codes and grid elements associated with them is described in the Grid View Elements topic.  Please refer to the Understanding HitTests topic for basic information on HitTests and hit codes.

You shouldn't create any HitTest class instances directly.  They are created automatically on demand.


TcxCustomGridHitTest Hierarchy
Hierarchy

TObject

     |


Properties for TcxCustomGridHitTest
TcxCustomGridHitTest Properties

TcxCustomGridHitTest          Legend

In TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxCustomGridHitTest
TcxCustomGridHitTest Methods

TcxCustomGridHitTest          Legend

In TcxCustomGridHitTest

Cursor

HitTestCode


TcxCustomGridHitTest.Pos

TcxCustomGridHitTest

Provides the coordinates of the grid test point.

property Pos: TPoint;

Description

The Pos property represents the HitTest position offset in pixels from the upper left corner of the grid (i.e. relative coordinates) and is equal to the ViewInfo.GetHitTest method's parameters.

ReadOnly Property


TcxCustomGridHitTest.ViewInfo

TcxCustomGridHitTest

Provides access to information on the visual properties of the grid element that initiated the current hit test.

property ViewInfo: TcxCustomGridCellViewInfo;

Description

Use the ViewInfo property to access basic information such as its size and position within the grid for the grid element that initiated the current hit test.


TcxCustomGridHitTest.Cursor

TcxCustomGridHitTest

Specifies the image used to represent the mouse pointer when the mouse pointer is over the inspected grid element.

class function Cursor: TCursor; virtual;

Description

The Cursor function provides feedback to end-users when the mouse pointer hovers over the inspected grid element.  The return value of the Cursor function represents the index of the cursor in the list of cursors maintained by the global variable, Screen (see the TCursor type description for details) or custom cursors added by an application.  By default, the Cursor function returns crDefault.  This indicates that the default cursor for the window class (usually, crArrow) will be displayed for the inspected grid element.

TcxCustomGridHitTest descendants override the Cursor function to provide return values specific to the grid elements that they’re associated with.


TcxCustomGridHitTest.HitTestCode

TcxCustomGridHitTest

Returns the hit code of the inspected grid element.

class function HitTestCode: Integer;

Description

The HitTestCode function returns the unique identifier (called Hit Code) of the grid element being inspected.  The initial value returned by this function is htError which indicates that the grid element is not associated with any hit code.  Each TcxCustomGridHitTest descendant provides a meaningful hit code specific to the grid element it’s associated with.

A full list of the hit codes and the grid view elements that are associated with them is described in the Grid View Elements topic.


TcxCustomGridViewHitTest
TcxCustomGridViewHitTest Object

Hierarchy          Properties          Methods

Provides general information for the Grid View’s point.

Unit

cxGridCustomView

TcxCustomGridViewHitTest = class(TcxCustomGridHitTest)

Description

The TcxCustomGridViewHitTest class provides general information on the grid view elements.  Note that the TcxCustomGridHitTest class does the same for the grid elements.  This results in adding the GridView property that provides access to the corresponding Grid View’s properties and methods.

You shouldn't create any HitTest class instances directly.  They are created automatically on demand.


TcxCustomGridViewHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |


Properties for TcxCustomGridViewHitTest
TcxCustomGridViewHitTest Properties

TcxCustomGridViewHitTest          Legend

In TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxCustomGridViewHitTest
TcxCustomGridViewHitTest Methods

TcxCustomGridViewHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxCustomGridViewHitTest.GridView

TcxCustomGridViewHitTest

Provides access to the corresponding Grid View’s properties and methods.

property GridView: TcxCustomGridView;

Description

The GridView property enables you to access the properties and method of the Grid View whose point is being inspected.


TcxGridSite
TcxGridSite Object

Hierarchy          Properties          Methods          Events          See Also           Example

Represents a control containing a single view within EQGrid5.

Unit

cxGridCustomView

TcxGridSite = class(TcxControl)

Description

TcxGridSite is a control containing views within EQGrid5.  A grid site receives and handles mouse, keyboard and drag-and-drop events and passes appropriate messages to a corresponding view object.

A grid site is responsible for rendering views.  It draws views on its surface with the help of the ViewInfo object, which is passed as a parameter of the TcxGridSite constructor and can then be accessed via the Viewinfo property.  The Viewinfo object provides information on sizes of grid view elements.  The view displayed by the site is returned by the GridView property.

When a grid control represents a master-detail relationship, a grid site of a master view contains grid sites of detail views.

A grid site is passed as the Sender parameter to various mouse and keyboard events of a view object (OnMouseDown, OnMouseWheel, OnKeyDown, etc).

A grid site provides the ability to display a pop-up menu within a specific view when it is selected and an end user then clicks it with the right mouse button.  Assign a pop-up menu object to the PopupMenu property for this purpose.


TcxGridSite Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |


Properties for TcxGridSite
TcxGridSite Properties

TcxGridSite          Legend

In TcxGridSite

Container

GridView

ViewInfo

Derived from TcxControl

BorderStyle

Bounds

Canvas

ClientBounds

FocusOnClick

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxGridSite
TcxGridSite Methods

TcxGridSite          Legend

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxGridSite
TcxGridSite Events

TcxGridSite          Legend

Derived from TcxControl

OnMouseEnter

OnMouseLeave


TcxGridSite.GridView

TcxGridSite          See Also

Specifies the view contained within a grid site object.

property GridView: TcxCustomGridView;

Description

You can use the GridView property to access properties of the view object, which is displayed by the current grid site.  The TcxCustomGridView class is the base class for all views provided by EQGrid.

A grid view represents records in a specific form (table views represent records as rows; card views represent them as cards).  See the Views section for more information.

ReadOnly Property


TcxGridSite.Container

TcxGridSite

Specifies the grid control containing a site object.

property Container: TcxControl;

Description

The Container property returns an instance of the TcxGrid class, which contains the current grid site control.

ReadOnly Property


TcxGridSite.ViewInfo

TcxGridSite

Returns the object describing the elements of the grid view (i.e. displayed by a grid site object).

property ViewInfo: TcxCustomGridViewInfo;

Description

The ViewInfo object provides information on sizes of grid view elements (records, filter, footer, indicator panels etc).  ViewInfo is used when drawing a view on the graphical surface of a grid site control.

Every view available within EQGrid provides its own ViewInfo class, which contains view specific data.  The TcxCustomGridViewInfo class is the base class for ViewInfo objects of all views.

ReadOnly Property


TcxGridNoneHitTest
TcxGridNoneHitTest Object

Hierarchy          Properties          Methods          See Also

Represents the HitTest object for any point within the grid which doesn’t contain any visible Views.

Unit

cxGridCustomView

TcxGridNoneHitTest = class(TcxCustomGridHitTest)

Description

The TcxGridNoneHitTest class does not introduce any new functionality, but instead designates the hit code (which is equal to htNone) of any point within or outside the grid which doesn’t contain any visible Views.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridNoneHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |


Properties for TcxGridNoneHitTest
TcxGridNoneHitTest Properties

TcxGridNoneHitTest          Legend

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridNoneHitTest
TcxGridNoneHitTest Methods

TcxGridNoneHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridViewNoneHitTest
TcxGridViewNoneHitTest Object

Hierarchy          Properties          Methods          See Also

Represents the HitTest object for an empty point in the Grid View.

Unit

cxGridCustomView

TcxGridViewNoneHitTest = class(TcxCustomGridViewHitTest)

Description

The TcxGridViewNoneHitTest class represents the HitTest object for an empty point in the Grid View (a point in the View where there are no grid view elements).  The TcxGridViewNoneHitTest class doesn’t introduce any new functionality, but instead designates the hit code (which is equal to htNone) of an empty point in the Grid View.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridViewNoneHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |


Properties for TcxGridViewNoneHitTest
TcxGridViewNoneHitTest Properties

TcxGridViewNoneHitTest          Legend

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridViewNoneHitTest
TcxGridViewNoneHitTest Methods

TcxGridViewNoneHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridDesignSelectorHitTest
TcxGridDesignSelectorHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the view selector located at the point being tested.

Unit

cxGridCustomView

TcxGridDesignSelectorHitTest = class(TcxCustomGridViewHitTest)

Description

The TcxGridDesignSelectorHitTest class does not introduce any new functionality, but instead designates the hit code (equal to htDesignSelector) of the view selector which is located at the Grid View’s point being tested.  The view selector is only visible at design time.  Hit information can be useful when implementing a subclass of any view.

To learn more about basic HitTest concepts, review the description of the TcxCustomGridHitTest class.


TcxGridDesignSelectorHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxGridDesignSelectorHitTest


Properties for TcxGridDesignSelectorHitTest
TcxGridDesignSelectorHitTest Properties

TcxGridDesignSelectorHitTest          Legend

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridDesignSelectorHitTest
TcxGridDesignSelectorHitTest Methods

TcxGridDesignSelectorHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridNavigatorHitTest
TcxGridNavigatorHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the view navigator which is located at the point being tested.

Unit

cxGridCustomView

TcxGridNavigatorHitTest = class(TcxCustomGridViewHitTest)

Description

The TcxGridNavigatorHitTest class does not introduce any new functionality, but instead designates the hit code (which is equal to htNavigator) of the view navigator which is located at the Grid View’s point that is being tested.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridNavigatorHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |


Properties for TcxGridNavigatorHitTest
TcxGridNavigatorHitTest Properties

TcxGridNavigatorHitTest          Legend

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridNavigatorHitTest
TcxGridNavigatorHitTest Methods

TcxGridNavigatorHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


cxGridCustomView Unit Overview
cxGridCustomView Unit

Classes

TcxCustomGridBackgroundBitmaps

TcxCustomGridCellViewInfo

TcxCustomGridController

TcxCustomGridOptions

TcxCustomGridOptionsBehavior

TcxCustomGridOptionsSelection

TcxCustomGridOptionsView

TcxCustomGridViewCellViewInfo

TcxCustomGridViewData

TcxCustomGridHitTest

TcxCustomGridStyles

TcxCustomGridView

TcxCustomGridViewHitTest

TcxCustomGridViewStyles

TcxGridDesignSelectorHitTest

TcxGridNavigatorHitTest

TcxGridNoneHitTest

TcxGridSite

TcxGridViewHandler

TcxGridViewNoneHitTest


TcxCustomGridViewData
TcxCustomGridViewData Object

Hierarchy          Properties          Methods          See Also

Represents the base class for classes providing data to a view.

Unit

cxGridCustomView

TcxCustomGridViewData = class(TcxGridViewHandler);

Description

TcxCustomGridViewData is an abstract class that provides basic functionality for classes which supply information to a view (TcxCustomGridView) in a convenient form.  It acts as a conduit between the view and a data controller providing data from a data storage.

The TcxCustomGridViewData class provides access to several objects affecting the view’s functionality and appearance:

•	DataController – handles data posting and retrieval from a data set;

•	Controller – processes keyboard and mouse messages;

•	Painter – implements drawing of the grid control;

•	ViewInfo – calculates grid element sizes and provides information for the painter.

The TcxCustomGridViewData class inherits all its functionality from its ancestor and publishes the DataController property.

TcxCustomGridTableViewData derives from the TcxCustomGridViewData class and presents data as an array of records, each of which is a TcxCustomGridRecord object.


TcxCustomGridViewData Hierarchy
Hierarchy

TObject

     |

TcxGridViewHandler

     |


Properties for TcxCustomGridViewData
TcxCustomGridViewData Properties

TcxCustomGridViewData          Legend

Derived from TcxGridViewHandler

Control

Controller

DataController

GridView

ViewData


Methods for TcxCustomGridViewData
TcxCustomGridViewData Methods

TcxCustomGridViewData          Legend

In TcxCustomGridViewData

 IsEmpty

 MakeDetailVisible

Derived from TcxGridViewHandler

 BeginUpdate

 Create

 EndUpdate


TcxCustomGridViewData.IsEmpty

TcxCustomGridViewData          See Also

Determines whether a data controller provides any rows for a view.

function IsEmpty: Boolean; virtual;

Description

The IsEmpty method returns True, if no data is available for the view.  Otherwise – False.


TcxCustomGridViewData.MakeDetailVisible

TcxCustomGridViewData          See Also

Displays the detail view of a particular level.

function MakeDetailVisible(ADetailLevel: TComponent): TcxCustomGridView; virtual;

Description

The MakeDetailVisible method scrolls the master view in order to bring the master row into view (if it’s beyond the view’s boundaries) and expands this row sequentially to the specified detail level to show the joined detail view.  It returns an instance of that view.

Use the MakeDetailVisible method to show an associated detail view of the ADetailLevel level.


TcxCustomGridBackgroundBitmaps
TcxCustomGridBackgroundBitmaps Object

Hierarchy          Properties          Methods

Serves as the base for classes providing background bitmaps for the visual elements of views.

Unit

cxGridCustomView

TcxCustomGridBackgroundBitmaps = class(TcxCustomGridOptions)

Description

The grid control enables you to assign background bitmaps to elements of its views.  The following properties should be used for this purpose:

•	BackgroundBitmaps property of table views.  Its value is represented by a TcxGridTableBackgroundBitmaps object.

•	BackgroundBitmaps property of banded table views. Its value is represented by a TcxGridBandedTableBackgroundBitmaps object.

•	BackgroundBitmaps property of card views. Its value is represented by a TcxGridCardViewBackgroundBitmaps object.

All the objects above provide a set of properties that specify the bitmaps assigned to specific elements of the corresponding view.  They are all inherited from the TcxCustomGridBackgroundBitmaps class that implements their common functionality: the Background property that specifies the background image for the entire view and the Values property that allows the access of element bitmaps using element indexes.

The image below shows an example of assigning bitmaps to elements of a table view.


TcxCustomGridBackgroundBitmaps Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |


Properties for TcxCustomGridBackgroundBitmaps
TcxCustomGridBackgroundBitmaps Properties

TcxCustomGridBackgroundBitmaps          Legend

In TcxCustomGridBackgroundBitmaps

Background

Values


Methods for TcxCustomGridBackgroundBitmaps
TcxCustomGridBackgroundBitmaps Methods

TcxCustomGridBackgroundBitmaps          Legend

In TcxCustomGridBackgroundBitmaps

 Assign


TcxCustomGridBackgroundBitmaps.Background

TcxCustomGridBackgroundBitmaps

Specifies the view’s background bitmap.

property Background: TBitmap;

Description

The Background property lets you set the bitmap for grid views’ background.

Note that the bitmap specified by this property will be visible only in places not occupied by elements of the view.  For instance, if the number of records displayed by a table view is so small that they don’t occupy the entire view, the background bitmap will be visible below the records.

Images below show examples of assigning background bitmaps to table and card views.


TcxCustomGridBackgroundBitmaps.Values

TcxCustomGridBackgroundBitmaps

Provides access to a bitmap assigned to the element specified by its index.

property Values[Index: Integer]: TBitmap;

Description

Bitmaps assigned to properties of TcxCustomGridBackgroundBitmaps descendants are stored in an internal collection.  The Values property provides access to elements of this collection by their indexes.  Indexes of specific elements are specified by constants.

The Values property is used internally.  To specify a bitmap for an element of a view, use the corresponding property of the TBitmap type instead.  For instance, to set the view’s background image, use the Background property.


TcxCustomGridBackgroundBitmaps.Assign

TcxCustomGridBackgroundBitmaps

Copies the contents of one TcxCustomGridBackgroundBitmaps object to another.

procedure Assign(Source: TPersistent); override;

Description

Use the Assign method to copy the contents of one object storing element bitmaps to another.  The Source parameter specifies the source object.  The caller is the destination object.

As implemented in the TcxCustomGridBackgroundBitmaps class, the Assign method copies the Background property value.  Descendants override this method to copy all the required property values.


TcxGridViewHandler
TcxGridViewHandler Object

Hierarchy          Properties          Methods

Represents an abstract class providing information from a view.

Unit

cxGridCustomView

TcxGridViewHandler = class(TObject)

Description

TcxGridViewHandler is a base class for descendants which return view information.  When creating a TcxGridViewHandler object, a view (TcxCustomGridView) is passed as a constructor parameter.  TcxGridViewHandler declares a number of attributes used to retrieve the corresponding properties of a view.

TcxGridViewHandler is a base class for the following classes:

•	TcxCustomGridController – processes keyboard and mouse messages;

•	TcxCustomGridViewData – provides an intermediate class providing an interface between a data controller and a view

•	TcxCustomGridPainter – implements drawing of a grid control based on information provided by the TcxCustomGridViewInfo class

•	TcxCustomGridViewInfo – contains information for calculating grid element sizes.


TcxGridViewHandler Hierarchy
Hierarchy

TObject

     |


Properties for TcxGridViewHandler
TcxGridViewHandler Properties

TcxGridViewHandler          Legend

In TcxGridViewHandler

Control

Controller

DataController

GridView

ViewData


Methods for TcxGridViewHandler
TcxGridViewHandler Methods

TcxGridViewHandler          Legend

In TcxGridViewHandler

 BeginUpdate

 Create

 EndUpdate


TcxGridViewHandler.Control

TcxGridViewHandler

Specifies the grid control owning the view.

property Control: TcxControl;

Description

The Control property returns the grid control which owns the view.

ReadOnly Property


TcxGridViewHandler.Controller

TcxGridViewHandler

Returns the view’s controller object.

property Controller: TcxCustomGridController;

Description

The Controller property returns the object which processes keyboard and mouse events on behalf of the view.

ReadOnly Property


TcxGridViewHandler.DataController

TcxGridViewHandler

Specifies the data controller assigned to the view.

property DataController: TcxCustomDataController;

Description

The Data controller handles the retrieval and posting of data from/to a data storage.  Descendants of the TcxCustomDataController class implement working with datasets and are used in data-aware views.  A view gets data from a data storage with the help of the intermediate object – ViewData.

ReadOnly Property


TcxGridViewHandler.GridView

TcxGridViewHandler

Identifies the view to which the TcxGridViewHandler class provides information.

property GridView: TcxCustomGridView;

Description

The GridView property references the view to which information is presented by the TcxGridViewHandler class.  TcxGridViewHandler properties retrieve values of corresponding view members.

ReadOnly Property


TcxGridViewHandler.ViewData

TcxGridViewHandler

Specifies the object retrieving data from a data controller and providing it to a view.

property ViewData: TcxCustomGridViewData;

Description

The ViewData property provides an interface between a view and an assigned data controller. Its retrieves data from the data controller and structures it in a convenient form for display.

ReadOnly Property


TcxGridViewHandler.BeginUpdate

TcxGridViewHandler

Prevents a grid view from updating until the EndUpdate method is called.

procedure BeginUpdate;

Description

BeginUpdate calls the view’s BeginUpdate method.  The BeginUpdate and EndUpdate methods can be used to prevent updates until all changes to a view object have been completed.


TcxGridViewHandler.Create

TcxGridViewHandler

Creates a TcxGridViewHandler class instance.

constructor Create(AGridView: TcxCustomGridView); virtual;

Description

The constructor creates an instance of the TcxGridViewHandler class.  The AGridView parameter is used to initialize the GridView property.  Other properties of the TcxGridViewHandler class retrieve corresponding view member values.


TcxGridViewHandler.EndUpdate

TcxGridViewHandler

Enables updates of a view.

procedure EndUpdate;

Description

The EndUpdate method calls the view’s EndUpdate method thus enabling updates postponed by the BeginUpdate call.


TcxCustomGridController
TcxCustomGridController Object

Hierarchy          Properties          Methods          See Also

Represents the base class for a view’s controller.

Unit

cxGridCustomView

TcxCustomGridController = class(TcxGridViewHandler, IcxMouseTrackingCaller)

Description

TcxCustomGridController is the base class for view specific controllers that manage certain operations depending on which view they are associated with.  To access the view’s controller functionality, see its Controller property.

The view’s controller enables you to:

-	start/cancel an incremental search

-	access selected and focused records

-	control cell editing

-	invoke a customization form

-	perform scrolling

-	navigate records

-	etc.

TcxCustomGridController provides only base features.  Its functionality is extended by descendants (See the TcxCustomGridTableController class, for instance).


TcxCustomGridController Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxGridViewHandler

     |


Properties for TcxCustomGridController
TcxCustomGridController Properties

TcxCustomGridController          Legend

Derived from TcxGridViewHandler

Control

Controller

DataController

GridView

ViewData


Methods for TcxCustomGridController
TcxCustomGridController Methods

TcxCustomGridController          Legend

In TcxCustomGridController

 Scroll

Derived from TcxGridViewHandler

 BeginUpdate

 Create

 EndUpdate


TcxCustomGridController.Scroll

TcxCustomGridController          See Also

Scrolls the view contents.

type

  TScrollBarKind = (sbHorizontal, sbVertical);

  TScrollCode = (scLineUp, scLineDown, scPageUp, scPageDown, scPosition, scTrack, scTop, scBottom, scEndScroll);

procedure Scroll(AScrollBarKind: TScrollBarKind; AScrollCode: TScrollCode; var AScrollPos: Integer); virtual;

Description

The Scroll method is called internally when a user scrolls the view contents using the keyboard or scroll bars.  You can control the visibility of scroll bars in tabular and card views via the view’s OptionsView.ScrollBars property.  Chart views display a scroll bar only for paged diagrams.  Refer to the description of the view’s OptionsView.CategoriesPerPage and Controller.ActiveDiagramSupportsPaging properties for details on paging contents of chart diagrams.  A scroll bar is displayed along a category axis.  The diagram type determines the scroll bar’s orientation.

You can use the Scroll method to perform scrolling programmatically horizontally or vertically.  The direction of scrolling is specified by the AScrollBarKind parameter.  If it is set to sbHorizontal, the scrolling is performed horizontally.  The sbVertical value designates vertical scrolling.

The AScrollCode parameter indicates the type (amount) of scrolling.  The Scroll method recognizes the following scroll codes: scLineUp, scLineDown, scPageUp, scPageDown, scPosition and scTrack.

Rather than apply the Scroll method with scPosition or scTrack codes to perform scrolling to a specific position, you should use the LeftPos and TopRecordIndex properties declared in TcxCustomGridController descendants for this purpose.

The following table describes four scroll codes you can use with the Scroll method.

Value	Meaning
scLineUp	Vertical scrolling This has the same effect as clicking the top scroll arrow. Horizontal scrolling Scrolls the view to the left by a specific amount of pixels similar to clicking the left scroll button.
scLineDown	Vertical scrolling This has the same effect as clicking the bottom scroll arrow. Horizontal scrolling Scrolls the view to the right by a specific amount of pixels similar to clicking the right scroll button.
scPageUp	This has the same effect as clicking the area above the thumb tab (when scrolling vertically) or to the left of it (when scrolling horizontally).
scPageDown	This has the same effect as clicking the area down to the thumb tab (when scrolling vertically) or to the right of it (when scrolling horizontally).

A card view displays only one scrollbar.  Its orientation is defined by the view’s LayoutDirection property.  When calling the Scroll method for a card view, the AScrollBarKind parameter is ignored and scrolling is applied to the scrollbar determined by LayoutDirection.

The AScrollPos parameter is used when the Scroll method is called internally.  When using the scLineUp, scLineDown, scPageUp and scPageDown scroll codes, this parameter is ignored.

The following code simulates clicking the bottom scroll arrow of a scrollbar:

//Delphi

var

  A: Integer;

  AView: TcxCustomGridTableView;

//...

  AView := TcxCustomGridTableView(Grid.FocusedView);

  A := 0;

  AView.Controller.Scroll(sbVertical, scLineDown, A);

//C++ Builder

TcxCustomGridTableView *  AView =

  (TcxCustomGridTableView*)Grid->FocusedView;

int  A = 0;

AView->Controller->Scroll(sbVertical, scLineDown, A);


TcxGridColumn
TcxGridColumn Object

Hierarchy          Properties          Methods          Events          See Also

Represents an item in a table view.

Unit

cxGridTableView

TcxGridColumn = class(TcxCustomGridTableItem);

Description

TcxGridColumn represents an item (column) in a table view of the TcxGridTableView class.  A table view has the Columns property, which supports a list of columns displayed within the view.

The Options property provides a number of settings which manage the behavior and appearance of columns.  Using the Styles object, you can specify the styles of different column elements (data cells, header, footer).

To specify an editor for an item and thus specify the data representation, you can use either the repository and repository items mechanism or the PropertiesClass and Properties objects.

Classes that derive functionality from the TcxGridColumn class are TcxGridBandedColumn and TcxGridDBColumn.


TcxGridColumn Hierarchy
Hierarchy

TComponent

     |

TcxCustomGridTableItem

     |


Properties for TcxGridColumn
TcxGridColumn Properties

TcxGridColumn          Legend

In TcxGridColumn

FooterAlignmentHorz

GridView

GroupSummaryAlignment

HeaderGlyph

HeaderGlyphAlignmentHorz

HeaderGlyphAlignmentVert

IsBottom

IsLeft

IsMostBottom

IsMostLeft

IsMostRight

IsPreview

IsRight

Options

Selected

Styles

Summary

Derived from TcxCustomGridTableItem

ActuallyVisible

BestFitMaxWidth

Caption

DataBinding

DateTimeGrouping

Editing

EditValue

Filtered

Focused

GridView

GroupIndex

GroupingDateRanges

HeaderAlignmentHorz

HeaderAlignmentVert

Hidden

ID

IncSearching

Index

IsFirst

IsLast

MinWidth

Options

Properties

PropertiesClass

RepositoryItem

SortIndex

SortOrder

Styles

Visible

VisibleForCustomization

VisibleIndex

Width


Methods for TcxGridColumn
TcxGridColumn Methods

TcxGridColumn          Legend

Derived from TcxCustomGridTableItem

 ApplyBestFit

 GetProperties

 RestoreDefaults


Events for TcxGridColumn
TcxGridColumn Events

TcxGridColumn          Legend

In TcxGridColumn

 OnCompareValuesForCellMerging

 OnCustomDrawFooterCell

 OnCustomDrawGroupSummaryCell

 OnCustomDrawHeader

 OnHeaderClick

Derived from TcxCustomGridTableItem

 OnCustomDrawCell

 OnGetCellHint

 OnGetDataText

 OnGetDisplayText

 OnGetFilterDisplayText

 OnGetFilterValues

 OnGetProperties

 OnGetStoredProperties

 OnGetStoredPropertyValue

 OnInitFilteringDateRanges

 OnInitGroupingDateRanges

 OnSetStoredPropertyValue

 OnUserFiltering


TcxGridColumn.FooterAlignmentHorz

TcxGridColumn          See Also

Specifies the alignment of text in a column footer.

property FooterAlignmentHorz: TAlignment;

Description

Use the FooterAlignmentHorz property to set the alignment of the column footer text.  The column footer displays the footer summary result.  To set the summary, see the view’s DataController.Summary property.  It is also possible to create a summary at design time via the grid designer.

You display a footer panel by setting the view’s OptionsView.Footer property to True.


TcxGridColumn.GridView

TcxGridColumn          See Also

Defines a table view containing the current column.

property GridView: TcxGridTableView;

Description

Use GridView to access properties of a view containing the current column.  A view provides a set of options managing properties and behavior of columns, filter, group and preview panels etc.

ReadOnly Property


TcxGridColumn.GroupSummaryAlignment

TcxGridColumn

Specifies the horizontal alignment of a group summary in the currently processed column.

property GroupSummaryAlignment: TAlignment;

Description

A group summary can be horizontally aligned in the column if the view’s OptionsView.GroupSummaryLayout property is set to gslAlignWithColumns or gslAlignWithColumnsAndDistribute.

Use the GroupSummaryAlignment property to specify group summary alignment in the column.


TcxGridColumn.HeaderGlyph

TcxGridColumn

Specifies the column header’s icon.

property HeaderGlyph: TBitmap;

Description

Use the HeaderGlyph property to assign a bitmap to the header of the currently processed column.

Once specified, an image can be aligned in the column header horizontally or vertically by using the column’s HeaderGlyphAlignmentHorz or HeaderGlyphAlignmentVert properties.


TcxGridColumn.HeaderGlyphAlignmentHorz

TcxGridColumn          See Also

Specifies the horizontal alignment of the column header’s icon.

property HeaderGlyphAlignmentHorz: TAlignment;

Description

To draw an icon in the column header, specify an image for it via the column’s HeaderGlyph property.

The HeaderGlyphAlignmentHorz property allows the specified icon to be horizontally aligned in the column header.

The default value of the HeaderGlyphAlignmentHorz property is taLeftJustify.


TcxGridColumn.HeaderGlyphAlignmentVert

TcxGridColumn          See Also

Specifies the vertical alignment of the column header’s icon.

property HeaderGlyphAlignmentVert: TcxAlignmentVert;

Description

To draw an icon in the column header, specify an image for it via the column’s HeaderGlyph property.

The HeaderGlyphAlignmentVert property allows the specified icon to be vertically aligned in the column header.

The default value of the HeaderGlyphAlignmentVert property is vaCenter.


TcxGridColumn.IsBottom

TcxGridColumn

Specifies whether the column is displayed at the bottom of the object that owns the column.

property IsBottom: Boolean;

Description

The IsBottom property returns True if a column is displayed at the bottom of the object which owns the column.  This property is useful, for instance, when columns are grouped in bands in a banded table view (the TcxGridBandedTableView class).

The height of the band header panel is determined by the band containing the maximum number of band rows.  Therefore, some bands can contain empty band rows.  The IsBottom property returns True if the column is positioned at the last non-empty row of the corresponding band.

ReadOnly Property


TcxGridColumn.IsLeft

TcxGridColumn

Specifies whether the column is displayed at the left of the object that owns the column.

property IsLeft: Boolean;

Description

It could be said that in a banded table view, a band owns columns while in a table view the view itself does.  For a table view, the IsLeft property returns the value of the IsFirst attribute.  For a banded table view, IsLeft returns True if the column is positioned at the left edge of the corresponding band.  Otherwise, it returns False.

ReadOnly Property


TcxGridColumn.IsMostBottom

TcxGridColumn

Specifies whether the column is bottommost.

property IsMostBottom: Boolean;

Description

In a banded table view, the IsMostBottom property specifies whether the column is displayed within the last row of the view bands panel.  To determine whether a column is positioned at the last row within its band, see the IsBottom member.

ReadOnly Property


TcxGridColumn.IsMostLeft

TcxGridColumn

Specifies whether a column is displayed at the left edge of a view.

property IsMostLeft: Boolean;

Description

The IsMostLeft property returns True if a column is positioned at the left of a view.  For a banded table view, you can determine whether a column is displayed at the left edge of a corresponding band via the IsLeft property.

ReadOnly Property


TcxGridColumn.IsMostRight

TcxGridColumn

Returns a value indicating whether a column is positioned at the right edge of a view.

property IsMostRight: Boolean;

Description

Use the IsMostRight property to determine whether a column is displayed at the right edge of a view.  In a banded table view, you can use the IsRight property to learn whether the column is positioned at the right of a corresponding band.

ReadOnly Property


TcxGridColumn.IsPreview

TcxGridColumn          See Also

Defines whether the column is previewed.

property IsPreview: Boolean;

Description

The IsPreview property is True if a column’s view contains a preview section displaying this column’s values.  The preview options are adjusted via the TcxGridTableView.Preview object.  Only one column can be previewed at a time.  The previewed column is not displayed with the other view columns.  If a column is previewed, setting its IsPreview property to False results in clearing the preview section.

You can also specify the column for the preview section by using the Column attribute of the Preview object.


TcxGridColumn.IsRight

TcxGridColumn

Specifies whether the column is displayed at the right of the object that owns the column.

property IsRight: Boolean;

Description

In a banded table view a band owns columns, so the IsRight property returns True for columns positioned at the right edge of the corresponding band.  For a table view, the IsRight property returns the value of the IsLast member value.  To determine whether a column is displayed at the right edge of a view, read the IsMostRight property.

ReadOnly Property


TcxGridColumn.Options

TcxGridColumn          See Also

Defines a set of options managing the behavior and appearance of a column.

property Options: TcxGridColumnOptions;

Description

Use the Options object to adjust various settings of a grid column.  You can specify whether a user can edit the column data, move the column, group view data by the column, etc.  See the numerous attributes of the view’s OptionsData and OptionsCustomize properties to define settings common to all columns within a view.


TcxGridColumn.Selected

TcxGridColumn          See Also

Specifies whether the current column’s cells are selected within a (banded) table view.

property Selected: Boolean;

Description

Use the Selected property to include/exclude the current column’s cells from the currently selected records within a (banded) table view.  This property is useful only when the view’s OptionsSelection.CellMultiSelect property is set to True.  To select a set of sequential columns, use the SelectColumns method.  The SelectAllColumns method allows you to select the cells of all the columns within the current record selection, i.e. select the entire record(s).

In order to select specific columns’ cells within the particular record selection, use the SelectCells method.


TcxGridColumn.Styles

TcxGridColumn          See Also

Specifies a set of styles managing the appearance of column elements.

property Styles: TcxGridColumnStyles;

Description

The Styles object defines a set of styles for different column elements (content region, footer and header panel).  It is possible to define styles common to all columns within a view via the view’s Styles property and then redefine them for particular columns.  Handling the events of the Styles object, it is possible to set specific styles for individual records.


TcxGridColumn.Summary

TcxGridColumn          See Also

Specifies the set of summaries that are calculated for the current column.

property Summary: TcxGridColumnSummary;

Description

The Summary object defines a set of summaries (summary kinds and display formats) that are calculated for the current column and displayed in different view elements (footer panel, group row and group footer).

For more information, see the Creating Summaries topic.


TcxGridColumn.OnCompareValuesForCellMerging

TcxGridColumn          See Also

Occurs when the values of two sequential cells in a column are compared to determine if these cells can be merged into a single cell.

type

  TcxGridColumnCompareValuesEvent = procedure(Sender: TcxGridColumn; AProperties1: TcxCustomEditProperties; const AValue1: TcxEditValue; AProperties2: TcxCustomEditProperties; const AValue2: TcxEditValue; var AAreEqual: Boolean) of object;

property OnCompareValuesForCellMerging: TcxGridColumnCompareValuesEvent;

Description

When a column has its CellMerging property set to True, the OnCompareValuesForCellMerging event occurs every time the values of two sequential cells are compared to determine if they are equal and thus the corresponding cells can be merged and displayed as a single cell.

The Sender parameter specifies the column whose cells are being compared.  The AProperties1 and AProperties2, AValue1 and AValue2 parameter pairs specify editor-specific attributes and edit values for the first and second cells’ editors, correspondingly.  You can use these values to perform additional comparisons of the cells' values.  The AAreEqual parameter gives the comparison's result and initially indicates whether the displayed values of these cells are the same.

Note:	The OnCompareRowValuesForCellMerging event is an extended version of the OnCompareValuesForCellMerging event which provides the data rows in which the cells are displayed as additional parameters.


TcxGridColumn.OnCompareRowValuesForCellMerging

TcxGridColumn          See Also

Occurs when the values of two sequential cells in a column are compared to determine if these cells can be merged into a single cell.

type

  TcxGridColumnCompareRowValuesEvent = procedure(Sender: TcxGridColumn; ARow1: TcxGridDataRow; AProperties1: TcxCustomEditProperties; const AValue1: TcxEditValue; ARow2: TcxGridDataRow; AProperties2: TcxCustomEditProperties; const AValue2: TcxEditValue; var AAreEqual: Boolean) of object;

property OnCompareRowValuesForCellMerging: TcxGridColumnCompareRowValuesEvent;

Description

When a column has its CellMerging property set to True, the OnCompareRowValuesForCellMerging event (as with the OnCompareValuesForCellMerging event) occurs every time the values of two sequential cells are compared to determine if they are equal and thus the corresponding cells can be merged and displayed as a single cell.

The Sender parameter specifies the column whose cells are being compared.  The ARow1 and ARow2, AProperties1 and AProperties2, AValue1 and AValue2 parameter pairs specify correspondingly the rows in which the cells whose values are being compared are displayed, editor-specific attributes and edit values for the first and second cells’ editors.  The OnCompareRowValuesForCellMerging event is an extended version of the OnCompareValuesForCellMerging event.  It provides in addition the data rows in which the cells are displayed as additional parameters.  You can use these values to perform additional comparisons of the cells' values.  The AAreEqual parameter gives the comparison's result and initially is equal to the result of the OnCompareValuesForCellMerging event (if it is assigned).  Otherwise, the initial value of the AAreEqual parameter indicates whether the displayed values of the cells are the same.


TcxGridColumn.OnCustomDrawFooterCell

TcxGridColumn          See Also

Occurs when a footer cell within a table column needs to be painted.

type

  TcxGridColumnCustomDrawHeaderEvent = procedure(Sender: TcxGridTableView; ACanvas: TcxCanvas; AViewInfo: TcxGridColumnHeaderViewInfo; var ADone: Boolean) of object;

property OnCustomDrawFooterCell: TcxGridColumnCustomDrawHeaderEvent;

Description

The OnCustomDrawFooterCell event occurs every time a footer cell needs to be painted. As with other custom draw events it provides a canvas for the grid control (ACanvas parameter), view info to get the bounding rectangle of the painted element (AViewInfo parameter and its Bounds property). Sender is usually the element that caused the repaint. The ADone parameter is initially False you should set it to True to tell the grid that you have chosen to custom draw this item.


TcxGridColumn.OnCustomDrawGroupSummaryCell

TcxGridColumn          See Also

Fires each time a group summary is about to be drawn in the currently processed column.

type

  TcxGridGroupSummaryCellCustomDrawEvent = procedure(Sender: TObject; ACanvas: TcxCanvas; ARow: TcxGridGroupRow; AColumn: TcxGridColumn; ASummaryItem: TcxDataSummaryItem; AViewInfo: TcxCustomGridViewCellViewInfo; var ADone: Boolean) of object;

property OnCustomDrawGroupSummaryCell: TcxGridGroupSummaryCellCustomDrawEvent;

Description

Implement the OnCustomDrawGroupSummaryCell event handler to custom paint the group summary.

The Sender parameter specifies the currently processed column;

The ACanvas parameter specifies the drawing surface;

The ARow parameter specifies the group row that the group summary is currently drawn in;

The AColumn parameter specifies the currently processed column;

The ASummaryItem parameter specifies the currently drawn group summary;

The AViewInfo parameter provides details for rendering the group summary;

The ADone parameter specifies whether default painting is required. Set ADone to True, to prevent default painting.


TcxGridColumn.OnCustomDrawHeader

TcxGridColumn          See Also

Occurs when a cell within a table column header needs to be painted.

type

  TcxGridColumnCustomDrawHeaderEvent = procedure(Sender: TcxGridTableView; ACanvas: TcxCanvas; AViewInfo: TcxGridColumnHeaderViewInfo; var ADone: Boolean) of object;

property OnCustomDrawHeader: TcxGridColumnCustomDrawHeaderEvent;

Description

The OnCustomDrawHeader event occurs every time a column header needs to be painted. As every custom draw events it provides a canvas for the grid control (ACanvas parameter), view info to get the bounding rectangle of the painted element (AViewInfo parameter and its Bounds property). Sender is usually the element that caused the repaint. The ADone parameter is initially False you should set it to True to tell the grid that you have chosen to custom draw this item.


TcxGridColumn.OnHeaderClick

TcxGridColumn          See Also

The event is fired on clicking the column header in a grid table view.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnHeaderClick: TNotifyEvent;

Description

The OnHeaderClick event occurs when a user clicks the header of the current column.  For instance, a user can handle the OnHeaderClick event in order to perform sorting by the specific column values when sorting is restricted for that column (the ColumnOptions.Sorting property value is False).

The following code shows how to perform sorting by the PaymentType column values when sorting is disabled for that column at design time:

//Delphi

procedure TColumnsSimpleDemoMainForm.OrdersViewPaymentTypeHeaderClick(

  Sender: TObject);

begin

  With TcxGridColumn(Sender) do

  begin

    if SortOrder = TcxDataSortOrder(soDescending) then

      SortOrder := TcxDataSortOrder(soAscending)

    else

      SortOrder := TcxDataSortOrder(soDescending);

  end;

end;

//C++ Builder

void __fastcall TColumnsSimpleDemoMainForm::OrdersViewPaymentTypeHeaderClick(TObject *Sender) {

  TcxGridColumn *sender = (TcxGridColumn *)Sender;

  if (sender->SortOrder == Cxcustomdata::soDescending) {

    sender->SortOrder = Cxcustomdata::soAscending;

  } else {

    sender->SortOrder = Cxcustomdata::soDescending;

  }

end;


TcxGridColumnOptions
TcxGridColumnOptions Object

Hierarchy          Properties          See Also

Options for managing the behavior of columns in a table view.

Unit

cxGridTableView

TcxGridColumnOptions = class(TcxCustomGridTableItemOptions);

Description

The TcxGridColumnOptions class contains options defining the global behavior of all columns at runtime.  They define the end-users ability to manipulate column data such as sorting, filtering, moving, sizing, editing, etc.

Most of the properties are provided by TcxGridColumnOptions class descendants.  TcxGridColumnOptions introduces members specific to grid columns.

To override these options for one a column, see that columns TcxGridColumn.Options property.


TcxGridColumnOptions Hierarchy
Hierarchy

TPersistent

     |

TcxCustomGridTableItemCustomOptions

     |

TcxCustomGridTableItemOptions

     |


Properties for TcxGridColumnOptions
TcxGridColumnOptions Properties

TcxGridColumnOptions          Legend

In TcxGridColumnOptions

CellMerging

GroupFooters

HorzSizing

Derived from TcxCustomGridTableItemOptions

Editing

Filtering

FilteringFilteredItemsList

FilteringMRUItemsList

FilteringPopup

FilteringPopupMultiSelect

Focusing

Grouping

IgnoreTimeForFiltering

IncSearch

Moving

ShowCaption

ShowEditButtons

SortByDisplayText

Sorting


TcxGridColumnOptions.CellMerging

TcxGridColumnOptions          See Also

Specifies whether sequential cells in a column, which have the same value will be merged and displayed as a single cell.

property CellMerging: Boolean;

Description

Set the CellMerging property to True to activate cell merging mode in which sequential cells within a column that have the same value are merged and displayed as a single cell with the only cell value shown at once.  Otherwise, set this property to False.  By default, display values of cells are used for equality comparison.  You can implement your own comparison technique by handling the OnCompareValuesForCellMerging event for a specific column.

The image below shows the resulting grid view when sequential cells in the Trademark column are merged by their display values comparison.

Note:	While cell merging is in effect for a column the column is set to read only for end users.

The default value of the CellMerging property is False.


TcxGridColumnOptions.GroupFooters

TcxGridColumnOptions

Specifies whether to display group footers for a grouping column.

property GroupFooters: Boolean;

Description

Set the GroupFooters property to False to hide group footers for the currently processed column if it is grouped.

The default value of the GroupFooters property is True.


TcxGridColumnOptions.HorzSizing

TcxGridColumnOptions          See Also

Specifies whether a user can resize the column.

property HorzSizing: Boolean;

Description

Set the HorzSizing property to False to prevent a user from resizing the column.  If the HorzSizing is set to True, a user can drag the right column edge to change the column width.

It is possible to define the minimum width for a column via the MinWidth property.  Using the view’s OptionsCustomize.ColumnHorzSizing property you can globally prevent a user from resizing any of the view columns.

The default value of the HorzSizing property is True.


TcxGridColumnStyles
TcxGridColumnStyles Object

Hierarchy          Properties          Methods          Events          See Also

Represents a set of styles managing the appearance of different column elements.

Unit

cxGridTableView

TcxGridColumnStyles = class(TcxCustomGridTableItemStyles);

Description

The TcxGridColumnStyles class introduces new properties and events allowing you to specify the appearance of column elements (header and footer panels).

Use a column’s Styles property to set the styles of the column.  A View’s Styles property allows you to define styles common to all columns within the View.

It is possible to specify different styles for individual records by handling the styles events and changing the styles on the fly.


TcxGridColumnStyles Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomStyles

     |

TcxStyles

     |

TcxCustomGridStyles

     |

TcxCustomGridTableItemStyles

     |


Properties for TcxGridColumnStyles
TcxGridColumnStyles Properties

TcxGridColumnStyles          Legend

In TcxGridColumnStyles

Footer

GridView

GroupSummary

Header

Item

Derived from TcxCustomGridTableItemStyles

Content

GridView

Item

Derived from TcxCustomGridStyles

GridView

Derived from TcxCustomStyles

StyleSheet


Methods for TcxGridColumnStyles
TcxGridColumnStyles Methods

TcxGridColumnStyles          Legend

In TcxGridColumnStyles

GetFooterParams

GetGroupSummaryParams

GetHeaderParams

Derived from TcxCustomStyles

Assign

Create

Destroy


Events for TcxGridColumnStyles
TcxGridColumnStyles Events

TcxGridColumnStyles          Legend

In TcxGridColumnStyles

OnGetFooterStyle

OnGetFooterStyleEx

OnGetFooterSummaryStyle

OnGetGroupSummaryStyle

OnGetHeaderStyle

Derived from TcxCustomGridTableItemStyles

OnGetContentStyle


TcxGridColumnStyles.Footer

TcxGridColumnStyles          See Also

Specifies the style for the footer region of a column.

property Footer: TcxStyle;

Description

Use the Footer property to set the style for a footer region of a column.  The footer region is used to display a summary result calculated on the column.

You can set the style of a footer panel for all columns within a view via the view’s Styles.Footer property.

To provide individual styles for specific records, handle the OnGetFooterStyle event.


TcxGridColumnStyles.GridView

TcxGridColumnStyles

Specifies the table view containing the column for which the TcxGridColumnStyles specifies styles.

property GridView: TcxGridTableView;

Description

The GridView property returns the table view containing the column that this TcxGridColumnStyles defines styles for.

ReadOnly Property


TcxGridColumnStyles.GroupSummary

TcxGridColumnStyles          See Also

Specifies style attributes for the column’s group summary.

property GroupSummary: TcxStyle;

Description

Use the GroupSummary property to apply the required style to the column’s group summary (if any).

To dynamically apply a new style to the column’s group summary on some conditions, handle the OnGetGroupSummaryStyle event.


TcxGridColumnStyles.Header

TcxGridColumnStyles          See Also

Determines the appearance of the column header region.

property Header: TcxStyle;

Description

Use the Header property to associate a style for the column header region displaying the column caption.

It is possible to specify styles for header panel of all columns via the view’s Styles.Header object.

By handling the OnGetHeaderStyle event you can specify individual styles on the fly for specific records.


TcxGridColumnStyles.Item

TcxGridColumnStyles

Returns the column that this style is applied to.

property Item: TcxGridColumn;

Description

The Item property identifies the column that the TcxGridColumnStyles applies styles to.

ReadOnly Property


TcxGridColumnStyles.GetFooterParams

TcxGridColumnStyles          See Also

Gets the TcxViewParams record containing information on the footer’s style attributes.

procedure GetFooterParams(ARow: TcxCustomGridRow; AFooterGroupLevel: Integer; ASummaryItem: TcxDataSummaryItem; out AParams: TcxViewParams); virtual;

Description

The ARow parameter specifies a row that the column’s footer resides in.

The AFooterGroupLevel parameter corresponds to the data group, for which the footer region is drawn (it's equal to the group column’s GroupIndex property’s value).  For view footers, the AFooterGroupLevel value is –1.

The ASummaryItem parameter provides access to the summary object displayed by the Item column.

The AParams parameter specifies style attributes that the method results in.


TcxGridColumnStyles.GetGroupSummaryParams

TcxGridColumnStyles          See Also

Gets the TcxViewParams record containing information on the group summary’s style attributes.

procedure GetGroupSummaryParams(ARow: TcxGridGroupRow; ASummaryItem: TcxDataSummaryItem; out AParams: TcxViewParams); virtual;

Description

The ARow parameter specifies the row that the column’s group summary corresponds to.

The ASummaryItem parameter specifies a summary.

The AParams parameter specifies style attributes that the method results in.


TcxGridColumnStyles.GetHeaderParams

TcxGridColumnStyles          See Also

Gets the TcxViewParams record containing information on style attributes of the column header.

procedure GetHeaderParams(out AParams: TcxViewParams); virtual;

Description

The AParams parameter specifies style attributes that the method results in.


TcxGridColumnStyles.OnGetFooterStyle

TcxGridColumnStyles          See Also

Occurs when the column footer should be redrawn.

type

  TcxGridGetCellStyleEvent = procedure(Sender: TcxCustomGridTableView; ARecord: TcxCustomGridRecord; AItem: TcxCustomGridTableItem; out AStyle: TcxStyle) of object;

property OnGetFooterStyle: TcxGridGetCellStyleEvent;

Description

The OnGetFooterStyle event occurs every time the column footer is redrawn.

The style returned by the column’s OnGetFooterStyle event overrides the default style for the columns footer which is stored in the column’s Styles.Footer property.  This in turn overrides any style returned from the view’s Styles.OnGetFooterStyle event which in turn overrides the style stored in the view’s Styles.Footer property.

To specify the style for a footer region you have to create a TcxStyle object instance, adjust its properties as necessary and return it via the AStyle parameter.

The Sender and AItem parameters identify a view and a column respectively for which the footer region is drawn.

When view data is grouped the ARecord parameter refers to the last record in a group.  When data is not grouped it is nil.

To define the default styles for footer regions of all columns use the view’s Styles.Footer and Styles.OnGetFooterStyle members.

The OnGetFooterStyleEx event represents the extended version of the OnGetFooterStyle event and should be handled whenever you need to perform additional style customizations of the grouped items in the view.

Note:	The column’s OnGetFooterStyle and OnGetFooterStyleEx events override the default style of the column footer which is stored in the column’s Styles.Footer property. The latter in its turn overrides any style which is returned from the view’s Styles.OnGetFooterStyleEx and Styles.OnGetFooterStyle events which in turn override the style stored in the view’s Styles.Footer property.


TcxGridColumnStyles.OnGetFooterStyleEx

TcxGridColumnStyles          See Also

Occurs when the column footer should be redrawn.

type

  TcxGridGetFooterStyleExEvent = procedure(Sender: TcxGridTableView; ARow: TcxCustomGridRow; AColumn: TcxGridColumn; AFooterGroupLevel: Integer; var AStyle: TcxStyle) of object;

property OnGetFooterStyleEx: TcxGridGetFooterStyleExEvent;

Description

The OnGetFooterStyleEx event occurs every time the column footer is redrawn and is fired after the OnGetFooterStyle event.

By default, the AStyle parameter at the moment the OnGetFooterStyleEx event is fired represents the style which was returned by the procedure that handles the OnGetFooterStyle event (if any).  To specify the style for a footer region you can create a TcxStyle object instance, adjust its properties as required and return it via the AStyle parameter.

The Sender, ARow, and AColumn parameters identify the view, row, and column, respectively for which the footer region is drawn.  When handling the OnGetFooterStyleEx event, you can distinguish between the view footer and group footers by comparing the ARow parameter's value with nil.  For view footers, it will always return nil.  For group footers, the ARow parameter will specify the last data record/row within the corresponding group.

The AFooterGroupLevel parameter corresponds to the data group, for which the footer region is drawn (it's equal to the group column’s GroupIndex property’s value).  For view footers, the AFooterGroupLevel value is –1.

To define the default styles for the footer regions of all the columns in the view, use the view’s Styles.Footer, Styles.OnGetFooterStyle and Styles.OnGetFooterStyleEx members.

Note:	The column’s OnGetFooterStyleEx and OnGetFooterStyle events override the default style for the column footer stored in the column’s Styles.Footer property. The latter in turn overrides any style which is returned from the view’s Styles.OnGetFooterStyleEx and Styles.OnGetFooterStyle events, which in turn override the style stored in the view’s Styles.Footer property.


TcxGridColumnStyles.OnGetFooterSummaryStyle

TcxGridColumnStyles          See Also

Fires each time a column’s footer summary or a group summary displayed in a group footer panel is about to be drawn.

type

  TcxGridGetFooterSummaryStyleEvent = procedure(AView: TcxGridTableView; ARow: TcxGridGroupRow; AColumn: TcxGridColumn; ASummaryItem: TcxDataSummaryItem; var AStyle: TcxStyle) of object;

property OnGetFooterSummaryStyle: TcxGridGetFooterSummaryStyleEvent;

Description

The AView parameter specifies the Table View that displays the currently processed summary.

The ARow parameter specifies the row that the group summary resides in.  For view footers, the ARow value is nil.

The AColumn parameter specifies the column that the summary is linked to.

The ASummaryItem parameter represents the summary object.  To determine whether summary values are used to sort group rows, use the ASummaryItem.Sorted property.

The AFooterGroupLevel parameter corresponds to the data group, for which the group footer panel is drawn (it's equal to the group column’s GroupIndex property’s value).  For view footers, the AFooterGroupLevel value is –1.

The AStyle parameter specifies style attributes to be applied to the column’s summary.

Note:	To customize the style of summaries displayed for all columns within the View, handle the View’s OnGetFooterSummaryStyle event.

The OnGetFooterSummaryStyle event is fired after the OnGetFooterStyle and OnGetFooterStyleEx events.


TcxGridColumnStyles.OnGetGroupSummaryStyle

TcxGridColumnStyles          See Also

Fires when a column’s group summary is about to be drawn.

type

  TcxGridGetGroupSummaryStyleEvent = procedure(Sender: TcxGridTableView; ARow: TcxGridGroupRow; AColumn: TcxGridColumn; ASummaryItem: TcxDataSummaryItem; var AStyle: TcxStyle) of object;

property OnGetGroupSummaryStyle: TcxGridGetGroupSummaryStyleEvent;

Description

Implement the OnGetGroupSummaryStyle event handler to provide style attributes the group summary to be drawn with.

The Sender parameter specifies a table view containing the currently processed group summary.

The ARow parameter specifies a row that the group summary resides in.

The AColumn parameter specifies a column that the group summary is linked to.

The ASummaryItem parameter represents the summary.

The AStyle parameter specifies style attributes to be applied to the group summary.


TcxGridColumnStyles.OnGetHeaderStyle

TcxGridColumnStyles          See Also

Occurs when a column header region is redrawn.

type

  TcxGridGetHeaderStyleEvent = procedure(Sender: TcxGridTableView; AColumn: TcxGridColumn; out AStyle: TcxStyle) of object;

property OnGetHeaderStyle: TcxGridGetHeaderStyleEvent;

Description

The OnGetHeaderStyle event occurs every time a column header region is redrawn.  The column header is the panel used to display the column caption.

The Style returned by the column’s Styles.OnGetHeaderStyle event overrides the default style for the columns header which is stored in the column’s Styles.Header property.  This in turn overrides any style returned from the view’s Styles.OnGetHeaderStyle event which in turn overrides the style stored in the view’s Styles.Header property.

To associate a new style with this column you need to create a TcxStyle object instance, adjust its properties and return in the AStyle parameter.  The column containing the header region and the view containing the column are specified by the Sender and AColumn parameters respectively.

The view’s Styles.Header and Styles.OnGetHeaderStyle members allow you to define the default styles for a header panel for all columns.


TcxGridColumnSummary
TcxGridColumnSummary Object

Hierarchy          Properties          See Also

Represents a set of options that determine the kind and appearance of a column’s footer and group summaries.

Unit

cxGridTableView

TcxGridColumnSummary = class(TcxCustomGridTableItemCustomOptions);

Description

These options allow you to specify:

•	the kind of footer and group summaries to calculate for the column (FooterKind, GroupFooterFormat, and GroupKind);

•	the appearance of summary values (FooterFormat, GroupFooterFormat, and GroupFormat);

•	whether group summary values determine the sort order of data groups (SortByGroupFooterSummary and SortByGroupSummary).

Note:	Setting column summary properties greatly simplifies the way you create footer and group summary items.  For more information about summaries, see the Creating Summaries topic.


TcxGridColumnSummary Hierarchy
Hierarchy

TPersistent

     |

TcxCustomGridTableItemCustomOptions

     |


Properties for TcxGridColumnSummary
TcxGridColumnSummary Properties

TcxGridColumnSummary          Legend

In TcxGridColumnSummary

FooterFormat

FooterKind

GroupFooterFormat

GroupFooterKind

GroupFormat

GroupKind

SortByGroupFooterSummary

SortByGroupSummary


TcxGridColumnSummary.FooterFormat

TcxGridColumnSummary          See Also

Specifies the format pattern that controls the manner in which a column’s footer summary value is displayed.

property FooterFormat: string;

Description

Refer to the TcxDataSummaryItem.Format property's description for the complete format description.

For more information and examples of format strings, see the Creating Summaries topic.


TcxGridColumnSummary.FooterKind

TcxGridColumnSummary          See Also

Specifies the kind of footer summary to calculate for a column.

property FooterKind: TcxSummaryKind;

Description

Refer to the TcxDataSummaryItem.Kind property's description for the list of possible summary kinds.

When the FooterKind property is set to a value other than skNone (which is the default value for this property) a single summary item will be automatically created for a column and added to the View’s footer summaries.


TcxGridColumnSummary.GroupFooterFormat

TcxGridColumnSummary          See Also

Specifies the format pattern that controls the manner in which a column’s group summary value is displayed in a group footer panel.

property GroupFooterFormat: string;

Description

Refer to the TcxDataSummaryItem.Format property's description for the complete format description.

For more information and examples of format strings, see the Creating Summaries topic.


TcxGridColumnSummary.GroupFooterKind

TcxGridColumnSummary          See Also

Specifies the kind of group summary to calculate for a column and display in a group footer panel.

property GroupFooterKind: TcxSummaryKind;

Description

Refer to the TcxDataSummaryItem.Kind property's description for the list of possible summary kinds.

When the GroupFooterKind property is set to a value other than skNone (which is the default value for this property) a single summary item is automatically created for the column and added to the View’s group summaries.  The item’s Position property is set to spFooter which designates the group footer panel as the place where the summary value will be displayed.


TcxGridColumnSummary.GroupFormat

TcxGridColumnSummary          See Also

Specifies the format pattern that controls the manner in which a column’s group summary value is displayed in a group row.

property GroupFormat: string;

Description

Refer to the TcxDataSummaryItem.Format property description for the complete format description.

For more information and examples of format strings, see the Creating Summaries topic.


TcxGridColumnSummary.GroupKind

TcxGridColumnSummary          See Also

Specifies the kind of group summary to calculate for a column and display in a group row.

property GroupKind: TcxSummaryKind;

Description

Refer to the TcxDataSummaryItem.Kind property description for the list of possible summary kinds.

When the GroupKind property is set to a value other than skNone (which is the default value for this property) a single summary item is automatically created for the column and added to the View’s group summaries.  The item’s Position property is set to spGroup which designates the group row as the place where the summary value will be displayed.


TcxGridColumnSummary.SortByGroupFooterSummary

TcxGridColumnSummary          See Also

Specifies whether a column’s group summary values displayed in group footer panels are used to sort data groups.

property SortByGroupFooterSummary: Boolean;

Description

Enabling this option assigns True to the Sorted property of the first summary object that calculates group footer summaries for the column.  If the object doesn’t exist, it’s created using a value of spFooter for its Position property and default values for its Kind and Format properties.  You can modify default values for these properties via the column’s Summary.GroupFooterKind and Summary.GroupFooterFormat properties.

When the SortByGroupFooterSummary property is set to False the summary object is deleted provided that its Kind and Format properties are assigned default values.

To sort data groups by a column’s group summary values displayed in group rows, set the SortByGroupSummary property to True.

End-users can choose the sort method from the Group Row Popup Menu.

To display multiple group footer summaries for columns, set the View’s OptionsView.GroupFooterMultiSummaries property to True.


TcxGridColumnSummary.SortByGroupSummary

TcxGridColumnSummary          See Also

Specifies whether a column’s group summary values displayed in group rows are used to sort data groups.

property SortByGroupSummary: Boolean;

Description

Enabling this option assigns True to the Sorted property of the first summary object that calculates group row summaries for the column.  If the object doesn’t exist, it’s created using a value of spGroup for its Position property and default values for its Kind and Format properties.  You can modify default values for these properties via the column’s Summary.GroupKind and Summary.GroupFormat properties.

When the SortByGroupSummary property is set to False the summary object is deleted provided that its Kind and Format properties are assigned default values.

To sort data groups by a column’s group summary values displayed in group footer panels, set the SortByGroupFooterSummary property to True.

End-users can choose the sort method from the Group Row Popup Menu.


TcxGridTableOptionsBehavior
TcxGridTableOptionsBehavior Object

Hierarchy          Properties          See Also

Contains options determining the grid table view’s response to user actions.

Unit

cxGridTableView

TcxGridTableOptionsBehavior = class(TcxCustomGridTableOptionsBehavior);

Description

The TcxGridTableOptionsBehavior object contains settings determining the view’s response to keyboard and mouse events.  This class is inherited from the TcxCustomGridTableOptionsBehavior class and publishes properties but does not implement any new functionality.   Its properties determine whether its cell editors are always active, whether the focus can be moved using the Tab and Enter keys, hints are displayed for columns, etc.  Use the OptionsBehavior property to access this set of options.


TcxGridTableOptionsBehavior Hierarchy
Hierarchy

TPersistent

     |

TcxCustomGridOptions

     |

TcxCustomGridTableOptionsBehavior

     |


Properties for TcxGridTableOptionsBehavior
TcxGridTableOptionsBehavior Properties

TcxGridTableOptionsBehavior          Legend

In TcxGridTableOptionsBehavior

ColumnHeaderHints

CopyPreviewToClipboard

ExpandMasterRowOnDblClick

Derived from TcxCustomGridTableOptionsBehavior

AlwaysShowEditor

BestFitMaxRecordCount

CellHints

CopyCaptionsToClipboard

DragDropText

DragFocusing

DragHighlighting

DragOpening

DragScrolling

FocusCellOnCycle

FocusCellOnTab

FocusFirstCellOnNewRecord

GoToNextCellOnEnter

ImmediateEditor

IncSearch

IncSearchItem

NavigatorHints

PullFocusing

Derived from TcxCustomGridOptionsBehavior

PostponedSynchronization

Derived from TcxCustomGridOptions

GridView


TcxGridTableOptionsBehavior.ExpandMasterRowOnDblClick

TcxGridTableOptionsBehavior          See Also

Determines whether master rows within the current view can be expanded by a double-click within the row area.

property ExpandMasterRowOnDblClick: Boolean;

Description

Use the ExpandMasterRowOnDblClick property to prevent master rows from expanding on a double-click within the master row area.

The default action on double-click is cell editing.  But if editing is explicitly prohibited (for instance, the item (column) is read-only), then a double-click expands the row.  The preview section cannot be edited so double-clicking this section always results in row expanding.


TcxGridTableOptionsBehavior.ColumnHeaderHints

TcxGridTableOptionsBehavior

Specifies whether a hint box is displayed when the mouse pointer is hovered over a column containing a clipped caption.

property ColumnHeaderHints: Boolean;

Description

Set the ColumnHeaderHints property to True to display a hint box when moving the mouse pointer over partially visible columns or columns which have their captions clipped by their bounds.  The hint box will contain the caption of the underlying column.

The following image shows a view with several columns.  The column hint is displayed for the second one:

The default value of the ColumnHeaderHints property is True.


TcxGridTableOptionsBehavior.CopyPreviewToClipboard

TcxGridTableOptionsBehavior          See Also

Specifies whether the text displayed in the preview section will be included in the resulting text which is copied to the clipboard.

property CopyPreviewToClipboard: Boolean;

Description

Set the CopyPreviewToClipboard property to True to add the display value of the column which is displayed in the preview section to the resulting text which is copied to the clipboard.  This property is in effect only when the preview section is active.  In the resulting text the column’s caption (if the CopyCaptionsToClipboard is set to True) and its cells’ contents are positioned at the end of the corresponding lines, caption line and content lines.  The Tab character is used to separate the column’s caption and its content within these lines.

The default value of the CopyPreviewToClipboard property is True.


TcxGridTableOptionsCustomize
TcxGridTableOptionsCustomize Object

Hierarchy          Properties          Methods          See Also

Contains settings determining whether a user can customize a view via runtime modifications of the view’s columns.

Unit

cxGridTableView

TcxGridTableOptionsCustomize = class(TcxCustomGridTableOptionsCustomize);

Description

An end-user can customize a view at runtime by performing actions concerning the view’s columns.  These actions include filtering, grouping, sorting, columns resizing and moving.  All these actions can also be performed in code.  The properties of the TcxGridTableOptionsCustomize object control the availability of the column features to end-users.  Some of them depend on others. For instance, if the ColumnMoving property value is False, then the grouping feature and column reordering via the Quick Column Customization dropdown list (refer to the description of the ColumnsQuickCustomizationReordering property for details) are also disabled.

Note: the TcxGridTableOptionsCustomize options settings can be overridden by code.  For instance, if column grouping is disabled (the ColumnGrouping property value is False), then grouping can still be performed by setting the Column.GroupIndex of the required column(s).

Use the OptionsCustomize property to access this options set.


TcxGridTableOptionsCustomize Hierarchy
Hierarchy

TPersistent

     |

TcxCustomGridOptions

     |

TcxCustomGridTableOptionsCustomize

     |


Properties for TcxGridTableOptionsCustomize
TcxGridTableOptionsCustomize Properties

TcxGridTableOptionsCustomize          Legend

In TcxGridTableOptionsCustomize

ColumnFiltering

ColumnGrouping

ColumnHiding

ColumnHidingOnGrouping

ColumnHorzSizing

ColumnMoving

ColumnSorting

ColumnsQuickCustomization

ColumnsQuickCustomizationMaxDropDownCount

ColumnsQuickCustomizationReordering

DataRowSizing

GroupBySorting

GroupRowSizing

Derived from TcxCustomGridTableOptionsCustomize

ItemFiltering

ItemGrouping

ItemHiding

ItemMoving

ItemSorting

Derived from TcxCustomGridOptions

GridView


Methods for TcxGridTableOptionsCustomize
TcxGridTableOptionsCustomize Methods

TcxGridTableOptionsCustomize          Legend

Derived from TcxCustomGridTableOptionsCustomize

SupportsItemsQuickCustomizationReordering


TcxGridTableOptionsCustomize.ColumnFiltering

TcxGridTableOptionsCustomize          See Also

Specifies whether columns can display filter dropdown buttons.

property ColumnFiltering: Boolean;

Description

If the ColumnFiltering property value is True, columns display filter dropdown buttons provided that their Options.Filtering option is enabled.  Otherwise, filter dropdown buttons are not displayed within columns regardless of other settings.

The default value of the ColumnFiltering property is True.


TcxGridTableOptionsCustomize.ColumnGrouping

TcxGridTableOptionsCustomize          See Also

Determines whether the view’s records can be grouped according to column values.

property ColumnGrouping: Boolean;

Description

Use the ColumnGrouping property to determine whether view records can be grouped according to column values.  The view’s grouping feature can also be disabled by setting the ColumnMoving property to False.

The default value of the ColumnGrouping property is True.


TcxGridTableOptionsCustomize.ColumnHiding

TcxGridTableOptionsCustomize          See Also

Determines the manner in which the table view’s columns can be hidden from a view.

property ColumnHiding: Boolean;

Description

Use the ColumnHiding property to determine the manner in which the table view’s columns can be hidden from a view.  When set to False, columns can only be hidden by dragging them to the active customization form.  When ColumnHiding is set to True, columns can also be hidden by dragging their headers, even if the customization form is not displayed.  If a column is displayed within the customization form, it is not visible within the view (i.e. the Visible property value of that column is False).  A column can also be made invisible within the customization form.  Set the Column.VisibleForCustomization property value to True and then a column can only be returned to a view programmatically.

The default value of the ColumnHiding property is False.


TcxGridTableOptionsCustomize.ColumnHidingOnGrouping

TcxGridTableOptionsCustomize          See Also

Indicates whether to hide columns from the view when grouping is applied.

property ColumnHidingOnGrouping: Boolean;

Description

A grid control enables a user to group data displayed within a view by a column or several columns.  Records, which have identical values for grouping columns, are displayed in a single group.

To group by a specific column, the user needs to drag it from the column header panel onto the group-by-box.  By default, ColumnHidingOnGrouping is True.  Thus dragging a column onto the group-by-box hides this column (its Visible property is set to False).

If ColumnHidingOnGrouping is False, the column remains within the view when you drag it onto the group-by-box panel (the Visible property value stays True).

When a column is dragged onto the group-by-box panel, its GroupIndex property is set to a value greater than 0 thus determining the position of the column among other grouping columns.

To enable grouping within a view, make certain that the ColumnGrouping property is set to True.  It is possible to disable grouping for an individual column via its Options.Grouping property.

See the view’s OptionsView.GroupByBox property to specify the visibility of the group-by-box panel.

Columns invisible within a view can be accessed using the Customization form (the Customization form displays those columns which have Visible set to False).  You can drag a column from the Customization form on to the column header panel and this will display the column within a view.  Dragging a column from the column header panel on to the Customization form hides this column from the view.  See the view controller’s Customization property for more information.

The default value of the ColumnHidingOnGrouping property is True.


TcxGridTableOptionsCustomize.ColumnHorzSizing

TcxGridTableOptionsCustomize          See Also

Determines whether the view’s columns can be resized by dragging the sides of column headers.

property ColumnHorzSizing: Boolean;

Description

Set the ColumnHorzSizing property to True to allow column widths to change by dragging their vertical edges.

The default value of the ColumnHorzSizing property is True.


TcxGridTableOptionsCustomize.ColumnMoving

TcxGridTableOptionsCustomize          See Also

Determines whether the table view’s columns can be moved by dragging column headers.

property ColumnMoving: Boolean;

Description

Set ColumnMoving to True to allow columns to be moved by dragging their headers.  Setting this property to False also disables the view’s grouping feature and column reordering via the Quick Column Customization dropdown provided that the ColumnsQuickCustomizationReordering property is set to qcrDefault.

The default value of the ColumnMoving property is True.


TcxGridTableOptionsCustomize.ColumnSorting

TcxGridTableOptionsCustomize          See Also

Determines whether records can be sorted according to column values.

property ColumnSorting: Boolean;

Description

Set the ColumnSorting property to True to allow records to be sorted according to column values.

The default value of the ColumnSorting property is True.


TcxGridTableOptionsCustomize.ColumnsQuickCustomization

TcxGridTableOptionsCustomize          See Also

Specifies whether the Quick Column Customization button is displayed.

property ColumnsQuickCustomization: Boolean;

Description

Set the ColumnsQuickCustomization property to True to display the Quick Column Customization button in the indicator.  This automatically makes the indicator visible if it's not yet displayed.  Otherwise, the button is not displayed.

The default value of the ColumnsQuickCustomization property is False.


TcxGridTableOptionsCustomize.ColumnsQuickCustomizationMaxDropDownCount

TcxGridTableOptionsCustomize          See Also

Specifies the maximum number of column names displayed in the Quick Column Customization dropdown list at a time.

property ColumnsQuickCustomizationMaxDropDownCount: Integer;

Description

When an end-user clicks the Quick Column Customization button, the Quick Column Customization dropdown list is displayed.  The column names defined within the view populate this list.  Set the ColumnsQuickCustomizationMaxDropDownCount property to specify the number of column names displayed in the list at any one time.  If this property's value is set to 0, the visible portion of the dropdown list displays all the columns defined within the view.

The default value of the ColumnsQuickCustomizationMaxDropDownCount property is 0.


TcxGridTableOptionsCustomize.ColumnsQuickCustomizationReordering

TcxGridTableOptionsCustomize          See Also

Specifies whether columns in a Table View can be reordered by dragging column names in the Quick Column Customization dropdown list.

type

  TcxGridQuickCustomizationReordering = (qcrDefault, qcrEnabled, qcrDisabled);

property ColumnsQuickCustomizationReordering: TcxGridQuickCustomizationReordering;

Description

Users can reorder columns in a Table View by selecting and dragging corresponding column names in the Quick Column Customization dropdown list provided that the SupportsItemsQuickCustomizationReordering function returns True.  Multiple column names can be selected by clicking them while holding down the Shift and Ctrl keys.

Use the ColumnsQuickCustomizationReordering property to specify this features’ availability.  All the possible values for this property are listed in the TcxGridQuickCustomizationReordering topic.

Note:	This feature is disabled in Banded Table Views.

The default value of the ColumnsQuickCustomizationReordering property is qcrDefault.


TcxGridTableOptionsCustomize.DataRowSizing

TcxGridTableOptionsCustomize          See Also

Indicates whether the end-user is able to resize data rows.

property DataRowSizing: Boolean;

Description

Set the DataRowSizing property to True to enable the end-user to change the height of data rows by dragging the bottom edge of indicator items.  If the indicator panel is not displayed, this functionality is not available (see the view’s OptionsView.Indicator property).

When the DataRowSizing property is set to True and the user moves the mouse to the bottom edge of an indicator item, the mouse pointer changes, thus indicating that resizing is available:

Changing the height of data rows at runtime affects the OptionsView.DataRowHeight property value specifying the current height of data rows.

Double-clicking an indicator item’s edge sets the OptionsView.DataRowHeight property to 0.  In this case, the height of data rows is determined by the current font settings and the CellAutoHeight property value.

You can also let the end-user change the height of grouping rows by setting the GroupRowSizing property to True.

Note:	when the value of the Position.LineCount property of any banded column which is currently visible within the view exceeds the default value (1) end-users are unable to change the height of data rows by dragging the bottom edge of indicator items (when the grid’s OptionsCustomize.DataRowSizing property is set to True).

The default value of the DataRowSizing property is False.


TcxGridTableOptionsCustomize.GroupBySorting

TcxGridTableOptionsCustomize

Specifies whether sorting data by a column results in grouping by this column.

property GroupBySorting: Boolean;

Description

Enabling the GroupBySorting option allows you to emulate the behavior of MS Outlook 2003.  This implies that clicking a column header results in grouping data by the clicked column’s values.  The previously applied grouping is cleared in such cases.  If the GroupBySorting option is disabled, clicking a column header results in sorting data by this column’s values.

Note that the GroupBySorting option has no effect if sorting via code.

The default value of the GroupBySorting property is False.


TcxGridTableOptionsCustomize.GroupRowSizing

TcxGridTableOptionsCustomize          See Also

Specifies whether an end-user can resize grouping rows.

property GroupRowSizing: Boolean;

Description

The GroupRowSizing property allows an end-user to change the height of grouping rows, i.e. to change the OptionsView.GroupRowHeight property value.  This property specifies the current height of grouping rows, in pixels.

To change the height of a group row, the user drags the bottom edge of an indicator item within a group row.  If resizing of group rows is enabled, the mouse pointer changes when moving to the bottom edge of an indicator item thus indicating that resizing is available.  To make the indicator visible, set the OptionsView.Indicator property to True.

Double-clicking an indicator item’s edge sets the OptionsView.GroupRowHeight property to 0.  In this case, the height of group rows is determined by the current font settings.

The DataRowSizing property gives the end-user an ability to resize data rows.  Refer to its description for more information.

The default value of the GroupRowSizing property is False.


TcxGridTableOptionsData
TcxGridTableOptionsData Object

Hierarchy          Properties          See Also

Contains settings determining the functionality of a data-aware table view.

Unit

cxGridTableView

TcxGridTableOptionsData = class(TcxCustomGridTableOptionsData);

Description

The properties of a TcxGridTableOptionsData object are used to determine which actions can be performed on the data set providing records for the view.  This class is inherited from the TcxCustomGridTableOptionsData class and does not implement any new functionality.  These actions include inserting, appending, editing and deleting records.  The data options also indicate whether confirmation is required before record deletion and whether empty records can be posted into the data set.

Use the OptionsData property to access this set of options.


TcxGridTableOptionsData Hierarchy
Hierarchy

TPersistent

     |

TcxCustomGridOptions

     |

TcxCustomGridTableOptionsData

     |


Properties for TcxGridTableOptionsData
TcxGridTableOptionsData Properties

TcxGridTableOptionsData          Legend

Derived from TcxCustomGridTableOptionsData

Appending

CancelOnExit

Deleting

DeletingConfirmation

Editing

GridView

Inserting

Derived from TcxCustomGridOptions

GridView


TcxGridTableOptionsSelection
TcxGridTableOptionsSelection Object

Hierarchy          Properties          See Also

Contains settings that affect the selection within a view.

Unit

cxGridTableView

TcxGridTableOptionsSelection = class(TcxCustomGridTableOptionsSelection);

Description

The properties of a TcxGridTableOptionsSelection object determine the selection options for a table view.  The TcxGridTableOptionsSelection class is inherited from the TcxCustomGridTableOptionsSelection class and does not implement any new functionality.  Its properties indicate whether to select individual cells or the whole row, whether the focus rectangle is displayed around the focused row and whether multiple rows can be selected, etc.

Use the OptionsSelection property to access this set of options.


TcxGridTableOptionsSelection Hierarchy
Hierarchy

TPersistent

     |

TcxCustomGridOptions

     |

TcxCustomGridOptionsSelection

     |

TcxCustomGridTableOptionsSelection

     |


Properties for TcxGridTableOptionsSelection
TcxGridTableOptionsSelection Properties

TcxGridTableOptionsSelection          Legend

In TcxGridTableOptionsSelection

CellMultiSelect

Derived from TcxCustomGridTableOptionsSelection

CellSelect

HideFocusRect

HideFocusRectOnExit

HideSelection

InvertSelect

MultiSelect

UnselectFocusedRecordOnExit

Derived from TcxCustomGridOptions

GridView


TcxGridTableOptionsSelection.CellMultiSelect

TcxGridTableOptionsSelection          See Also

Specifies whether multiple selections of cells within a (banded) table view are enabled.

property CellMultiSelect: Boolean;

Description

This property lets you select/deselect particular cells within the current (banded) table view’s record selection.  In order to include or exclude all the cells of the specific column to/from the selection, you can set the column’s Selected property to the value you need.  To do this for a set of sequential columns, use the SelectColumns method.  The SelectAllColumns method allows you to select the cells of all the columns within the current record selection, i.e. select the entire record(s).  Use the SelectCells method to explicitly specify the cells that will be included in the selection designated by the column range and row range.  The SelectAllCells method selects all cells within the (banded) table view regardless of the current record selection.

Note:	The MultiSelect property’s value is automatically set to the value passed to the CellMultiSelect property.

Please refer to the SelectedRecords and SelectedColumns properties for details on selected records and columns.

The default value of the CellMultiSelect property is False.


TcxGridTableOptionsView
TcxGridTableOptionsView Object

Hierarchy          Properties          Methods          See Also

Contains settings determining the grid’s appearance (table view).

Unit

cxGridTableView

TcxGridTableOptionsView = class(TcxCustomGridTableOptionsView);

Description

The properties of the TcxGridTableOptionsView object specify the view’s appearance options.  Its properties specify the editor buttons, footer, group footers and column headers visibility, grid lines visibility and color, rows separator color and width, etc.  Some view options affect the view’s behavior.  For instance, if the GroupByBox option is deactivated, then runtime column grouping is disabled (see the GroupByBox description for details).

Use the View’s OptionsView property to access this set of options.


TcxGridTableOptionsView Hierarchy
Hierarchy

TPersistent

     |

TcxCustomGridOptions

     |

TcxCustomGridOptionsView

     |

TcxCustomGridTableOptionsView

     |


Properties for TcxGridTableOptionsView
TcxGridTableOptionsView Properties

TcxGridTableOptionsView          Legend

In TcxGridTableOptionsView

ColumnAutoWidth

DataRowHeight

ExpandButtonsForEmptyDetails

Footer

FooterAutoHeight

FooterMultiSummaries

GridLineColor

GridLines

GridView

GroupByBox

GroupFooterMultiSummaries

GroupFooters

GroupRowHeight

GroupSummaryLayout

Header

HeaderAutoHeight

HeaderEndEllipsis

HeaderHeight

Indicator

IndicatorWidth

NewItemRow

NewItemRowInfoText

NewItemRowSeparatorColor

NewItemRowSeparatorWidth

RowSeparatorColor

RowSeparatorWidth

ShowColumnFilterButtons

Derived from TcxCustomGridTableOptionsView

CellAutoHeight

CellEndEllipsis

CellTextMaxLineCount

GridView

Navigator

NavigatorOffset

ShowEditButtons

Derived from TcxCustomGridOptionsView

ScrollBars

Derived from TcxCustomGridOptions

GridView


Methods for TcxGridTableOptionsView
TcxGridTableOptionsView Methods

TcxGridTableOptionsView          Legend

In TcxGridTableOptionsView

CanShowFooterMultiSummaries

CanShowGroupFooterMultiSummaries

GetGridLineColor

GetGroupSummaryLayout

Derived from TcxCustomGridTableOptionsView

GetNoDataToDisplayInfoText


TcxGridTableOptionsView.ColumnAutoWidth

TcxGridTableOptionsView          See Also

Determines whether column widths are changed in order to display all columns without using the horizontal scrollbar.

property ColumnAutoWidth: Boolean;

Description

Use the ColumnAutoWidth property to determine whether column widths are changed in order to display all columns without using the horizontal scrollbar.  If a column’s content is still too large to display without the grid needing to resize, then that column’s values are truncated and the hidden characters are replaced with an end ellipsis (provided that the CellEndEllipsis option is set to True).

The following image shows a grid table view with the ColumnAutoWidth options active.  Note the way that the Description column values are displayed:

The default value of the ColumnAutoWidth property is False.


TcxGridTableOptionsView.DataRowHeight

TcxGridTableOptionsView          See Also

Specifies the height of a data row (in pixels).

property DataRowHeight: Integer;

Description

By default, the height of the data rows is calculated based upon the height of the in-place editors that are used within the grid.  For the text editors the height is determined by their current font settings (the grid’s Font property).  If the CellAutoHeight property is set to False, each data row will have its height set to a size sufficient to display the cells according to the height of the in-place editors they correspond to.  If the CellAutoHeight property is set to True, each data row may span several lines of text depending upon the contents of the cells within the row.

Setting the DataRowHeight property to a value other than the default overrides these settings.  The height of a data row in this case is the number of pixels specified by the DataRowHeight property.  Whenever this property value exceeds the default value, the contents of cells are automatically shown in all data rows in the manner of multi-line columns.  Note that a grid which uses the image combo box control as an in-place editor is a special case.  The CellAutoHeight property has no effect on calculating the height of this editor since its height is determined by the height of the image displayed within the editor’s edit region.  The list of images that are available for displaying within the editor is accessible via the editor’s Properties.Images property.  As a result, the height of the editor (actually, the height of the images) also affects the minimal value of the DataRowHeight property so the image isn’t displayed clipped.

In a banded table view, the DataRowHeight property is in effect only when columns are arranged in a single row within the view and the column headers occupy a single line (i.e. the columns’ Position.LineCount property value is equal to 1).

To let end-users change the height of data rows, you can set the OptionsCustomize.DataRowSizing property to True.

The default value of the DataRowHeight property is 0.


TcxGridTableOptionsView.ExpandButtonsForEmptyDetails

TcxGridTableOptionsView

Specifies whether to display expand buttons within master rows that doesn’t have associated details.

property ExpandButtonsForEmptyDetails: Boolean;

Description

There may be cases when not all or none of master view’s rows have associated details.  In this case, you can specify whether to display expand buttons for such rows using the ExpandButtonsForEmptyDetails options.  If the option is enabled, all master rows display expand buttons regardless of whether they have details.  If disabled, only master rows with associated details display such buttons.

Enabling expand buttons for empty details may be useful if you need to allow end-users to enter detail data manually.  For instance, you may enable the new item record for detail views so that end-users can expand empty details and type in data required.

Note: in grid mode or when binding details to parameterized dataset, you should handle the data controller’s OnDetailHasChildren event to provide this option’s correct behavior.  If working in provider mode, you should override that data source’s GetDetailHasChildren method.


TcxGridTableOptionsView.Footer

TcxGridTableOptionsView          See Also

Determines whether the footer is displayed.

property Footer: Boolean;

Description

Set the Footer property to True to display a footer row at the bottom of the view. The Footer panel is the area used for displaying footer summaries.  A user can set up summaries using the view’s DataController.Summary property or the column’s Summary property.  For more information about summaries see the Creating Summaries topic.

The default value of the Footer property is False.


TcxGridTableOptionsView.FooterAutoHeight

TcxGridTableOptionsView          See Also

Determines whether the View’s footer is stretched vertically to fit its content completely.

property FooterAutoHeight: Boolean;

Description

If this option is enabled, the footer’s height is automatically adjusted so that the footer summary text for all columns is displayed entirely in each footer cell.  Otherwise, the text in footer cells is clipped.

Property Value equals	False	True

Note:	The FooterAutoHeight option is in effect only when the FooterMultiSummaries property is set to False.

The default value of the FooterAutoHeight property is False.


TcxGridTableOptionsView.FooterMultiSummaries

TcxGridTableOptionsView          See Also

Determines whether the View’s footer displays multiple footer summaries for columns.

property FooterMultiSummaries: Boolean;

Description

If this option is enabled, the footer’s height is automatically adjusted so that each footer line displays the text of a footer summary created for a column.  Otherwise, a single summary is displayed per column.

Property Value equals	False	True

Call the CanShowFooterMultiSummaries function to determine whether the View is set to display multiple summaries per column.

Note:	Setting the FooterMultiSummaries property to False disables the FooterAutoHeight option.

To display multiple group footer summaries for columns, set the GroupFooterMultiSummaries property to True.

The default value of the FooterMultiSummaries property is False.


TcxGridTableOptionsView.GridLineColor

TcxGridTableOptionsView          See Also

Specifies the color of grid lines.

property GridLineColor: TColor;

Description

Use the GridLineColor property to specify the color of grid lines within the view.  Ensure that the GridLines property is not set to glNone in order to display the lines.

The default value of the GridLineColor property is clDefault.


TcxGridTableOptionsView.GridLines

TcxGridTableOptionsView          See Also

Specifies whether grid lines are visible.

type TcxGridLines = (glBoth, glNone, glVertical, glHorizontal);

property GridLines: TcxGridLines;

Description

Set the GridLines property to select which grid lines are displayed in the view.  The possible values are:

Value	Meaning
glBoth	Horizontal and vertical grid lines are visible
glHorizontal	Only horizontal grid lines are visible
glNone	There are no grid lines
glVertical	Only vertical grid lines are visible

Use the GridLineColor property to specify the color of the lines.

The default value of the GridLines property is glBoth.


TcxGridTableOptionsView.GridView

TcxGridTableOptionsView

Identifies the grid table view owning the current set of options.

property GridView: TcxGridTableView;

Description

Use the GridView property to access a grid table view owning the current set of options.  This view provides a user with access to its collection of columns, other options and styles sets, etc.

ReadOnly Property


TcxGridTableOptionsView.GroupByBox

TcxGridTableOptionsView          See Also

Determines whether the grouping panel is visible.

property GroupByBox: Boolean;

Description

Set the GroupByBox property to True to show the grouping.  Setting this property to False disables runtime grouping, but does not affect grouping set up programmatically.

Note:	Regardless of this property's value, grouping at runtime is still available in a grid whenever it has the TcxGridPopupMenu object assigned and this object’s UseBuiltInPopupMenus property is set to True.

The default value of the GroupByBox property is True.


TcxGridTableOptionsView.GroupFooterMultiSummaries

TcxGridTableOptionsView          See Also

Determines whether group footers display multiple group summaries for columns.

property GroupFooterMultiSummaries: Boolean;

Description

If this option is enabled, the height of group footers is automatically adjusted so that each group footer line displays the text of a group summary created for a column.  Otherwise, a single summary is displayed per column.

Property Value equals	False	True

Call the CanShowFooterMultiSummaries function to determine whether the View is set to display multiple summaries per column.

To display multiple footer summaries for columns, set the FooterMultiSummaries property to True.

The default value of the GroupFooterMultiSummaries property is False.


TcxGridTableOptionsView.GroupFooters

TcxGridTableOptionsView          See Also

Specifies whether group footers are visible.

type

  TcxGridGroupFootersMode = (gfInvisible, gfVisibleWhenExpanded, gfAlwaysVisible);

property GroupFooters: TcxGridGroupFootersMode;

Description

The group footer is a panel at the bottom of the group for displaying group summaries.  A group summary is displayed in the group footer only if its Position is set to spFooter.

Use the GroupFooters property to specify when group footers are visible.  The possible values are:

Value	Meaning
gfAlwaysvisible	Group footers are always visible
gfInvisible	Group footers are never visible
gfVisibleWhenExpanded	Group footers are visible only for expanded group rows

The default value of the GroupFooters property is gfInvisible.


TcxGridTableOptionsView.GroupRowHeight

TcxGridTableOptionsView          See Also

Specifies the height of grouping rows (in pixels).

property GroupRowHeight: Integer;

Description

Use the GroupRowHeight property to specify the height of grouping rows in pixels.  To change the height of data rows, use the DataRowHeight property.

If GroupRowHeight is set to 0, the height of grouping rows is calculated automatically based on the current font settings.

You can let the end-user resize grouping rows by dragging the bottom edge of indicators within grouping rows.  For this purpose, use the OptionsCustomize.GroupRowSizing property.

The default value of the GroupRowHeight property is 0.


TcxGridTableOptionsView.GroupSummaryLayout

TcxGridTableOptionsView          See Also

Specifies the position of the group summary text in a row.

property GroupSummaryLayout: TcxGridGroupSummaryLayout;

Description

The GroupSummaryLayout property allows you to specify three positioning options:

•	gslStandard – the group summary text follows the row caption;

•	gslAlignWithColumns – the group summary text is aligned with the column it’s linked to (the text is aligned in the column depending upon the column’s GroupSummaryAlignment property value);

•	gslAlignWithColumnsAndDistribute – the group summary text is aligned with the column it’s linked to.  If a particular column contains two or more group summaries, the column is divided into even blocks and summaries are distributed across them.

Use the GroupSummaryLayout property to specify how group summary text will be arranged in a row.

The default value of the GroupSummaryLayout property is gslStandard.


TcxGridTableOptionsView.Header

TcxGridTableOptionsView          See Also

Determines whether the column’s headers are visible.

property Header: Boolean;

Description

Use the Header property to determine whether the column’s headers are displayed by the view.  Setting this property to False disables runtime column operations (sorting, grouping and moving).  This does not apply to the column changes implemented via code.

The default value of the Header property is True.


TcxGridTableOptionsView.HeaderAutoHeight

TcxGridTableOptionsView          See Also

Determines whether the column header’s height changes to display the full caption text.

property HeaderAutoHeight: Boolean;

Description

Use the HeaderAutoHeight property to determine whether the column header’s height is automatically increased to display the entire caption.

The default value of the HeaderAutoHeight property is False.


TcxGridTableOptionsView.HeaderEndEllipsis

TcxGridTableOptionsView          See Also

Specifies whether to display an ellipsis when the column caption is clipped.

property HeaderEndEllipsis: Boolean;

Description

The HeaderEndEllipsis property determines whether to display an ellipsis in the column header panel when the column width is too small to display the column caption entirely.  The column caption is provided by the Caption property.

The default value of the HeaderEndEllipsis property is False.


TcxGridTableOptionsView.HeaderHeight

TcxGridTableOptionsView          See Also

Specifies the height of column headers (in pixels).

property HeaderHeight: Integer;

Description

Use the HeaderHeight property to specify the height of column headers (in pixels).

In a banded table view, the HeaderHeight property is in effect only when columns are arranged in a single row within the view and the column headers occupy a single line.

The visibility of the column headers’ panel is determined by the Header property.

The default value of the HeaderHeight property is 0.


TcxGridTableOptionsView.Indicator

TcxGridTableOptionsView          See Also

Determines whether the row indicator is displayed.

property Indicator: Boolean;

Description

Set the Indicator property to True to display the row indicator.  Use the IndicatorWidth property to specify the width of the row indicator within a view.  If this property’s value is 0, then the row indicator is not visible.

The default value of the Indicator property is False.


TcxGridTableOptionsView.IndicatorWidth

TcxGridTableOptionsView          See Also

Specifies the row indicator’s width.

property IndicatorWidth: Integer;

Description

Use the IndicatorWidth property to specify the row indicator’s width for the current view.  Note: if this property is set to 0, then the row indicator will not be visible.  You can also use the Indicator property to specify whether the row indicator should be displayed.

The default value of the IndicatorWidth property is cxGridDefaultIndicatorWidth.


TcxGridTableOptionsView.NewItemRow

TcxGridTableOptionsView          See Also

Determines whether the "new item row" record is displayed.

property NewItemRow: Boolean;

Description

Use the NewItemRow property to determine whether the "new item row" record is visible within the current view.  This record is initially empty and is used for inserting new data into a dataset.  The record corresponding to the "new item row" can be accessed via the view’s ViewData.NewItemRecord property.  By default, the text ('Click here to add a new row') is displayed in the background of a new item row.  This text can be changed via the NewItemRowInfoText property.

If a new item row is not displayed within a view, then a user can still add records to a view.  This can be done in two ways: by pressing the down arrow key when focused on the bottom row of the grid or by pressing the Insert key while any row is focused.  Pressing the Insert key inserts a new record before the one currently focused; pressing the down arrow key adds a new record to the end of the underlying data set.

Ensure that the View.OptionsData.Appending and View.OptionsData.Inserting options are active before inserting records as described above.

Note: The NewItemRow property is obsolete.  Use the view’s NewItemRow property instead.

The default value of the NewItemRow property is False.


TcxGridTableOptionsView.NewItemRowInfoText

TcxGridTableOptionsView          See Also

Specifies the text displayed within a new item row.

property NewItemRowInfoText: string;

Description

New item rows allow a user to enter new records within the current (banded) table view.  They are displayed at the top of the view if the NewItemRow property is set to True.  To insert a new record using a new item row, you need to focus the row, populate all the required fields and move the focus to another row within the view.

The NewItemRowInfoText property specifies the static text displayed in the background of the unfocused new item row.  The default text is 'Click here to add a new row'.  You can use the NewItemRowInfoText property to provide a different string to display instead.  Setting NewItemRowInfoText to an empty string clears the caption.  The info text’s style can be customized via the view’s Styles.NewItemRowInfoText property.

Note: The NewItemRowInfoText property is obsolete.  Use the NewItemRow.InfoText property instead.


TcxGridTableOptionsView.NewItemRowSeparatorColor

TcxGridTableOptionsView          See Also

Specifies the color of a line separating the "new item row" record from the other grid view records.

property NewItemRowSeparatorColor: TColor;

Description

Use the NewItemRowSeparatorColor property to specify the color of a line separating the "new item row" from the other grid view rows.

Use the NewItemRowSeparatorWidth property to set the width of the line separating the new item row from the other view records.

The new item row separator in the following image is painted in clRed:

Note: The NewItemRowSeparatorColor property is obsolete.  Use the NewItemRow.SeparatorColor property instead.

The default value of the NewItemRowSeparatorColor property is clDefault.


TcxGridTableOptionsView.NewItemRowSeparatorWidth

TcxGridTableOptionsView          See Also

Specifies the width of a line separating the "new item row" record from the other grid view records.

property NewItemRowSeparatorWidth: Integer;

Description

Use the NewItemRowSeparatorWidth property to specify the width of a line separating the "new item row" record from the other grid view records.

Use the NewItemRowSeparatorColor property to specify the color of the line separating the new item row from the other view records.

The new item row separator width in the following image is set to 6:

Note: The NewItemRowSeparatorWidth property is obsolete.  Use the NewItemRow.SeparatorWidth property instead.

The default value of the NewItemRowSeparatorWidth property is specified by the cxGridDefaultNewItemRowSeparatorWidth constant.


TcxGridTableOptionsView.RowSeparatorColor

TcxGridTableOptionsView          See Also

Specifies the color of the lines separating grid rows from each other.

property RowSeparatorColor: TColor;

Description

Use the RowSeparatorColor property to specify the color of the lines separating the grid rows from each other.

You can use the RowSeparatorWidth property to set the width of row separator lines.

The row separator in the following image is painted in clPurlple:

The default value of the RowSeparatorColor property is clDefault.


TcxGridTableOptionsView.RowSeparatorWidth

TcxGridTableOptionsView          See Also

Specifies the width of the lines separating grid rows from each other.

property RowSeparatorWidth: Integer;

Description

Use the RowSeparatorWidth property to specify the width of the lines separating the grid rows from each other.

You can use the RowSeparatorColor property to specify the color of the row separator lines.

 The row separator width in the following image is set to 5:

The default value of the RowSeparatorWidth property is 0.


TcxGridTableOptionsView.ShowColumnFilterButtons

TcxGridTableOptionsView

Specifies how filter buttons are shown in columns.

type

  TcxGridShowItemFilterButtons = (sfbAlways, sfbWhenSelected);

property ShowColumnFilterButtons: TcxGridShowItemFilterButtons;

Description

One of the two available appearance states can be specified via the ShowColumnFilterButtons property: either filter buttons are shown in all columns (if the ShowColumnFilterButtons property is set to sfbAlways) or only the selected column contains a filter button (if the ShowColumnFilterButtons property is set to sfbWhenSelected).

The default value of the ShowColumnFilterButtons property is sfbWhenSelected.


TcxGridTableOptionsView.CanShowFooterMultiSummaries

TcxGridTableOptionsView          See Also

Determines whether the View can display multiple footer summaries per column.

function CanShowFooterMultiSummaries: Boolean;

Description

This function returns True when the FooterMultiSummaries option is enabled and the View is capable of displaying vertically stacked summaries in a footer panel.

Note:	For Banded Table Views with nested bands, this function returns False.


TcxGridTableOptionsView.CanShowGroupFooterMultiSummaries

TcxGridTableOptionsView          See Also

Determines whether the View can display multiple group footer summaries per column.

function CanShowGroupFooterMultiSummaries: Boolean;

Description

This function returns True when the GroupFooterMultiSummaries option is enabled and the View is capable of displaying vertically stacked summaries in a group footer panel.


TcxGridTableOptionsView.GetGridLineColor

TcxGridTableOptionsView          See Also

Returns the color of grid lines.

function GetGridLineColor: TColor;

Description

The GetGridLineColor method returns a color specified by the OptionsView.GridLineColor property.  If the OptionsView.GridLineColor property is set to clDefault, clBtnShadow will be returned.

Use the GetGridLineColor method to determine the color used for current grid lines.


TcxGridTableOptionsView.GetGroupSummaryLayout

TcxGridTableOptionsView          See Also

Returns the type of group summary text alignment in a row.

type

  TcxGridGroupSummaryLayout = (gslStandard, gslAlignWithColumns, gslAlignWithColumnsAndDistribute);

function GetGroupSummaryLayout: TcxGridGroupSummaryLayout;

Description

The GetGroupSummaryLayout method returns the position of the group summary text in a row specified by the OptionsView.GroupSummaryLayout property.


TcxGridGroupSummaryLayout
TcxGridGroupSummaryLayout type

See Also

Enumerates the types of group summary text alignment in a row.

Unit

cxGridTableView

type

  TcxGridGroupSummaryLayout = (gslStandard, gslAlignWithColumns, gslAlignWithColumnsAndDistribute);

Description

The following table contains descriptions of the enumeration values:

Value	Meaning
gslStandard	Group summary text follows the row’s caption.
gslAlignWithColumns	Group summary text is aligned with the column it’s linked to (the text is aligned in the column depending upon the column’s GroupSummaryAlignment property’s value).
gslAlignWithColumnsAndDistribute	Group summary text is aligned with the column it’s linked to.  If a particular column contains two or more group summaries, the column is divided into even blocks and summaries are distributed across them.


TcxGridTableDateTimeHandling
TcxGridTableDateTimeHandling Object

Hierarchy          Properties          Methods          See Also

Represents a set of options that determine the manner in which columns that display date/time values are filtered or grouped, and how their values are displayed when filtering or grouping is applied.

Unit

cxGridTableView

TcxGridTableDateTimeHandling = class(TcxCustomGridTableDateTimeHandling)

Description

This class does not introduce any new functionality, but instead publishes properties that affect grouping functionality, as follows:

•	appearance aspects of time periods in group rows when data is grouped by a column (HourFormat, DateFormat, UseLongDateFormat, and UseShortTimeFormat);

•	the manner in which date/time values are grouped (Grouping).

Use a tabular View’s DateTimeHandling property to access an instance of the TcxGridTableDateTimeHandling class.


TcxGridTableDateTimeHandling Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |

TcxCustomGridTableDateTimeHandling

     |

TcxGridTableDateTimeHandling


Properties for TcxGridTableDateTimeHandling
TcxGridTableDateTimeHandling Properties

TcxGridTableDateTimeHandling          Legend

Derived from TcxCustomGridTableDateTimeHandling

DateFormat

Filters

GridView

Grouping

HourFormat

IgnoreTimeForFiltering

MonthFormat

UseLongDateFormat

UseShortTimeFormat

YearFormat


Methods for TcxGridTableDateTimeHandling
TcxGridTableDateTimeHandling Methods

TcxGridTableDateTimeHandling          Legend

Derived from TcxCustomGridTableDateTimeHandling

GetDateFormat

GetHourFormat

GetMonthFormat

GetYearFormat


TcxGridTableFiltering
TcxGridTableFiltering Object

Hierarchy          Properties          Methods          See Also

Contains filter settings for the current view.

Unit

cxGridTableView

TcxGridTableFiltering = class(TcxCustomGridTableFiltering);

Description

The TcxGridTableFiltering class contains filter settings for a table view.  These settings specify the filtering features available to end-users.  TcxGridTableFiltering objects are exposed via the Filtering property of table views.

To specify the filter programmatically, use the view’s DataController.Filter property.


TcxGridTableFiltering Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |

TcxCustomGridTableFiltering

     |


Properties for TcxGridTableFiltering
TcxGridTableFiltering Properties

TcxGridTableFiltering          Legend

In TcxGridTableFiltering

ColumnFilteredItemsList

ColumnMRUItemsList

ColumnMRUItemsListCount

ColumnPopup

ColumnPopupDropDownWidth

ColumnPopupMaxDropDownItemCount

Derived from TcxCustomGridTableFiltering

CustomizeDialog

DropDownWidth

ItemMRUItemsList

ItemMRUItemsListCount

ItemPopup

MaxDropDownCount

MRUItemsList

MRUItemsListCount

MRUItemsListDropDownCount

Position

Visible

Derived from TcxCustomGridOptions

GridView


Methods for TcxGridTableFiltering
TcxGridTableFiltering Methods

TcxGridTableFiltering          Legend

Derived from TcxCustomGridTableFiltering

 RunCustomizeDialog


TcxGridTableFiltering.ColumnFilteredItemsList

TcxGridTableFiltering

Specifies whether to display a list of all filter items or only filtered items in filter dropdowns.

property ColumnFilteredItemsList: Boolean;

Description

Set the ColumnFilteredItemsList property to True, to display only filtered items (selected items) in filter dropdowns.

Note: The column’s Options.FilteringFilteredItemsList property specifies the visibility of dropdown items for a specific column.

The default value of the ColumnFilteredItemsList property is False.


TcxGridTableFiltering.ColumnMRUItemsList

TcxGridTableFiltering          See Also

Specifies whether filter dropdowns for columns should display the most recently used filter items.

property ColumnMRUItemsList: Boolean;

Description

If the ColumnMRUItemsList property’s value is True, filter dropdowns for columns display the most recently used filter items at the top of the list.  The maximum number of most recently used filter items that can be displayed within the list is specified by the ColumnMRUItemsListCount property value.

Note:	To disable the most recently used list for a particular column, set its Options.FilteringMRUItemsList property.

The default value of the ColumnMRUItemsList property is True.


TcxGridTableFiltering.ColumnMRUItemsListCount

TcxGridTableFiltering          See Also

Specifies the maximum number of most recently used filter items that can be displayed within filter dropdowns for columns.

property ColumnMRUItemsListCount: Integer;

Description

Filter dropdowns for columns can display a list of the most recently used filter items (MRU list for short).  Each time after a filter item in the dropdown has been selected it is displayed at the top of the MRU list.  The next time another filter item is selected it is added to the top of the MRU list thus increasing the number of filter items in the list.  This takes place until the number of filter items reaches the ColumnMRUItemsListCount property’s value.  After this has happened, selecting a filter item results in this item being added to the top of the MRU list and the bottom filter item in the list being deleted.

The ColumnPopup.MaxDropDownItemCount property’s value specifies the number of filter items that can be displayed simultaneously within filter dropdowns for columns.

The default value of the ColumnMRUItemsListCount property is specified by the cxGridFilterDefaultItemMRUItemsListCount constant.


TcxGridTableFiltering.ColumnPopup

TcxGridTableFiltering

Represents options for a filter dropdown.

property ColumnPopup: TcxGridItemFilterPopupOptions;

Description

With these options, you can specify:

•	the filtering mode used (see the ApplyMultiSelectChanges property);

•	the size of the filter dropdown – its width and the maximum number of items in the filter dropdown (see the DropDownWidth and MaxDropDownItemCount properties);

•	whether multiple selection of the filter dropdown’s items is available (see the MultiSelect property).


TcxGridTableFiltering.ColumnPopupDropDownWidth

TcxGridTableFiltering

Specifies the width of filter dropdowns for columns.

property ColumnPopupDropDownWidth: Integer;

Description

This property is obsolete and used for compatibility purposes.  Use the ColumnPopup.DropDownWidth property instead.


TcxGridTableFiltering.ColumnPopupMaxDropDownItemCount

TcxGridTableFiltering          See Also

Specifies the number of filter items which are displayed within the filter dropdowns for columns simultaneously.

property ColumnPopupMaxDropDownItemCount: Integer;

Description

This property is obsolete and used for compatibility purposes.  Use the ColumnPopup.MaxDropDownItemCount property instead.


TcxGridGroupSummaryHitTest
TcxGridGroupSummaryHitTest Object

Hierarchy          Properties          Methods          See Also

TcxGridGroupSummaryHitTest provides hit information on the inspected group summary that is located in the group caption panel.

Unit

cxGridTableView

TcxGridGroupSummaryHitTest = class(TcxGridRecordHitTest)

Description

A unique identifier (returned by the HitTestCode method) of the group summary  is htGroupSummary.


TcxGridGroupSummaryHitTest Hierarchy
Hierarchy

TcxCustomGridViewHitTest

     |

TcxGridRecordHitTest

     |

TcxGridGroupSummaryHitTest


Properties for TcxGridGroupSummaryHitTest
TcxGridGroupSummaryHitTest Properties

TcxGridGroupSummaryHitTest          Legend

In TcxGridGroupSummaryHitTest

Column

Derived from TcxGridRecordHitTest

GridRecord


Methods for TcxGridGroupSummaryHitTest
TcxGridGroupSummaryHitTest Methods

TcxGridGroupSummaryHitTest          Legend

Derived from TcxGridRecordHitTest

 CanClick


TcxGridGroupSummaryHitTest.Column

TcxGridGroupSummaryHitTest

Represents a column that the summary is calculated for.

property Column: TcxGridColumn;

Description

Use the Column property to access the TcxGridColumn instance.

ReadOnly Property


TcxGridTableSummaryGroupItemLink
TcxGridTableSummaryGroupItemLink Object

Hierarchy          Properties          Methods          See also

Links a grid table column with group summaries within a summary group.

Unit

cxGridTableView

TcxGridTableSummaryGroupItemLink = class(TcxDataSummaryGroupItemLink);

Description

A summary group (TcxDataSummaryGroup) is an association of specific columns with group summaries.  When grid records are grouped by any of these columns, the corresponding group summaries will be calculated.  To associate columns with group summaries within a summary group, use the TcxDataSummaryGroup.Links property which supports a collection of links to proposed group columns.

In (banded) table views, every element in this collection represents an object of the TcxGridTableSummaryGroupItemLink class.  A proposed group column is identified by its Column property.


TcxGridTableSummaryGroupItemLink Hierarchy
Hierarchy

TCollectionItem

     |

TcxCustomDataSummaryItem

     |

TcxDataSummaryGroupItemLink

     |


Properties for TcxGridTableSummaryGroupItemLink
TcxGridTableSummaryGroupItemLink Properties

TcxGridTableSummaryGroupItemLink          Legend

In TcxGridTableSummaryGroupItemLink

Column

Derived from TcxDataSummaryGroupItemLink

SummaryGroupItemLinks

Derived from TcxCustomDataSummaryItem

DataController

ItemLink


Methods for TcxGridTableSummaryGroupItemLink
TcxGridTableSummaryGroupItemLink Methods

TcxGridTableSummaryGroupItemLink          Legend

Derived from TcxCustomDataSummaryItem

 Assign

 BeginUpdate

 EndUpdate


TcxGridTableSummaryGroupItemLink.Column

TcxGridTableSummaryGroupItemLink

Specifies a table view column linked to group summaries within a summary group.

property Column: TcxGridColumn;

Description

A TcxGridTableSummaryGroupItemLink object links a column specified by the Column property to group summaries within a summary group.  When data in a view is grouped by this column, the corresponding group summaries will be calculated.


TcxGridTableSummaryItem
TcxGridTableSummaryItem Object

Hierarchy          Properties          Methods          Events          See also

An object representing a single summary to calculate for a specific column.

Unit

cxGridTableView

TcxGridTableSummaryItem = class(TcxDataSummaryItem);

Description

ExpressQuantumGrid allows you to calculate different summaries using the view’s DataController.Summary property.  The Summary object provides the FooterSummaryItems, DefaultGroupSummaryItems and SummaryGroups properties and these specify the collections of footer summaries, group summaries and summary groups respectively.

Individual summaries within these collections are represented by TcxDataSummaryItem class objects.  When creating summaries in tabular Views, the TcxGridTableSummaryItem class is used instead of TcxDataSummaryItem.  In addition to the settings inherited from the base TcxDataSummaryItem class, the TcxGridTableSummaryItem class introduces members that allow you to specify:

•	the column for which the summary is calculated (Column);

•	the general appearance and the caption for the Group Row Popup Menu item associated with the summary (VisibleForCustomization and DisplayText).


TcxGridTableSummaryItem Hierarchy
Hierarchy

TCollectionItem

     |

TcxCustomDataSummaryItem

     |

TcxDataSummaryItem

     |


Properties for TcxGridTableSummaryItem
TcxGridTableSummaryItem Properties

TcxGridTableSummaryItem          Legend

In TcxGridTableSummaryItem

Column

DisplayText

VisibleForCustomization

Derived from TcxDataSummaryItem

DataController

Format

Kind

Position

Sorted

SummaryItems

Derived from TcxCustomDataSummaryItem

DataController

ItemLink


Methods for TcxGridTableSummaryItem
TcxGridTableSummaryItem Methods

TcxGridTableSummaryItem          Legend

Derived from TcxDataSummaryItem

Assign

FormatValue

Derived from TcxCustomDataSummaryItem

Assign

BeginUpdate

EndUpdate


Events for TcxGridTableSummaryItem
TcxGridTableSummaryItem Events

TcxGridTableSummaryItem          Legend

Derived from TcxDataSummaryItem

OnGetText


TcxGridTableSummaryItem.Column

TcxGridTableSummaryItem

Specifies the column on which to calculate the current summary.

property Column: TcxGridColumn;

Description

The Column property defines the column on which the current summary is calculated.  In practice, Column refers to the ItemLink property introduced in the TcxCustomDataSummaryItem class.


TcxGridTableSummaryItem.DisplayText

TcxGridTableSummaryItem

Specifies the caption of the Group Row Popup Menu item associated with the summary.

property DisplayText: string;

Description

This property is effective for group summaries only.

If this property is assigned an empty string, the item’s caption is determined automatically using the cxSGridSortBySummary resource string as a format pattern.  Refer to the corresponding section in the cxGridPopupMenu: Resource Strings topic for detailed information on this resource string.

Use the VisibleForCustomization property to control the general appearance of the menu item in this popup menu.


TcxGridTableSummaryItem.VisibleForCustomization

TcxGridTableSummaryItem

Specifies whether the menu item associated with the summary will be included into the Group Row Popup Menu.

property VisibleForCustomization: Boolean;

Description

This property is effective for group summaries only.

To specify the caption for this item, use the DisplayText property.

The default value of the VisibleForCustomization property is True.


TcxGridPreview
TcxGridPreview Object

Hierarchy          Properties          See Also

Contains preview settings for the current view.

Unit

cxGridTableView

TcxGridPreview = class(TcxCustomGridOptions);

Description

The TcxGridPreview object contains settings defining the view’s preview settings.  The preview section provides the convenient way of displaying large text fields:

The TcxGridPreview options provide various settings: its position within the view, the number of text lines and the text indent.  The main preview settings are provided by the Visible and Column properties.  These determine the preview section’s visibility and the column to be displayed within the preview area instead of occupying a single column.

Note that until the Column property is properly initialized, the preview is not visible regardless of other settings.

Use the view’s Preview property to access the preview option settings.

You can also specify the preview column for by setting its IsPreview attribute.


TcxGridPreview Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |


Properties for TcxGridPreview
TcxGridPreview Properties

TcxGridPreview          Legend

In TcxGridPreview

Active

AutoHeight

Column

LeftIndent

MaxLineCount

Place

RightIndent

Visible

Derived from TcxCustomGridOptions

GridView


TcxGridPreview.Active

TcxGridPreview          See Also

Determines whether the preview is displayed or hidden.

property Active: Boolean;

Description

Use the Active property to determine whether the preview section is displayed.  To display the preview section, set the column to preview via the Column property and set the Visible property to True.

ReadOnly Property


TcxGridPreview.AutoHeight

TcxGridPreview          See Also

Determines whether the preview section height varies according to the preview’s text length.

property AutoHeight: Boolean;

Description

The preview section height can also be specified via the MaxLineCount property value.  This property setting overrides the AutoHeight property.  Thus, if the MaxLineCount property value is 1, for instance, and the preview section contains several text lines, then only one line will be displayed regardless of the AutoHeight property value.

The default value of the AutoHeight property is True.


TcxGridPreview.Column

TcxGridPreview          See Also

Identifies the column being displayed within the preview section.

property Column: TcxGridColumn;

Description

Use the Column property to specify the view’s column to be displayed within the preview area instead of a single column.  If a column already being displayed within a view is assigned to the Preview.Column property, then its original display is removed from the view but appears again if the Preview.Column property is cleared.

It is also possible to specify the preview column by its IsPreview attribute.  When you set a column’s IsPreview property to True, the column replaces any previous preview column.  Setting IsPreview to False clears and hides the preview section.


TcxGridPreview.LeftIndent

TcxGridPreview          See Also

Specifies the distance between the preview text and the left preview section border.

property LeftIndent: Integer;

Description

Use the LeftIndent property to provide a left margin for the preview text.

Note: The preview text is affected by the LeftIndent and RightIndent values.  If these overlap, then the preview text is not displayed.

The default value of the LeftIndent property is specified by the cxGridPreviewDefaultLeftIndent constant.


TcxGridPreview.MaxLineCount

TcxGridPreview          See Also

The maximum number of text lines displayed within the preview section.

property MaxLineCount: Integer;

Description

Use the MaxLineCount property to specify the maximum number of text lines displayed within the preview section.  This value has a higher priority than the AutoHeight property.  In other words, the MaxLineCount property limits the maximum height.  For instance, if the MaxLineCount property value is 1 and the preview section contains more than one text line, then only one line will be displayed regardless of the AutoHeight property value.

The default value of the MaxLineCount property is specified by the cxGridPreviewDefaultMaxLineCount constant.


TcxGridPreview.Place

TcxGridPreview

Specifies the preview section position within a view.

type TcxGridPreviewPlace = (ppBottom, ppTop);

property Place: TcxGridPreviewPlace;

Description

Use the Place property to specify the preview section position relative to the row for which it is displayed.  The list of possible values include:

Value	Meaning
ppBottom	The preview is displayed at the bottom of the row
ppTop	The preview is displayed at the top of the row

The default value of the Place property is ppBottom.


TcxGridPreview.RightIndent

TcxGridPreview          See Also

Specifies the distance between the preview text and the right preview section border.

property RightIndent: Integer;

Description

Use the RightIndent property to provide a right margin for the preview text.

Note: The preview text is affected by the LeftIndent and RightIndent values.  If these overlap, then the preview text is not displayed.

The default value of the RightIndent property is specified by the cxGridPreviewDefaultRightIndent constant.


TcxGridPreview.Visible

TcxGridPreview          See Also

Determines whether the preview section is displayed.

property Visible: Boolean;

Description

Use the Visible property to determine whether the preview section is visible within the view.  If True, the preview section is displayed, but it may be empty.  To display preview text, you should assign its Column property.  Once a column’s values are displayed within the preview section they no longer display with the other columns.

The default value of the Visible property is False.


cxGridTableView Unit Overview
cxGridTableView Unit

Classes

TcxCustomGridColumnHitTest

TcxCustomGridRow

TcxGridColumn

TcxGridColumnHeaderFilterButtonHitTest

TcxGridColumnHeaderHitTest

TcxGridColumnHeaderHorzSizingEdgeHitTest

TcxGridColumnOptions

TcxGridColumnStyles

TcxGridColumnSummary

TcxGridDataRow

TcxGridFilterRow

TcxGridFilterRowOptions

TcxGridFooterCellHitTest

TcxGridFooterHitTest

TcxGridGroupByBoxHitTest

TcxGridGroupFooterCellHitTest

TcxGridGroupFooterHitTest

TcxGridGroupRow

TcxGridGroupSummaryHitTest

TcxGridHeaderHitTest

TcxGridIndicatorHeaderHitTest

TcxGridIndicatorHitTest

TcxGridMasterDataRow

TcxGridNewItemRow

TcxGridNewItemRowOptions

TcxGridPreview

TcxGridRowFooterCellViewInfo

TcxGridRowIndicatorHitTest

TcxGridRowLevelIndentHitTest

TcxGridRowSizingEdgeHitTest

TcxGridSpecialRowOptions

TcxGridTableBackgroundBitmaps

TcxGridTableController

TcxGridTableDateTimeHandling

TcxGridTableEditingController

TcxGridTableFiltering

TcxGridTableOptionsBehavior

TcxGridTableOptionsCustomize

TcxGridTableOptionsData

TcxGridTableOptionsSelection

TcxGridTableOptionsView

TcxGridTableSummaryGroupItemLink

TcxGridTableSummaryItem

TcxGridTableView

TcxGridTableViewStyles

TcxGridTableViewStyleSheet

TcxGridViewData

Other Types

TcxGridFilterRowApplyChangesMode

TcxGridGroupSummaryLayout

Global Constants

cxGridCustomRowSeparatorDefaultWidth


TcxGridTableBackgroundBitmaps
TcxGridTableBackgroundBitmaps Object

Hierarchy          Properties          Methods

Provides background bitmaps for elements of a table view.

Unit

cxGridTableView

TcxGridTableBackgroundBitmaps = class(TcxCustomGridTableBackgroundBitmaps)

Description

The TcxGridTableBackgroundBitmaps object can be accessed via the BackgroundBitmaps property of table views (TcxGridTableView and TcxGridDBTableView objects).  It provides properties that enable you to assign bitmaps to elements of these views.  These properties and their corresponding elements are:

•	the background of the view (the Background property);

•	data cells (the Content property);

•	the filter box (the FilterBox property);

•	the view’s footer (the Footer property);

•	grouping rows (the Group property);

•	the group by box (the GroupByBox property);

•	column headers (the Header property);

•	indicator (the Indicator property);

•	preview sections (the Preview property).

To locate these elements within the grid view, please refer to the Grid View Elements topic.

The Background and Content properties are inherited from the TcxCustomGridTableBackgroundBitmaps  class.  These are common for objects providing background bitmaps for any views.  The TcxGridTableBackgroundBitmaps object introduces properties specific for table views.  This object also serves as the base for the TcxGridBandedTableBackgroundBitmaps class that provides bitmaps for banded table views.


TcxGridTableBackgroundBitmaps Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |

TcxCustomGridBackgroundBitmaps

     |

TcxCustomGridTableBackgroundBitmaps

     |


Properties for TcxGridTableBackgroundBitmaps
TcxGridTableBackgroundBitmaps Properties

TcxGridTableBackgroundBitmaps          Legend

In TcxGridTableBackgroundBitmaps

Footer

Group

GroupByBox

Header

Indicator

Preview

Derived from TcxCustomGridTableBackgroundBitmaps

Content

FilterBox

Derived from TcxCustomGridBackgroundBitmaps

Background

Values


Methods for TcxGridTableBackgroundBitmaps
TcxGridTableBackgroundBitmaps Methods

TcxGridTableBackgroundBitmaps          Legend

Derived from TcxCustomGridBackgroundBitmaps

Assign


TcxGridTableBackgroundBitmaps.Footer

TcxGridTableBackgroundBitmaps

Specifies the background bitmap for the view’s footer.

property Footer: TBitmap;

Description

The Footer property allows you to set the background bitmap for a tabular grid view’s footer.  The image below shows an example.

The view’s footer is only visible when the OptionsView.Footer property is set to True.


TcxGridTableBackgroundBitmaps.Group

TcxGridTableBackgroundBitmaps

Specifies the background bitmap for grouping rows.

property Group: TBitmap;

Description

The Group property allows you to set the background bitmap for a tabular grid view’s grouping row.

Group rows are visible when grouping is applied to a view.  See the GroupIndex property of table view items for details on grouping the view programmatically.  Also, see the OptionsCustomize.ColumnGrouping and OptionsView.GroupByBox properties of views and Options.Grouping property of columns for details on allowing end users to perform grouping.


TcxGridTableBackgroundBitmaps.GroupByBox

TcxGridTableBackgroundBitmaps

Specifies the background bitmap for the "Group By" box.

property GroupByBox: TBitmap;

Description

The GroupByBox property allows you to set the background bitmap for a tabular grid view’s "Group By" box.  The image below displays an example.

The "Group By" box is visible when the OptionsView.GroupByBox property of the view is set to True.


TcxGridTableBackgroundBitmaps.Header

TcxGridTableBackgroundBitmaps

Specifies the background image for column headers.

property Header: TBitmap;

Description

The Header property allows you to set the background bitmap for column headers.  The image below shows an example.

You can control the visibility of column headers using the OptionsView.Header property of the view.


TcxGridTableBackgroundBitmaps.Indicator

TcxGridTableBackgroundBitmaps

Specifies the background image for the indicator panel.

property Indicator: TBitmap;

Description

The Indicator property allows you to set the background bitmap for a tabular grid view’s indicator.  The image below shows an example.

To locate the indicator within a grid view, please refer to the Grid View Elements topic.  The visibility of the indicator is specified by the OptionsView.Indicator property of the view.


TcxGridTableBackgroundBitmaps.Preview

TcxGridTableBackgroundBitmaps

Specifies the background bitmap for preview panels.

property Preview: TBitmap;

Description

The Preview property allows you to set the background bitmap for a tabular grid view’s preview section.

To locate the preview section within a grid view, please refer to the Grid View Elements topic.  The preview section is visible if the Preview.Visible property of the view is set to True and the Preview.Column property is set to one of columns within the view.


TcxGridTableController
TcxGridTableController Object

Hierarchy          Properties          Methods

Represents a controller class for (banded) table views.

Unit

cxGridTableView

TcxGridTableController = class(TcxCustomGridTableController)

Description

The TcxGridTableController class represents a controller for a grid table view.  A banded table view provides its own controller which inherits from TcxGridTableController.

The functionality of the class can be accessed via the view’s Controller property.

You can use members of a view controller to:

•	control editing of a record cell;

•	set focus to a specific column and record;

•	start/cancel an incremental search;

•	access the collection of selected records;

•	perform scrolling;

•	navigate records and items;

•	display/hide the customization form.

Most properties declared in TcxGridTableController are wrappers for the properties introduced in the base TcxCustomGridTableController class.


TcxGridTableController Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxGridViewHandler

     |

TcxCustomGridController

     |

TcxCustomGridTableController

     |


Properties for TcxGridTableController
TcxGridTableController Properties

TcxGridTableController          Legend

In TcxGridTableController

EditingController

FocusedColumn

FocusedColumnIndex

FocusedRow

FocusedRowIndex

LeftPos

SelectedColumnCount

SelectedColumns

SelectedRowCount

SelectedRows

TopRowIndex

Derived from TcxCustomGridTableController

Customization

CustomizationForm

CustomizationFormBounds

EditingController

EditingItem

FocusedItem

FocusedItemIndex

FocusedRecord

FocusedRecordIndex

IncSearchingItem

IncSearchingText

IsEditing

IsIncSearching

SelectedRecordCount

SelectedRecords

TopRecordIndex

Derived from TcxGridViewHandler

Control

Controller

DataController

GridView

ViewData


Methods for TcxGridTableController
TcxGridTableController Methods

TcxGridTableController          Legend

In TcxGridTableController

ClearCellSelection

IsFilterRowFocused

IsNewItemRowFocused

IsSpecialRowFocused

SelectAllCells

SelectAllColumns

SelectCells

SelectColumns

Derived from TcxCustomGridTableController

CancelIncSearching

ClearSelection

CreateNewRecord

DeleteSelection

FindNextItem

FindNextRecord

FocusFirstAvailableItem

FocusNextCell

FocusNextItem

FocusNextRecord

FocusNextRecordWithSelection

GoToFirst

GoToLast

GoToNext

GoToPrev

MakeFocusedItemVisible

MakeFocusedRecordVisible

MakeItemVisible

MakeRecordVisible

Derived from TcxCustomGridController

Scroll

Derived from TcxGridViewHandler

BeginUpdate

Create

EndUpdate


TcxGridTableController.EditingController

TcxGridTableController

Represents a controller that handles editing operations specific to a table view.

property EditingController: TcxGridTableEditingController;

Description

The TcxGridTableEditingController object takes care of all stages of in-place editing in data rows or a filter row, and updates the view based upon either the data being editing or the filter being applied.

Use the EditingController property to access the controller instance.

ReadOnly Property


TcxGridTableController.FocusedColumn

TcxGridTableController          See Also

Gets the focused column within the current view.

property FocusedColumn: TcxGridColumn;

Description

Use the FocusedColumn property to specify the column being focused within the view.

The FocusedColumn is a wrapper for the FocusedItem property.  FocusedItem references a TcxCustomGridTableItem object and FocusedColumn casts it to the TcxGridColumn class.  Please refer to the FocusedItem property topic for details.


TcxGridTableController.FocusedColumnIndex

TcxGridTableController          See Also

Specifies the index of the focused column.

property FocusedColumnIndex: Integer;

Description

Use the FocusedColumnIndex property to specify the index of the focused column.  Setting the FocusedColumnIndex property moves focus to a corresponding column which can be accessed via the FocusedColumn property.

Items in (banded) table views stand for columns.  FocusedColumnIndex is a wrapper for the FocusedItemIndex property.  FocusedColumnIndex and FocusedItemIndex can be used interchangeably.  Refer to the FocusedItemIndex topic for more details.


TcxGridTableController.FocusedRow

TcxGridTableController          See Also

Gets the focused row within the current view.

property FocusedRow: TcxCustomGridRow;

Description

Records in (banded) table views are represented as rows.  The FocusedRow property just addresses the FocusedRecord property value cast to TcxCustomGridRow class and does not introduce new functionality.  FocusedRow and FocusedRecord can be used interchangeably.

See to the FocusedRecord topic for more information.


TcxGridTableController.FocusedRowIndex

TcxGridTableController          See Also

Specifies the index of the focused row within the current view.

property FocusedRowIndex: Integer;

Description

The FocusedRowIndex specifies the position of the focused row within the view.

Records in (banded) table views are represented as rows.  The FocusedRowIndex is a wrapper for the FocusedRecordIndex property introduced in the TcxCustomGridTableController class.  FocusedRowIndex and FocusedRecordIndex can be used interchangeably.

See the FocusedRecordIndex topic for more details.


TcxGridTableController.LeftPos

TcxGridTableController          See Also

Specifies the horizontal offset of the views contents.

property LeftPos: Integer;

Description

You can use the LeftPos property to scroll the current view horizontally.

When the total width of all view columns is greater than the view window and the view’s OptionsView.ScrollBars property is set to ssHorizontal or ssBoth, a horizontal scrollbar appears thus enabling scrolling.

LeftPos specifies the offset, in pixels, of the visible view portion relative to the left edge of the first column.

To scroll the view vertically, see the TopRecordIndex property.  The Scroll method allows you to simulate user actions with a scrollbar.  Refer to its description for more information.  To make a specific column visible, use the MakeItemVisible method.

The following example scrolls the view contents to make the rightmost column visible.  It subtracts the ViewInfo.ScrollableAreaWidth value from ViewInfo.DataWidth thus getting the maximum offset for the LeftPos property:

//Delphi

var

  AView: TcxGridTableView;

//...

  if Grid.FocusedView is TcxGridTableView then

    with TcxGridTableView(Grid.FocusedView) do

      Controller.LeftPos :=

        ViewInfo.DataWidth - ViewInfo.ScrollableAreaWidth;

//C++ Builder

  TcxGridTableView * AView;

  if (AView = dynamic_cast<TcxGridTableView *>(Grid->FocusedView))

    AView->Controller->LeftPos =

      AView->ViewInfo->DataWidth - AView->ViewInfo->ScrollableAreaWidth;


TcxGridTableController.SelectedColumnCount

TcxGridTableController          See Also

Gets the number of selected columns within the current (banded) table view.

property SelectedColumnCount: Integer;

Description

A column is called "selected" whenever it has at least one cell which is selected within the current (banded) table view’s record selection.  The SelectedColumnCount property returns the number of such columns.

To enable cell selection, set the view’s OptionsSelection.CellMultiSelect property to True.

Please refer to the SelectedRecords property for details on selected records.

ReadOnly Property


TcxGridTableController.SelectedColumns

TcxGridTableController          See Also

Provides indexed access to selected columns within the current (banded) table view.

property SelectedColumns[Index: Integer]: TcxGridColumn;

Description

A column is called "selected" whenever it has at least one cell which is selected within the current (banded) table view’s record selection.  The SelectedColumns property provides indexed access to such columns.

To enable cell selection, set the view’s OptionsSelection.CellMultiSelect property to True.

Please refer to the SelectedRecords property for details on selected records.

ReadOnly Property


TcxGridTableController.SelectedRowCount

TcxGridTableController          See Also

Gets the number of selected rows within the current view.

property SelectedRowCount: Integer;

Description

The SelectedRowCount property returns the number of selected rows within the current view.

Records within a (banded) table view are represented as rows.  The SelectedRecordCount property returns the same value as SelectedRowCount.  These properties denote the same and can be used interchangeably.  See the SelectedRecordCount topic for more information.

ReadOnly Property


TcxGridTableController.SelectedRows

TcxGridTableController          See Also

Provides indexed access to selected rows within the current view.

property SelectedRows[Index: Integer]: TcxCustomGridRow;

Description

Use the SelectedRows property to access selected rows within the current view when the grid is in default mode (GridMode is False).

Records within a (banded) table view are represented as rows.  SelectedRows is just a wrapper for the SelectedRecords property which returns TcxCustomGridRecord objects.  The SelectedRows property casts an object returned by SelectedRecords to TcxCustomGridRow class.  So the difference between these properties is the type of objects returned.

Please refer to the SelectedRecords for details on selected rows.

ReadOnly Property


TcxGridTableController.TopRowIndex

TcxGridTableController          See Also

Specifies the topmost visible row within the current view.

property TopRowIndex: Integer;

Description

TopRowIndex specifies the index of the row displayed at the top of the visible view portion.  You can use the TopRowIndex property to scroll the view contents programmatically.

Records within a (banded) table view are represented as rows.  The TopRowIndex property is a wrapper for the TopRecordIndex property.  They denote the same and can be used interchangeably.

Refer to the TopRecordIndex topic for the description.


TcxGridTableController.ClearCellSelection

TcxGridTableController          See Also

Clears the column selection within a (banded) table view.

procedure ClearCellSelection;

Description

Call the ClearCellSelection method to clear the current column selection within the (banded) table view.  All cells within the view will be deselected.  The SelectedColumnCount property returns 0 in this case.  The ClearCellSelection method does not deselect records/rows, use the DataController.ClearSelection method for this purpose.

Please refer to the SelectedRecords and SelectedColumns properties for details on selected records and columns.


TcxGridTableController.IsFilterRowFocused

TcxGridTableController          See Also

Returns True when a filter row is displayed and focused in a (Banded) Table View.

function IsFilterRowFocused: Boolean;


TcxGridTableController.IsNewItemRowFocused

TcxGridTableController          See Also

Returns True when a new item row is displayed and focused in a (Banded) Table View.

function IsNewItemRowFocused: Boolean;


TcxGridTableController.IsSpecialRowFocused

TcxGridTableController          See Also

Returns True when a utility row is displayed and focused in a (Banded) Table View.

function IsSpecialRowFocused: Boolean; virtual;

Description

By default this function returns True when either a filter row or new item row is displayed and focused.


TcxGridTableController.SelectAllCells

TcxGridTableController          See Also

Selects all the cells within a (banded) table view.

procedure SelectAllCells;

Description

Call the SelectAllCells method to select all the cells within the (banded) table view regardless of the current record selection.  This method selects all the records and column cells, which are visible - or potentially visible by scrolling - within the view.  Records hidden within collapsed group rows are not selected.  In order to select a specific cell or cells within the record selection, use the SelectColumns or SelectCells methods.

Please refer to the SelectedRecords and SelectedColumns properties for details on selected records and columns.


TcxGridTableController.SelectAllColumns

TcxGridTableController          See Also

Selects all columns within the (banded) table view’s currently selected records.

procedure SelectAllColumns;

Description

By calling the SelectAllColumns method you select all columns (i.e. their cells) within the (banded) table view’s currently selected records.  In order to select a specific cell or cells within the record selection, use the SelectColumns or SelectCells methods.

Please refer to the SelectedRecords and SelectedColumns properties for details on selected records and columns.


TcxGridTableController.SelectCells

TcxGridTableController          See Also

Selects specific cells within a (banded) table view.

procedure SelectCells(AFromColumn, AToColumn: TcxGridColumn; AFromRowIndex, AToRowIndex: Integer);

Description

Call the SelectCells method to select all the cells in the columns within the column range defined by the AFromColumn and AToColumn parameters and records (rows) within the row range defined by the AFromRowIndex and AToRowIndex parameters.  The AFromRowIndex and AToRowIndex parameters designate the bound row indexes for the rows in the row range which specifies the record selection while the AFromColumn and AToColumn parameters represent bound columns for the column range which specifies the columns whose cells will be selected.  The order in which parameters in each parameter pair are specified does not matter, e.g. the column denoted by the AToColumn can precede (using its horizontal position) the column which corresponds to the AFromColumn parameter.

Note: the SelectCells method automatically clears the current selection (if any) within the view prior to making a new one.

In order to select all columns (their cells) within the current record selection, use the SelectAllColumns method.

To enable cell (column) selection, set the view’s OptionsSelection.CellMultiSelect property to True.

Please refer to the SelectedRecords and SelectedColumns properties for details on selected records and columns.


TcxGridTableController.SelectColumns

TcxGridTableController          See Also

Selects specific columns within the (banded) table view’s currently selected records.

procedure SelectColumns(AFromColumn, AToColumn: TcxGridColumn);

Description

Call the SelectColumns method to select only specific columns (i.e. their cells) within the (banded) table view’s currently selected records.  The column range is defined by the AFromColumn and AToColumn parameters.  The AFromColumn and AToColumn parameters represent bound columns for the column range which specifies the columns whose cells will be selected.  The order in which parameters are specified does not matter, e.g. the column denoted by the AToColumn can precede (using its horizontal position) the column which corresponds to the AFromColumn parameter.

Note: the SelectColumns method automatically deselects the columns which are outside the column range specified by the parameters.

Use the SelectAllColumns method to select all columns (their cells) within the current record selection.  In order to select specific cells (columns and rows) within a view, call the SelectCells method.

If the column specified by the parameter is not visible within the view, then the first visible column is used instead of the AFromColumn parameter and the last visible column is used instead of the AToColumn parameter.

For instance, the following code example is the equivalent to the SelectAllColumns method’s call.

//Delphi

tableView.Controller.SelectColumns(nil, nil);

//C++ Builder

tableView->Controller->SelectColumns(NULL, NULL);

To enable cell (column) selection, set the view’s OptionsSelection.CellMultiSelect property to True.

Please refer to the SelectedRecords and SelectedColumns properties for details on selected records and columns.


TcxGridTableEditingController
TcxGridTableEditingController Object

Hierarchy          Properties          Methods

The TcxGridTableEditingController class handles editing operations specific to a table view.

Unit

cxGridTableView

TcxGridTableEditingController = class(TcxGridEditingController)

Description

The TcxGridTableEditingController class oversees end-user interaction with data rows or a filter row in a table view.

The TcxGridTableEditingController object is referenced by the Contoller.EditingController property.


TcxGridTableEditingController Hierarchy
Hierarchy

TObject

     |

TcxGridEditingController

     |

TcxGridTableEditingController


Properties for TcxGridTableEditingController
TcxGridTableEditingController Properties

TcxGridTableEditingController          Legend

Derived from TcxGridEditingController

Edit

EditingItem

IsEditing


Methods for TcxGridTableEditingController
TcxGridTableEditingController Methods

TcxGridTableEditingController          Legend

Derived from TcxGridEditingController

 HideEdit

 ShowEdit


TcxGridTableView
TcxGridTableView Object

Hierarchy          Properties          Methods          Events          See Also

Represents a view implementing tabular data representation.

Unit

cxGridTableView

TcxGridTableView = class(TcxCustomGridTableView);

Description

The TcxGridTableView class represents a view of your data in table form.  The key element of the grid table view is a column.  Columns provide a convenient way to represent data allowing an end-user to customize a view by sorting, filtering and grouping data.  Each column is an instance of the TcxGridColumn class.  Members of this class define the sorting order for a column, column position and visibility within a view, styles applied to a column, etc.   All view columns can be accessed via the Columns property.

The columns position within a view is determined via the Column.GroupIndex and Column.VisibleIndex properties.  The Column.GroupIndex property defines the columns position among the grouped columns in the group panel.  The Column.VisibleIndex property defines the columns position within the table view.

References to all visible columns of the table view are stored within the VisibleColumns collection.  References to grouped columns collection are stored in the GroupedColumns property.

At runtime grouping can be done by the end-user by clicking and dragging a column header to the group panel of the Table view.

The grid table view has several option sets which manage the different aspects of the view behavior and appearance.  These sets include:

•	OptionsBehavior which contains that determine how a Table view will react to end-user actions;

•	OptionsCustomize which contains settings that control the availability of the customization options to end-users at runtime;

•	OptionsData which contains settings that determine the functionality of a data-aware Table view;

•	OptionsSelection which contains settings that are to do with row and cell selections within a Table view;

•	OptionsView which contains settings that control the appearance of a Table view;

•	Filtering which controls the filter settings for a Table view;

•	FilterBox which contains appearance options of the filter box within a Table view.

•	Preview which contains settings that determine the appearance of the preview section within a Table view;

•	DateTimeHandling which contains settings that control the manner in which date/time values are handled within a Table view.

The view object also publishes the set of styles that affect the appearance of view elements which are accessible via the Styles property.


TcxGridTableView Hierarchy
Hierarchy

TComponent

     |

TcxControlChildComponent

     |

TcxCustomGridView

     |

TcxCustomGridTableView

     |


Properties for TcxGridTableView
TcxGridTableView Properties

TcxGridTableView          Legend

In TcxGridTableView

BackgroundBitmaps

ColumnCount

Columns

Controller

DateTimeHandling

Filtering

FilterRow

GroupedColumnCount

GroupedColumns

NewItemRow

OptionsBehavior

OptionsCustomize

OptionsData

OptionsSelection

OptionsView

Preview

Styles

ViewData

VisibleColumnCount

VisibleColumns

Derived from TcxCustomGridTableView

Control

Controller

DataController

DateTimeHandling

FilterBox

GroupedItemCount

GroupedItems

ItemCount

Items

MasterGridRecord

NavigatorButtons

OptionsBehavior

OptionsCustomize

OptionsData

OptionsSelection

OptionsView

Styles

SortedItemCount

SortedItems

ViewData

VisibleItemCount

VisibleItems

Derived from TcxCustomGridView

CloneCount

Clones

Controller

DataController

DragMode

Focused

IsControlFocused

IsDetail

IsMaster

IsPattern

Level

MasterGridRecordIndex

MasterGridView

MasterRecordIndex

OptionsSelection

OptionsView

PatternGridView

Site

Styles

ViewData

ViewInfo

Visible

Derived from TcxControlChildComponent

Control

IsDestroying

IsLoading


Methods for TcxGridTableView
TcxGridTableView Methods

TcxGridTableView          Legend

In TcxGridTableView

 CreateColumn

Derived from TcxCustomGridTableView

 ApplyBestFit

 ClearItems

 CopyToClipboard

 CreateItem

 FindItemByID

 FindItemByName

 IndexOfItem

 MakeMasterGridRecordVisible

 RestoreDefaults

Derived from TcxCustomGridView

 BeginUpdate

 CancelUpdate

 EndUpdate

 GetHitTest

 LayoutChanged

 RestoreDefaults

 RestoreFromIniFile

 RestoreFromRegistry

 RestoreFromStream

 SizeChanged

 StoreToIniFile

 StoreToRegistry

 StoreToStream

 ViewChanged

Derived from TcxControlChildComponent

 CreateEx

 Destroy


Events for TcxGridTableView
TcxGridTableView Events

TcxGridTableView          Legend

In TcxGridTableView

OnColumnHeaderClick

OnColumnPosChanged

OnColumnSizeChanged

OnCustomDrawColumnHeader

OnCustomDrawFooterCell

OnCustomDrawGroupCell

OnCustomDrawGroupSummaryCell

OnCustomDrawIndicatorCell

OnLeftPosChanged

Derived from TcxCustomGridTableView

OnCanSelectRecord

OnCellClick

OnCustomDrawCell

OnCustomDrawPartBackground

OnCustomization

OnEditChanged

OnEditing

OnEditValueChanged

OnFilterControlDialogShow

OnFilterCustomization

OnFilterDialogShow

OnFocusedItemChanged

OnFocusedRecordChanged

OnGetCellHeight

OnInitEdit

OnInitEditValue

OnInitGroupingDateRanges

OnSelectionChanged

OnTopRecordIndexChanged

Derived from TcxCustomGridView

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnGetStoredProperties

OnGetStoredPropertyValue

OnInitStoredObject

OnMouseDown

OnMouseEnter

OnMouseLeave

OnMouseUp

OnSetStoredPropertyValue

OnStartDrag


TcxGridTableView.BackgroundBitmaps

TcxGridTableView

Specifies background bitmaps for the visual elements of the view.

property BackgroundBitmaps: TcxGridTableBackgroundBitmaps;

Description

Use the BackgroundBitmaps property to specify background images for elements of the TableView.  The TcxGridTableBackgroundBitmaps object represents the property’s value.  The object provides properties of the TBitmap type that specify the bitmaps used as the background of specific elements.  See the TcxGridTableBackgroundBitmaps class description for details.

Note that background images can also be applied to elements of the view using styles.  Set the Bitmap property of the applied style to the desired value to implement this.  Styles are assigned to elements of views using the Styles property.


TcxGridTableView.ColumnCount

TcxGridTableView          See Also

Returns the total number of columns within the current table view.

property ColumnCount: Integer;

Description

The ColumnCount property returns the total number of columns within the table view.  All columns are stored within the Columns collection.

ReadOnly Property


TcxGridTableView.Columns

TcxGridTableView          See Also

Provides indexed access to the table views columns.

property Columns[Index: Integer]: TcxGridColumn;

Description

Use the Columns property to access columns of the table view.  Each column will be an instance of the TcxGridColumn class.  The properties of the column class allow you to specify the sort order for a column, where the column will appear in the view or in the group panel, data settings, column behavior, editors for the columns cells, styles for the columns elements, etc.


TcxGridTableView.Controller

TcxGridTableView

Specifies a controller for the current view.

property Controller: TcxGridTableController;

Description

A controller provides handlers for keyboard and mouse events on behalf of a view.  You can use these methods in your projects depending on your needs.

A view controller enables you to:

-	control editing of a record cell;

-	set focus to a specific column and record;

-	start/cancel an incremental search;

-	access the collection of selected records and cells;

-	perform scrolling;

-	navigate records and items;

-	display/hide the customization form;

-	select/deselect cells.

ReadOnly Property


TcxGridTableView.DateTimeHandling

TcxGridTableView

Provides a set of options that control the manner in which date/time values are handled in the current Table view.

property DateTimeHandling: TcxGridTableDateTimeHandling;

Description

Use this property to access settings that determine the manner in which date/time value columns are filtered and grouped, and how these values are displayed when filtering or grouping is applied.  Refer to the description of the TcxGridTableDateTimeHandling class for available options.

Note:	To override the view’s DateTimeHandling.IgnoreTimeForFiltering and DateTimeHandling.Grouping options for a particular column, use the column’s Options.IgnoreTimeForFiltering and DateTimeGrouping properties, respectively.


TcxGridTableView.Filtering

TcxGridTableView          See Also

Contains settings required for implementing filtering within the table view.

property Filtering: TcxGridTableFiltering;

Description

Use the Filtering property to specify settings required for implementing filters within the table view.  These settings specify the maximum number of items within the filters dropdown, the width of the filters dropdown and whether the filter panel is visibility.

To set filtering for a view see the DataController.Filter property.


TcxGridTableView.FilterRow

TcxGridTableView          See Also

Specifies filter row options.

property FilterRow: TcxGridFilterRowOptions;

Description

The FilterRow property provides options which allow you to specify the filter row’s visibility (see the Visible property), its description (see the InfoText property), the width and color of the separator that visually divides the filter row from data rows (see SeparatorWidth and SeparatorColor properties), and the filtering mechanism (see the ApplyChanges property).


TcxGridTableView.GroupedColumnCount

TcxGridTableView          See Also

Returns the number of group columns within the table view.

property GroupedColumnCount: Integer;

Description

The GroupedColumnCount property returns the number of grouped columns within a view.  A user can access all group columns within a table view via the GroupedColumns property.

To group a table view by a specific column values programmatically set the Column.GroupIndex to any value, greater than –1, the higher the index the deeper the grouping level.  To group by a column at run time drag and drop it into the Group panel.

ReadOnly Property


TcxGridTableView.GroupedColumns

TcxGridTableView          See Also

Indexed access to the group columns of the table view.

property GroupedColumns[Index: Integer]: TcxGridColumn;

Description

Use the GroupedColumns property to gain access to the collection of the group items within the table view.

To group a table view by a specific column values programmatically set the Column.GroupIndex to any value, greater than –1, the higher the index the deeper the grouping level.  To group by a column at run time drag and drop it into the Group panel.

ReadOnly Property


TcxGridTableView.NewItemRow

TcxGridTableView          See Also

Specifies new item row options.

property NewItemRow: TcxGridNewItemRowOptions;

Description

The NewItemRow property represents settings that allow one to specify the new item row’s visibility (see the Visible property), its description (see the InfoText property), and the width and color of the separator that divides the new item row from data rows (see SeparatorWidth and SeparatorColor properties).


TcxGridTableView.OptionsBehavior

TcxGridTableView

Settings that determine how table views respond to user actions such as key presses.

property OptionsBehavior: TcxGridTableOptionsBehavior;

Description

Use the OptionsBehavior property to access the settings that determine how the grid view respond to user actions such as key presses.  This property determines whether cell editors are always active, whether the focus can be moved using the Tab and Enter keys, and other behaviors related to end-user interaction.


TcxGridTableView.OptionsCustomize

TcxGridTableView

Settings that determine the column manipulations that end-users can perform at run-time.

property OptionsCustomize: TcxGridTableOptionsCustomize;

Description

Use the OptionsCustomize property to determine the features that can be activated via runtime column manipulations within the table view.

These features include filtering, grouping, sorting, columns resizing and moving.  Some of them are mutually dependent (for instance, if the ColumnMoving property value is False, then the grouping feature is also disabled).

Note: These options can be overridden via code, for instance, if column grouping or moving is disabled, then columns still can be grouped programmatically by setting the Column.GroupIndex to a value greater than -1.


TcxGridTableView.OptionsData

TcxGridTableView

Settings that determine the data features of a table view.

property OptionsData: TcxGridTableOptionsData;

Description

Use the OptionsData to determine which actions can be performed upon the data set that provides records for the table view.

These actions include inserting, appending, editing and deleting records.  The data options also indicate whether the confirmation is asked before record deletion and whether empty records can be posted into a data set.


TcxGridTableView.OptionsSelection

TcxGridTableView

Settings regarding selections within a table view.

property OptionsSelection: TcxGridTableOptionsSelection;

Description

Use the OptionsSelection property to determine the selection options for a table view.

These options indicate whether the end user can select individual cells or whole rows, whether the focus rectangle is displayed around the focused row, whether the multiple rows can be select at a time, etc.


TcxGridTableView.OptionsView

TcxGridTableView

Settings determining the table views appearance.

property OptionsView: TcxGridTableOptionsView;

Description

Use the TcxGridTableOptionsView property to specify the table views appearance.

These options specify the visibility of editor buttons, footer, group footers and column headers, whether grid lines are drawn and in which color, the color and width of row separators, etc.  Sometimes view options affect the views behavior.  For instance, if the GroupByBox option is disabled, then runtime column grouping is disabled for the view.


TcxGridTableView.Preview

TcxGridTableView          See Also

Settings required for implementing preview within the table view.

property Preview: TcxGridPreview;

Description

Use the Preview property to access settings required for implementing the preview section into a table view.  These settings include:

1.	the Preview.Visible property which determines whether to display the preview section;

2.	the Preview.Column property which defines the grid column used to display the preview;

3.	the Preview.LeftIndent and Preview.RightIndent properties determining the position of the preview text;

4.	the Preview.Place property used to determine the preview sections position within a view;

5.	the Preview.AutoHeight property determining whether the preview sections height is automatically sized based on the content;

6.	the Preview.MaxLineCount property specifying the maximum number of text lines displayed within the preview.

Another way to specify the column for previewing is to set the appropriate column’s IsPreview attribute to True.


TcxGridTableView.Styles

TcxGridTableView          See Also

Specifies the set of styles defining the appearance of the table views elements.

property Styles: TcxGridTableViewStyles;

Description

Use the Styles property to access styles that define the appearance of the table views elements.

This set expands as the Styles property is redefined by TcxCustomGridView descendants.  In the base class the Styles set includes a style defining the appearance of the current view background.  The table view adds styles for the cell contents, selection bar, group, footer and preview sections, column headers, row indicator and etc.


TcxGridTableView.ViewData

TcxGridTableView          See Also

ViewData provides a bridge between the data controller and the table view.

property ViewData: TcxGridViewData;

Description

Use the ViewData property to access the rows currently displayed within a view.

This property refers to an instance of the TcxGridViewData class.  The collection of records provided by the TcxGridViewData class is supported by the Rows property.  Every row represents an object of the TcxCustomGridRow class allowing you to access different attributes relating to a row (an array of values corresponding to record fields, level of a record and others).

A ViewData object represents only records displayed within a view (i.e. it does not include those hidden within collapsed records).

ReadOnly Property


TcxGridTableView.VisibleColumnCount

TcxGridTableView          See Also

Returns the number of column visible within the table view.

property VisibleColumnCount: Integer;

Description

Use the VisibleColumnCount to obtain the number of columns currently visible within the table view.

The column visibility is determined via several properties: Column.GroupIndex and Column.VisibleIndex.  An item is not visible within the current view (but it persists within the Columns collection) if its Column.VisibleIndex property value is –1 or the Column.GroupIndex property value is greater than

–1.  The items visibility is also determined by the Column.Visible property value.

ReadOnly Property


TcxGridTableView.VisibleColumns

TcxGridTableView          See Also

Indexed access to the currently visible items within the table view.

property VisibleColumns[Index: Integer]: TcxGridColumn;

Description

Use the VisibleColumns property for indexed access to the currently visible columns within a table view.

A columns visibility is determined by the properties Column.GroupIndex and Column.VisibleIndex.  An item is not visible within the current view (but persists within the Columns collection) if the Column.VisibleIndex property value is –1 or the Column.GroupIndex property value is greater than –1.  An items visibility can also be set via the Column.Visible property value.

ReadOnly Property


TcxGridTableView.CreateColumn

TcxGridTableView          See Also

Creates a new column and adds it to the Columns collection of the table view.

function CreateColumn: TcxGridColumn;

Description

Use the CreateColumn method to create a column and add it to the Columns collection of the table view.

You can specify different column settings after a column is created and added to the collection.  These settings include the sort order, position among grouped columns, data binding, the column’s behavior, editors for the columns cells, styles for columns elements, etc.


TcxGridTableView.OnColumnHeaderClick

TcxGridTableView          See Also

Occurs on clicking a column header.

type

  TcxGridColumnEvent = procedure(Sender: TcxGridTableView; AColumn: TcxGridColumn) of object;

property OnColumnHeaderClick: TcxGridColumnEvent;

Description

The OnColumnHeaderClick event is fired on clicking a column header within the current view.  The column and the view are passed as the Sender and AColumn parameters respectively.

Column headers are displayed if the view’s OptionsView.Header property is set to True.

Clicking a column header activates sorting data by this column.  However, you can disable the user’s ability to sort data in this manner via the view’s OptionsCustomize.ColumnSorting and column’s Options.Sorting properties.  In this case, the OnColumnHeaderClick event is still fired, but sorting is not applied.


TcxGridTableView.OnColumnPosChanged

TcxGridTableView          See Also

Occurs when an end-user changes the visibility or position of a column within the current view.

type

  TcxGridColumnEvent = procedure(Sender: TcxGridTableView; AColumn: TcxGridColumn) of object;

property OnColumnPosChanged: TcxGridColumnEvent;

Description

The OnColumnPosChanges event is fired when an end-user moves a column or changes its visibility within the current view (for instance, by using the Quick Column Customization or dragging the column to the Customization Form).  The Sender parameter specifies the view in which a column’s position or visibility has been changed.  The AColumn parameter identifies the column being moved or shown/hidden.


TcxGridTableView.OnColumnSizeChanged

TcxGridTableView          See Also

Occurs when a user changes the size of a column.

type

  TcxGridColumnEvent = procedure(Sender: TcxGridTableView; AColumn: TcxGridColumn) of object;

property OnColumnSizeChanged: TcxGridColumnEvent;

Description

Write an OnColumnSizeChanged event handler to perform specific actions when a user changes the height (for a banded column) or the width of a specific column.  The Sender parameter specifies the view where a user changes the column’s dimensions.  The AColumn parameter identifies the column whose height (for a banded column) or width changes.


TcxGridTableView.OnCustomDrawColumnHeader

TcxGridTableView          See Also

Occurs when a cell within a table column header needs to be painted.

type

  TcxGridColumnCustomDrawHeaderEvent = procedure(Sender: TcxGridTableView; ACanvas: TcxCanvas; AViewInfo: TcxGridColumnHeaderViewInfo; var ADone: Boolean) of object;

property OnCustomDrawColumnHeader: TcxGridColumnCustomDrawHeaderEvent;

Description

The OnCustomDrawColumnHeader occurs every time a column header needs to be painted. As with other custom draw events it provides a canvas for the grid control (ACanvas parameter), view info to get the bounding rectangle of the painted element (AViewInfo parameter and its Bounds property). Sender is usually the element that caused the repaint. The ADone parameter is initially False you should set it to True to tell the grid that you have chosen to custom draw this item.


TcxGridTableView.OnCustomDrawFooterCell

TcxGridTableView          See Also

Occurs when a footer cell within a table view needs to be painted.

type

  TcxGridColumnCustomDrawHeaderEvent = procedure(Sender: TcxGridTableView; ACanvas: TcxCanvas; AViewInfo: TcxGridColumnHeaderViewInfo; var ADone: Boolean) of object;

property OnCustomDrawFooterCell: TcxGridColumnCustomDrawHeaderEvent;

Description

The OnCustomDrawFooterCell occurs every time a footer cell needs to be painted. As with other custom draw events it provides a canvas for the grid control (ACanvas parameter), view info to get the bounding rectangle of the painted element (AViewInfo parameter and its Bounds property). Sender is usually the element that caused the repaint. The ADone parameter is initially False you should set it to True to tell the grid that you have chosen to custom draw this item.


TcxGridTableView.OnCustomDrawGroupCell

TcxGridTableView          See Also

Enables you to paint grouped rows in a custom manner.

type

  TcxGridTableCellCustomDrawEvent = procedure(Sender: TcxCustomGridTableView; ACanvas: TcxCanvas; AViewInfo: TcxGridTableCellViewInfo; var ADone: Boolean) of object;

property OnCustomDrawGroupCell: TcxGridTableCellCustomDrawEvent;

Description

Handle the OnCustomDrawGroupCell event to take control of the painting of grouped rows.  This event fires just before a grouping row is painted.  The ACanvas and AViewInfo event parameters specify the canvas to draw upon and the object containing the rows view information, respectively.  Please refer to the TcxGridTableCellViewInfo class description for details on this view information object.

The ADone parameter specifies whether default painting should be performed after executing the event handler.  Set it to True to prohibit default painting for the processed row.  Leave the parameter set to False to paint the group row using the regular painting process.

The Sender parameter specifies the view whose row is being painted.


TcxGridTableView.OnCustomDrawGroupSummaryCell

TcxGridBandedTableView          See Also

Fires each time a group summary is about to be drawn in the currently processed view.

type

  TcxGridGroupSummaryCellCustomDrawEvent = procedure(Sender: TObject; ACanvas: TcxCanvas; ARow: TcxGridGroupRow; AColumn: TcxGridColumn; ASummaryItem: TcxDataSummaryItem; AViewInfo: TcxCustomGridViewCellViewInfo; var ADone: Boolean) of object;

property OnCustomDrawGroupSummaryCell: TcxGridGroupSummaryCellCustomDrawEvent;

Description

Implement the OnCustomDrawGroupSummaryCell event handler to custom paint the group summary.

The Sender parameter specifies the currently processed view;

The ACanvas parameter specifies the drawing surface;

The ARow parameter specifies the group row that the group summary is currently drawn in;

The AColumn parameter specifies the column that the group summary is currently drawn in;

The ASummaryItem parameter specifies the currently drawn group summary;

The AViewInfo parameter provides details for rendering the group summary;

The ADone parameter specifies whether default painting is required. Set ADone to True, to prevent default painting.


TcxGridTableView.OnCustomDrawIndicatorCell

TcxGridBandedTableView          See Also

Occurs when painting an indicator cell within a table view.

type

  TcxGridIndicatorCellCustomDrawEvent = procedure(Sender: TcxGridTableView; ACanvas: TcxCanvas; AViewInfo: TcxCustomGridIndicatorItemViewInfo; var ADone: Boolean) of object;

property OnCustomDrawIndicatorCell: TcxGridIndicatorCellCustomDrawEvent;

Description

The OnCustomDrawIndicatorCell event occurs every time an indicator cell needs to be painted.  Similar to other custom draw events, it provides a canvas for the grid control via the ACanvas parameter and the attributes of the indicator cell via the AViewInfo parameter.  The Sender parameter usually represents the element initiating the repaint procedure.  The ADone parameter is initially False.  You should set it to True to notify the grid control that custom drawing has been applied to this item.

The following example shows how to imitate a fixed column of the table view using the OnCustomDrawIndicatorCell event

procedure TViewTableSimpleDemoMainForm.cxgFilmsDBTableViewCustomDrawIndicatorCell(

  Sender: TcxGridTableView; ACanvas: TcxCanvas;

  AViewInfo: TcxCustomGridIndicatorItemViewInfo; var ADone: Boolean);

var

  FValue: string;

  FBounds: TRect;

begin

    FBounds := AViewInfo.Bounds;

  if (AViewInfo is TcxGridIndicatorHeaderItemViewInfo) then

  begin

    ACanvas.Brush.Color := $00C56A31;

    ACanvas.FillRect(FBounds);

    ACanvas.DrawComplexFrame(FBounds, clBlack, clBlack, cxBordersAll, 1);

    ACanvas.Font.Color := clWhite;

    ACanvas.Font.Style := [fsBold];

    ACanvas.Brush.Style := bsClear;

    InflateRect(FBounds, -3, 0); //Platform specific. May not work on Linux.

    ACanvas.DrawText('Year', FBounds, cxAlignLeft or cxAlignVCenter);

    ADone := True;

  end

  else if (AViewInfo is TcxGridIndicatorRowItemViewInfo) then

  begin

    ACanvas.FillRect(FBounds);

    ACanvas.DrawComplexFrame(FBounds, clBlack, clBlack, [bBottom, bLeft, bRight], 1);

    FValue := TcxGridIndicatorRowItemViewInfo(AViewInfo).GridRecord.Values[cxgFilmsDBTableViewYEAR.Index];

    InflateRect(FBounds, -3, -2); //Platform specific. May not work on Linux.

    ACanvas.Font.Color := clBlack;

    ACanvas.Brush.Style := bsClear;

    ACanvas.DrawText(FValue, FBounds, cxAlignRight or cxAlignTop);

    ADone := True;

  end;

end;

The result is shown on the following image:


TcxGridTableView.OnLeftPosChanged

TcxGridTableView          See Also

Occurs when a view is scrolled horizontally.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnLeftPosChanged: TNotifyEvent;

Description

Use the OnLeftPosChanged event handler to process horizontal scrolling of a view.  This event occurs however a view is scrolled, either by keyboard navigation or by moving the view’s horizontal scroll bar.


TcxGridTableViewStyles
TcxGridTableViewStyles Object

Hierarchy          Properties          Methods          Events          See Also

Represents the set of styles for managing the appearance of a table view.

Unit

cxGridTableView

TcxGridTableViewStyles = class(TcxCustomGridTableViewStyles);

Description

The TcxGridTableViewStyles property defines a set of properties and events that allow you to specify the appearance of all table view elements.  By handling the styles events it is possible to unique styles to different rows.


TcxGridTableViewStyles Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomStyles

     |

TcxStyles

     |

TcxCustomGridStyles

     |

TcxCustomGridViewStyles

     |

TcxCustomGridTableViewStyles

     |


Properties for TcxGridTableViewStyles
TcxGridTableViewStyles Properties

TcxGridTableViewStyles          Legend

In TcxGridTableViewStyles

FilterRowInfoText

Footer

GridView

Group

GroupByBox

GroupFooterSortedSummary

GroupSortedSummary

GroupSummary

Header

Indicator

NewItemRowInfoText

Preview

Derived from TcxCustomGridTableViewStyles

Content

ContentEven

ContentOdd

FilterBox

GridView

Inactive

IncSearch

Selection

Derived from TcxCustomGridViewStyles

Background

Derived from TcxCustomGridStyles

GridView

Derived from TcxCustomStyles

StyleSheet


Methods for TcxGridTableViewStyles
TcxGridTableViewStyles Methods

TcxGridTableViewStyles          Legend

In TcxGridTableViewStyles

GetContentParams

GetFooterParams

GetGroupParams

GetGroupSummaryParams

GetHeaderParams

GetPreviewParams

GetRecordContentParams

Derived from TcxCustomStyles

Assign

Create

Destroy


Events for TcxGridTableViewStyles
TcxGridTableViewStyles Events

TcxGridTableViewStyles          Legend

In TcxGridTableViewStyles

OnGetFooterStyle

OnGetFooterStyleEx

OnGetFooterSummaryStyle

OnGetGroupStyle

OnGetGroupSummaryStyle

OnGetHeaderStyle

OnGetPreviewStyle

Derived from TcxCustomGridTableViewStyles

OnGetContentStyle


TcxGridTableViewStyles.FilterRowInfoText

TcxGridTableViewStyles          See Also

Specifies the filter row’s style.

property FilterRowInfoText: TcxStyle;

Description

The specified style is only applied, if the filter row is not focused and no filter is set.

Use the FilterRowInfoText property to apply the required style to the filter row.


TcxGridTableViewStyles.Footer

TcxGridTableViewStyles          See Also

Specifies the style for the table views footer.

property Footer: TcxStyle;

Description

The Footer property allows you to define the style (font, background color) for the table view footer.  It is possible to redefine the style for a specific footer by handling the OnGetFooterStyle event.

The following image demonstrates a grid control with the footer panel painted in the pale golden color:


TcxGridTableViewStyles.GridView

TcxGridTableViewStyles

Specifies the table view the style is applied to.

property GridView: TcxGridTableView;

Description

Use the GridView property to get the table view for which the current style is applied.

ReadOnly Property


TcxGridTableViewStyles.Group

TcxGridTableViewStyles          See Also

Specifies the style for the table views group rows.

property Group: TcxStyle;

Description

The Group property allows you to define the style (font, background color) for the table view group.

It is possible to change group styles on the fly by handling the OnGetGroupStyle event.

The next image demonstrates a grid control with the group region painted in the wheat color ($00B3DEF5):


TcxGridTableViewStyles.GroupByBox

TcxGridTableViewStyles          See Also

Specifies the style for the table views group-by box.

property GroupByBox: TcxStyle;

Description

The GroupByBox property allows you to define the style (font, background color) for the table view group-by box.

The following image displays a grid control with the group panel painted yellow:


TcxGridTableViewStyles.GroupFooterSortedSummary

TcxGridTableViewStyles          See Also

Specifies the foreground color and font settings for group summaries displayed in group footer panels and used to determine the sort order of group rows.

property GroupFooterSortedSummary: TcxStyle;

Description

The following image displays a grid control with these group summaries painted in bold type.

To specify style settings for group summaries displayed in group rows and used to determine the sort order of these group rows, use the GroupSortedSummary property.

To dynamically apply custom styles to group summaries displayed in group footer panels and group rows, handle the OnGetFooterSummaryStyle and OnGetGroupSummaryStyle events, respectively.


TcxGridTableViewStyles.GroupSortedSummary

TcxGridTableViewStyles          See Also

Specifies the foreground color and font settings for group summaries displayed in group rows and used to determine the sort order of these group rows.

property GroupSortedSummary: TcxStyle;

Description

The following image displays a grid control with these group summaries painted blue.

To specify style settings for group summaries displayed in group footer panels and used to determine the sort order of these group rows, use the GroupFooterSortedSummary property.

To dynamically apply custom styles to group summaries displayed in group footer panels and group rows, handle the OnGetFooterSummaryStyle and OnGetGroupSummaryStyle events.


TcxGridTableViewStyles.GroupSummary

TcxGridTableViewStyles          See Also

Specifies group summary style.

property GroupSummary: TcxStyle;

Description

Use the GroupSummary property to apply the appropriate style to group summaries within a table view.

To dynamically apply custom styles to group summaries, handle the OnGetGroupSummaryStyle event.


TcxGridTableViewStyles.Header

TcxGridTableViewStyles          See Also

Specifies the table views header’s style.

property Header: TcxStyle;

Description

The Header property allows you to define the style (font, background color) for the table view header.

It is possible to change header styles on the fly by handling the OnGetHeaderStyle event.

The style of the following column headers are redefined so that they are painted in white against the blue background:


TcxGridTableViewStyles.Indicator

TcxGridTableViewStyles          See Also

Specifies the style for the table views row indicator.

property Indicator: TcxStyle;

Description

The Indicator property allows you to define the style (font, background color) for the table view row indicator.

In the following image the indicator is painted in coral ($00507FFF).


TcxGridTableViewStyles.NewItemRowInfoText

TcxGridTableViewStyles          See Also

Specifies the style for the text displayed in the background of a new item row.

property NewItemRowInfoText: TcxStyle;

Description

The NewItemRowInfoText property specifies the style (font attributes and text color) used to draw text in the background of a new item row.  The text is specified by the view’s OptionsView.NewItemRowInfoText property.  It is displayed if the new item row is not focused.

To specify the style for the info text:

1.	Create a TcxStyle object using a TcxStyleRepository component, for instance.

2.	Customize the new style depending on your needs.  (Note that you are able to customize the style later at any time you need)

3.	Assign it to the NewItemRowInfoText property

The following example shows how to create and customize a style for the info text of a new item row in a tvCustomers view.  When creating the style, the form (Self) is specified as its owner.  Thus, the style is automatically destroyed when destroying the form.

//Delphi

FInfoStyle: TcxStyle;

//...

procedure TForm1.FormCreate(Sender: TObject);

begin

  FInfoStyle := TcxStyle.Create(Self);

  with FInfoStyle do

  begin

    TextColor := clPurple;

    Font.Name := 'Courier New';

  end;

  tvCustomers.Styles.NewItemRowInfoText := FInfoStyle;

end;

//C++ Builder

TcxStyle * FInfoStyle;

//...

void __fastcall TForm1::FormCreate(TObject *Sender) {

  FInfoStyle = new TcxStyle(this);

  FInfoStyle->TextColor = clPurple;

  FInfoStyle->Font->Name = "Courier New";

  tvCustomers->Styles->NewItemRowInfoText = FInfoStyle;

}

The image below shows the info text (‘Click here to add a new row’) drawn using the specified style:


TcxGridTableViewStyles.Preview

TcxGridTableViewStyles          See Also

Specifies the style for the rows preview section.

property Preview: TcxStyle;

Description

The Preview property allows you to define the style (font, background color) of the current for the row preview section.

It is possible to change the preview style on the fly by handling the OnGetPreviewStyle event.

The next image displays a grid control with the preview rows painted in bisque ($00C4E4FF):


TcxGridTableViewStyles.GetContentParams

TcxGridTableViewStyles

Gets the TcxViewParams record containing information on the data row’s style attributes.

procedure GetContentParams(ARecord: TcxCustomGridRecord; AItem: TcxCustomGridTableItem; out AParams: TcxViewParams); override;

Description

The ARecord parameter specifies a record that the currently processed data row corresponds to;

The AItem parameter specifies a row to be processed;

 The AParams parameter specifies style attributes that the method results in.


TcxGridTableViewStyles.GetFooterCellParams

TcxGridTableViewStyles

Gets the TcxViewParams record containing information on the footer cell’s style attributes.

procedure GetFooterCellParams(ARow: TcxCustomGridRow; AColumn: TcxGridColumn; AFooterGroupLevel: Integer; ASummaryItem: TcxDataSummaryItem; out AParams: TcxViewParams); virtual;

Description

The ARow and AColumn parameters specify the row and column that the currently processed footer cell resides in.

The AFooterGroupLevel parameter corresponds to the data group, for which the footer region is drawn (it's equal to the group column’s GroupIndex property’s value).  For view footers, the AFooterGroupLevel value is –1.

The ASummaryItem parameter provides access to the summary object displayed by the footer cell.

The AParams parameter specifies style attributes that the method results in.


TcxGridTableViewStyles.GetFooterParams

TcxGridTableViewStyles

Gets the TcxViewParams record containing information on the footer’s style attributes.

procedure GetFooterParams(ARow: TcxCustomGridRow; AColumn: TcxGridColumn; AFooterGroupLevel: Integer; ASummaryItem: TcxDataSummaryItem; out AParams: TcxViewParams); virtual;

Description

The ARow and AColumn parameters specify the row and column that the currently processed footer resides in.

The AFooterGroupLevel parameter corresponds to the data group, for which the footer region is drawn (it's equal to the group column’s GroupIndex property’s value).  For view footers, the AFooterGroupLevel value is –1.

The ASummaryItem parameter provides access to the summary object displayed by the AColumn.

The AParams parameter specifies style attributes that the method results in.


TcxGridTableViewStyles.GetGroupParams

TcxGridTableViewStyles          See Also

Gets the TcxViewParams record containing information on the group row’s style attributes.

procedure GetGroupParams(ARecord: TcxCustomGridRecord; ALevel: Integer; out AParams: TcxViewParams); virtual;

Description

The ARecord parameter specifies the record that the currently processed group row corresponds to.

The ALevel parameter specifies the hierarchical depth of the currently processed group row.

The AParams parameter specifies style attributes that the method results in.


TcxGridTableViewStyles.GetGroupSummaryParams

TcxGridTableViewStyles          See Also

Gets the TcxViewParams record containing information on the group summary’s style attributes.

procedure GetGroupSummaryParams(ARow: TcxGridGroupRow; ASummaryItem: TcxDataSummaryItem; out AParams: TcxViewParams); virtual;

Description

The ARow parameter specifies the row that the currently processed group summary corresponds to.

The ASummaryItem parameter specifies a summary.

The AParams parameter specifies style attributes that the method results in.


TcxGridTableViewStyles.GetHeaderParams

TcxGridTableViewStyles          See Also

Gets the TcxViewParams record containing information on style attributes of the column header.

procedure GetHeaderParams(AItem: TcxGridColumn; out AParams: TcxViewParams); virtual;

Description

The AItem parameter specifies the column.

The AParams parameter specifies style attributes that the method results in.


TcxGridTableViewStyles.GetPreviewParams

TcxGridTableViewStyles          See Also

Gets the TcxViewParams record that contains information on style attributes of preview section rows.

procedure GetPreviewParams(ARecord: TcxCustomGridRecord; AItem: TcxCustomGridTableItem; out AParams: TcxViewParams); virtual;

Description

The ARecord parameter specifies the record that the currently processed row corresponds to.

The AItem parameter specifies the row to be processed.

The AParams parameter specifies style attributes that the method results in.


TcxGridTableViewStyles.GetRecordContentParams

TcxGridTableViewStyles

Gets the TcxViewParams record that contains information on style attributes of the row value.

procedure GetRecordContentParams(ARecord: TcxCustomGridRecord; AItem: TcxCustomGridTableItem; out AParams: TcxViewParams); override;

Description

The ARecord parameter specifies the record that the currently processed row corresponds to.

The AItem parameter specifies the processed row.

The AParams parameter specifies style attributes that the method results in.


TcxGridTableViewStyles.OnGetFooterStyle

TcxGridTableViewStyles          See Also

Occurs when it is necessary to paint View footer and group footer panels.

type

  TcxGridGetCellStyleEvent = procedure(Sender: TcxCustomGridTableView; ARecord: TcxCustomGridRecord; AItem: TcxCustomGridTableItem; out AStyle: TcxStyle) of object;

property OnGetFooterStyle: TcxGridGetCellStyleEvent;

Description

You can handle the OnGetFooterStyle event to change the styles of group and table footers on the fly.

Group footers allow you to display group summaries when data is grouped by column(s).  The view footer resides at the bottom of a grid control and is used to display footer summaries.  To show group and view footers, use the view’s OptionsView.GroupFooters and OptionsView.Footer properties.

When handling the OnGetFooterStyle event, you can distinguish between the view footer and group footers by comparing the ARecord parameter value with nil.  For view footers, it will always contain nil.  For group footers, ARecord will specify the last data record within the corresponding group.

A summary result corresponding to a particular column is drawn within a footer cell (a bordered rectangle region in the footer panel).  If a footer cell is being painted, the AItem parameter specifies a non-nil value.  In this case, it refers to the column containing the footer cell.  If AItem contains nil, the entire footer panel is being painted.

The Sender parameter is the view containing the item.

The following code handles the OnGetFooterStyle event.  Different styles are specified when the AItem and ARecord parameters contain nil and non-nil values.

// Delphi

procedure TForm1.tvOrdersStylesGetFooterStyle(

  Sender: TcxCustomGridTableView; ARecord: TcxCustomGridRecord;

  AItem: TcxCustomGridTableItem; out AStyle: TcxStyle);

begin

  if Assigned(ARecord) then

    if Assigned(AItem) then

      AStyle := cxStyle1

    else

      AStyle := cxStyle2

  else

    if Assigned(AItem) then

      AStyle :=  cxStyle3

    else

      AStyle := cxStyle4

end;

// C++ Builder

void TForm1::tvOrdersStylesGetFooterStyle(

  TcxCustomGridTableView *Sender, TcxCustomGridRecord *ARecord,

  TcxCustomGridTableItem *AItem, TcxStyle &AStyle)

{

  if (ARecord != NULL) {

    if (AItem != NULL) AStyle = cxStyle1;

    else AStyle = cxStyle2;

  }

  else

    if (AItem != NULL) AStyle =  cxStyle3;

    else AStyle = cxStyle4;

}

Styles used in this example were created via a style repository of the TcxStyleRepository class.  They specify colors as follows:

cxStyle1:

cxStyle2:

cxStyle3:

cxStyle4:

The result of this code is shown below:

You can use the OnGetFooterStyleEx event which represents the extended version of the OnGetFooterStyle event and should be handled whenever you need additional style customizations for the grouped items in the view.

Note:	The column’s Styles.OnGetFooterStyle and Styles.OnGetFooterStyleEx events override the default style for the column footer which is stored in the column’s Styles.Footer property. The latter in turn overrides any style which is returned from the view’s OnGetFooterStyle and OnGetFooterStyleEx events which in turn override the style stored in the view’s Styles.Footer property.


TcxGridTableViewStyles.OnGetFooterStyleEx

TcxGridTableViewStyles          See Also

Occurs when it is necessary to paint View footer and group footer panels.

type

  TcxGridGetFooterStyleExEvent = procedure(Sender: TcxGridTableView; ARow: TcxCustomGridRow; AColumn: TcxGridColumn; AFooterGroupLevel: Integer; var AStyle: TcxStyle) of object;

property OnGetFooterStyleEx: TcxGridGetFooterStyleExEvent;

Description

The OnGetFooterStyleEx event occurs every time the group or view footer is redrawn and is fired after the OnGetFooterStyle event.  The OnGetFooterStyleEx event is the extended version of the OnGetFooterStyle event and should be handled whenever you need to perform additional style customizations for the grouped items in the view.

By default, the AStyle parameter at the point the event is fired represents the style which was returned by the procedure that handles the OnGetFooterStyle event (if any).  To specify the style for a footer region you can create a TcxStyle object instance, adjust its properties as necessary and return it via the AStyle parameter.

The Sender, ARow and AColumn parameters identify the view, row and column, respectively for which the footer region is drawn.  When handling the OnGetFooterStyleEx event, you can distinguish between the view footer and group footers by comparing the ARow parameter value with nil.  For view footers, it will always return nil.  For group footers, the ARow parameter will specify the last data record/row within the corresponding group.

The AFooterGroupLevel parameter corresponds to the data group, for which the footer region is drawn (it's equal to the group column’s GroupIndex property’s value).  For view footers, the AFooterGroupLevel value is –1.

To define the default styles for footer regions use the view’s Styles.Footer,

Note:	The column’s Styles.OnGetFooterStyle and Styles.OnGetFooterStyleEx events override the default style for the column footer which is stored in the column’s Styles.Footer property. The latter in turn overrides any style which is returned from the view’s OnGetFooterStyleEx and OnGetFooterStyle events which in turn override the style stored in the view’s Styles.Footer property.


TcxGridTableViewStyles.OnGetFooterSummaryStyle

TcxGridTableViewStyles          See Also

Fires each time a footer summary or a group summary displayed in a group footer panel is about to be drawn.

type

  TcxGridGetFooterSummaryStyleEvent = procedure(AView: TcxGridTableView; ARow: TcxGridGroupRow; AColumn: TcxGridColumn; AFooterGroupLevel: Integer; ASummaryItem: TcxDataSummaryItem; var AStyle: TcxStyle) of object;

property OnGetFooterSummaryStyle: TcxGridGetFooterSummaryStyleEvent;

Description

The AView parameter specifies the Table View that displays the currently processed summary.

The ARow parameter specifies the row that the group summary resides in.  For view footers, the ARow value is nil.

The AColumn parameter specifies the column that the summary is linked to.

The ASummaryItem parameter represents the summary object.  To determine whether summary values are used to sort group rows, use the ASummaryItem.Sorted property.

The AFooterGroupLevel parameter corresponds to the data group, for which the footer region is drawn (it's equal to the group column’s GroupIndex property’s value).  For view footers, the AFooterGroupLevel value is –1.

The AStyle parameter specifies style attributes to be applied to the summary.

Note:	To customize the style of summaries displayed for a particular column, handle the column’s OnGetFooterSummaryStyle event.

The OnGetFooterSummaryStyle event is fired after the OnGetFooterStyle and OnGetFooterStyleEx events.


TcxGridTableViewStyles.OnGetGroupStyle

TcxGridTableViewStyles          See Also

Occurs when the table views group row is painted.

type

  TcxGridGetGroupStyleEvent = procedure(Sender: TcxGridTableView; ARecord: TcxCustomGridRecord; ALevel: Integer; out AStyle: TcxStyle) of object;

property OnGetGroupStyle: TcxGridGetGroupStyleEvent;

Description

You can handle the OnGetGroupStyle event to redefine style for the table view group rows.  This event occurs every time when it is necessary to redraw a group row defined by the ARecord parameter. The ALevel parameter specifies the current nesting level.

The Sender parameter determines the table view containing the row.

The following simple code colors groups based on their level.  cxStyleLevel0 and cxStyleLevel1 represent TcxStyle objects created using the style repository.  The Color property of the styles is set to $007A96E9 and $00CDEBFF respectively:

// Delphi

procedure TForm1.tvCustomersStylesGetGroupStyle(

  Sender: TcxGridTableView; ARecord: TcxCustomGridRecord; ALevel: Integer;

  out AStyle: TcxStyle);

begin

  if ALevel = 0 then

    AStyle := cxStyleLevel0

  else

    AStyle := cxStyleLevel1;

end;

// C++ Builder

void TForm1::tvCustomersStylesGetGroupStyle(

  TcxGridTableView *Sender, TcxCustomGridRecord *ARecord, int ALevel,

  TcxStyle &AStyle)

{

  if (ALevel = = 0) AStyle = cxStyleLevel0;

  else AStyle = cxStyleLevel1;

}

The result of this customization is displayed below:


TcxGridTableViewStyles.OnGetGroupSummaryStyle

TcxGridTableViewStyles          See Also

Fires each time a group summary displayed in a group row is about to be drawn.

type

  TcxGridGetGroupSummaryStyleEvent = procedure(Sender: TcxGridTableView; ARow: TcxGridGroupRow; AColumn: TcxGridColumn; ASummaryItem: TcxDataSummaryItem; var AStyle: TcxStyle) of object;

property OnGetGroupSummaryStyle: TcxGridGetGroupSummaryStyleEvent;

Description

The Sender parameter specifies the Table View that contains the currently processed group summary.

The ARow parameter specifies the row that the group summary resides in.

The AColumn parameter specifies the column that the group summary is linked to.  For a group row’s text that isn’t associated with a group summary (for instance, enclosing brackets ‘( )’), the AColumn value is nil.

The ASummaryItem parameter represents the summary.  For a group row’s text that isn’t associated with a group summary (for instance, enclosing brackets ‘( )’), the ASummaryItem value is nil.

The AStyle parameter specifies style attributes to be applied to the group summary.

To customize the style applied to group summaries displayed in group footer panels, handle the OnGetFooterSummaryStyle event.


TcxGridTableViewStyles.OnGetHeaderStyle

TcxGridTableViewStyles          See Also

Occurs when it is necessary to paint the table views header.

type

  TcxGridGetHeaderStyleEvent = procedure(Sender: TcxGridTableView; AColumn: TcxGridColumn; out AStyle: TcxStyle) of object;

property OnGetHeaderStyle: TcxGridGetHeaderStyleEvent;

Description

You can handle the OnGetHeaderStyle event to change the column header style on the fly.

The column is passed as the AColumn parameter.

The Sender parameter determines the table view containing the column.


TcxGridTableViewStyles.OnGetPreviewStyle

TcxGridTableViewStyles          See Also

Occurs when it is necessary to paint the table rows preview section.

type

  TcxGridGetCellStyleEvent = procedure(Sender: TcxCustomGridTableView; ARecord: TcxCustomGridRecord; AItem: TcxCustomGridTableItem; out AStyle: TcxStyle) of object;

property OnGetPreviewStyle: TcxGridGetCellStyleEvent;

Description

You can handle the OnGetPreivewStyle event to change table row preview styles on the fly.

This event occurs on every redraw of a row preview.

The table view record is passed in the ARecord parameter.

The column being previewed is specified by the AItem parameter.

The Sender parameter determines the view containing the item.


TcxGridTableViewStyleSheet
TcxGridTableViewStyleSheet Object

Hierarchy          Properties          Methods          See Also

Represents a stylesheet for banded table view.

Unit

cxGridTableView

TcxGridTableViewStyleSheet = class(TcxCustomStyleSheet);

Description

A StyleSheet contains a collection of styles that can be applied to a view, setting multiple styles in one step.  The TcxGridTableViewStyleSheet provides a stylesheet collection for the table view.


TcxGridTableViewStyleSheet Hierarchy
Hierarchy

TComponent

     |

TcxCustomStyleSheet

     |


Properties for TcxGridTableViewStyleSheet
TcxGridTableViewStyleSheet Properties

TcxGridTableViewStyleSheet          Legend

In TcxGridTableViewStyleSheet

Styles

Derived from TcxCustomStyleSheet

Caption

StyleRepository


Methods for TcxGridTableViewStyleSheet
TcxGridTableViewStyleSheet Methods

TcxGridTableViewStyleSheet          Legend

Derived from TcxCustomStyleSheet

 Create

 Destroy


TcxGridTableViewStyleSheet.Styles

TcxGridTableViewStyleSheet          See Also

Represents a set of styles managing the appearance of table view.

property Styles: TcxGridTableViewStyles;

Description

The Styles property defines a set of properties and events that allow you to specify the appearance of all table view parts.  By handling the styles events it is possible to override the property styles and define different styles for records on the fly.


TcxGridCardViewBackgroundBitmaps
TcxGridCardViewBackgroundBitmaps Object

Hierarchy          Properties          Methods

Provides background bitmaps for the visual elements of a card view.

Unit

cxGridCardView

TcxGridCardViewBackgroundBitmaps = class(TcxCustomGridTableBackgroundBitmaps)

Description

The TcxGridCardViewBackgroundBitmaps object can be accessed via the BackgroundBitmaps property of card views (TcxGridCardView and TcxGridDBCardView objects).  It provides properties that specify background bitmaps assigned to elements of the owning view.  These elements and their corresponding properties are:

•	The background of the view (the Background property);

•	Data cells (the Content property);

•	Row captions (the CaptionRow property),

•	Card borders (the CardBorder property),

•	Row Caption (the RowCaption property).

To locate these elements within the view, please refer to the Grid View Elements topic.

The TcxGridCardViewBackgroundBitmaps object in derived from the TcxCustomGridTableBackgroundBitmaps class.  It inherits the Background and Content properties that are common to all views.  The properties above are specific to card views.

You will have no need to create instances of the TcxGridCardViewBackgroundBitmaps class at runtime.  A view will create the object when initializing its Bitmaps property.


TcxGridCardViewBackgroundBitmaps Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |

TcxCustomGridBackgroundBitmaps

     |

TcxCustomGridTableBackgroundBitmaps

     |


Properties for TcxGridCardViewBackgroundBitmaps
TcxGridCardViewBackgroundBitmaps Properties

TcxGridCardViewBackgroundBitmaps          Legend

In TcxGridCardViewBackgroundBitmaps

CaptionRow

CardBorder

RowCaption

Derived from TcxCustomGridTableBackgroundBitmaps

Content

FilterBox

Derived from TcxCustomGridBackgroundBitmaps

Background

Values


Methods for TcxGridCardViewBackgroundBitmaps
TcxGridCardViewBackgroundBitmaps Methods

TcxGridCardViewBackgroundBitmaps          Legend

Derived from TcxCustomGridBackgroundBitmaps

 Assign


TcxGridCardViewBackgroundBitmaps.CaptionRow

TcxGridCardViewBackgroundBitmaps

Specifies the background bitmap for caption rows.

property CaptionRow: TBitmap;

Description

The CaptionRow property allows you to set the background bitmap for caption rows (with their Kind property set to rkCaption).  The image below displays an example of setting the CaptionRow property.


TcxGridCardViewBackgroundBitmaps.CardBorder

TcxGridCardViewBackgroundBitmaps

Specifies the background bitmap for card borders.

property CardBorder: TBitmap;

Description

Use the CardBorder property to assign a background bitmap to card borders.  Card borders are painted around each card and their width is set using the OptionsView.CardBorderWidth property of the view.  The image below shows an example of assigning a background image.

To locate the card border within a grid view, please refer to the Grid View Elements topic.


TcxGridCardViewBackgroundBitmaps.RowCaption

TcxGridCardViewBackgroundBitmaps

Specifies the background bitmap for row headers.

property RowCaption: TBitmap;

Description

Use the RowCaption property to specify the background bitmap for row headers within cards.  The image below shows an example.


TcxGridCardViewController
TcxGridCardViewController Object

Hierarchy          Properties          Methods

Represents a controller for a card view.

Unit

cxGridCardView

TcxGridCardViewController = class(TcxCustomGridTableController)

Description

The TcxGridCardViewController class represents a controller for card views.  Its functionality is accessible via the view’s Controller property.

A view controller provides methods and properties enabling you to:

-	control editing of a record cell

-	set focus to a specific card row and record

-	start/cancel an incremental search

-	access the collection of selected records

-	perform scrolling

-	navigate records and card rows

Most class members are inherited from the TcxCustomGridTableController class.

The TopCardIndex property declared in TcxGridCardViewController is a wrapper for the inherited TopRecordIndex property.  TopCardIndex and TopRecordIndex can be used interchangeably.


TcxGridCardViewController Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxGridViewHandler

     |

TcxCustomGridController

     |

TcxCustomGridTableController

     |


Properties for TcxGridCardViewController
TcxGridCardViewController Properties

TcxGridCardViewController          Legend

In TcxGridCardViewController

FocusedCard

FocusedRow

TopCardIndex

Derived from TcxCustomGridTableController

Customization

CustomizationForm

CustomizationFormBounds

EditingController

EditingItem

FocusedItem

FocusedItemIndex

FocusedRecord

FocusedRecordIndex

IncSearchingItem

IncSearchingText

IsEditing

IsIncSearching

SelectedRecordCount

SelectedRecords

TopRecordIndex

Derived from TcxGridViewHandler

Control

Controller

DataController

GridView

ViewData


Methods for TcxGridCardViewController
TcxGridCardViewController Methods

TcxGridCardViewController          Legend

In TcxGridCardViewController

 CanScrollFocusedCard

 FocusNextRowHorizontally

 FocusNextRowVertically

 ScrollFocusedCard

Derived from TcxCustomGridTableController

 CancelIncSearching

 ClearSelection

 CreateNewRecord

 DeleteSelection

 FindNextItem

 FindNextRecord

 FocusFirstAvailableItem

 FocusNextCell

 FocusNextItem

 FocusNextRecord

 FocusNextRecordWithSelection

 GoToFirst

 GoToLast

 GoToNext

 GoToPrev

 MakeFocusedItemVisible

 MakeFocusedRecordVisible

 MakeItemVisible

 MakeRecordVisible

Derived from TcxCustomGridController

 Scroll

Derived from TcxGridViewHandler

 BeginUpdate

 Create

 EndUpdate


TcxGridCardViewController.FocusedCard

TcxGridCardViewController

Represents the currently selected card in a card view.

property FocusedCard: TcxGridCard;

Description

Use the FocusedCard property to access the TcxGridCard instance that is associated with the currently selected card.


TcxGridCardViewController.FocusedRow

TcxGridCardViewController

Represents the currently selected row in a card.

property FocusedRow: TcxGridCardViewRow;

Description

Use the FocusedRow property to access the TcxGridCardViewRow instance that is associated with the currently focused row.


TcxGridCardViewController.TopCardIndex

TcxGridCardViewController          See Also

Specifies the index of a topmost visible card.

property TopCardIndex: Integer;

Description

You can use the TopCardIndex property to scroll the view contents.  TopCardIndex specifies the index of a card displayed at the top of the visible portion of the current view.

Records in a card view are represented as cards.  TopCardIndex is a wrapper for the inherited TopRecordIndex property.  You can use both properties interchangeably.  Please see the TopRecordIndex description for more details.


TcxGridCardViewController.CanScrollFocusedCard

TcxGridCardViewController          See Also

Determines whether the card rows in the currently focused card can be scrolled vertically in the specified direction.

function CanScrollFocusedCard(ADown: Boolean): Boolean;

Description

You can use the CanScrollFocusedCard function to determine whether card rows in the currently focused card can be scrolled vertically in the direction specified by the ADown parameter, which is True for down and False for up.


TcxGridCardViewController.FocusNextRowHorizontally

TcxGridCardViewController          See Also

Moves focus from the currently selected item (see the FocusedRow property) to the next item in a card (see the FocusedCard property) horizontally.

function FocusNextRowHorizontally(AGoForward, AGoOnCycle: Boolean): Boolean; virtual;

Description

The AGoForward parameter specifies whether navigation is forward or backward.  Set the AGoForward to True, to move focus forward.  Otherwise the previous item will be selected;

Set the AGoOnCycle the to True, to cyclically move focus in a card.


TcxGridCardViewController.FocusNextRowVertically

TcxGridCardViewController          See Also

Moves focus from the currently selected item (see the FocusedRow property) to the next item in a card (see the FocusedCard property) vertically.

function FocusNextRowVertically(AGoForward, AGoOnCycle: Boolean): Boolean; virtual;

Description

The AGoForward parameter specifies whether navigation is forward or backward.  Set the AGoForward to True, to move focus forward.  Otherwise the previous item will be selected;

Set the AGoOnCycle the to True, to cyclically move focus in a card.


TcxGridCardViewController.ScrollFocusedCard

TcxGridCardViewController          See Also

Scrolls the currently focused card in the specified direction.

function ScrollFocusedCard(ADown: Boolean): Boolean;

Description

The ScrollFocusedCard function scrolls card rows in the currently focused card vertically in the direction specified by the ADown parameter (True for down and False for up).  This function returns True when the scrolling operation was successful.  Scrolling is performed in steps that equal a single card row.


TcxGridCard
TcxGridCard Object

Hierarchy          Properties          Methods          See Also

Represents a record in a card view.

Unit

cxGridCardView

TcxGridCard = class(TcxCustomGridRecord);

Description

The TcxGridCard class represents a single card referencing the data of a record within a data source.  Records are presented in a form of cards in a card view of class TcxGridCardView.  You can get the cards displayed within the current view via the card view’s ViewData.Cards array.

The visual position of a card is defined by the Index property.  When you sort data by any item (card row), the card’s Index is changed to reflect the current card position.  You can use the RecordIndex property of a card as a constant reference to this card.  RecordIndex determines the position of the corresponding record in a data source.

The Values and DisplayTexts properties allow you to get a value and its text representation at a specific item (card row).

For more information on the view’s records see the TcxCustomGridRecord class topic.


TcxGridCard Hierarchy
Hierarchy

TObject

     |

TcxCustomGridRecord

     |


Properties for TcxGridCard
TcxGridCard Properties

TcxGridCard          Legend

Derived from TcxCustomGridRecord

DisplayTexts

Expandable

Expanded

Focused

HasCells

Index

IsFirst

IsLast

IsNewItemRecord

IsParentRecordLast

LastParentRecordCount

Level

ParentRecord

RecordIndex

Selected

ValueCount

Values

ViewData

Visible


Methods for TcxGridCard
TcxGridCard Methods

TcxGridCard          Legend

In TcxGridCard

 GetVisibleRows

Derived from TcxCustomGridRecord

 Collapse

 Expand

 GetFirstFocusableChild

 GetLastFocusableChild

 Invalidate

 MakeVisible


TcxGridCard.GetVisibleRows

TcxGridCard          See Also

Returns the list of rows that are currently visible within the card.

procedure GetVisibleRows(ARows: TList);

Description

Use the GetVisibleRows method to obtain a list of visible rows that belong to the card.  This method first clears the list passed as the ARows parameter and then populates this list with TcxGridCardViewRow objects representing currently visible rows.

Note: a row is not included into the resulting list if:

•	it is a data row that resides within a collapsed card;

•	it is an empty data row (provided that the view’s OptionsView.EmptyRows option is disabled);

•	this row’s Visible property value if False.


TcxGridCardViewViewData
TcxGridCardViewViewData Object

Hierarchy          Properties          Methods          See Also

Represents a class providing data retrieved from the data controller as an array of cards.

Unit

cxGridCardView

TcxGridCardViewViewData = class(TcxCustomGridTableViewData);

Description

ViewData is an intermediate class for retrieving data from the data controller and presenting it as an array of cards for a card view (TcxGridCardView).  TcxGridCardViewViewData does not introduce new functionality but publishes the Cards and CardCount properties.  The Cards collection allows you to get the values and display texts stored in the rows of a specific card.  Also, you can focus and select a specific card.

Every record (card) is an object of the TcxGridCard class.  It provides properties to retrieve values and texts for every item (field) in the record.  Each card can be identified by its index and record index.  Index defines the visual position of a card within a card view while the record index defines the position of a record within a data source. Using the properties of the TcxGridCard class, you can focus and select a specific card.

To access the ViewData object attributes use the card view’s ViewData property.


TcxGridCardViewViewData Hierarchy
Hierarchy

TObject

     |

TcxGridViewHandler

     |

TcxCustomGridViewData

     |

TcxCustomGridTableViewData

     |


Properties for TcxGridCardViewViewData
TcxGridCardViewViewData Properties

TcxGridCardViewViewData          Legend

In TcxGridCardViewViewData

CardCount

Cards

Derived from TcxCustomGridTableViewData

NewItemRecord

RecordCount

Records

Derived from TcxGridViewHandler

Control

Controller

DataController

GridView

ViewData


Methods for TcxGridCardViewViewData
TcxGridCardViewViewData Methods

TcxGridCardViewViewData          Legend

Derived from TcxCustomGridTableViewData

 Collapse

 Expand

 HasNewItemRecord

Derived from TcxGridViewHandler

 BeginUpdate

 Create

 EndUpdate


TcxGridCardViewViewData.CardCount

TcxGridCardViewViewData          See Also

Specifies the number of cards presented by the ViewData object.

property CardCount: Integer;

Description

The CardCount property returns the number of cards stored in the Cards collection.

ReadOnly Property


TcxGridCardViewViewData.Cards

TcxGridCardViewViewData          See Also

Defines a collection of cards provided by the ViewData object.

property Cards[Index: Integer]: TcxGridCard;

Description

The Cards property supports a collections of cards retrieved from the data controller.  The number of cards is determined by the CardCount property.  Each card represents an object of the TcxGridCard class enabling you to retrieve values and texts stored by every card.

ReadOnly Property


TcxGridColumnHeaderViewInfo
TcxGridColumnHeaderViewInfo Object

Hierarchy          Properties          Methods

Provides all the necessary information for drawing the column header for a tabular grid view.

Unit

cxGridTableView

TcxGridColumnHeaderViewInfo = class(TcxCustomGridViewCellViewInfo)

Description

The TcxGridColumnHeaderViewInfo allows you to implement custom drawing of the column header.

The TcxGridColumnHeaderViewInfo is used in the TcxGridTableView.OnCustomDrawColumnHeader event.  This event enables you to custom draw all the headers of a tabular grid view’s columns.  You can use the TcxGridColumn.OnCustomDrawHeader event to perform custom drawing of a single column.  To learn more about custom drawing, please refer to the Custom Draw topic.

The TcxGridColumnHeaderViewInfo class contains properties on the state, location and size of a tabular grid view’s column header.

To get the column header's state, you should reference the following properties:

•	IsFixed – indicates whether the header is fixed.

•	IsPressed – indicates whether the header is pressed.

The following properties help you to determine the actual and permitted dimensions of the header:

•	MaxWidth – contains the maximum permitted width of the header.

•	MinWidth – contains the minimum permitted width of the header.

•	RealWidth – contains the real header width.

Location and size information (such as the width or bounding rectangle) are provided by the TcxCustomGridCellViewInfo properties.

You should not create instances of ViewInfos. They are created automatically on demand.

To locate the column headers within a grid view, see the Grid View Elements topic.


TcxGridColumnHeaderViewInfo Hierarchy
Hierarchy

TObject

     |

TcxCustomGridCellViewInfo

     |

TcxCustomGridViewCellViewInfo

     |


Properties for TcxGridColumnHeaderViewInfo
TcxGridColumnHeaderViewInfo Properties

TcxGridColumnHeaderViewInfo          Legend

In TcxGridColumnHeaderViewInfo

Column

Index

IsFixed

IsPressed

MaxWidth

MinWidth

RealWidth

Derived from TcxCustomGridViewCellViewInfo

GridView

Derived from TcxCustomGridCellViewInfo

AlignmentHorz

AlignmentVert

BackgroundBitmap

BorderBounds

BorderColor

Borders

BorderSize

ContentBounds

ContentHeight

ContentWidth

Height

State

Text

TextAreaBounds

TextAreaHeight

TextAreaWidth

TextHeight

TextWidth

Transparent

Visible

Width


Methods for TcxGridColumnHeaderViewInfo
TcxGridColumnHeaderViewInfo Methods

TcxGridColumnHeaderViewInfo          Legend

In TcxGridColumnHeaderViewInfo

 GetBestFitWidth

Derived from TcxCustomGridCellViewInfo

 GetHitTest

 Paint


TcxGridColumnHeaderViewInfo.Column

TcxGridColumnHeaderViewInfo

References the Column object.

property Column: TcxGridColumn;

Description

Use the Column property to access the underlying column.

ReadOnly Property


TcxGridColumnHeaderViewInfo.Index

TcxGridColumnHeaderViewInfo

Contains the column header’s index.

property Index: Integer;

Description

The Index property contains the column index of the current column header.  This property simply references the Index of the grid’s column.

ReadOnly Property


TcxGridColumnHeaderViewInfo.IsFixed

TcxGridColumnHeaderViewInfo

Indicates whether the column’s width is fixed.

property IsFixed: Boolean;

Description

Use the IsFixed property to determine whether the width of the grid column is fixed. If the property is True, the column width cannot be changed at run-time by the user. However, you can still change it programmatically via the Width property.

If the property is False, the column can be resized by the user using the mouse.

ReadOnly Property


TcxGridColumnHeaderViewInfo.IsPressed

TcxGridColumnHeaderViewInfo

Indicates whether the column’s header is currently pressed.

property IsPressed: Boolean;

Description

Use the Pressed property to determine whether the grid column’s header is pressed.

If the property value is True, the column header’s ViewInfo State contains the gcsPressed value.  See the State property for more grid element states.

ReadOnly Property


TcxGridColumnHeaderViewInfo.MaxWidth

TcxGridColumnHeaderViewInfo

The maximum permitted width for the column.

property MaxWidth: Integer;

Description

Use the MaxWidth property to get the maximum permitted width for the column.  If TcxGridTableOptionsView.ColumnAutoWidth is set, the property contains the maximum width permitted for the column. (The width depends on the column style and the width of the cell’s content.)  Otherwise it simply contains MaxInt.  Use the MinWidth property to obtain the minimum width permitted for the column.

ReadOnly Property


TcxGridColumnHeaderViewInfo.MinWidth

TcxGridColumnHeaderViewInfo

The minimum permitted width for the column.

property MinWidth: Integer;

Description

Use the MinWidth property to obtain the minimum permitted width for the column.  The width depends on the column style and the width of the cell’s content.  Use the MaxWidth property to obtain the maximum width permitted for the column.

ReadOnly Property


TcxGridColumnHeaderViewInfo.RealWidth

TcxGridColumnHeaderViewInfo

Contains the actual width of the column.

property RealWidth: Integer;

Description

The RealWidth property is equal to the TcxCustomGridTableItem.Width property in all cases except when the grid column is the left most column and the view is grouped.  In this case the RealWidth property contains the column width plus sum of the group level indents that precedes the column.

ReadOnly Property


TcxGridColumnHeaderViewInfo.GetBestFitWidth

TcxGridColumnHeaderViewInfo

Returns the best width for the column according to the current grid layout.

function GetBestFitWidth: Integer; virtual;

Description

Use the GetBestFitWidth method to obtain the best width for the column.  The best width is calculated according to the content of the cells in the column, other columns widths and the overall views width.  The MaxWidth and MinWidth properties might also provide useful information for determining optimal column width.


TcxGridFooterCellViewInfo
TcxGridFooterCellViewInfo Object

Hierarchy          Properties          Methods

Represents information for drawing footer cells in tabular Views.

Unit

cxGridTableView

TcxGridFooterCellViewInfo = class(TcxGridColumnHeaderViewInfo)

Description

Footer cells are designed to display footer summaries for corresponding columns.  Footer summaries are stored in the View's DataController.Summary.FooterSummaryItems collection.  The SummaryItem property of the TcxGridFooterCellViewInfo object references the summary item displayed by the footer cell.

An instance of the TcxGridFooterCellViewInfo class is passed as the AViewInfo parameter to the View’s OnCustomDrawFooterCell event.  This event allows you to custom draw all footer and group footer cells in a tabular View.  Alternatively, you can handle a column’s OnCustomDrawFooterCell event to custom draw a footer cell for this column.  To learn more about custom draw please refer to the Custom Draw topic.

You should not create instances of ViewInfos.  They are created automatically on demand.

To locate footer cells within a tabular View, see the Grid View Elements topic.


TcxGridFooterCellViewInfo Hierarchy
Hierarchy

TObject

     |

TcxCustomGridCellViewInfo

     |

TcxCustomGridViewCellViewInfo

     |

TcxGridColumnHeaderViewInfo

     |


Properties for TcxGridFooterCellViewInfo
TcxGridFooterCellViewInfo Properties

TcxGridFooterCellViewInfo          Legend

In TcxGridFooterCellViewInfo

SummaryItem

Derived from TcxGridColumnHeaderViewInfo

Column

Index

IsFixed

IsPressed

MaxWidth

MinWidth

RealWidth

Derived from TcxCustomGridViewCellViewInfo

GridView

Derived from TcxCustomGridCellViewInfo

AlignmentHorz

AlignmentVert

BackgroundBitmap

BorderBounds

BorderColor

Borders

BorderSize

ContentBounds

ContentHeight

ContentWidth

Height

State

Text

TextAreaBounds

TextAreaHeight

TextAreaWidth

TextHeight

TextWidth

Transparent

Visible

Width


Methods for TcxGridFooterCellViewInfo
TcxGridFooterCellViewInfo Methods

TcxGridFooterCellViewInfo          Legend

Derived from TcxCustomGridCellViewInfo

GetHitTest

Paint


TcxGridFooterCellViewInfo.SummaryItem

TcxGridFooterCellViewInfo

Provides access to the summary item displayed by the footer cell.

property SummaryItem: TcxDataSummaryItem;

Description

Use the View’s DataController.Summary property to access a collection of summaries associated with the View.

ReadOnly Property


TcxGridRowFooterCellViewInfo
TcxGridRowFooterCellViewInfo Object

Hierarchy          Properties          Methods

Represents information for drawing group footer cells in tabular Views.

Unit

cxGridTableView

TcxGridRowFooterCellViewInfo = class(TcxGridFooterCellViewInfo)

Description

Group footer cells are designed to display group summaries for corresponding columns.  Group summaries are stored in the View's DataController.Summar.DefaultGroupSummaryItems collection.  The SummaryItem property of the TcxGridRowFooterCellViewInfo object references the summary item displayed by the group footer cell.

An instance of the TcxGridRowFooterCellViewInfo class is passed as the AViewInfo parameter to the View’s OnCustomDrawFooterCell event.  This event allows you to custom draw all footer and group footer cells in a tabular View.  Alternatively, you can handle a column’s OnCustomDrawFooterCell event to perform custom draw a group footer cell for this column.  To learn more about custom draw please refer to the Custom Draw topic.

You should not create instances of ViewInfos.  They are created automatically on demand.

To locate group footer cells within a tabular View, see the Grid View Elements topic.


TcxGridRowFooterCellViewInfo Hierarchy
Hierarchy

TObject

     |

TcxCustomGridCellViewInfo

     |

TcxCustomGridViewCellViewInfo

     |

TcxGridColumnHeaderViewInfo

     |


Properties for TcxGridRowFooterCellViewInfo
TcxGridRowFooterCellViewInfo Properties

TcxGridFooterCellViewInfo          Legend

In TcxGridRowFooterCellViewInfo

GridRecord

Derived from TcxGridFooterCellViewInfo

SummaryItem

Derived from TcxGridColumnHeaderViewInfo

Column

Index

IsFixed

IsPressed

MaxWidth

MinWidth

RealWidth

Derived from TcxCustomGridViewCellViewInfo

GridView

Derived from TcxCustomGridCellViewInfo

AlignmentHorz

AlignmentVert

BackgroundBitmap

BorderBounds

BorderColor

Borders

BorderSize

ContentBounds

ContentHeight

ContentWidth

Height

State

Text

TextAreaBounds

TextAreaHeight

TextAreaWidth

TextHeight

TextWidth

Transparent

Visible

Width


Methods for TcxGridRowFooterCellViewInfo
TcxGridRowFooterCellViewInfo Methods

TcxGridFooterCellViewInfo          Legend

Derived from TcxCustomGridCellViewInfo

GetHitTest

Paint


TcxGridRowFooterCellViewInfo.GridRecord

TcxGridFooterCellViewInfo

Provides access to the underlying grid record that corresponds to the group footer cell.

property GridRecord: TcxCustomGridRecord;

ReadOnly Property


TcxCustomGridIndicatorItemViewInfo
TcxCustomGridIndicatorItemViewInfo Object

Hierarchy          Properties         Methods

Provides general information used in drawing the indicators in tabular grid view's.

Unit

cxGridTableView

TcxCustomGridIndicatorItemViewInfo = class(TcxCustomGridViewCellViewInfo)

Description

The TcxCustomGridIndicatorItemViewInfo contains information used to draw grid indicators.

There are three types of indicator items ViewInfos available:

1.	TcxGridIndicatorHeaderItemViewInfo – header indicator ViewInfo,

2.	TcxGridIndicatorRowItemViewInfo – row indicator ViewInfo,

3.	TcxGridIndicatorFooterItemViewInfo – footer indicator ViewInfo.

You should not create instances of this ViewInfos or its descendants. It is created when the TcxGridTableView.OnCustomDrawIndicatorCell event fires and is passed as its AViewInfo parameter.  You should use this event to perform custom drawing of the grid view's indicator cell.

To locate the indicator within a grid view, see the Grid View Elements topic.


TcxCustomGridIndicatorItemViewInfo Hierarchy
Hierarchy

TObject

     |

TcxCustomGridCellViewInfo

     |

TcxCustomGridViewCellViewInfo

     |


Properties for TcxCustomGridIndicatorItemViewInfo
TcxCustomGridIndicatorItemViewInfo Properties

TcxCustomGridIndicatorItemViewInfo          Legend

In TcxCustomGridIndicatorItemViewInfo

Container

Derived from TcxCustomGridViewCellViewInfo

GridView

Derived from TcxCustomGridCellViewInfo

AlignmentHorz

AlignmentVert

BackgroundBitmap

BorderBounds

BorderColor

Borders

BorderSize

ContentBounds

ContentHeight

ContentWidth

Height

State

Text

TextAreaBounds

TextAreaHeight

TextAreaWidth

TextHeight

TextWidth

Transparent

Visible

Width


Methods for TcxCustomGridIndicatorItemViewInfo
TcxCustomGridIndicatorItemViewInfo Methods

TcxCustomGridIndicatorItemViewInfo          Legend

Derived from TcxCustomGridCellViewInfo

 GetHitTest

 Paint


TcxCustomGridIndicatorItemViewInfo.Container

TcxCustomGridIndicatorItemViewInfo

Accesses the ViewInfo for the indicators owner.

property Container: TcxGridIndicatorViewInfo;

Description

The Container property enables you to access the viewinfo of the current grid view's indicator.  This allows you to access the ViewInfos of other indicator items (the TcxGridIndicatorViewInfo.Items property) and the count of indicator items (the TcxGridIndicatorViewInfo.Count property). The number of indicator items is equal to the number of currently visible table rows.

ReadOnly Property


TcxGridIndicatorFooterItemViewInfo
TcxGridIndicatorFooterItemViewInfo Object

Hierarchy          Properties          Methods

Provides painting information for the footer indicator of a grid view.

Unit

cxGridTableView

TcxGridIndicatorFooterItemViewInfo = class(TcxCustomGridIndicatorItemViewInfo)

Description

The TcxGridIndicatorFooterItemViewInfo class provides painting information specific for the grid view's footer indicator.  For instance, you can use the IndicatorKind property to draw indicator marks relative to the state of the corresponding row.  You can provide a different appearance for a mark if its corresponding row is selected, contains the focused or edited cell, etc.  Also you can access the corresponding grid record (the GridRecord property) to draw an indicator cell based on the grid record properties.

You should not create instances this ViewInfo or its descendants. It is created when the TcxGridTableView.OnCustomDrawIndicatorCell event fires and is passed as its AViewInfo parameter.  You should use this event to perform custom drawing of the grid view's indicator item.

To locate the indicator within a grid view, see the Grid View Elements topic.


TcxGridIndicatorFooterItemViewInfo Hierarchy
Hierarchy

TObject

     |

TcxCustomGridCellViewInfo

     |

TcxCustomGridViewCellViewInfo

     |

TcxCustomGridIndicatorItemViewInfo

     |

TcxGridIndicatorFooterItemViewInfo


Properties for TcxGridIndicatorFooterItemViewInfo
TcxGridIndicatorFooterItemViewInfo Properties

TcxGridIndicatorFooterItemViewInfo          Legend

In TcxGridIndicatorFooterItemViewInfo

SeparatorWidth

Derived from TcxCustomGridIndicatorItemViewInfo

Container

Derived from TcxCustomGridViewCellViewInfo

GridView

Derived from TcxCustomGridCellViewInfo

AlignmentHorz

AlignmentVert

BackgroundBitmap

BorderBounds

BorderColor

Borders

BorderSize

ContentBounds

ContentHeight

ContentWidth

Height

State

Text

TextAreaBounds

TextAreaHeight

TextAreaWidth

TextHeight

TextWidth

Transparent

Visible

Width


Methods for TcxGridIndicatorFooterItemViewInfo
TcxGridIndicatorFooterItemViewInfo Methods

TcxGridIndicatorFooterItemViewInfo          Legend

Derived from TcxCustomGridCellViewInfo

 GetHitTest

 Paint


TcxGridIndicatorFooterItemViewInfo.SeparatorWidth

TcxGridIndicatorFooterItemViewInfo

The width of the footer indicator’s separator.

property SeparatorWidth: Integer;

Description

The SeparatorWidth property represents the width of the footer indicator’s separator.

Please refer to the Grid View Elements topic for information on what the separator is and where it is located.

ReadOnly Property


TcxGridIndicatorRowItemViewInfo
TcxGridIndicatorRowItemViewInfo Object

Hierarchy          Properties          Methods

Painting information for the row indicator of a grid view.

Unit

cxGridTableView

TcxGridIndicatorRowItemViewInfo = class(TcxCustomGridIndicatorItemViewInfo)

Description

The TcxGridIndicatorRowItemViewInfo provides information for drawing a grid row indicator.  For instance, you can use the IndicatorKind property to draw indicator marks according to the state of the corresponding row.  You can provide a different appearance for a mark if its corresponding row is selected, contains the focused or edited cell, etc.   Also you can access the corresponding grid record (the GridRecord property.

You should not create instances this ViewInfo or its descendants. It is created when the TcxGridTableView.OnCustomDrawIndicatorCell event fires and is passed as its AViewInfo parameter.  You should use this event to perform custom draw of the grid view's indicator item.

To locate the indicator within a grid view, see the Grid View Elements topic.


TcxGridIndicatorRowItemViewInfo Hierarchy
Hierarchy

TObject

     |

TcxCustomGridCellViewInfo

     |

TcxCustomGridViewCellViewInfo

     |

TcxCustomGridIndicatorItemViewInfo

     |


Properties for TcxGridIndicatorRowItemViewInfo
TcxGridIndicatorRowItemViewInfo Properties

TcxGridIndicatorRowItemViewInfo          Legend

In TcxGridIndicatorRowItemViewInfo

GridRecord

IndicatorKind

Derived from TcxCustomGridIndicatorItemViewInfo

Container

Derived from TcxCustomGridViewCellViewInfo

GridView

Derived from TcxCustomGridCellViewInfo

AlignmentHorz

AlignmentVert

BackgroundBitmap

BorderBounds

BorderColor

Borders

BorderSize

ContentBounds

ContentHeight

ContentWidth

Height

State

Text

TextAreaBounds

TextAreaHeight

TextAreaWidth

TextHeight

TextWidth

Transparent

Visible

Width


Methods for TcxGridIndicatorRowItemViewInfo
TcxGridIndicatorRowItemViewInfo Methods

TcxGridIndicatorRowItemViewInfo          Legend

Derived from TcxCustomGridCellViewInfo

 GetHitTest

 Paint


TcxGridIndicatorRowItemViewInfo.GridRecord

TcxGridIndicatorRowItemViewInfo

Reference to the underlying Grid row.

property GridRecord: TcxCustomGridRow;

Description

The GridRecord property allows you to paint an indicator item based on the state of the grid row.

ReadOnly Property


TcxGridIndicatorRowItemViewInfo.IndicatorKind

TcxGridIndicatorRowItemViewInfo

 Indicator State of the current row.

type

  TcxIndicatorKind = (ikNone, ikArrow, ikEdit, ikInsert, ikMultiDot, ikMultiArrow);

property IndicatorKind: TcxIndicatorKind;

Description

The indicator enables a user to determine the selected record or cell state visually: selected, edited, part of multiselection, etc. Each state has its descriptive image that is displayed within a grid indicator cell.  The IndicatorKind property value specifies the indicator being used for the current record.

There are six kinds of indicator available:

Value	Description
ikNone	A record is neither focused, nor selected.
ikArrow	Multuselect is disabled (the MultiSelect property is False).  A cell is either focused or selected.
ikEdit	A record cell is being edited.
ikInsert	A new row is inserted into the grid view, but is not posted to the dataset.
ikMultiDot	Multuselect is enabled (the MultiSelect property is True).  A cell is selected, but not focused.
ikMultiArrow	Multuselect is enabled (the MultiSelect property is True).  A cell is focused.

You may use this property to implement your own descriptive images for the indicator kinds.

ReadOnly Property


TcxGridIndicatorViewInfo
TcxGridIndicatorViewInfo Object

Hierarchy          Properties          Methods

Painting information for the indicator of a grid view.

Unit

cxGridTableView

TcxGridIndicatorViewInfo = class(TcxCustomGridViewCellViewInfo)

Description

The TcxGridIndicatorViewInfo provides information used in the painting of indicators.  This allows you to implement custom drawing of the grid indicator.

The indicator ViewInfo has an Items property that accesses the ViewInfos of all indicator rows including footer and header indicators.  There are several conditions affecting the contents of the Items collection:

•	If a grid view has a header (the TcxGirdTableView.OptionsView.Header property is True), the first item (with the zero index) refers to an indicator header item. The rest of the items refer to row indicator items.

•	If the grid view has a footer (the TcxGirdTableView.OptionsView.Footer property is True) and has no header (the TcxGirdTableView.OptionsView.Header property is False), the first item (with the zero index) refers to a footer indicator item. The rest of the items refer to row indicator items.

•	If a grid view has both a header and a footer (the TcxGirdTableView.OptionsView.Footer and TcxGirdTableView.OptionsView.Header properties are True), the first item (with the zero index) refers to a header indicator item and the second - to a footer indicator item. The rest of the items refer to row indicator items.

•	If a grid view has neither header nor footer (the TcxGirdTableView.OptionsView.Footer and TcxGirdTableView.OptionsView.Header properties are False), all items refer to row indicator items.

You should not create instances of this ViewInfo or its descendants. It is created when the TcxGridTableView.OnCustomDrawIndicatorCell event fires and is passed as its AViewInfo parameter.  You should use this event to perform custom draw of the grid view's indicator item.

To locate the indicator within a grid view, see the Grid View Elements topic.


TcxGridIndicatorViewInfo Hierarchy
Hierarchy

TObject

     |

TcxCustomGridCellViewInfo

     |

TcxCustomGridViewCellViewInfo

     |


Properties for TcxGridIndicatorViewInfo
TcxGridIndicatorViewInfo Properties

TcxGridIndicatorViewInfo          Legend

In TcxGridIndicatorViewInfo

Count

Items

Derived from TcxCustomGridViewCellViewInfo

GridView

Derived from TcxCustomGridCellViewInfo

AlignmentHorz

AlignmentVert

BackgroundBitmap

BorderBounds

BorderColor

Borders

BorderSize

ContentBounds

ContentHeight

ContentWidth

Height

State

Text

TextAreaBounds

TextAreaHeight

TextAreaWidth

TextHeight

TextWidth

Transparent

Visible

Width


Methods for TcxGridIndicatorViewInfo
TcxGridIndicatorViewInfo Methods

TcxGridIndicatorViewInfo          Legend

Derived from TcxCustomGridCellViewInfo

 GetHitTest

 Paint


TcxGridIndicatorViewInfo.Count

TcxGridIndicatorViewInfo

The count of indicator items including the header and footer.

property Count: Integer;

Description

Use this property to obtain the indicator items count including the header and footer.

The indicator viewinfo has an Items property that accesses all row indicator viewinfos including footer and header indicator viewinfos.

There are several conditions affecting the contents of the Items collection:

1.	If a grid view has a header (the TcxGirdTableView.OptionsView.Header property is True), the first item (with the zero index) refers to a header indicator item. The rest of the items refer to row indicator items.

2.	If the grid view has a footer (the TcxGirdTableView.OptionsView.Footer property is True) and has no header (the TcxGirdTableView.OptionsView.Header property is False), the first item (with the zero index) refers to a footer indicator item. The rest of the items refer to row indicator items.

3.	If a grid view has both a header and a footer (the TcxGirdTableView.OptionsView.Footer and TcxGirdTableView.OptionsView.Header properties are True), the first item (with the zero index) refers to a header indicator item and the second - to an footer indicator item. The rest of the items refer to row indicator items.

4.	If a grid view has neither header nor footer (the TcxGirdTableView.OptionsView.Footer and TcxGirdTableView.OptionsView.Header properties are False), all items refer to row indicator items.

ReadOnly Property


TcxGridIndicatorViewInfo.Items

TcxGridIndicatorViewInfo

Indexed property referencing the ViewInfos of all row footer and header indicators.

property Items[Index: Integer]: TcxCustomGridIndicatorItemViewInfo;

Description

The Items property enables you to access the ViewInfos of all indicators including footer and header indicators.  There are several conditions affecting the contents of the Items collection:

1.	If a grid view has a header (the TcxGirdTableView.OptionsView.Header property is True), the first item (with the zero index) refers to a header indicator item. The rest of the items refer to row indicator items.

2.	If a grid view has a footer (the TcxGirdTableView.OptionsView.Footer property is True) and has no header (the TcxGirdTableView.OptionsView.Header property is False), the first item (with the zero index) refers to a footer indicator item. The rest of the items refer to row indicator items.

3.	If a grid view has both a header and a footer (the TcxGirdTableView.OptionsView.Footer and TcxGirdTableView.OptionsView.Header properties are True), the first item (with the zero index) refers to an header indicator item and the second - to an footer indicator item. The rest of the items refer to row indicator items.

4.	If a grid view has neither header nor footer (the TcxGirdTableView.OptionsView.Footer and TcxGirdTableView.OptionsView.Header properties are False), all items refer to row indicator items.

ReadOnly Property


TcxGridIndicatorHeaderItemViewInfo
TcxGridIndicatorHeaderItemViewInfo Object

Hierarchy          Properties          Methods

Contains painting information for the header indicator of a grid view.

Unit

cxGridTableView

TcxGridIndicatorFooterItemViewInfo = class(TcxCustomGridIndicatorItemViewInfo)

Description

The TcxGridIndicatorFooterItemViewInfo class provides information for drawing the header indicator.

You should not create instances this ViewInfo or its descendants. It is created when the TcxGridTableView.OnCustomDrawIndicatorCell event fires and is passed as its AViewInfo parameter.  You should use this event to perform custom draw of the grid view's indicator item.

To locate the indicator within a grid view, see the Grid View Elements topic.


TcxGridIndicatorHeaderItemViewInfo Hierarchy
Hierarchy

TObject

     |

TcxCustomGridCellViewInfo

     |

TcxCustomGridViewCellViewInfo

     |

TcxCustomGridIndicatorItemViewInfo

     |


Properties for TcxGridIndicatorHeaderItemViewInfo
TcxGridIndicatorHeaderItemViewInfo Properties

TcxGridIndicatorFooterItemViewInfo          Legend

Derived from TcxCustomGridIndicatorItemViewInfo

Container

Derived from TcxCustomGridViewCellViewInfo

GridView

Derived from TcxCustomGridCellViewInfo

AlignmentHorz

AlignmentVert

BackgroundBitmap

BorderBounds

BorderColor

Borders

BorderSize

ContentBounds

ContentHeight

ContentWidth

Height

State

Text

TextAreaBounds

TextAreaHeight

TextAreaWidth

TextHeight

TextWidth

Transparent

Visible

Width


Methods for TcxGridIndicatorHeaderItemViewInfo
TcxGridIndicatorHeaderItemViewInfo Methods

TcxGridIndicatorRowItemViewInfo          Legend

Derived from TcxCustomGridCellViewInfo

 GetHitTest

 Paint


TcxGridRowIndicatorHitTest
TcxGridRowIndicatorHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the row indicator which is located at the point being tested.

Unit

cxGridTableView

TcxGridRowIndicatorHitTest = class(TcxGridRecordHitTest)

Description

The TcxGridRowIndicatorHitTest class designates the hit code (which is equal to htRowIndicator) of the row indicator which is located at the Grid View’s point that is being tested and also introduces the MultiSelect field whose values are used to determine whether multiple selection of records or grouping rows is in effect and change the mouse pointer accordingly.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridRowIndicatorHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxGridRecordHitTest

     |


Properties for TcxGridRowIndicatorHitTest
TcxGridRowIndicatorHitTest Properties

TcxGridRowIndicatorHitTest          Legend

In TcxGridRowIndicatorHitTest

MultiSelect

Derived from TcxGridRecordHitTest

GridRecord

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridRowIndicatorHitTest
TcxGridRowIndicatorHitTest Methods

TcxGridRowIndicatorHitTest          Legend

Derived from TcxGridRecordHitTest

CanClick

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridRowIndicatorHitTest.MultiSelect

TcxGridRowIndicatorHitTest          See Also

Indicates whether multiple records or grouping rows can be selected.

MultiSelect: Boolean;

Description

The MultiSelect field returns True when multiple records or grouping rows is in effect.  Otherwise, False is returned.


TcxGridRowSizingEdgeHitTest
TcxGridRowSizingEdgeHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the (grouping) row sizing edge which is located at the point being tested.

Unit

cxGridTableView

TcxGridRowSizingEdgeHitTest = class(TcxGridRecordHitTest)

Description

The TcxGridRowSizingEdgeHitTest class does not introduce any new functionality, but instead designates the hit code (which is equal to htRowSizingEdge) of the (grouping) row sizing edge which is located at the Grid View’s point that is being tested.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridRowSizingEdgeHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxGridRecordHitTest

     |


Properties for TcxGridRowSizingEdgeHitTest
TcxGridRowSizingEdgeHitTest Properties

TcxGridRowSizingEdgeHitTest          Legend

Derived from TcxGridRecordHitTest

GridRecord

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridRowSizingEdgeHitTest
TcxGridRowSizingEdgeHitTest Methods

TcxGridRowSizingEdgeHitTest          Legend

Derived from TcxGridRecordHitTest

CanClick

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridRowLevelIndentHitTest
TcxGridRowLevelIndentHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the row level indent which is located at the point being tested.

Unit

cxGridTableView

TcxGridRowLevelIndentHitTest = class(TcxGridRecordHitTest)

Description

The TcxGridRowLevelIndentHitTest class designates the hit code (which is equal to htRowLevelIndent) of the row level indent located at the Grid View’s point that is being tested.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridRowLevelIndentHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxGridRecordHitTest

     |


Properties for TcxGridRowLevelIndentHitTest
TcxGridRowLevelIndentHitTest Properties

TcxGridRowLevelIndentHitTest          Legend

Derived from TcxGridRecordHitTest

GridRecord

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridRowLevelIndentHitTest
TcxGridRowLevelIndentHitTest Methods

TcxGridRowLevelIndentHitTest          Legend

Derived from TcxGridRecordHitTest

CanClick

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxCustomGridColumnHitTest
TcxCustomGridColumnHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the tabular column which is located at the point being tested.

Unit

cxGridTableView

TcxCustomGridColumnHitTest = class(TcxCustomGridViewHitTest)

Description

The TcxCustomGridColumnHitTest class provides general information for the column within the (Banded) Table View which is located at the View’s point that is being tested.  The corresponding column and View can be accessed using the Column and GridView properties, respectively.

TcxCustomGridColumnHitTest descendants extend their ancestor class with the properties and methods that are specific to the grid view elements (related to a column) they correspond to.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxCustomGridColumnHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |


Properties for TcxCustomGridColumnHitTest
TcxCustomGridColumnHitTest Properties

TcxCustomGridColumnHitTest          Legend

In TcxCustomGridColumnHitTest

Column

ColumnContainerKind

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxCustomGridColumnHitTest
TcxCustomGridColumnHitTest Methods

TcxCustomGridColumnHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxCustomGridColumnHitTest.Column

TcxCustomGridViewHitTest

Provides access to the inspected (banded) table view column.

property Column: TcxGridColumn;

Description

Use the Column property to access the properties and methods of the (banded) table view column whose point is being inspected.


TcxCustomGridColumnHitTest.ColumnContainerKind

TcxCustomGridViewHitTest

Specifies a container for the inspected grid view column.

type

  TcxGridColumnContainerKind = Integer;

property ColumnContainerKind: TcxGridColumnContainerKind;

Description

The ColumnContainerKind property specifies the container for the grid view column at the (Banded) Table View’s point which is being inspected (where the column is located).  The column is accessible via the Column property.  The table below lists all the possible values for the ColumnContainerKind property.

Value	Meaning
ckCustomizationForm	The column is located in the (Banded) Table View’s customization form.
ckFooter	The column is located in the (Banded) Table View’s footer panel.
ckHeader	The column is located in the column header of the (Banded) Table View.
ckGroupByBox	The column is located in the (Banded) Table View’s Group By box.
ckNone	The column is located in none of the above containers.


TcxGridColumnHeaderHorzSizingEdgeHitTest
TcxGridColumnHeaderHorzSizingEdgeHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the grid view column header horizontal sizing edge which is located at the point being tested.

Unit

cxGridTableView

TcxGridColumnHeaderHorzSizingEdgeHitTest = class(TcxCustomGridColumnHitTest)

Description

The TcxGridColumnHeaderHorzSizingEdgeHitTest class does not introduce any new functionality, but instead designates the hit code (which is equal to htColumnHeaderHorzSizingEdge) of the grid view column header horizontal sizing edge which is located at the (Banded) Table View’s point that is being tested.  The corresponding column and View can be accessed using the Column and GridView properties, respectively.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridColumnHeaderHorzSizingEdgeHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxCustomGridColumnHitTest

     |


Properties for TcxGridColumnHeaderHorzSizingEdgeHitTest
TcxGridColumnHeaderHorzSizingEdgeHitTest Properties

TcxGridColumnHeaderHorzSizingEdgeHitTest          Legend

Derived from TcxCustomGridColumnHitTest

Column

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridColumnHeaderHorzSizingEdgeHitTest
TcxGridColumnHeaderHorzSizingEdgeHitTest Methods

TcxGridColumnHeaderHorzSizingEdgeHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridColumnHeaderHitTest
TcxGridColumnHeaderHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the grid view column header which is located at the point being tested.

Unit

cxGridTableView

TcxGridColumnHeaderHitTest = class(TcxCustomGridColumnHitTest)

Description

The TcxGridColumnHeaderHitTest class does not introduce any new functionality, but instead designates the hit code (which is equal to htColumnHeader) of the grid view column header which is located at the Grid View’s point that is being tested.  The corresponding column and View can be accessed using the Column and GridView properties, respectively.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridColumnHeaderHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxCustomGridColumnHitTest

     |


Properties for TcxGridColumnHeaderHitTest
TcxGridColumnHeaderHitTest Properties

TcxGridColumnHeaderHitTest          Legend

Derived from TcxCustomGridColumnHitTest

Column

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridColumnHeaderHitTest
TcxGridColumnHeaderHitTest Methods

TcxGridColumnHeaderHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridColumnHeaderFilterButtonHitTest
TcxGridColumnHeaderFilterButtonHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the grid view column header filter dropdown button which is located at the point being tested.

Unit

cxGridTableView

TcxGridColumnHeaderFilterButtonHitTest = class(TcxCustomGridColumnHitTest)

Description

The TcxGridColumnHeaderFilterButtonHitTest class does not introduce any new functionality, but instead designates the hit code (which is equal to htColumnHeaderFilterButton) of the grid view column header filter dropdown button which is located at the (Banded) Table View’s point that is being tested.  The corresponding column and View can be accessed using the Column and GridView properties, respectively.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridColumnHeaderFilterButtonHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxCustomGridColumnHitTest

     |


Properties for TcxGridColumnHeaderFilterButtonHitTest
TcxGridColumnHeaderFilterButtonHitTest Properties

TcxGridColumnHeaderFilterButtonHitTest          Legend

Derived from TcxCustomGridColumnHitTest

Column

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridColumnHeaderFilterButtonHitTest
TcxGridColumnHeaderFilterButtonHitTest Methods

TcxGridColumnHeaderFilterButtonHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridFooterCellHitTest
TcxGridFooterCellHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the view footer cell located at the point being tested.

Unit

cxGridTableView

TcxGridFooterCellHitTest = class(TcxCustomGridColumnHitTest)

Description

In addition to the settings inherited from the base TcxCustomGridColumnHitTest class, the TcxGridFooterCellHitTest class:

•	introduces the SummaryItem property that provides access to the summary object displayed in the footer cell;

•	designates the hit code (which is equal to htFooterCell) of the footer cell located at the point being tested.

Please refer to the Summaries topic for information on displaying data within footers.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridFooterCellHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxCustomGridColumnHitTest

     |


Properties for TcxGridFooterCellHitTest
TcxGridFooterCellHitTest Properties

TcxGridFooterCellHitTest          Legend

In TcxGridFooterCellHitTest

SummaryItem

Derived from TcxCustomGridColumnHitTest

Column

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridFooterCellHitTest
TcxGridFooterCellHitTest Methods

TcxGridFooterCellHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridFooterCellHitTest.SummaryItem

TcxGridFooterCellHitTest

Provides access to the summary object displayed in the inspected footer cell.

property SummaryItem: TcxDataSummaryItem;

Description

Use the View’s OptionsView.FooterMultiSummaries and OptionsView.GroupFooterMultiSummaries properties to display multiple summaries in the View’s footer and group footer panels.


TcxGridGroupFooterCellHitTest
TcxGridGroupFooterCellHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the grid view's group footer cell which is located at the point being tested.

Unit

cxGridTableView

TcxGridGroupFooterCellHitTest = class(TcxGridFooterCellHitTest)

Description

The TcxGridGroupFooterCellHitTest class does not introduce any new functionality, but instead designates the hit code (which is equal to htGroupFooterCell) of the grid view's group footer cell which is displayed within the group footer and located at the (Banded) Table View’s point that is being tested.

Please refer to the Summaries topic for information on displaying data within group footers.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridGroupFooterCellHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxCustomGridColumnHitTest

     |

TcxGridFooterCellHitTest

     |


Properties for TcxGridGroupFooterCellHitTest
TcxGridGroupFooterCellHitTest Properties

TcxGridGroupFooterCellHitTest          Legend

Derived from TcxGridFooterCellHitTest

SummaryItem

Derived from TcxCustomGridColumnHitTest

Column

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridGroupFooterCellHitTest
TcxGridGroupFooterCellHitTest Methods

TcxGridGroupFooterCellHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridGroupByBoxHitTest
TcxGridGroupByBoxHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the Group By box which is located at the point being tested.

Unit

cxGridTableView

TcxGridGroupByBoxHitTest = class(TcxCustomGridViewHitTest)

Description

The TcxGridGroupByBoxHitTest class does not introduce any new functionality, but instead designates the hit code (which is equal to htGroupByBox) of the Group By box which is located at the Grid View’s point that is being tested.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridGroupByBoxHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |


Properties for TcxGridGroupByBoxHitTest
TcxGridGroupByBoxHitTest Properties

TcxGridGroupByBoxHitTest          Legend

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridGroupByBoxHitTest
TcxGridGroupByBoxHitTest Methods

TcxGridGroupByBoxHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridHeaderHitTest
TcxGridHeaderHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the tabular View grid header, which is located at the point being tested.

Unit

cxGridTableView

TcxGridHeaderHitTest = class(TcxCustomGridViewHitTest)

Description

The TcxGridHeaderHitTest class does not introduce any new functionality, but instead designates the hit code (which is equal to htHeader) of the grid header (the column header panel in the Table View and both the band header panel and column header panel in the Banded Table View) within a tabular View which is located at the View’s point that is being tested.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridHeaderHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |


Properties for TcxGridHeaderHitTest
TcxGridHeaderHitTest Properties

TcxGridHeaderHitTest          Legend

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridHeaderHitTest
TcxGridHeaderHitTest Methods

TcxGridHeaderHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridFooterHitTest
TcxGridFooterHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the (banded) table view grid footer which is located at the point being tested.

Unit

cxGridTableView

TcxGridFooterHitTest = class(TcxCustomGridViewHitTest)

Description

The TcxGridFooterHitTest class does not introduce any new functionality, but instead designates the hit code (which is equal to htFooter) of the grid footer within a tabular View which is located at the View’s point that is being tested.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridFooterHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |


Properties for TcxGridFooterHitTest
TcxGridFooterHitTest Properties

TcxGridFooterHitTest          Legend

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridFooterHitTest
TcxGridFooterHitTest Methods

TcxGridFooterHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridGroupFooterHitTest
TcxGridGroupFooterHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the grid view group footer which is located at the point being tested.

Unit

cxGridTableView

TcxGridGroupFooterHitTest = class(TcxGridFooterCellHitTest)

Description

The TcxGridGroupFooterHitTest class does not introduce any new functionality, but instead designates the hit code (which is equal to htGroupFooter) of the grid view group footer which is located at the (Banded) Table View’s point that is being tested.  The corresponding column and View can be accessed using the Column and GridView properties, respectively.

Please refer to the Summaries topic for information on displaying data within group footers.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridGroupFooterHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxCustomGridColumnHitTest

     |

TcxGridFooterCellHitTest

     |


Properties for TcxGridGroupFooterHitTest
TcxGridGroupFooterHitTest Properties

TcxGridGroupFooterHitTest          Legend

Derived from TcxCustomGridColumnHitTest

Column

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridGroupFooterHitTest
TcxGridGroupFooterHitTest Methods

TcxGridGroupFooterHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridIndicatorHeaderHitTest
TcxGridIndicatorHeaderHitTest Object

Hierarchy

TcxGridIndicatorHeaderHitTest provides hit information for the inspected column header’s indicator.

Unit

cxGridTableView

TcxGridIndicatorHeaderHitTest = class(TcxGridIndicatorHitTest)

Description

htIndicatorHeader is a unique identifier for the column header indicator (it is returned by the HitTestCode method).


TcxGridIndicatorHeaderHitTest Hierarchy
Hierarchy

TcxCustomGridViewHitTest

     |

TcxGridIndicatorHitTest

     |

TcxGridIndicatorHeaderHitTest


TcxGridIndicatorHitTest
TcxGridIndicatorHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the grid indicator which is located at the point being tested.

Unit

cxGridTableView

TcxGridIndicatorHitTest = class(TcxCustomGridViewHitTest)

Description

The TcxGridIndicatorHitTest class does not introduce any new functionality, but instead designates the hit code (which is equal to htIndicator) of the indicator within a tabular View which is located at the View’s point that is being tested.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridIndicatorHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |


Properties for TcxGridIndicatorHitTest
TcxGridIndicatorHitTest Properties

TcxGridIndicatorHitTest          Legend

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridIndicatorHitTest
TcxGridIndicatorHitTest Methods

TcxGridIndicatorHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridBandHitTest
TcxGridBandHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the grid view band which is located at the point being tested.

Unit

cxGridBandedTableView

TcxGridBandHitTest = class(TcxCustomGridViewHitTest)

Description

The TcxGridBandHitTest class designates the hit code (which is equal to htBand) of the grid view band which is located at the grid view’s point that is being tested and also provides access to the band (which is accessible via the Band property) and specifies band-specific information such as the container control in which the band is located and the hypothetical vertical position of a column when it’s positioned at the inspected point of the band (which are accessible via the BandContainerKind and VisibleRowIndex properties, respectively).

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridBandHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |


Properties for TcxGridBandHitTest
TcxGridBandHitTest Properties

TcxGridBandHitTest          Legend

In TcxGridBandHitTest

Band

BandContainerKind

VisibleRowIndex

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridBandHitTest
TcxGridBandHitTest Methods

TcxGridBandHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridBandHitTest.Band

TcxGridBandHitTest

Specifies the grid view band located at the point in the grid view which the hit test information has been obtained for.

property Band: TcxGridBand;

Description

The Band property specifies the grid view band at the grid view’s point which the hit test information has been obtained for.  The grid view whose point is being inspected can be accessed via the GridView property.


TcxGridBandHitTest.BandContainerKind

TcxGridBandHitTest

Specifies the container control in which the grid view band is located.

type

  TcxGridBandContainerKind = (bcHeader, bcCustomizationForm);

property BandContainerKind: TcxGridBandContainerKind;

Description

The BandContainerKind property specifies the container control for the grid view band at the grid view’s point which is being inspected (where the band is located).  The band is accessible via the Band property.  The table below lists all the possible values for the BandContainerKind property.

Value	Meaning
bcHeader	The band is located in the Banded Table View.
bcCustomizationForm	The band is located in the Banded Table View’s customization form.


TcxGridBandHitTest.VisibleRowIndex

TcxGridBandHitTest

Specifies the hypothetical vertical position of a column when it’s positioned at the inspected point of the band.

property VisibleRowIndex: Integer;

Description

The VisibleRowIndex property specifies the hypothetical vertical position (row) of a column when it’s positioned at the inspected point of the band which is accessible via the Band property.  The grid view whose point is being inspected can be accessed via the GridView property.


TcxGridBandHeaderHitTest
TcxGridBandHeaderHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the grid view band header which is located at the point being tested.

Unit

cxGridBandedTableView

TcxGridBandHeaderHitTest = class(TcxGridBandHitTest)

Description

The TcxGridBandHeaderHitTest class does not introduce any new functionality, but instead designates the hit code (which is equal to htBandHeader) of the grid view band header which is located at the grid view’s point that is being tested.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridBandHeaderHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxGridBandHitTest

     |


Properties for TcxGridBandHeaderHitTest
TcxGridBandHeaderHitTest Properties

TcxGridBandHeaderHitTest          Legend

Derived from TcxGridBandHitTest

Band

BandContainerKind

VisibleRowIndex

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridBandHeaderHitTest
TcxGridBandHeaderHitTest Methods

TcxGridBandHeaderHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridBandHeaderSizingEdgeHitTest
TcxGridBandHeaderSizingEdgeHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the grid view band header sizing edge which is located at the point being tested.

Unit

cxGridBandedTableView

TcxGridBandHeaderSizingEdgeHitTest = class(TcxGridBandHitTest)

Description

The TcxGridBandHeaderSizingEdgeHitTest class does not introduce any new functionality, but instead designates the hit code (which is equal to htBandHeaderSizingEdge) of the grid view band header sizing edge which is located at the grid view’s point that is being tested.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridBandHeaderSizingEdgeHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxGridBandHitTest

     |


Properties for TcxGridBandHeaderSizingEdgeHitTest
TcxGridBandHeaderSizingEdgeHitTest Properties

TcxGridBandHeaderSizingEdgeHitTest          Legend

Derived from TcxGridBandHitTest

Band

BandContainerKind

VisibleRowIndex

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridBandHeaderSizingEdgeHitTest
TcxGridBandHeaderSizingEdgeHitTest Methods

TcxGridBandHeaderSizingEdgeHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridColumnHeaderVertSizingEdgeHitTest
TcxGridColumnHeaderVertSizingEdgeHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the grid view column header's vertical sizing edge which is located at the point being tested.

Unit

cxGridBandedTableView

TcxGridColumnHeaderVertSizingEdgeHitTest = class(TcxCustomGridColumnHitTest)

Description

The TcxGridColumnHeaderVertSizingEdgeHitTest class does not introduce any new functionality, but instead designates the hit code (which is equal to htColumnHeaderVertSizingEdge) of the grid view column header's vertical sizing edge which is located at the Banded Table View’s point that is being tested.  The corresponding column and View can be accessed using the Column and GridView properties, respectively.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridColumnHeaderVertSizingEdgeHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxCustomGridColumnHitTest

     |


Properties for TcxGridColumnHeaderVertSizingEdgeHitTest
TcxGridColumnHeaderVertSizingEdgeHitTest Properties

TcxGridColumnHeaderVertSizingEdgeHitTest          Legend

Derived from TcxCustomGridColumnHitTest

Column

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridColumnHeaderVertSizingEdgeHitTest
TcxGridColumnHeaderVertSizingEdgeHitTest Methods

TcxGridColumnHeaderVertSizingEdgeHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridIndicatorBandHeaderHitTest
TcxGridIndicatorBandHeaderHitTest Object

Hierarchy

The TcxGridIndicatorBandHeaderHitTest provides hit information on the inspected band header indicator area.

Unit

cxGridBandedTableView

TcxGridIndicatorBandHeaderHitTest = class(TcxGridIndicatorHitTest)

Description

A unique identifier for the band header indicator area (it is returned by the HitTestCode method).


TcxGridIndicatorBandHeaderHitTest Hierarchy
Hierarchy

TcxCustomGridViewHitTest

     |

TcxGridIndicatorHitTest

     |

TcxGridIndicatorBandHeaderHitTest


TcxGridTableCellViewInfo
TcxGridTableCellViewInfo Object

Hierarchy          Properties          Methods

Provides data for painting the cells of tabular views.

Unit

cxGridCustomTableView

TcxGridTableCellViewInfo = class(TcxCustomGridViewCellViewInfo)

Description

Instances of the TcxGridTableCellViewInfo class are passed to handlers of the OnCustomDrawGroupCell event as the parameters.  They provide all the information needed to paint a grouping row cell – the bounding rectangle, display text, row state, etc.

You should not create instances of the TcxGridTableCellViewInfo class. They are automatically created, modified and passed to event handlers.

Please refer to the ViewInfo topic for more information on ViewInfo objects.


TcxGridTableCellViewInfo Hierarchy
Hierarchy

TObject

     |

TcxCustomGridCellViewInfo

     |

TcxCustomGridViewCellViewInfo

     |


Properties for TcxGridTableCellViewInfo
TcxGridTableCellViewInfo Properties

TcxGridTableDataCellViewInfo          Legend

In TcxGridTableCellViewInfo

GridRecord

Selected

Derived from TcxCustomGridViewCellViewInfo

GridView

Derived from TcxCustomGridCellViewInfo

AlignmentHorz

AlignmentVert

BackgroundBitmap

BorderBounds

BorderColor

Borders

BorderSize

ContentBounds

ContentHeight

ContentWidth

Height

State

Text

TextAreaBounds

TextAreaHeight

TextAreaWidth

TextHeight

TextWidth

Transparent

Visible

Width


Methods for TcxGridTableCellViewInfo
TcxGridTableCellViewInfo Methods

TcxGridTableDataCellViewInfo          Legend

Derived from TcxCustomGridCellViewInfo

 GetHitTest

 Paint


TcxGridTableCellViewInfo.GridRecord

TcxGridTableDataCellViewInfo

Returns the record where the cell is displayed.

property GridRecord: TcxCustomGridRecord;

Description

Use the GridRecord property to obtain the object representing the record that holds the cell.  The property returns the TcxCustomGridRecord object which is the base for record classes.  Thus, you may need to perform typecasts to access members specific to the record type.  Please refer to the TcxCustomGridRecord class description for the list of descendants available.

The GridRecord property enables you to paint cells depending on the record where they are displayed.  For instance, you may identify a record, obtain its data within a particular cell and, thus, determine how the cell should be painted.

ReadOnly Property


TcxGridTableCellViewInfo.Selected

TcxGridTableDataCellViewInfo

Returns a value indicating whether the cell is selected.

property Selected: Boolean;

Description

The Selected property enables you to determine whether the cell currently being painted is selected.  If it is selected, the property returns True. Otherwise, False is returned..  Use this property to paint selected cells differently from non-selected cells.

ReadOnly Property


TcxGridTableDataCellViewInfo
TcxGridTableDataCellViewInfo Object

Hierarchy          Properties          Methods

Provides information required for painting data cells.

Unit

cxGridCustomTableView

TcxGridTableDataCellViewInfo = class(TcxGridTableCellViewInfo)

Description

Instances of the TcxGridTableDataCellViewInfo class are passed to handlers of the OnCustomDrawCell event of views and OnCustomDrawCell event of items.  These events enable you to paint data cells in a custom manner.  The TcxGridTableDataCellViewInfo object provides all the information needed to paint a cell.

Most of TcxGridTableDataCellViewInfo object’s functionality is implemented by its ancestor – the TcxGridTableCellViewInfo class.  The introduced properties are listed below:

•	DisplayValue - Return the cell’s display value;

•	Editing - indicates whether the cell is in edit mode;

•	Focused - indicates whether the cell is focused;

•	Style - enables you to access the style assigned to the cell;

•	Value – enables you to access the value that the current cell contains;

•	Item – returns the item to which the cell belongs;

•	Properties – A reference to the in-place editor assigned to the cell.

You do not need to create instances of the TcxGridTableDataCellViewInfo class in applications.  Such objects are automatically created, modified and passed to event handlers.


TcxGridTableDataCellViewInfo Hierarchy
Hierarchy

TObject

     |

TcxCustomGridCellViewInfo

     |

TcxCustomGridViewCellViewInfo

     |

TcxGridTableCellViewInfo

     |


Properties for TcxGridTableDataCellViewInfo
TcxGridTableDataCellViewInfo Properties

TcxGridTableDataCellViewInfo          Legend

In TcxGridTableDataCellViewInfo

DisplayValue

Editing

Focused

Item

Properties

Style

Value

Derived from TcxGridTableCellViewInfo

GridRecord

Selected

Derived from TcxCustomGridViewCellViewInfo

GridView

Derived from TcxCustomGridCellViewInfo

AlignmentHorz

AlignmentVert

BackgroundBitmap

BorderBounds

BorderColor

Borders

BorderSize

ContentBounds

ContentHeight

ContentWidth

Height

State

Text

TextAreaBounds

TextAreaHeight

TextAreaWidth

TextHeight

TextWidth

Transparent

Visible

Width


Methods for TcxGridTableDataCellViewInfo
TcxGridTableDataCellViewInfo Methods

TcxGridTableDataCellViewInfo          Legend

Derived from TcxCustomGridCellViewInfo

 GetHitTest

 Paint


TcxGridTableDataCellViewInfo.DisplayValue

TcxGridTableDataCellViewInfo

Returns the display value of the cell.

type

  TcxEditValue = Variant;

property DisplayValue: TcxEditValue;

Description

Use the DisplayValue property to obtain the text value that the cell displays if no in-place editor is assigned to that cell.  The obtained value can be painted within the cell using the DrawText method of the canvas.

If you want to obtain the dataset value corresponding to the cell, use the Value property.

ReadOnly Property


TcxGridTableDataCellViewInfo.Editing

TcxGridTableDataCellViewInfo

Indicates whether the cell is being edited.

property Editing: Boolean;

Description

Use the Editing property to determine whether a cell is in edit mode. If the property value is True then the cell is being edited, otherwise not.

If the cell is being edited at the moment, its bound editor will be displayed independently of whether custom painting is performed.  Thus, if the Editing property returns True, you don’t need to perform cell painting since it will be overridden anyway.

ReadOnly Property


TcxGridTableDataCellViewInfo.Focused

TcxGridTableDataCellViewInfo

Indicates whether the cell is focused.

property Focused: Boolean;

Description

The Focused property enables you to determine whether a cell is focused. If the property value is True, the cell is focused, otherwise False.  Use this property to provide different painting behavior for focused cells.

ReadOnly Property


TcxGridTableDataCellViewInfo.Item

TcxGridTableDataCellViewInfo

Provides access to the item which owns the cell.

property Item: TcxCustomGridTableItem;

Description

The Item property enables you to identify the item (card view row or table view column) to which the cell belongs.  This property can be used, for instance, if you need to perform cells custom painting only within specific items.  Thus, you can inspect the Item property value and perform custom painting only when its properties satisfy to some conditions.  Another way of using the Item property is painting cells with respect to settings of their owning item (e.g. cell of items whose Options.Editing property is False can be painted with a different background).

ReadOnly Property


TcxGridTableDataCellViewInfo.Properties

TcxGridTableDataCellViewInfo

A reference to the in-place editor that is bound to the cell.

property Properties: TcxCustomEditProperties;

Description

The Properties property enables you to access the properties and methods of the in-place editor assigned to a cell. This allows you to paint cells according to editor settings.

If no editor is assigned to the cell, the Properties property returns nil.

ReadOnly Property


TcxGridTableDataCellViewInfo.Style

TcxGridTableDataCellViewInfo

Provides access to the style assigned to the cell.

property Style: TcxCustomEditStyle;

Description

Use the Style property to access the style assigned to the cell. This is useful if you want to paint a part of the cell’s content in the default manner.  For instance, you may want to paint custom backgrounds for cells, but preserve their font settings.  In this case, you need to read the Font property value of the object obtained via the Style property.  This font must be assigned to the Font property of the canvas before calling the DrawText method to paint the cell text.

ReadOnly Property


TcxGridTableDataCellViewInfo.Value

TcxGridTableDataCellViewInfo

Gets the dataset value that corresponds to the cell.

property Value: Variant;

Description

The TcxGridTableDataCellViewInfo object enables you to obtain two values associated with the cell – the display value and the edit value.  The display value is the string displayed within the cell (in no specific editor is assigned to it).  This value can be obtained via the DisplayValue property.  The edit value is the dataset value corresponding to the cell and is obtained via the Value property.  Generally, these two values may differ.  Use the property that suits your needs for custom painting.

ReadOnly Property


TcxGridFilterHitTest
TcxGridFilterHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the filter panel which is located at the point being tested.

Unit

cxGridCustomTableView

TcxGridFilterHitTest = class(TcxCustomGridViewHitTest)

Description

The TcxGridFilterHitTest class does not introduce any new functionality, but instead designates the hit code (which is equal to htFilter) of the filter panel which is located at the Grid View’s point that is being tested.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridFilterHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |


Properties for TcxGridFilterHitTest
TcxGridFilterHitTest Properties

TcxGridFilterHitTest          Legend

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridFilterHitTest
TcxGridFilterHitTest Methods

TcxGridFilterHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridFilterCloseButtonHitTest
TcxGridFilterCloseButtonHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the close filter button which is located at the point being tested.

Unit

cxGridCustomTableView

TcxGridFilterCloseButtonHitTest = class(TcxCustomGridViewHitTest)

Description

The TcxGridFilterCloseButtonHitTest class does not introduce any new functionality, but instead designates the hit code (which is equal to htFilterCloseButton) of the close filter button which is located at the Grid View’s point that is being tested.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridFilterCloseButtonHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |


Properties for TcxGridFilterCloseButtonHitTest
TcxGridFilterCloseButtonHitTest Properties

TcxGridFilterCloseButtonHitTest          Legend

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridFilterCloseButtonHitTest
TcxGridFilterCloseButtonHitTest Methods

TcxGridFilterCloseButtonHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridFilterActivateButtonHitTest
TcxGridFilterActivateButtonHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the filter activation button which is located at the point being tested.

Unit

cxGridCustomTableView

TcxGridFilterActivateButtonHitTest = class(TcxCustomGridViewHitTest)

Description

The TcxGridFilterActivateButtonHitTest class does not introduce any new functionality, but instead designates the hit code (which is equal to htFilterActivateButton) of the filter activation button which is located at the Grid View’s point that is being tested.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridFilterActivateButtonHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |


Properties for TcxGridFilterActivateButtonHitTest
TcxGridFilterActivateButtonHitTest Properties

TcxGridFilterActivateButtonHitTest          Legend

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridFilterActivateButtonHitTest
TcxGridFilterActivateButtonHitTest Methods

TcxGridFilterActivateButtonHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridFilterDropDownButtonHitTest
TcxGridFilterDropDownButtonHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the filter MRU list button which is located at the point being tested.

Unit

cxGridCustomTableView

TcxGridFilterDropDownButtonHitTest = class(TcxCustomGridViewHitTest)

Description

The TcxGridFilterDropDownButtonHitTest class does not introduce any new functionality, but instead designates the hit code (which is equal to htFilterDropDownButton) of the filter MRU list button which is located at the Grid View’s point that is being tested.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridFilterDropDownButtonHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |


Properties for TcxGridFilterDropDownButtonHitTest
TcxGridFilterDropDownButtonHitTest Properties

TcxGridFilterDropDownButtonHitTest          Legend

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridFilterDropDownButtonHitTest
TcxGridFilterDropDownButtonHitTest Methods

TcxGridFilterDropDownButtonHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridFilterCustomizeButtonHitTest
TcxGridFilterCustomizeButtonHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the filter customization button which is located at the point being tested.

Unit

cxGridCustomTableView

TcxGridFilterCustomizeButtonHitTest = class(TcxCustomGridViewHitTest)

Description

The TcxGridFilterDropDownButtonHitTest class does not introduce any new functionality, but instead designates the hit code (which is equal to htFilterCustomizeButton) of the filter customization button which is located at the Grid View’s point that is being tested.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridFilterCustomizeButtonHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |


Properties for TcxGridFilterCustomizeButtonHitTest
TcxGridFilterCustomizeButtonHitTest Properties

TcxGridFilterCustomizeButtonHitTest          Legend

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridFilterCustomizeButtonHitTest
TcxGridFilterCustomizeButtonHitTest Methods

TcxGridFilterCustomizeButtonHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridExpandButtonHitTest
TcxGridExpandButtonHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the expand button which is located at the point being tested.

Unit

cxGridCustomTableView

TcxGridExpandButtonHitTest = class(TcxGridRecordHitTest)

Description

The TcxGridExpandButtonHitTest class does not introduce any new functionality, but instead designates the hit code (which is equal to htExpandButton) of the expand button (card expand button in the Card View) which is located at the Grid View’s point that is being tested.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridExpandButtonHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxGridRecordHitTest

     |


Properties for TcxGridExpandButtonHitTest
TcxGridExpandButtonHitTest Properties

TcxGridExpandButtonHitTest          Legend

Derived from TcxGridRecordHitTest

GridRecord

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridExpandButtonHitTest
TcxGridExpandButtonHitTest Methods

TcxGridExpandButtonHitTest          Legend

Derived from TcxGridRecordHitTest

CanClick

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridCustomizationFormHitTest
TcxGridCustomizationFormHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the customization form which is located at the point being tested.

Unit

cxGridCustomTableView

TcxGridCustomizationFormHitTest = class(TcxCustomGridViewHitTest)

Description

The TcxGridCustomizationFormHitTest class does not introduce any new functionality, but instead designates the hit code (which is equal to htCustomizationForm) of the customization form which is located at the Grid View’s point that is being tested.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridCustomizationFormHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |


Properties for TcxGridCustomizationFormHitTest
TcxGridCustomizationFormHitTest Properties

TcxGridCustomizationFormHitTest          Legend

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridCustomizationFormHitTest
TcxGridCustomizationFormHitTest Methods

TcxGridCustomizationFormHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


 Banded Table View Tutorial. Overview

Prev:	Next: View Creation
This tutorial describes how to create a fully functional data-aware application using ExpressQuantumGrid as a key control for displaying and accessing data.  A banded table view has much in common with the regular table view.  Therefore, this tutorial concentrates on features available only for banded table views.

Consider the CARS table that is shipped with the EQGrid demos and contains information on various cars.  This table will be connected to a banded table view within the grid control.

This tutorial covers the following topics:

1.	View Creation.  This describes how to create a grid control with a banded table view.  Creating a data source for the view and connecting the Grid control to data is also described.  Read the Connecting To Data, Working With Levels and Data Representation topics for related information.

2.	Bands And Columns.  This topic covers the creation of bands and grid columns.  To learn more about bands, see the Bands topic.  The TcxGridBand and TcxGridBandedColumn class descriptions provide additional detail.  Also, read the Banded Table View and Create And Delete Columns topics for more information on the creation and maintenance of bands and columns.

3.	Setting Up The View Look And Feel.  This topic shows how to use the view and column options to improve the look of the grid.

4.	Editors And Repository.  This topic shows how to use Express Editors as in-place editors within the EQGrid.  It provides examples of setting up cxImage, cxHyperLinkEdit and cxRadioGroup editors.  For related information, see the Data Editing Using Inplace Editors, Using Lookup Columns and TcxEditRepository topics.

5.	Styles And Style Sheets.  See how to use cxStyles and the Style Repository.  Here you will create and modify a style, assign it to a view element and change the view’s appearance by using one of the built-in StyleSheets.


Banded Table View Tutorial. Step 1: View Creation

Prev: Overview	Next: Bands And Columns

This tutorial describes how to create a fully functional data-aware application using ExpressQuantumGrid as a key control for displaying and accessing data.  We will use the grid’s banded table view to show the data.  Since the banded table view is an enhanced version of a standard table view, this tutorial will concentrate on those aspects with no equivalent in the table view.  Read the table view tutorial for more information.

This first step of the tutorial creates an ExpressQuantumGrid control with a banded table view and binds it to data.

First, create an empty application project.  Then go to the Dev Express tab of the component palette and select the cxGrid control:

Double-click it to add ExpressQuantumGrid to a form.  After the control appears, adjust its size as required.  The following screenshot demonstrates a cxGrid component placed on the form:

The Structure Navigator situated at the bottom right corner of the grid control is used for displaying and managing the grid structure.  Currently, the grid control shown above only contains one grid level (cxGrid1Level1) with an associated DB table view (cxGrid1DBTableView1).  To display the properties of the level or the table view in the Object Inspector, click the corresponding label in the Structure Navigator (alternatively, you can use the Object TreeView).  For comprehensive information on the Structure Navigator, see the Structure Navigator topic.

Since the existing view is a standard table view, for the purposes of this tutorial we need to replace it with a banded table view.  Right-click cxGrid1DBTableView1 label within the Structure Navigator and select the Delete View item from the dropdown menu:

After the table view has been removed, right-click on the cxGrid1Level1 label in the Structure Navigator and expand the Create view item displayed by the dropdown menu.  Select DB Banded Table View from the list.  Now the grid contains an empty banded view:

Sequentially select the grid control, the created view and the existing level to use the Object Inspector to set their Name properties to Grid, btvCars and lvCars respectively.

Now to create a grid data source, you should:

1.	Create a database which will be connected to the CARS table.  Place a TDatabase component [image] on a form.  Set its properties as follows:

•	DatabaseName to DemosDB

•	DriverName to STANDARD

In order to specify connection parameters for the database, double-click on the component.  In the opened Database Editor dialog click the Defaults button to obtain a list of all parameters, as well as their default values.  Set the PATH parameter to a string which defines a path to the directory where the CARS table is located.  Click the OK button to close the Database Editor dialog.

To connect the database to the table, set its Connected property to True.

2.	Activate the BDE tab of the component palette and place a TQuery component [image] on the form.  Set its properties as follows:

•	DatabaseName to DemosDB

•	Name to qryCars

•	SQL to "SELECT * from Cars".  This specifies the query which will select all the fields in the CARS table.  To set the query, click the ellipsis button in the SQL property:

This activates the editor to enter the query text so you can type the required string.

•	Active to True.  Note that the Active property must be set after all the other properties have been set.

3.	Switch to the Data Access tab of the component palette and place a TDataSource component [image] on the form and connect it to the qryCars dataset by setting its DataSet property to qryCars.  Rename the component to dsCars.

After the data source has been created and set up, it must be connected to the banded view.  Select the btvCars view within the Structure Navigator window.  The Object Inspector will display the view’s properties.

Expand the DataController property so you can edit the view’s data-aware properties.   Set the DataSource property value to DataSource1 as shown below:

At this stage, the grid will not display data, because there are no columns yet within the btvCars view.  For more detailed information on creating the grid control and binding it to data, see the Connecting To Data topic.

See the next topic for basic information on creating bands and columns.


Banded Table View Tutorial. Step 2: Bands And Columns

Prev: View Creation	Next: Editors And Repository

In the previous topic we created a grid control containing a banded view.  This view was bound to the Cars table from the DemosDB database.  Note that at this stage, the grid control does not display data:

In order to display data in a banded table view, we must create bands and columns and there are two ways to do this.

First, we will consider using the view’s Bands property.  Select the btvCars view using the Structure Navigator, go to the Object Inspector and press the ellipsis button next to the Bands property and this will enable the bands collection editor:

As you can see one band with no caption specified is already present within the btvCars view.  Select the existing band and set "General Info" as its Caption:

You can also create bands using the Component Editor.  Activate it by clicking the Customize… button within the Structure Navigator and switch to the Bands tab:

Click the Add button to create a new band.  Select it and set "Miscellaneous Info" as its Caption.  Add one more band and name it as "Engine Info":

The next step is to create columns and there are three ways to do this for a data bound view.  First, use the Structure Navigator.  Right-click on the btvCars label and choose the Create All Columns option from the dropdown menu:

The second method uses the Component Editor (invoked by right clicking on the grid). The Component Editor contains the Columns tab.  Press the Retrieve Fields button at the bottom of the page to add columns for all data source fields:

The third, and easiest method, connects the grid to the data source and creates the grid's columns from scratch.  This is the method you may want to use whenever the ExpressQuantumGrid is placed on a form, a view is designated to display the data and all the necessary data sources are created and set up.  At this point, all you have to do to connect the grid to a data source is right-click on the grid and choose the Link to <DataSource name> option from the dropdown menu as shown in the image below:

This will automatically connect the grid to the selected data source and retrieve all the fields which will be displayed as view items (columns for a (banded) table view and rows for a card view).

Once columns have been added to the view, their names appear within the list on the Columns page along with the names and indexes of the bands assigned to these columns which are called parent bands. By default, the parent band for retrieved fields is the first visible band in the view, the General Info band in this case.  In order to remove unwanted fields, select the btvCarsID, btvCarsTransmissionSpeedCount, btvCarsMPG_City, btvCarsMPG_Highway, btvCarsCyl and btvCarsDescription columns and press the Delete button or the Del key.

Next, we allocate the columns to bands.

Multi-select the btvCarsCategory, btvCarsHyperlink, btvCarsPicture and btvCarsPrice columns and invoke the Object Inspector.  Expand the Position property and select Miscellaneous Info as the BandIndex property value for the selected columns.

This moves the columns into the Miscellaneous Info band:

Allocate the btvCarsHP, btvCarsLiter and btvCarsTransmissAutomatic columns to the Engine Info band:

Now the columns can be arranged within each band.  Bands support multiple rows, thus allowing data to be arranged to make best use of the space available. To implement this, use the banded column’s Position.RowIndex property.  This property is the zero based index of the row where a banded column is placed within the band.

Select the btvCarsModel column and invoke the Object Inspector.  Set its Position.RowIndex property value to 1.  This places the column in the General Info band’s second row:

In a similar way, place the btvCarsPicture and btvCarsLiter columns into the second row of their bands and the btvCarsTransmissAutomatic column into the third row of the Engine Info band:

Properties of each column can be modified using the Component Editor and Object Inspector.  Select the btvCarsHyperlink column and use the Object Inspector to set the column’s Caption to "Official site" as shown by the following image:

Alternatively, you can select a column in the Delphi Form Designer, invoke the Object Inspector and set the column’s properties.

Give appropriate names to all columns as displayed in the following screenshot:

You can change the banded column’s properties in the same manner, even its data binding settings.  Read the TcxGridBandedColumn class description for more details.

In the same manner as we have done for the columns, bands can be nested (parent bands can be assigned to the bands). See Banded Table View for details.

See the next topic for basic use of the Express Editors within a grid view.


Banded Table View Tutorial. Step 3: Editors And Repository

Prev: Bands And Columns	Next: Setting Up The View Look And Feel

The previous topic covered the creation and arrangement of columns within bands as shown by the following screenshot:

This topic explains how to use the ExpressEditors as in-place editors within theExpressQuantumGrid.

You can assign editors to column cells in two ways:

1.	Change properties of individual columns.  This method is used in this tutorial lesson.

2.	Use of the Express Editors Repository.  The Repository allows you to assign the same editor properties to many columns at once.  See the TcxEditRepository class description and Data Editing Using Inplace Editors topic for more information.

Let us consider the first method.

Activate the Component Editor and switch to the Columns tab.  Select the btvCarsTransmissAutomatic column.  Invoke the Object Inspector and set the Properties property to RadioGroup, as shown below:

Having assigned a value (RadioGroup), the Properties group can now be expanded in the Object Inspector.  Click the ellipsis button next to the Items sub-property.  This invokes the radio group items editor:

Press the Add button to create a new radio group item.  Select this item and invoke the Object Inspector.  Set its Caption property value to "Automatic" and its Value property to Yes:

As you can see, the item appears within the btvCarsTransmissAutomatic column as a radio button:

Create another item.  Set its Caption and Value values to "Manual" and No respectively:

The new item now appears within the btvCarsTransmissAutomatic column:

Activate the Component Editor and select the btvCarsCategory column.  Use the Object Inspector and the Properties property to select RadioGroup as the btvCarsCategory column editor:

Open the radio group items editor.  Create an item and set "Sports Car" and "SPORTS" strings as the Caption and Value values respectively.  This item appears within the btvCarsCategory column:

Add another item, name it "Luxury Car" and specify "SALOON" as its Value property value.

Create a third item with "Truck" and "TRUCK" as the Caption and Value property values respectively:

Now that all category items have been created, set the Properties.Columns property of the btvCarsCategory column to 3.  This arranges the items horizontally within the radio group:

Activate the Component Editor again and select the btvCarsPicture column.  Set its Properties property value to Image.

Expand the Properties group and set the GraphicClassName property value to TJPEGImage and set the Propeties.Stretch property to True:

This modifies the image size within an editor so that the full content is displayed within the cell:

Now select the btvCarsHyperlink column.  Use the Object Inspector to assign the HyperLink editor as the Properties value:

After the cxHyperLink editor has been assigned to the btvCarsHyperLink column, the text within the column cells acts as a hyperlink (which can be double-clicked to access a remote site).

See the next topic to learn how to modify the view’s look & feel.


Banded Table View Tutorial. Step 4: Setting Up The View Look And Feel
Banded Table View Tutorial. Step 4: Setting Up The View’s Look And Feel

Prev: Editors And Repository	Next: Styles And Style Sheets

In the previous lesson, we used view options to set up its look and feel, as shown in the following image:

This tutorial topic explains how to modify view and column options to make the grid look better.

Let us customize the look & feel settings of the btvCars view.

As you can see, images within the btvCarsPicture column are too small.  A banded view has a nice feature to prevent such problems - variable column height.

Click the bottom edge of the Picture column header and drag it down.  This changes the number of rows occupied by the column cell.  Change the height of the Picture column so that it occupies 3 rows:

Now you can see that there is unused space in other column headers (in dark gray). Change the height of the Model and Gear Box columns to fill the space.

The column height can also be specified by the Position.LineCount property value.

Change the width of all columns to display complete column values.  This will mean that you have to use the horizontal scrollbar to access all the columns.  However, the banded table view provides a fixed band feature, thus allowing you to prevent the important columns from scrolling.

Activate the Component Editor, switch to the Bands tab and select the General Info band.  Use the Object Inspector and set the FixedKind property of the General Info band to fkLeft.

This fixes the General Info band to the left side of the btvCars view.  Note that the General Info band is no longer involved in view scrolling:

Now select the Engine Info band and set its FixedKind property to fkRight.  This fixes the Engine Info band to the right side of the view:

Now we will provide a better visual separation of grid rows one from another.  Select the btvCars view and expand the OptionsView group within the Object Inspector.  Set the RowSeparatorWidth property value to 5:

This enlarges the empty space between the rows:

The resulting view is displayed below:

ExpressQuantumGrid has a lot of options, affecting almost every aspect of the control’s appearance and functionality.  For more information on the different options available, see the ExpressQuantumGrid reference section in this help system.

See the next topic showing how to use styles and the Style Repository.


Banded Table View Tutorial. Step 5: Styles And Style Sheets

Prev: Setting Up The View Look And Feel

The previous topic showed how to modify view settings to make it look better, as shown below:

This topic demonstrates how to modify the grid’s appearance using styles and the Styles Repository.

Go to the Dev Express tab of the component palette and drop a cxStyleRepository control on the form:

The Style Repository editor allows you to create and manage styles.  Double-click the cxStyleRepository component on the form.  This invokes the editing dialog.  Activate the Styles page and click the Add button.  This creates a new style as shown below:

Give the created style an appropriate name, for instance, BandHeaderStyle.  Now you need to set up the style properties:

•	Set $00C56A31 as the Style.Color value.

•	Set Style.TextColor to clWhite.

•	Expand the Style.Font property and set the font style to fsBold.

After the style has been created, it can be assigned to a grid element.  Select the grid view using the Structure Navigator or the Component Editor.  Expand the Styles property.  Select the Styles.BandHeader property and use its combo to assign BandHeaderStyle to column headers:

The result is shown in the following screenshot:

You can create and assign styles in this way for every grid element, but there is a more convenient way to change the grid’s appearance by using style sheets.

A Style sheet is a set of styles for a particular view type.  There are three types of style sheet: table view style sheet, banded table view style sheet and card view style sheet.  All style sheets can be created and edited using the Style Sheets tab of the Style Repository Editor:

The Style Repository also provides a set of predefined color schemes for each view type.  To use the predefined style sheets, follow the instructions below:

•	Activate the Style Repository Editor.  Switch to the Style Sheets tab.

•	Click the Predefined… button.  This invokes the Predefined StyleSheets dialog.

•	Use the Style Sheet Class combo to select the type of the required style sheet. In this case, we need the TcxGridBandedTableViewStyleSheet entry:

•	Select the DevExpress style sheet from the list located under the Style Sheet Class combo box.  The following screenshot shows this color scheme applied to the sample grid in the preview panel.

•	Press the Load button at the bottom of the dialog.

After the required style sheet is loaded into the editor, you can access and override individual style settings.  Switch to the Styles tab of the Style Repository Editor.  Select the desired style and modify as required.

Next, we will assign the DevExpess style sheet to a banded table view.  Select the btvCars view using the Structure Navigator or the Component Editor.  Expand the Styles property and select the new style sheet via the combo box belonging to the StyleSheet property.  You will see that styles of all the grid elements have been assigned and these style settings can be edited using the Object Inspector.

The grid control reflects these changes:

For comprehensive information on the Style Repository and its usage, see the Style Repository topic in this help system.


Card View Tutorial. Overview

Prev:	Next: View Creation
This tutorial describes how to create a fully functional data-aware application using ExpressQuantumGrid as a key control for displaying and accessing data.

Consider the CARS table that is shipped with the EQGrid demos and contains information on various cars.  This table will be connected to a card view within the grid control.

This tutorial covers the following topics:

1.	View Creation.  This topic describes how to create a grid control with a card view.  Creating a data source for the view and connecting the Grid control to data is also demonstrated.  Read the Connecting To Data, Working With Levels, Data Representation topics for related information.

2.	Card View Rows.  This topic contains information on grid columns creation.  The TcxGridCardVIewRow class description provides you with additional knowledge.  Read the Create And Delete Columns topic for more information on columns and creating card view rows.

3.	Setting Up The View Look And Feel.  This topic explains how to use the view and column options to make the grid data display look better.

4.	Editors And Repository.  This topic gives the basic information about using the ExpressEditors as in-place editors within EQGrid.  It provides examples of setting up cxCheckBox and cxBlobEdit editors.  For related information see the Data Editing Using Inplace Editors, Using Lookup Columns and TcxEditRepository topics.

5.	Styles And Style Sheets.  This topic provides information on using the cxStyles and Style Repository.  Here you will create and setup a style, assign to a view element and change the view’s appearance by using one of the built-in StyleSheets.


Card View Tutorial. Step 1: View Creation

Prev: Overview	Next: Card View Rows
Topics in this tutorial describe how to create a fully functional data-aware application using ExpressQuantumGrid.  This control is used together with card view data representation to display and access data.

This topic explains how to create an ExpressQuantumGrid control with card view data representation and bind it to data.

First, create an empty application project.  Then go to the Dev Express tab of the component palette and select the cxGrid control:

Double-click it to add an ExpressQuantumGrid to the form.  After the control appears, adjust its size as required.  The following screenshot demonstrates a cxGrid component placed on the form:

The Structure Navigator situated at the bottom right part of the grid control is used for displaying and managing the grid structure.  Currently, the grid control shown above contains only one grid level (cxGrid1Level) with an associated DB table view (cxGrid1DBTableView1).  To display the properties of the level or the table view in the Object Inspector, click on the corresponding label in the Structure Navigator (alternatively, you can use the Object TreeView).  For detailed information on the Structure Navigator, see the Structure Navigator topic.

Since the existing view is a table view, we need to replace it with a card view.  Right-click the table view box within the Structure Navigator and select the Delete View item within the dropdown menu:

After the table view has been removed, right-click the level box within the Structure Navigator and expand the Create view item within the dropdown menu.  Select DB Card View from the list.  Now the grid contains an empty card view:

Sequentially select the grid control, the created view and the existing level to use the Object Inspector to set their Name properties to Grid, cvCars and lvCars respectively.

Now to create a grid data source, you should:

1.	Create a database which will be connected to the CARS table.  Place a TDatabase component [image] on a form.  Set its properties as follows:

•	DatabaseName to DemosDB

•	DriverName to STANDARD

In order to specify connection parameters for the database, double-click on the component.  In the opened Database Editor dialog click the Defaults button to obtain a list of all parameters, as well as their default values.  Set the PATH parameter to a string which defines a path to the directory where the CARS table is located.  Click the OK button to close the Database Editor dialog.

To connect the database to the table, set its Connected property to True.

2.	Activate the BDE tab of the component palette and place a TQuery component [image] on the form.  Set its properties as follows:

•	DatabaseName to DemosDB

•	Name to qryCars

•	SQL to "SELECT * from Cars".  This specifies the query which will select all the fields in the CARS table.  To set the query, click the ellipsis button in the SQL property:

This activates the editor to enter the query text so you can type the required string.

•	Active to True.  Note that the Active property must be set after all the other properties have been set.

3.	Switch to the Data Access tab of the component palette and place a TDataSource component [image] on the form and connect it to the qryCars dataset by setting its DataSet property to qryCars.  Rename the component to dsCars.

After the data source has been created and set up, it must be connected to the appropriate view.  Select the cvCars view within the Structure Navigator window.  The Object Inspector will display the view properties.

Expand the DataController property.  It allows editing of the data-aware properties of a view.   Use the combo box near the DataSource property to choose the TDataSource instance as a view data source:

Currently, the grid will not display any data, because there are no card view rows created yet for the cvCars view.  For more detailed information on creating the grid control and binding it to data, see the Connecting To Data topic.

See the next topic for information on card view rows creation.


Card View Tutorial. Step 2: Card View Rows

Prev: View Creation	Next: Setting Up The View Look And Feel

In the previous topic, we created a grid control containing a card view.  This view was bound to the Cars table from the DemosDB database.  Note that the grid control does not display any data yet:

The next step is the creation of card view rows.  There are three ways of creating card view rows for data bound views.  The first is to use the Structure Navigator.  Right-click on the cvCars label and choose the Create All Rows option from the dropdown menu:

The second method of creating rows is to use the Component Editor.  This is activated by clicking on the Customize… button of the Structure Navigator.  The Component Editor contains a Card rows tab on the right.  Press the Retrieve Fields button at the bottom of the page to add card view rows for all data source fields:

The third, and easiest method, connects the grid to the data source and creates the grid's rows from scratch.  This is the method you may want to use whenever the ExpressQuantumGrid is placed onto a form, a view is designated to display the data and all the necessary data sources are created and set up.  At this point, all you have to do to connect the grid to a data source is right-click on the grid and choose the Link to <DataSource name> option from the dropdown menu as shown in the image below:

This will automatically connect the grid to the selected data source and retrieve all the fields which will be displayed as view items (columns for a (banded) table view and rows for a card view).

Once card view rows are added to the view, their names appear within the list on the Card rows Designer page.  Select the cvCarsID, cvCarsLiter, cvCarsCyl, cvCarsTransmissionSpeedCount, cvCarsMPG_City, cvCarsMPG_Highway, cvCarsCategory and cvCarsHyperlink rows and press the Delete button or the Del key.  This removes the selected rows from the view:

The following screenshots demonstrate how the grid control looks before:

and after removing rows:

Note, that after reducing the number of fields displayed, two records (cards) occupy the vertical space.

Properties of each card view row can be modified using the Component Editor and the Object Inspector.  Select the cvCarsTransmissAutomatic row and change its caption to "Automatic Transmission".

Multi-select the cvCarsTrademark and the cvCarsModel rows and access their Kind property using the Object Inspector.  Set this property value to rkCaption.  The following image demonstrates the result:

Similarly, you can change any of the card view row properties, even the data binding settings of a row.  See the TcxGridCardViewRow class description for details on the card view row settings.

See the next topic for a snapshot of the view options setup.


Card View Tutorial. Step 3: Setting Up The View Look And Feel

Prev: Card View Rows	Next: Editors And Repository

The previous topic finished with the card view rows creation.  The result is demonstrated on the following screenshot:

This topic explains how to use the view and card row options to improve the look of the ExpressQuantumGrid display.  A quick overview of the complete set of options is given in the Options topic.

When a specific view is selected within the Structure Navigator or the Component Editor, all corresponding options can be accessed via the Object Inspector.

Let’s customize the look & feel settings of the cvCars view.  Select the cvCars view using the Structure Navigator and set the LayoutDirection property value to ldVertical (for the purpose of the following screenshots, we have added the ID field to the view):

Note the order of the records (illustrated by the ID values) and see the result of switching to vertical layout direction:

Expand the OptionsView group within the Object Inspector and set CellAutoHeight to True:

The result is shown below:

As you can see, the Description card row values are too large to be displayed properly.  This can be fixed by setting the OptionsView.CellTextMaxLineCount property value.  Set it to 2 and the CellEndEllipsis property to True:

The result is shown below:

ExpressQuantumGrid has many options, affecting almost every aspect of the control’s functionality.  For more information on the different options, see the TcxGridCardView and TcxGridCardViewRowOptions reference sections.

See the next topic for the base information on the Express Editors usage.


Card View Tutorial. Step 4: Editors And Repository

Prev: Setting Up The View Look And Feel	Next: Styles And Style Sheets

In the previous lesson, we set up the view’s look & feel using the view options.  The result is demonstrated in the following image:

This topic explains how to use the ExpressEditors as in-place editors within the ExpressQuantumGrid.

You can assign editors to card row cells in two ways:

1.	Change the properties of individual card rows.  This method is described in the following tutorial lesson.

2.	Using the ExpressEditors Repository.  Another method of assigning editors to grid cells is by using the Editors Repository.  This supports the assignment of editor properties to many card rows.  See the TcxEditRepository class description and the Data Editing Using Inplace Editors topic for more information.

Let’s consider the first method.

Activate the Component Editor, switch to the Card rows tab and select the cvCarsTransmissAutomatic row.  Invoke the Object Inspector and use the combo box for the Properties property.  Select CheckBox from the dropdown list:

Expand the Properties group and set the Properties.ValueChecked property value to Yes and the Properties.ValueUnchecked property value to No.  The result is shown in the image below:

Activate the Component Editor again and select the cvCarsDescription row.  Set the Properties property value to BlobEdit:

Expand the Properties group and set the Properties.BlobPaintStyle property to bpsText and the Propeties.MemoScrollBars property to ssVertical:

Run the application and invoke the editor dropdown of the Description row to display the entire cell value:

Now we will assign an appropriate editor to the Picture row:

•	Select the row and set its Properties property to BlobEdit.

•	Expand the Properties property and set the Properties.BlobEditKind property to the bekPict value.

•	Set the Properties.PictureGraphicClassName property value to TJPEGImage.

The result is shown in the following screenshot:

See the next topic for details on improving the grid’s appearance.


Card View Tutorial. Step 5: Styles And Style Sheets

Prev: Editor And Repository	Next:

The previous topic explained how to assign editors to grid cells’ contents.  The result of all the actions performed is shown below:

This topic now demonstrates how to improve the grid’s appearance using styles and the Styles Repository.

Go to the Dev Express tab of the component palette and drop a cxStyleRepository control on the form:

Using the Style Repository, you can create and manage styles.  Double-click the cxStyleRepository component on the form to invoke the editing dialog.  Activate the Styles page and click the Add button to create a new style, as displayed below:

Note that the style has been renamed to CaptionRowStyle.  Now you need to set up the other style properties:

•	Enter 0x00C56A31 as the Style.Color property value.

•	Set the Style.TextColor property value to clWhite.

•	Expand the Style.Font property and set its font style to fsBold.

After the style has been created and set up, it can be assigned to a grid element.  Select the grid view using the Structure Navigator or the Component Editor.  Expand the Styles property.  Select the Styles.CaptionRow property and use the corresponding combo to assign the CaptionRowStyle to the card row headers.  The result is shown in the following screenshot:

You can create and assign styles in the same way for every grid element.  But there is another easier way to manipulate grid appearance – by using style sheets.

A Style sheet is a set of styles designed for a specific view type.  There are three types of style sheets: table view style sheet, banded table view style sheet and the card view style sheet.  All these style sheets can be created and edited using the Style Sheets tab of the Style Repository Editor:

The Style Repository also provides a set of predefined color schemes for each view type.  To use predefined style sheets, follow the instructions below:

•	Activate the Style Repository Editor.  Switch to the Style Sheets tab.

•	Click the Predefined… button to invoke the Predefined StyleSheets dialog.

•	Use the Style Sheet Class combo to select the type of the required style sheet – TcxGridCardViewStyleSheet in this case:

•	Select the DevExpress style sheet from the list below the Style Sheet Class combo box.  Watch the preview box at the right side of the dialog as it reflects the results of applying this color scheme to a sample grid.

•	Press the Load button at the bottom of the dialog.

After the required style sheet has been loaded into the editor, you can access and override individual styles within it.  Switch to the Styles tab of the Style Repository Editor.  Select the desired style and modify its settings as described above.

Now we will assign the DevExpess style sheet to a card view.  Select the cvCars view using the Structure Navigator or the Component Editor.  Expand the Styles property and select the style sheet just created using the combo box near the StyleSheet property.  Note that all grid element styles have been assigned and styles settings can now be edited using the Object Inspector.

The grid control reflects the changes immediately:

For comprehensive info about the Style Repository and its usage, see the Style Repository topic.


Master-Detail Tutorial. Overview

Prev:	Next: Connecting to Data

This tutorial covers the steps required to display data from several tables within a single TcxGrid control.  EQGrid lets you display master-detail relationships between tables.  You are also able to display data from independent tables and this is also demonstrated in this tutorial.

Consider the FILMS, FILMSPERSONSSTAFF, FILMSSCREENS and PERSONS tables that are shipped with the EQGrid demos and contain various data on the films in our collection.

The FILMS table contains information on films in the catalog and such fields as CAPTION, YEAR, PHOTO, TAGLINE, ID and others.  ID is the key field name uniquely identifying each record in the table.

The FILMSPERSONSSTAFF table describes people involved in film production.  It also has an ID field uniquely identifying records in this table.  Other fields are PERSONID, PERSONLINEID, DESCRIPTION and FILMID.  FILMID denotes a value of the ID field from the FILMS table.  It associates each record in the FILMSPERSONSSTAFF table with a specific film from the FILMS table.  Thus a master-detail relationship can be established between these tables in which FILMS is a master table and FILMSPERSONSSTAFF is a detail table.

A similar master-detail relationship can be set up between the FILMS and FILMSSCREENS tables.  The latter provides images associated with films.  It contains the following fields: ID (unique key field), FILMID (addresses a film from the FILMS table) and SCREEN (a BLOB field containing an image).

The PERSONS table represents information on the people in our video catalog.  It does not contain any dependent fields and we want this table to be displayed in the same grid control.

The following screenshot shows the resultant grid control after you complete this tutorial.  The independent FILMS and PERSONS tables are displayed at the root hierarchy level.  You can access them via the Films and Persons tabs respectively:

Two detail tables (FILMSPERSONSSTAFF and FILMSSCREENS) are associated with the FILMS table.  You can switch between them via the Staff and Film Screens tabs.


Master-Detail Tutorial. Step 1: Connecting to Data

Prev: Overview	Next: The Level and View Structure

In this section, a connection to the FILMS, FILMSPERSONSSTAFF, FILMSSCREENS and PERSONS tables is created.  Each table requires TDataSet (TTable, in our case) and TDataSource components to be created.  You can refer to the Connecting to Data document providing more details on this task.  This section describes the steps required to create data-aware components and set their attributes as appropriate.

1.	Create an empty application project.

2.	Create a database which will be connected to the tables.  Place a TDatabase component [image] on a form.  Set its properties as follows:

•	DatabaseName to DemosDB

•	DriverName to STANDARD

•	Name to Database

In order to specify connection parameters for the database, double-click on the component.  In the opened Database Editor dialog click the Defaults button to obtain a list of all parameters, as well as their default values.  Set the PATH parameter to a string which defines a path to the directory where the FILMS, FILMSPERSONSSTAFF, FILMSSCREENS and PERSONS tables are located.  Click the OK button to close the Database Editor dialog.

To connect the database to the tables, set its Connected property to True.

3.	Place a TTable component [image] onto the form.  This table will represent the FILMS table from the DemosDB database.  Set its properties as follows:

•	DatabaseName to DemosDB

•	Name to tblFilms

•	TableName to FILMS.DB

•	Active to True.  Note that the Active property must be set after all other properties are specified.

4.	Add a new TTable component on the form.  Set its properties to the following values:

•	DatabaseName to DemosDB

•	Name to tblStaff

•	TableName to FILMSPERSONSSTAFF.DB

•	the Active property to True.

5.	Place another new TTable component on the form.  Set its properties as follows:

•	DatabaseName to DemosDB

•	Name to tblFilmScreens

•	TableName to FILMSSCREENS.DB

•	Active to True.

6.	Place a further new TTable component on the form.  Set its properties to the following values:

•	DatabaseName to DemosDB

•	Name to tblPersons

•	TableName to PERSONS.DB

•	Active to True.

7.	Place a TDataSource component [image] on the form which will connect to the tblFilms dataset.  Set the Name property to dsFilms and the DataSet property to tblFilms.

8.	Place another three TDataSource components to connect to the other tables.  Specify their names as dsStaff, dsFilmScreens and dsPersons and set their DataSet properties to tblFilms, tblStaff, tblFilmScreens and tblPersons respectively.


Master-Detail Tutorial. Step 2: Level Structure

Prev: Connecting to Data	Next: Connecting Views to Data

To represent data from a single dataset within EQGrid, you need to create a level-view pair.  Grid levels are destined to create a hierarchical structure of data.  Each level is bound to a view and this displays data in a form.  Refer to the Data Representation topic for more information.

This section shows the creation of level-view pairs to represent four datasets.  EQGrid provides the Structure Navigator to facilitate the creation of levels and views.

1.	Place a TcxGrid [image] control onto the form.  The grid by default contains one level-view pair (cxGrid1Level1-cxGrid1DBTableView1):

This view will display data from the master FILMS table.  Click the left mouse button on the cxGrid1Level1 box in the Structure Navigator so as to display its properties in the Object Inspector.

Rename cxGrid1Level1 to lvFilms using the Object Inspector.  Similarly, rename cxGrid1DBTableView1 to tvFilms.

2.	Click the right mouse button on the lvFilms box to display the popup menu.  Then select the Add Level option.

This adds a child grid level and this will represent data from the FILMSPERSONSSTAFF table.  Set the name of the new level to lvStaff as described above.

Right-click the lvStaff box and select the Create View->DB Table option.

Now the lvStaff level is associated with a data-aware view and this will display data from the FILMSPERSONSSTAFF table.  Set the name of the new view to tvStaff.

3.	Click the right mouse button on the lvFilms box again and add another level to display data from the FILMSSCREENS table.  Rename the grid level to lvFilmScreens.  Then associate a card view with the level by selecting the Create View->DB Card View option from the level’s popup menu.

The newly created view should be renamed to cvFilmScreens.

4.	We want the PERSONS table to be displayed at the same hierarchy level as the FILMS table, i.e. at the ‘root’ hierarchy level.  To add a level-view pair at the root, right-click the cxGrid1 box and select the Add Level menu item.

Next, associate a new data-aware view with it as shown in the previous section.  Set the names for the new level and view to lvPersons and tvPersons respectively. Note that we are using a convention where table views and card views have prefixes ‘tv’ and ‘cv’ respectively (this is not mandatory though).

Finally, your grid will look like:


Master-Detail Tutorial. Step 3: Connecting Views to Data

Prev: The Level and View Structure	Next: Setting Up Master-Detail Relationships
This section shows how to connect views to datasets.  To represent particular data fields, we will create items (columns in a table view and rows in a card view).

This section also shows how to display tabs for root and nested levels of the hierarchy.  We need to provide tabs for switching between the root tvFilms and tvPersons views and between the detail tvStaff and cvFilmScreens views.

1.	Display the properties of the tvFilms view in the Object Inspector.  Expand the DataController property and set its DataSource attribute to dsFilms.

In a similar way, set the DataController.DataSource property of the tvStaff, cvFilmScreens and tvPersons views to dsStaff, dsFilmScreens and dsPersons respectively.

2.	For views to display data, you need to create columns (or rows in a card view).  The easiest way to create columns in data-aware views is to right-click the view’s box in the Structure Navigator and select the Create All Columns option.

Perform this operation for each table view (tvFilms, tvStaff, tvPersons).

For a card view, we will create a column manually via the Component Editor:

•	Double-click the grid control to open the Component Editor.

•	Select the cvFilmScreens box on the Structure panel:

•	Click the Add button on the Rows panel.  This will add a new card row.

•	The Object Inspector should now display the properties of the new row.  If not, select the row on the Rows panel.  Using the Object Inspector, set the row’s DataBinding.FieldName property to SCREEN.

Now you can see the grid control currently displaying the data from the FILMS table via the tvFilms view.

Expanding master rows will do nothing, as we have not established a master-detail relationship at the table level yet (this is described below).  Also, you cannot see the tvPersons view.

3.	Enable the tabs used to switch between views at the same hierarchy level (tvFilms-tvPersons and tvStaff-cvFilmScreens).

•	To activate tabs at the root hierarchy level, set the grid’s RootLevelOptions.DetailTabsPosition property to dtpTop, for instance.

•	You also need to activate tabs for the details of the lvFilms level.  You can do this by setting the Options.DetailTabsPosition property of the lvFilms level to dtpTop.

•	Additionally, you need to specify the captions to be displayed on the tabs for each grid level (lvFilms, lvPersons, lvStaff and lvFilmScreens).  Display the properties of the lvFilms level in the Object Inspector and set its Caption property to ‘Films’.

Similarly, set the Caption properties of the other three levels to ‘Persons’, ‘Staff’ and ‘Film Screens’ respectively.  In the following image, you can see the tabs for the Films and Persons levels:

Now you are able to switch to the tvPersons view.


Master-Detail Tutorial. Step 4: Setting Up Master-Detail Relationships

Prev: Connecting Views to Data	Next: Specifying Editors for Items

Two master-detail relationships must be set up.  The first one is between the master FILMS and detail STAFF tables.  The second one is between the master FILMS and detail FILMSSCREENS tables.

1.	For the first relationship, you need to adjust the properties of the tvStaff view.  Open the Object Inspector and set the attributes as follows:

•	DataController.DetailKeyFieldNames to FILMID

•	DataController.KeyFieldNames to ID

•	DataController.MasterkeyFieldNames to ID

DetailKeyFieldNames specifies the field(s) from the detail tvStaff view.  The MasterkeyFieldNames property specifies the field(s) from the master tvFilms view.  Detail key fields must correspond to master key fields.  The KeyFieldNames property specifies the field(s) in the detail view uniquely identifying each record.  Refer to its description for more information.

2.	For the second relationship, set the properties of the cvFilmScreens view as described for the tvStaff view:

•	DataController.DetailKeyFieldNames to FILMID

•	DataController.KeyFieldNames to ID

•	DataController.MasterkeyFieldNames to ID

3.	The datasets displayed in detail views must be sorted against fields addressed by the DataController.DetailKeyFieldNames property.  This is necessary for the detail data controller to be able to correctly retrieve all the necessary records from it.  To sort data in the tblStaff and tblFilmScreens tables, set their IndexFieldNames properties to FILMID.

All the properties affecting master-detail relationships have been set and you can now run the program.  The following steps refine the application by specifying editors for particular columns/card rows, customizing the view’s layouts, and by improving the appearance of the grid.


Master-Detail Tutorial. Step 5: Specifying Editors for Items

Prev: Setting Up Master-Detail Relationships	Next: Customizing Views

Assigning editors to items allows the end-user to edit dataset fields in a more convenient way.  In this section, editors are assigned to three items:

•	a radio group (TcxRadioGroup) is assigned to the GENDER column in the tvPersons view

•	a lookup editor (TcxLookupComboBox) is assigned to the PERSONID column in the tvStaff view

•	an image editor (TcxImage) is assigned to the SCREEN row in the cvFilmScreens view

To assign editors to items in this tutorial, use the Properties property.

Note: to specify the editor via code, you should use the PropertiesClass property as well.  Refer to the Data Editing Using Inplace Editors section for details.

1.	Activate the Component Editor and click the tvPersons box on the Structure panel and this displays the view’s columns on the right.  Select the tvPersonsGENDER item (the name for the GENDER column) in the list and switch to the Object Inspector and this should now display the properties of the item.

Set the column’s Properties property to RadioGroup by selecting the corresponding value from the dropdown list:

Now expand the Properties property and click the ellipsis button in the Items value box.  This opens a standard collection editor where we can now add items:

Add two items by clicking the [image] button twice.  Items will be used to represent the male or female sex of a person.  Set the Caption property of the first item to Male and the Value property to True.

For the second item, set the Caption property to Female and the Value property to False.

The following image shows a cell from the GENDER column with a radio group specified as an editor:

2.	The tvStaffPERSONID column contains numerical identifiers of persons from the PERSONS table.  It corresponds to the ID column from this table, thus allowing you to specify the lookup combo box as an editor.  Instead of the person identifier, the editor will display the person’s name in the edit box.  The dropdown window of the lookup will display the first and the second name of the person.

Display the properties of the tvStaffPERSONID column of the tvStaff view in the Object Inspector as shown above.  Set its Properties property to LookupComboBox.  Then set the attributes of the Properties object as follows:

•	ListSource to dsPersons

This sets the source of records displayed in the dropdown and in the edit box of the lookup combo box.

•	ListFieldNames to the FIRSTNAME;SECONDNAME string

The ListFieldNames property identifies fields displayed in the dropdown of the lookup editor.

•	KeyFieldNames to ID

The KeyFieldNames property specifies the field(s) used to identify records from ListSource.  The values of this field must match the values of the current column (tvStaffPERSONID).

•	DropDownWidth to 200

This sets the width of the dropdown window.

•	ListFieldIndex to 1

The ListFieldIndex addresses the column in the dropdown to display in the edit box.  The value of the property defines a zero-based index of a field within the ListFieldNames list.  ListFieldIndex is set to 1 and so addresses the SECONDNAME field.

The following image shows a lookup editor assigned to the tvStaffPERSONID column:

3.	For the SCREEN item of the cvFilmScreens view, set its Properties property to Image.  Then set the item’s properties to the following values:

•	Properties.GraphicClassName to TJPEGImage

Graphics provided by the dataset field are interpreted as JPEG images.

•	Properties.Stretch to True

This stretches the image to accommodate the size of cells.


Master-Detail Tutorial. Step 6: Customizing Views

Prev: Specifying Editors for Items	Next:

This section describes the steps required to customize the layout and the appearance of views.

1.	Set the MaxDetailHeight property of the master lvFilms level to 200 in order to limit the height of the detail views (tvStaff and cvFilmScreens)

The result is shown below:

2.	For the tvFilms view, hide the tvFilmsID, tvFilmsPLOTOUTLINE, tvFilmsCOLOR, tvFilmsPHOTO, tvFilmsICON and tvFilmsWEBSITE columns by setting their Visible property to False.

3.	Similarly, hide the tvStaffID, tvStaffFilmID and tvStaffPERSONLINEID columns in the tvStaff view.

4.	Hide the following columns for the tvPersons view: tvPersonsID, tvPersonsBIRTHCOUNTRY, tvPersonsLOCATIONOFBIRTH, tvPersonsBIRTHNAME, tvPersonsNICKNAME and tvPersonsHOMEPAGE.

5.	In order to display the TAGLINE field in the preview section, set the properties of the tvFilms view to the following values:

•	Preview.Column to tvFilmsTAGLINE

•	Preview.Visible to True

The preview section in the following image is displayed in blue. Notice how it spans regular columns.

6.	Set the Options.ShowCaption property of the SCREEN card row in the cvFilmScreens view to False.

This hides the caption of the row:

7.	Set the OptionsView.CellAutoHeight property of the cvFilmScreens view to True.

This changes the size of view rows to fully display their contents.

8.	Change the width of columns depending on your needs.  You can do this in a number of ways:

•	set the column’s Width property via the Object Inspector

•	drag the column’s right edge.  See the note below.

•	double-click the column’s right edge to set the width according to the contents of the column’s cells.  See the note below.

Note: At design time, you cannot specify the layout of detail views by moving/resizing their columns right on the form.  Details on screen are represented by a number of clones created based on the pattern view (in our example, the tvStaff and cvFilmScreens views are patterns).  Expanding a specific master row in a master view (tvFilms) opens a detail clone created based upon the settings of the detail pattern view.  So changing settings of a particular detail clone at design time is in no effect since clones will be recreated at runtime and any changes will be discarded.  For detail views, you have to use the Layout Editor.  See the View Layout section for more information.

9.	Create style sheets for table and card views based on the predefined DevExpress color scheme and assign them to the views (tvFilms, tvStaff, cvFilmScreens and tvPersons).  Refer to the Styles and Style Sheets sections of the Table View and Card View tutorialsI for more information.

The following images show the result of view customizations.

You can click the ‘+’ button of a master row in the tvFilms table view to access the detail tvStaff and tvFilmScreens views.  To switch between the views, use the corresponding tabs (Staff and Film Screens).  You can see that detail views display information related to the selected master row.

To access the tvPersons view, click the Persons tab at the root level.  It displays records from the PERSONS table.  The data of the PERSONS table is independent of data from other tables used in this tutorial.


Table View Tutorial. Overview

Prev:	Next: View Creation
This tutorial describes how to create a fully functional data-aware application using ExpressQuantumGrid as a key control for displaying and accessing data.

Consider the FILMS, FILMSPERSONSSTAFF, FILMSSCREENS and PERSONS tables that are shipped with the EQGrid demos and contain various data on the films in our collection.  We shall use only the FILMS table.  This table will be connected to a TableView within the grid control.

The tutorial covers the following topics:

1.	View Creation.  This topic describes how to create a grid control with a TableView.  Creating a data source for the View and connecting the Grid control to data is also covered.  Read the Connecting To Data, Working With Levels, Data Representation topics for related information.

2.	Columns Creation.  This topic contains information on the creation of grid columns.  The TcxGridColumn class description provides additional detail.  Read the Create And Delete Columns topic for more information on creating columns.

3.	Setting Up The View Look And Feel.  This topic explains how to use the View and column options to improve the grid data display.

4.	Editors And Repository.  This topic covers basic information about using the Express Editors as in-place editors within EQGrid.  It provides examples of setting up cxImage and cxRadioGroup editors.  For related information, see the Data Editing Using Inplace Editors, Using Lookup Columns and TcxEditRepository topics.

5.	Styles And Style Sheets.  This topic shows how to use the cxStyles and Style Repository.  Here you will create and setup a style, assign it to a view element and change the View’s appearance by using one of the built-in StyleSheets.

6.	Preview Creation.  This topic provides information about the preview section.

7.	Footer Summary Creation.  Footer summaries are calculated against column values and are displayed within the footer panel.

8.	Group Summary Creation.  Group summaries are calculated against grouped records and are displayed either within group footers or grouping rows.

9.	Summary Group Creation.  A summary group is a collection of group summaries displayed when a view is grouped by the appropriate column.

For more information on different types of summaries and their creation and set up, see the Summaries, Creating Summaries and Create Custom Summaries topics.


Table View Tutorial. Step 1: View Creation

Prev: Overview	Next: Columns Creation
This topic explains how to create an ExpressQuantumGrid control using a table view and shows how to bind it to data.

First, create an empty application project.  Then go to the Dev Express tab of the component palette and select the cxGrid control:

Double-click it to add the ExpressQuantumGrid to a form.  After the control appears, adjust its size as required.  The following screenshot demonstrates a form with a cxGrid component on it:

The Structure Navigator located at the bottom right part of the grid control is used for displaying and managing the grid structure.  Currently, the grid control shown above only contains one grid level (cxGrid1Level1) with an associated DB table view (cxGrid1DBTableView1).  To display the properties of a level or a table view in the Object Inspector, click on the corresponding label in the Structure Navigator (alternatively, you can use the Object TreeView).  For comprehensive information on the Structure Navigator, see the Structure Navigator topic.

Select the cxGrid1 component and rename it to Grid.  Next, use the Structure Navigator to name the level and view to lvFilms and tvFilms:

Now to create a grid data source, you should:

1.	Create a database which will be connected to the FILMS table.  Place a TDatabase component [image] on a form.  Set its properties as follows:

•	DatabaseName to DemosDB

•	DriverName to STANDARD

In order to specify connection parameters for the database, double-click on the component.  In the opened Database Editor dialog click the Defaults button to obtain a list of all parameters, as well as their default values.  Set the PATH parameter to a string which defines a path to the directory where the FILMS table is located.  Click the OK button to close the Database Editor dialog.

To connect the database to the table, set its Connected property to True.

2.	Activate the BDE tab of the component palette and place a TQuery component [image] on the form.  Set its properties as follows:

•	DatabaseName to DemosDB

•	Name to qryFilms

•	SQL to "SELECT * from Films".  This specifies the query which will select all the fields in the FILMS table.  To set the query, click the ellipsis button in the SQL property:

This activates the editor to enter the query text so you can type the required string.

•	Active to True.  Note that the Active property must be set after all the other properties have been set.

3.	Switch to the Data Access tab of the component palette and place a TDataSource component [image] on the form and connect it to the qryFilms dataset by setting its DataSet property to qryFilms.

After the data source has been created and set up, it must be connected to the grid’s view.  Select the tvFilms view from within the Structure Navigator window.  The Object Inspector will display the view’s properties.

Expand the DataController property.  It controls editing of the view’s data-aware properties.  Set the DataSource property value to DataSource1 as shown below.

At this stage, the grid will not display data because the view does not contain any columns yet.  For more detailed information on creating the grid control and binding it to data, see the Connecting To Data topic.

See the next topic for basic information on column creation.


Table View Tutorial. Step 2: Columns Creation
Table View Tutorial. Step 2: Column Creation

Prev: View Creation	Next: Setting Up The View Look & Feel

In the previous topic, an ExpressQuantumGrid control was created and connected to a data source.  This topic shows how to create and customize columns.

There are three ways to create columns for a data bound view.  The first is to use the Structure Navigator.  Right-click the tvFilms label and choose the Create All Columns option from the dropdown menu:

Columns may also be created using the Component Editor. This can be activated via the Customize… button of the Structure Navigator.  In the Columns tab, press the Retrieve Fields button at the bottom of the page to add columns corresponding to all the fields of the bound dataset.

The third, and easiest method, connects the grid to a data source and creates the grid's columns from scratch.  This is the method you may want to use whenever the ExpressQuantumGrid is placed on a form, a view is designated to display data and all the necessary data sources are created and set up.  At this point, all you have to do to connect the grid to a data source is right-click on the grid and choose the Link to <DataSource name> option from the dropdown menu as shown in the image below:

This will automatically connect the grid to the selected data source and retrieve all the fields which will be displayed as view items (columns for a (banded) table view and rows for a card view).

Once columns have been added to the view, their names appear within the list on the Columns page.  Select the tvFilmsID, tvFilmsWEBSITE, tvFilmsTAGLINE and tvFilmsPhoto columns and press the Delete button or the Del key.  This removes the selected (unwanted) columns from the view.

Properties for each column can be customized using the Structure Navigator and the Object Inspector.  When a column is selected in the Structure Navigator, its properties are displayed within the Object Inspector window.  The following image demonstrates changing a column’s caption:

Give appropriate names to all columns, as shown in the following screenshot:

You can change all column properties in the same way, even a column’s data binding settings.  See the TcxGridColumn class description for more information on grid columns and their settings.

The next topic covers customizing the view and changing column options.


Table View Tutorial. Step 3: Setting Up The View Look & Feel

Prev: Columns Creation	Next: Editors And Repository

The previous step completed the creation of columns.  The result is shown by the following image:

This tutorial topic explains how to use the view and column options to improve the ExpressQuantumGrid’s display.  A quick overview of all options available is given in the Options topic.

Let’s modify the appearance of the tvFilms view.  Expand its OptionsView property group within the Object Inspector.  First, we will adjust the width of all columns so as to display full cell contents without needing the horizontal scroll bar.  Select the ColumnAutoWidth option and set it to True, as shown below:

Adjust the width of all columns, where necessary, in order to display the full text of each column header.  Simply click and drag the appropriate column header edge.

You may have noticed that some column values are trimmed.  To avoid this:

1.	Activate the CellAutoHeight option.  It adjusts the cells height to display their contents entirely.  The result is shown below:

2.	You can also apply best fit to an individual column.  Just double-click the right border of the column header.

There are many view options in ExpressQuantumGrid and some will be described in the topics following.

Activate the Structure Navigator and select the tvFilmsYEAR column.  Invoke the Object Inspector and expand the column’s Options properties group.  Set the Options.Grouping property to False:

This prevents the selected column being grouped at runtime.  This feature will be used in further tutorial lessons.

ExpressQuantumGrid has many options, affecting almost every aspect of the control’s display and functionality.  For more information on the options available, see the TcxGridTableView , TcxGridTableOptionsView , TcxGridTableOptionsBehavior, TcxGridTableOptionsCustomize, TcxGridTableOptionsData, TcxGridTableOptionsSelection topics.

See the next topic for the base information on the Express Editors usage.


Table View Tutorial. Step 4: Editors And Repository

Prev: Setting Up The View Look & Feel	Next: Styles And Style Sheets

The previous topic showed how to modify grid views and change column options.

This topic explains how to use the ExpressEditors as in-place editors within ExpressQuantumGrid.

You can assign editors to column cells in two ways:

1.	Changing the properties of individual columns.

2.	Using the ExpressEditors Repository.

Let’s consider the first method.

Activate the Component Editor and switch to the Columns page.  Select the tvFilmsICON column.  Open the Properties combo box within the Object Inspector window and select the Image item from the dropdown list:

Expand the Properties group and use the GraphicClassName property to set the image type to JPEG:

The cxImage editor now displays images:

Select the tvFilmsCOLOR column to display its properties within the Object Inspector. Use the Properties combo to assign the cxRadioGroup editor to the column.

Expand the Properties group and modify the cxRadioGroup editor’s properties as follows:

•	Select the Properties.Items property via the Object Inspector.  Click the ellipsis button:

This invokes the RadioGroup items collection editor:

•	Click the [image] button to create a radio group item.  Name this item "Yes" and set its Value property to "True":

•	Create another item.  Name it "No" and set its Value property to "False":

•	As you can see below, the radio group item selected now depends on tvFilmsCOLOR column values:

Another method of assigning editors to grid cells is by using the Editors Repository and this allows you to assign editor properties to many columns at once.  See the TcxEditRepository class description and the Data Editing Using Inplace Editors topics for more information.

See the next topic for more information on modifying the grid’s appearance.


Table View Tutorial. Step 5: Styles And Style Sheets

Prev: Editors And Repository	Next: Preview Creation

The previous topic explained how to assign editors to grid cells and the result is shown below:

This topic demonstrates how modify the grid’s appearance by using styles and the Style Repository.

Go to the cxControls tab on the component palette and place the cxStyleRepository control on the form:

With the Style Repository, you can create and manage styles.  Double-click the cxStyleRepository component on the form.  This invokes the editing dialog.  Activate the Styles page and click the Add button to create a new style, as shown below:

Give the style an appropriate name, HeaderStyle, for instance.  Now you need to set its style properties:

•	Enter $00C56A31 as the Style.Color value;

•	Set the TextColor property value to clWhite;

•	Expand the Font property and set the font style to Bold.

After the style is created and set up, it can be assigned to a grid element.  Select the grid view using the Structure Navigator or the Component Editor.  Expand its Styles property in the Object Inspector.  Select the Styles.Header property and assign it to HeaderStyle:

The following two images show the column headers before and after the above change:

You can create and assign styles in the same way for every grid element.  But there is another simpler way to modify the grid’s appearance – the use of style sheets.

A Style sheet is a set of styles designed for use with a particular view type.  There are three types of style sheets: table view style sheet, banded table view style sheet and card view style sheet.  All types of style sheet can be created and edited using the Style Sheets tab of the Style Repository Editor.

The Style Repository also provides a set of predefined color schemes for each view type.  To use a predefined style sheet, follow the instructions below:

•	Activate the Style Repository Editor.  Switch to the Style Sheets tab.

•	Click the Predefined… button to invoke the Predefined StyleSheets dialog.  Use the Style Sheet Class combo to select the type of the required style sheet – TcxGridTableViewStyleSheet. in this case:

•	Select the DevExpress style sheet from the list placed below the Style Sheet Class combo box.  The preview box at the right side of the dialog shows the effect of applying the color scheme:

•	Press the Load button at the bottom of the dialog.

After the style sheet has been applied to our view, you can access and override individual style settings.  See the Style Repository topic in this help system for details.

Now we should assign the DevExpess style sheet to a table view.  Select the tvFilms view using the Structure Navigator or the Component Editor.  In the Object Inspector, expand the Styles property and select the new style sheet using the combobox supplied for the StyleSheet property.  Note that all grid elements have been assigned style settings and these can be edited using the Object Inspector.

The grid view immediately reflects any such change:

For comprehensive information regarding the Style Repository and its usage, see the Style Repository topic.

See the next topic for use of the preview feature.


Table View Tutorial. Step 6: Preview Creation

Prev: Styles And Style Sheets	Next: Footer Summary Creation

In the previous topic, we modified the grid’s appearance as shown below:

The Preview Section feature is effective when displaying long text field values.  Follow the instructions below to enable this feature:

•	Select the tvFilms view.  Use the Object Inspector and expand the Preview property.

•	Set the Preview.Column property value to tvFilmsPLOTOUTLINE and this selects the column to be displayed in the preview section.

•	Set the Preview.Visible property value to True.  The preview section is displayed immediately.

•	Set the Preview.MaxLineCount property value to 4.  This makes all the text within the preview section visible.

•	Set the Preview.LeftIndent and Preview.RightIndent property values to 150.

The result is demonstrated on the following screenshot:

See the next topic for information on creating and modifying footer summaries.


Table View Tutorial. Step 7: Footer Summary Creation

Prev: Preview Creation	Next: Group Summary Creation

The previous topic showed how to use the preview feature of ExpressQuantumGrid, as shown in the screenshot below:

This topic covers the creation of footer summaries.

The Component Editor is a convenient tool for the creation of summaries in ExpressQuantumGrid.  Activate it, select the required view and switch to the Summary tab of the designer window.  The Summary tab contains three sub-tabs used for the creation of summaries of different types.  To create a footer summary, go to the Footer tab:

Click the Add button to create a footer summary item and this will appear within the empty items list displayed above.  Select it and use the Object Inspector to adjust its properties as follows:

•	Change its Column property value to tvFilmsRUNTIME.  This selects the column values to be used during summary calculations.  This property also defines the default column footer where the summary value will be displayed.

•	Set its Kind property value to skMax and this will set the footer to display the longest run time of any movie.

You can also format summary values to provide more information.  Use the Object Inspector and set the Format property value to "MAX=0 minutes", where 0 is a summary value placeholder.  A formatted summary value is shown below:

To access properties of a summary item you can click the corresponding cell in the grid control.

See the next topic for creation of group summaries.


Table View Tutorial. Step 8: Group Summary Creation

Prev: Footer Summary Creation	Next: Summary Group Creation

In the previous topic, we created a footer summary displaying the longest runtime of any movie:

This topic shows how to create a group summary.

Group summary values can be displayed within grouping rows (i.e. the parent row of all child rows within the group) or within grouping row footers (displayed after child rows while the group is expanded).  To create group summaries, activate the Component Editor, switch to the Summary tab and activate the Default For Groups sub-tab.  Click the Add button to create a group summary item:

Select it and use the Object Inspector to modify the item’s properties:

•	Set the Column property value to tvFilmsCAPTION.  This defines the column where the summary value will be displayed;

•	Set the Kind property value to skCount to display the number of records in the group;

•	Set the Position property value to spGroup.  The record count will be displayed in the grouping row, not as a group footer;

•	Set the Format property value to "Number of released movies: 0".

Press the Add button again to add another group summary item.  This time, the summary will be displayed within a group footer.

Select the new item and modify its properties as follows:

•	Set the Column property value to tvFilmsCAPTION.

•	Set the FieldName property value to RUNTIME. This defines the field involved in the calculations. Note that this is different from the column displaying the result (i.e. the Caption column).

•	Set the Kind property value to skSum, as this time we want to get the runtimes total.

•	Specify the value for the summary item’s Position property value to spFooter.  This displays the summary within group footers, as opposed to the grouping row as before.

•	Set the Format property value to "Total runtime: 0 minutes".

To make group summaries visible, grouping needs to be applied.  Activate the Component Editor and select the tvFilmsYEAR column. This is the column whose Options.Grouping property was set to False in the Setting The View Look And Feel topic.  Invoke the Object Inspector and set the column’s GroupIndex property to 0.  This applies grouping to the view and group summaries within grouping rows become visible:

Note that the view has been grouped by the tvFilmsYEAR column even though grouping by this column was disabled earlier.  Set the Visible property of tvFilmsYEAR to False.  This removes the tvFilmsYEAR column from the view:

We need to modify the view’s properties so that the group footer summary is visible.  Select the view using the Structure Navigator or the Component Editor.  Use the Object Inspector to expand the View.OptionsView property.  Expand the GroupFooters property combo box and set it to gfAlwaysVisible.

The next topic explains how to create summary groups.


Table View Tutorial. Step 9: Summary Group Creation

Prev: Group Summary Creation	Next:

In the previous topic, you were shown how to create group summaries.  The result is shown in the following screenshot:

This topic describes one of the most powerful features of the ExpressQuantumGrid: summary groups.  All summaries within a group are linked to a specific column.  Summaries from the corresponding group appear only when grouping by that column is implemented.

To create a summary group, activate the Summaries tab of the Component Editor and select the Groups sub-tab.  Press the Add button under the Groups list to create a new summary group:

We want this summary group to be displayed when the tvFilms view is grouped by tvFilmsYEAR column values.  Select the tvFilmsYEAR column within the Unlinked Columns list and press the [>] button at the right edge of the list.  This moves the selected column to the Linked Columns list:

Click the Add button under the Items list (to the right of the Groups list).  This adds a summary item to the existing group.  Select that item within the list and modify its properties as displayed in the following screenshot:

Add another summary item and set up its properties as shown below:

Select the tvFilms view and set OptionsView.GroupFooters to gfInvisible.

This hides group footers from the view.

The result of the above changes is shown below:

See the Creating Summaries topic for more information.

ExpressQuantumGrid also supports summaries based upon custom functions.  See the Create Custom Summaries topic for details.


Data Representation Capabilities

See Also

In addition to the presentation of data in various forms (Table, BandedTable, Card or Chart View), the ExpressQuantumGrid provides other features to help display records in a more convenient form.  These features include sorting, grouping, filtering, summary calculation, previewing a specific column and incremental search support.  A user can perform most of these operations at runtime, provided that the options are set accordingly.

One of the new features introduced by the ExpressQuantumGrid is the capability of displaying multiple views within one grid control.

Multiple Views

Using our grid control, you can represent data from multiple data storages.  This is implemented by views connected to data storages (custom data sources and/or datasets) and they display data in various forms (tabular, card etc.).  You can establish master-detail relationships between views.  Every master view can have one or more detail views (details) linked by a specific key field(s).  The grid control provides a convenient way of switching between detail views via tabs.

In addition, you can display multiple non-related datasets at the top level and their access is also controlled by tabs.

To learn more about multiple views see the Data Representation section.

Sorting

Our grid control allows you to sort data in a grid view by multiple items (columns in a table view and rows in a card view).  A user can switch between different sort modes by clicking the column caption (implemented only in a table view).  The first click on a column header sorts data in ascending order and the second by descending order, etc.  To clear sorting by a column, click the column caption holding the Ctrl key down.

You can also sort data by multiple columns.  To do this, click on column headers while pressing the Shift key.

A small arrow displayed within a column header indicates the current sort order.  The up-arrow indicates the ascending sort order, the down-arrow – the descending sort order.

To sort by code, see the SortOrder attribute of an item.  Probably, you will need to clear the current data details first.  For this, use the view’s DataController.ClearSorting method.

Filtering

The ExpressQuantumGrid allows you to filter the data displayed by creating filter conditions.  When filtering is applied, only the records matching all filter conditions set in the view are displayed.

Runtime filtering for a table view is very easy.  By default, every column has a down-arrow button at the left edge of its caption.  Clicking this button displays a dropdown list containing unique values from the current column.

When a user selects a value from this list, a new EQUAL filter condition of type "Column = Value" is added to the existing filter criteria.

Selecting All from the list clears the filter condition for that column.  The Custom item displays a filter dialog, enabling a user to define filter conditions with other operators (=, <>, <, <=, >, >=, LIKE and NOT LIKE).  For more information on the filter dialog, refer to the Runtime Filtering section.

To set filter criteria programmatically, use the view’s DataController.Filter property.

Grouping

When data in a grid view is grouped, records with the same value in the grouping column make up a group and the grid view’s content is displayed in a tree-like manner.  Grouping is not supported in card views.

The grid control displays the group by box (also called a group panel) by default, thus enabling a user to group data.  He/she can easily group data by dragging a column caption to this panel and then ungroup data by dragging it back to the column header panel.  When a user drags a column caption, two green arrows indicate the position where the column will be placed.  The column dragged to the group panel is hidden within a view.  Its header is now within the group panel and its values are displayed within group rows.

Grouping can be performed against multiple columns.  A user can move column captions within the group panel to change the group order.

Column and view options allow you to prevent a user from grouping and moving columns (within the groups and standard columns).  These options do not affect grouping performed programmatically.

At design and runtime, grouping can be performed by setting the column’s GroupIndex property.  Actually, the access methods of this property call the TcxDataControllerGroups class’s methods, as grouping operations are performed by the data controller.

Summaries

Summaries allow you to calculate totals by specific columns against a group of records or all records in a view.  There are two types of summaries provided by the grid control: footer summaries and group summaries.

Footer summaries are calculated against all the records in the view and the resulting values are displayed within the footer panel at the bottom of the view.  Group summaries are calculated for records of each view group.  Their results can be displayed either within the group rows or within group footer panels.

To learn more about summaries see the Summaries and Creating Summaries topics.

Preview

The ExpressQuantumGrid provides a convenient way to display large text fields within the preview section.  The preview section is implemented only in table views.

The preview section is a region that may occupy several columns and several lines to display the contents of a single column.  You cannot edit the contents of the preview section.  The following image demonstrates the preview section displayed at the bottom of a row.  You can also make the preview to appear at its top.

To set options for the preview section, use the view’s Preview object. To display the preview you should:

•	assign a column for previewing via the Preview.Column property.  When it is assigned, its original column is no longer displayed.

•	enable the preview section by setting Preview.Visible to True.

It is also possible to specify the preview column via the column’s IsPreview attribute.

Incremental Search

The Incremental Search feature allows a user to locate records in a view by column values.

If Incremental Search is enabled (the view’s OptionsBehavior.IncSearch attribute is True), you can type in a column to jump to the first record with a column value starting with the typed letters.

The ‘mi’ characters are pressed.  As a result, the first ‘Mickey Alcorn’ record is located.	An ‘l’ character is pressed after ‘mi’ and focus has moved to the ‘Mildred Johanson’ record.

Press the Ctrl+UpArrow or Ctrl+DownArrow key combination to continue searching in the appropriate direction.

Note that the column must not be in edit mode before applying the incremental search.


Views

See Also

A view consists of "items" arranged in a specific manner.  "Item" is a key view element.  For the TableView and BandedTableView, it corresponds to a column and for the CardView, "item" is a card view row.  For the ChartView, "item" represents categories or a series.  View objects support an items collection providing access to all view items.  Since the items’ visibility can change at runtime, view objects also contain a collection of currently visible items.

Since view objects are designed to represent data in a specific manner, the main property of any view object is the DataController.  This property provides access to objects by managing the view connection to a data storage.  The DataController object implements the main features of a data-aware view: grouping, sorting, filtering, posting changes to a data storage, etc.

View objects also provide a user with a set of options and styles to manage a view’s look & feel.  The view options are grouped according to their functions. See the Options topic for more information about the view and other ExpressQuantumGrid options.

Each view object publishes a set of styles defining the appearance of view elements.  These sets are different for different view types (for instance, a banded table view has a style, affecting the appearance of band headers, but this style is not available for table views).

The base class for all view classes is the TcxCustomGridView class.  This class implements the common functionality of all views.  It connects to a data storage via the DataController object, controls the look & feel of views via a set of options and styles, etc.

The TcxCustomGridTableView class enhances the basic view functionality with items support and provides properties to access all view items, visible items and grouping items collections.   These two classes are the base for custom view classes.

Other view classes are built-in classes used for the implementation of the different data display formats: tabular and card.  A tabular data representation form is implemented via the TcxGridTableView class:

The TcxGridCardView class allows you to represent data as a set of cards:

The grid table view has an enhanced version – banded table view (TcxGridBandedTableView).  The banded view lets you combine columns into Bands.  Bands allow you to group columns logically and thus move and/or resize as a single entity (see the TcxGridBandedTableView class description for details).

The most illustrative view for numerical data is the TcxGridChartView.  The TcxGridChartView class lets you visualize data using various diagrams which represent values in the form of graphical shapes (for instance, bars or columns):

All four view classes described above have data-aware versions.  They use the TDataSet object or its descendant to connect to a data storage.


Options

See Also

The ExpressQuantumGrid has many features making it a very powerful and flexible data-aware control.  Most of these features can be accessed by sets of options.  These options control the functionality and appearance of almost all the grid elements: views, grid levels, items (columns, card view rows), etc.  Sometimes the ExpressQuantumGrid options affect other option sets, even if connections between them are not obvious.

The ExpressQuantumGrid uses views to represent data to a user, so the view options play the main role in the customization of the ExpressQuantumGrid.  There are several option sets available for grid views.  These options include:

•	OptionsBehavior – options defining the grid view’s response to the user’s actions, i.e. via the mouse and keyboard

•	OptionsCustomize – options determining the runtime functionality of view items.  These options determine whether the end-user can move, group, sort, resize and view columns.  The banded table view also provides options controlling band functionality– moving and resizing.  These option settings can be overridden via code, e.g. suppress column grouping by setting the OptionsCustomize.ColumnGrouping property value to False.  Columns can still be grouped though by setting the Column.GroupIndex property as appropriate.

•	OptionsData – options controlling data manipulation within the view.  These options control editing, inserting, deleting records, etc.

•	OptionsSelection – options managing selections within a view.  Options from this set determine whether the selection bar is visible, whether the selection bar bounding rectangle is visible, whether multiple rows can be selected, whether individual cells can be focused instead of rows, etc.  The OptionsSelecton.CellSelect property affects the editing capability of a view.  If this property value is False, editing can be implemented only programmatically.

•	OptionsView – options controlling the appearance of a view.  This option set defines the visibility, color, width and other appearance settings of view elements.  These options are specific to the view type.  They often affect the view functionality.  For instance, making the view group panel invisible by setting the OptionsView.GroupByBox property value to False restricts runtime grouping for a specific view.

•	FilterBox – options which affect a View’s filter panel (also called a filter box).  These options control various appearance settings and behavior of a filter box.  For more information about filtering in the ExpressQuantumGrid, refer to the Filtering and Runtime Filtering topics.

•	Filtering – options affecting a View’s filter dropdowns and filter dropdowns for the filter panel.  These options specify the filter panel visibility, filter dropdown width and the number of data field values displayed within the filter dropdown.  For more information about filtering in the ExpressQuantumGrid, see the Filtering and Runtime Filtering topics.

•	FilterRow – options which control various appearance aspects and behavior of a filter row.  For more information about filtering in the ExpressQuantumGrid, refer to the Filtering and Runtime Filtering topics.

•	NavigatorButtons – options which control the behavior of the data navigator and various appearance aspects of its buttons.  For additional information on the data navigator, refer to the Record Navigation topic.

•	NewItemRow – options which control various appearance aspects of a new item row.

•	Preview – options managing the preview section of a view.  These options specify the preview section visibility, the view column whose values are displayed within the preview section, the preview text position, etc.  For more information on the ExpressQuantumGrid preview feature, see the Preview Section topic.

View elements (columns, bands, diagrams, categories and series) have their own option sets.  These option sets are similar to the OptionsCustomize view options and are used to override the view settings for certain view elements.  For instance, a user can allow all view columns to be moved via an appropriate option from the OptionsCustomize set and prevent a particular column from moving via the Column.Option.Moving property.


Grid Control is just a Container for Grid Views

See Also

When placing the TcxGrid control onto a form and looking through its properties in the Object Inspector window, you will not find any properties that allow you to bind the grid to a data source, customize the columns collection or change any other aspect of data binding and representation.  This might seem confusing if you previously used, say, the standard TDBGrid control which has the DataSource, Columns properties, etc.  This topic will explain why there is such a difference between these controls, how the TcxGrid control is organized and where you need to look for the properties, methods and events that are actually related to the data's representation.

First of all, lets point out the two basic benefits of the TcxGrid control:

•	This control enables you to represent data in various layouts.  This includes the standard column/row layout, cards layout, plotting charts and, the advanced column/row layout allowing you to group columns into bands, create multi-line cells within rows, etc.  And of course, we provide the possibility to extend this set of data representation formats as well as enhance any of the mentioned ones.

•	This control enables you to display master-detail (hierarchical) data as well as to display data from several independent data sources.  At the same type, data at different hierarchy levels and data from different independent data sources can be represented in its own format.

The implementation of the two benefits described above involves two key notions in the ExpressQuantumGrid – grid views and grid levels.  To implement various data representation formats the grid control provides a set of objects – grid views – with the following basic sets of features:

•	Each grid view can have its own data binding mechanism;

•	Each grid view can visually represent data in its own manner and provides its own unique settings for this purpose;

•	All grid views have a common interface so that the grid control can manage them in the same manner.

The second benefit is implemented by means of grid levels – objects that arrange grid views into hierarchical and multiple-branch structures.  The grid control holds the hierarchy of grid levels while each grid level has an associated grid view that should be used for data representation at the current hierarchy point.  So the grid control is just a container for grid views, which are the ones that actually display the data.

And now it’s time to see what you have in a TcxGrid control when you place it onto a form.

The Structure Navigator in the bottom-right grid’s corner displays three labels:

•	The cxGrid1 label indicating the grid control itself;

•	The cxGrid1Level1 label indicating an automatically created level;

•	The cxGrid1DBTableView1 label indicating an automatically created grid view that is associated with the level.

Since the grid control contains a single grid level, the grid will display only a single grid view associated with this level.  So the automatically created structure is the same as when you place a standard TDBGrid control onto a form.  The only difference is that you should use the grid view’s settings to bind to a data source and specify how the bound data should be represented.  To access the grid view’s settings via the Object Inspector, just click the view’s label within the Structure Navigator.

For further information about customizing the grid levels structure, changing their associated grid views and working with grid views, refer to the following topics:

•	Grid Levels

•	View Types and Inheritance

•	View Structure

For information regarding the settings provided by the grid control itself, please read the Grid Control Settings topic.


Grid Levels

See Also

As described in the Grid Control is just a Container for Grid Views topic, grid levels are used to arrange grid views into hierarchical and multiple-branch structures.  Additionally, these levels specify which grid view should represent data at a hierarchy point.  This topic provides a comprehensive description of the grid levels’ settings and their hierarchy within the grid control.

Accessing and Customizing the Grid Levels Structure

Grid levels are TcxGridLevel objects.  Each object of this type can hold a collection of child levels thus enabling you to build hierarchical level structures within the grid.  The grid’s root level can be accessed via the Levels property.  This root level is not used for display purposes and doesn’t have an associated grid view.  It only provides a collection of first-level grid levels and specifies the settings for these child levels.

To add a grid level at the first nesting level of the hierarchy, you should use the root level’s Add method.  To add grid levels at deeper hierarchy levels, you should use the desired parent level’s Add method.  To delete a grid level, you should dispose of it by calling its Free method.

At design time, you can customize the levels structure using the Structure Navigator displayed at the bottom-right grid control’s corner.  Consider the default layout that is automatically created when placing the grid control onto a form.

As you can see from the image above, the Structure Navigator hides the root level object.  This is done for your convenience since this level is not used for display purposes.  To add a grid level to the first nesting level, you should right-click the grid control’s label and choose the Add Level item from the context menu.  To add a grid level to deeper hierarchy levels, right-click the desired parent level’s label and choose its context menu’s Add Level option.  The image below gives an example.

After you have created the levels hierarchy, you should specify the associated grid views.  This topic describes the ways of implementing this some paragraphs further down.  Running a few steps forward, let’s see the grid control’s actual layout specified by the created levels hierarchy.  The image below assumes that table views have been assigned to all the levels created.

As you can see from the above images, grid levels standing at the first hierarchy level enable you to display data from several independent data sources within the same grid control.  Grid levels at deeper nesting levels of hierarchy are used to create master-detail relationships.

Specifying Associated Grid Views

Once you have created the levels structure, you should specify the grid views that will visually represent data at every hierarchy point.  To specify a grid view for top grid levels, you should use the desired grid level’s GridView property.  If you specify a grid view for detail grid levels, there are two alternatives to choose from.  These alternatives come from the fact that each detail is represented by an individual grid view instance.  E.g. if there are five expanded records in a master view, there are five grid view instances created for the detail level.  These grid view instances are called clone views since they are created by copying the settings from the grid views that are assigned to levels.  By default, clone views are created using the settings of the grid view that is assigned to the grid level’s GridView property.  At the same time, you can provide different grid view types and grid view settings for each individual detail.  This can be done using the grid level’s OnGetGridView event.  And these are actually the two alternatives mentioned above:

•	Displaying each detail using the same grid view’s settings.  In this case, you simply assign a view to a level using the level’s GridView property.  Note that this is the most commonly used case and you will rarely need to change this behavior.

The image below shows how to create a grid view for a grid level at design time.

The next image illustrates the view assignment approach described.

•	Providing different views for different details.  In this case, you should assign one of the desired views to the level’s GridView property and handle the OnGetGridView event to override the default assigned view.

If you use the second approach, you may need a tool for creating standalone views and customizing them at design time.  The reason for this is that the TcxGrid control’s Structure Navigator doesn’t allow you to create and customize views that are not directly assigned to levels.  To create such views, use the TcxGridViewRepository component.

Grid Level Settings

The table below lists the main settings provided by the TcxGridLevel object.

Property	Meaning
Caption	Specifies the text displayed within the tabs that correspond to that level.
Options	Provides settings for detail levels.  This includes the detail bounding frame’s width and color together with the detail tabs position.
Styles	Specifies the styles for detail tabs and their background.
Visible	Enables you to toggle the level’s visibility.


Grid Control Settings

See Also

As described in the Grid Control is just a Container for Grid Views topic, the grid control doesn’t provide any settings for data binding and customizing the displayed layout since these settings are provided by grid views.  At the same time, the grid control has a number of settings you will definitely use so this topic provides a brief overview of these settings.

Settings Inherited from the TcxControl Class

The TcxGrid control is derived from the TcxControl class which is the TCustomControl descendant.  Thus, the grid control provides you with most of the settings that are common to all visual controls.  These settings allow you to specify the control’s position, tab order, etc.

Look and Feel Settings

The grid control supports the look and feel technology, which is common to all Developer Express controls.  The look and feel settings are exposed via the grid’s LookAndFeel property.  Note that you can either customize the look and feel settings directly using this property or place a TcxLookAndFeelController component onto a form to provide centralized control over the look and feel of all Developer Express controls in the application.  Please refer to the Look and Feel topic for details.

Grid Levels Management Settings

As described in the Grid Control is just a Container for Grid Views and Grid Levels topics, the grid control maintains a hierarchy of grid levels.  The root level in the hierarchy can be accessed via the grid’s Levels property.  This root level holds a collection of the first-level grid levels and specifies their appearance.  These appearance settings are exposed via the grid control’s RootLevelOptions and RootLevelStyles properties.  Note that these properties simply provide access to the root level’s Options and Styles properties as shown in the image below.

Additionally, the grid control publishes the OnActiveTabChanged event that is raised when end-users switch between grid levels at any nesting level using tabs.  The active level at the top of the hierarchy can be obtained via the ActiveLevel property.

Grid Views Management Settings

When developing an application that uses the TcxGrid control, you will mostly deal with the properties and the methods of grid views.  Since the grid control is capable of displaying several grid views on screen at a time, it provides a number of properties, methods and events that allow you to manage the grid views.  For instance, the grid’s FocusedView property enables you to access or specify the grid view that has input focus while the OnFocusedViewChanged event allows you to respond to moving view focus.  The ActiveView property provides access to the currently active top-level view.  This means that the ActiveView property value matches the FocusedView property when a top-level view has input focus.

The ViewCount and Views properties allow you to access all pattern grid views currently present within the grid control.  To access actual clone views representing details, you should use the corresponding pattern views’ properties.


View Types and Inheritance

See Also

The ExpressQuantumGrid provides a number of different grid view types that differ in the manner in which they bind to and display data.  All the grid view objects have a common ancestor and this enables common view management within the grid control.  This common ancestor is the TcxCustomGridView class which is the type of most of the properties, method return values and parameters that represent grid views.

The image below shows the inheritance diagram for the Grid Views available.

As you can see, there are four main branches in the grid views inheritance diagram and these branches correspond to the four types of grid view available – Card View, Table View, Banded Table View and Chart View.  Each view type has a data-aware and non data-aware version.  The data-aware view versions obtain their data from a dataset.  Non data-aware view versions are designed to allow working in Unbound Mode and Provider Mode.

Note that the Card View, Table View and Banded Table View are not derived directly from the TcxCustomGridView class, but instead inherited from an intermediate TcxCustomGridTableView class.  The reason for this is that currently all these views have a tabular data representation format which means that a view contains a collection of objects that represent data fields (items) and objects which represent data records.  Thus, they all have a common functionality which is implemented by the TcxCustomGridTableView class.  The only exception is a Chart View which derives directly from the TcxCustomGridView class since the Chart View provides visualization of the data using various diagrams that produce far more than a tabular data representation.

The following topic sections provide a general overview for each of the available view types.

Card Views

Card Views are designed to represent data in a card format.  Each data record corresponds to a card, and each data column corresponds to a card row.  Card Views support most of the advanced data representation features found in other Views and offers extra features specific to Card Views.  These features include programmatic and end-user sorting, data filtering of a wide set of data types (including date/time values filtering), card expanding and collapsing, the multi-card selection, row flat layering in a card, etc.

Table Views

Table Views represent data in a tabular format where columns correspond to data fields while rows represent data records.  They support a wide range of data representation features including programmatic and end-user sorting, grouping, filtering, total and group summary calculation, row and cell multi select, row preview, etc.

Banded Table Views

Banded Table Views extend Table Views to provide two main data layout features:

•	Arranging columns into bands (including nesting band structures).  This enables end-users to manipulate groups of columns since they are capable of reordering bands, toggling band visibility, etc.  Additionally, particular bands can be anchored to the left or right edge of a view so that they are not involved in horizontal view scrolling.

•	Arranging columns into several rows.  This enables you to arrange your data in the most compact way since the column layout specifies the layout of data cells within rows.

Chart Views

Chart Views represent data visually by using various diagrams which present the data in the form of data markers so that values can be easily compared.  Chart Views have the most distinctive appearance amongst other Views as they visualize numerical data in an extremely illustrative manner.  Chart Views provide a wide range of data representation features (mostly visual options) which control the appearance aspects of their graphical elements and are unique to the charts.


View Structure

See Also

The functionality of grid views is not implemented in a single grid view class.  Grid views delegate much of their functionality to specially designed helper objects and provide a number of objects that store grid view settings so that these settings are logically organized.  Thus, a grid view is not just an object but a bunch of objects that has a TcxCustomGridView descendant in its center and a number of helper objects exposed via particular properties.  This topic provides information on which helper objects are available and which properties should be used to access them.

The Basic Grid View Structure

First, lets consider the TcxCustomGridView class which is the base for all views in the ExpressQuantumGrid.  The diagram below shows the relationship between this view and its helper objects.

The list below describes the properties illustrated in the above image.

Site, Controller, Painter and ViewInfo

The Site property provides access to the TcxGridSite control that actually represents the grid view on screen.  This control is painted by means of the grid view painter available via the view’s Painter property.  When painting, the layout and appearance of view elements is obtained from a special object available via the grid view’s ViewInfo property.  End-user actions are also processed by the grid view’s underlying site control.  All these actions are passed and finally processed by an object exposed via the grid view’s Controller property.  For additional information on grid sites, please refer to the TcxGridSite and TcxCustomGridView.Site topics.

Particular attention should be paid to the Controller property.  The object available via this property enables you to obtain information related to end-user actions and customize the view in this regard.  For instance, it enables you to determine or set the currently focused cell, scroll the view or obtain its current scrolling state, determine which operation is currently being performed by an end-user and which visual elements are affected by it.  Please refer to the topics covering the TcxCustomGridController class and its descendants for additional information.

DataController

This property provides access to the data controller object that manages the view’s data binding and data operations.  This data controller object provides properties, methods and events that allow you to bind the view to data (if working in bound mode), provide data to the view (if working in unbound mode), specify the data loading mode, read and write data values, filter data, summarize data, locate records by data, manage bookmarks, navigate between records, manage record selection and perform many other data related operations.

As you can see in most cases with (banded) table views and card views, you should use the view’s data controller object to perform data operations.  Note that at the same time, some data related settings can also be found in other objects.  For instance, you should specify the sort order or summary for a column using the desired column’s settings.

For ChartViews however, it's recommended to use the view’s Categories, Series or ViewData properties to manipulate the data since these properties provide a more convenient way to manage the data which is associated with the views.

ViewData

This property provides access to the object that holds information about how the view represents data from its data controller.  In card and table views, this object provides access to cards and rows respectively.  Note that the rows in table views include group rows and the new item row.  Thus, you should use a grid view’s ViewData property when you need to access objects that represent data in the view.  In ChartViews, the ViewData object provides access to category values and series values.

Options

Each view has a number of options properties such as OptionsView, OptionsCustomize, etc.  These properties provide access to objects that hold settings related to a particular aspect of a view's functionality.  For instance, the OptionsView property provides settings specifying the visibility of the view’s elements, their content and other attributes related to the view’s visual representation.

Styles, BackgroundBitmaps

The names of these properties are self-explanatory.  They specify the styles and background bitmaps assigned to the view elements.  It's also worth noting that the structure of objects available via these properties is very similar.  Both objects have a set of properties whose names are the names of the corresponding visual elements.  Assigning a bitmap or a style object to such a property sets the corresponding element’s background image or style, respectively.  Note that you can change the styles of all the visual elements in a view at once.  For this purpose, use the Styles.StyleSheet property that accepts style sheet objects that you can supply using the TcxStyleRepository component.


Pattern and Clone Views

See Also

This topic explains the mechanisms used by the ExpressQuantumGrid to manage detail views.  This information is useful if you display master-detail data within the grid and need to access or customize detail views at runtime.

Leaving the data-binding details aside, the most common level-view structure you will face when displaying master-detail data is a single root level with a view assigned and a child level bound to another grid view.

The ViewProducts detail view displayed in the above image allows you to bind the detail to data and customize the detail’s behavior and appearance.  One of the ways to access this view’s settings is to click the corresponding label in the Structure Navigator.

It may appear at first glance that the ViewProducts view represents all the details you see on screen – its settings specify the appearance and behavior of all the details and at the same time it manages the data displayed by the details.  Actually, the View Technology introduced by the ExpressQuantumGrid is far more flexible.  The list below describes its key points:

•	Each detail you see on screen is an individual grid view instance.

•	The view you customize at design-time serves only as a store for the view's settings and doesn’t have any visual representation (and it doesn’t provide access to any data).  Such views are called Pattern Views.

•	When end-users expand a master row, the grid control creates a view instance of the same type as the pattern view, which is identified by the master view and the relationship (multiple details can be displayed for a single master view).  The created view is initialized with the pattern view’s settings.  Such view instances are what you actually see on screen – they are called Clone Views.

•	After a clone view has been created, it can either live independently from other clones and the pattern or it may be constantly synchronized.  This depends on the pattern view’s Synchronization property value, which is set to True by default.

Note: It's not necessary to have a single pattern view that corresponds to all the details.  You can provide multiple pattern views per level – see the Grid Levels topic for more details.

As you can see, view technology provides you with two main benefits when representing master-detail data:

•	Each detail clone can live separately from the others.  For instance, end-users may filter one detail without affecting the others.

•	Detail data corresponding to different master rows can be displayed by different views (and even different kinds of views – card view, table view, etc.).

As can be seen from the above explanation, the main point to managing the detail at runtime is to determine whether you need to access/modify the pattern or a clone.  Here are the main rules:

•	It's worth mentioning again, that pattern views do not control anything related to the actual data or end-user actions.  This means, pattern views do not provide information such as the current selection, focus, scrolling position, etc.  You should determine this via the appropriate clone view object.

•	If view synchronization is disabled, you should not use the pattern view’s settings to change the view’s layout.  For instance, reordering columns, changing a particular element’s visibility or style will have no effect on the actual clones you see on screen (except for when you provide manual detail synchronization via the DataController.ClearDetails or DataController.ClearDetailLinkObject methods).

If modifying the pattern view meets your requirements, you can access it in code by its name.  Otherwise, you will need to access its clones and this can be done using the following members:

•	The currently focused clone view can be accessed via the grid control’s FocusedView property.

•	To traverse through all the clones corresponding to a pattern view, you can use the pattern view’s Clones and CloneCount properties.

•	A view’s MasterGridView, MasterGridRecord and MasterGridRecordIndex enable you to identify the master view and the record in it which the current detail corresponds to.

•	If you handle the pattern view’s event, the sender view is the actual clone that has been affected.  For instance, the OnColumnHeaderClick event passes the clone whose header has been clicked, via its Sender parameter.


TcxCustomGridTableFiltering
TcxCustomGridTableFiltering Object

Hierarchy          Properties          Methods          See Also

Provides common filtering options for grid views.

Unit

cxGridCustomTableView

TcxCustomGridTableFiltering = class(TcxCustomGridOptions)

Description

The TcxCustomGridTableFiltering class serves as the base for the TcxGridTableFiltering and TcxGridCardViewFiltering classes.  These classes serve as the type for the Filtering property in table views and card views, respectively.

The TcxCustomGridTableFiltering class declares a set of properties specifying the availability of filtering features to end-users.  It also implements the RunCustomizeDialog method that allows you to invoke filter customization dialogs via code.


TcxCustomGridTableFiltering Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |

TcxCustomGridTableFiltering


Properties for TcxCustomGridTableFiltering
TcxCustomGridTableFiltering Properties

TcxCustomGridTableFiltering          Legend

In TcxCustomGridTableFiltering

CustomizeDialog

DropDownWidth

ItemMRUItemsList

ItemMRUItemsListCount

ItemPopup

MaxDropDownCount

MRUItemsList

MRUItemsListCount

MRUItemsListDropDownCount

Position

Visible

Derived from TcxCustomGridOptions

GridView


Methods for TcxCustomGridTableFiltering
TcxCustomGridTableFiltering Methods

TcxCustomGridTableFiltering          Legend

In TcxCustomGridTableFiltering

RunCustomizeDialog


TcxCustomGridTableFiltering.CustomizeDialog

TcxCustomGridTableFiltering

Specifies whether the Customize button is displayed within the filter panel.

property CustomizeDialog: Boolean;

Description

This property is obsolete and used for compatibility purposes.  Use the View’s FilterBox.CustomizeDialog property instead.


TcxCustomGridTableFiltering.DropDownWidth

TcxCustomGridTableFiltering

Specifies the width of filter dropdowns for items.

property DropDownWidth: Integer;

Description

This property is obsolete and used for compatibility purposes.  Use the ItemPopup.DropDownWidth property instead.


TcxCustomGridTableFiltering.ItemMRUItemsList

TcxCustomGridTableFiltering          See Also

Specifies whether filter dropdowns for view items (columns or card rows) should display the most recently used filter items.

property ItemMRUItemsList: Boolean;

Description

If the ItemMRUItemsList property’s value is True, filter dropdowns for view items (columns or card rows) display the most recently used filter items at the top of the list.  The maximum number of most recently used filter items that can be displayed within the list is specified by the ItemMRUItemsListCount property’s value.

Note:	To disable the most recently used list for a particular column or card row, set its Options.FilteringMRUItemsList property.

The default value of the ItemMRUItemsList property is True.


TcxCustomGridTableFiltering.ItemMRUItemsListCount

TcxCustomGridTableFiltering          See Also

Specifies the maximum number of most recently used filter items that can be displayed within filter dropdowns for view items (columns or card rows).

property ItemMRUItemsListCount: Integer;

Description

Filter dropdowns for view items (columns or card rows) can display a list of the most recently used filter items (MRU list for short).  Each time after a filter item in the dropdown has been selected it is displayed at the top of the MRU list.  The next time another filter item is selected it is added to the top of the MRU list thus increasing the number of filter items in the list.  This takes place until the number of filter items reaches the ItemMRUItemsListCount property’s value.  After this has happened, selecting a filter item results in this item being added to the top of the MRU list and the bottom filter item in the list being deleted.

The ItemPopup.MaxDropDownItemCount property’s value specifies the number of filter items that can be displayed simultaneously within filter dropdowns for view items.

The default value of the ItemMRUItemsListCount property is specified by the cxGridFilterDefaultItemMRUItemsListCount constant.


TcxCustomGridTableFiltering.ItemPopup

TcxCustomGridTableFiltering

Provides access to options that control various appearance and behavior aspects of filter dropdowns for view items (columns or card rows).

property ItemPopup: TcxGridItemFilterPopupOptions;

Description

Use this property to customize appearance and behavior elements of filter dropdowns for view items (columns or card rows).  Each view introduces its own property to access these options.  Use the view’s Filtering.ColumnPopup and Filtering.RowPopup properties for Table views and Card views, respectively.


TcxCustomGridTableFiltering.MaxDropDownCount

TcxCustomGridTableFiltering          See Also

Specifies the number of filter items which are displayed within the filter dropdown for view items (columns or card rows) simultaneously.

property MaxDropDownCount: Integer;

Description

This property is obsolete and used for compatibility purposes.  Use the ItemPopup.MaxDropDownItemCount property instead.


TcxCustomGridTableFiltering.MRUItemsList

TcxCustomGridTableFiltering          See Also

Specifies whether the filter dropdown for the filter panel should be displayed within the filter panel.

property MRUItemsList: Boolean;

Description

If the MRUItemsList property’s value is True, the filter dropdown for the filter panel is displayed.  Similar to the filter dropdowns for view items (columns or card rows), this filter dropdown displays all the filter criteria that were applied to the current view.  The filter criteria in this case are considered to be items.  The most recently applied filter criteria (used items) are displayed at the top of the list.

The maximum number of used items that can be displayed within the filter dropdown for the filter panel is specified by the MRUItemsListCount property’s value.

The number of used items which are displayed within the filter dropdown simultaneously is specified by the View’s FilterBox.MRUItemsListDropDownCount property.

The default value of the MRUItemsList property is True.


TcxCustomGridTableFiltering.MRUItemsListCount

TcxCustomGridTableFiltering          See Also

Specifies the maximum number of most recently applied filter criteria that are displayed within the filter dropdown for the filter panel.

property MRUItemsListCount: Integer;

Description

The filter dropdown for the filter panel displays a list of the most recently applied filter criteria or used items (MRU list for short).  Each time after a new filter criterion (used item) has been applied to a view it becomes the current filter criterion.  The next time another filter criterion is applied the current filter criterion is added to the top of the MRU list thus increasing the number of items in the list.  This takes place until the number of items reaches the MRUItemsListCount property’s value.  After this has happened, selecting an item results in this item being added to the top of the MRU list and the bottom item in the list being deleted.  The MRUItemsListCount property’s value of 0 indicates that the list’s capacity is not restricted in any way.

The View’s FilterBox.MRUItemsListDropDownCount property’s value specifies the number of items that can be displayed simultaneously within the filter dropdown for the filter panel.

The default value of the MRUItemsListCount property is specified by the cxGridFilterDefaultMRUItemsListCount constant.


TcxCustomGridTableFiltering.MRUItemsListDropDownCount

TcxCustomGridTableFiltering          See Also

Specifies how many filter criteria are simultaneously displayed within the filter dropdown for the filter panel.

property MRUItemsListDropDownCount: Integer;

Description

This property is obsolete and used for compatibility purposes.  Use the View’s FilterBox.MRUItemsListDropDownCount property instead.


TcxCustomGridTableFiltering.Position

TcxCustomGridTableFiltering

Specifies the filter panel ‘s vertical position.

type

  TcxGridFilterPosition = (fpTop, fpBottom);

property Position: TcxGridFilterPosition;

Description

This property is obsolete and used for compatibility purposes.  Use the View’s FilterBox.Position property instead.


TcxCustomGridTableFiltering.Visible

TcxCustomGridTableFiltering

Specifies when the filter panel is visible.

type

  TcxGridFilterVisible = (fvNever, fvNonEmpty, fvAlways);

property Visible: TcxGridFilterVisible;

Description

This property is obsolete and used for compatibility purposes.  Use the View’s FilterBox.Visible property instead.


TcxCustomGridTableFiltering.RunCustomizeDialog

TcxCustomGridTableFiltering          See Also

Invokes the filter customization dialog.

procedure RunCustomizeDialog(AItem: TcxCustomGridTableItem = nil);

Description

The RunCustomizeDialog method’s behavior depends on the AItem parameter value.  If this parameter’s value is nil or not specified, the method invokes the filter builder dialog for the view.  If you pass a column (or card row) as this parameter, the method’s effect will be the same as choosing the Custom item within the specified column’s filter dropdown.  This method fires the OnFilterDialogShow event.


TcxGridFilterMRUItem
TcxGridFilterMRUItem Object

Hierarchy          Properties          Methods

Represents an item in the lists of most recently used items.

Unit

cxGridCustomTableView

TcxGridFilterMRUItem = class(TcxMRUItem)

Description

A list of most recently used items is used to maintain the choices (such as filtering options) made by end-users for future use or tracking activities.  The TcxMRUItem class is the base class for classes which represent this kind of items.  The Equals abstract function is the only member which is introduced by the TcxMRUItem class.  When implemented in descendant classes this function determines whether the item which is represented by an instance of the TcxMRUItem class is equal to the specified item.


TcxGridFilterMRUItem Hierarchy
Hierarchy

TcxMRUItem

     |


Properties for TcxGridFilterMRUItem
TcxGridFilterMRUItem Properties

TcxGridFilterMRUItem          Legend

In TcxGridFilterMRUItem


Methods for TcxGridFilterMRUItem
TcxGridFilterMRUItem Methods

TcxGridFilterMRUItem          Legend

Derived from TcxMRUItem

Equals


TcxGridFilterBox
TcxGridFilterBox Object

Hierarchy          Properties          See Also

Represents settings that determine the appearance aspects of the filter box within grid views.

Unit

cxGridCustomTableView

TcxGridFilterBox = class(TcxCustomGridOptions)

Description

The TcxGridFilterBox class declares a set of properties which determine the various appearance aspects of the grid view's filter box (such as its general appearance, position, the availability of the filter customization button, etc.).  Use the View’s FilterBox property to specify the properties of the filter box within the View.


TcxGridFilterBox Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |


Properties for TcxGridFilterBox
TcxGridFilterBox Properties

TcxGridFilterBox          Legend

In TcxGridFilterBox

CustomizeDialog

MRUItemsListDropDownCount

Position

Visible

Derived from TcxCustomGridOptions

GridView


TcxGridFilterBox.CustomizeDialog

TcxGridFilterBox

Specifies whether the Customize button is displayed within the filter panel.

property CustomizeDialog: Boolean;

Description

If the CustomizeDialog property value is True, the filter panel displays the Customize button that can be clicked to invoke the filter control dialog.  If this property’s value is False, end-users cannot invoke the filter control dialog.

The default value of the CustomizeDialog property is True.


TcxGridFilterBox.MRUItemsListDropDownCount

TcxGridFilterBox          See Also

Specifies how many filter criteria are simultaneously displayed within the filter dropdown for the filter panel.

property MRUItemsListDropDownCount: Integer;

Description

The MRUItemsListDropDownCount property sets the height of the filter dropdown for the filter panel in terms of used items (applied filer criteria).  Note that the actual height may be less than that specified by the MRUItemsListDropDownCount property if the specified number is greater than the total number of items to be displayed (as specified by the MRUItemsListCount property).

If the number of the items to be displayed exceeds the MRUItemsListDropDownCount property’s value, the filter dropdown displays scrollbars which allow end-users to access all the items.

If the MRUItemsListDropDownCount property’s value is set to 0, the filter dropdown for the filter panel displays all the items simultaneously.  Negative values are not accepted (the property’s value is automatically set to 0).

The default value of the MRUItemsListDropDownCount property is 0.


TcxGridFilterBox.Position

TcxGridFilterBox

Specifies the filter panel‘s vertical position.

type

  TcxGridFilterPosition = (fpTop, fpBottom);

property Position: TcxGridFilterPosition;

Description

Use the Position property to specify where the filter panel should be displayed.  The table below describes the values that can be assigned to this property.

Value	Meaning
fpTop	The filter panel is displayed at the top of the view.
fpBottom	The filter panel is displayed at the bottom of the view.
Note:	The filter panel’s visibility is controlled by the Visible property.

The default value of the Position property is fpBottom.


TcxGridFilterBox.Visible

TcxGridFilterBox

Specifies when the filter panel is visible.

type

  TcxGridFilterVisible = (fvNever, fvNonEmpty, fvAlways);

property Visible: TcxGridFilterVisible;

Description

The table below describes the values that can be assigned to the Visible property.

Value	Meaning
fvNever	The filter panel is always invisible.
fvNonEmpty	The filter panel is visible when filter conditions are applied to the view.
fvAlways	The filter panel is always visible.
Note:	You can specify the filter panel’s position within the view using the Position property.

The default value of the Visible property is fvNonEmpty.


TcxGridFilterValueList
TcxGridFilterValueList Object

Hierarchy          Methods

The TcxGridFilterValueList class represents a list of filter items that are used in a filter dropdown.

Unit

cxGridCustomTableView

TcxGridFilterValueList = class(TcxDataFilterValueList)

Description

The TcxGridFilterValueList class provides a Load method with an implemented behavior specific to the grid control.  This method creates a list of filter items that are then added to the filter dropdown.

The ApplyFilter method is designed to programmatically filter items in the view at a higher level, rather than accomplishing this task at the data controller layer.


TcxGridFilterValueList Hierarchy
Hierarchy

TcxDataFilterValueList

     |

TcxGridFilterValueList


Methods for TcxGridFilterValueList
TcxGridFilterValueList Methods

TcxGridFilterValueList          Legend

In TcxGridFilterValueList

 ApplyFilter

 Load


TcxGridFilterValueList.ApplyFilter

TcxGridFilterValueList

Applies the AFilterList filter to AItem.

procedure ApplyFilter(AItem: TcxCustomGridTableItem; AIndex: Integer; AFilterList: TcxFilterCriteriaItemList; AReplaceExistent, AAddToMRUItemsList: Boolean);

Description

The AItem parameter specifies an item whose values are to be filtered;

The AIndex parameter specifies an index of the filter condition in the filter dropdown;

The AFilterList parameter specifies the list of filter criteria.  Note: To add the specified filter item to the root filter list (see the Filter.Root property), set the AFilterList parameter to nil;

The AReplaceExistent parameter specifies whether to clear the AFilterList list before a new criterion is added.  Set the AReplaceExistent to True, to remove existing filter items.  Otherwise, a new filter item will be added to the existing list;

The AAddToMRUItemsList parameter specifies whether the AIndex filter item will be added to the list of most recently used filter items.  The most recently used filter items are shown at the top of the filter dropdown.  Set the AAddToMRUItemsList to True to add the AIndex filter item to that list.

Note: before using the ApplyFilter method, invoke the Load method to populate the filter list.


TcxGridFilterValueList.Load

TcxGridFilterValueList

Populates the filter list with filter items.

procedure Load(AItem: TcxCustomGridTableItem; AInitSortByDisplayText: Boolean = True; AUseFilteredValues: Boolean = False); virtual;

Description

A filter dropdown is populated with filter items from the list (see TcxFilterValueList) created by the Load method.

Filter items are also used by the ApplyFilter method.  The ApplyFilter method is designed to programmatically apply filtering to AItem as an end-user does through the filter dropdown.

The AItem parameter specifies the item whose values are used to populate the filter list;

The AInitSortByDisplayText parameter specifies whether filter items in the filter list are ordered by the display text or by value (see the SortByDisplayText property).  Set the AInitSortByDisplayText parameter to True to sort filter items by display text;

The AUseFilteredValues parameter specifies whether all filter items, or only those that were used in the filter prior to the call, are added to the filter list.  Set the AUseFilteredValues parameter to True to add only filter items from the previously used filter.


Component Editor

See Also

This topic describes the Structure Navigator and the Component Editor used to customize the grid control at design time.  This includes specifying the structure for the representation of multiple datasets (including master-detail relationships), connecting to datasets, retrieving columns and adding summaries.  Using the Component Editor together with the Object Inspector allows you to adjust most of the properties of grid elements without writing a single line of code.  The Component Editor represents the grid's structure in a regular form.

Before reading this topic, you must understand the terms "view" and "level" as the base constituents of our grid control.  Grid levels are objects used for the creation of tree-like structures to represent data.  Using levels you can represent, for instance, master-detail relationships between datasets.  Master datasets are displayed at the upper grid level, while detail datasets are placed at the lower grid level.  But grid levels cannot display data themselves.  Grid views are responsible for drawing data in a specific form (table, banded table, card view), for connecting to data storage and editing its data.  To get more information, refer to the Views topic.  For a view to be displayed, it must be associated with a level.

But levels are not only used to create master-detail relationships, they can present information from independent data sources in a single grid control, as well.

Structure Navigator

When your grid control is placed onto a form, it already contains a grid level (TcxGridLevel) and a DB table view (TcxGridDBTableView), by default.

The Structure Navigator, at the right bottom corner of the component, describes the grid level structure.  Currently, the grid control shown above only contains one grid level (cxGrid1Level) with an associated DB table view (cxGrid1DBTableView).  To display the properties of the level or the table view in the Object Inspector, click on the corresponding label in the Structure Navigator (alternatively, you can use the Object TreeView).  The following image shows the Object Inspector displaying the properties of a grid level:

Every label provides an appropriate context menu, thus allowing you to customize the grid control further.

The context menu for a view label allows you to:

•	Create All Columns

Creates columns based on the corresponding dataset fields.  This option is available if a view is linked to an active dataset via the DataController.DataSource property.

•	Delete All Columns

Destroys all columns within a view, if any.

•	Delete View

Deletes the current view including all the columns it owns.

•	Set As Default

This command stores the view’s OptionsBehavior, OptionsCustomize, OptionsData, OptionsSelection, OptionsView and Filtering option sets in the system registry.  Options are stored separately for banded table, table and card views.  These options are then used as the default for creating subsequent instances of the same view class.

•	Edit Layout And Data…

Opens the Layout and Data Editor dialog allowing you to customize the view's layout (resize columns, specify the column's width and visibility, group by specific columns, apply sorting, etc) and enter data for unbound views.  The view layout customization is especially useful when customizing detail views.

The context menu for a level label provides the following options:

•	Create View

Creates a new view within a grid control and assigns it to the current level.  If the level already contains a view, the new view replaces the old one.  The old view is not deleted from the grid view collection.  The ExpressQuantumGrid provides several types of view.  DB views work with datasets, while non data-aware views work for unbound and provider modes.

•	Add Level

Creates a new child grid level for the current level.  Child levels are used to implement master-detail relationships.  Each level can have multiple details linked by specific key field names.

•	Delete Level

Deletes the current level.

The grid context menu contains only one option:

•	Add Level

Adds a new grid level at the root nesting level for displaying data from another data source.

Component Editor

The Component Editor provides more capabilities than the Structure Navigator when adjusting a grid control.  To open the Component Editor, you can:

•	press the Customize button in the Structure Navigator

•	double-click the grid control

•	select the Edit option from the grid context menu

The editor allows you to access the properties of levels and views and also:

•	access the views collection (not only those assigned to levels);

•	access the columns collection (in a table view) or rows (in a card view) and adjust their properties;

•	change the column/row position within a view;

•	specify summaries (for a table view).

The Component Editor has several panels.  You can switch to a particular panel by clicking the corresponding tab.

The Structure panel is similar to the Structure Navigator and displays a tree-like structure of data.  You can click each label with the left mouse button to display the properties of the corresponding object in the Object Inspector.  When a view is selected, its items (columns in table views or rows in card views) are listed within the right panel.

The context menus for the grid, level and view labels are the same as in the Structure Navigator.

The Structure panel contains two buttons:

•	Add Level

Adds a child level to the selected grid or level.  If a grid label is selected, the level is added at the root nesting level.  If a level label is selected, a child level is created.

•	Delete Level

Deletes the currently selected grid level.

The Views panel contains all the views created in the grid.

Two buttons are provided:

•	Add View

Adds a new view to the grid view collection.  For a view to be displayed in a grid, it must be assigned to a level.

•	Delete View

Deletes the currently selected view

•	Edit View Layout and Data…

Invokes the Layout and Data Editor dialog which lets you customize the currently selected view’s layout and enter data (for the unbound view only).

If a table view is selected, the right pane contains two tabs: Columns and Summary.  For a card view, only the Rows panel is displayed.  The Rows panel is the equivalent of the Columns panel in a table view.  If a banded table view is selected, the Bands tab is displayed.

The Columns panel provides access to all the columns created.  You can create a column manually by pressing the Add button.  If a view is connected to an active dataset, it is possible to create columns for all dataset fields via the Retrieve Fields button.

When a column is created manually, you need to connect it to a dataset field by setting its DataBinding property attributes.  When columns are created via the Retrieve Fields button, the DataBinding is set automatically.

Other buttons in the Columns panel implement the following operations:

•	Delete

Deletes the selected column(s) from the view

•	Restore Defaults

Restores the width, caption and other properties of the selected columns to their default values.

•	Move Up

Moves the selected column(s) up the list

•	Move Down

Moves the selected column(s) down the list

The Columns panel allows you to select several columns at once and adjust their properties via the Object Inspector.  Use the SHIFT and CTRL keys to select several columns.  You can also change a column’s position by dragging it with the mouse.

The Bands panel allows you to manipulate bands in the same way as the Columns panel.  You can create and delete bands and also arrange the order in which they are displayed (horizontal position).

The Summary panel allows you to specify summaries for a table view.  See the Summaries topic for details of the summary types provided by the ExpressQuantumGrid.  The Create Summaries section shows how to set summaries at design-time and runtime.

There are individual pages in the Summary panel to specify footer and group summaries and to create summary groups for the selected view.  The Footer page allows you to add footer summaries (summaries calculated against all records in a view).

The Add button adds a new summary item to the collection of footer summary items.  A summary item defines on which column a summary should be calculated, the summary kind, position (in effect only for a group summary), format and a field name (for a DB view only).  To adjust an item's properties, just select it and switch to the Object Inspector window.

The Delete button deletes the item(s) currently selected.

ExpressQuantumGrid provides an extremely convenient way of specifying footer and group summaries for a particular column.  All you need to do is to select the column which you want to calculate a summary for and set its Summary property.  By assigning the summary kind to calculate to the specific column’s property (Summary.FooterKind, Summary.GroupFooterKind and Summary.GroupKind) you automatically designate the summary type and the view element where the summary value will be displayed (a footer panel, group footer or group row, correspondingly).  Use the FooterFormat, GroupFooterFormat and GroupFormat properties to customize the format of the resulting string for these summaries.  For more information, see the Creating Summaries topic.

The Default For Groups page is similar to the Footer page.  Here you can add a new summary item to the collection of default group summaries (summaries calculated against a group of records when data in a view is grouped by any column).

To calculate summaries when data is grouped by particular columns, use summary groups instead.  You can access these via the Groups panel.

The Groups panel gives you the ability to create summary groups.  A summary group associates individual grouping columns with specific group summaries.  When data in a view is grouped by any of the grouping columns referenced by a summary group (these are linked columns), the corresponding group summaries are evaluated.  It is possible to create multiple summary groups, each of which determines the set of group summaries to calculate when data is grouped by the corresponding (linked) columns.

The Groups panel contains the following lists:

•	Groups

Shows the collection of all summary groups in the selected view.

•	Items

Lists the summary items which determine the summaries to calculate.  This panel is similar to the Items list in the Default For Groups panel.

•	Unlinked Columns

Contains all the columns the selected view owns.  This list allows you to select the columns associated with the summary items.

•	Linked Columns

Specifies columns selected from the Unlinked Columns list.  When data in a view is grouped by any of these columns, the summary items added via the Items list will be evaluated.


View Layout

ExpressQuantumGrid gives you the ability to customize a view's layout and enter data (for unbound (banded) table and card views only) at design time.  In this section we will consider customizing the view's layout.  For more information about entering data into unbound (non data-aware) views at design time, see the Data Editing topic.

In order to customize the view's layout, the "Layout and Data Editor" dialog is used.  Click the "Edit Layout and Data…" item of the view’s context menu to invoke this dialog.  Note that for ChartViews this dialog only lets you preview their appearance in a form.  That is the following information relates to (banded) table and card views only.

Also you can select a specific view from the Views panel in the Component Editor and click the Edit View Layout and Data… button to invoke the corresponding dialog.

You can customize a view directly on the form.  When a grid displays a master-detail relationship, you can expand a specific master row and this will open a clone view that corresponds to the selected row. The EQGrid allows you to set up the layout of individual clones which will result in the immediate modification of the corresponding pattern view and all of the created clone views.

The Layout and Data Editor gives you the ability to customize any grid view: master, detail and even views not currently connected to any grid level (for instance, those that are created within a TcxGridViewRepository component).  When you edit the layout of a detail view, these changes are then applied to all view clones.

For (banded) table views, you are able to:

•	specify the grouping order

•	apply sorting to columns

•	resize columns and change their position

•	hide specific columns (this sets their Visible property to False)

•	arrange bands (for banded table views only)

The Layout and Data Editor contains the "Save layout" checkbox and three buttons:

•	The Columns Customization button (Rows Customization for card views)

Activates the Customization form and this displays hidden columns and bands (for a banded table view only).  When the Customization form is visible, you can drag any column off the column header panel and this will remove the column from the view.  Hiding a column in the Customization form sets its Visible property to False and vice versa.  You will see a hidden column in the Customization form unless its VisibleForCustomization property is set to True.  To display the Customization form at runtime, set the view’s Controller.Customization property to True.

You can bring a specific column back to the view by dragging it from the Customization form onto the column header panel.  Similarly, you work the same way with bands in a banded table view.

•	The Ok button

Applies layout changes to a grid view on the form (only when the ‘Save layout’ checkbox is checked) and closes the dialog.

•	The Cancel button

Discards any changes made to the layout and closes the dialog.

For non data-aware views the ‘Save data‘ checkbox is also displayed.  See the Data Editing section for additional information as this checkbox is used to indicate whether the data for an unbound view will be saved when you click the Ok button.

Grouping

To group by a specific column, drag its header onto the Group panel.  The panel is visible if the view’s OptionsView.GroupByBox property is set to True.  The Group panel displays all columns used to group data:

Moving a column to the Group panel sets its Visible property to False.

Sorting

To sort by a specific column, click its header.  The first click on a column header sorts data in ascending order and the second in descending order, etc.  To clear sorting by a column, click the column's caption whilst holding the Ctrl key down.

You can also sort data by multiple columns.  To do this, click on column headers while holding down the Shift key.

The current sort order is indicated by a small arrow which is displayed adjacent to the right column header’s edge.  The Up arrow indicates ascending order, while the Down arrow indicates descending order.

Note, that grid columns used for grouping are always sorted.

Resizing columns

You can change the width of a column by dragging its right edge:

If you need to set a column's width according to the size of its contents, double-click its right edge.  This will find the cell with the widest contents and the column's width will then be changed to accommodate it.  At runtime, use the ApplyBestFit method to get the same effect.

Moving columns

To change the order of columns within the view, drag the column header to the required position.  You can change the column's position within the view and within the Group panel.

For card views, the Layout editor allows you to change the card's width.

To specify the card's width, click and drag the vertical separator line to the left or right.

When the LayoutDirection property of the card view is set to ldVertical, a card view displays only horizontal separator lines.  In this case, click the space between two adjacent horizontal cards to change their widths.

Customizing bands

Similar to operations with columns, bands can be easily moved, resized and arranged within the view as nested bands.


Default Values for View Options

See Also

Every grid view (BandedTableView, TableView, CardView or ChartView) provides a specific set of options controlling its appearance and behavior.  EQGrid allows you to save the default values of most of its options to the registry.  When a new view is created, its options will be set to these default values.

To save the default values for a view’s options, you can use the view’s context menu provided by the Structure Navigator, for instance:

Adjust the view’s OptionsBehavior, OptionsCustomize, OptionsData, OptionsSelection, OptionsView, Filtering, Preview and NavigatorButtons properties and click the Set As Default item from the view’s context menu.  This stores the current view options to the registry.  For instance, in Delphi 6, the path to the options is defined as follows:

HKEY_CURRENT_USER\Software\Borland\Delphi\6.0\Property Editors\TcxGridViewTemplate


Converting to ExpressQuantumGrid

ExpressQuantumGrid provides an Import dialog at design time for importing settings from third-party grid controls and converting them to the native properties of the ExpressQuantumGrid.  Three types of grid components can be imported to ExpressQuantumGrid:

•	ExpressQuantumGrid3 (TdxDBGrid) and ExpressQuantumGrid3 Layout (TdxDBGridLayout)

•	standard TDBGrid

•	W2W InfoPowerGrid 3000 (TwwDBGrid)

You can use the links above for more information on importing from these specific grid controls.

Descendants of these grid controls can also be imported to ExpressQuantumGrid using the Import dialog.  New properties (if there are any) that are declared in descendants will be ignored by the converter and no exception is raised in this case.

Data within the ExpressQuantumGrid is presented with the help of a view object.  The converter creates a new view within the ExpressQuantumGrid for displaying the contents of the grid control being imported.  The converter creates either a table view (TcxGridDBTableView) or a banded table view (TcxGridDBBandedTableView) depending on the type of grid control being imported and that grid’s configuration:

Grid control	An EQGrid view used to display the contents of the grid being imported
TdxDBGrid and TdxDBGridLayout	A table or banded table view is created depending on the grid’s properties.  Refer to the Importing ExpressQuantumGrid3 topic for more details.
TDBGrid	A table view.
TwwDBGrid	A banded table view.

The look & feel of the ExpressQuantumGrid is maintained by a number of style properties.  When a grid control being imported contains color and font attributes that are set to non-default values, these attributes are transformed into style objects.  Once these styles have been created, they are assigned to the respective grid elements.  Note that importing styles is optional.  You can disable this in the Import dialog.

To invoke the Import dialog, right-click the import target TcxGrid control and select the Import… option from the context menu.  The panel on the left of the dialog lists all the supported grid components found in the current form.

The easiest way to perform the conversion is to double-click a source grid in this list or select the source grid and click the Import button.

This destroys all existing levels and views in the target TcxGrid control and creates a new level-view pair for displaying data to match the source grid (levels and views are discussed in the Data Representation topic).  Then the converter imports columns and various grid properties (event handlers are not imported).

In addition, if a grid control contains color and font attributes set to non-default values, they are imported as EQGrid styles represented by TcxStyle objects and are applied to corresponding TcxGrid elements.  By default, the converter creates a new style repository (a TcxStyleRepository component) for storing these styles.

The Levels and Styles pages allow you to customize the import process.

The Levels panel

The Levels panel displays the Structure Navigator which describes the logical structure of the grid's levels.  Each level is associated with a view displaying data from a specific data source.  When importing a grid control, a new view is created to display its contents.  You can use the Structure Navigator to specify the destination level for this view.  The name of the currently selected destination level is displayed at the top of the Structure Navigator.

By default, the destination level is set to the target grid control itself meaning that the converter will create a new root level and associate a new view with it.  The converter will also delete all other existing levels and views.

You can set the destination level to any existing Level object (levels are painted within gray-blue boxes).  This will destroy an old view linked to the level and will associate a new view with it.

The converter reads the Delete All Sublevels check-box's state to determine whether child levels need to be deleted when importing to a specific grid level.  If the Delete All Sublevels is checked, all child levels (and their views) at the currently selected destination level are disposed of.  Otherwise, the child levels are not affected.

Importing grids to different grid levels allows you to establish master-detail and sibling relationships between data sources.  Note that properties controlling the master-detail relationships must be set manually.  You can refer to the Master-Detail section for more information.

The Styles panel

The Styles panel allows you to control the importing of color and font settings.

Unlike other grid controls, the appearance of the ExpressQuantumGrid is maintained by a number of style properties.  Usually you create style objects (TcxStyle) via a style repository and assign them to style properties thus specifying the look & feel of the required elements.  The converter will do this for you.  It converts color and font attributes to style objects while adding them to a style repository.  Styles are assigned to the corresponding style properties of the target grid control.  Styles are not created for font and color attributes which are set to their default values.

Importing styles is optional.  You can stop styles from being imported by unchecking the Import Styles check box.  In this case, only properties that affect the representation of data are imported.

By default, styles are imported.  You can choose between creating styles either within a new style repository or within an existing one.  Selecting the Create New StyleRepository option enables the edit box.  Use it to specify the name of the new style repository.  The Use Existing StyleRepository option is a combo-box listing all the style repositories that can be found on the form.

You can refer to the tutorials shipped with the ExpressQuantumGrid which describe working with the Import dialog step by step.


Importing ExpressQuantumGrid3

This topic provides general information on the properties imported from ExpressQuantumGrid3 and ExpressQuantumGrid3 layout components.  Working with the Import dialog is discussed in the Converting to ExpressQuantumGrid section.  It also provides general information on importing third-party grid controls to the native format of ExpressQuantumGrid.

The conversion utility imports most of the settings from the TdxDBGrid and TdxDBGridLayout components.  Versions 3 and 4 of the Grid control may appear similar in their outwards appearances but architecturally they are really quite different.  Therefore, not all options can be imported to EQGrid.  You can refer to the Grid3 and Grid4 Equivalents document which describes the main differences and the equivalent properties of the two grid controls.

When an EQGrid3 is imported to an EQGrid, either a table or banded table view is created.  A banded table view (TcxGridDBBandedTableView) is created in the following cases:

•	an EQGrid3 control displays the band header

or

•	an EQGrid3 control contains two or more bands

or

•	the caption of a band specifies a non-empty string

Otherwise, the table view of the TcxGridDBTableView class is used and no bands are imported.

The following grid elements are imported when converting from the EQGrid3 and its layout components:

•	the DataSource property

•	columns and their attributes such as column width, grouping, sorting, summary options and field names.

EQGrid does not provide different column classes like EQGrid3 does.  Instead, the column type is assigned via the PropertiesClass property.  Refer to the EQGrid3 and EQGrid4 Equivalents document for details.

•	bands

Bands are imported only in specific cases (when the converter creates a banded table view) as listed above.

•	options controlling the behavior and appearance of a grid control

These options include:

-	the visibility of footer, group and header panels, preview sections,  grid lines, the indicator, etc.

-	options controlling the ability of an end-user to manipulate the bands and columns

-	multiple data-aware settings

-	font and color attributes

•	summary groups and summary items

Note: A separate TdxDBGrid control must be present on the form when importing a TdxDBGridLayout source component.


Importing TDBGrid

This topic describes the properties imported from the standard Delphi TDBGrid to ExpressQuantumGrid.  See the Converting to ExpressQuantumGrid document which describes working with the Import dialog and gives general pointers on importing third-party grid controls to the native format of EQGrid.

The converter imports a source TDBGrid into a new table view represented by the target TcxGridDBTableView class.

The following grid elements are imported from a TDBGrid control by the Import tool:

•	the DataSource property

•	columns and their attributes such as column width, caption, alignment, and visibility status

The type of a column being created is based upon TColumn (a TDBGrid column) properties according to the following table.  The column type is assigned via the PropertiesClass property. You can refer to the Data Editing Using Inplace Editors for more information on editing grid cells.

The following table describes the column types assigned based on combinations of TColumn properties:

TColumn properties	Column type assigned to a corresponding TcxGrid column
ButtonStyle = cbsAuto AND Field.FieldKind = fkLookup	A lookup combo box editor (TcxLookupComboBoxProperties).
ButtonStyle = cbsAuto AND Field.FieldKind <> fkLookup AND PickList.Count > 0	A combo box editor (TcxComboBoxProperties).
ButtonStyle = cbsAuto AND Field.FieldKind <> fkLookup AND PickList.Count = 0	A text editor (TcxTextEditProperties).
ButtonStyle = cbsEllipsis	A button editor (TcxButtonEditProperties).
ButtonStyle = cbsNone AND (ReadOnly = True OR  Alignment <> taLeftJustify)	A text editor (TcxTextEditProperties).

If your TColumn does not meet any of the conditions listed in this table, then the new column's type will be exclusively determined by the field type.  This is discussed in the FieldName topic of this help system.

•	grid options

The next table describes the TDBGrid options imported to ExpressQuantumGrid.  The second column specifies the properties of an EQGrid control which are set according to the flags included in the TDBGrid.Options property (unless otherwise indicated, an EQGrid property is set to True or False if a corresponding TDBGrid flag is enabled or disabled, respectively).

Flags enabled in the TDBGrid.Options property	The corresponding EQGrid property
dgAlwaysShowEditor	The view’s OptionsBehavior.AlwaysShowEditor property.
dgAlwaysShowSelection	The view’s OptionsSelection.HideSelection property. This property is set to False, if the flag is enabled.  Otherwise, it is set to True.
dgCancelOnExit	The view’s OptionsData.CancelOnExit property.
dgColumnResize	The view’s OptionsCustomize.ColumnHorzSizing property.
dgColLines, dgRowLines	The view’s OptionsView.GridLines property. It is set to glNone, glHorizontal, glVertical or glBoth based on the flag combination.
dgConfirmDelete	The view’s OptionsData.DeletingConfirmation property.
dgEditing	The view’s OptionsData.Editing property.
dgIndicator	The view’s OptionsView.Indicator property.
dgMultiSelect	The view’s OptionsSelection.MultiSelect property.
dgRowSelect	The view’s OptionsSelection.CellSelect property. This property is set to False, if the flag is enabled.  Otherwise, it is set to True.
dgTabs	The view’s OptionsBehavior.FocusCellOnTab property.
dgTitles	The view’s OptionsView.Header property.
•	color and font settings

The look & feel of EQGrid is maintained by a number of style properties which identify the background and foreground colors and font attributes specific to particular grid elements.  The converter imports the color and font settings of a TDBGrid control as style objects and applies them to the corresponding TcxGrid elements:

Color and font settings of TDBGrid	The corresponding EQGrid style property(s)
TDBGrid.Color and TDBGrid.Font	The view’s Styles.Content style.
TDBGrid.FixedColor and TDBGrid.TitleFont	The view’s Styles.Header and Styles.Indicator styles.
TColumn.Color and TColumn.Font	The column’s Styles.Content style.
TColumn.Title.Color and TColumn.Title.Font	The column’s Styles.Header style.


Importing TwwDBGrid

This topic describes the properties imported from a source TwwDBGrid to a target ExpressQuantumGrid.  See the Converting to ExpressQuantumGrid document which describes working with the Import dialog and provides general information on importing third-party grid controls to the native format of the EQGrid.

When importing from a TwwDBGrid control, a banded table view (TcxGridDBBandedTableView) is created.  TwwDBGrid bands are not imported.  Instead, a single band is created and all columns are placed in this band.  You can refer to the Banded Table View topic if you need to customize your banded table view depending on your needs.

The following grid elements are affected when importing TwwDBGrid:

•	the DataSource property

•	grid options

The converter imports the options provided by the TwwDBGrid.Options and TwwDBGrid.KeyOptions properties.  The following tables describe the EQGrid properties which are affected by the conversion (unless otherwise indicated, an EQGrid property is set to True or False if the corresponding TwwDBGrid flag is enabled or disabled respectively).

Flags enabled in the TwwDBGrid.Options property	The corresponding EQGrid property
dgAlwaysShowEditor	The view’s OptionsBehavior.AlwaysShowEditor property.
dgAlwaysShowSelection	The view’s OptionsSelection.HideSelection property. This property is set to False, if the flag is enabled.  Otherwise, it is set to True.
dgCancelOnExit	The view’s OptionsData.CancelOnExit property.
dgColLines, dgRowLines	The view’s OptionsView.GridLines property. This property is set to glNone, glHorizontal, glVertical or glBoth based on the flag combination.
dgColumnResize	The view’s OptionsCustomize.ColumnHorzSizing property.
dgConfirmDelete	The view’s OptionsData.DeletingConfirmation property.
dgEditing	The view’s OptionsData.Editing property.
dgIndicator	The view’s OptionsView.Indicator property.
dgMultiSelect	The view’s OptionsSelection.MultiSelect property.
dgRowSelect	The view’s OptionsSelection.CellSelect property. This property is set to False, if the flag is enabled.  Otherwise, it is set to True.
dgShowFooter	The view’s OptionsView.Footer property.
dgTabExitsOnLastCol	The view’s OptionsBehavior.FocusCellOnCycle property. This property is set to False, if the flag is enabled.  Otherwise, it is set to True.
dgTabs	The view’s OptionsBehavior.FocusCellOnTab property.
dgTitles	The view’s OptionsView.Header property.
Flags enabled in the TwwDBGrid.KeyOptions property	The corresponding EQGrid property
dgAllowDelete	The view’s OptionsData.Deleting property.
dgAllowInsert	The view’s OptionsData.Inserting property.
dgEnterToTab	The view’s OptionsBehavior.GoToNextCellOnEnter property.
•	columns and their attributes (field name, width, caption and read-only status)

A TwwDBGrid column specifies the type of a column being created via the Control Type.  When an EQGrid column is created, its type (a class that has edit properties specific to the data type of the column) is set via the PropertiesClass property.  Refer to the Data Editing Using Inplace Editors topic for more information.

Control Type of a TwwDBGrid column	Column type assigned to a corresponding TcxGrid column
Bitmap	An image editor (TcxImageProperties).
CheckBox	A check box (TcxCheckBoxProperties).
URL-Link	A hyper-link editor (TcxHyperLinkEditProperties).
RichEdit	A memo control (TcxMemoProperties).
If the control type is set to CustomEdit, the type of a corresponding TcxGrid column is defined by the editor assigned to a TwwDBGrid column.

Editor assigned to a TwwDBGrid column	Column type assigned to a corresponding TcxGrid column
TwwDBSpinEdit	A spin editor (TcxSpinEditProperties).
TwwDBEdit	A text editor (TcxTextEditProperties).
TwwDBComboBox	Either an MRU-editor or image combo-box is used based upon the TwwDBComboBox.History.Enabled attribute value.  If the Enabled property is set to True, an MRU-editor (TcxMRUEditProperties) is applied.  Otherwise, an image combo-box (TcxImageComboBoxProperties) is used.
TwwDBComboDlg	A button editor (TcxButtonEditProperties).
TwwDBLookupCombo	A lookup combo-box (TcxLookupComboBoxProperties).
TwwDBLookupComboDlg	A lookup combo-box (TcxLookupComboBoxProperties).
TwwDBMonthCalendar	A date editor (TcxDateEditProperties).
TwwDBDateTimePicker	A date editor (TcxDateEditProperties).
TwwCheckBox	A checkbox (TcxCheckBoxProperties).
TwwRadioGroup	A radio-group is imported as an image combo box (TcxImageComboBoxProperties).
•	color and font settings

The look & feel of EQGrid is maintained by a number of style properties which identify the background and foreground colors and font attributes specific to particular grid elements.  The converter imports the color and font settings of the TwwDBGrid control as style objects (except for the grid line colors) and applies them to the corresponding TcxGrid elements.  The next table lists the EQGrid properties which are affected by importing color and font attributes:

Color and font settings of TwwDBGrid	The corresponding EQGrid property(s)
TwwDBGrid.Color and TwwDBGrid.Font	The view’s Styles.Content style.
TwwDBGrid.TitleColor and TwwDBGrid.TitleFont	The view’s styles: - Styles.Header - Styles.Footer - Styles.Background - Styles.Indicator
TwwDBGrid.LineColors.HighlightColor	The view’s OptionsView.GridLineColor property.
TwwDBGrid.LineColors.ShadowColor	The view’s OptionsView.GridLineColor property. (The ShadowColor property is imported only if the HighLightColor property specifies a non-default value).
TwwDBGrid.PaintOptions.ActiveRecordColor	The view’s Styles.Selection property.
TwwDBGrid.PaintOptions.AlternatingRowColor	The view’s Styles.ContentOdd property.


Footer Panel

Footer panels are displayed at the bottom of table and banded table views.  Commonly, such panels are used to display total summaries but you can also display any custom information you need.

Feature	Related Members
Visibility	The view’s OptionsView.Footer property.
Appearance	The footer panel’s look and feel depends upon the grid control’s LookAndFeel property settings.  The panel’s style and background bitmap can be changed using the view’s Styles.Footer and BackgroundBitmaps.Footer properties.  Note that these properties affect both the footer panel and group footer panels.  If you need to provide a unique style for the footer panel only, handle the view’s Styles.OnGetFooterStyle event.  The event’s ARecord parameter is nil if the footer panel is being processed.  Note that this event also enables you to set styles for the footer panel’s cells.
Custom Draw	Handle the view’s OnCustomDrawPartBackground event.  The event’s AViewInfo parameter is of the TcxGridFooterViewInfo type if the footer panel is about to be painted.  If you need to custom paint footer cells, handle the view’s OnCustomDrawFooterCell event.
Content	If you need to display custom information within the footer panel, handle the OnCustomDrawPartBackground event.  If this event is not handled, the footer panel displays the total summaries specified.  Please refer to the Summaries topic for additional information.
Layout	The footer panel’s height depends on the style (font settings, in particular) that is assigned.  If the view’s OptionsView.FooterAutoHeight option is enabled the footer panel is automatically enlarged vertically when a summary value's text doesn’t fit into the footer cells.


Group Footer Panel

If enabled, group footers are displayed under each group of rows when a view is grouped.  Commonly, these panels are used to display group summary values for particular columns.

Feature	Related Members
Visibility	The view’s OptionsView.GroupFooters property.
Appearance	The group footer panels’ look and feel depends on the grid control’s LookAndFeel property settings.  The style and background bitmap can be changed using the view’s Styles.Footer and BackgroundBitmaps.Footer properties.  If you need to provide different styles for individual footers and footer cells, handle the view’s Styles.OnGetFooterStyle or Styles.OnGetFooterStyleEx event. Table and banded table views also allow you to provide custom styles for the footer cells corresponding to a particular column.  For this purpose, handle the desired column’s Styles.OnGetFooterStyle and Styles.OnGetFooterStyleEx events.
Custom Draw	To custom paint the entire group footer panel, handle the view’s OnCustomDrawPartBackground event.  The event’s AViewInfo parameter is of the TcxGridRowFooterViewInfo type if a group footer panel is about to be painted. If you need to custom paint footer cells, you can handle either the view’s OnCustomDrawFooterCell event or the desired column’s OnCustomDrawFooterCell event.
Content	If you need to display custom information within a group footer panel, handle the OnCustomDrawPartBackground event.  If this event is not handled, group footer panels display the group summaries specified.  Please refer to the Summaries topic for additional information.
Layout	A group footer panel’s height depends on the style (font settings, in particular) assigned.  If the view’s OptionsView.FooterAutoHeight option is enabled group footer panels are automatically enlarged vertically when a summary value's text doesn’t fit into the footer cells.


Group By Box

The Group By box displays the headers of the columns that are involved in grouping (if any).  This box also enables end users to group a view's data by serving as a drop target for column headers.  If enabled, this box is displayed at the top of the view.

Feature	Related Members
Visibility	The view’s OptionsView.GroupByBox property.
Appearance	The style and background bitmap can be changed using the view’s Styles.GroupByBox and BackgroundBitmaps.GroupByBox properties.  If you need to manually paint the Group By box, handle the view’s OnCustomDrawPartBackground event.
Custom Draw	The view’s OnCustomDrawPartBackground event.  The event’s AViewInfo parameter is of the TcxGridGroupByBoxViewInfo type if the Group By box is about to be painted.
Content	If the view is grouped, the Group By box displays the headers of the columns involved in grouping.  Otherwise, this box displays the string which is specified by the scxGridGroupByBoxCaption constant.
Localization	The text displayed within the Group By box when no grouping is applied is stored in the scxGridGroupByBoxCaption resource string.  You can change this string using the common localization routines.


Indicator

If enabled, the indicator is displayed at the left of a grid view.  The indicator is divided into cells which correspond to the band header panel, column header panel, rows (this area is called the row indicator) and the footer panel.  The cells corresponding to the band header panel and column header panel can serve as the Quick Column Customization button and Quick Band Customization button, respectively.  The cells that correspond to rows display the corresponding row’s state.  Additionally, indicator cells corresponding to rows can be used to expand/collapse master and group rows and their edges can be used to resize rows, if allowed.

Feature	Related Members
Visibility	The view’s OptionsView.Indicator property.
Appearance	The indicator’s look and feel depends on the grid control’s LookAndFeel property settings.  The style and background bitmap can be changed using the view’s Styles.Indicator and BackgroundBitmaps.Indicator properties.
Custom Draw	Handle the view’s OnCustomDrawIndicatorCell event.  The event’s AViewInfo parameter can be of the TcxGridIndicatorHeaderItemViewInfo, TcxGridIndicatorRowItemViewInfo or TcxGridIndicatorFooterItemViewInfo type depending on which indicator cell is about to be painted.
Layout	The indicator’s width can be changed using the view’s OptionsView.IndicatorWidth property.


Column Header Panel

The column header panel is the container for the visible columns’ headers.

Feature	Related Members
Visibility	The view’s OptionsView.Header property.
Appearance	Most commonly, column headers occupy the entire column header panel’s area.  If using a banded table view, there may be cases when there are empty spaces within the column header panel.  The appearance of such empty spaces is set using the Styles.BandBackground and BackgroundBitmaps.BandBackground properties.
Layout	By default, the column header panel’s height depends on the style (font settings, in particular) assigned.  If the OptionsView.HeaderAutoHeight option is enabled, column headers are automatically resized vertically when their captions cannot be completely displayed.  You can also set the column header panel’s height implicitly using the OptionsView.HeaderHeight property.  Note that both of the properties mentioned are in effect only when column headers are arranged into a single row.


Column Header

Column headers are displayed at the top of each column provided that the column header panel is visible.  They display information about the corresponding column’s content and allow end users to manipulate columns, e.g. sort by column values, reorder columns, change columns’ size, etc.

Feature	Related Members
Visibility	Column headers may reside within the column header panel (if the corresponding column is visible), within the customization form (if the corresponding column is hidden) and within the Group By box (if the view is grouped by this column’s values).
Appearance	The look and feel of column headers depends upon the grid control’s LookAndFeel property settings.  The style and background bitmap can be changed using the view’s Styles.Header and BackgroundBitmaps.Header properties.  You can also specify a custom style for a particular column header using the corresponding column’s Styles.Header property.  Lastly, you can specify column header styles by handling the view’s Styles.OnGetHeaderStyle event or the desired column’s Styles.OnGetHeaderStyle event.
Custom Draw	The view’s OnCustomDrawColumnHeader event or a column’s OnCustomDrawHeader event.


Quick Column Customization Button

The Quick Column Customization button is displayed at the intersection of the column header panel and the indicator.  Clicking this button invokes the Quick Column Customization dropdown, which displays column names in a checklist.  Users are able to toggle columns’ visibility and reorder columns by dragging items in the dropdown.  Multiple items can be selected by clicking them while holding down the Shift and Ctrl keys.

Feature	Related Members
Availability	The view’s OptionsCustomize.ColumnsQuickCustomization property.  Note that setting this property to True results in enabling the indicator.
Appearance	The Quick Column Customization button is an indicator cell.  Please refer to the Indicator topic for information on customizing indicator cells’ appearance.
Behavior	The Quick Column Customization dropdown allows users to: • change the visible state of columns without using the Customization Form at runtime or the Object Inspector at design time; • reorder columns in a View by dragging their names in the dropdown.  This functionality is enabled in a View when the View’s OptionsCustomize.ColumnsQuickCustomizationReordering property is set to True.
Dropdown List’s Content	The dropdown list displays all columns whose VisibleForCustomization property value is False.
Dropdown List’s Layout	You can constrain the dropdown’s height using the view’s OptionsCustomize.ColumnsQuickCustomizationMaxDropDownCount property.


Group Row

See Also

Group rows appear when grouping is applied to a view.  Each group row corresponds to a value in a field by whose values the view is grouped.  Group rows can be expanded/collapsed to show/hide data rows that correspond to a particular grouping value.

Feature	Related Members
Appearance	The common style for all group rows is set via a view’s Styles.Group property.  You can also provide styles for individual group rows (e.g. rows corresponding to a particular grouping level) by handling the view’s Styles.OnGetGroupStyle event.  Note that both the property and the event affect both the group row and the corresponding row level indent. The background bitmap for group rows can be set via the view’s BackgroundBitmaps.Group property.
Custom Draw	The view’s OnCustomDrawGroupCell event.  Note that this event doesn’t affect row level indents.
Content	By default, group rows display the corresponding column’s caption, its value and the specified group summaries.  You can specify any custom text to display within group rows by handling the corresponding custom draw event or substitute only the text representing the column’s value using the OnGetDisplayText event.


Preview Section

See Also

MS-Outlook style preview sections allow you to display a memo field’s content or custom memo information for records in an elegant manner.  Such sections are displayed above or under each data row and their width matches total column width.

Feature	Related Members
Visibility	The view’s Preview.Visible property. Note: If a column’s values are displayed within the preview, this column is not displayed with other grid columns.
Content	Preview sections display values from the field that is bound to the column specified by the Preview.Column property.  You can customize preview text by handling that column’s OnGetDisplayText event.
Appearance	The common style for preview sections in a view is set by the view’s Styles.Preview property.  You can also provide styles for individual preview sections by handling the view’s Styles.OnGetPreviewStyle event. The preview sections’ background bitmap can be set via the view’s BackgroundBitmaps.Preview property.
Custom Draw	The view’s OnCustomDrawCell event.  The event’s AViewInfo parameter is of the TcxGridPreviewCellViewInfo type if a preview section is about to be painted.
Layout	A view’s Preview.AutoHeight and Preview.MaxLineCount properties specify the height of preview sections.  The Preview.LeftIndent and Preview.RightIndent properties set the horizontal indentation between the preview text and the view’s edges.  Finally, the Preview.Place property specifies whether to display preview sections above or under the corresponding records.


Column Header Popup Menu

See Also

This menu represents a built-in menu available in the cxGridPopupMenu component.

This menu is invoked when right-clicking a column header.  It allows an end-user to:

•	sort in ascending order;

•	sort in descending order;

•	group using the clicked column;

•	enable/disable the Group By box;

•	remove the clicked column;

•	display the Customization form;

•	set column content alignment;

•	apply the Best Fit feature to the column;

•	apply the Best Fit feature to all columns.

Feature	Related Members
Visibility	The UseBuiltInPopupMenus property of the cxGridPopupMenu component.
Content	All constants for default built-in menu captions are stored in the cxGridPopUpMenuConsts unit.  Refer to the corresponding section in the cxGridPopupMenu: Resource Strings topic for detailed information on constants used in the Column Header Popup Menu. Refer to the Managing Grid Menus topic, for detailed information and sample code on how to add custom menu items to built-in popup menus.


Footer Popup Menu

See Also

This menu represents a built-in menu available in the cxGridPopupMenu component.

This menu is invoked when right-clicking a View’s footer or a group footer panel.  It allows an end-user to specify the required summary types or disable summary calculation via the None option.

Feature	Related Members
Visibility	The UseBuiltInPopupMenus property of the cxGridPopupMenu component.
Content	All constants for default built-in menu captions are stored in the cxGridPopUpMenuConsts unit.  Refer to the corresponding section in the cxGridPopupMenu: Resource Strings topic for detailed information on constants used in the Footer Popup Menu. Refer to the Managing Grid Menus topic, for detailed information and sample code on how to add custom menu items to built-in popup menus.


Group Row Popup Menu

See Also

This menu represents a built-in menu available in the cxGridPopupMenu component.

This menu is invoked when right-clicking a group row.  Group rows can be sorted:

•	by group values (the default option);

•	by group summary values.  In this instance, each menu caption represents the display text.

Feature	Related Members
Visibility	The UseBuiltInPopupMenus property of the cxGridPopupMenu component.
Content	All constants for default built-in menu captions are stored in the cxGridPopUpMenuConsts unit.  Refer to the corresponding section in the cxGridPopupMenu: Resource Strings topic for detailed information on constants used in the Group Row Popup Menu. Use the summary object’s VisibleForCustomization and DisplayText properties to control the general appearance of these menu items and to specify their captions. Refer to the Managing Grid Menus topic, for detailed information and sample code on how to add custom menu items to built-in popup menus.


Card Expand Button

Card scroll buttons allow end users to expand/collapse individual cards.  When a card is collapsed it displays only its caption rows.

Feature	Related Members
Availability	Card expand buttons are available if the view’s OptionsCustomize.CardExpanding property value is True and there is at least one caption row defined.
Appearance	The expand buttons’ appearance depends on the grid control’s LookAndFeel settings.
Layout	Expand buttons are displayed within the top caption row in a card.  Their horizontal alignment within caption rows is specified by the view’s OptionsView.CardExpandButtonAlignment property.


Card Caption Row

Caption rows are non-editable card rows that are most commonly used for card identification.  Caption rows remain visible when collapsing a card.  If you are not using the card expanding feature, caption rows may be utilized to enhance data readability.

Feature	Related Members
Availability	To turn a card row into a caption row, set the desired row’s Kind property to rkCaption.
Appearance	A common style for all caption rows in a view can be set using the view’s Styles.CaptionRow property.  You can also specify styles for individual caption row’s using the Styles.CaptionRow property of card rows.  If you need to provide different styles for caption rows displayed in different cards, handle the view’s OnGetCaptionRowStyle or a card row’s OnGetCaptionRowStyle event. You can provide a background bitmap for caption rows using the view’s BackgroundBitmaps.CaptionRow property.
Custom Draw	The view’s OnCustomDrawCell or a card row’s OnCustomDrawCell event.  The event’s AViewInfo parameter is of the TcxGridCardCaptionRowDataViewInfo type when a caption row’s data cell is about to be painted.  When a caption row’s header is about to be painted, this parameter is of the TcxGridCardCaptionRowCaptionViewInfo type.


Card Row Caption

Card row captions identify card rows just like column headers in table views identify columns.

Feature	Related Members
Visibility	A card row’s Options.ShowCaption property.
Content	By default, row captions display the text specified by the row’s Caption property.
Appearance	The common appearance for all captions can be set via the view’s Styles.RowCaption property.  You can also specify the caption style for individual rows using their Styles.Caption properties.  To specify different styles for captions displayed in different cards, handle the view’s OnGetRowCaptionStyle or a card row’s OnGetCaptionStyle event.
Custom Draw	The view’s OnCustomDrawCell event or a particular card row’s OnCustomDrawCell event.  The event’s AViewInfo parameter is of the TcxGridCardRowCaptionViewInfo type if a row caption is about to be painted.


Card Scroll Button

Card scroll buttons allow end-users to scroll cards’ content when cards do not fit into the view’s area vertically.

Feature	Related Members
Availability	Card scroll buttons are enabled automatically when cards do not fit into the view vertically.
Appearance	The scroll buttons’ look and feel depends on the grid control’s LookAndFeel settings.


Card Separator

Card separators are displayed between card columns to allow end-user card sizing.

Feature	Related Members
Availability	Card scroll buttons are enabled automatically when cards do not fit into the view vertically.
Appearance	The scroll buttons’ look and feel depends on the grid control’s LookAndFeel settings.


Custom Filter Dialog

See Also

The Custom Filter dialog enables filter criteria to be constructed visually for individual columns.  Filter criteria constructed using this dialog can contain up to two filter conditions combined by the AND or OR logical operator.

Feature	Related Members
Availability	End-users can invoke the Custom Filter dialog using the (Custom…) item from the filter dropdown.  Note that if this dialog cannot display the filter condition applied to the corresponding column or card row, the Filter Builder dialog is displayed instead. To invoke the Custom Filter dialog via code, call the view’s Filtering.RunCustomizeDialog method passing the desired column or card row as the parameter. You can prevent the grid view from displaying the Custom Filter dialog or display your own dialog instead by handling the view’s OnFilterDialogShow event.
Appearance	The look and feel of controls displayed within the Custom Filter dialog depends on the grid control’s LookAndFeel property settings.


Filter Builder Dialog

See Also

One of the end-user capabilities for filtering data displayed within a grid view is to use the Filter Builder dialog.  This dialog allows end-users to build complex filter criteria with an unlimited number of filter conditions combined by logical operators.

Feature	Related Members
Availability	End-users can invoke the Filter Builder dialog using the Customize… button displayed within the filter panel.  This dialog is also invoked when choosing the (Custom…) item from the filter dropdown, provided that the Custom Filter dialog cannot display the filter condition applied to the corresponding column or card row. To invoke the Filter Builder dialog via code, use the view’s Filtering.RunCustomizeDialog method without the parameter. You can prevent the grid view from displaying the Filter Builder dialog or display a custom dialog instead by handling the view’s OnFilterCustomization or OnFilterDialogShow event.
Appearance	The look and feel of the controls displayed within the Filter Builder dialog depends on the grid control’s LookAndFeel property settings.
Content	Handle the view’s OnFilterControlDialogShow event to customize the Filter Builder dialog’s content before the dialog is invoked.

Please refer to the Using Filter Builder Dialog topic for additional information.


Filter Dropdown

Similar to filter dropdowns for the filter panel, filter dropdowns for view items (or simply filter dropdowns) are one of the alternative ways end-users have for filtering the data displayed by a grid view.  They are invoked using the filter dropdown buttons displayed within the desired column or card row.  Selecting an item from a filter dropdown, changes the current grid view’s filter criteria appropriately.

Feature	Related Members
Availability	A filter dropdown is available to end-users provided that a column or a card row displays its filter dropdown button.
Layout	For tabular Views, the dropdown list’s width is specified by the View’s Filtering.ColumnPopup.DropDownWidth property (corresponds to the View’s Filtering.RowPopup.DropDownWidth property for Card Views). For tabular Views, the list’s height is specified by the View’s Filtering.ColumnPopup.MaxDropDownItemCount property (corresponds to the View’s Filtering.RowPopup.MaxDropDownItemCount property for Card Views), which sets the maximum number of filter items that can be displayed simultaneously.  If the actual number of items exceeds the specified value, the dropdown list displays a vertical scrollbar.
Content	Most Recently Used List By default, filter dropdowns display a list of the most recently used items at their top.  You can disable these MRU lists by settings the desired column’s or card row’s Options.FilteringMRUItemsList property to False.  If you need to disable MRU lists for all filter dropdowns in a grid view, set the desired table view’s Filtering.ColumnMRUItemsList property (or the Filtering.RowMRUItemsList property for a card view) to False.  The maximum MRU list’s length is specified by the view’s Filtering.ColumnMRUItemsListCount property (the Filtering.RowMRUItemsListCount property for a card view). Predefined Items By default, filter dropdowns display the (All) and (Custom…) items allowing you to clear filtering by the field’s values and display a Custom Filter dialog respectively.  Additionally, if a field contains null values, the filter dropdown displays the (Blanks) and (NonBlanks) items that allow you to filter by null and non-null values, respectively.  You can remove any of the predefined items by handling the view’s DataController.Filter.OnGetValueList event or a particular item’s OnGetFilterValues event. Note: For date/time values, you can control the items to be created as specified via the View’s DateTimeHandling.Filters property. User-Defined Items You can extend the default values list with manually created items that correspond to the most commonly used filtering tasks performed by your application’s end-users.  To do so, handle the view’s DataController.Filter.OnGetValueList event or a particular item’s OnGetFilterValues event.  Both events enable you to add custom filter items to filter lists.  To provide proper handling for the items added, you should handle the desired item’s OnUserFiltering event. Value List A filter dropdown’s bottom part contains a list of the unique values in the corresponding field.  You can customize this list by handling the two events mentioned earlier.  This may be useful for instance, if you need to provide only the manually created items and remove all value items from the list. Note: you can customize the text representing each item within the filter dropdown by handling the desired item’s OnGetFilterDisplayText event.  The text specified will also be used to construct the filter string displayed within the filter panel.
Localization	The captions of the (All), (Custom…), (Blanks) and (NonBlanks) predefined items are specified by the cxSFilterBoxAllCaption, cxSFilterBoxCustomCaption, cxSFilterBoxBlanksCaption and cxSFilterBoxNonBlanksCaption resource strings. For date/time values, the filtering options specified via the View’s DateTimeHandling.Filters property determine the captions of the items associated with these options.  As with the common predefined items described above, these captions are specified by the resource strings listed in the description of the TcxGridDateTimeFilter type. You can use the common localization routines to change these item’s captions.


Filter Dropdown Button

Column headers in Table Views and Banded Table Views, as well as card row captions in Card Views, can display filter dropdown buttons.  End-users can click filter dropdown buttons to invoke filter dropdowns which allow a filter value or filter condition to be selected from a list.

Feature	Related Members
Visibility	In table and banded table views, filter dropdown buttons are available only if the view’s OptionsCustomize.ColumnFiltering option is enabled.  In this case, the filter button's visibility for each column is specified using the column’s Options.Filtering or Options.FilteringPopup property.  At the same time, if the view’s OptionsCustomize.ColumnFiltering option is disabled, filter dropdown buttons are not visible regardless of the column’s Options.Filtering or Options.FilteringPopup property. Card views provide a similar option for specifying the filter dropdown buttons’ visibility.  You should specify the buttons’ visibility at the view’s level using the OptionsCustomize.RowFiltering property.  To disable filter dropdown buttons for a particular row, set the row’s Options.Filtering or Options.FilteringPopup property to False. Through the view’s OptionsView.ShowColumnFilterButtons (OptionsView.ShowRowFilterButtons) property, you can also specify whether filter dropdown buttons are permanently visible in all columns (rows), or only in a particular column (row), if it’s selected. Note that filter dropdown buttons are not displayed for columns and rows that use editors which do not support filtering operations.  For instance, filter buttons will not be displayed for columns and rows that use BLOB editors.
Appearance	Basically, the filter dropdown buttons’ look and feel is specified by the grid control’s LookAndFeel property settings.  You can also provide manual button painting by handling the following events: The view’s OnCustomDrawColumnHeader or a column’s OnCustomDrawHeader event if using a table view or a banded table view; The view’s OnCustomDrawCell or a row’s OnCustomDrawCell event if using a card view.


Filter Dropdown for the Filter Panel

Similar to filter dropdowns for view items, filter dropdowns for the filter panel are one of the alternative ways end-users have for filtering the data displayed by a grid view.  They are populated with the filter criteria that were applied to a grid view and can be invoked using the filter MRU list button displayed within the filter panel.  Selecting an item from a filter dropdown, changes the current grid view’s filter criteria appropriately.

Feature	Related Members
Availability	A filter dropdown is available to end-users provided that a filter panel within a grid view displays its filter MRU list button.
Layout	The dropdown list’s height in terms of used items (applied filer criteria) is specified by the View’s FilterBox.MRUItemsListDropDownCount property, which sets the maximum number of MRU items that can be displayed simultaneously.  If the actual number of items exceeds the specified value, the dropdown list displays a vertical scrollbar.
Content	The filter dropdown for the filter panel displays a list of used items which represent unique filter criteria that have been applied to a grid view.  This list represents a MRU list since the most recently used items are displayed at the top of the list.  The MRU list’s maximum length is specified by the view’s Filtering.MRUItemsListCount property. Note: The text which represents each item within the filter dropdown for a view item can be customized by handling the item’s OnGetFilterDisplayText event.  The text specified is also used to construct the filter strings displayed within the filter dropdown for the filter panel.
Localization	The captions of the filter operators displayed in a filter panel are specified by the cxSFilterOperator~ constants which are defined in the cxFilterConsts unit.  Please refer to the Express DataController: Resource Strings topic for details. You can use the common localization routines to change these captions.


Filter MRU List Button

The filter MRU list button is displayed within a filter panel adjacent to the current filter criteria when at least two unique filter criteria have been applied to a grid view.  Clicking this button opens the filter dropdown for the filter panel.

Feature	Related Members
Visibility	The filter MRU list button is available only when the view’s Filtering.MRUItemsList option is enabled.
Appearance	The filter MRU list buttons’ look and feel is specified by the settings of the grid control’s LookAndFeel property.  You can also perform manual button painting by handling the view’s OnCustomDrawBackgroundBitmaps.


Filter Panel

Card views, table views and banded table views can display a filter panel (also called a filter box) that displays information about the currently applied filter criteria and allows end-users to:

•	customize the filter criteria;

•	enable, disable or clear the currently applied filter;

•	apply a filter by clicking the filter MRU list button and selecting a filter from the opened filter dropdown for the filter panel.

Feature	Related Members
Visibility	The grid view’s FilterBox.Visible property.
Position	The grid view’s FilterBox.Position property.
Appearance	The grid view’s BackgroundBitmaps.FilterBox, Styles.FilterBox properties.
Custom Draw	The view’s OnCustomDrawPartBackground event.  The event’s AViewInfo parameter is of the TcxGridFilterViewInfo type if the filter panel is about to be painted.
Content	The filter string is built automatically based on the current filter criteria.  If no filter criterion is currently applied to the view, the filter panel displays the ‘<Filter is Empty>’ string which can be localized. The Customize… button’s visibility is specified by the grid view’s FilterBox.CustomizeDialog property.
Localization	The ‘<Filter is Empty>’ string displayed within the filter panel when no filtering is applied is specified by the scxGridFilterIsEmpty constant.  The Customize… button’s caption is stored in the scxGridFilterCustomizeButtonCaption  resource string. You can use the common localization routines to change these strings.


View Navigator

Grid views can display their own data navigators which enable end-users to navigate through dataset records, add and delete records, control the data editing process, work with bookmarks and filter data.

Feature	Related Members
Visibility	Use the desired grid view’s OptionsView.Navigator property to show or hide the embedded navigator.
Content	Use the desired view’s NavigatorButtons property to specify the visibility and content of individual navigator buttons.
Appearance	The navigator buttons’ look and feel depends on the grid control’s LookAndFeel property settings. You can customize the images displayed in the navigator buttons by accessing individual buttons via the NavigatorButtons property and changing their ImageIndex property.
Miscellaneous	The grid view’s OptionsBehavior.NavigatorHints property specifies whether navigator button hints should be displayed.  The OptionsView.NavigatorOffset property sets the distance between the data navigator and the view’s horizontal scrollbar.


Customization Form

Customization forms provide runtime customization of Views.  The appearance and capabilities of customization forms depend upon the View type.  The following sections summarize the information on customization forms for various Views.

Customization Forms in Tabular and Card Views

In tabular and Card Views, end-users can hide and show and hide table columns, bands and card rows at runtime using drag and drop.  If a View’s customization form is visible and all the options required to allow elements to be hidden are set, end-users can drag a column header, band or a row caption and drop it onto the customization form.  As a result, the corresponding column, band or all corresponding card rows become hidden and can be made visible again by dragging the appropriate header from the customization form back to the View.

Customization Forms in Chart Views

In Chart Views the customization form has three tabbed pages.

•	Series

This page allows end-users to select which series to display in the currently active diagram and also designate the plotting order of series values by selecting the series, whose values will be used for sorting, and specifying the order in which its values will be sorted.

•	Data Groups

This page allows end-users to hide and show data groups via drag and drop.  A data group appears in the customization form provided that its VisibleForCustomization property is set to True.

Refer to the Creating Data Groups in Chart Views topic to learn how to create data groups.

•	Options

This page provides a set of options which control various appearance aspects of chart elements such as a chart legend, title, and toolbox.  These options are grouped by the corresponding chart elements.

Feature	Related Members
Visibility	The customization form’s visibility is specified using the desired View’s Controller.Customization property. If you use a Table or Banded Table View whose column header menu is enabled, end-users can invoke the customization form using this menu’s Field Chooser item. If you use a Chart View, you should enable the customization button in a chart toolbox using the View’s Toolbox.CustomizeButton property.  If it's enabled, end-users will be able to invoke thea customization form by clicking this button. If you need to respond to such end-user actions, handle the View’s OnCustomization event.
Appearance	You can access the View’s customization form via the Controller.CustomizationForm property.  This property returns an object which is a TForm descendant and this enables you to customize the customization form as any other form.  Note that you can also use the Controller.CustomizationFormBounds property to specify the form’s position and size before making it visible.
Content	Customization forms display tabs corresponding to the types of elements they can hold.  For instance, a Table View’s customization form displays a single Columns tab, while a Banded Table View’s customization form additionally displays the Bands tab.  Pages corresponding to these tabs display lists of elements whose Visible property is set to False.  Note that you can prohibit displaying an element within the customization form by setting this element’s Hidden property to True (this relates to bands, table columns and card rows). In Chart Views, you can control the general appearance of the Series, Data Groups, and Options tabs in the customization form using the View’s OptionsCustomize.SeriesCustomization, OptionsCustomize.DataGroupMoving, and OptionsCustomize.OptionsCustomization properties, respectively.
Localization	The customization window’s caption is specified by the scxGridCustomizationFormCaption constant.  The captions for Columns, Bands, Rows, Series, Data Groups, and Options tabs are set by the scxGridCustomizationFormColumnsPageCaption, scxGridCustomizationFormBandsPageCaption, scxGridCustomizationFormRowsPageCaption, scxGridChartCustomizationFormSeriesPageCaption, scxGridChartCustomizationFormDataGroupsPageCaption, and scxGridChartCustomizationFormOptionsPageCaption resource strings, respectively.  You can change these strings using the common localization routines.


Record

The record is a set of data cells corresponding to a single row in table views or a single card in card views.

Feature	Related Members
Appearance	Depends on the appearance of cells displayed within a record.
Content	Depends on the content of cells displayed within a record.
Layout	Please refer to the View Layout topic to learn about the available layout options.


Cell

Cells display field values from particular records and, thus, stand at the intersection of a column and row (card row and card).  In Chart Views, category values and data markers represent field values.

Feature	Related Members
Appearance	At a view’s level specified by the Styles.Content, Styles.ContentEven and Styles.ContentOdd properties.  You can also specify the style for cells within a particular column or card row using its Styles.Content property.  The style specified at a column or card row level overrides other styles applied.  Note also, that in banded table views you can specify a style for cells residing within a particular band using the desired band’s Styles.Content property. To specify styles for individual cells, handle the view’s Styles.OnGetContentStyle or a column’s or card row’s Styles.OnGetContentStyle event. The background bitmap for cells can be set via the view’s BackgroundBitmaps.Content property.
Custom Draw	The view’s OnCustomDrawCell event.  To provide custom painting for cells in individual columns or card rows, you can also handle the column’s or card row’s OnCustomDrawCell event.
Content	Cells display values from the underlying data source.  The format of such values depends on editors that are assigned to cells.  Note that you can also provide custom display texts for cells by handling the desired column’s or card row’s OnGetDisplayText or OnGetDataText events.


View Background

The view background is the view’s area not occupied by any other visual element.  In table views, the background is visible if there are only a few records so that they don’t occupy the entire view vertically or if columns don’t occupy the entire view area.

Feature	Related Members
Appearance	The view’s Styles.Background property.  The background bitmap can be set via the view’s BackgroundBitmaps.Background property.
Content	If a view has no data to display, the ‘<No data to display>’ string is displayed in the background’s center. If needed, you can provide another descriptive string using the View’s OptionsView.NoDataToDisplayInfoText property.
Localization	The ‘<No data to display>’ string is specified by the scxGridNoDataInfoText constant and can be localized using the common localization routines.


Visual Elements List

Common Elements of Card and Table Views

Cell

Custom Filter dialog

Customization Form

Filter Dropdown

Filter Dropdown Button

Filter Dropdown for the Filter Panel

Filter MRU List Button

Filter Panel

Filter Builder dialog

Record

View Background

View Navigator

Card View Elements

Card Caption Row

Card Category Row

Card Expand Button

Card Scroll Button

Card Separator

Card Row Caption

Table View Elements

Column Header Panel

Column Header

Filter Row

Footer Panel

Group By box

Group Footer Panel

Group Row

Indicator

New Item Row

Preview Section

Quick Column Customization Button

Banded Table View Elements

Band Header

Band Header Panel

Filter Row

Fixed Band Separator

New Item Row

Quick Band Customization Button


Band Header Panel

The band header panel is the container for the visible bands’ headers.

Feature	Related Members
Visibility	The view’s OptionsView.BandHeaders property.
Appearance	Most commonly, band headers occupy the entire panel’s area.  At the same time, there may be cases when there are empty spaces within the band header panel.  The appearance of such empty spaces is set using the Styles.BandBackground and BackgroundBitmaps.BandBackground properties.  Note that you can also specify an empty space’s style for a particular band using the desired band’s Styles.Background property.
Layout	You can customize the height of band headers and, thus, the band header panel’s height using the OptionsView.BandHeaderHeight and OptionsView.BandHeaderLineCount properties.


Band Header

Band headers identify column groups and can also be used by end users to rearrange bands or toggle their visibility by dragging to the customization form and back to the view.

Feature	Related Members
Visibility	Visible bands’ headers reside within the band header panel.  Headers of hidden bands are displayed within the customization form provided that the corresponding band’s VisibleForCustomization property value is False.
Appearance	The look and feel of band headers depends upon the grid control’s LookAndFeel property settings.  The style and background bitmap can be changed using the view’s Styles.BandHeader and BackgroundBitmaps.BandHeader properties.  You can also specify a custom style for a particular band header using the corresponding band’s Styles.Header property.  Lastly, you can specify band header styles by handling the view’s Styles.OnGetBandHeaderStyle event or the desired band’s Styles.OnGetHeaderStyle event.
Custom Draw	The view’s OnCustomDrawBandHeader event.


Quick Band Customization Button

The Quick Band Customization button is displayed at the intersection of the band header panel and the indicator.  Clicking this button invokes the Quick Band Customization dropdown, which displays band names in a checklist.  Users are able to toggle bands’ visibility and reorder bands by dragging items in the dropdown.  Multiple items can be selected by clicking them while holding down the Shift and Ctrl keys.

Feature	Related Members
Availability	The view’s OptionsCustomize.BandsQuickCustomization property.  Note that setting this property to True results in enabling the indicator.
Appearance	The Quick Band Customization button is an indicator cell.  Please refer to the Indicator topic for information on customizing indicator cells’ appearance.
Behavior	The Quick Band Customization dropdown allows users to: • change the visible state of bands without using the Customization Form at runtime or the Object Inspector at design time; • reorder bands in a View by dragging their names in the dropdown.  This functionality is enabled in a View when the View’s OptionsCustomize.BandsQuickCustomizationReordering property is set to True.
Dropdown List’s Content	The dropdown list displays all bands whose VisibleForCustomization property value is False.
Dropdown List’s Layout	You can constrain the dropdown’s height using the view’s OptionsCustomize.BandsQuickCustomizationMaxDropDownCount property.


Fixed Band Separator

These visual elements are used to separate fixed bands from the rest.

Feature	Related Members
Availability	Fixed band separators are available if there are fixed bands in the view.  This means that the FixedKind property of at least a single band should be set to fkRight or fkLeft.
Appearance	The separators’ color is specified by the view’s OptionsView.FixedBandSeparatorColor property.
Layout	The separators’ width can be changed using the view’s OptionsView.FixedBandSeparatorWidth property.


TcxGridCardViewInfo
TcxGridCardViewInfo Object

Hierarchy          Properties          Methods          See Also

Provides all the information needed to draw cards.

Unit

cxGridCardView

TcxGridCardViewInfo = class(TcxCustomGridRecordViewInfo)

Description

The TcxGridCardViewInfo class contains the visual properties of the control and other visual elements such as the scroll buttons and the card border of a card.

You can use the OnCustomDrawCell event to custom draw a single card.  To learn more about custom drawing, please refer to the Custom Draw topic.

You should not create instances of ViewInfos. They are created automatically on demand.

To locate the column headers within a grid view, see the Grid View Elements topic.


TcxGridCardViewInfo Hierarchy
Hierarchy

TObject

     |

TcxCustomGridCellViewInfo

     |

TcxCustomGridViewCellViewInfo

     |

TcxCustomGridRecordViewInfo

     |


Properties for TcxGridCardViewInfo
TcxGridCardViewInfo Properties

TcxGridCardViewInfo          Legend

In TcxGridCardViewInfo

TopRowIndex

Derived from TcxCustomGridViewCellViewInfo

GridView

Derived from TcxCustomGridCellViewInfo

AlignmentHorz

AlignmentVert

BackgroundBitmap

BorderBounds

BorderColor

Borders

BorderSize

ContentBounds

ContentHeight

ContentWidth

Height

State

Text

TextAreaBounds

TextAreaHeight

TextAreaWidth

TextHeight

TextWidth

Transparent

Visible

Width


Methods for TcxGridCardViewInfo
TcxGridCardViewInfo Methods

TcxGridCardViewInfo          Legend

In TcxGridCardViewInfo

MakeRowVisible

NeedsScrollingDown

NeedsScrollingUp

Derived from TcxCustomGridCellViewInfo

GetHitTest

Paint


TcxGridCardViewInfo.TopRowIndex

TcxGridCardViewInfo

Specifies the row which is the first row (top-most) displayed in the current card.

property TopRowIndex: Integer;

Description

Use the TopRowIndex property to specify the index of the row which is the first row (top-most) displayed in the current card.  All visible rows preceding the one specified by this property will not be displayed in the card, and thus it is necessary to scroll up the view to see them.


TcxGridCardViewInfo.MakeRowVisible

TcxGridCardViewInfo

Makes the specified row visible in the current card.

procedure MakeRowVisible(ARow: TcxGridCardViewRow); virtual;

Description

The MakeRowVisible procedure scrolls the current card vertically until the row specified by the ARow parameter becomes visible in the card.

Note:	This procedure works with visible rows (the Row.Visible is set to True) only.


TcxGridCardViewInfo.NeedsScrollingDown

TcxGridCardViewInfo          See Also

Determines whether there are card rows hidden off screen at the view's bottom edge, which require the view to be scrolled downwards to be made visible.

function NeedsScrollingDown: Boolean; virtual;

Description

Whenever the card view's height is insufficient to display all the card rows at once and some rows are hidden by the top or bottom edges of the view, vertical scrolling may be required to display them.  The NeedsScrollingDown function determines whether data is hidden by the current card’s view bottom edge and as a result the view needs to be scrolled down to display them.

The following image represents the situation when rows are hidden by the bottom edge of a view.


TcxGridCardViewInfo.NeedsScrollingUp

TcxGridCardViewInfo          See Also

Determines whether there are card rows hidden off screen at the view's top edge, which require the view upwards to be made visible.

function NeedsScrollingUp: Boolean; virtual;

Description

Whenever the card view's height is insufficient to display all the card rows at once and some rows are hidden by the top or bottom edges of the view, vertical scrolling may be required to display them.  The NeedsScrollingUp function determines whether data is hidden by the current card’s view top edge and as a result the view needs to be scrolled up to display them.

The following image represents the situation when rows are hidden by the top edge of a view.


TcxGridCardViewSeparatorHitTest
TcxGridCardViewSeparatorHitTest Object

Hierarchy          Properties          Methods          See Also

Represents the HitTest object for card separators in a Card View.

Unit

cxGridCardView

TcxGridCardViewSeparatorHitTest = class(TcxCustomGridHitTest)

Description

The TcxGridCardViewSeparatorHitTest class represents the HitTest object for card separators (the lines which separate cards in a Card View).  The TcxGridCardViewSeparatorHitTest class designates the hit code (which is equal to htSeparator) of the card separator located at the grid view’s point that is being tested and also provides additional properties to get the information specific to card separators.  For instance, visual information on card separators is accessible via the Separators field.  The Index field can be used to access a particular card separator for the HitTest object.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridCardViewSeparatorHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |


Properties for TcxGridCardViewSeparatorHitTest
TcxGridCardViewSeparatorHitTest Properties

TcxGridCardViewSeparatorHitTest          Legend

In TcxGridCardViewSeparatorHitTest

Index

Separators

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridCardViewSeparatorHitTest
TcxGridCardViewSeparatorHitTest Methods

TcxGridCardViewSeparatorHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridCardViewSeparatorHitTest.Index

TcxGridCardViewSeparatorHitTest

Returns the position of the card separator within the collection of card separators used to render a Card View.

Index: Integer;

Description

The collection of card separators (the lines separating cards in a Card View) is accessible via the Separators field.  The Index field specifies the position of the inspected card separator within this collection.  To get the card separator, use the Index field’s value as the index for the Separators.Items property.


TcxGridCardViewSeparatorHitTest.Separators

TcxGridCardViewSeparatorHitTest

Provides access to the visual information on card separators used to render a Card View.

Separators: TcxGridCardViewSeparatorsViewInfo;

Description

The HitTest object for a card separator contains visual information on the card separators used to render the current Card View (which is accessible via the Separators field) and an index that corresponds to the card separator for which the hit test information has been obtained (which is accessible via the Index field).  To get the card separator, use the Index field’s value as the index for the Separators.Items property.


TcxGridCardScrollButtonDownHitTest
TcxGridCardScrollButtonDownHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the card scroll down button which is located at the point being tested.

Unit

cxGridCardView

TcxGridCardScrollButtonDownHitTest = class(TcxGridRecordHitTest)

Description

The TcxGridCardScrollButtonDownHitTest class does not introduce any new functionality, but instead designates the hit code (which is equal to htCardScrollButtonDown) of the card scroll down button which is located at the Grid View’s point that is being tested.

Refer to the description of the NeedsScrollingDown function for details on the circumstances when the card scroll down button appears.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridCardScrollButtonDownHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxGridRecordHitTest

     |


Properties for TcxGridCardScrollButtonDownHitTest
TcxGridCardScrollButtonDownHitTest Properties

TcxGridCardScrollButtonDownHitTest          Legend

Derived from TcxGridRecordHitTest

GridRecord

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridCardScrollButtonDownHitTest
TcxGridCardScrollButtonDownHitTest Methods

TcxGridCardScrollButtonDownHitTest          Legend

Derived from TcxGridRecordHitTest

CanClick

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridCardScrollButtonUpHitTest
TcxGridCardScrollButtonUpHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the card scroll up button which is located at the point being tested.

Unit

cxGridCardView

TcxGridCardScrollButtonUpHitTest = class(TcxGridRecordHitTest)

Description

The TcxGridCardScrollButtonUpHitTest class does not introduce any new functionality, but instead designates the hit code (which is equal to htCardScrollButtonUp) of the card scroll up button which is located at the Grid View’s point that is being tested.

Refer to the description of the NeedsScrollingUp function for details on the circumstances when the card scroll up button appears.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridCardScrollButtonUpHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxGridRecordHitTest

     |


Properties for TcxGridCardScrollButtonUpHitTest
TcxGridCardScrollButtonUpHitTest Properties

TcxGridCardScrollButtonUpHitTest          Legend

Derived from TcxGridRecordHitTest

GridRecord

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridCardScrollButtonUpHitTest
TcxGridCardScrollButtonUpHitTest Methods

TcxGridCardScrollButtonUpHitTest          Legend

Derived from TcxGridRecordHitTest

CanClick

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridCardRowCaptionHitTest
TcxGridCardRowCaptionHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the card row caption which is located at the point being tested.

Unit

cxGridCardView

TcxGridCardRowCaptionHitTest = class(TcxGridCardRowCellHitTest)

Description

The TcxGridCardRowCaptionHitTest class provides general information for the card row caption within the Card View which is located at the View’s point that is being tested.  This class introduces the RowContainerKind field which specifies the container for the inspected card row caption and also designates the hit code (which is equal to htRowCaption) of this card row caption.  Use the Item and GridRecord properties to access the properties and methods of the grid item and record which correspond to the card row whose caption is being inspected, respectively.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridCardRowCaptionHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxGridRecordHitTest

     |

TcxGridRecordCellHitTest

     |

TcxGridCardRowCellHitTest

     |


Properties for TcxGridCardRowCaptionHitTest
TcxGridCardRowCaptionHitTest Properties

TcxGridCardRowCaptionHitTest          Legend

In TcxGridCardRowCaptionHitTest

RowContainerKind

Derived from TcxGridRecordCellHitTest

Item

Derived from TcxGridRecordHitTest

GridRecord

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridCardRowCaptionHitTest
TcxGridCardRowCaptionHitTest Methods

TcxGridCardRowCaptionHitTest          Legend

Derived from TcxGridRecordHitTest

CanClick

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridCardRowCaptionHitTest.RowContainerKind

TcxGridCardRowCaptionHitTest

Specifies the container for the inspected card row caption.

type

  TcxGridColumnContainerKind = Integer;

RowContainerKind: TcxGridItemContainerKind;

Description

The RowContainerKind property specifies the container for the grid view card row caption at the Card View’s point being inspected (where the card row caption is located).  The grid item which corresponds to the card row whose caption is being inspected is accessible via the Item property.  The table below lists all the possible values for the RowContainerKind property.

Value	Meaning
ckCustomizationForm	The card row caption is located in the Card View’s customization form.
ckRows	The card row caption is located within a card of the Card View.
ckNone	The card row caption is located in none of the above containers.


TcxGridCardRowCellHitTest
TcxGridCardRowCellHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the cell within a card row which is located at the point being tested.

Unit

cxGridCardView

TcxGridCardRowCellHitTest = class(TcxGridRecordCellHitTest)

Description

The TcxGridCardRowCellHitTest class does not introduce any new functionality, but instead it’s extended for internal purposes with information specific to card row cells.  The hit code for the inspected card row cell is the same as for a generic view cell and is equal to htCell.  Use the Item and GridRecord properties to access the properties and methods of the grid item and record which correspond to the card row cell being inspected, respectively.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridCardRowCellHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxGridRecordHitTest

     |

TcxGridRecordCellHitTest

     |


Properties for TcxGridCardRowCellHitTest
TcxGridCardRowCellHitTest Properties

TcxGridCardRowCellHitTest          Legend

Derived from TcxGridRecordCellHitTest

Item

Derived from TcxGridRecordHitTest

GridRecord

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridCardRowCellHitTest
TcxGridCardRowCellHitTest Methods

TcxGridCardRowCellHitTest          Legend

Derived from TcxGridRecordHitTest

CanClick

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridCardRowExpandButtonHitTest
TcxGridCardRowExpandButtonHitTest Object

Hierarchy          Properties          Methods          See Also

The TcxGridCardRowExpandButtonHitTest provides hit information on the inspected category row’s expand button.

Unit

cxGridCardView

TcxGridCardRowExpandButtonHitTest = class(TcxGridRecordCellHitTest)

Description

A unique identifier for the category row’s expand button - returned by the HitTestCode method - is htCardRowExpandButton.


TcxGridCardRowExpandButtonHitTest Hierarchy
Hierarchy

TcxCustomGridViewHitTest

     |

TcxGridRecordHitTest

     |

TcxGridRecordCellHitTest

     |

TcxGridCardRowExpandButtonHitTest


Properties for TcxGridCardRowExpandButtonHitTest
TcxGridCardRowExpandButtonHitTest Properties

TcxGridCardRowExpandButtonHitTest          Legend

Derived from TcxGridRecordHitTest

GridRecord


Methods for TcxGridCardRowExpandButtonHitTest
TcxGridCardRowExpandButtonHitTest Methods

TcxGridCardRowExpandButtonHitTest          Legend

Derived from TcxGridRecordHitTest

 CanClick


TcxGridCardRowFilterButtonHitTest
TcxGridCardRowFilterButtonHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the card row filter dropdown button which is located at the point being tested.

Unit

cxGridCardView

TcxGridCardRowFilterButtonHitTest = class(TcxGridRecordCellHitTest)

Description

The TcxGridCardRowFilterButtonHitTest class does not introduce any new functionality, but instead designates the hit code (which is equal to htRowFilterButton) of the card row filter dropdown button which is located at the Grid View’s point that is being tested.  Use the Item and GridRecord properties to access the properties and methods of the grid item and record which correspond to the card row filter dropdown button being inspected, respectively.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridCardRowFilterButtonHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxGridRecordHitTest

     |

TcxGridRecordCellHitTest

     |


Properties for TcxGridCardRowFilterButtonHitTest
TcxGridCardRowFilterButtonHitTest Properties

TcxGridCardRowFilterButtonHitTest          Legend

Derived from TcxGridRecordCellHitTest

Item

Derived from TcxGridRecordHitTest

GridRecord

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridCardRowFilterButtonHitTest
TcxGridCardRowFilterButtonHitTest Methods

TcxGridCardRowFilterButtonHitTest          Legend

Derived from TcxGridRecordHitTest

CanClick

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridCardRowIndentHitTest
TcxGridCardRowIndentHitTest Object

Hierarchy          Properties          Methods          See Also

The TcxGridCardRowIndentHitTest provides hit information on the inspected category row’s child indent.

Unit

cxGridCardView

TcxGridCardRowIndentHitTest = class(TcxGridRecordCellHitTest)

Description

The unique identifier of the category row’s child indent - returned by the HitTestCode method - is htCardRowIndent.


TcxGridCardRowIndentHitTest Hierarchy
Hierarchy

TcxCustomGridViewHitTest

     |

TcxGridRecordHitTest

     |

TcxGridRecordCellHitTest

     |

TcxGridCardRowIndentHitTest


Properties for TcxGridCardRowIndentHitTest
TcxGridCardRowIndentHitTest Properties

TcxGridCardRowIndentHitTest          Legend

Derived from TcxGridRecordHitTest

GridRecord


Methods for TcxGridCardRowIndentHitTest
TcxGridCardRowIndentHitTest Methods

TcxGridCardRowIndentHitTest          Legend

Derived from TcxGridRecordHitTest

 CanClick


TcxGridCardViewSeparatorsViewInfo
TcxGridCardViewSeparatorsViewInfo Object

Hierarchy          Properties

Contains the visual information on a card separator.

Unit

cxGridCardView

TcxGridCardViewSeparatorsViewInfo = class(TObject);

Description

The TcxGridCardViewSeparatorsViewInfo class provides the following visual information on a card separator:

•	the indexed collection of the card separators used to render the current card view and the number of card separators within the collection via the Items and Count properties, correspondingly.

•	the color and width of the card separators via the Color and Width properties, respectively;


TcxGridCardViewSeparatorsViewInfo Hierarchy
Hierarchy

TObject

     |


Properties for TcxGridCardViewSeparatorsViewInfo
TcxGridCardViewSeparatorsViewInfo Properties

TcxGridCardViewSeparatorsViewInfo          Legend

In TcxGridCardViewSeparatorsViewInfo

Color

Count

Items

Width


TcxGridCardViewSeparatorsViewInfo.Color

TcxGridCardViewSeparatorsViewInfo

Gets the color of the card separators in the current card view.

property Color: TColor;

Description

The Color property indicates the color used to paint the card separators, i.e. the color specified by the card view’s OptionsView.SeparatorColor property.

ReadOnly Property


TcxGridCardViewSeparatorsViewInfo.Count

TcxGridCardViewSeparatorsViewInfo

Gets the number of card separators used to render the current card view.

property Count: Integer;

Description

The Items property enumerates all the card separators that are used to render the cards currently visible in the card view.  Use the Count property to determine the number of card separators contained within the Items property.

ReadOnly Property


TcxGridCardViewSeparatorsViewInfo.Items

TcxGridCardViewSeparatorsViewInfo

Provides indexed access to the collection of card separators used to render the current card view.

property Items[Index: Integer]: TRect;

Description

Visually the cards in a card view are arranged vertically in columns and horizontally in rows like records in a table.  They are separated using card separators which represent the lines (vertical or horizontal) drawn between them.  The orientation of the separator lines is specified by the card view’s LayoutDirection property.  In a card view which uses the horizontal layout each column has a vertical corresponding card separator (on the right of each column), while in a card view which has a vertical layout each row has a horizontal corresponding card separator (on the bottom of each row).

The Items property provides indexed access to the collection of card separators (their bounding rectangles) that are used to render the cards currently visible in the card view.  The Count property returns the number of card separators contained within the collection.

The width of the vertical line separators and the height of the horizontal line separators are equal to the OptionsView.SeparatorWidth property’s value.


TcxGridCardViewSeparatorsViewInfo.Width

TcxGridCardViewSeparatorsViewInfo

Gets the width of the card separators in the current card view.

property Width: Integer;

Description

The Width property indicates the width of the separator lines used to render the current card view, i.e. the value specified by the card view’s OptionsView.SeparatorWidth property.

ReadOnly Property


cxGridCardDefaultCategorySeparatorWidth constant
cxGridCardDefaultCategorySeparatorWidth global constant

See Also

Specifies the default width of the category row separator in pixels.

Unit

cxGridCardView

cxGridCardDefaultCategorySeparatorWidth = 2;

Description

Use the cxGridCardDefaultCategorySeparatorWidth constant to specify the default width of the category row separator.


cxGridCardDefaultLayerSeparatorWidth constant
cxGridCardDefaultLayerSeparatorWidth global constant

See Also

Specifies the default width of a layer separator in pixels.

Unit

cxGridCardView

cxGridCardDefaultLayerSeparatorWidth = 0;

Description

A layer separator is a bar that visually divides layered card rows in a card view:

Use the cxGridCardDefaultLayerSeparatorWidth constant to specify the default width of the layer separator.


cxGridCardViewAlternateCaptionSeparator constant
cxGridCardViewAlternateCaptionSeparator global constant

See Also

Specifies a string character to be used as a splitter between captions of the category row and its children.

Unit

cxGridCardView

cxGridCardViewAlternateCaptionSeparator : string = '-';

Description

Use the cxGridCardViewAlternateCaptionSeparator constant to change the default splitter.


Data Loading Modes

See Also

Data loading in the ExpressQuantumGrid control is implemented via a data controller.  A data controller is a core module implementing data related operations.  Its main task is to connect a view to the data storage.  In addition, a data controller provides grouping operations on data, filtering and summary calculations.

Every type of grid view has a DataController property providing access to a data source.

There are three main modes of data loading provided by a data controller:

•	Bound mode

The DataController is connected to a TDataSet by means of a TDataSource object.

•	Provider mode

The DataController is connected to a user-defined (custom) data source and data is requested as needed.

•	Unbound mode

The data controller is not connected to a data source and is pre-populated with records manually.

Grid views can be divided into two main groups: data-aware views and non data-aware views.  Data-aware views containing the DB sub-string in the class name (TcxGridDBTableView, TcxGridDBBandedTableView, TcxGridDBCardView, and TcxGridDBChartView), have a data-aware data controller represented by the TcxDBDataController class or one of its descendants.  Each data-aware view functions in bound mode, linking to data via a TDataSet.  Refer to the Connecting to Data topic for more information.

Non data-aware views (TcxGridTableView, TcxGridBandedTableView, TcxGridCardView, and TcxGridChartView) are designed to work in provider and unbound modes.

In provider mode, data is retrieved from a user-defined data source.  This mode can be used, for instance, when you need to display structured data within your grid control.  The TcxCustomDataSource class provides an interface, which must be overridden to implement a data source with which your data controller can work.  Typically, creating a custom data source requires code in only two methods.  See the Provider Mode topic to learn more.

In unbound mode, the data controller must be populated manually.  First, you should set the number of records in your data controller and then set item values for each record.  The Unbound Mode section provides more information on the implementation of unbound mode.


Grid Mode

See Also

The ExpressQuantumGrid performance when loading data from DataSets depends on several factors:

•	the number of records loaded;

•	the number (and size) of fields in each record loaded;

•	the database server's location.

If any of these factors cause insufficient application performance, the ExpressQuantumGrid should be used in Grid Mode.

When using Grid Mode, the data controller loads a fixed number of dataset records into memory.  The number of records to be loaded depends on the GridModeBufferCount property value.  A user is permitted to perform data-related operations on the loaded records only.    The automatic sorting, filtering, summary calculations and smart refresh features are not supported in Grid Mode.  These features need to be handled manually by handling the appropriate events of the data controller.

To activate Grid Mode, set the data controller’s GridMode property to True.  This data controller mode is deactivated though when you group records within a view.  In this case, the data controller switches to default data loading mode.

There is an issue concerning scrolling records in grid mode.  Most dataset tables support sequence numbers (sequence numbers can also be computed by dataset components).  See the TDataSet.IsSequenced function to test whether sequence numbers are available.  If IsSequenced is True, applications can safely use the RecNo property to navigate dataset records.

If sequence numbers are available for a dataset displayed in grid mode, there is a unique correspondence between the position of the scroll bar’s thumb and the record number.  So you can drag the thumb to scroll the view to locate a specific record.

If sequence numbers are not available, the grid control cannot determine the position of the current record relative to the beginning or end of the dataset.  That is why the scroll bar’s thumb cannot reflect the absolute position of the current record.

However, in some cases the grid control cannot display the scroll bar’s thumb correctly in grid mode even if sequence numbers are available in the dataset.  To support sequence numbers in grid mode, the following conditions must be observed:

•	records within a corresponding view must be of the same height (the OptionsView.CellAutoHeight property must be set to False or the OptionsView.DataRowHeight property must be set to a non-zero value)

•	the height of the preview section must not be calculated automatically based on the length of a corresponding field (the Preview.AutoHeight property must be set to False)

•	the view must not be a master view

By default, the ExpressQuantumGrid data controller loads all records from a dataset.  This mode was called LoadAllRecords in ExpressQuantumGrid3.  In this mode all data controller features (automatic sorting, filtering and summary calculations) are available.  The SmartRefresh feature is also available in this mode.  This option increases the ExpressQuantumGrid performance by reloading only changed dataset records when updating.  Using SmartRefresh imposes some restrictions on the dataset:

•	the key field should exist

•	all changes to data should be performed via EQGrid5

The SmartRefresh feature is effective if the dataset’s size exceeds 1000 records.  Otherwise, you should disable it.


Connecting to Data

See Also

This topic explains how to connect the ExpressQuantumGrid to a dataset (which is a required step when working in bound mode).  There will be a single level with a single view within the grid control.

Generally, the connection procedure can be divided into several steps:

1.	Data Preparation

First, all necessary data objects (dataset and data source) are created and set up.

2.	Grid Control Preparation

Then a grid control with the appropriate data-aware view is created.

3.	Data Connection

Finally, data is connected to the grid view.

Below these steps are discussed in detail:

Data Preparation

The type of underlying data engine used by the grid control is not important.  It can be BDE, ADO, ODBC, etc. The only requirement is that you should use the TDataSource component as the link between the dataset and the grid control.

We will discuss two methods of data preparation: BDE and ADO.

1.	BDE

•	Place TTable and TDataSource components onto a form.

•	Setup the TTable component via the Object Inspector: Set its DatabaseName property to "DBDEMOS", the TableName property to "biolife.db" and the Active property to True.

•	Setup the TDataSource component via the Object Inspector: Set its DataSet property to the TTable class instance (normally Table1).

2.	ADO

•	Place TADOConnection, TADOTable and TDataSource components onto a form.

•	Setup the TADOConnection component via the Object Inspector: Use the Connection String Wizard to form a connection string:

This is the Connection String Wizard. Press the [Build…] button to continue:

The following dialog will appear. Select the Microsoft Jet 4.0 OLE DB Provider data provider and click the Connection tab.

In the Connection tab, click the […] button next to the database name textbox. Navigate to either the DBDEMOS.mdb or BCDEMOS.mdb databases which are located in the Borland sample data files directory (assuming these files have been installed during a Delphi or C++ Builder installation).  Click the [OK] button to apply changes and exit the Connection String Builder.

Click the [OK] button to apply changes and exit the Connection String Wizard.

Set the LoginPrompt property to False to deactivate the database login dialog:

Now the ADO Connection is ready to use.

•	Setup the TADOTable component via the Object Inspector: Set its Connection property to ADOConnection1, the TableName property to "country" and the Active property to True.

•	Setup the TDataSource component via the Object Inspector: Set its DataSet property to a TADOTable class instance (normally ADOTable1).

Grid Control Preparation

Drop the Grid control onto a form and set its Align property to alClient. The grid control already has a level and a db table view, so there is no need to create them.

Data Connection

After the data and grid control are prepared, you should connect them:

•	Click an appropriate view within the Structure Navigator:

•	Set the DataSource property of the view’s data controller to a TDataSource class instance (normally DataSource1):

•	Now the data is connected to the Grid control and it’s time to display the data. Right-click the view within the Structure Navigator to display the popup menu. Select the "Create All Columns" menu item.

The easiest way of connecting the grid to a data source and creating its items is at design time.  Whenever you have active datasets in a form that are accessible via the TDataSource components and the grid control only has one level which is associated with a data-aware view, all you have to do to connect the grid to a data source is right-click on the grid and choose the Link to <DataSource name> option from the dropdown menu as shown in the image below:

If there are several data sources available then a submenu item "Link to DataSource" will be shown instead, which will list the available data sources:

Linking the grid to the data source in this manner will automatically connect the grid to the selected data source and retrieve all the fields which will be displayed as view items (columns for a (banded) table view and rows for a card view).  For a banded view, the columns are placed within the first visible band, if any.

To connect your grid control to a dataset at runtime, implement the following code:

//Delphi

  with cxGrid1DBTableView1.DataController do

  begin

    DataSource := DataSource1;

    CreateAllItems;

  end;

//C++ Builder

  cxGrid1DBTableView1->DataController->DataSource = DataSource1;

  cxGrid1DBTableView1->DataController->CreateAllItems();

Note: The CreateAllItems method creates items within a view for each field in the linked dataset.

If you’ve done everything correctly, data will appear within a grid view:

1.	BDE

2.	ADO


Provider Mode

See Also

Provider mode allows a grid control to display information when it is not stored in a standard database and cannot be connected with the help of a TDataSource object.  In this instance you need to create a custom data source by overriding the TcxCustomDataSource class.

To display data in provider mode, you should use one of the non data-aware views designed to work in unbound and provider modes.  These views obtain data from the DataController.CustomDataSource property once it is assigned to an instance of the TcxCustomDataSource class.

When creating a custom data source, usually you only need to override the methods responsible for getting/setting data and for item (column) identification.

This topic describes the base steps when implementing provider mode based on the UnboundList demo.

Class structure

The UnboundList demo displays records from a text file.  Each record contains the customer and company names displayed in corresponding grid columns.

When the main form is created, these records are loaded into memory.  Two classes (TCustomer and TCustomerList) have been designed to represent the records in memory.  TCustomerList organizes records into a list and every record is represented by a TCustomer object.  The classes provide a convenient way to access particular records and record fields.

The TCustomer class contains the Name and Description properties and stores the values of the corresponding fields in the text file.  The TCustomer.ID property specifies a value which uniquely identifies the current record within TCustomerList.  This property is automatically initialized when records are loaded from the file.

To display data from the TCustomerList, the custom data source of class TCustomerDataSource is used.  TCustomerDataSource contains the FCustomers field identifying a TCustomerList object to access (i.e. get/set) data.  The TCustomerDataSource class is inherited from the TcxCustomDataSource class and overrides the following methods:

•	GetRecordCount

Retrieves the number of records in the FCustomers list.

•	GetValue, SetValue

GetValue returns a value contained in a specific record and field (ID, Name or Description).  SetValue updates this data.

•	InsertRecord , AppendRecord and DeleteRecord.

Methods used to add and delete individual records respectively from the FCustomers list.

Item identification

Data from TCustomerList is displayed within three columns: ID, Customer and Company.  When a value of a specific record and column is needed, the grid control calls the GetValue method passing a record handle and an item (column) handle as parameters.  By default, an item handle specifies the item’s index (its current visible position amongst the other items).  However, this index is not constant (it will change if the column moves), so it cannot be used as an item identifier.  To solve this problem, every column must be associated with a unique value thus guaranteeing columns are correctly identified.  For this purpose, the GetDefaultItemID method can be used.  When an item (column) is created, the data controller designates a new unique identity value for it, thus allowing columns to be identified in the GetValue and SetValue methods.  The following code lists the GetValue method from the UnboundList demo:

//Delphi

function TCustomerDataSource.GetValue(ARecordHandle: TcxDataRecordHandle;

  AItemHandle: TcxDataItemHandle): Variant;

var

  AColumnId: Integer;

  ACustomer: TCustomer;

begin

  //Get a specific record from the FCustomers list

  ACustomer := FCustomers[Integer(ARecordHandle)];

  //Get column’s identity value based on its index

  AColumnId := GetDefaultItemID(Integer(AItemHandle));

  //Return a value according to the identity value

  case AColumnId of

    IndexOfID:

      Result := ACustomer.ID;

    IndexOfName:

      Result := ACustomer.Name;

    IndexOfDescription:

      Result := ACustomer.Description;

  end;

end;

//C++ Builder

Variant __fastcall TCustomerDataSource::GetValue(TcxDataRecordHandle ARecordHandle;

  TcxDataItemHandle AItemHandle) {

  //Get column’s identity value based on its index

  int AColumnId = GetDefaultItemID((int)AItemHandle);

  //Get a specific record from the FCustomers list

  TCustomer* ACustomer = FCustomers->Customers[(int)ARecordHandle];

  Variant Result;

  //Return a value according to the identity value

  switch(AColumnId) {

  case IndexOfID:

    Result = ACustomer->ID;

    break;

  case IndexOfName:

    Result = ACustomer->Name;

    break;

  case IndexOfDescription:

    Result = ACustomer->Description;

    break;

  }

  return (Result);

}

Alternatively, you can override the default behavior of the TcxCustomDataSource.GetItemHandle method. For instance, this can be necessary if you want to provide a real item handle for GetValue (instead of the item’s index) and for other methods requiring AItemHandle as a parameter.

Record identification

The methods of the TcxCustomDataSource class get a record handle as a parameter.  By default, a record handle is an integer value between 0 and (GetRecordCount – 1) which uniquely identifies a record in the custom data source.  Record handles always refer to the same data regardless of sorting/grouping/filtering applied.  They are determined by the virtual GetRecordHandle function before records are retrieved from a data source for the first time.  Usually you do not need to override this function.

Creating columns

The following code for the GenerateColumns method in the UnboundList demo illustrates how columns are added in provider mode.  The column’s DataBinding.ValueTypeClass property is initialized with a class that indicates the type of the column’s values.  The last statement assigns an instance of TCustomerDataSource to the view’s DataController.CustomDataSource property by connecting a view to a custom data source.

//Delphi

procedure TUnboundListDemoMainForm.GenerateColumns;

begin

  with tvCustomers as TcxGridTableView do

  begin

    //Clear existing columns from the view if any

    ClearItems;

    //Create the ID column

    with CreateColumn as TcxGridColumn do

    begin

      Caption := 'ID';

      Name := 'tvCustomersID';

      DataBinding.ValueTypeClass := TcxIntegerValueType;

      Width := 50;

    end;

    //Create the Customer column

    with CreateColumn as TcxGridColumn do

    begin

      Caption := 'Customer';

      Name := 'tvCustomersCustomer';

      DataBinding.ValueTypeClass := TcxStringValueType;

      Width := 200;

    end;

    //Create the Company column

    with CreateColumn as TcxGridColumn do

    begin

      Caption := 'Company';

      Name := 'tvCustomersCompany';

      DataBinding.ValueTypeClass := TcxStringValueType;

      Width := 200;

    end;

  end;

  tvCustomers.DataController.CustomDataSource := CustomerDataSource;

end;

//C++ Builder

void TUnboundListDemoMainForm::GenerateColumns() {

  //Clear existing columns from the view if any

  TcxGridColumn* GridColumn;

  tvCustomers->ClearItems();

  //Create the ID column

  GridColumn = tvCustomers->CreateColumn();

  GridColumn->Caption = "ID";

  GridColumn->Name = "tvCustomersID";

  GridColumn->DataBinding->ValueTypeClass = __classid(TcxIntegerValueType);

  GridColumn->Width = 50;

  //Create the Customer column

  GridColumn = tvCustomers->CreateColumn();

  GridColumn->Caption = "Customer";

  GridColumn->Name = "tvCustomersCustomer";

  GridColumn->DataBinding->ValueTypeClass = __classid(TcxStringValueType);

  GridColumn->Width = 200;

  //Create the Company column

  GridColumn = tvCustomers->CreateColumn();

  GridColumn->Caption = "Company";

  GridColumn->Name = "tvCustomersCompany";

  GridColumn->DataBinding->ValueTypeClass = __classid(TcxStringValueType);

  GridColumn->Width = 200;

  tvCustomers->DataController->CustomDataSource = CustomerDataSource;

}

Since the data controller designates a unique identity value for each column created in a view, there is no need to explicitly assign a unique value to a column to identify it.  However, if you want to implement custom item (column) identification see the corresponding section below.

The constants used to address the columns are declared as follows:

//Delphi

const

  IndexOfID = 0;

  IndexOfName = 1;

  IndexOfDescription = 2;

//C++ Builder

const

  IndexOfID = 0,

  IndexOfName = 1,

  IndexOfDescription = 2;

Other TCustomerDataSource methods are not discussed here.  Their implementation is quite simple.  Please refer to the UnboundList demo for the complete example.

The following image shows the grid control from this demo:

Custom item identification

In the UnboundList demo the identity values used to address the items (columns) correspond to the order in which they were created and also to their indexes.  To designate a unique value for a column in this demo, you can assign the column’s DataBinding.Data property to the required value and also override the GetDefaultItemID method in the TCustomerDataSource class to provide access to this value as shown in the following code:

//Delphi

TCustomerDataSource = class(TcxCustomDataSource)

...

protected

  ...

  function GetDefaultItemID(AItemIndex: Integer): Integer; override;

  ...

end;

function TCustomerDataSource.GetDefaultItemID(AItemIndex: Integer): Integer;

var

  GridItem: TcxCustomGridTableItem;

begin

  GridItem := TcxCustomGridTableItem(DataController.GetItem(AItemIndex));

  Result := Integer(GridItem.DataBinding.Data);

end;

procedure TUnboundListDemoMainForm.GenerateColumns;

begin

  with tvCustomers as TcxGridTableView do

  begin

    //Create the ID column

    with CreateColumn as TcxGridColumn do

    begin

      Caption := 'ID';

      Name := 'tvCustomersID';

      DataBinding.Data := Pointer(IndexOfID);

      //...

    end;

    //Create the Customer column

    with CreateColumn as TcxGridColumn do

    begin

      Caption := 'Customer';

      Name := 'tvCustomersCustomer';

      DataBinding.Data := Pointer(IndexOfName);

      //...

    end;

    //Create the Company column

    with CreateColumn as TcxGridColumn do

    begin

      Caption := 'Company';

      Name := 'tvCustomersCompany';

      DataBinding.Data := Pointer(IndexOfDescription);

      //...

    end;

  end;

  tvCustomers.DataController.CustomDataSource := CustomerDataSource;

end;

//C++ Builder

class TCustomerDataSource : public TcxCustomDataSource {

...

protected:

  ...

  int __fastcall GetDefaultItemID(int AItemIndex);

  ...

end;

function TCustomerDataSource.GetDefaultItemID(AItemIndex: Integer): Integer;

int __fastcall TCustomerDataSource::GetDefaultItemID(int AItemIndex)

{

  TcxCustomGridTableItem* GridItem =

    (TcxCustomGridTableItem)DataController->GetItem(AItemIndex);

  return(GridItem->DataBinding->Data);

}

void TUnboundListDemoMainForm::GenerateColumns() {

  TcxGridColumn* GridColumn;

  ...

  //Create the ID column

  GridColumn = tvCustomers->CreateColumn();

  GridColumn->Caption = "ID";

  GridColumn->Name = "tvCustomersID";

  GridColumn->DataBinding->Data = (void *)IndexOfID;

  //...

  //Create the Customer column

  GridColumn = tvCustomers->CreateColumn();

  GridColumn->Caption = "Customer";

  GridColumn->Name = "tvCustomersCustomer";

  GridColumn->DataBinding->Data = (void *)IndexOfName;

  //...

  //Create the Company column

  GridColumn = tvCustomers->CreateColumn();

  GridColumn->Caption = "Company";

  GridColumn->Name = "tvCustomersCompany";

  GridColumn->DataBinding->Data = (void *)IndexOfDescription;

  //...

  tvCustomers->DataController->CustomDataSource = CustomerDataSource;

}

The constants required to initialize the DataBinding.Data property and address the columns can now be assigned to arbitrary integer values as follows:

//Delphi

const

  IndexOfID = 10;

  IndexOfName = 11;

  IndexOfDescription = 12;

//C++ Builder

const

  IndexOfID = 10,

  IndexOfName = 11,

  IndexOfDescription = 12;


Unbound Mode

See Also

The TcxGrid control can operate in 3 modes: Bound, Provider and Unbound. This topic explains how to setup your grid control to work in unbound mode.  When in unbound mode, the grid control does not use any data source and the view’s data controller cache is filled with values directly.

Let’s explore an example from the UnboundSimple demo.  In this demo, a grid control is populated in unbound mode with data relating to the solar system.

Creating and initializing columns

Columns within a grid view can be created at design or runtime.  To create columns at design time, use the Component Editor.  You can refer to the Create And Delete Columns topic for details.

If a grid view is not connected to a data source, columns should be created manually.  Additionally, you need to set the appropriate data type for each column.  Use the DataBinding.ValueType or DataBinding.ValueTypeClass property for this purpose.  See the TcxValueType class topic for available types.  The following code shows how to specify the value type for four columns of the tvPlanets view.

//Delphi

  tvPlanetsPERIOD.DataBinding.ValueTypeClass := TcxFloatValueType;

  tvPlanetsDISTANCE.DataBinding.ValueTypeClass := TcxIntegerValueType;

  tvPlanetsNAME.DataBinding.ValueTypeClass := TcxStringValueType;

  tvPlanetsORBITS.DataBinding.ValueTypeClass := TcxStringValueType;

//C++ Builder

  tvPlanetsPERIOD->DataBinding->ValueTypeClass = __classid(TcxFloatValueType);

  tvPlanetsDISTANCE->DataBinding->ValueTypeClass = __classid(TcxIntegerValueType);

  tvPlanetsNAME->DataBinding->ValueTypeClass = __classid(TcxStringValueType);

  tvPlanetsORBITS->DataBinding->ValueTypeClass = __classid(TcxStringValueType);

Loading data

Before loading data, you need to provide the number of records available to your grid view.  To display two records within the tvPlanets view, write the following:

//Delphi

tvPlanets.DataController.RecordCount := 2;

//C++ Builder

tvPlanets->DataController->RecordCount = 2;

The Values property of the data controller allows you to get/set values of a particular record.  It requires two indexes to be supplied: the record index and the item (column) index.  Below two records are filled with values.  The following code shows how to enter data into the four columns mentioned above:

//Delphi

var

  APeriodIndex, ADistanceIndex, AOrbitsIndex, ANameIndex: Integer;

//...

  //Indexes to access values in particular columns

  APeriodIndex := tvPlanetsPERIOD.Index;

  ADistanceIndex := tvPlanetsDISTANCE.Index;

  ANameIndex := tvPlanetsNAME.Index;

  AOrbitsIndex := tvPlanetsORBITS.Index;

  with tvPlanets.DataController do

  begin

    BeginUpdate;

    try

      //the first record

      Values[0, APeriodIndex] := 87.97;

      Values[0, ADistanceIndex] := 57910;

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

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

      //the second record

      Values[1, APeriodIndex] := 365.26;

      Values[1, ADistanceIndex] := 149600;

      Values[1, ANameIndex] := 'Earth';

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

    finally

      EndUpdate;

    end;

  end;

//C++ Builder

  //Indexes to access values in particular columns

  int APeriodIndex = tvPlanetsPERIOD->Index;

  int ADistanceIndex = tvPlanetsDISTANCE->Index;

  int ANameIndex = tvPlanetsNAME->Index;

  int AOrbitsIndex = tvPlanetsORBITS->Index;

  TcxCustomDataController *dc = tvPlanets->DataController;

  dc->BeginUpdate();

  try {

    //the first record

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

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

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

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

    //the second record

    dc->Values[1][APeriodIndex] = 365.26;

    dc->Values[1][ADistanceIndex] = 149600;

    dc->Values[1][ANameIndex] = "Earth";

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

  } __finally {

    dc->EndUpdate();

  }

When executing this code, the grid view will only display two records as follows:

At design time, it is possible to enter data directly into a non data-aware view by means of the Layout and Data Editor dialog.  Please refer to the Data Editing topic for detailed information.


Grid Mode: Master-Detail

See Also

EQGrid provides a special data-loading mode called Grid Mode, which loads only a fraction of the dataset records at a time, thus improving performance for huge datasets.  See the Grid Mode section to know more about this loading mode and the restrictions it imposes.

This document describes how to set up a master-detail relationship between datasets in grid mode.

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.

To represent a master-detail relationship between storages in EQGrid, you need to create a hierarchical structure of grid levels and views similar to the one shown in the following image:

The first view (MasterTableView) will display data from a master dataset, while the second view (DetailTableView) will display records from the detail dataset corresponding to the selected master record.

Refer to the Working with Levels section to learn how to create such a structure at design time and via code.

In default loading mode (Grid Mode is disabled), you use the properties of the detail data controller to specify the fields used to establish the connection between master and detail tables.  Refer to the Master-Detail section as this provides an example of creating a master-detail relationship between database tables when grid mode is not applied.

In Grid Mode, however, you have to establish a master-detail relationship in the usual way described in the Delphi/C++ Builder documentation, i.e. by using properties provided by dataset components.  You can refer to the Making the table a detail of another dataset and Establishing master/detail relationships using parameters sections, which provide information for this task.

When Grid Mode is applied, only one detail clone can be visible on screen at once.  When you switch from one detail clone to another, the first one is collapsed.  See the Data Representation section for more information on clones.

Consider an example of creating a master-detail relationship in grid mode between the CARS and ORDERS tables shipped with the EQGrid demos.  The CARS table describes all available cars.  Each car is uniquely identified by the ID field.  The ORDERS table contains information on orders and every order addresses the car bought via the ProductID field.  ProductID corresponds to the ID field from the CARS table.

In our example, the CARS table will be displayed in a master view, while the ORDERS table will be represented as a detail view, providing information on all orders of a particular car.

1.	Create an empty application.

2.	Create a database which will be connected to the demo tables.  Place a TDatabase component [image] on a form.  Set its properties as follows:

•	DatabaseName to DemosDB

•	DriverName to STANDARD

In order to specify connection parameters for the database, double-click on the component.  In the opened Database Editor dialog click the Defaults button to obtain a list of all parameters, as well as their default values.  Set the PATH parameter to a string which defines a path to the directory where the CARS and ORDERS tables are located.  Click the OK button to close the Database Editor dialog.

To connect the database to the demo tables, set its Connected property to True.

3.	Place a TQuery component [image] on the form.  This query will select records from the master CARS table.  Set its properties as follows:

•	DatabaseName to DemosDB

•	Name to qryCars

•	SQL to "SELECT * from Cars".  This specifies the query which will select all the fields in the CARS table. To set the query, click the ellipsis button in the SQL property:

This activates the editor to enter the query text so you can type the required string.

•	Active to True.  Note that the Active property must be set after all the other properties have been set.

4.	Place a TDataSource component [image] on the form and connect it to the qryCars dataset by setting its DataSet property to qryCars.  Rename the component to dsCars.

5.	Place another TQuery component on the form.  This query will select records from the ORDERS table for a specific detail clone, i.e. depending on the currently selected record in the master table.  Set the properties of the component to the following values:

•	DatabaseName to DemosDB

•	Name to qryOrders

•	DataSource to dsCars.  This provides the master dataset link.

•	SQL to "SELECT * from Orders WHERE Orders.ProductID = :ID".  The property is set as shown above for the qryCars component.

This SQL statement selects only those records from the ORDERS table which contain a particular value of the ProductID field.

The :ID parameter of the WHERE clause has the same name as the ID field from the dsCars data source (set as the DataSource property value).  This ensures that correct ID field value is used for the currently selected record in the dsCars data source.

•	Active to True.  Note that the Active property must be set after all other properties have been specified.

6.	Create another instance of the TDataSource component.  Connect it to the qryOrders query by setting its DataSet property to qryOrders.  Also, set the name of the component to dsOrders.

7.	Place a TcxGrid control onto the form and create a structure of grid levels and views as shown in the image below:

Each level (lvCars and lvOrders) is associated with a data-aware grid table view (tvCars and tvOrders, respectively).  Refer to the Working with Levels section to see how to create such a structure at design time or by code.

8.	Open the tvCars view’s properties in the Object Inspector and set them as follows:

•	DataController.DataSource to dsCars

•	DataController.DataModeController.GridMode to True (activates GridMode for the master view).

9.	In a similar way, customize the tvOrders view.  Set its properties to the following values:

•	DataController.DataSource to dsOrders

•	DataController.DataModeController.GridMode to True (activates GridMode for the detail view).

10.	Create columns for the views.  For this purpose, you can right-click the view boxes in the Structure Navigator and select the Create All Columns option from the context menu.  The command creates a column for every field from the underlying dataset, specifies the column caption and width and assigns default editors based on the corresponding field properties.

Now you can run the application and work with the grid control.  Customizing grid views is described in other documents within this help file:

•	Data Editing Using Inplace Editors describes how to specify editors for items

•	Style Repository describes applying styles to grid views

The GridModeDemo provides a more elaborate example of implementing a master-detail relationship in grid mode.


Unbound Mode: Master Detail

See Also

ExpressQuantumGrid provides unbound mode to display custom data (from non data-aware sources) within grid views.  In unbound mode, the data controller of a view is not connected to any data source and therefore must be populated with values manually: record-by-record and item-by-item.  First, you should set the number of records to display and then set the field values for each record.

Unbound mode can be useful, for instance, when you need to represent runtime created data within a grid control.  In unbound mode, you are notified of editing data via the DataController.OnDataChanged event.  This event is fired when the end-user modifies cell values, deletes a specific record or inserts a new one.  You may find that use of the DataController.OnDataChanged event is not suitable for responding to user manipulation such as updating your external data source, for instance. In this case, you should consider use of provider mode.  This also allows you to display custom data (from non data-aware sources).  However, provider mode gives you more functionality while editing data within views.  See the Provider Mode and Provider Mode: Master-Detail documents for more information.

The Unbound Mode section provides an example of implementing unbound mode to fill a single view with data.  This document provides a simple example of how to create a master-detail relationship in unbound mode (both master and detail views will work in unbound mode).

Unbound mode is supported by non data-aware views (TcxGridTableView, TcxGridBandedTableView, TcxGridCardView and TcxGridChartView).  Note that neither a card view nor a chart view can become a master view.

A master-detail relationship associates every single record from a master data source with zero or more records from a detail data source.  To set up a master-detail relationship in unbound mode, you need to:

1.	Create a hierarchical structure of grid levels and views similar to the one shown on the following image:

MasterTableView will represent a master data source.  DetailTableView will represent a detail data source.

Refer to the Working with Levels section to learn how to create such a structure at design time and via code.  Note that in unbound and provider modes, you should use non data-aware versions of views (TcxGridTableView, TcxGridBandedTableView, TcxGridCardView and TcxGridChartView).

2.	Populate the master view with data.

3.	Populate the detail view with data.  Doing this, you should bind data to a specific master row.

The last two steps can be performed via code only.

Detail views in EQGrid are represented by their "clones".  A clone is an instance of a detail view displaying records corresponding to a specific master row.  For every detail clone you can obtain a reference to the DataController object using which, you can populate this particular view with data in unbound mode.  To access the DataController of a specific detail, use the DataController.GetDetailDataController function of a master view.

This function requires two parameters: record index and relation index.  The record index indicates the zero-based index of the master row for which to get the detail data controller.  Record indexes correspond to the natural order of records (i.e. with no sorting applied).  Record indexes always refer to the same data regardless of the position of a record within the view.

The relation index indicates the zero-based index of a master-detail relationship for a master view (if there are several detail views).  For the DetailTableView1 view (see the image below), the relation index is 0.  For DetailTableView2, the relation index is 1.

Once you obtain the view’s DataController object, you can specify the number of records to display and populate the data controller with values.  To set the number of records, use the data controller’s RecordCount property.  The Values property allows you to specify the value for each cell.  The first parameter of the Values property specifies the record index.  The second parameter specifies the index of the item for which to set a value.

Let’s consider a simple example implementing a master-detail relationship in unbound mode (both master and detail views will work in unbound mode).

The master table view will represent information on planets while the detail view will display their satellites.

Assume that the master view (FMasterTableView) contains only two rows.  Therefore, only two detail clones of the FDetailTableView view corresponding to these rows 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;

The full code of the example is listed below.  It shows how to create a grid control, customize it for representing a master-detail relationship and populate the master and detail views.  This is performed in the following procedures:

•	CreateGrid

Creates a grid control and the structure of levels and views objects.

•	CreateColumns

Creates columns in the master and table views.  Note that in unbound and provider modes the column’s DataBinding.ValueTypeClass property is assigned.  This indicates the data type of values to edit within columns.

•	SetLookAndFeel

Applies a predefined style sheet to master and detail views.  Predefined style sheets are declared in the cxGridPredefinedStyles unit.

•	FillMasterView and FillDetailView

Populate the master and detail views with data.

•	FormCreate (the form’s OnCreate event handler)

Calls the aforementioned procedures.

To run the example:

•	create an empty application

•	replace the code of your Unit1 module with the following code

•	assign the form’s OnCreate event handler to the FormCreate method

The following image shows the grid control created in this example:

The full code of the example

To see C++ Builder code, use this link.

//Delphi

unit Unit1;

interface

uses

  Windows, Messages, SysUtils, Variants, Classes, Graphics, Controls, Forms, Dialogs, cxStyles, cxCustomData, cxGraphics, cxFilter, cxData, cxEdit, cxGridCustomTableView, cxGridTableView, cxClasses, cxControls, cxGridCustomView, cxGridLevel, cxGrid;

type

  TForm1 = class(TForm)

    procedure FormCreate(Sender: TObject);

  private

    FGrid: TcxGrid;

    FMasterTableView: TcxGridTableView;

    FDetailTableView: TcxGridTableView;

  public

    procedure CreateGrid;

    procedure CreateColumns;

    procedure SetLookAndFeel;

    procedure FillMasterView;

    procedure FillDetailView;

  end;

var

  Form1: TForm1;

implementation

uses

  cxDataStorage, cxGridPredefinedStyles;

{$R *.dfm}

procedure TForm1.FillDetailView;

var

  I: Integer;

  ADetDataController: TcxCustomDataController;

begin

  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;

end;

procedure TForm1.FillMasterView;

begin

  with FMasterTableView.DataController do

  begin

    BeginUpdate;

    try

      RecordCount := 2;

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

      Values[0, 1] := 778330;

      Values[0, 2] := 4332.71;

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

      Values[1, 1] := 149600;

      Values[1, 2] := 365.26;

    finally

      EndUpdate;

    end;

  end;

end;

procedure TForm1.FormCreate(Sender: TObject);

begin

  CreateGrid;

  CreateColumns;

  SetLookAndFeel;

  FillMasterView;

  FillDetailView;

end;

procedure TForm1.CreateColumns;

begin

  with FMasterTableView do

  begin

    BeginUpdate;

    try

      with CreateColumn do

      begin

        Caption := 'Planet';

        Name := 'mtPlanet';

        DataBinding.ValueTypeClass := TcxStringValueType;

        Width := 90;

      end;

      with CreateColumn do

      begin

        Caption := 'Distance(000km)';

        Name := 'mtDistance';

        DataBinding.ValueTypeClass := TcxFloatValueType;

        Width := 130;

      end;

      with CreateColumn do

      begin

        Caption := 'Period(days)';

        Name := 'mtPeriod';

        DataBinding.ValueTypeClass := TcxFloatValueType;

        Width := 150;

      end;

    finally

      EndUpdate;

    end

  end;

  with FDetailTableView do

  begin

    BeginUpdate;

    try

      with CreateColumn do

      begin

        Caption := 'Satellite';

        Name := 'mtSatellite';

        DataBinding.ValueTypeClass := TcxStringValueType;

        Width := 100;

      end;

      with CreateColumn do

      begin

        Caption := 'Distance(000km)';

        Name := 'mtDistance';

        DataBinding.ValueTypeClass := TcxFloatValueType;

        Width := 160;

      end;

      with CreateColumn do

      begin

        Caption := 'Period(days)';

        Name := 'mtPeriod';

        DataBinding.ValueTypeClass := TcxFloatValueType;

        Width := 90;

      end;

    finally

      EndUpdate;

    end;

  end;

end;

procedure TForm1.CreateGrid;

begin

  FGrid := TcxGrid.Create(Self);

  with FGrid do

  begin

    FMasterTableView :=
      CreateView(TcxGridTableView) as TcxGridTableView;

    Levels.Add.GridView := FMasterTableView;

    FDetailTableView :=
      CreateView(TcxGridTableView) as TcxGridTableView;

    Levels[0].Add.GridView := FDetailTableView;

    Align := alClient;

    Parent := Self;

  end;

end;

procedure TForm1.SetLookAndFeel;

begin

  FMasterTableView.Styles.StyleSheet := TcxdmGridPredefinedStyles.Create(Self).GridTableViewStyleSheetDevExpress;

  FDetailTableView.Styles.StyleSheet := FMasterTableView.Styles.StyleSheet;

end;

end.

//C++ Builder

//Unit1.h

#ifndef Unit1H

#define Unit1H

//-------------------------------------------------------------------

#include <Classes.hpp>

#include <Controls.hpp>

#include <StdCtrls.hpp>

#include <Forms.hpp>

#include <cxGridTableView.hpp>

//-------------------------------------------------------------------

class TForm1 : public TForm {

__published:

  void __fastcall FormCreate(TObject *Sender);

private:

  TcxGrid * FGrid;

  TcxGridTableView * FMasterTableView, * FDetailTableView;

public:

  __fastcall TForm1(TComponent* Owner);

  void CreateGrid();

  void CreateColumns();

  void SetLookAndFeel();

  void FillMasterView();

  void FillDetailView();

};

//-------------------------------------------------------------------

extern PACKAGE TForm1 *Form1;

//-------------------------------------------------------------------

#endif

//Unit1.cpp

#include <vcl.h>

#pragma hdrstop

#include "Unit1.h"

#include <cxGridPredefinedStyles.hpp>

//-------------------------------------------------------------------

#pragma package(smart_init)

#pragma link "cxClasses"

#pragma link "cxControls"

#pragma link "cxData"

#pragma link "cxDBData"

#pragma link "cxEdit"

#pragma link "cxFilter"

#pragma link "cxGraphics"

#pragma link "cxGridCustomTableView"

#pragma link "cxGridCustomView"

#pragma link "cxGridDBTableView"

#pragma link "cxGridLevel"

#pragma link "cxStyles"

#pragma link "cxGridPredefinedStyles"

#pragma resource "*.dfm"

TForm1 *Form1;

//-------------------------------------------------------------------

// TForm1

__fastcall TForm1::TForm1(TComponent* Owner) : TForm(Owner) {

}

void TForm1::FillDetailView() {

  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();

  }

}

void TForm1::FillMasterView() {

  TcxCustomDataController * AMasterDataController =    FMasterTableView->DataController;

  AMasterDataController->BeginUpdate();

  try {

    AMasterDataController->RecordCount = 2;

    AMasterDataController->Values[0][0] = "Jupiter";

    AMasterDataController->Values[0][1] = 778330;

    AMasterDataController->Values[0][2] = 4332.71;

    AMasterDataController->Values[1][0] = "Earth";

    AMasterDataController->Values[1][1] = 149600;

    AMasterDataController->Values[1][2] = 365.26;

  } __finally {

    AMasterDataController->EndUpdate();

  }

}

void TForm1::CreateGrid() {

  FGrid = new TcxGrid(this);

  FMasterTableView = (TcxGridTableView*)
    FGrid->CreateView(__classid(TcxGridTableView));

  FGrid->Levels->Add()->GridView = FMasterTableView;

  FDetailTableView = (TcxGridTableView*)
    FGrid->CreateView(__classid(TcxGridTableView));

  FGrid->Levels->Items[0]->Add()->GridView = FDetailTableView;

  FGrid->Align = alClient;

  FGrid->Parent = this;

}

void TForm1::CreateColumns() {

  TcxGridColumn * AColumn;

  FMasterTableView->BeginUpdate();

  try {

    AColumn = FMasterTableView->CreateColumn();

    AColumn->DataBinding->ValueTypeClass =

      __classid(TcxStringValueType);

    AColumn->Caption = "Planet";

    AColumn->Name = "mtPlanet";

    AColumn->Width = 90;

    AColumn = FMasterTableView->CreateColumn();

    AColumn->DataBinding->ValueTypeClass =

      __classid(TcxFloatValueType);

    AColumn->Caption = "Distance(000km)";

    AColumn->Name = "mtDistance";

    AColumn->Width = 130;

    AColumn = FMasterTableView->CreateColumn();

    AColumn->DataBinding->ValueTypeClass =

      __classid(TcxFloatValueType);

    AColumn->Caption = "Period(days)";

    AColumn->Name = "mtPeriod";

    AColumn->Width = 150;

  } __finally {

    FMasterTableView->EndUpdate();

  }

  FDetailTableView->BeginUpdate();

  try {

    AColumn = FDetailTableView->CreateColumn();

    AColumn->DataBinding->ValueTypeClass =

      __classid(TcxStringValueType);

    AColumn->Caption = "Satellite";

    AColumn->Name = "mtSatellite";

    AColumn->Width = 100;

    AColumn = FDetailTableView->CreateColumn();

    AColumn->DataBinding->ValueTypeClass =

      __classid(TcxFloatValueType);

    AColumn->Caption = "Distance(000km)";

    AColumn->Name = "mtDistance";

    AColumn->Width = 160;

    AColumn = FDetailTableView->CreateColumn();

    AColumn->DataBinding->ValueTypeClass =

      __classid(TcxFloatValueType);

    AColumn->Caption = "Period(days)";

    AColumn->Name = "mtPeriod";

    AColumn->Width = 90;

  } __finally {

    FDetailTableView->EndUpdate();

  }

}

void __fastcall TForm1::FormCreate(TObject *Sender) {

  CreateGrid();

  CreateColumns();

  SetLookAndFeel();

  FillMasterView();

  FillDetailView();

}

void TForm1::SetLookAndFeel() {

  FMasterTableView->Styles->StyleSheet = (new TcxdmGridPredefinedStyles(this))->GridTableViewStyleSheetDevExpress;

  FDetailTableView->Styles->StyleSheet =
    FMasterTableView->Styles->StyleSheet;

}


Provider Mode: Master-Detail

See Also

Provider mode in ExpressQuantumGrid allows you to populate a grid control with data from a custom (user-defined) data source.  This mode is useful when it is necessary to represent data within a grid control from non data-aware sources (data which cannot be accessed via a TDataSource component).

EQGrid provides unbound mode, which can also be used to represent user-defined data.  However, this mode gives you fewer capabilities than provider mode to respond to user editing-aware actions (modifying cell values, inserting and deleting records, etc).  In provider mode, it is easier to respond to such actions by implementing appropriate methods of the custom data source.  To learn about unbound mode, see the Unbound Mode and Unbound Mode: Master-Detail sections.

To create a custom data source, you need to inherit from the TcxCustomDataSource class and override some of its methods, which are called by a data controller in response to user specific actions.

For instance, you can create a custom data source to represent data from an external file.  Each time a user appends a record within a view, the view’s data controller calls the AppendRecord method of your custom data source.  You can implement this method in order to add a new entry to the file corresponding to the appended record.

The Provider Mode section shows how to implement provider mode to represent data from a text file.  The current document exemplifies the creation of a master-detail relationship in provider mode (both master and detail views will work in provider mode).

A master-detail relationship associates every single record from a master data source with zero or more records from a detail data source.  To set up a master-detail relationship in provider mode, you need to:

1.	Create a hierarchical structure of grid levels and views similar to the one shown on the following image:

MasterTableView and DetailTableView will represent the master and detail custom data sources respectively.

Refer to the Working with Levels section to learn how to create such a structure at design time and via code.  Note that in unbound and provider modes, you should use non data-aware versions of views (TcxGridTableView, TcxGridBandedTableView and TcxGridCardView).

2.	Create a master custom data source and assign it to the master view’s DataController.CustomDataSource property.

3.	Create a detail custom data source and assign it to the detail view’s DataController.CustomDataSource property.

The last two steps can be performed only via code.

A detail view in EQGrid is represented by its "clones".  A clone is an instance of the detail view displaying records corresponding to a specific master row.

When creating a custom data source, you usually have to override several methods:

•	GetItemHandle

The method is responsible for item identification.

•	GetRecordCount

Must retrieve the number of records to display within a view.  In a detail custom data source, GetRecordCount should return the number of records for a specific detail clone, i.e. according to the currently selected master row.

•	GetValue

Returns a value from the custom data source for a specific cell.  Before populating a grid view, the data controller calls the GetRecordCount method of the custom data source.  Knowing the number of records and items to display, the data controller then calls the GetValue method to populate the view with data.  GetValue is called for every cell in the view.

•	SetValue

The method is called when the contents of a specific cell is modified.  You should implement SetValue to post the modified value to the custom data source.

•	InsertRecord

The method is called when a new record is inserted within a view.  You should implement InsertRecord to add a new record to the custom data source.

•	AppendRecord

The method is called when a new record is appended within a view or inserted within a view containing no records.  You should implement AppendRecord to add a new record at the end of the custom data source.

•	DeleteRecord

The method is called in response to the deletion of a specific record.  You should implement DeleteRecord to delete the corresponding record from the custom data source.

Let’s consider a simple example where both master and detail views work in provider mode.  A master view is bound to a custom data source providing data from the TStringList component named MasterStringList.  In turn, every entry in this list is bound to a corresponding external (detail) string list via the Objects property.  Every string in a detail list is specified in the form: Name=Value.  The Name and Value portions are displayed within two columns of a detail view.

The following code shows how to implement the GetRecordCount method of a detail custom data source for this example:

function TUserDetailDataSource.GetRecordCount: Integer;

var

  ADetailStringList: TStringList;

begin

  Result := 0;

  if GetMasterRecordIndex >= 0 then

  begin

    ADetailStringList :=
      TStringList(MasterStringList.Objects[GetMasterRecordIndex]);

    Result := ADetailStringList.Count;

  end;

end;

The function determines the number of records to display according to the record index of the relative master row.  GetRecordCount locates the record in MasterStringList corresponding to the master row and obtains a reference to the detail list.  The number of records to display is determined by the number of items contained in this list.

The GetMasterRecordIndex function used in this code is defined as follows:

function TUserDetailDataSource.GetMasterRecordIndex: Integer;

begin

  Result := DataController.GetMasterRecordIndex;

end;

This returns the record index of the master row corresponding to the current detail.

The GetValue method of the detail custom data source returns the value of the detail dataset located within the specified record and item.  It returns either the Name or the Value portion of the list entry.  To get the desired detail list from MasterStringList, the GetMasterRecordIndex function is used.

function TUserDetailDataSource.GetValue(ARecordHandle: TcxDataRecordHandle;

  AItemHandle: TcxDataItemHandle): Variant;

var

  ADetailStringList: TStringList;

  AColumnId: Integer;

  AName: string;

begin

  //Get the column’s ID from the visible item index(AItemHandle)

  AColumnID := GetColumnID(Integer(AItemHandle));

  //Get the detail list

  ADetailStringList := TStringList(MasterStringList.Objects[GetMasterRecordIndex]);

  //Return the Name or Value part of the ADetailStringList[ARecordHandle] string

  //based on the column’s ID

  AName := ADetailStringList.Names[Integer(ARecordHandle)];

  if AColumnId = 0 then

    Result := AName

  else

    Result := ADetailStringList.Values[AName];

end;

The AItemHandle parameter of the GetValue method determines the visible item’s (column’s) position.  This cannot be used as a unique identifier of the column because the column’s position can be changed at runtime.  In this example, columns are recognized by their ID’s.  ID is a unique value automatically assigned to a column on creation; the ID of the first column is 0, the ID of the second column is 1, etc.  Other methods of item identification are discussed in the Provider Mode document.

The full code of this example is listed below.  It shows how to create a grid control, customize it for representing a master-detail relationship, create custom data sources and assign them to appropriate views.  All this is implemented in the following procedures:

•	CreateMasterStringList

Fills MasterStringList and creates detail string lists.

•	CreateGrid

Creates the grid control and the structure of level and view objects.

•	CreateColumns

Creates one column in a master view and two columns in a detail view.  Note that in unbound and provider modes the column’s DataBinding.ValueTypeClass property is assigned.  This indicates the data type of values to edit within columns.

•	SetLookAndFeel

Applies a predefined style sheet to master and detail views.  Predefined style sheets are declared in the cxGridPredefinedStyles unit.

•	FormCreate (the form’s OnCreate event handler)

Calls the aforementioned procedures, creates master and detail custom data sources and assigns them to relative views.

The resulting grid control is displayed on the following image:

You can refer to the UnboundExternalDataDemo demonstrating a more elaborate example of implementing a master-detail relationship in provider mode.

The full code of the example.

Note the implementation of the SetValue, InsertRecord and DeleteRecord methods.  They enable the end-user to modify cell values, insert and delete records by pressing the INS and DEL keys respectively.

To run this code:

•	create an empty application

•	replace the code of your Unit1 module with the following code

•	assign the form’s OnCreate and OnDestroy event handlers to the FormCreate and FormDestroy methods respectively

To see C++ Builder code, use this link.

//Delphi

unit Unit1;

interface

uses

  Windows, Messages, SysUtils, Variants, Classes, Graphics, Controls, Forms, Dialogs, cxCustomData, cxGrid, cxGridCustomTableView, cxGridTableView, cxDataStorage, cxGridPredefinedStyles;

type

  TUserDataSource = class(TcxCustomDataSource)

  protected

    function AppendRecord: Pointer; override;

    procedure DeleteRecord(ARecordHandle: Pointer); override;

    function GetRecordCount: Integer; override;

    function GetValue(ARecordHandle: TcxDataRecordHandle;

      AItemHandle: TcxDataItemHandle): Variant; override;

    function InsertRecord(ARecordHandle: Pointer): Pointer; override;

    procedure SetValue(ARecordHandle: TcxDataRecordHandle;

      AItemHandle: TcxDataItemHandle; const AValue: Variant); override;

  end;

  TUserDetailDataSource = class(TcxCustomDataSource)

  protected

    function AppendRecord: Pointer; override;

    procedure DeleteRecord(ARecordHandle: Pointer); override;

    function GetColumnID(AItemIndex: Integer): Integer;

    function GetRecordCount: Integer; override;

    function GetValue(ARecordHandle: TcxDataRecordHandle; AItemHandle: TcxDataItemHandle): Variant; override;

    function InsertRecord(ARecordHandle: Pointer): Pointer; override;

    procedure SetValue(ARecordHandle: TcxDataRecordHandle;

      AItemHandle: TcxDataItemHandle; const AValue: Variant); override;

  public

    function GetMasterRecordIndex: Integer;

  end;

  TForm1 = class(TForm)

    procedure FormCreate(Sender: TObject);

    procedure FormDestroy(Sender: TObject);

  private

    FGrid: TcxGrid;

    FMasterView, FDetailView: TcxGridTableView;

  public

    procedure CreateMasterStringList;

    procedure FreeMasterStringList;

    procedure CreateGrid;

    procedure CreateColumns;

    procedure SetLookAndFeel;

  end;

var

  Form1: TForm1;

implementation

{$R *.dfm}

var

  MasterStringList: TStringList;

{ TUserDataSource }

function TUserDataSource.AppendRecord: Pointer;

begin

  Result := Pointer(MasterStringList.AddObject('', TStringList.Create));

  DataChanged;

end;

procedure TUserDataSource.DeleteRecord(ARecordHandle: Pointer);

begin

  MasterStringList.Objects[Integer(ARecordHandle)].Free;

  MasterStringList.Delete(Integer(ARecordHandle));

  DataChanged;

end;

function TUserDataSource.GetRecordCount: Integer;

begin

  Result := MasterStringList.Count;

end;

function TUserDataSource.GetValue(ARecordHandle: TcxDataRecordHandle;

  AItemHandle: TcxDataItemHandle): Variant;

begin

  Result := MasterStringList[Integer(ARecordHandle)];

end;

function TUserDataSource.InsertRecord(ARecordHandle: Pointer): Pointer;

begin

  MasterStringList.InsertObject(Integer(ARecordHandle), '', TStringList.Create);

  Result := ARecordHandle;

  DataChanged;

end;

procedure TUserDataSource.SetValue(ARecordHandle: TcxDataRecordHandle;

  AItemHandle: TcxDataItemHandle; const AValue: Variant);

begin

  MasterStringList[Integer(ARecordHandle)] := AValue;

end;

{ TUserDetailDataSource }

function TUserDetailDataSource.AppendRecord: Pointer;

var

  ADetailStringList: TStringList;

begin

  ADetailStringList := TStringList(MasterStringList.Objects[GetMasterRecordIndex]);

  Result := Pointer(ADetailStringList.Add(''));

  DataChanged;

end;

procedure TUserDetailDataSource.DeleteRecord(ARecordHandle: Pointer);

var

  ADetailStringList: TStringList;

begin

  ADetailStringList := TStringList(MasterStringList.Objects[GetMasterRecordIndex]);

  ADetailStringList.Delete(Integer(ARecordHandle));

  DataChanged;

end;

function TUserDetailDataSource.GetMasterRecordIndex: Integer;

begin

  Result := DataController.GetMasterRecordIndex;

end;

function TUserDetailDataSource.GetRecordCount: Integer;

var

  ADetailStringList: TStringList;

begin

  Result := 0;

  if GetMasterRecordIndex >= 0 then

  begin

    ADetailStringList := TStringList(
      MasterStringList.Objects[GetMasterRecordIndex]);

    Result := ADetailStringList.Count;

  end;

end;

function TUserDetailDataSource.GetColumnID(AItemIndex: Integer): Integer;

begin

  Result := TcxCustomGridTableItem(DataController.GetItem(AItemIndex)).ID;

end;

function TUserDetailDataSource.GetValue(ARecordHandle: TcxDataRecordHandle;

  AItemHandle: TcxDataItemHandle): Variant;

var

  ADetailStringList: TStringList;

  AColumnId: Integer;

  AName: string;

begin

  AColumnID := GetColumnID(Integer(AItemHandle));

  ADetailStringList := TStringList(MasterStringList.Objects[GetMasterRecordIndex]);

  AName := ADetailStringList.Names[Integer(ARecordHandle)];

  if AColumnId = 0 then

    Result := AName

  else

    Result := ADetailStringList.Values[AName];

end;

procedure TUserDetailDataSource.SetValue(

  ARecordHandle: TcxDataRecordHandle; AItemHandle: TcxDataItemHandle;

  const AValue: Variant);

var

  ADetailStringList: TStringList;

  AColumnId: Integer;

  S1, S2: string;

begin

  AColumnId := GetColumnID(Integer(AItemHandle));

  ADetailStringList := TStringList(MasterStringList.Objects[GetMasterRecordIndex]);

  if AColumnId = 0 then

  begin

    if VarIsNull(AValue) then

      S1 := ''

    else

      S1 := AValue;

      S2 := ADetailStringList.Values[
        ADetailStringList.Names[Integer(ARecordHandle)]]

    end

  else

  begin

    S1 := ADetailStringList.Names[Integer(ARecordHandle)];

    if VarIsNull(AValue) then

      S2 := ''

    else

      S2 := AValue;

  end;

  ADetailStringList[Integer(ARecordHandle)]:= Format('%S=%S', [S1,S2]);

end;

function TUserDetailDataSource.InsertRecord(ARecordHandle: Pointer): Pointer;

var

  ADetailStringList: TStringList;

begin

  ADetailStringList := TStringList(MasterStringList.Objects[GetMasterRecordIndex]);

  ADetailStringList.Insert(Integer(ARecordHandle), '');

  Result := ARecordHandle;

  DataChanged;

end;

{ TForm1 }

procedure TForm1.CreateGrid;

begin

  FGrid := TcxGrid.Create(Self);

  with FGrid do

  begin

    FMasterView := CreateView(TcxGridTableView) as TcxGridTableView;

    Levels.Add.GridView := FMasterView;

    FDetailView := CreateView(TcxGridTableView) as TcxGridTableView;

    Levels[0].Add.GridView := FDetailView;

    Align := alClient;

    Parent := Self;

  end;

end;

procedure TForm1.CreateColumns;

begin

  with FMasterView.CreateColumn do

  begin

    DataBinding.ValueTypeClass := TcxStringValueType;

    Caption := 'Planet';

    Name := 'mvPlanet';

    Width := 300;

  end;

  with FDetailview.CreateColumn do

  begin

    DataBinding.ValueTypeClass := TcxStringValueType;

    Caption := 'Satellite';

    Name := 'mvSatellite';

    Width := 150;

  end;

  with FDetailview.CreateColumn do

  begin

    DataBinding.ValueTypeClass := TcxStringValueType;

    Caption := 'Distance';

    Name := 'mvDistance';

    Width := 150;

  end;

end;

procedure TForm1.CreateMasterStringList;

var

  ADetail1, ADetail2: TStringList;

begin

  ADetail1 := TStringList.Create;

  with ADetail1 do

  begin

    Add('Despina=53');

    Add('Galatea=62');

    Add('Proteus=118');

  end;

  ADetail2 :=TStringList.Create;

  with ADetail2 do

  begin

    Add('Cordelia=50');

    Add('Ophelia=54');

    Add('Bianca=59');

    Add('Cressida=62');

    Add('Desdemona=63');

  end;

  MasterStringList := TStringList.Create();

  with MasterStringList do

  begin

    AddObject('Neptune', ADetail1);

    AddObject('Uranus', ADetail2);

  end;

end;

procedure TForm1.FreeMasterStringList;

var

  I: Integer;

begin

  for I := 0 to MasterStringList.Count - 1 do

    MasterStringList.Objects[I].Free;

  MasterStringList.Free;

end;

procedure TForm1.FormCreate(Sender: TObject);

begin

  CreateMasterStringList;

  CreateGrid;

  CreateColumns;

  SetLookAndFeel;

  FMasterView.DataController.CustomDataSource := TUserDataSource.Create;

  FDetailView.DataController.CustomDataSource := TUserDetailDataSource.Create;

end;

procedure TForm1.FormDestroy(Sender: TObject);

begin

  FreeMasterStringList;

end;

procedure TForm1.SetLookAndFeel;

begin

  FMasterView.Styles.StyleSheet := TcxdmGridPredefinedStyles.Create(Self).GridTableViewStyleSheetDevExpress;

  FDetailView.Styles.StyleSheet := FMasterView.Styles.StyleSheet;

end;

end.

//C++ Builder

//Unit1.h

#ifndef Unit1H

#define Unit1H

//-------------------------------------------------------------------

#include <Classes.hpp>

#include <Controls.hpp>

#include <StdCtrls.hpp>

#include <Forms.hpp>

#include <cxGridTableView.hpp>

class TUserDataSource: public TcxCustomDataSource {

protected:

  virtual void * __fastcall AppendRecord(void);

  virtual void __fastcall DeleteRecord(void * ARecordHandle);

  virtual int __fastcall GetRecordCount();

  virtual Variant __fastcall GetValue(void * ARecordHandle, void * AItemHandle);

  virtual void * __fastcall InsertRecord(void * ARecordHandle);

  virtual void __fastcall SetValue(void * ARecordHandle, void * AItemHandle, const Variant &AValue);

};

class TUserDetailDataSource: public TcxCustomDataSource {

protected:

  virtual void * __fastcall AppendRecord(void);

  virtual void __fastcall DeleteRecord(void * ARecordHandle);

  int GetColumnID(int AItemIndex);

  virtual int __fastcall GetRecordCount();

  virtual Variant __fastcall GetValue(void * ARecordHandle, void * AItemHandle);

  virtual void * __fastcall InsertRecord(void * ARecordHandle);

  virtual void __fastcall SetValue(void * ARecordHandle, void * AItemHandle, const Variant &AValue);

public:

  int GetMasterRecordIndex();

};

//-------------------------------------------------------------------

class TForm1 : public TForm {

__published:

  void __fastcall FormCreate(TObject *Sender);

  void __fastcall FormDestroy(TObject *Sender);

private:

  TcxGrid * FGrid;

  TcxGridTableView * FMasterView, * FDetailView;

public:

  __fastcall TForm1(TComponent* Owner);

  void CreateMasterStringList();

  void FreeMasterStringList();

  void CreateGrid();

  void CreateColumns();

  void SetLookAndFeel();

};

//-------------------------------------------------------------------

extern PACKAGE TForm1 *Form1;

//-------------------------------------------------------------------

#endif

//Unit1.cpp

#include <vcl.h>

#pragma hdrstop

#include "Unit1.h"

#include <cxGridPredefinedStyles.hpp>

//-------------------------------------------------------------------

#pragma package(smart_init)

#pragma link "cxClasses"

#pragma link "cxControls"

#pragma link "cxData"

#pragma link "cxDBData"

#pragma link "cxEdit"

#pragma link "cxFilter"

#pragma link "cxGraphics"

#pragma link "cxGridCustomTableView"

#pragma link "cxGridCustomView"

#pragma link "cxGridDBTableView"

#pragma link "cxGridLevel"

#pragma link "cxStyles"

#pragma link "cxGridPredefinedStyles"

#pragma resource "*.dfm"

TForm1 *Form1;

TStringList * MasterStringList;

//-------------------------------------------------------------------

//TUserDataSource

void * __fastcall TUserDataSource::AppendRecord(void) {

  void * res = (void*)MasterStringList->AddObject("", new TStringList());

  DataChanged();

  return res;

}

void __fastcall TUserDataSource::DeleteRecord(void * ARecordHandle) {

  MasterStringList->Objects[(int)ARecordHandle]->Free();

  MasterStringList->Delete((int)ARecordHandle);

  DataChanged();

}

int __fastcall TUserDataSource::GetRecordCount() {

  return MasterStringList->Count;

}

Variant __fastcall TUserDataSource::GetValue(void * ARecordHandle, void * AItemHandle) {

  return MasterStringList->Strings[(int)ARecordHandle];

}

void * __fastcall TUserDataSource::InsertRecord(void * ARecordHandle) {

  MasterStringList->InsertObject((int)ARecordHandle, "", new TStringList());

  DataChanged();

  return ARecordHandle;

}

void __fastcall TUserDataSource::SetValue(void * ARecordHandle, void * AItemHandle, const Variant &AValue) {

  MasterStringList->Strings[(int)ARecordHandle] = AValue;

}

//-------------------------------------------------------------------

// TUserDetailDataSource

void * __fastcall TUserDetailDataSource::AppendRecord(void) {

  TStringList * ADetailStringList = (TStringList*)

    MasterStringList->Objects[GetMasterRecordIndex()];

  void * res = (void*) ADetailStringList->Add("");

  DataChanged();

  return res;

}

void __fastcall TUserDetailDataSource::DeleteRecord(void * ARecordHandle) {

  TStringList * ADetailStringList;

  ADetailStringList = (TStringList*)
    MasterStringList->Objects[GetMasterRecordIndex()];

  ADetailStringList->Delete((int)ARecordHandle);

  DataChanged();

}

int TUserDetailDataSource::GetMasterRecordIndex() {

  return DataController->GetMasterRecordIndex();

}

int __fastcall TUserDetailDataSource::GetRecordCount() {

  TStringList * ADetailStringList;

  int Result = 0;

  if (GetMasterRecordIndex() >= 0) {

    ADetailStringList =
    (TStringList*)MasterStringList->Objects[GetMasterRecordIndex()];

    Result = ADetailStringList->Count;

  }

  return Result;

}

int TUserDetailDataSource::GetColumnID(int AItemIndex) {

  return ((TcxCustomGridTableItem*)
    DataController->GetItem(AItemIndex))->ID;

}

Variant __fastcall TUserDetailDataSource::GetValue(void * ARecordHandle, void * AItemHandle) {

  TStringList * ADetailStringList;

  String AName;

  Variant Result;

  int AColumnId = GetColumnID((int)AItemHandle);

  ADetailStringList = (TStringList*)
    MasterStringList->Objects[GetMasterRecordIndex()];

  AName = ADetailStringList->Names[(int)ARecordHandle];

  if (AColumnId == 0)

    Result = AName;

  else

    Result = ADetailStringList->Values[AName];

  return Result;

}

void __fastcall TUserDetailDataSource::SetValue(void * ARecordHandle, void * AItemHandle, const Variant &AValue) {

  TStringList * ADetailStringList;

  int AColumnId;

  String S1, S2;

  AColumnId = GetColumnID((int)AItemHandle);

  ADetailStringList = (TStringList*)
    MasterStringList->Objects[GetMasterRecordIndex()];

  if (AColumnId == 0) {

    if (VarIsNull(AValue))

      S1 = "";

    else

      S1 = AValue;

    S2 = ADetailStringList->Values[
      ADetailStringList->Names[(int)ARecordHandle]];

  }

  else {

    S1 = ADetailStringList->Names[(int)ARecordHandle];

    if (VarIsNull(AValue))

      S2 = "";

    else

      S2 = AValue;

  }

  TVarRec v[] = {S1, S2};

  ADetailStringList->Strings[(int)ARecordHandle] = Format("%S=%S", v, ARRAYSIZE(v)-1);

}

void * __fastcall TUserDetailDataSource::InsertRecord(void * ARecordHandle) {

  TStringList * ADetailStringList;

  ADetailStringList = (TStringList*)
    MasterStringList->Objects[GetMasterRecordIndex()];

  ADetailStringList->Insert((int)ARecordHandle, "");

  DataChanged();

  return ARecordHandle;

}

//-------------------------------------------------------------------

// TForm1

__fastcall TForm1::TForm1(TComponent* Owner) : TForm(Owner) {

}

void TForm1::CreateGrid() {

  FGrid = new TcxGrid(this);

  FMasterView = (TcxGridTableView*)
    FGrid->CreateView(__classid(TcxGridTableView));

  FGrid->Levels->Add()->GridView = FMasterView;

  FDetailView = (TcxGridTableView*)
    FGrid->CreateView(__classid(TcxGridTableView));

  FGrid->Levels->Items[0]->Add()->GridView = FDetailView;

  FGrid->Align = alClient;

  FGrid->Parent = this;

}

void TForm1::CreateColumns() {

  TcxGridColumn * AColumn;

  AColumn = FMasterView->CreateColumn();

  AColumn->DataBinding->ValueTypeClass =
    __classid(TcxStringValueType);

  AColumn->Caption = "Planet";

  AColumn->Name = "mvPlanet";

  AColumn->Width = 300;

  AColumn = FDetailView->CreateColumn();

  AColumn->DataBinding->ValueTypeClass =
    __classid(TcxStringValueType);

  AColumn->Caption = "Satellite";

  AColumn->Name = "mvSatellite";

  AColumn->Width = 150;

  AColumn = FDetailView->CreateColumn();

  AColumn->DataBinding->ValueTypeClass =
    __classid(TcxStringValueType);

  AColumn->Caption = "Distance";

  AColumn->Name = "mvDistance";

  AColumn->Width = 150;

}

void TForm1::CreateMasterStringList() {

  TStringList * ADetail1, * ADetail2;

  ADetail1 = new TStringList();

  ADetail1->Add("Despina=53");

  ADetail1->Add("Galatea=62");

  ADetail1->Add("Proteus=118");

  ADetail2 = new TStringList();

  ADetail2->Add("Cordelia=50");

  ADetail2->Add("Ophelia=54");

  ADetail2->Add("Bianca=59");

  ADetail2->Add("Cressida=62");

  ADetail2->Add("Desdemona=63");

  MasterStringList = new TStringList();

  MasterStringList->AddObject("Neptune", ADetail1);

  MasterStringList->AddObject("Uranus", ADetail2);

}

void TForm1::FreeMasterStringList() {

  for (int I = 0; I < MasterStringList->Count; I++)

    delete MasterStringList->Objects[I];

  delete MasterStringList;

}

void __fastcall TForm1::FormCreate(TObject *Sender) {

  CreateMasterStringList();

  CreateGrid();

  CreateColumns();

  SetLookAndFeel();

  FMasterView->DataController->CustomDataSource =
    new TUserDataSource();

  FDetailView->DataController->CustomDataSource =
    new TUserDetailDataSource();

}

void __fastcall TForm1::FormDestroy(TObject *Sender) {

  FreeMasterStringList();

}

void TForm1::SetLookAndFeel() {

  FMasterView->Styles->StyleSheet =
    (new TcxdmGridPredefinedStyles(this))->
    GridTableViewStyleSheetDevExpress;

  FDetailView->Styles->StyleSheet = FMasterView->Styles->StyleSheet;

}


Items

See Also

The data in a data store can generally be represented using a tabular layout.  Rows refer to records, while columns identify the fields or attributes of each record.  The term "item" is used to describe a column in data storage.

Item captions and item cells are arranged differently depending upon the view type.

Use the links below to learn more about items and how they are arranged within specific views:

Tabular and Card Views

Chart Views


Items in Table and Card Views

See Also

For the ExpressQuantumGrid the term "item" is used to describe a column in a data store.  In a table view, items stand for columns and are displayed across the view.

In a card view, items are card view rows and are arranged vertically.

The TcxCustomGridTableItem class is the base class for all table items in card views.

All items can be divided into two main groups: data-aware and non data-aware.

Data-aware items (TcxGridDBColumn, TcxGridDBBandedColumn, TcxGridDBCardViewRow) are used in corresponding data-aware views (TcxGridDBTableView, TcxGridDBBandedTableView, TcxGridDBCardView).  Non data-aware items are elements of non data-aware views (TcxGridTableView, TcxGridBandedTableView, TcxGridCardView).

Every view has an Items property that maintains the collection of items created within each view.  You can use the CreateItem method (CreateColumn or CreateRow in some views) to create items manually.  In a non data-aware view, you can create items using the Layout and Data Editor at design time.  In a data-aware view, you can call the DataController.CreateAllItems method to create columns based on dataset fields.  The Component Editor allows you to access all items in a view and create/delete them at design time.

It is possible to get and set a value for an item cell in a focused record via the EditValue member.  The data controller gives you the ability to access the item values of all loaded records.

An item has various attributes controlling its behavior.  For instance, you can prevent a user from editing, focusing item cells, changing the item's position within the "group by" or column header panel, applying sorting or filtering by an item, etc.

Every item has a DataBinding property providing data for items from a view’s data controller. DataBinding retrieves data from and posts it back to a data store.  Data-aware items redefine DataBinding to work with TDataSet fields.

The ExpressQuantumGrid provides a wide range of in-place editors to edit or display item cells.  For instance, the TcxCheckBox editor provides a convenient way to edit Boolean fields.  By default, items are assigned default editors as appropriate.  In bound mode, the default editor is specified by the field type.  For instance, TcxDateEdit is used to edit TDateField fields.  See the FieldName topic for details.

In unbound mode, the default editor is determined by an item’s DataBinding.ValueTypeClass property.  You must specify an appropriate value type to provide the appropriate behavior when sorting, editing, validating and accessing item values.  Refer to the TcxValueType class to learn more about the default editors assigned in unbound mode.

To assign an editor to an item, you can use either the repository (repository and repository items) or the PropertiesClass object.  A repository item defines the specific editor settings used for a particular item editor.  A single repository item can be assigned to the RepositoryItem property of several items, thus creating items with the same edit behavior.  PropertiesClass is another way to set an item editor.  It defines the class of editor properties used to create a specific editor.  If both RepositoryItem and PropertiesClass are assigned, the item editor is determined by a corresponding repository item.  The ExpressQuantumGrid gives you the ability to specify different editors for individual item cells (i.e. on a row by row basis).  You can handle the OnGetProperties event and specify the editor based on the record's position or the data associated with it.  For more information refer to the Data Editing Using Inplace Editors topic.

The GroupIndex property of an item allows you to group data within a view by this item.  Grouping operations are implemented only in table views and are not supported in card views.  You can group data by multiple items.  The grid control provides the "group by" panel to which a user can easily drag a column by its caption to group by this column.

To sort data by an item, you should use the SortOrder property.  You can sort by multiple items by setting the SortOrder property of these items to a value other than soNone.  Data in a view is sorted in the exact SortOrder sequence.  At runtime, a user can sort data by clicking a column's caption.  A small arrow specifies the current sort order.  The up-arrow indicates that data is sorted in ascending order, while the down-arrow indicates that sorting is performed in descending order.

Data filtering within a view is implemented via a data controller.  It provides a Filter property which specifies the filter conditions set for all the items in a specific view.  A filter condition addresses the item, the operator type and the value with which every item cell is compared.  When filtering is applied, only the records matching the filter criteria are displayed within the view.

At runtime, a user can press the filter down-arrow button in a table view to filter by that column.

When a user selects a value from this list, a new EQUAL filter condition (of type "Column = Value") is added to the existing filter criteria.

Selecting All from the list clears the filter condition set for the column.  The Custom item displays a filter dialog that allows an end-user to define filter conditions with other operators (=, <>, <, <=, >, >=, LIKE and NOT LIKE).  For more information on the filter dialog, refer to the Runtime Filtering section.

Our grid control gives you the ability to temporarily remove column(s) from a view.  At runtime, a user can drag individual columns onto the Customization form thus hiding them in the view.

To display a column within the view again, the user must drag this column from the customization form onto the column header or "group by" panel.

Dragging a column onto the Customization form results in setting its Visible property to False.  It is possible to prevent a column from appearing in this form by setting its VisibleForCustomization property to True. In this case, if your column is dragged to the Customization form, it disappears completely and can only be made visible programmatically.


Items in Chart Views

See Also

For the ExpressQuantumGrid the term "item" is used to describe a column in a data store.  In a Chart View, items stand for the columns that correspond to series, data groups, and the default categories.  When series values are grouped at a data level associated with the visible data group, the unique values of this data group determine the categories which series values are arranged into.  Otherwise, the values of the default categories are used to categorize series values.

Each record in a data store corresponds to a category value and at least one series value.

The arrangement options of the items differ from diagram to diagram since each one provides options for visually representing category values and series values which are specific to the type of diagram.  The only thing you need to address to change the manner in which the items are displayed within a Chart View is to activate another diagram (by setting its Active property to True).

As with items in tabular and Card Views, series, data groups, and the default categories can be divided into two groups: data-aware and non data-aware.  Data-aware items (TcxGridDBChartSeries, TcxGridDBChartDataGroup, and TcxGridDBChartCategories) are used in the corresponding data-aware View (TcxGridDBChartView).  Non data-aware items (TcxGridChartSeries, TcxGridChartDataGroup, and TcxGridChartCategories) are elements of the non data-aware View (TcxGridChartView).

A Chart View has the Series, DataGroups, and Categories properties which maintain the collections of items (series, data groups, and the default categories, respectively) created within the View.  To access the series and data groups which are currently visible within a Chart View, use the View’s VisibleSeries and VisibleDataGroups properties.

The Component Editor allows you to access all the series and data groups in a Chart View and create/delete them at design time.  You can use the CreateSeries and CreateDataGroup methods to manually create series and data groups at runtime.

It's possible to get and set the value of an item using either the Values collection of the default categories or the Values collection of a series and data group.  Alternatively, you can use the View’s ViewData.Categories, ViewData.Values, and ViewData.GroupValues indexed collections, which address the same values.  To access values of the items which are currently displayed, use the View’s  ViewData.VisibleCategories, ViewData.VisibleValues, and ViewData.VisibleGroupValues, respectively.

To add a series value, call the AddValue method of the corresponding series.

Every item has a DataBinding property which links items to the data in a View’s data controller which retrieves data from and posts it back to a data store.  Data-aware items redefine DataBinding to work with TDataSet fields.

To sort data by an item, you should use its SortOrder property.

Note:	The sorting applied to the series takes priority over the sorting by the default categories or a data group.  Only a single type of sorting (either by the default categories/data group or series values) is active at a time within the chart.  The series whose values are sorted can be accessed via the View’s SortedSeries property.  End-users are able to customize the sorting applied to the series using the Customization Form.


Records

See Also

Data displayed in a view consists of records.  Each record stores a set of values corresponding to the dataset fields.  The fields or attributes of records are referred to as items in a grid control.

A data controller (the view’s DataController property) provides data loaded from storage as an array of records.  A data controller allows you to read and write a value in a record, append, insert, delete or navigate through records and perform many other operations.  To access a particular value, you just need to supply the record's index and the item's index.

Views display records in different forms.  A grid table view (TcxGridTableView) presents records as a set of rows.  Items in each row are displayed horizontally.  A banded table view (TcxGridBandedTableView) can be used to display record items in bands (a band consists of a set of columns).  In a card view (TcxGridCardView), each record is presented as a card, the items for which are drawn vertically.  A record in a chart view (TcxGridChartView) corresponds to a category and series values within this category.  Series values are presented as data markers and data labels which are visually grouped within the categories and arranged according to the type of the diagram that displays the data.

For more information on views, see the Views topic.

The term "record" is not relevant in chart views, instead "category" and "series values" are used to describe a specific database record.  The information below relates to (banded) table and card views only.

A view does not store all the records itself.  Instead, it obtains them from a data controller when necessary.  A view also has the ViewData object of class TcxCustomGridTableViewData providing access to the records currently displayed within the view.  Each record in ViewData is an object of the TcxCustomGridRecord class.  This class is the base class not only for data rows (rows that display item values) but also for other rows that can be focused.  The following figure shows the record classes hierarchy:

•	a card (TcxGridCard) – represents a record in a card view.

•	a grid group row (TcxGridGroupRow) is a row displaying the value of an item (column) by which data is grouped plus group summaries, if any

•	a grid data row (TcxGridDataRow) displaying data

•	a grid master data row (TcxGridMasterDataRow) is a data (non-group) row in a master view

•	the "new item row" (TcxGridNewItemRow) represents the row for entering new data

The next image shows a grid table view with the record types marked.

Records are retrieved from a data controller in the order determined by the record index.  Record indexes are not changed as a result of sorting or grouping data.  They always refer to the same data.  Unlike the record index, index defines the visible position of a record and this does change after grouping, sorting and filtering etc.

Using members of the TcxCustomGridRecord class, you can read the values of record fields, determine the index, record index and level of the record, set focus to a record within a view, expand (only for master and group rows) and select the record.

Instances of the TcxCustomGridRecord class are also passed as parameters to style events.  For instance, the TcxCustomGridTableViewStyles.OnGetContentStyle event occurs when redrawing a record in a view addressed by a TcxCustomGridRecord object.  Depending on record information, you can use different styles to render this record.

The view’s OptionData property specifies different settings relating to record manipulation.  It controls whether records can be inserted, appended, edited and deleted.


Create and Delete Columns

See Also

This topic covers column creation and deletion within a grid view.  But the term "column" should be substituted by item, because the concept covers columns in a table view and rows in a card view.

Every view provides an Items property and this maintains a collection of items created within the view.  The Rows property in a card view and the Columns property in a (banded) table view implement the same functionality and they both refer to elements of the Items collection.  The difference between them is in the class of the object returned.  The Items property addresses objects of the TcxCustomGridTableItem class (the base class for all items), while the Columns and Rows properties refer to items of the specific classes (TcxGridColumn, TcxGridDBColumn, TcxGridBandedColumn and TcxGridDBBandedColumn, TcxGridCardViewRow and TcxGridDBCardViewRow).

You can refer to the Views and Items topics to learn more about view and item types.

In this topic, the StylesSimpleDemo program is used to illustrate column creation and deletion.  It displays data from the PERSONS table which contains information on the people in our video catalog.

There are two methods you can employ to add items within a view.

Adding Columns Manually

This first method is applicable to data-aware and non data-aware views.  The CreateItem (CreateColumn in a table view or CreateRow in a card view) method creates a new item (column or row) and adds it to the Items collection.  In a data-aware view, CreateItem does not bind the column to a specific datasource field.  You need to perform this manually by using the item’s DataBinding property.

The following code creates a column within a view and links it to the FIRSTNAME field from the PERSONS table (linked via the view’s DataController.DataSource property).

//Delphi

var

  ADBColumn: TcxGridDBColumn;

//...

  ADBColumn := tvPersons.CreateColumn;

  ADBColumn.DataBinding.FieldName := 'FIRSTNAME';

  ADBColumn.Name := 'tvPersonsFIRSTNAME';

//C++ Builder

  TcxGridDBColumn *ADBColumn;

  ADBColumn = tvPersons->CreateColumn();

  ADBColumn->DataBinding->FieldName = "FIRSTNAME";

  ADBColumn->Name = "tvPersonsFIRSTNAME";

Adding Columns Within Data-Aware Views

For data-aware views designed to work in bound mode, you can use the CreateAllItems method declared in the view’s DataController property.  This method creates items for all the fields in the data source and automatically links them to the corresponding fields via the DataBinding property.

At design time, you can create all items within a data-aware view via the Structure Navigator or Component Editor.  Please refer to the Component Editor topic to learn more about these facilities.

In the Structure Navigator, right-click the label of the data-aware view (already linked to an active dataset) and select the Create All Columns option:

or press the Retrieve Fields button in the Component Editor:

If there are existing columns, you will be prompted to save or remove them before creating the new ones.

As a result, columns will appear within the Component Editor and the view.  If a table contains any records, the view is also populated with data.

To add all columns via code, write the following:

//Delphi

  tvPersons.DataController.CreateAllItems;

//C++ Builder

  tvPersons->DataController->CreateAllItems();

Deleting Columns

To delete a column at runtime, you just need to invoke the column’s destructor.  The following code is used to dispose of the tvPersonsID column from the current demo program:

//Delphi

  tvPersonsID.Free;

//C++ Builder

  tvPersonsID->Free();

The view’s ClearItems method allows you to destroy all items within a view.

//Delphi

  tvPersons.ClearItems;

//C++ Builder

  tvPersons->ClearItems();

At design time, use the Structure Navigator or the Component Editor to delete columns.  To delete all columns within a view, select the Delete All Columns option from the view’s context menu in the Structure Navigator.

The Component Editor allows you to delete individual columns.  Switch to the Columns panel, select the columns to delete and press the Delete button.


Create and Delete Series

See Also

This topic covers series creation and deletion within a chart view.

Every chart view provides the Series properties and this maintains indexed collections of the data series created within the view.  The Series properties address the items of the TcxGridChartSeries and TcxGridDBChartSeries classes.

You can refer to the Views and Items in Chart Views topics to learn more about the chart view and its item types.

In this topic, we will use the CARS table that is shipped with the EQGrid demos and contains information on various cars.

There are two methods that you can employ to create data series within a chart view.

Creating Series At Runtime

This method is applicable to data-aware and non data-aware views.  The CreateSeries method creates a new data series and adds it to the Series collection.  In a data-aware view, CreateSeries does not bind the series to a specific field in the bound dataset.  You need to do this manually by using the DataBinding property of a series.

The following code creates a series within the data-aware chart view named chvDBCars and links it to the CYL field in the CARS table (linked via the view’s DataController.DataSource property).

//Delphi

var

  ADBSeries: TcxGridDBChartSeries;

//...

  ADBSeries := chvDBCars.CreateSeries;

  ADBSeries.DataBinding.FieldName := 'CYL';

//C++ Builder

  TcxGridDBChartSeries *ADBSeries;

  ADBSeries = chvDBCars->CreateSeries();

  ADBSeries->DataBinding->FieldName = "CYL";

Creating Series At Design Time

At design time, you can create series within a chart view via the Structure Navigator and Component Editor.  Please refer to the Component Editor topic to learn more about these facilities.

In the Structure Navigator, click the label of the chart view and activate the Component Editor by clicking on the Customize… button of the Structure Navigator.  The Component Editor has a Series tab on the right.  Clicking the Add… button in a non data-aware view simply adds a series.

Clicking the Add… button in a data-aware view which is already linked to an active dataset displays a dropdown menu that lists all the numeric fields in the bound data source.  You can specify the fields for which the series need to be created or create an unbound series by choosing the ‘Blank‘ menu item.

Note:	The fields for which the series have been created in the view are displayed as checked in the dropdown menu.  You can delete the series from the view by unchecking the corresponding field in the dropdown menu.  Use the Move Up and Move Down buttons to specify the order in which the series will be plotted in the view.  This modifies the index of the series within the view’s Series collection.

Deleting Series

To delete a series at runtime, you just need to invoke its destructor.  The following code is used to dispose of the chvDBCarsSeriesCyl series from the chart view:

//Delphi

  chvDBCarsSeriesCyl.Free;

//C++ Builder

  chvDBCarsSeriesCyl->Free();

The view’s ClearSeries method allows you to destroy all the created series within a chart view.

//Delphi

  chvDBCars.ClearSeries;

//C++ Builder

  chvDBCars->ClearSeries();

At design time, use the Component Editor to delete a series.  To delete a specific series, select it and then click the Delete button.

To delete all the series within a chart view, click the Select All button and then click the Delete button.


Card Category Row

The intended purpose of a category row is organizing rows into logical groups in a card.  With this capability, an end-user can easily delve into details or hide the unnecessary data by expanding or collapsing category rows.

Any regular row in a card can be used as a category row.  The only requirement is to set the row’s Kind property to rkCategory.  As a result all rows, which follow that row, become its children.

A hierarchy of the resulting category is shown in a card in a tree-like manner.  The expand button is drawn to the left of the category row caption, if the view’s OptionsCustomize.RowExpanding property is set to True, and the category row’s Options.Expanding property is also set to True.  Expanding and collapsing of a category row can also be performed programmatically using the row’s Expanded property.

When coding, you can have access to children through the category row’s CategoryItems property.  And any child of a category row provides access to its parent through its CategoryRow property.

The table below lists the main properties, which affect a category row and the related elements appearance:

Appearance	The view’s Styles.CategoryRow property – specifies styles for all category rows (and for their children indent) in a card.  The row’s Styles.CategoryRow – specifies styles for a particular row (and for its children indent).  Note: to make a style common to the entire row (to the caption and to the content parts), set the row’s Options.Editing property to False. The view’s OnGetCategoryRowStyle and row’s OnGetCategoryRowStyle events are handy, if you are going to dynamically apply styles to all category rows in a card or to a particular category row.  The view’s OptionsView.CategoryIndent property – specifies the size of the category row’s children indent. The view’s OptionsView.CategorySeparatorWidth property – specifies the width of the category row separator, which divides a category row and other rows. The view’s Styles.CategorySeparator – specifies styles for separators of all category rows in a card.


Card View

A Card View displays rows using a card display metaphor – each row is shown in a separate block within the View (a card).  When in its regular layout, a row within a card is drawn vertically, so more space is available for detail data.

The ultimate purpose of a Card View is to provide you with more display "real-estate" than is possible when using a table view or a banded table view.  The TcxGridCardView class implements logic for the Card View.

Similar to table and banded table views, a Card View offers different ways of data manipulation, such as data filtering or the logical grouping of rows.

For this view type, a row is represented by the TcxGridCardViewRow class.  It offers a rich set of properties, most of which are common to other QuantumGrid Views.  Card Views also provide additional properties such as row type specification, the row’s appearance, and its position in a card (see the row’s Kind, Styles and Position properties).

A collection of rows in a Card View is accessible through the view’s Rows property.

Laying out rows in a card

For extended card layout, ExpressQuantumGrid provides a layering mechanism.  Layering is a process of dividing a card into spaces – flat layers.  Each layer can contain a different set of rows.  Rows can be visually laid out in layers (both vertically or horizontally).  They flow from top to bottom, if a card is layered vertically (the view’s RowLayout property is set to rlVertical)…

…And are arranged from left to right if a card is layered horizontally (the view’s RowLayout property is set to rlHorizontal).

To break a card into layers, set the Position.BeginsLayer property of rows that will start a layer, to True.


Bands

See Also

The ExpressQuantumGrid provides three major view types – the Table View, Card View and, Chart View.  These Views implement the tabular, card and, chart (graphical) data representation formats, respectively.  The Table View has an enhanced version – Banded Table View.

The main feature of the Banded Table View is a band.  A band is a view element which combines several columns.  At runtime, bands are represented by headers displayed spanned over column headers.

At runtime, ExpressQuantumGrid bands can be moved and resized.  Bands can be moved within a View by clicking and dragging their headers.  Band moving and sizing is affected by the band’s or Banded Table View’s options (the Band.Options and BandedTableView.OptionsCustomize properties, correspondingly).  Bands can be hidden from Views at runtime.  Do this by clicking on band headers and then drag them to the Customization Form of a Banded Table View, thus removing the bands, and all the associated columns, from the View.  To make them visible again, drag the required band headers from the Customization Form back to the view.

You can also fix the required bands within a View so that band columns are not affected by horizontal scrolling of the View.  Fixed bands cannot be moved within a View, but they can still be hidden by dragging to the Customization Form.  Use the FixedKind property to specify the View’s side where a band is fixed.  See the ViewBandedFixed demo demonstrating this feature.

Columns can be arranged in any required order within a band.  This allows you to represent most complicated tables in the most appropriate manner.


Banded Table View

See Also

The ExpressQuantumGrid control supports several data representation Views: the Table View, Card View, Chart View and, the enhanced version of the Table View: the Banded Table View.  This topic explains how to set up a Banded Table View.

First, place a grid control onto your form.  Create a grid level.  Create a TcxGridDBBandedTableView instance for the level.  Connect the created Banded View to a dataset, for instance, the ITEMS table from the IssueListDB database.  Refer to the Working With Levels and Connecting To Data topics for detailed step-by-step instructions on how to begin using the ExpressQuantumGrid.

After a Banded View is created and connected to a dataset, activate the Component Editor.  Create the appropriate number of bands by clicking the Add button on the Bands tab of the Component Editor.  After that you can specify band settings via the Object Inspector.

or programmatically.

//Delphi

for I := 0 to 2 do

  btvItems.Bands.Add;

btvItems.Bands[0].Caption := 'Issue Info';

btvItems.Bands[1].Caption := 'Issue Status';

btvItems.Bands[2].Caption := 'OwnerInfo';

//...

//C++ Builder

for (int i = 0; i < 3; i++) {

  btvItems->Bands->Add;

}

btvItems->Bands[0]->Caption = "Issue Info";

btvItems->Bands[1]->Caption = "Issue Status";

btvItems->Bands[2]->Caption = "OwnerInfo";

//...

Then go to the Columns tab of the Component Editor and click the Retrieve Fields button.  This creates TcxGridDBBandedColumn objects corresponding to the dataset fields.  Once columns have been added to the View their names appear in the list located on the Columns page, along with the names and indexes of the bands assigned to these columns, which are called parent bands. By default, the parent band for retrieved fields is the first visible band in the View, the Issue Info band in this case.

//Delphi

for I := 0 to 2 do

  btvItems.Bands.Add;

btvItems.Bands[0].Caption := 'Issue Info';

btvItems.Bands[1].Caption := 'Issue Status';

btvItems.Bands[2].Caption := 'OwnerInfo';

btvItems.DataController.CreateAllItems;

//...

//C++ Builder

for (int i = 0; i < 3; i++) {

  btvItems->Bands->Add;

}

btvItems->Bands[0]->Caption = "Issue Info";

btvItems->Bands[1]->Caption = "Issue Status";

btvItems->Bands[2]->Caption = "OwnerInfo";

btvItems->DataController->CreateAllItems;

//...

After creating columns, you should arrange them in bands.  To do this, select a column in the Component Editor and expand the Position property list in the Object Inspector.  You can move a column to a band by assigning the band’s index to the Position.BandIndex property of the column.  You can use the Object Inspector to set a band’s index or select a band from the list of available view bands, at design time.  Note that the Position property controls not only the band to which a column is assigned, but also the column’s position within the band.

//Delphi

for I := 0 to 2 do

  btvItems.Bands.Add;

btvItems.Bands[0].Caption := 'Issue Info';

btvItems.Bands[1].Caption := 'Issue Status';

btvItems.Bands[2].Caption := 'OwnerInfo';

btvItems.DataController.CreateAllItems;

//...

btvItemsTYPE.Position.BandIndex := 1;

btvItemsPRIORITY.Position.BandIndex := 1;

btvItemsSTATUS.Position.BandIndex := 1;

btvItemsFIXEDDATE.Position.BandIndex := 1;

//...

//C++ Builder

for (int i = 0; i < 3; i++) {

  btvItems->Bands->Add;

}

btvItems->Bands[0]->Caption = "Issue Info";

btvItems->Bands[1]->Caption = "Issue Status";

btvItems->Bands[2]->Caption = "OwnerInfo";

btvItems->DataController->CreateAllItems;

//...

btvItemsTYPE->Position->BandIndex = 1;

btvItemsPRIORITY->Position->BandIndex = 1;

btvItemsSTATUS->Position->BandIndex = 1;

btvItemsFIXEDDATE->Position->BandIndex = 1;

//...

After a column is assigned to a specific band, it appears within a View.  Arrange all view columns as appropriately.  An example of a configured Banded View is demonstrated below:

We have performed the first steps to set up the Banded Table View.  Now we will enhance it in order to make it show the information in the columns in a more compact manner.

First, note that a user has to scroll a View at runtime to view all columns data.  In some cases this is not convenient (for instance, when columns containing the most important information should always stay on the screen).  Using the Band.FixedKind property can solve this problem.  Set this property to fkLeft for the Issue Info band and to fkRight - for the Owner Info band.

//Delphi

for I := 0 to 2 do

  btvItems.Bands.Add;

btvItems.Bands[0].Caption := 'Issue Info';

btvItems.Bands[1].Caption := 'Issue Status';

btvItems.Bands[2].Caption := 'OwnerInfo';

btvItems.DataController.CreateAllItems;

//...

btvItemsTYPE.Position.BandIndex := 1;

btvItemsPRIORITY.Position.BandIndex := 1;

btvItemsSTATUS.Position.BandIndex := 1;

btvItemsFIXEDDATE.Position.BandIndex := 1;

//...

btvItems.Bands[0].FixedKind := fkLeft;

btvItems.Bands[2].FixedKind := fkRight;

//...

//C++ Builder

for (int i = 0; i < 3; i++) {

  btvItems->Bands->Add;

}

btvItems->Bands[0]->Caption = "Issue Info";

btvItems->Bands[1]->Caption = "Issue Status";

btvItems->Bands[2]->Caption = "OwnerInfo";

btvItems->DataController->CreateAllItems;

//...

btvItemsTYPE->Position->BandIndex = 1;

btvItemsPRIORITY->Position->BandIndex = 1;

btvItemsSTATUS->Position->BandIndex = 1;

btvItemsFIXEDDATE->Position->BandIndex = 1;

//...

btvItems->Bands[0]->FixedKind = fkLeft;

btvItems->Bands[2]->FixedKind = fkRight;

//...

Now these bands are fixed to the specified sides of a View.  Try to scroll the View horizontally and you will notice that only the columns belonging to the Issue Status band (which is not fixed) are scrolled.  Let us place the Created Date and Owner Phone columns into the second row of their bands.  The Position property is again how we set the position of a column within a band.

//Delphi

for I := 0 to 2 do

  btvItems.Bands.Add;

btvItems.Bands[0].Caption := 'Issue Info';

btvItems.Bands[1].Caption := 'Issue Status';

btvItems.Bands[2].Caption := 'OwnerInfo';

btvItems.DataController.CreateAllItems;

//...

btvItemsTYPE.Position.BandIndex := 1;

btvItemsPRIORITY.Position.BandIndex := 1;

btvItemsSTATUS.Position.BandIndex := 1;

btvItemsFIXEDDATE.Position.BandIndex := 1;

//...

btvItems.Bands[0].FixedKind := fkLeft;

btvItems.Bands[2].FixedKind := fkRight;

btvItemsCREATEDDATE.Position.RowIndex := 1;

btvItemsOwnerPhone.Position.RowIndex := 1;

//...

//C++ Builder

for (int i = 0; i < 3; i++) {

  btvItems->Bands->Add;

}

btvItems->Bands[0]->Caption = "Issue Info";

btvItems->Bands[1]->Caption = "Issue Status";

btvItems->Bands[2]->Caption = "OwnerInfo";

btvItems->DataController->CreateAllItems;

//...

btvItemsTYPE->Position->BandIndex = 1;

btvItemsPRIORITY->Position->BandIndex = 1;

btvItemsSTATUS->Position->BandIndex = 1;

btvItemsFIXEDDATE->Position->BandIndex = 1;

//...

btvItems->Bands[0]->FixedKind = fkLeft;

btvItems->Bands[2]->FixedKind = fkRight;

btvItemsCREATEDDATE->Position->RowIndex := 1;

btvItemsOwnerPhone->Position->RowIndex := 1;

//...

The following image shows the result of all the actions described above:

The bands can be arranged as nested bands.  Finally, the creator information and owner information can be combined to provide additional information on an issue.  For this purpose create a new band and name it as "Additional Info" as shown in the following image.

Now let us assign the Creator Info and Owner Info bands to the newly created band.  In the same way as with columns, these bands can be selected in the Component Editor and the Additional Info band can then be assigned as their parent band by setting its index to the BandPosition.BandIndex or selecting this band from the dropdown list of available bands.

The Bands list now displays ParentBand information for the Creator Info and Owner Info bands.

The following image shows the finished grid.


Look and Feel

ExpressQuantumGrid, as for other recent Developer Express VCL products, provides the ability of changing the control’s look & feel on the fly.  Painting of grid elements is implemented in appropriate painter classes derived from TcxCustomLookAndFeelPainter.  The control itself does not refer to these descendant painter classes, only the TcxCustomLookAndFeelPainter interface provided by the base class.  This provides great flexibility when changing between different look & feels.

The grid’s LookAndFeel attribute of class TcxLookAndFeel provides access to look & feel properties.  It allows you to choose one of the predefined styles: Standard, Flat, UltraFlat, and Office11.  The latter gives the grid's appearance an Office 2003 style.  In addition to these, ExpressQuantumGrid supports Windows® XP themes.  The LookAndFeel.NativeStyle property enables you to use the current Windows® XP theme to render grid control elements.

The painting of grid elements in a particular style is performed by a specific painter class, for instance TcxWinXPLookAndFeelPainter for the Windows® XP theme, which redefines the drawing functions for this purpose.


Styles

See Also

ExpressQuantumGrid is a very powerful and flexible data-aware control.  One of the major features contributing to this flexibility is styles.  Styles allow you to customize the appearance of grid elements such as views, items (columns or card view rows), bands and levels.  Each customizable element has a Styles property and this provides access to its style collection.  For instance, a table view declares properties defining styles for the following items:

•	View background;

•	Cells;

•	Filter box;

•	Footer;

•	Groups;

•	Group summary;

•	Group-by box;

•	Column headers;

•	Active selection;

•	Inactive selection;

•	Incremental search selection;

•	Indicator;

•	Row preview;

•	Category row;

•	Filter row;

•	New Item Row;

•	Layer’s separator;

•	Separators of a category, filter and new item rows.

 A style consists of the Background color, Text Color and Font attributes.  The TcxStyle.Color, TcxStyle.TextColor and TcxStyle.Font properties represent these settings respectively.

For instance, if you assign a style to the view’s Styles.Content property, the font and background of all view columns will be determined by this style.  However, you can override the appearance of an individual column by setting its Styles.Content property.  The following image shows a grid control with the style redefined for the second column:

At design time, styles are set up via a style repository of class TcxStyleRepository.  You can add, edit and delete styles via the style repository editor.

A style repository gives you the ability to arrange styles in a style sheet.  A style sheet is an effective way to set up a collection of styles for a grid view  For instance, the TcxGridCardViewStyleSheet provides styles specific to a card view (TcxGridCardView and TcxGridDBCardView).

To apply a StyleSheet’s styles to a view, use the Styles.StyleSheet property.

The following image shows the StyleSheet Editor activated via the style repository component dialog.

You should not write event handlers when using styles. This contrasts with the custom draw feature.  Styles are easier to use, but they are not as flexible.  For example, you cannot use gradient fill or bitmap graphics using styles.  Custom draw is more complex, but provides you with much greater opportunities for customization of the grid’s display.


Style Repository

See Also

The ExpressQuantumGrid library provides a TcxStyleRepository component to help in designing styles.  This component contains an embedded styles editor and this allows you to add, edit and delete styles within the repository.

To activate the style repository editor, double-click the component icon or select the Edit option from the component’s popup menu.  The Styles panel of the editor manages the collection of styles contained within the style repository:

To customize a style within the editor, highlight it and use the Object Inspector.  A style specifies the Background color, Text Color and Font of the applied object.  The TcxStyle.Color, TcxStyle.TextColor and TcxStyle.Font properties represent these settings correspondingly.

Once a style is set up as required, you can apply it to a specific grid element.  For instance, you can apply a style to a table view column via the TcxCustomGridTableItemStyles.Content property.

The Style Sheets tab of the editor allows you to organize styles in a more convenient manner.  A style sheet contains style attributes specific to a grid view.  ExpressQuantumGrid provides three style sheet classes: TcxGridTableViewStyleSheet, TcxGridBandedTableViewStyleSheet and TcxGridCardViewStyleSheet for the table view, banded table view and card view respectively.

Instead of creating separate styles for every view element, you can create a style sheet containing all styles supported by the required grid view and then assign the style sheet to the view’s Styles.StyleSheet property.

The style repository editor allows you to add/delete specific style sheets, customize their styles, store/restore style sheets to INI files and load predefined style sheets:

Buttons:

•	[Add] – Adds a new style sheet to the repository.  Clicking the button opens the popup menu and this allows you to select the class of the style sheet to add.

•	[Delete] – Deletes all selected style sheets.

•	[Edit…] – Invokes the StyleSheet Editor.  You can use the editor to specify and redefine individual sheet styles.  The style sheet editor will be discussed later.

•	[Save to ini…] – Invokes the Save As dialog that allows saving all selected style sheets to an INI file.

•	[Load from ini…] – Invokes the Open dialog that allows loading style sheets from an INI file.

•	[Predefined…] – Invokes the Predefined StyleSheets dialog which gives you the ability to create a specific style sheet based on one of the predefined color schemes.

The Style Sheet Class combo-box allows you to select the type of the style sheet you want to create.  When you select any item within the left pane, a sample grid in the preview section is automatically repainted to reflect the new color scheme.

For instance, a banded grid view with the applied DevExpress style will look as follows:

The [Load] button creates a style sheet based on the color scheme selected, initializes its styles and closes the editor window.

The [Close] button only closes the editor window without creating a style sheet.

Note that when you create a style sheet, all its styles are added to the TcxStyleRepository.Items collection.  But when you delete a style sheet, the corresponding styles are NOT deleted automatically.  If necessary, you can delete them manually.

The StyleSheet Editor

Like the Predefined StyleSheets dialog, the StyleSheet Editor allows WYSIWYG style sheet creation.  Select the desired style sheet from the list and click the [Edit…] button to activate the editor.

The styles listbox displays the list of styles available for the current grid view.  Each style corresponds to a grid view element.  The following buttons allow you to change the style settings:

[Color…] – This button enables you to change the background color of the selected style via a standard color dialog.

[Font…] – This button allows you to change the font settings for the selected style via a standard font dialog.

The preview section immediately reflects any changes after the Color and Font dialogs are closed.  The following image shows a grid control with a changed style for the Content element.  The background and text colors are blue and white respectively.

The [OK] button applies all changes, creates styles within a style sheet if necessary and closes the StyleSheet Editor.  Styles are created only if the default settings have been changed.

The [Cancel] button just closes the StyleSheet Editor discarding all changes.


Custom Draw

See Also

The Custom Draw feature provides unlimited customization facilities for the grid control’s look and feel.  As this feature is event-based, you have to handle events and implement some code.  You may use Styles instead for simplicity and to avoid coding, but this obviously reduces flexibility.

How a Custom Draw Event Works

Each custom draw event provides a set of parameters which supply the information needed for drawing each type of grid element.

The Sender parameter specifies the grid element to be repainted. Usually it is the grid element that owns this event. The following table lists all available custom draw events and their owners:

Event	Description
OnCustomDrawBandHeader	Allows a band header of the banded table view to be custom drawn. Applies to: • TcxGridBandedTableView and TcxGridDBBandedTableView.
OnCustomDrawFooterCell	Allows a footer cell of the table view to be custom drawn. Applies to: • TcxGridColumn, TcxGridBandedColumn, and TcxGridDBBandedColumn; • TcxGridTableView, TcxGridDBTableView, TcxGridBandedTableView, and TcxGridDBBandedTableView.
OnCustomDrawHeader	Allows a column header of the table view to be custom drawn. Applies to: • TcxGridColumn, TcxGridBandedColumn, and TcxGridDBBandedColumn.
OnCustomDrawColumnHeader	Allows a column header of the table view to be custom drawn. Applies to: • TcxGridTableView, TcxGridDBTableView, TcxGridBandedTableView, and TcxGridDBBandedTableView.
OnCustomDrawPartBackground	Allows view elements such as footers, group footers, filter panels and the group by box to be custom drawn. Applies to: • TcxGridTableView, TcxGridDBTableView, TcxGridBandedTableView, and TcxGridDBBandedTableView.
OnCustomDrawCell	Allows a grid view cell to be custom drawn. Applies to: • TcxCustomGridTableItem, TcxGridColumn, TcxGridBandedColumn, TcxGridDBBandedColumn, TcxGridCardViewRow, and TcxGridDBCardViewRow; • TcxCustomGridTableView, TcxGridTableView, TcxGridDBTableView, TcxGridBandedTableView, TcxGridDBBandedTableView, TcxGridCardView, and TcxGridDBCardView.
OnCustomDrawGroupCell	Allows a group row to be custom drawn. Applies to: • TcxGridTableView, TcxGridDBTableView, TcxGridBandedTableView, and TcxGridDBBandedTableView.
OnCustomDrawGroupSummaryCell	Allows a group summary to be custom drawn. Applies to: • TcxGridColumn, TcxGridBandedColumn, and TcxGridDBBandedColumn; • TcxGridTableView, TcxGridDBTableView, TcxGridBandedTableView, and TcxGridDBBandedTableView.
OnCustomDrawIndicatorCell	Allows a row indicator to be custom drawn. Applies to: • TcxGridTableView, TcxGridDBTableView, TcxGridBandedTableView, and TcxGridDBBandedTableView.
OnCustomDrawLegend	Allows a chart legend to be custom drawn. Applies to: • TcxGridChartView and TcxGridDBChartView; • TcxGridChartDiagram, TcxGridChartHistogram, TcxGridChartColumnDiagram, TcxGridChartBarDiagram, TcxGridChartLineDiagram, TcxGridChartAreaDiagram, and TcxGridChartPieDiagram.
OnCustomDrawLegendItem	Allows a legend item to be custom drawn. Applies to: • TcxGridChartView and TcxGridDBChartView; • TcxGridChartDiagram, TcxGridChartHistogram, TcxGridChartColumnDiagram, TcxGridChartBarDiagram, TcxGridChartLineDiagram, TcxGridChartAreaDiagram, and TcxGridChartPieDiagram.
OnCustomDrawPlot	Allows a chart’s plot area to be custom drawn. Applies to: • TcxGridChartHistogram, TcxGridChartColumnDiagram, TcxGridChartBarDiagram, TcxGridChartLineDiagram, TcxGridChartAreaDiagram, and TcxGridChartPieDiagram.
OnCustomDrawValue	Allows a chart value (also called a data marker) to be custom drawn. Applies to: • TcxGridChartHistogram, TcxGridChartColumnDiagram, TcxGridChartBarDiagram, TcxGridChartLineDiagram, TcxGridChartAreaDiagram, and TcxGridChartPieDiagram; • TcxGridChartSeries and TcxGridDBChartSeries.
OnCustomDrawValueArea	Allows a chart’s value area (a constituent part of the data markers in area diagrams) to be custom drawn. Applies to: • TcxGridChartAreaDiagram.
OnCustomDrawSeriesSite	Allows a series site’s area to be custom drawn. Applies to: • TcxGridChartPieDiagram.
OnCustomDrawSeriesSiteCaption	Allows a series site’s caption area to be custom drawn. Applies to: • TcxGridChartPieDiagram.

Information necessary for painting each element passed via the ViewInfo parameter.

Note: many ViewInfo properties are only needed by the grid’s internal structure, so you can ignore them.

The most useful ViewInfo properties are:

•	Bounds property.  Determines the bounding rectangle of the repainted grid element.  Each custom draw event provides a grid control canvas represented by the ACanvas parameter.  As the ACanvas parameter refers to the whole grid control canvas, you should use the AViewInfo.Bounds property to determine the position and size of the current grid element.  The rectangle contained within this property determines the top-left and bottom-right corners of the element within the grid control via the Bounds.Top, Bounds.Left, Bounds.Bottom and Bounds.Right fields correspondingly.

•	Params property. Contains a set of fields that determine the painted element style. They are:

•	Color – specifies the element background.

•	TextColor – specifies the element text color (if it contains any).

•	Font – specifies the element font (the TFont class instance).

•	DisplayValue property (ReadOnly) – Specifies the value that is displayed by the element.

•	The ACanvas parameter provides the canvas where the element is painted.  Remember that the ACanvas property provides the whole canvas of the grid control. So you should use the AViewInfo.Bounds property to determine the bounding rectangle for the repainted element.  Although ACanvas is of the TcxCanvas type, it publishes all the most useful canvas methods.  If you want to access the standard VCL canvas, you should use the ACanvas.Canvas property.

•	The ADone parameter determines whether an event handler completely draws an appropriate element.  If ADone is True, the default draw procedure is not called.


Setting the Grid's Appearance

See Also

The TcxGrid control provides several ways to modify its appearance.

Look And Feel

Changes the look & feel of the entire grid control.

Styles

Affects the appearance of the grid control elements which support the Styles technology.

Custom Draw

Changes the appearance of grid control elements for which Custom Draw events are written.

Let’s explore each option in detail.

Look And Feel

The ExpressQuantumGrid has a LookAndFeel property which provides 4 options:

1.	Standard

2.	Flat

3.	UltraFlat

4.	Office11

You can switch between them via the TcxLookAndFeel.Kind property.

Implement the following code to apply the Flat appearance to your grid control:

//Delphi

cxGrid1.LookAndFeel.Kind := lfFlat;

//C++ Builder

cxGrid1->LookAndFeel->Kind = lfFlat;

If you are using the Windows XP operating system, you can make your grid look like a Windows XP native control. Just set the TcxLookAndFeel.NativeStyle property to True.

Implement the following code to make the grid control look like a Windows XP native control:

  cxGrid1.LookAndFeel.NativeStyle := True;

Note: The NativeStyle property has higher priority than the Kind property.  Thus, if the NativeStyle property is set, the Kind property has no effect.

Styles

Styles allow you to customize the appearance of specific grid elements such as views, bands, columns, etc.  A style affects an element’s background, font and text color.

The Styles document provides general information on the styles introduced by EQGrid.

To specify the style for a specific grid element, you need to create a style object (TcxStyle) first.  A Style Repository component provides a convenient way to create and manipulate styles at design time.  If you apply styles at runtime, you can create them via code in the form’s constructor or by handling the form’s OnCreate event, for instance.

After a style is created, you can assign it to a specific style property to identify the look & feel of the corresponding grid element.

The following code creates a style (blue text and aqua background) in the form’s OnCreate handler and assigns it to the first column of the tvItems grid view:

//Delphi

  AFirstColumnStyle: TcxStyle;

//...

procedure TForm1.FormCreate(Sender: TObject);

begin

  AFirstColumnStyle := TcxStyle.Create(Self);

  AFirstColumnStyle.Color := clAqua;

  AFirstColumnStyle.TextColor := clBlue;

  tvItems.Columns[0].Styles.Content := AFirstColumnStyle;

end;

//C++ Builder

TcxStyle * AFirstColumnStyle;

//...

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  AFirstColumnStyle = new TcxStyle(this);

  AFirstColumnStyle->Color = clAqua;

  AFirstColumnStyle->TextColor = clBlue;

  tvItems->Columns[0]->Styles->Content = AFirstColumnStyle;

}

The following image shows the result of applying this style to the first column.  Note that other columns and other view elements are not assigned styles and they are painted by default.

A style repository component enables you to create and load predefined style sheets.  A style sheet represents a set of styles suitable for a particular grid view type (table, banded table or card view).  Instead of creating separate styles for every view element, you can create a style sheet containing all styles supported by the required grid view and then assign the style sheet to the view’s Styles.StyleSheet property.  To create style sheets at design time, you must use a style repository.  Refer to the Style Repository section for more information.

The following code assigns a style sheet (GridTableViewStyleSheetDevExpress) to the tvCustomers view, using a style repository component based on the DevExpress color scheme:

//Delphi

tvCustomers.Styles.StyleSheet := GridTableViewStyleSheetDevExpress;

//C++ Builder

tvCustomers->Styles->StyleSheet = GridTableViewStyleSheetDevExpress;

This specifies the look&feel of all view elements at once.  Now the tvCustomers view is displayed as follows:

If you need to create predefined style sheets via code, see the following example.  Predefined style sheets are declared in the cxGridPredefinedStyles unit.  In order to create predefined style sheets at runtime, you need to include this unit in the Uses section of your form.

First, create an instance of the TcxdmGridPredefinedStyles class.  Then use its members to access a style sheet of the required type (for table, banded table or card view) and of the required color scheme.  The following code shows how to access a predefined style sheet of the DevExpress color scheme and apply it to the tvCustomers view:

//Delphi

tvCustomers.Styles.StyleSheet := TcxdmGridPredefinedStyles.Create(Self).GridTableViewStyleSheetDevExpress;

//C++ Builder

tvCustomers->Styles->StyleSheet = (new TcxdmGridPredefinedStyles(this))->    GridTableViewStyleSheetDevExpress;

The result of this code is the same as in the previous example.

In addition to static styles (styles common to all items or records), the EQGrid control allows you to override the appearance of particular cells, records, grouping rows, items, footer panels, etc.  These styles are dynamic as they can be implemented only via code using style events.  To access the style events, see the view’s and/or item’s Styles property.

For instance, the view’s Styles.OnGetContentStyle event enables you to provide different styles for individual cells addressed by a record and item.  This event is fired in turn for each cell within a grid view.  If you assign a style to the event’s AStyle parameter, the grid view will use this style to draw the current cell.  Otherwise, the cell will be painted by default.

The item’s Styles.OnGetContentStyle event is similar to the view’s OnGetContentStyle event.  However, it occurs only for the cells of the current item.

The following code shows how you can handle the view’s OnGetContentStyle event to color grid records based on the value of the Population column.  The table view (tvCountries) in this example displays records from the Country table.  Countries with population greater than 10,000,000 are displayed with the AYellowStyle style (red text color and yellow background) and this style is created in the form’s OnCreate event as follows:

//Delphi

AYellowStyle: TcxStyle;

//...

procedure TForm1.FormCreate(Sender: TObject);

begin

  AYellowStyle := TcxStyle.Create(Self);

  AYellowStyle.Color := $0080FFFF;

  AYellowStyle.TextColor := clMaroon;

end;

procedure TForm1.tvCountriesStylesGetContentStyle(

  Sender: TcxCustomGridTableView; ARecord: TcxCustomGridRecord;

  AItem: TcxCustomGridTableItem; out AStyle: TcxStyle);

begin

  if ARecord.Values[tvCountriesPopulation.Index] > 10000000 then

    AStyle := AYellowStyle;

end;

//C++ Builder

  TcxStyle * AYellowStyle;

//...

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  AYellowStyle = new TcxStyle(this);

  AYellowStyle->Color = 0x0080FFFF;

  AYellowStyle->TextColor = clMaroon;

}

//---------------------------------------------------------------------------

void __fastcall TForm1::tvCountriesStylesGetContentStyle(

      TcxCustomGridTableView *Sender, TcxCustomGridRecord *ARecord,

      TcxCustomGridTableItem *AItem, TcxStyle *&AStyle)

{

  if (ARecord->Values[tvCountriesPopulation->Index] > 10000000)

    AStyle = AYellowStyle;

}

After you run the application, the grid control will look like:

Consider an example of specifying different styles for group rows at different nesting levels.  For this purpose, the view’s OnGetGroupStyle event is handled.  The ALevel parameter of the event identifies the nesting level of the grouping row for which the event is generated:

//Delphi

var

  cxMyStyle1, cxMyStyle2: TcxStyle;

  //...

  //Put the following code into form constructor

  cxMyStyle1 := TcxStyle.Create(Self);

  cxMyStyle1.Color := $0042D7FF;

  cxMyStyle2 := TcxStyle.Create(Self);

  cxMyStyle2.Color := $0073E1CC;

procedure TForm1.tvCustomersStylesGetGroupStyle(

  Sender: TcxGridTableView; ARecord: TcxCustomGridRecord; ALevel: Integer;

  out AStyle: TcxStyle);

begin

  if ALevel = 0 then

    AStyle := cxMyStyle1

  else

    AStyle := cxMyStyle2;

end;

//C++ Builder

  TcxStyle *cxMyStyle1, *cxMyStyle2;

  //...

  //Put the following code into form constructor

  cxMyStyle1 = new TcxStyle(this);

  cxMyStyle1->Color = 0x0042D7FF;

  cxMyStyle2 = new TcxStyle(this);

  cxMyStyle2->Color = 0x0073E1CC;

void __fastcall TStylesSimpleDemoMainForm::tvPersonsStylesGetGroupStyle(

      TcxGridTableView *Sender, TcxCustomGridRecord *ARecord, int ALevel,

      TcxStyle *AStyle) {

  switch(ALevel) {

  case 0:

    AStyle = cxMyStyle1;

    break;

  case 1:

    AStyle = cxMyStyle2;

    break;

  }

}

The result of the above code is shown in the image below:

Custom Draw

The CustomDraw feature provides the most powerful method of customizing the grid’s appearance. This is an event-based technology. Every customizable grid element provides a set of custom draw events. (See the Custom Draw custom document for more information). Each event provides several arguments necessary for grid element painting. These parameters include:

Sender – the standard parameter passed to all event handlers;

AViewInfo – an element’s view info;

ACanvas – the grid control’s canvas.

All these parameters are discussed in detail in the Custom Draw base concepts. The ACanvas parameter needs additional explanation though. Generally, the TcxCanvas class (passed by the ACanvas parameter) is a wrapper around the standard VCL canvas (TCanvas) and the latter is available via ACanvas.Canvas.

Note:  The ACanvas parameter contains the canvas of the whole grid control and you have to calculate the current element’s bounding rectangle manually. The AViewInfo parameter contains the Bounds property representing the current element’s bounding rectangle.

Implement the code below to draw an image as a card background.

//Delphi

procedure TForm1.cxGridDBCardView1CustomDrawCell(

  Sender: TcxCustomGridTableView; ACanvas: TcxCanvas;

  AViewInfo: TcxGridTableDataCellViewInfo; var ADone: Boolean);

var

  ARec: TRect;

  ABitmap: TBitmap;

  ATextToDraw: string;

begin

  if (AViewInfo is TcxGridCardRowDataViewInfo) then

    ATextToDraw := AViewInfo.GridRecord.DisplayTexts[AViewInfo.Item.Index]

  else

    ATextToDraw := VarAsType(AViewInfo.Item.Caption, varString);

  ARec := AViewInfo.Bounds;

  ABitmap := TBitmap.Create;

  ABitmap.LoadFromFile('sky.bmp');

  ACanvas.Canvas.Brush.Bitmap := ABitmap;

  ACanvas.Canvas.FillRect(ARec);

  ABitmap.Free;

  SetBkMode(ACanvas.Canvas.Handle, TRANSPARENT);

  ACanvas.DrawText(ATextToDraw, AViewInfo.Bounds, 0);

  ADone := True;

end;

//C++ Builder

void __fastcall TForm1::tvCarsCustomDrawCell(

      TcxCustomGridTableView *Sender, TcxCanvas *ACanvas,

      TcxGridTableDataCellViewInfo *AViewInfo, bool &ADone)

{

  AnsiString ATextToDraw;

  if (dynamic_cast<TcxGridTableDataCellViewInfo *>(AViewInfo) != NULL) {

    ATextToDraw = AViewInfo->GridRecord->DisplayTexts[AViewInfo->Item->Index];

  } else {

    ATextToDraw = VarAsType(AViewInfo->Item->Caption, varString);

  }

  TRect ARec = AViewInfo->Bounds;

  Graphics::TBitmap *ABitmap = new Graphics::TBitmap();

  ABitmap->LoadFromFile("sky.bmp");

  ACanvas->Canvas->Brush->Bitmap = ABitmap;

  ACanvas->Canvas->FillRect(ARec);

  ABitmap->Free();

  SetBkMode(ACanvas->Canvas->Handle, TRANSPARENT);

  ACanvas->DrawText(ATextToDraw, AViewInfo->Bounds, 0);

  ADone = true;

}

The result of the above code is shown on the image below:


Data Editing Using Inplace Editors

See Also

The ExpressQuantumGrid gives you the ability to use different editors to edit the values of grid items.  There are many ExpressEditors and these enable you to edit text, date/time values, graphical fields, etc.

An item linked to a dataset field in a DB view is automatically assigned a default editor according to the field type.  For instance, if an item is linked to a Boolean field, a check box (TcxCheckBox) is used to edit the column's values.  The correspondence of field types to default editors is presented in the cxEditDBRegisteredRepositoryItems unit.  You can change the default editors assigned via the DBRepositoryItemClasses array.

If a default editor does not suit your needs, you can assign an appropriate editor explicitly.  Assigning a specific editor to an item can be done in one of two ways: via the repository mechanism or by using the editor properties class.

Repository

A repository (TcxEditRepository) represents a storage of repository items each of which defines properties that are specific to a corresponding editor.  There is a repository item for every editor in the ExpressEditors Library.

After you have added a repository item, you can adjust its properties in the Object Inspector.

To assign an editor to an item (column), you have to set the item’s RepositoryItem property.

The point of using repository items is that you can assign the same one to several columns, thus specifying the same behavior.

Editor Properties Class

Every item (column) has the PropertiesClass field and this can be used to assign a particular editor to a column.  After setting the PropertiesClass you can access and adjust the editor’s properties via the column’s Properties field.

The following code shows how to specify the BLOB editor to edit the cxGrid1DBTableView1Graph1 item data.  Its type is set to bekPict to enable displaying graphics via the editor.

//Delphi

  cxGrid1DBTableView1Graph1.PropertiesClass := TcxBLOBEditProperties;

  TcxBLOBEditProperties(cxGrid1DBTableView1Graph1.Properties).BlobEditKind := bekPict;

At design time, you can use the Object Inspector to assign editor properties.  The column’s Properties field provides a drop-down list containing all the available editors.

Selecting the item from this list initializes the PropertiesClass field with the corresponding editor’s properties class. These classes handle the requirements of different data types. For instance, the TcxMaskEditProperties class holds the properties required for mask edit fields.

To customize the properties of an assigned editor, expand the Properties entry in the Object Inspector:

When both the PropertiesClass and RepositoryItem are assigned, the editor for a column is determined by the RepositoryItem object.  You can obtain the reference to the edit properties by calling the GetProperties method.

ExpressQuantumGrid gives you the ability to specify different editors for individual item cells.  You can handle the OnGetProperties event and specify an editor depending on a record's position or the data associated with it.


New Item Row

See Also

A new item row is labeled with the ‘Click here to add a new row’ description for the visual cue of detecting its location.  To provide it with another descriptive name, use the new item row’s InfoText property. To apply a different style, use the view’s Styles.NewItemRowInfoText property.

This row is visually delimited in a view from other regular rows by a horizontal bar – the new item row’s separator.  The ExpressQuantumGrid offers two options that allow this separator to fit your needs.  To specify its dimension, use the new item row’s SeparatorWidth property.  To change the separator’s appearance, use the new item row’s SeparatorColor property.

As a regular data row, a new item row activates an in-place editor in the space selected by an end-user.  When the row loses focus, the entered data is sent to the underlying dataset.  After the view is updated with the posted data, the new item row becomes blank (to be more precise, shows its descriptive name) prompting an end-user for new inputs.


Lookup Column

See Also

The ExpressQuantumGrid allows you to display data in different formats and to edit the data using an appropriate in-place editor.  The type of editor is chosen according to the type of data displayed within a column.  For more information on assigning in-place editors, see the Data Editing Using Inplace Editors topic.

One of the most advanced column editors is used for a lookup column.  It is capable of displaying data from another dataset (whose key values match those of a field within the view’s dataset).

The editor type corresponding to the lookup column is the LookupComboBox editor.  This editor displays lookup values within the edit region and within its dropdown window, activated by the button located at the right side of the editor.  The LookupComboBox dropdown window can contain several columns displaying different field values from the lookup dataset.  A user can change the width of each column, assign an editor to a column’s contents, enable sorting, etc.

The LookupComboBox editor implements an incremental search feature.  The search can be performed when inputting text either in the edit region or within the editor dropdown.  If incremental filtering is also activated, the dropdown list is filtered based on the typed characters:

For more information on how to create and use lookup columns, see the Using Lookup Columns topic.


Using Lookup Columns

See Also

The lookup column allows records to be displayed and edited from a lookup dataset.  This column type is represented by the LookupComboBox editor.

There are 2 ways to set up a lookup column.

The first method is to connect your DBColumn to a lookup field that was created in Delphi’s persistent field editor specifically for this purpose.  For more information on how to create a persistent Lookup field see the Defining a lookup field topic in the Delphi documentation or the Using Lookup Editors topic in this help system.  If a dataset contains a lookup field (which is properly set up) a user just has to assign the lookup field's name to the DBColumn.DataBinding.FieldName property.

Another way of setting up a lookup column is to use the Properties or RepositoryItem properties of a column.

The PropertiesClass property allows you to choose a specific editor class for the column.

The RepositoryItem property allows you to choose from one you have previously prepared.

After assigning the required value to either of these properties, the Properties property will contain an object for configuring that kind of editor:

//Delphi

  tvFilmsPersonsStaffPERSONID.PropertiesClass := TcxLookupComboBoxProperties;

//C++ Builder

  tvFilmsPersonsStaffPERSONID->PropertiesClass = __classid(TcxLookupComboBoxProperties);

If you choose the editor class LookupCombo you will get an editor class that will include properties for configuring a ListSource, ListColumns and KeyFieldNames and DataBinding.FieldName which replaces the LookupComboBox.DataBinding property (see section two in the topic Using Lookup Editors) and is used to match the value of the lookup dataset field (KeyFieldNames ).

Let us examine how lookup columns are configured in the MasterDetailTableDemo.

This demo introduces two grid controls which display data from a master and detail table (Grid and GridDetail, respectively).  The GridDetail control shows data from the tblFilmsPersonsStaff table, which contains information about people involved in film production.  There are two fields in this table: PERSONLINEID and PERSONID, which refer to key field values from other tables (tblPersonsLine and tblPersons, respectively).  The Person column in the tvFilmsPersonsStaff view is set up to demonstrate the name of the person whose ID field in the tblPersons table matches the PERSONID field value in tblFimsPersonsStaff.  The following image shows the design time settings applied to the editor of the Person lookup column:

//Delphi

  tvFilmsPersonsStaffPERSONID.PropertiesClass := TcxLookupComboBoxProperties;

  with TcxLookupComboBoxProperties(tvFilmsPersonsStaffPERSONID.Properties) do

  begin

    ListSource := MasterDetailTableDemoMainDM.dsPersons;

    ListFieldNames := 'NAME';

    KeyFieldNames := 'ID';

  end;

  tvFilmsPersonsStaffPERSONID.DataBinding.FieldName := 'PERSONID';

//...

//C++ Builder

  tvFilmsPersonsStaffPERSONID->PropertiesClass = __classid(TcxLookupComboBoxProperties);

  TcxLookupComboBoxProperties *properties = (TcxLookupComboBoxProperties *)tvFilmsPersonsStaffPERSONID->Properties;

  properties->ListSource = MasterDetailTableDemoMainDM.dsPersons;

  properties->ListFieldNames = "NAME";

  properties->KeyFieldNames = "ID";

  tvFilmsPersonsStaffPERSONID->DataBinding->FieldName = "PERSONID";

//...

The following image shows the Person column at runtime:


Obtain and Set Cell Values

See Also

This topic describes how you can get and set the values of particular cells in a (banded) table view or card view.  For information on getting and setting the values in a chart view please refer to the Obtain and Set Values in Chart Views topic.

Every cell in a grid view is identified by its record and item.  Items refer to the fields in a record.  In a (banded) table view, items stand for the grid columns.  In a card view, items are card rows.  Please refer to the Items section for more detailed information.

At runtime, a user can easily navigate records and edit cell values.  When moving from one record to another, any data changed is posted to a database.  You can prevent a user from editing cells in a number of ways:

•	the item’s Options.Editing property controls whether a user can edit its cells (provided that any cell can be edited, see OptionsData.Editing)

•	the item’s Options.Focusing enables/disables the ability to focus its cells

•	the view’s OptionsData.Editing enables/disables the editing of all items within this view

•	the view’s OptionsSelection.CellSelect determines whether individual items can be selected within a record

To get/set an item's value in the focused record, you can use the item’s EditValue property (a variant).  You can access EditValue regardless of the data loading mode used.  The following code shows how to post changes to the current item using the data provided by a TEdit control.

//Delphi

  try

    with tvCustomers do

    if Assigned(Controller.EditingItem) then

    begin

      Controller.EditingItem.EditValue := Edit1.Text;

      //post data

      DataController.Post;

    end;

  except

    on E: Exception do

      ShowMessage('Cannot set a value due to the exception: ' + E.Message);

  end;

//C++ Builder

  try {

    if (tvCustomers->Controller->EditingItem != NULL) {

      tvCustomers->Controller->EditingItem->EditValue = Edit1->Text;

      //post data

      tvCustomers->DataController->Post();

    }

  } catch(Exception &e) {

    ShowMessage("Cannot set a value due to the exception: " + e.Message);

  }

Here, tvCustomers specifies a table view of the TcxGridTableView class.  If an error occurs, the exception's description is displayed within the message box.

Other methods to get/set cell values programmatically differ according to the grid view’s mode.

Get/set values in bound mode

For data-aware views, you are also able to access record values using TDataSet and TField members.  The following code inserts a new record and sets the values for the two fields displayed in the tvFilmsCaption and tvFilmsYEAR columns.

//Delphi

var

  AFieldFilmCaption, AFieldFilmYear: TField;

  AFilmDataSet: TDataSet;

//...

  //get TField objects for corresponding columns

  AFieldFilmCaption := tvFilmsCaption.DataBinding.Field;

  AFieldFilmYear := tvFilmsYEAR.DataBinding.Field;

  //get TDataSet owning fields

  AFilmDataSet := AFieldFilmCaption.DataSet;

  //insert new record

  AFilmDataSet.Insert;

  //set values for the Caption and Year fields

  AFieldFilmCaption.AsString := ‘Harry Potter and the Sorcerer''s Stone';

  AFieldFilmYear.AsInteger := 2001;

  //post data

  AFilmDataSet.Post;

//C++ Builder

  //get TField objects for corresponding columns

  TField *AFieldFilmCaption = tvFilmsCaption->DataBinding->Field;

  TField *AFieldFilmYear = tvFilmsYEAR->DataBinding->Field;

  //get TDataSet owning fields

  TDataSet *AFilmDataSet = AFieldFilmCaption->DataSet;

  //insert new record

  AFilmDataSet->Insert();

  //set values for the Caption and Year fields

  AFieldFilmCaption->AsString = "Harry Potter and the Sorcerer's Stone";

  AFieldFilmYear->AsInteger = 2001;

  //post data

  AFilmDataSet->Post();

To access values, you can use the Values property of the view’s DataController as you would normally do in unbound or provide mode (see the section below for details).

Get/set values in unbound mode

In unbound and provider modes, you can use the Values property of the view’s DataController.  This returns a two-dimensional array containing the values stored in records and their items.  To get the text equivalents of these variant values, use DisplayTexts instead.  You need to supply a record index and an item index to address a particular value within either array.  An item index provides the item’s displayed position and is determined by the TcxCustomGridTableItem.Index property's value.

The following code sets the values of the first column (ItemIndex = 0) to the corresponding record indexes:

//Delphi

var

  ARecordIndex, AItemIndex: Integer;

//...

  try

    AItemIndex := 0;

    for ARecordIndex := 0 to tvCustomers.DataController.RecordCount - 1 do

      tvCustomers.DataController.Values[ARecordIndex, AItemIndex] := ARecordIndex;

  except

    on E: Exception do

      ShowMessage('Cannot set a value due to the exception: ' + E.Message);

  end;

//C++ Builder

  try {

    int AItemIndex = 0;

    for (int ARecordIndex = 0; ARecordIndex < tvCustomers->DataController->RecordCount; ARecordIndex++) {

      tvCustomers->DataController->Values[ARecordIndex][AItemIndex] = ARecordIndex;

    }

  } catch(Exception &e) {

    ShowMessage("Cannot set a value due to the exception: " + e.Message);

  }


Obtain and Set Values in Chart Views

See Also

This topic describes how you can get and set category values and series values in a chart view.  For information on getting and setting cell values in a (banded) table view or a card view please refer to the Obtain and Set Cell Values topic.

Items in a chart view are represented by categories and data series.  In a data-aware view items refer to the fields in the data source.  Since a chart view simply displays the data in the form of graphical shapes (for instance, bars or columns) it doesn’t provide facilities for an end-user to supply additional values or edit the values of the items used to render the chart view.  That is the values should be provided and edited in code.  The methods used to get and set the category values and series values are described below and can be used for both data-aware and non data-aware chart views.

Every chart view has Categories and Series properties which provide access to the categories and data series created within the view.  The Categories properties refer to the items of the TcxGridChartCategories and TcxGridDBChartCategories classes.  The Series properties represent an indexed collections of the series and address the items of the TcxGridChartSeries and TcxGridDBChartSeries classes.  A specific series in the Series collections can be addressed by its index (position) within the collection.

Please refer to the Create and Delete Series topic for details on managing the series within the chart view.

The category values can be accessed via the Categories.Values property which represents an indexed collection.  Similarly, the Values indexed collection contains the series values of a specific series.  Note that the view’s ViewData.Categories and ViewData.Values properties provide access to the same collections of category values and series values.  The ViewData.Values property provides the series values for all the series.  To address the value of a specific series, you need to pass the index of the series as the first parameter.

Since each series provides a series value for each category the total number of series values within each series is equal to the total number of category values and can be determined via the view’s ViewData.CategoryCount property (or either via the ValueCount property of a series or the view’s Categories.ValueCount property which provides the same resulting value).  In other words, adding a new category automatically assumes specifying series values for this category and vice versa.  These properties are not read-only and this allows you to modify the number of series and category values used to render the chart view.

Adding new category values and series values by increasing one of the abovementioned properties and subsequently initializing the corresponding entries in the Categories.Values and the Values collections of series with new values is one of the possible ways to insert series data into the chart view.  The other possible and straightforward method is to call the AddValue function of a series which adds a new series value and returns its index (position) within the Values collection of this series.  The index can then be used to specify the category value and series values of the other series within the category for example.

Get/set values in unbound mode

Consider the example shown in the Chart View Tutorial topic.  Use the suggestions in the Chart View Tutorial. Step 1: View Creation topic as general instructions for creating a non data-aware chart view.  Sequentially select the grid control, the created view and the existing level to use the Object Inspector to set their Name properties to Grid, chvCars and lvCars, respectively.  Here’s the look of the form so far:

The following code creates two series in the chvCars view, adds a category by adding a new series value and specifies a category value and a series values for the second series in the created category.

//Delphi

var

  ASeries: TcxGridChartSeries;

  ACategoryIndex: Integer;

begin

  chvCars.ClearSeries;

  ASeries := chvCars.CreateSeries;

  ASeries.DisplayText := 'Cyl';

  ASeries.DataBinding.ValueType := 'Smallint';

  ACategoryIndex := ASeries.AddValue(6);

  ASeries := chvCars.CreateSeries;

  chvCars.ViewData.Values[ASeries.Index, ACategoryIndex] := 3;

  ASeries.DisplayText := 'Liter';

  chvCars.Categories.Values[ACategoryIndex] := 'BMW 530i';

end;

//C++ Builder

  TcxGridChartSeries *ASeries;

  Integer ACategoryIndex;

  chvCars->ClearSeries();

  ASeries = chvCars->CreateSeries();

  ASeries->DisplayText = "Cyl";

  ASeries->DataBinding->ValueType = "Smallint";

  ACategoryIndex = ASeries->AddValue(6);

  ASeries = chvCars->CreateSeries();

  chvCars->ViewData->Values[ASeries->Index][ACategoryIndex] = 3;

  ASeries->DisplayText = "Liter";

  chvCars->Categories->Values[ACategoryIndex] = "BMW 530i";

Note that the series value of the second series is addressed via the ViewData.Values property which uses the index of the second series to specify the series for which the value is being set.  Here we need to specify the values of the DisplayText properties for the series.  As for a data-aware series, the descriptive text for the series is by default determined from the bound field’s display name.

The resulting view is shown in the screenshot below:

Get/set values in bound mode

The principles of getting and setting values in bound mode are the same as the technique described above for unbound mode.  For data-aware views, you are also able to access the values of the records which correspond to categories and series using the TDataSet and TField members.  Below, how to connect the data-aware chart view to a dataset and use the DataBinding objects to access to the data in the underlying database is explained.

For demonstration purposes, a data-aware chart view needs to be created.  Use the suggestions in the Chart View Tutorial. Step 1: View Creation topic as general instructions for creating a data-aware chart view.  Instead of using a TQuery to access the CARS table that is shipped with the EQGrid demos we will use a TTable.  Activate the BDE tab of the component palette, place a TTable component [image] on the form and set its properties as follows:

•	DatabaseName to DemosDB

•	Name to tableCars

•	TableName to Cars.DB

•	Active to True.  Note that the Active property must be set after all the other properties have been set.

Then switch to the Data Access tab of the component palette and place a TDataSource component [image] on the form.  Rename the component to dsCars.  Do not connect it to tableCars as this will be done in code.  Sequentially select the grid control, the created view and the existing level to use the Object Inspector and set their Name properties to Grid, chvDBCars and lvCars respectively.  Here’s the look of the form so far:

The following code connects the view to the CARS table, filters the data in the table by a car category (so as to display saloon cars only), creates two series and binds a category and the created series to the fields of the CARS table.  This connects the view to the data so it can be properly displayed within chart diagrams.  After that the code inserts the data for a new category by inserting a new record into the table and initializing the record according to the category value and series values.

//Delphi

var

  ASeriesCyl: TcxGridDBChartSeries;

  ASeriesLiter: TcxGridDBChartSeries;

begin

  tableCars.Filter := 'Category = ''SALOON''';

  tableCars.Filtered := True;

  dsCars.DataSet := tableCars;

  chvDBCars.DataController.DataSource := dsCars;

  chvDBCars.ClearSeries;

  ASeriesCyl := chvDBCars.CreateSeries;

  ASeriesCyl.DataBinding.FieldName := 'CYL';

  ASeriesLiter := chvDBCars.CreateSeries;

  ASeriesLiter.DataBinding.FieldName := 'LITER';

  chvDBCars.Categories.DataBinding.FieldName := 'Model';

  chvDBCars.DataController.Append;

  tableCars.FindField('Category').AsString := 'SALOON';

  ASeriesCyl.DataBinding.Field.AsInteger := 6;

  ASeriesLiter.DataBinding.Field.AsFloat := 3.0;

  chvDBCars.Categories.DataBinding.Field.AsString := '530i';

  chvDBCars.DataController.Post;

end;

//C++ Builder

  TcxGridDBChartSeries *ASeriesCyl;

  TcxGridDBChartSeries *ASeriesLiter;

  tableCars->Filter = "Category = 'SALOON'";

  tableCars->Filtered = True;

  dsCars->DataSet = tableCars;

  chvDBCars->DataController->DataSource = dsCars;

  chvDBCars->ClearSeries();

  ASeriesCyl = chvDBCars->CreateSeries();

  ASeriesCyl->DataBinding->FieldName = "CYL";

  ASeriesLiter = chvDBCars->CreateSeries();

  ASeriesLiter->DataBinding->FieldName = "LITER";

  chvDBCars->Categories->DataBinding->FieldName = "Model";

  chvDBCars->DataController->Append();

  tableCars->FindField("Category")->AsString = "SALOON";

  ASeriesCyl->DataBinding->Field->AsInteger = 6;

  ASeriesLiter->DataBinding->Field->AsFloat = 3.0;

  chvDBCars->Categories->DataBinding->Field->AsString = "530i";

  chvDBCars->DataController->Post();

Note that the Category field in the inserted record is initialized with the ‘SALOON’ string so that the data can be displayed within the column diagram of the view.

The resulting view is shown in the screenshot below:


Deleting Records

See Also

For you to be able to delete records at runtime, the view’s OptionsData.Deleting property must be set to True and then pressing the Del or Ctrl+Del keys will delete the selected records.

If the OptionsSelection.MultiSelect property is set to True, several records can be selected simultaneously.  Otherwise, only one record can be selected at a time.  Refer to the Selecting Records section for details.

By activating the OptionsData.DeletingConfirmation attribute, it is possible to display a confirmation dialog box before records are deleted.

To delete records programmatically, use the methods provided by a data controller:  TcxCustomDataController.DeleteSelection and TcxCustomDataController.DeleteFocused.  These methods delete the selected and focused records and do not require any parameters.  The following code invokes the DeleteSelection method to delete the selected records from the tvCustomers view:

//Delphi

  try

    tvCustomers.DataController.DeleteSelection;

  except

    on E: Exception do

      ShowMessage('Cannot delete selected records due to the exception: ' + E.Message);

  end;

//C++ Builder

  try {

    tvCustomers->DataController->DeleteSelection();

  } catch(Exception &e) {

    ShowMessage("Cannot delete selected records due to the exception: " + e.Message);

  }

An exception may occur if records cannot be deleted.  This can for instance, be caused by the deletion violating the integrity rules.


Data Editing

ExpressQuantumGrid gives you the ability to customize the view's layout and enter data (for unbound (banded) table and card views only) at design time.  For more information about the customizing the view's layout at design time, see the View Layout topic.  In this section we will consider the entry of data.

In order to enter data the "Layout and Data Editor" dialog is used.  Click the "Edit Layout and Data…" item of the view’s context menu to invoke this dialog.  Note that for chart views this dialog only lets you preview their appearance in a form.  That is the following information relates to (banded) table and card views only.

Also you can select a specific view from the Views panel in the Component Editor and click the "Edit View Layout and Data…" button to invoke the corresponding dialog.

Obviously, you can enter data for existing columns but in order to do this, at least one column should exist at the moment the Layout and Data Editor is opened.

For non data-aware views the Layout and Data Editor dialog contains three buttons:

•	The Columns Customization button (Customization of rows for card views)

Activates the Customization Form which lets you temporarily hide specific items/bands and then restore them back to a view.

•	The Ok button

Applies any changes made to the layout of a grid view on the form and passes the data entered in the editor to the view only when the corresponding checkbox is checked and then closes the dialog.

•	The Cancel button

Discards any changes made to the layout and the data entered into the editor and closes the dialog.

and two checkboxes:

•	The ‘Save layout’ checkbox

Specifies that layout changes should be saved and applied to a grid view on the form when the Ok button is clicked.  See the View Layout topic for more information about customizing the layout of views.

•	The ‘Save data’ checkbox

Specifies that data entered in the Layout and Data Editor should be saved and passed to a grid view on the form when the Ok button is clicked.

For data-aware views the ‘Save data’ checkbox is not displayed as the data for these views will be acquired from the bound data sources.

When a clone of the grid view on the form is displayed in the Layout and Data Editor you can insert and delete records by pressing the INS and DEL keys respectively, and modify cell values by selecting a specific cell and typing appropriate information into it.

Note: the item’s DataBinding.ValueType property specifies the data type and the type of the default editor used to edit the contents of the cell.

When you have finished entering data into the Layout and Data Editor dialog and are ready to save it make sure the ‘Save data’ checkbox is checked and then click the Ok button.  The data from the clone view will be passed to the grid view on the form which the dialog was called for.


Filtering

See Also

Filtering allows you to display a subset of records from a data source.  Our grid control allows you to construct complex filter criteria by combining simple filter conditions with logical operators for individual items (columns in grid views and rows in card views).

Data filtering in a grid view is implemented by the data controller.  The view’s DataController.Filter property of the TcxFilterCriteria class gives you the ability to set filter conditions and control the filtering.  TcxFilterCriteria is the base class for the TcxDataFilterCriteria and TcxDBDataFilterCriteria classes for working in unbound and bound modes, respectively.

When setting filter conditions via the DataController.Filter object, you should also set the TcxDataFilterCriteria.Active property to True to activate filtering.  The filter panel at the bottom of a view displays the text representation of the applied filter criteria.

By default, a user can filter data at runtime in a grid table view.  The Runtime Filtering topic provides more details.

As mentioned above, filter criteria consist of simple filter conditions combined with logical operators.  A simple filter condition specifies the item for which the condition is applied, the comparison operator and the value with which to compare it.

Assume we have a table providing information on companies.  The table contains the Company and City fields.  The following simple filter condition, if applied, selects the companies located in Madrid:

City = ‘Madrid’

Suppose, you need to select the companies starting with A and located in Madrid or Caracas:

(City = ‘Madrid’ OR City = ‘Caracas’) AND (Company LIKE ‘A%’)

This filter consists of three simple conditions.  A simple condition consists of a TcxFilterCriteriaItem object and this specifies the item (column) for which the filter is applied, the operator and the value with which to compare it.  Simple conditions are combined by a logical operator and stored in lists of the TcxFilterCriteriaItemList class.  In addition, these lists can be combined by an operator with other lists and simple conditions.

For the filter criteria shown above, two lists are used.  The first list stores simple conditions (City = ‘Madrid’) and (City = ‘Caracas’).  These conditions are combined by the OR operator.  The second list points to a simple condition (Company LIKE ‘A%’) defined by the first list.  Conditions in the second list are combined by the AND operator.


Runtime Filtering

See Also

This topic describes how to filter data at runtime.  See the Filtering Data section for writing code to implement filtering.

1. Filter Dropdown List

2. Custom Filter Dialog

3. Filter Builder Dialog

1. Filter Dropdown List

With filter dropdowns, you can filter records in tabular and Card Views by the values of grid items (column or card rows).  To invoke a filter dropdown for a grid item, click its filter dropdown button.  When a grid item is used to create a filter, its filter dropdown button is displayed in blue.

A filter dropdown is populated with various filter conditions which are determined by the grid item’s unique values.  In large datasets, this operation may consume a lot of time since all records are accessed.  In this case, it is better to limit the length of the list by setting the MaxValueListCount property.

The (All) and (Custom…) items are always added to the list.  Selecting the (All) item removes all the filter conditions set for the current column.  The (Custom…) item invokes the Custom Filter or Filter Builder dialog which allow you to visually construct the filter criteria for the given column or current view, respectively.

(Blanks) and (NonBlanks) elements are added automatically if your column contains NULL and non-NULL values, respectively.  You can customize this list before displaying it by using the column’s OnGetFilterValues event.  You can remove elements from the list, add your own elements (enabling custom actions when they are selected) and customize the displayed list of values.  For more information refer to the TcxFilterValueList class topic.

Note:	For grid items, which display date/time values, filter dropdowns are populated with the predefined filter items according to the filter options accessible via a View’s DateTimeHandling.Filters property.

When a user selects a value from the list (any item other than All, Custom, Blanks or NonBlanks), a new filter condition is created and applied to the data in the current view.  This new condition is of the type:

<Column> = <Value>,

where <Column> stands for the current column for which the filter list was activated and <Value> defines the selected value.  For instance, when selecting the ‘Mercedes-Benz’ item, the "Trademark = Mercedes-Benz" filter condition is created and applied:

When filtering is applied, the filter panel appears with a description of the filter criteria.  The view’s FilterBox.Visible property affects the manner in which this panel is displayed within it.  You can temporarily deactivate and then activate filtering by clicking the checkbox on this panel.  The ‘x’ button clears all the filter criteria applied.

2. Custom Filter Dialog

Selecting the (Custom) item from the filter dropdown list activates the Custom Filter dialog.

This dialog allows you to specify the filter criteria for a single column consisting of one or two filter conditions.  You can also specify the operator for these conditions.

The following image shows all the possible operators:

Operator	Text representation
=	equals
<>	does not equal
<	is less than
<=	is less than or equal to
>	is greater than
>=	is greater than or equal to
LIKE	like
NOT LIKE	not like
= NULL	is blank
<> NULL	is not blank

In addition to the operator, values must be specified via the value box.  This uses the same editor type as the column (stand-alone and in-place use the same editor classes).

When using the LIKE or NOT LIKE operator, you can use the ‘underscore’(_) and ‘percent’ (%) characters to substitute one or several symbols in a string value respectively.  These characters are identified by the view’s DataController.Filter.UnderscoreWildcard and PercentWildCard properties.

The second filter condition is specified in the same manner.  To combine two conditions, use the AND/OR check box.

3. Filter Builder Dialog

In some cases, however, filter conditions cannot be displayed with the help of the Custom Filter dialog.  For instance, the Custom Filter dialog supports only one or two filter conditions for a single column.  The dialog also does not support some filter operators (BETWEEN, membership test operator and date/time related operators).  So if the filter criteria contains more than two conditions bound to a single column or if non-supportable operators are used, the Filter Builder dialog is activated instead when selecting the (Custom) option from the filter dropdown list.

The filter criteria specified by this dialog is interpreted as:

(ID=1 OR ID=4 OR ID=7) AND (CustomerID>=1 AND CustomerID<=100)

The Filter Builder dialog extends the functionality of the Custom Filter dialog.  Unlike the Custom Filter, the Filter Builder dialog allows you to specify the filter criteria for any column in the view.  An end-user can also invoke the dialog by clicking the Customize button in the filter panel.  Set the view’s FilterBox.CustomizeDialog property to True to make the button visible.

The Filter Builder dialog supports all possible operators.  In addition to those described in the above table, you can create filter conditions using the BETWEEN, membership test operators and date/time related operators:

Operator	Description
BETWEEN	The operator allows you to select records whose column values are included between two operands.  To specify the range, use the editors which appear when clicking the operand boxes. The operator displayed in the picture above is equivalent to the following statement: ID>=1 AND ID<=100
NOT BETWEEN	The NOT BETWEEN operator selects records whose column values are not included in the required range.  Operands are specified in the same manner as for the BETWEEN operator. The equivalent of the operator displayed in the image is: ID<1 AND ID>100
IN	Implements a membership test operator. The IN operator selects records with column values equal to operands from the specified set.  To add an operand to the set, click the ‘+’ button. The equivalent to the IN operator shown in the image above is: ID=1 OR ID=4 OR ID=7
NOT IN	The negation of the IN operator.  It selects a record if its column value is not a member of a specified set. The equivalent to the IN operator shown in the image above is: ID<>1 AND ID<>4 AND ID<>7
Date/time operators: is yesterday is today is tomorrow is last 7 days is last week is last 14 days is last two weeks is last 30 days is last month is last year is past is this week is this month is this year is next 7 days is next week is next 14 days is next two weeks is next 30 days is next month is next year is future	This group of operators is available only for date/time fields.  They do not require any operands. For instance, the is today operator selects records with column values equal to the current day.  The is this year operator selects records equal to the current year, etc. String representations of these operators are determined by the filter options accessible via a View’s DateTimeHandling.Filters property.

The Filter Builder dialog also supports two more Boolean operators to combine conditions in the list: NOT AND and NOT OR.

NOT AND combines conditions by the AND operator and then negates the result:

These criteria select all records except those with the Car column value set to ‘BMW 530i’ and PaymentType set to Cash.  The equivalent text representation is:

NOT (Car=‘BMW 530i’ AND PaymentType=Cash)

NOT OR combines conditions by the OR operator and then negates the result:

The criteria selects records which don't have their PaymentType set to Master or Visa.  The text representation is:

NOT (PaymentType=Master OR PaymentType=Visa)

To invoke the Custom Filter or Filter Builder dialog programmatically, see the view’s Filtering.RunCustomizeDialog method.  You can invoke your own custom filter building dialog by handling the OnFilterDialogShow or OnFilterCustomization events.

Set the item’s Options.Filtering property or the view’s OptionsCustomize.ColumnFiltering property to False to deactivate runtime filtering.


Filtering Data

See Also

This topic covers filtering the data displayed in a grid view (using the data controller's functionality).  Important note: please do not confuse our filtering with the standard dataset functionality provided by the TDataSet.Filter property.  To learn more about this type of filtering, refer to the corresponding Delphi help section.

An end-user has access to quick and simple filtering at runtime and this is discussed in the Runtime Filtering topic.  This includes a reference to the Custom Filter dialog and Filter Builder dialog which show how to combine at most two simple filter conditions.  To construct more complex filter criteria, it needs to be done in code and that is what will be covered here.

Data filtering functionality is provided by the TcxFilterCriteria class.  You will use its descendants such as TcxDataFilterCriteria and TcxDBDataFilterCriteria. These extend the base class's functionality for unbound and bound modes, respectively.  TcxFilterCriteria and its descendants, provide filter conditions which relate to all the columns in a view.

Let us consider the FilterByCodeDemo which shows you how to implement data filtering by code.  This demo displays data from the Customers table of the CustomersDB database.

Each record in the Customers table stores information on a customer and the product they have purchased.  This product is specified by the PRODUCTID field, which represents the numeric product identifier.

Suppose we want to know the customers who only bought grid components.  In this case, you have to filter data by the Product column bound to the PRODUCTID field.  The filter criteria can be constructed as follows:

(Product = ExpressQuantumGridProductID) OR
(Product = XpressQuantumGridProductID) OR
(Product = XtraGridProductID) OR
(Product = ASPXGridProductID)

This filter cannot be set by end-users via the Custom Filter dialog because it consists of four simple filter conditions for a single column, which exceeds the limit of two conditions.

So, applying such filter criteria can be performed via the Filter Builder dialog and via code. Consider how this can be done via code.  The view’s DataController.Filter.Root property manages all the filter conditions applied to the current view.  It allows you to construct complex nested filter criteria by combining filter conditions with logical operators (AND, OR).  The Root property represents a list (TcxFilterCriteriaItemList) of filter conditions (simple and/or aggregate).

A simple filter condition (TcxFilterCriteriaItem) addresses:

•	the column for which the condition is applied;

•	the comparison operator represented by the TcxFilterOperatorKind enumerator;

•	the comparison value;

•	the display value.

An aggregate filter condition is a list (similar to Root) of simple and/or aggregate conditions combined by a Boolean operator.  It represents an instance of the TcxFilterCriteriaItemList class.

For the filter criteria listed above, only simple filter conditions are used.  They are combined by the OR operator and added to the Root list.

//Delphi

const

  cExpressQuantumGridID = 3; //ProductID of ExpressQuantumGrid

  cXtraGridID = 7;           //ProductID of XtraGrid

  cASPXGridID = 9;           //ProductID of ASPXGrid

  cXpressQuantumGridID = 14; //ProductID of XpressQuantumGrid

procedure TFilterByCodeMainForm.SetOnlyGridsFilter;

begin

  with tvCustomers.DataController.Filter.Root do

  begin

    //clear all existing filter conditions

    Clear;

    //set the logical operator

    //by which new conditions are combined

    BoolOperatorKind := fboOr;

    //add new filter conditions

    AddItem(tvCustomersPRODUCTID, foEqual, cExpressQuantumGridID, 'ExpressQuantumGrid');

    AddItem(tvCustomersPRODUCTID, foEqual, cXpressQuantumGridID,  'XpressQuantumGrid');

    AddItem(tvCustomersPRODUCTID, foEqual, cXtraGridID, 'XtraGrid');

    AddItem(tvCustomersPRODUCTID, foEqual, cASPXGridID, 'ASPX Grid');

  end;

end;

//C++ Builder

const

  cExpressQuantumGridID = 3, //ProductID of ExpressQuantumGrid

  cXtraGridID = 7,           //ProductID of XtraGrid

  cASPXGridID = 9,           //ProductID of ASPXGrid

  cXpressQuantumGridID = 14; //ProductID of XpressQuantumGrid

procedure TfilterByCodeMainForm::SetOnlyGridsFilter() {

  TcxFilterCriteriaItemList *root = tvCustomers->DataController->Filter->Root;

  //clear all existing filter conditions

  root->Clear();

  //set the logical operator

  //by which new conditions are combined

  root->BoolOperatorKind = fboOr;

  //add new filter conditions

  root->AddItem(tvCustomersPRODUCTID, foEqual, cExpressQuantumGridID, "ExpressQuantumGrid");

  root->AddItem(tvCustomersPRODUCTID, foEqual, cXpressQuantumGridID,  "XpressQuantumGrid");

  root->AddItem(tvCustomersPRODUCTID, foEqual, cXtraGridID, "XtraGrid");

  root->AddItem(tvCustomersPRODUCTID, foEqual, cASPXGridID, "ASPX Grid");

}

On executing this code, a grid control will display data that meets the filter criteria set.

You can enable an end-user to run this code, for instance, by adding a button onto a form and handling its OnClick event in which you call the SetOnlyGridsFilter procedure.

ExpressQuantumGrid provides another way of applying such predefined filters.  It allows you to customize the filter dropdown list activated when a user clicks the filter arrow in a column header.  You can customize this list by deleting individual elements and/or by adding new ones.  Suppose we want to add an ‘ONLY GRIDS’ item to this list.  Selecting this item will call the SetOnlyGridsFilter procedure thus displaying customers who bought only grid components.

To do this, you have to handle two column events:

•	the OnGetFilterValues event which allows you to add the new item

•	the OnUserFiltering event which handles the selection of the item

The following code shows an OnGetFilterValues event handler in which the ‘ONLY GRIDS’ item is added to the filter list.  The filter list is provided by the AValueList parameter.  To add a new list item, call the AValueList.Add method.  The first parameter set to fviUser indicates that this item will generate the OnUserFiltering event when selected.

The second parameter specifies the value associated with the new item.  If you add several elements of the fviUser kind, you will need to know which item has been selected when implementing the OnUserFiltering event.  Use the value associated with an item for this purpose (see code below).

The third parameter represents a string displayed in the filter list.  The last parameter affects the position within the filter list in which the new item is inserted.  See the Add method description for details.

//Delphi

const

 cOnlyGrids = 100;

procedure TFilterByCodeMainForm.tvCustomersPRODUCTIDGetFilterValues(

  Sender: TcxCustomGridTableItem; AValueList: TcxDataFilterValueList);

begin

  AValueList.Add(fviUser, cOnlyGrids, 'ONLY GRIDS', True);

end;

//C++ Builder

const cOnlyGrids = 100;

void __fastcall TfilterByCodeMainForm::tvCustomersPRODUCTIDGetFilterValues( TcxCustomGridTableItem *Sender, TcxDataFilterValueList *AValueList) {

  AValueList->Add(fviUser, cOnlyGrids, "ONLY GRIDS", true);

}

The implementation of the OnUserFiltering event is quite simple.  To ascertain that the ‘ONLY GRIDS’ item was selected, the AValue parameter is compared to the cOnlyGrids constant.  If True, the SetOnlyGridsFilter procedure is called which applies the filter criteria discussed.

//Delphi

procedure TFilterByCodeMainForm.tvCustomersPRODUCTIDUserFiltering(

  Sender: TcxGridColumn; const AValue: Variant;

  const ADisplayText: String);

begin

  if AValue = cOnlyGrids then

    SetOnlyGridsFilter;

end;

//C++ Builder

void __fastcall TfilterByCodeMainForm::tvCustomersPRODUCTIDUserFiltering(

  TcxGridColumn *Sender, const Variant &AValue, const AnsiString ADisplayText) {

  if (AValue == cOnlyGrids) {

    SetOnlyGridsFilter();

  }

}


Using Filter Builder Dialog

See Also

ExpressQuantumGrid enables you to filter the data displayed by views.  This functionality is implemented by a view’s DataController property.

Also, the Filter property of the data controller allows you to provide filter conditions for the data displayed by the current view, i.e. reduce the data available as opposed to temporarily suppressing some of it.  Refer to the Filtering Data topic for more information.

EQGrid provides a Filter Builder dialog to facilitate creating and applying filter criteria at runtime.  The Filter Builder dialog supports all the filter operators available via the Filter property programmatically.  In addition, it allows you to save filter criteria to an external file for future use.  You can invoke your custom filter building dialog by handling the OnFilterDialogShow and OnFilterCustomization events.

The Runtime Filtering topic provides general information on the Filter Builder dialog.  This section relates to how you can use the dialog to construct custom filter criteria.

1. Building filter criteria

2. Saving to/loading from an external file

1. Building Filter Criteria

Let’s examine the Orders table from the CarsDB database shipped with the EQGrid demos.  Each record in the table describes a single order made.  It refers to a customer, the product bought, purchase date, payment amount and type, etc.

To invoke the Filter Builder dialog, click the Customize button on the Filter panel.  The Customize button is visible if the view’s FilterBox.CustomizeDialog property is set to True.  The visibility of the Filter panel is determined by the FilterBox.Visible property.

The following image displays an empty Filter Builder dialog:

Suppose we need to select the orders made between the 11.15.02 and 12.15.02.  These criteria are applied to the PurchaseDate column.

Click the ‘press button to add new condition’ box.  This will add a new condition to the criteria.  Alternatively, you can left-click on the Filter box and select the Add Condition option from the dropdown menu:

As we need to apply the filter criteria to the PurchaseDate column, left-click the column box (next to the ellipsis button) to open the dropdown list displaying the available column names.  Then select the PurchaseDate item:

In the operator box, select the BETWEEN item.  This will add two empty value boxes to specify the inclusive range for the BETWEEN condition:

Next, you need to specify the range for the BETWEEN operator.  You can do this either manually by typing a date using the keyboard or via the date editor that is activated when you click the value box and open the dropdown.  The editor used in value boxes is determined by the editor type assigned to the corresponding column:

Now you can apply this filter condition to the view by clicking the Apply button.

In a similar manner, we will add another filter condition to show only the orders with their PaymentType set to AmericanExpress.

Click the ‘press button to add new condition’ box.  This adds a new filter condition at the same level as the condition for the PurchaseDate column.  In the column box, select the PaymentType item.  Then move to the value box and select the Am. Express item using the image combo box editor.

To select orders made by particular customers, we need to add a new filter condition.  Suppose that we want to select orders made by three customers.

Customer = ‘Sam Hill’ OR Customer = ‘Karen Holmes’ OR Customer = ‘Bobbie Valentine’

This is a complex filter condition combining three simple conditions with the OR operator.  So we cannot just add them at the same root level as for the existing conditions which are combined by an AND operator.  Instead, we need to add a group of conditions.

Left-click the ellipsis button for the PaymentType condition and select the Add Group menu item:

Our new complex criteria must combine conditions using the OR operator.  To do this, left-click the operator box (by default, it specifies the AND operator) and select the OR item from the dropdown:

The group already contains one condition.  You have to add two more conditions at the same level and specify the required customers using value boxes.  After doing this, the Filter Builder dialog will look like:

Finally, click the OK button to apply the filter criteria and close the dialog.  The grid view now displays only the records matching the set criteria.

2. Saving to/Loading from an External File

The Filter Builder dialog allows you to save filter criteria to and load them from an external file.  Clicking the Save As… or Open… buttons activates one of these dialogs.

Filter settings are stored in a file with a flt extension.  Starting from version 6 of the ExpressQuatnumGrid, a column in the file is referenced by its name (not by its position in a View).  This means that filter settings are correctly restored if columns were deleted from the View after saving the filter to a file.  Note that filter criteria saved in the old format will be restored using column positions as references to columns.


Filter Row

See Also

A filter row is a simpler alternative to filter dropdowns.  In a table view (or in a banded table view), it appears directly under column headers (if the FilterRow.Visible property is set to True).  When initially drawn (or not focused and no filtering is applied), it displays a text describing its functionality:

If needed, you can change the description by using the FilterRow.InfoText property and apply a different style (see the view’s Styles.FilterRowInfoText property).

A filter row is separated from other rows by a horizontal bar – the filter row’s separator.  You can specify its width and color through the filter row’s FilterRow.SeparatorWidth and FilterRow.SeparatorColor properties.

An end-user can filter results by any field, which is currently allocated in the view (see also the Customization Form).

A filter row provides two ways of filtering:

•	If the FilterRow.ApplyChanges property is set to fracOnCellExit, then the filter row’s in-place editors add an auto-complete feature.  When you start typing characters, an in-place editor automatically completes with the field value containing similar starting characters. Pressing the Enter key updates the view with the filtered data.

•	If the FilterRow.ApplyChanges property is set to fracImmediately, then the view is dynamically updated with the filtered data every time an end-user continues typing in the in-place editor.

If a field contains string data, a filter row uses a LIKE operator.

You can specify wildcard operators for a LIKE-match.  The default operators are a percent sign (%) for a substring comparison, and an underscore (_) for a single character comparison.  To change the comparison behavior, you can substitute the above operators with the other wildcards using the View’s DataController.Filter.PercentWildcard and DataController.Filter.UnderscoreWildcard properties.

By default, filtering is case insensitive. If needed, you can change this state by disabling the fcoCaseInsensitive on the view’s DataController.Filter.Options property.

Note: the above image shows filtering in the fracImmediately mode.  The filter panel automatically appears with the first update (if the View’s FilterBox.Visible property is set to fvNonEmpty).


Filtering DateTime Values


Sorting Data

See Also

The ExpressQuantumGrid provides you with the two following options to sort data in Grid Views:

•	by the column and card row content (available for tabular and Card Views);

•	by group values or group summary values (available for grouped tabular Views only).

Both these options can be switched and customized with ease both at design time and runtime.

This topic describes the methods related to the first option.  Refer to the Sorting Data by Group Summaries topic for more information on the second option.

Tabular Views represent data in columns, each of which has a caption displayed within the column header panel.  An end-user can click on the column header to sort data by the column’s content.  To sort by multiple columns, column headers should be clicked while holding down the Shift key.  When data is sorted by a column, a small arrow is displayed in its caption indicating the current sort order.  You can stop sorting against a particular column by clicking its header again while pressing the Ctrl key.

You may not want the user to be able to sort a particular view or column(s) - see the view’s OptionsCustomize.ItemSorting (OptionsCustomize.ColumnSorting in a grid table view) or the item’s Options.Sorting properties.

When data is sorted by multiple columns, the order in which you apply sorting is important.  Sorting orders the data according to the first sort column specified.  Other column values only come into play if earlier column(s) data is identical.

Let us examine the Customers table from the CardsDB database.  The following image shows a grid control with data sorted by the State, City and LastName columns.  Data is sorted in descending order by the State column (and in ascending order by City and LastName).  Filter arrows are indicated in color:

Sorting data programmatically can be applied to all types of items, i.e. columns in a grid table view and rows in a card view.  To implement such sorting, you should use the item’s SortOrder property.  Before sorting, you can call the view’s DataController.ClearSorting method to clear the current sorting if any.  The following code sets sorting for the State, City and LastName columns specified by the tvCustomersState, tvCustomersCity and tvCustomersLastName objects respectively.

The tvCustomers object refers to the view containing these columns:

//Delphi

  tvCustomers.BeginUpdate;

  tvCustomers.DataController.ClearSorting(True);

  tvCustomersState.SortOrder := soDescending;

  tvCustomersCity.SortOrder := soAscending;

  tvCustomersLastName.SortOrder := soAscending;

  tvCustomers.EndUpdate;

//C++ Builder

  tvCustomers->BeginUpdate();

  tvCustomers->DataController->ClearSorting(true);

  tvCustomersState->SortOrder = soDescending;

  tvCustomersCity->SortOrder = soAscending;

  tvCustomersLastName->SortOrder = soAscending;

  tvCustomers->EndUpdate();


Sorting Data by Group Summaries

See Also

The ExpressQuantumGrid provides you with the two following options to sort data in Grid Views:

•	by the column and card row content (available for tabular and Card Views);

•	by group values or group summary values (available for grouped tabular Views only).

Both these options can be switched and customized with ease both at design time and runtime.

This topic describes the methods related to the second option.  Refer to the Sorting Data topic for more information on the first option.

When a tabular View is grouped by any column, group rows are automatically sorted by group values provided by this column.  End-users can reverse the sort order of group rows by clicking a grouped column header or using the Column Header Popup Menu.

To programmatically specify the sort order, use a grouped column’s SortOrder property.  Refer to the Sorting Data topic for the code example on how this can be accomplished.

In addition to this standard method of sorting data in grouped Views, you can specify group rows to be sorted using group summary values calculated at the corresponding level.

The following image shows the View grouped by the Payment Type column.

In this View, the following two group summaries are calculated in data groups:

•	a group row summary calculated against the values of the Payment Amount column;

•	a group footer summary calculated against the values of the Quantity column.

End-users can choose the sort method from the Group Row Popup Menu.

As a result, group rows are sorted using the values of the selected summary.

In code, this can be done via:

•	a required summary item’s Sorted property.  At design time, you can access a summary item’s properties by clicking the corresponding group summary in a group row or group footer;

•	the Summary.SortByGroupFooterSummary or Summary.SortByGroupSummary property of a column whose summary values will be used for sorting.

The grouped column controls the order in which group rows are displayed when sorted by summary values.  End-users can change this order in a standard manner.

To apply a style to group summary values used to determine the sort order, use the View’s Styles.GroupSortedSummary and Styles.GroupFooterSortedSummary properties.  The following images display the View with these group summaries painted blue.


Expand and Collapse Rows

See Also

The ExpressQuantumGrid control displays records obtained from a data source with the help of a View object.  It provides four distinct types of views representing records in a specific manner:

•	a TableView arranges dataset records in rows each of which can be either of four types:

-	a grid data row (TcxGridDataRow) displaying field values of a dataset record;

-	a grid group row (TcxGridGroupRow) is a row displaying the value of a column by which data is grouped as well as any group summaries;

-	a grid master data row (TcxGridMasterDataRow) is a data (non-group) row in a master view;

-	the "new item row" (TcxGridNewItemRow) represents the row for entering new data;

•	a BandedTableView also represents dataset records as rows, but it is capable of arranging columns in bands.  The row types in a BandedTableView are the same as in a TableView.

•	a CardView arranges records in cards each of which represents an object of the TcxGridCard class.

•	a ChartView represents each dataset record as category and series values (which correspond to field values) within this category.  Various diagrams then render categories and series to produce charts.  You can aggregate data within categories using data groups.  Refer to the Creating Data Groups in Chart Views topic for additional information.

A TableView, BandedTableView and CardView reference displayed rows/cards via their ViewData property.  This property provides indexed access to all records which are currently visible or potentially visible by scrolling.  Records hidden under collapsed groups within tabular Views are not accessible via ViewData.  To access individual rows/cards by the record index, use the view’s ViewData.Records property (you can refer to the Records topic to know more about record objects).

A ChartView references the items (categories and series values) via the ViewData.Categories and ViewData.Values properties.  You can refer to the Obtain and Set Values in Chart Views topic for details.

Expand/collapse group & master rows in (banded) table views

Expanding/collapsing group & master rows can be performed in a number of ways:

•	the Expanded property of a record object.  It allows expanding/collapsing group & master rows:

The following code sets the Expanded property of the first record within the tvCustomers view to True.  If this record is either a group or master row, it will be expanded.  Otherwise, nothing happens.

//Delphi

tvCustomers.ViewData.Records[0].Expanded := True;

//C++ Builder

tvCustomers->ViewData->Records[0]->Expanded = true;

•	the Expand and Collapse methods of a record object.

Similar to the Expanded property, these methods allow you to expand group and master rows.  However, the Expand and Collapse methods enable you to perform recursive expansion/collapse of group rows.  If data is grouped by multiple columns, you can expand all nesting groups under the first row by using the following code:

//Delphi

tvCustomers.ViewData.Records[0].Expand(True);

//C++ Builder

tvCustomers->ViewData->Records[0]->Expand(true);

Passing False as the Expand method parameter expands only the given row.

Suppose you have two views representing a master-detail relationship, data within a master view being grouped by one or more columns.  Calling the Expand or Collapse method with True as a parameter for group rows within the master view does not expand/collapse nested master data rows.

The DoRecursiveExpansion procedure enables you to work around this problem.  It performs recursive expansion for the record specified by the ARecordIndex parameter within the AView view.  At first, it expands the given row.  Any nested rows, which have appeared, are also expanded.

//Delphi

procedure DoRecursiveExpansion(AView: TcxGridTableView; ARecordIndex: Integer);

var

  APrevRecordCount, ANestedRecordCount: Integer;

begin

  with AView.ViewData do

  begin

    APrevRecordCount := RecordCount;

    //Expand the given record

    Records[ARecordIndex].Expand(True);

    ANestedRecordCount := RecordCount  - APrevRecordCount;

    //Process nested records which have appeared

    while ANestedRecordCount > 0 do

    begin

      Inc(ARecordIndex);

      Records[ARecordIndex].Expand(True);

      Dec(ANestedRecordCount);

    end;

  end;

end;

//C++ Builder

void DoRecursiveExpansion(TcxGridTableView * AView, int ARecordIndex) {

  int APrevRecordCount, ANestedRecordCount;

  TcxGridViewData * AViewData = AView->ViewData;

  APrevRecordCount = AViewData->RecordCount;

  //Expand the given record

  AViewData->Records[ARecordIndex]->Expand(true);

  ANestedRecordCount = AViewData->RecordCount  - APrevRecordCount;

  //Process nested records which have appeared

  TcxCustomGridRecord * ARecord;

  while (ANestedRecordCount > 0) {

    ARecordIndex++;

    AViewData->Records[ARecordIndex]->Expand(true);

    ANestedRecordCount--;

  }

}

•	the Expand and Collapse methods of the view’s ViewData object.

These methods expand/collapse all group & master rows within a given view recursively.  They take the ARecurse parameter which specifies whether an expansion/collapse applied to a master view affects all corresponding detail views.

The next code expands records within the tvCustomers view and all detail views linked to it:

//Delphi

tvCustomers.ViewData.Expand(True);

//C++ Builder

tvCustomers->ViewData->Expand(true);


Adding Custom Filter and Grouping Date Ranges

See Also

The ExpressQuantumGrid allows you to manage filter and grouping date ranges by handling the OnInitFilteringDateRanges and OnInitGroupingDateRanges events, respectively.  You should handle a View’s OnInitFilteringDateRanges event to manage filter date ranges which are common to all items in this View.  To manage filter date ranges for a particular item, you should handle the item’s OnInitFilteringDateRanges event.  You can manage grouping date ranges in a similar manner by handling a View’s OnInitGroupingDateRanges and/or an item’s OnInitGroupingDateRanges events.

To use the predefined date ranges when filtering and grouping data in a View by date/time values, use the View’s DateTimeHandling.Filters and DateTimeHandling.Grouping properties.  Also you can specify grouping options for each individual column, which displays date/time values, via the column’s DateTimeGrouping property.  Refer to the descriptions of these properties to learn about the correspondence between the predefined date ranges, and filter and grouping options.

The ExpressQuantumGrid allows you to extend a list of the predefined date ranges with custom date ranges.  In order to do this, you should:

•	create a TcxCustomGridDateRange descendant;

•	to add the date range as a filter date range, handle the OnInitFilteringDateRanges event and add this date range to a collection of filter date ranges;

•	to add the date range as a grouping date range, handle the OnInitGroupingDateRanges event and add this date range to a collection of grouping date ranges.

The following code snippet demonstrates how to create a date range which represents a one-quarter period.

// Delphi

type

  TcxGridQuarterRange = class(TcxCustomGridDateRange)

  public

    function Contains(const ADate: TDateTime): Boolean; override;

    function GetDisplayText(const ADate: TDateTime): string; override;

    function GetRangeValue(const ADate: TDateTime; AIgnoreTime: Boolean): Variant; override;

    function GetValue(const ADate: TDateTime): Variant; override;

  end;

implementation

uses

  ..., cxDateUtils;

// ...

// Utility functions

function GetStartMonthOfQuarter(const ADate: TDateTime): Integer;

begin

  Result := GetDateElement(ADate, deMonth) div 4 * 3 + 1;

end;

function GetStartDateOfQuarter(const ADate: TDateTime): TDateTime;

begin

  Result := EncodeDate(GetDateElement(ADate, deYear), GetStartMonthOfQuarter(ADate), 1);

end;

function GetEndDateOfQuarter(const ADate: TDateTime; AIgnoreTime: Boolean): TDateTime;

var

  AMonth, AYear: Integer;

begin

  AYear := GetDateElement(ADate, deYear);

  AMonth := GetStartMonthOfQuarter(ADate) + 2;

  Result := EncodeDate(AYear, AMonth, MonthDays[IsLeapYear(AYear), AMonth]);

  if not AIgnoreTime then

    Result := Result + EncodeTime(23, 59, 59, 999);

end;

{ TcxGridQuarterRange }

function TcxGridQuarterRange.Contains(const ADate: TDateTime): Boolean;

begin

  Result := True;

end;

function TcxGridQuarterRange.GetDisplayText(const ADate: TDateTime): string;

begin

  Result := 'Qtr' + IntToStr(GetDateElement(ADate, deMonth) div 4 + 1) +

    ' ' + IntToStr(GetDateElement(ADate, deYear));

end;

function TcxGridQuarterRange.GetRangeValue(const ADate: TDateTime; AIgnoreTime: Boolean): Variant;

begin

  Result := VarBetweenArrayCreate(GetStartDateOfQuarter(ADate), GetEndDateOfQuarter(ADate, AIgnoreTime));

end;

function TcxGridQuarterRange.GetValue(const ADate: TDateTime): Variant;

begin

  Result := GetStartDateOfQuarter(ADate);

end;

The following code snippet demonstrates how to add the created date range to filter and grouping collections of date ranges by handling a View’s OnInitFilteringDateRanges and OnInitGroupingDateRanges events.

// Delphi

// A View’s OnInitFilteringDateRanges event handler

procedure TForm1.tvCustomersInitFilteringDateRanges(

  Sender: TcxCustomGridTableItem; ADateRanges: TcxGridDateRanges);

begin

  ADateRanges.Add(TcxGridQuarterRange);

end;

// A View’s OnInitGroupingDateRanges event handler

procedure TForm1.tvCustomersInitGroupingDateRanges(

  Sender: TcxCustomGridTableItem; ADateRanges: TcxGridDateRanges);

begin

  ADateRanges.Add(TcxGridQuarterRange);

end;

The following image shows the resulting View.

To narrow an item’s filter value list to display only values that correspond to date ranges, handle the item’s OnGetFilterValues event.


Creating Data Groups in Chart Views

See Also

This topic describes the methods used to create data groups in Chart Views.  The examples that are referred to herein are based on the MasterDetailChartDemo that is shipped with the ExpressQuantumGrid.

By exploiting the data grouping capability of Chart Views, you can design a multilevel (hierarchical), interactive Chart, without the need to implement data-drilling since both the drill-down and drill-up functionality is built directly into the control.

Creating Data Groups at Design Time

In this demo, the chvOrders detail Chart View (see the Orders page) initially displays information on payments grouped by orders.  To group series values by payment type, create a new data group and bind it to the PaymentType field as described below.

Click the chvOrders label in the Structure Navigator and then click the Customize… button to invoke the Component Editor.

Open the DataGroups page by clicking the corresponding tab in the Component Editor.

Click the Add… button to add a data group.  This will display a dropdown menu which lists all data source fields.  Choose the PaymentType field.

This creates the required data group and automatically updates the View.  Now values are grouped by the payment type.

Note that chvOrdersPaymentAmountSeries series values - which displays payment amounts - are summarized because the GroupSummaryKind property of this series is set to skSum by default.  You can specify a different computation as your needs dictate.

When adding a data group, the chart toolbox appeared on-screen.  It displays the data level navigator (labeled as ‘Data Levels’).  This element provides drill-down functionality for end-users.  The default values of the View’s ToolBox.Visible and ToolBox.DataLevelsInfoVisible properties allow the chart toolbox and data level navigator to be displayed when at least a single data group is visible in a Chart View.

When running, the MasterDetailChartDemo displays the pound (#) symbol which precedes the captions of category values.  This modification is done in the View’s Categories.OnGetValueDisplayText event handler.

// Delphi

  ADisplayText := '#' + ADisplayText;

// C++ Builder

  ADisplayText = "#" + ADisplayText;

Remove this handler to display the captions of category values as is.

To explore the drill-down functionality, let’s create a second-level group.  At this level, we’ll aggregate the data by the purchase date.  To do this, open the Component Editor and add the data group bound to the PurchaseDate field.  Note that the PaymentType field associated with the first-level data group remains checked in the Add… dropdown menu.

This adds the required data group to the list and creates the corresponding data level in the data level navigator.

You can change the display order of data groups in the list by clicking the Move Up and Move Down buttons.  This results in a change to the hierarchy (see below):

Alternatively, you can drag data levels in the data level navigator to change the hierarchy of the grouped data.  End-users are able to do this at runtime provided that the View’s OptionsCustomize.DataGroupMoving property is set to True.  Note that the label (‘Data’), which corresponds to default categories cannot be moved in this manner since it represents the highest level of detail.

You can customize the caption of this label using the View’s Categories.DisplayText property.  At design time, you can click this visual element to display the properties of the default categories in the Object Inspector.

End-users can drill down on the aggregated value either by clicking the corresponding data marker or selecting a value from the list available for each data group (called a data group active value).  To drill up, end-users can right-click anywhere on the chart or click a data level’s label in the data level navigator.  Use the View’s OptionsCustomize.DataDrillUpMethod property to specify the manner in which a drill-up can be performed.

To learn more about groups and group summaries in tabular Views, and data groups and aggregate values in Chart Views, run the ChartDataDrillingDemo that is shipped with the ExpressQuantumGrid.

Creating Data Groups at Runtime

To programmatically add a data group to a Chart View, you should call the View’s CreateDataGroup method.  To map this data group to a specific field in the bound dataset, use the DataBinding.FieldName property.  The Index property of the data group allows you to specify the visual position of this data group and the corresponding data level in the data level navigator of a chart toolbox.

The following code snippet demonstrates how to create PaymentType and PurchaseDate data groups.  Note that the PurchaseDate data group is positioned as the first visible data group.

// Delphi

  with chvOrders.CreateDataGroup do

    DataBinding.FieldName := 'PaymentType';

  with chvOrders.CreateDataGroup do

  begin

    DataBinding.FieldName := 'PurchaseDate';

    Index := 0;

  end;

// C++ Builder

  TcxGridDBChartDataGroup *dgPaymentType = (TcxGridDBChartDataGroup*) chvOrders->CreateDataGroup();

  dgPaymentType->DataBinding->FieldName = "PaymentType";

  TcxGridDBChartDataGroup *dgPurchaseDate = (TcxGridDBChartDataGroup*) chvOrders->CreateDataGroup();

  dgPurchaseDate->DataBinding->FieldName = "PurchaseDate";

  dgPurchaseDate->Index = 0;

The resulting View is shown in the image below:


Summaries

See Also

The ExpressQuantumGrid provides a very useful feature called Summaries.  It allows you to calculate totals against a group of records or all the records and represent the results in a convenient form.

You can create multiple summaries both at runtime via code and at design time using the Component Editor and Object Inspector.

Our grid control gives you the ability to calculate five built-in summaries:

•	Sum

•	Average of values

•	The number of records

•	Maximum value

•	Minimum value

But it is also possible to calculate more complex aggregate functions which combine the values of several columns.  This can be implemented by handling grid events (OnSummary and OnAfterSummary).  You are also able to exclude specific rows (containing NULL, for instance) and change the summary results on the fly.

There are two summary types available: footer and group summaries.  A footer summary calculates its value by using all the records in a grid view.  The footer summary result is displayed within the footer panel at the bottom of a grid view.

In tabular Views, group summaries are calculated when data is grouped by column(s).  They are calculated for each data group created and displayed either within a group row or within the group's footer.  Only records contained within a group are used to evaluate these summary values.

In Chart Views, group summaries are calculated when series values are aggregated in the same categories using data groups.  Group summaries are calculated for each category and displayed as aggregate values.

The view’s OptionsView.GroupFooters property determines the manner in which group footer panels are displayed.  Group footer panels can be set to always be visible, visible only when a group is expanded or they can be completely hidden.

ExpressQuantumGrid allows you to calculate individual group summaries according to the current group column.  The following screenshot displays data grouped by two columns: Product and Customer:

For the group identified by the Product grouping column, two summaries are calculated:

•	Last purchase date – the maximum value within the PurchaseDate column

•	Records – the number of records within the group

For the group identified by the Customer grouping column, two different summaries are calculated:

•	Payment Amount – the sum of the values in the PaymentAmount column

•	Quantity – the sum of the Quantity column

Calculating different summaries when grouping by specific columns is implemented by creating summary groups.  A summary group links a proposed group column(s) with the group summaries to calculate.

For the above example, two summary groups must be created.  The first one links the Product column with the two summaries (Last purchase date and Records).  The second summary group links the Customer column with another two summaries (Payment Amount and Quantity).

Summaries can only reference records relating to a single view. A view is a grid item representing records from a single data source and displaying them in a particular form (table, banded table, card views).  A card view does not support summaries.  Only table and banded table views (TcxGridTableView descendants) that display data source records in a tabular form provide support for footers, group summaries and summary groups.

The calculation of summaries is implemented within the data controller.  The main task of the data controller is to connect to a data store (custom data source or dataset).  However, it also encapsulates grouping and filtering operations on data and evaluates summaries.  To access the summaries of a particular view, use the view’s DataController.Summary object.  The most convenient way to calculate footer and group summaries is to specify a summary for a particular column using the column’s Summary property.

For more information, see the summary related topics in the Task Based Help section.


Creating Summaries Overview
Creating Summaries

See Also

ExpressQuantumGrid supports three summary types.  It can evaluate: footer summaries, group summaries and summary groups.  Footer summaries are calculated over all the records in a grid view.  Group summaries are calculated over groups of records when data in a view is grouped by grid items (columns in tabular Views and data groups in Chart Views).  A summary group is a set of group summaries that are calculated when grouping by particular columns.  Refer to the Summaries topic for general information on summaries.

Summaries in a grid view are calculated by a data controller.  The DataController.Summary property of the TcxDataSummary class gives you the ability to

•	specify footer summaries via FooterSummaryItems;

•	set group summaries via DefaultGroupSummaryItems;

•	manage summary groups via SummaryGroups;

•	determine whether to calculate summaries against all or just selected records and ignore null values (the Options property);

•	get and set summary results;

•	etc.

TcxDataSummaryItem is the base element of all types of summary.  It references the column by which to calculate the summary, a function (Sum, Minimum, Maximum, Count, Average), the format of the output string and the position at which to display the result.

For further information about creating specific summaries, refer to the following topics:

Creating Footer and Group Summaries

Creating Summary Groups


Creating Footer and Group Summaries

See Also

Setting footer and group summaries is a similar process.  We will create a footer summary based on the SummaryFooterDemo.  Let us calculate the sum of payments for the tvOrders detail view.

At design time, footer and group summaries can be specified in two ways:

•	by using the Component Editor to manage summary items for all columns within a (banded) table view;

•	by setting the Summary property for particular columns.

The first method involves the following steps:

1.	Open the Component Editor and switch to the Summary panel.

2.	Click the tvOrders label in the left panel to select this view.  The label at the top of the right panel should indicate: Selected View: tvOrders.

3.	Press the Add button on the Footer panel to add a new summary.  This adds a TcxGridDBTableSummaryItem object to the FooterSummaryItems collection.

4.	Select the newly created item and open the Object Inspector window to display its properties.  Alternatively, you can click a cell, which displays the created summary item’s values.

5.	Set the item’s properties as follows:

•	set the Column property to tvOrdersPaymentAmount.  This specifies the column by which the summary can be calculated and where the result should be placed.

•	set the Kind property to skSum

•	set the Format property to ‘SUM = $,0.00;-$,0.00’.  This property specifies the pattern for displaying the summary string.  The 0.00 portion will be substituted with the summary result.  The two zeros following the point identify the number of digits in the summary result to the right of the decimal point.  The comma represents the ThousandSeparator global variable.  The semicolon separates two patterns used to display positive and negative results respectively.  Other characters do not have special meaning and display onscreen as is.

The FieldName property can also be used to address the column by which to evaluate a summary.  If both Column and FieldName are specified, the result of the summary calculated by FieldName values will be displayed in the Column footer region.

Creating a footer summary at runtime is listed below:

//Delphi

  with tvOrders.DataController.Summary do

  begin

    BeginUpdate;

    try

      with FooterSummaryItems.Add as TcxGridDBTableSummaryItem do

      begin

        Column := tvOrdersPaymentAmount;

        Kind := skSum;

        Format := 'SUM = $,0.00;-$,0.00';

      end;

    finally

      EndUpdate;

    end;

    //Update all open details of the master view (tvCars)

    tvCars.DataController.ClearDetails;

  end;

//C++ Builder

  TcxDataSummary * summary = tvOrders->DataController->Summary;

  summary->BeginUpdate();

  try {

    TcxGridDBTableSummaryItem *summaryItem = (TcxGridDBTableSummaryItem *)(summary->FooterSummaryItems->Add());

    summaryItem->Column = tvOrdersPaymentAmount;

    summaryItem->Kind = skSum;

    summaryItem->Format = "SUM = $,0.00;-$,0.00";

  } __finally {

    summary->EndUpdate();

  }

  //Update all open details of the master view (tvCars)

  tvCars->DataController->ClearDetails();

The second and most convenient way is to specify footer and group summaries for a particular column.  This involves the following steps:

1.	Select the tvOrdersPaymentAmount column.  You can do this using the Object TreeView or by expanding the detail view (tvOrders) or by clicking the tvOrdersPaymentAmount column in the view’s header panel.

Or open the Component Editor and click the tvOrders label in the left panel to select this view.  The label at the top of the right panel should indicate: Selected View: tvOrders.and select the tvOrdersPaymentAmount column in the Columns list.

2.	Open the Object Inspector window to display the column’s properties.  Set its properties as follows:

•	set the FooterKind property to skSum

•	set the FooterFormat property to ‘SUM = $,0.00;-$,0.00’ to specify the pattern used for displaying the summary string.

This automatically adds a TcxGridDBTableSummaryItem object to the FooterSummaryItems collection and sets its Column and Kind properties to the values which you entered/selected manually using the first method.

(The image below assumes that there are no existing footer summaries within this view.)

The summary item’s Position property is set to the spFooter in the same way as the FooterKind and FooterFormat properties were set.

You might need to set the item’s FieldName property in the Component Editor to address the column which a summary is evaluated for, since the second method assumes that the summary is calculated for the column you selected and thus leaves the FieldName property unchanged.

Creating a footer summary by this method at runtime is listed below:

//Delphi

  with tvOrdersPaymentAmount.Summary do

  begin

    FooterKind := skSum;

    FooterFormat := 'SUM = $,0.00;-$,0.00';

  end;

//C++ Builder

  TcxGridColumnSummary * summary = tvOrdersPaymentAmount->Summary;

  summary->FooterKind = skSum;

  summary->FooterFormat = "SUM = $,0.00;-$,0.00";

This code is sufficient to display the summary by the tvOrdersPaymentAmount values under this column in the footer panel of the tvOrders view.

The following image shows the result of the footer summary calculation in a detail view:

As for the group summary, you can set the position where a summary will be displayed by using the Position property or specify the corresponding column’s GroupKind or GroupFooterKind properties.  A group summary can be displayed either in a group row or in a group footer panel.


Creating Summary Groups

See Also

The SummaryGroupDemo demonstrates summary group calculation.  This demo displays Orders table data from the CarsDB database.  When grouping data by the CustomerID and ProductID columns, different summaries are calculated.

Let us examine the steps for creating two summary groups.  The first summary group will calculate Sum and Count summaries using the PaymentAmount column when data is grouped by CustomerID.  The second group also specifies two summaries to calculate, but this time for when grouping is by the ProductID column.  In this instance, Sum and Minimum summaries are evaluated by the OrdersQuantity and PurchaseDate columns, respectively.

1.	Open the Component Editor and switch to the Groups panel for the tvOrders view.  (The images below assume that there were no existing summary groups within this view.)

2.	Click the Add button to create a new group.  A summary group represents an object of the TcxDataSummaryGroup class associating a collection of proposed grouping columns with summaries to calculate (a collection of TcxDataSummaryItem objects).

When a summary group is created, the Unlinked Columns panel is populated with the columns of the current view.

3.	Select the CustomerID column from the Unlinked Columns panel and click the ‘>’ button to move it to the Linked Columns group.

4.	Create a summary in the Items panel by clicking the corresponding Add button.

5.	Select it via the mouse and open the Object Inspector window to display this item's properties. Set its properties as follows:

•	set Column to tvOrdersPaymentAmount

•	set Kind to skSum

•	set Format to 'Amount Paid: $,0'

6.	To create the second summary, click the Add button on the Items panel once more and adjust its properties as displayed in the following image:

The first summary group is completed.  The second summary group can be created in the same manner.  But instead of CustomerID, the ProductID column should be moved to the Linked Columns panel and the two summary items should reference the OrdersQuantity and PurchaseDate columns.

The following code shows how you can create these summaries programmatically:

//Delphi

  with tvOrders.DataController.Summary do

  begin

    BeginUpdate;

    try

      SummaryGroups.Clear;

      //The first summary group

      with SummaryGroups.Add do

      begin

        //Add proposed grouping column(s)

        TcxGridTableSummaryGroupItemLink(Links.Add).Column := tvOrdersCustomerID;

        //Add summary items

        with SummaryItems.Add as TcxGridDBTableSummaryItem do

        begin

          Column := tvOrdersPaymentAmount;

          Kind := skSum;

          Format := 'Amount Paid: $,0';

        end;

        with SummaryItems.Add as TcxGridDBTableSummaryItem do

        begin

          Column := tvOrdersPaymentAmount;

          Kind := skCount;

          Format := 'Records: 0';

        end;

      end;

      //The second summary group

      with SummaryGroups.Add do

      begin

        //Add proposed grouping column(s)

        TcxGridTableSummaryGroupItemLink(Links.Add).Column := tvOrdersProductID;

        //Add summary items

        with SummaryItems.Add as TcxGridDBTableSummaryItem do

        begin

          Column := tvOrdersQuantity;

          Kind := skSum;

          Position := spFooter;

          Format := 'TOTAL = 0';

        end;

        with SummaryItems.Add as TcxGridDBTableSummaryItem do

        begin

          Column := tvOrdersPurchaseDate;

          Kind := skMin;

          Position := spFooter;

        end;

      end;

    finally

      EndUpdate;

    end;

  end;

//C++ Builder

  TcxDataSummary * summary = tvOrders->DataController->Summary;

  summary->BeginUpdate();

  try {

    summary->SummaryGroups->Clear();

    TcxDataSummaryGroup *summaryGroup;

    TcxGridDBTableSummaryItem *summaryItem;

    //The first summary group

    summaryGroup = summary->SummaryGroups->Add();

    //Add proposed grouping column(s)

    ((TcxGridTableSummaryGroupItemLink *)summaryGroup->Links->Add())->Column = tvOrdersCustomerID;

    //Add summary items

    summaryItem = (TcxGridDBTableSummaryItem *)summaryGroup->SummaryItems->Add();

    summaryItem->Column = tvOrdersPaymentAmount;

    summaryItem->Kind = skSum;

    summaryItem->Format = "Amount Paid: $,0";

    summaryItem = (TcxGridDBTableSummaryItem *)summaryGroup->SummaryItems->Add();

    summaryItem->Column = tvOrdersPaymentAmount;

    summaryItem->Kind = skCount;

    summaryItem->Format = "Records: 0";

    //The second summary group

    summaryGroup = summary->SummaryGroups->Add();

    //Add proposed grouping column(s)

    ((TcxGridTableSummaryGroupItemLink *)summaryGroup->Links->Add())->Column = tvOrdersProductID;

    //Add summary items

    summaryItem = (TcxGridDBTableSummaryItem *)summaryGroup->SummaryItems->Add();

    summaryItem->Column = tvOrdersQuantity;

    summaryItem->Kind = skSum;

    summaryItem->Position = spFooter;

    summaryItem->Format = "TOTAL = 0";

    summaryItem = (TcxGridDBTableSummaryItem *)summaryGroup->SummaryItems->Add();

    summaryItem->Column = tvOrdersPurchaseDate;

    summaryItem->Kind = skMin;

    summaryItem->Position = spFooter;

  } __finally {

    summary->EndUpdate();

  }

The following image shows a grid control with data grouped by the CustomerID and ProductID columns.  For the first group level, the two summaries specified by the summary group linked to the CustomerID column are calculated.  In the second group level, summaries are specified by the summary group linked to the ProductID column:


Creating Custom Summaries

See Also

The ExpressQuantumGrid provides two events that allow a user to control summary calculations.  These events are

•	OnSummary event;

•	OnAfterSummary event.

Handling these events allows you to change the default summary calculations or implement your own functions for summary calculations.

The OnSummary event occurs when calculating a summary value.  The event parameters are used to identify the summary item to be calculated, the currently calculated value (for instance, for Sum summary type), the number of records involved in the summary calculation and other summary parameters.

The following code alters a Record count summary to count only those fields with values greater than 300000:

//Delphi

procedure TSummaryMultiDemoMainForm.tvOrdersDataControllerSummaryDefaultGroupSummaryItemsSummary(

  ASender: TcxDataSummaryItems; Arguments: TcxSummaryEventArguments;

  var OutArguments: TcxSummaryEventOutArguments);

var

  AValue: Variant;

  AItem: TcxGridTableSummaryItem;

begin

//the summary item whose value is calculated is identified by the

//TcxSummaryEventArguments.SummaryItem property

  AItem := TcxGridTableSummaryItem(Arguments.SummaryItem);

//if the required item is calculated against the ProductID column, its type

//is Count and it is displayed within the group row...

  if (AItem.Column = tvOrdersProductID) and

    (AItem.Kind = skCount) and (AItem.Position = spGroup) then

  begin

//...then the AValue variable is assigned the value of PaymentAmount field of

//a record, identified by the TcxSummaryEventArguments.RecordIndex property

    AValue := tvOrders.DataController.Values[

      Arguments.RecordIndex, tvOrdersPaymentAmount.Index];

    if not VarIsNull(AValue) then

//if the obtained value is less than or equal to 300000, then...

      if VarAsType(AValue, varInteger) <= 300000 then

//...the TcxSummaryOutArguments.CountValue property, representing the number

//of records involved into summary calculations, is decreased by 1

       Dec(OutArguments.CountValue);

  end;

end;

//C++ Builder

void __fastcall TSummaryMultiDemoMainForm::tvOrdersDataControllerSummaryDefaultGroupSummaryItemsSummary(

      TcxDataSummaryItems *ASender, TcxSummaryEventArguments &Arguments,

      TcxSummaryEventOutArguments &OutArguments)

{

//the summary item whose value is calculated is identified by the

//TcxSummaryEventArguments.SummaryItem property

  TcxGridTableSummaryItem* AItem = (TcxGridTableSummaryItem*)Arguments.SummaryItem;

//if the required item is calculated against the ProductID column, its type

//is Count and it is displayed within the group row...

  if((AItem->Column == tvOrdersProductID) && (AItem->Kind == skCount) &&

    (AItem->Position == spGroup)) {

//...then the AValue variable is assigned the value of PaymentAmount field of

//a record, identified by the TcxSummaryEventArguments.RecordIndex property

    Variant AValue = tvOrders->DataController->Values[Arguments.RecordIndex]

      [tvOrdersPaymentAmount->Index];

    if(!VarIsNull(AValue))

//if the obtained value is less than or equal to 300000, then...

      if(VarAsType(AValue, varInteger) <= 300000)

//...the TcxSummaryOutArguments.CountValue property, representing the number

//of records involved into summary calculations, is decreased by 1

        OutArguments.CountValue--;

  }

}

The result of executing the above code is demonstrated below.  The calculated summary and the corresponding PaymentAmount column values are emphasized:

The OnAfterSummary event occurs after all summary values have been calculated.  Handling it allows you to work with any summary value, even those which are not currently visible.  This event accepts one argument – an instance of the TcxDataSummary class, representing all the summaries calculated within a view.

The following code iterates through the summaries of all groups in a level calculating the maximum value and displays it as the root group level summary.

//Delphi

procedure TSummaryGroupDemoMainForm.tvOrdersDataControllerSummaryAfterSummary(

  ASender: TcxDataSummary);

var

  AItem: TcxGridTableSummaryItem;

  AGroups: TcxDataControllerGroups;

  AValue, AMaxValue: Variant;

  I: Integer;

begin

  //The first footer summary item, displayed within the PaymentAmount column footer

  //is formatted to display the maximum value of the first group summary item displayed

  //at the root group level

  AItem := TcxGridTableSummaryItem(ASender.FooterSummaryItems[0]);

  AItem.Format := 'The maximum number of sold cars is: 0';

  AGroups := ASender.DataController.Groups;

  //the AMaxValue variable contains the value of the first required group summary item

  AMaxValue := ASender.GroupSummaryValues[AGroups.ChildDataGroupIndex[-1, 0], 0];

  //for all group rows...

  for I := 1 to AGroups.ChildCount[-1] - 1 do

  begin

  //the AValue variable contains the value of the required group summary item

      AValue := ASender.GroupSummaryValues[AGroups.ChildDataGroupIndex[-1, I], 0];

  //if the obtained value is greater than the current maximum, then the current maximum value is replaced with the obtained value

      if AValue > AMaxValue then AMaxValue := AValue;

  end;

  //the value of the first footer summary item is set to maximum value of the first group summary item at the roow group level

  ASender.FooterSummaryValues[0] := AMaxValue;

end;

//C++ Builder

void __fastcall TSummaryGroupDemoMainForm::tvOrdersDataControllerSummaryAfterSummary(

      TcxDataSummary *ASender)

{

  //The first footer summary item, displayed within the PaymentAmount column footer

  //is formatted to display the maximum value of the first group summary item displayed

  //at the root group level

  TcxGridTableSummaryItem* AItem = (TcxGridTableSummaryItem*)ASender->FooterSummaryItems->Items[0];

  AItem->Format = "The maximum number of sold cars is: 0";

  TcxDataControllerGroups* AGroups = ASender->DataController->Groups;

  //the AMaxValue variable contains the value of the first required group summary item

  Variant AMaxValue = ASender->GroupSummaryValues[AGroups->ChildDataGroupIndex[-1][0]][0];

  //for all group rows...

  for (int i = 0; i < AGroups->ChildCount[-1]; i++) {

  //the AValue variable contains the value of the required group summary item

    Variant AValue = ASender->GroupSummaryValues[AGroups->ChildDataGroupIndex[-1][i]][0];

  //if the obtained value is greater than the current maximum, then the current maximum value is replaced with the obtained value

    if (AValue > AMaxValue) AMaxValue = AValue;

  }

  //the value of the first footer summary item is set to maximum value of the first group summary item at the roow group level

  ASender->FooterSummaryValues[0] = AMaxValue;

}

The result of executing the above code is demonstrated below.  The calculated value of the footer summary and the corresponding group summary value are emphasized:


Obtain And Set Summary Values

See Also

The ExpressQuantumGrid supports two summary types: footer summary and group summary.  These summaries’ values are calculated via several built in functions: Max, Min, Sum, Average and Count.  The ExpressQuantumGrid provides several events, which can be used for custom summary implementations (see the Create Custom Summary topic for details).

This topic explains how to work with the summary values. It consists of the following sections:

•	Footer summary values;

•	Group summary values.

FOOTER SUMMARY VALUES

Footer summaries are displayed within the grid footer.  Each footer summary is an instance of the TcxDataSummaryItem class.  All footer summary items can be accessed via the View.DataController.Summary.FooterSummaryItems property.  To obtain or set the value of a specific footer summary item use the View.DataController.Summary.FooterSummaryValues property.  The formatted text of a specific footer summary can be obtained via the View.DataController.Summary.FooterSummaryTexts property.

The following code demonstrates how to obtain the value of a footer summary calculated for a specific data field.  Note, that the FooterSummaryValues property returns the value of the footer summary item as a Variant:

// Delphi

//...

var

  I: Integer;

  AValue: Variant;

begin

  with tvOrders.DataController.Summary do

  begin

    for I := 0 to FooterSummaryItems.Count - 1 do

    begin

      if TcxGridDBTableSummaryItem(FooterSummaryItems[I]).Column = tvOrdersPurchaseDate then

      begin

        AValue := FooterSummaryValues[I];

      end;

    end;

  end;

end;

//...

//C++ Builder

//...

  TcxDataSummary* ASummary = tvOrders->DataController->Summary;

  for(int i = 0; i < ASummary->FooterSummaryItems->Count; i++) {

    TcxGridTableSummaryItem* AItem = (TcxGridTableSummaryItem*)ASummary->FooterSummaryItems->Items[i];

    if (AItem->Column == tvOrdersPurchaseDate)

       Variant AValue = ASummary->FooterSummaryValues[i];

  }

//...

GROUP SUMMARY VALUES

Group summaries are calculated against grouped records.  In tabular Views, group summaries can be displayed within the group footer or within the grouping row.

In Chart Views, group summaries are calculated when series values are aggregated in the same categories using data groups.  Group summaries are calculated for each category and displayed as aggregate series values.  Group summaries are displayed as data markers which correspond to aggregate series values.

There are two types of group summaries:

•	group summaries, displayed when a view is grouped by any column values (accessed via the View.DataController.Summary.DefaultGroupSummaryItems collection);

•	summary groups, displayed when grouping occurs by specific columns (accessed via the View.DataController.Summary.SummaryGroups collection).

All summary items representing both the group summaries and summary groups can be accessed via the GroupSummaryItems collection.

Use the View.DataController.Summary.GroupSummaryValues property to obtain or set the values of the group summary.  This property provides access to all the summary values, regardless of the corresponding group's row state (expanded or collapsed).  It uses the index of the required data group and the required group summary index among the group summaries associated with the specified data group to address a summary value.  The data group index can be retrieved via properties of the TcxDataControllerGroups object, representing the collection of all groups within a view.

The following code demonstrates how to use the GroupSummaryValues property to obtain a summary value.  It locates the summary item, associated with the Purchase Date column from among the summary items of the fifth group row at the first group level.

//Delphi

//...

var

  AValue: Variant;

  AGroups: TcxDataControllerGroups;

  I: Integer;

//...

//the AGroups variable references a TcxDataControllerGroups instance

//representing all data groups within the tvOrders view

AGroups := tvOrders.DataController.Groups;

with tvOrders.DataController.Summary do

begin

//searching within the collection of the summary items associated

//with the first group level...

  for I := 0 to GroupSummaryItems[0].Count - 1 do

  begin

//for a summary item whose Column property addresses the Purchase

//Date column...

    if TcxGridTableSummaryItem(GroupSummaryItems[0].Items[I]).Column = tvOrdersPurchaseDate then

//...and assigning such item’s value to the AValue variable.  The

//required value is addressed via the ChildDataGroupIndex property

//which is passed –1 as the root group level index and 4 as the

//required group row index within the root group level

      AValue := GroupSummaryValues[AGroups.ChildDataGroupIndex[-1, 4], I];

  end;

end;

//...

//C++ Builder

//...

TcxDataSummary* ASummary = tvOrders->DataController->Summary;

//the AGroups variable references a TcxDataControllerGroups instance

//representing all data groups within the tvOrders view

TcxDataControllerGroups* AGroups = tvOrders->DataController->Groups;

//searching within the collection of the summary items associated

//with the first group level...

for (int i = 0; i < ASummary->GroupSummaryItems[0]->Count; i++) {

    TcxGridTableSummaryItem* AItem = (TcxGridTableSummaryItem*)ASummary->GroupSummaryItems[0]->Items[i];

//for a summary item whose Column property addresses the Purchase

//Date column...

  if (AItem->Column == tvOrdersPurchaseDate)

//...and assigning such item’s value to the AValue variable.  The

//required value is addressed via the ChildDataGroupIndex property

//which is passed –1 as the root group level index and 4 as the

//required group row index within the root group level

     Variant AValue = ASummary->GroupSummaryValues[AGroups->ChildDataGroupIndex[-1][4]][i];

}

//...

To obtain or set only visible group summaries' values use the View.DataController.Summary.GroupSummaryDisplayValues property, which addresses summary values via the required row index.

The formatted representation of the group summary can be accessed through two properties:

•	The View.DataController.Summary.GroupFooterSummaryTexts property provides access to the texts of group summaries displayed within the group footers;

•	The View.DataController.Summary.GroupSummaryText property provides access to the text representations of group summaries, displayed within the group rows.

The following code demonstrates how to obtain the group summary value, displayed within the Payment Amount column footer of the second row at the first group level.  This code uses the GroupFooterIndexOfItemLink property to obtain the index of the required group summary.  Keep in mind that the summary value can be obtained as a Variant value.

//Delphi

var

  AValue: Variant;

  AFooterItemIndex: Integer;

//...

with tvOrders.DataController.Summary do

begin

//the AFooterItemIndex variable contains the index of a group summary

//displayed within the tvOrdersPaymentAmount column footer at the

//first group level

  AFooterItemIndex := GroupFooterIndexOfItemLink[0, tvOrdersPaymentAmount];

//the AValue variable is used to store the group summary value

//displayed within the tvOrdersPaymentAmount column footer of the

//second row at the first group level

  AValue := GroupSummaryDisplayValues[1, 0, AFooterItemIndex];

end;

//...

//C++ Builder

//...

TcxDataSummary* ASummary = tvOrders->DataController->Summary;

//the AFooterItemIndex variable contains the index of a group summary

//displayed within the tvOrdersPaymentAmount column footer at the

//first group level

int AFooterItemIndex = ASummary->GroupFooterIndexOfItemLink[0][tvOrdersPaymentAmount];

//the AValue variable is used to store the group summary value

//displayed within the tvOrdersPaymentAmount column footer of the

//second row at the first group level

Variant AValue = ASummary->GroupSummaryDisplayValues[1][0][AFooterItemIndex];

//...


Selecting Records

See Also

This section relates to selecting records programmatically.  Focused and selected records are discussed in the Focused/Selected Records topic.

If the view’s OptionsSelection.MultiSelect property is set to False, only one record (row in a (banded) table view or card in a card view) can be selected at a time.  This record is said to be focused.  Focusing a record automatically selects it.

You can use the following code to focus and select the first record within the tvFilms view at the same time:

//Delphi

tvFilms.ViewData.Records[0].Focused := True;

//C++ Builder

tvFilms->ViewData->Records[0]->Focused = true;

If the view’s OptionsSelection.MultiSelect property is set to True, you are able to select multiple records at once.  When this option is enabled and an end-user clicks any record, it becomes focused and selected at the same time.  The focused record can be deselected by clicking it while holding down the Ctrl key.  Furthermore, when the view’s OptionsBehavior.PullFocusing property is set to True an end user can select records by holding down the left mouse button whilst dragging the mouse pointer over the records to be selected.  This automatically focuses the records under the cursor and adds them to the selection.

To select/deselect multiple records, you can use one of the following methods:

•	the Selected property of a record object.

The following code navigates the Orders dataset displayed by the tvOrders view and selects records which have a payment amount greater than 100000.  To navigate the dataset, we use a TDataSet object's First and Next methods, which move focus through the records in the dataset.  The currently focused record is accessed via the view’s Controller.FocusedRecord property.

Note that this code works correctly in the following cases:

1)	when Grid Mode is applied (the view’s DataController.DataModeController.GridMode property is set to True)

2)	when synchronization between a grid control and a TDataSet object is enabled (the view’s DataController.DataModeController.SyncMode property is set to True) and grouping is not used.

//Delphi

var

  AView: TcxGridDBTableView;

//...

  AView := tvOrders;

  AView.OptionsSelection.MultiSelect := True;

  AView.Controller.ClearSelection;

  with AView.DataController.DataSet do

  begin

    First;

    while not EOF do

    begin

      if FieldValues['PaymentAmount'] > 100000 then

        AView.Controller.FocusedRecord.Selected := True;

      Next;

    end;

  end;

//C++ Builder

  TcxGridDBTableView * AView = tvOrders;

  AView->OptionsSelection->MultiSelect = true;

  AView->Controller->ClearSelection();

  TDataSet * ADataSet = AView->DataController->DataSet;

  ADataSet->First();

  while(! ADataSet->Eof) {

    if (ADataSet->FieldValues["PaymentAmount"] > 100000)

      AView->Controller->FocusedRecord->Selected = true;

    ADataSet->Next();

  }

•	the ChangeRowSelection method of the view’s data controller

This method changes the selection state of a given row.  The row is addressed by the method’s ARowIndex parameter which specifies the row index (visual position of a row within a view).  Using row indexes you can access both group and data rows.  Rows hidden under collapsed groups are not indexed.

The following code selects the records within the tvCustomers view based on the Customer field's value.  The Customer field is a string field and it is displayed by the tvCustomersCustomer column.  We need to select the records which have their Customer field's value set to ‘Y’.

To get the row index for a given record index, we use the GetRowIndexByRecordIndex method of the view’s data controller.  Its first parameter specifies a record index and the second parameter specifies whether the record should be made visible if it is hidden under a collapsed group row.  We need to set the second parameter to True to ensure that the required record is visible thus enabling its selection.

You should use this code only when Grid Mode is not applied (the view’s DataController.DataModeController.GridMode property is set to False).  In Grid Mode, you will not be able to process all the 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);

  }

•	the SelectRows method of the view’s data controller

This method allows a continuous range of records to be selected.  Two parameters specify the starting and ending row indexes of the required range.

The next code selects rows 0-5 within the tvOrders view:

//Delphi

tvOrders.DataController.SelectRows(0, 5);

//C++ Builder

tvOrders->DataController->SelectRows(0, 5);

•	the SelectAll method of the view’s data controller

This method selects all the records, which are visible or potentially visible by scrolling, within a view.  Records hidden within collapsed group rows are not selected.

//Delphi

tvOrders.DataController.SelectAll;

//C++ Builder

tvOrders->DataController->SelectAll();


Focused/Selected Records

See Also

The focused record

All table and card views allow an end-user to navigate through the corresponding dataset's records (move focus from one record to another).  Only a single record can be focused within a view at a time.  In (banded) table views, you can focus both data rows and group rows.

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

•	the grid control works in Grid Mode

or

•	the view’s DataController.DataModeController.SyncMode property is set to True.

You can get/set the focused record via the view’s Controller.FocusedRecord property.  This property specifies an object of the TcxCustomGridRecord class which enables you to:

•	get the data provided by specific record fields (the Values property);

•	expand/collapse the row via the Expanded attribute (only for master and group rows in a (banded)table view);

•	select a record via the Selected property (if multi-selection is enabled; see below).

To change the focused record’s position via code, you can use the methods provided by a view’s controller and the data controller's methods:  GotoFirst, GotoLast, GotoNext and GotoPrev.

These methods let you move focus through the current view’s potentially visible data records and grouping rows (i.e. currently visible or available by scrolling).  They do not allow you to move focus to records hidden within a collapsed group.

Unlike the data controller’s methods, the controller’s GoToNext and GoToPrev methods enable you to move focus between master and detail views.

To move focus to data records (even to those that are hidden within collapsed groups) in bound mode, you can use the methods implemented by TDataSet descendants (First, Last, Next, Prior and MoveBy).

Records displayed within a view are indexed.  All data records are assigned record indexes defining the order of the records in a dataset.  All visible records (including group rows) are assigned indexes (in the data controller, they are called row indexes) and they define the order in which records are displayed on the screen.

The controller’s FocusedRecordIndex property specifies the index of the focused record.  You can also use this property to change the focused record.  The Controller.FocusedRecordIndex property is equivalent to the data controller’s FocusedRowIndex property.

Note: Do not confuse the view’s Controller.FocusedRecordIndex and DataController.FocusedRecordIndex properties.  The former specifies the row index of the focused record, i.e. the record’s visual position (this is equivalent to the Index property of the Controller.FocusedRecord object and to the TcxCustomDataController.FocusedRowIndex property).  The latter specifies the record index of the focused record, i.e. the position of the record in the data controller/dataset (this is equivalent to the RecordIndex property of the Controller.FocusedRecord object).

To move focus to a record hidden within a collapsed group, its index (row index) needs to be obtained by using the GetRowIndexByRecordIndex method.  It returns the visual position of the record based on its record index.  Then assign the obtained index to the Controller.FocusedRecordIndex property.

When a grid control loads all dataset records into memory (the GridMode property is set to False), the FocusedRecordIndex property manages the index of the focused record relative to the first view record.

In Grid Mode, only a fixed amount of records are loaded into a memory buffer at a time.  When scrolling causes a different set of records to be loaded into the buffer, record focus is automatically moved so that it remains on a buffered record (the FocusedRecord property always maintains a record within this buffer).  In Grid Mode, the FocusedRecordIndex property stores a record index relative to the first record of the current visible buffer.

Selected records

ExpressQuantumGrid allows you to select multiple records if the view’s OptionsSelection.MultiSelect property is set to True.  When this option is enabled an end-user can select records by clicking them while holding down the Ctrl and Shift keys.  The Ctrl key allows you to select/unselect individual records.  The Shift key can be used to select a continuous range of records.

To select/unselect an individual record programmatically, you can use:

•	the record’s Selected property

•	the view’s DataController.ChangeRowSelection method

Please refer to the Selecting Records topic for details.

If the OptionsSelection.MultiSelect property is set to False, only one record can be selected at a time.  In this case, the focused and selected records are equivalent.

When Grid Mode is not applied, you can use the view’s Controller.SelectedRecords property or the data controller’s GetSelectedRowIndex function to access all records currently selected one by one.

In Grid Mode, you should use the view’s DataController.GetSelectedBookmark function instead.

The data controller provides the ForEachRow method, which allows you to iterate through selected records in all loading modes.

The number of selected records is returned by the Controller.SelectedRecordCount property.  A grid control provides methods to clear the selection and delete the selected records.  These are found in the view’s Controller object:

•	the view’s Controller.ClearSelection method

•	the view’s Controller.DeleteSelection method.

Selected records within (banded) table views are marked by a small dot displayed in the indicator panel (set the view’s OptionsView.Indicator property to True to make it visible).  It is possible to specify a distinct style for selected records via the view’s Styles.Selection property.


Selecting Cells

See Also

This section deals with selecting cells programmatically.  Focused and selected records are discussed in the Focused/Selected Records and Selecting Records topics.

The view’s OptionsSelection.CellMultiSelect property allows you to select/deselect particular cells within the current (banded) table view’s record selection.  If this property is set to False, only entire record(s) (row(s) in a (banded) table view) can be selected.  Setting this property also affects the view’s OptionsSelection.MultiSelect property’s value.  The OptionsSelection.MultiSelect property’s value is automatically set to the value passed to the OptionsSelection.CellMultiSelect property. A column is called "selected" whenever it has at least one selected cell within the view’s record selection.

When the view’s OptionsSelection.CellMultiSelect property is set to True, the record selection can be adjusted according to your needs by including/excluding particular columns (i.e. their cells) from the selection.

The most obvious solution for selecting/deselecting a specific column’s cells within the record selection is to assign the corresponding value to the column’s Selected property as shown in the following code example.

//Delphi

tvFilms.Columns[0].Selected := True;

//C++ Builder

tvFilms->Columns[0]->Selected = true;

Note:	When the view’s OptionsSelection.CellMultiSelect property is set to True, the entire record selection can be easily performed by means of the Indicator (set the view’s OptionsView.Indicator property to True to make it visible).

If the view’s OptionsSelection.MultiSelect property is set to True, you are able to select multiple records at once.  When this option is enabled and an end-user clicks any record, it becomes focused and selected at the same time.  The focused record can be deselected by clicking it while pressing the Ctrl key.  The same works for cell selection also, except that the Ctrl key does not deselect the cell or all of the specific column’s cells.  Furthermore, when the view’s OptionsBehavior.PullFocusing property is set to True, the end-user can select records and cells by holding down the left mouse button and dragging the mouse pointer over the cells to be selected.  This automatically focuses the records and cells under the cursor and adds them to the selection.

To select/deselect multiple cells, you can use one of the following methods:

•	the Selected property of a column object as shown in the code example above.

•	The SelectColumns and SelectAllColumns methods of the view’s controller.

The SelectColumns method selects a set of sequential columns which are in the column range specified by the parameters passed to the method.  The following code example shows how to select the cells in the third, fourth and fifth columns, within the current record selection.  The selection will contain only these columns’ cells and all other columns outside of the column range will be automatically deselected.

//Delphi

with tableView do

  Controller.SelectColumns(Columns[3], Columns[5]);

//C++ Builder

tableView->Controller->SelectColumns(tableView->Columns[3], tableView->Columns[5]);

The SelectAllColumns method allows you to select the cells of all the columns within the current record selection, i.e. select all records.

•	the SelectCells method of the view’s controller.

Use this method to explicitly specify the cells that will be included in the selection which is designated by a column range and row range.  The row range specifies a continuous range of records to be selected, while the column range specifies the columns to be selected.  Two parameter pairs specify the starting and ending columns and row indexes of the required column and row ranges.

The following code selects rows 0-5 and columns 2-4 within the tableView view:

//Delphi

with tableView do

begin

  DataController.SelectRows(0, 5);

  Controller.SelectColumns(Columns[2], Columns[4]);

end;

//C++ Builder

tvOrders->DataController->SelectRows(0, 5);

tableView->Controller->SelectColumns(tableView->Columns[2], tableView->Columns[4]);

•	the SelectAllCells method of the view’s controller.

This method selects all the records and column cells, which are visible or potentially visible by scrolling, within a view.  Records hidden within collapsed group rows are not selected.

//Delphi

tableView.Controller.SelectAllCells;

//C++ Builder

tableView->Controller->SelectAllCells;

•	the ClearCellSelection method of the view’s controller.

Use this method to clear the current column (cell) selection within the view.  Calling this method does not affect the current view’s record selection.  Use the DataController.ClearSelection method instead.

To access the selected columns within the view, use the SelectedColumns method of the view’s controller.


Record Navigation

See Also

The GotoFirst, GotoLast, GotoNext and GotoPrev methods provided by a data controller allow you to navigate through visible rows in the order that they are displayed on screen.  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.  Rows hidden within collapsed data groups cannot be accessed by these methods.

Navigation methods (GoToFirst, GoToLast, GoToNext and GoToPrev) provided by the view’s controller work in a similar manner.  However, these also enable you to move focus between master and detail views.

To move focus between rows, you can change the focused row or its index explicitly.  See the Focused/Selected Records topic for more information.

Data record navigation is performed differently in provider/unbound and bound modes.

In provider/unbound and default bound modes, you can use record indexes to iterate through data records.  To make a data record focused and visible at the same time, you can assign its record index to the data controller’s FocusedRecordIndex property.  Record indexes can vary from 0 to RecordCount – 1.

Note: Do not confuse the view’s DataController.FocusedRecordIndex and Controller.FocusedRecordIndex properties.  The former specifies the record index of the focused record, i.e. the position of the record in the data controller (this is equivalent to the RecordIndex property of the Controller.FocusedRecord object).  The latter specifies the row index of the focused record, i.e. the record’s visual position (this is equivalent to the Index property of the Controller.FocusedRecord object and to the TcxCustomDataController.FocusedRowIndex property)

In Grid mode, you should use methods provided by the TDataSet descendant associated with the data controller to navigate records.

EQGrid provides the end user the ability to navigate records using an embedded data navigator control.  This allows moving focus to the first, last, next and previous row and to the next and previous page.

To activate the navigator, set the view’s OptionsView.Navigator property to True.


Incremental Search

ExpressQuantumGrid implements an incremental search functionality allowing a user to locate records in a grid control by matching the initial characters of a record field.

To search a record by a field value, focus on a record cell within the appropriate column and type the search text.  If a view contains a record with a value that starts with the search text, the record is focused.

The ‘mi’ characters are pressed.  As a result, the first ‘Mickey Alcorn’ record is located.	The ‘l’ character is pressed after ‘mi’ and the focus is moved to the ‘Mildred Johanson’ record

When the first record is located, you can continue searching.  To search forward and backward, press the Ctrl+DownArrow and Ctrl+UpArrow keys respectively.

By default, incremental search is disabled.  To enable the facility, set the view’s OptionsBehavior.IncSearch to True.  The item’s Options.IncSearch attribute controls whether incremental search can be applied to this item.

The TcxCustomGridTableController class, accessible via the view’s Controller property provides more functionality.  It allows you to start the incremental search by specifying the search text, continue and cancel the operation programmatically.

If a user is unable to focus cells within a view because of setting its OptionsSelection.CellSelect property to False, the search item can be specified explicitly using the view’s OptionsBehavior.IncSearchItem property.  Note that the property is not in effect if cell selection is enabled (OptionsSelection.CellSelect is True).


Data Export

ExpressQuantumGrid allows you to export data to a number of formats.  Currently HTML, XML, MS Excel and text formats are supported.

The HTML and XML formats are more complex since they can reflect most of grid features, such as styles, grouping and master-detail relationships.  The MS Excel format does not support master-details because of the rigid column arrangement.  When exporting to text format, only the data and its arrangement is exported.  As for the MS Excel format, text format does not support exporting detail views.

Four methods allow you to export data to these formats:

•	ExportGridToHTML

•	ExportGridToXML

•	ExportGridToExcel

•	ExportGridToText

In addition to the cxGridExportLink unit, where these methods are declared, you should include the cxExport module into the uses statement.


Data Printing

See Also

Sometimes a user may wish to print out data displayed by the ExpressQuantumGrid.  In order to print out the ExpressQuantumGrid, a user can export it to any available format: HTML, XML, XLS and TXT and then print as usually done for these formats.  However, these methods are not as convenient and comprehensive as you might wish, because they allow you only to print the current data display without customization being available.

The best way to print out the ExpressQuantumGrid is to use the ExpressPrinting System (must be purchased separately via devexpress.com).  This component introduces a GridReportLink, optimized for printing the ExpressQuantumGrid.  This report link publishes various sets of options controlling the appearance of the report displaying data from the ExpressQuantumGrid.  These options include:

•	the view elements’ visibility and position within the report - OptionsView and OptionsOnEveryPage;

•	whether the group or master rows are displayed expanded or collapsed – OptionsExpanding;

•	whether the detail views are printed, including the appropriate master and detail views - OptionsDetails;

•	processing of the selection when creating a report - OptionsSelection;

The GridReportLink component also implements a custom draw mechanism.  This is implemented by several events, corresponding to the drawing of particular areas of the report.  The TdxGridReportLink class publishes events that fire before drawing:

•	band headers - OnCustomDrawBandCell;

•	column headers - OnCustomDrawHeaderCell;

•	cell contents - OnCustomDrawCell;

•	footer panel - OnCustomDrawFooterCell.

Writing code in these event handlers allows you to control the report’s appearance.


Grid View Elements

See Also

Views

A grid control cannot represent data itself.  Data is represented by "Grid Views", while the grid control is a container for these "Grid Views".

For instance, the Card View (one of the four standard views of a grid control) enables you to arrange a database as a set of cards, each of which is a database record, while the Table View provides a standard tabular database representation (each database record corresponds to its table row).  To display data in a more logical manner, table columns can be arranged in bands with the help of the Banded Table View.  The Chart View allows you to visualize data using various diagrams which represent values in the form of data markers.

The Grid View is a structure representing a database in a convenient and user-friendly manner.

Each grid view consists of grid view elements.  They have different functionality:

•	Data representation (Cells, Data Markers)

•	Navigation (Indicator)

•	Data arrangement (Bands, Columns, Group By Box, Filter Panel, Card, Categories, Series)

•	Analysis and summary (Group and grid Footer Panels)

•	Description (Preview Section, Chart Legend)

A set of these grid view elements available is determined by the view’s type.

Note: one element, which is present in all views and is only available to you at design-time, is a view selector.  This element facilitates you to select a particular view in a form:

Table View and Banded Table View

The images below represent table view and banded table view layouts:

Table View

Banded Table View

These images show that Table Views and Banded Table Views have much in common.  The Banded Table View extends the data representation capabilities of the Table View with the help of the bands feature.

Card View

Unlike tabular Views, a Card View does not have analytical and summarizing facilities.  Its advantage is that database records are arranged in separate cards instead of table rows, as designed in tabular Views.

Chart View

Chart Views visually represent the data in a database by using various diagrams which present the data in the form of graphical shapes (also called data markers) so that values can easily be compared.

Pie diagrams have unique visual elements.

Chart Views provide the drill-down functionality that allows data to be grouped similar to tabular Views thus representing more or less detailed charts.

ViewInfos

Each grid view element has its own painter and is painted based on the settings relevant to the View’s type.  These settings are stored within the ViewInfo of a grid view element.  ViewInfo attributes provide much useful information about an element:

•	The Bounding Rectangle and other size and position parameters

•	Colors and fonts

•	Particular parameters of an element (such as the indicator type of the table view indicator).

ViewInfos can be used when you want to redraw a specific grid element completely.  For this purpose, every type of grid view element has custom draw implemented by the OnCustomDraw events (check the desired View reference for detailed information).

Every ViewInfo has a GetHitTest method which receives the X and Y coordinates of a point within a grid view and returns general identity information (called HitTest) on the grid view element which includes this point.  HitTests provide unique identifiers (called hit codes) which are associated with the grid view element that corresponds to a particular HitTest.

Please refer to the Understanding HitTests topic for basic information on HitTests and hit codes.


Understanding HitTests

See Also

HitTests are used to identify a grid view element by its position within a grid view.  Every grid view and ViewInfo has the GetHitTest method which receives the X and Y coordinates of a point within a grid view and returns the grid view element whose bounding rectangle includes this point.

HitTest class instances are used internally by the grid control infrastructure.  The HitTestCode method of a particular HitTest class instance returns the unique hit code of the grid view element which corresponds to this HitTest.  A developer can only use the HitTestCode method as the others are intended for internal use.

HitTests are especially useful when implementing responses to mouse actions such as movements, clicks and drag-and-drop operations.  To identify a particular grid view element which is located at the point being inspected, examine the hit code that is returned by the grid view’s ViewInfo for this point.  Then use the HitTest class which corresponds to the inspected grid view element to access the properties which are specific to this element.

Use the links below to get information on hit codes and HitTests classes of the grid view elements for specific views:

•	Table View

•	Banded Table View

•	Card View

•	Chart View

Note: one element, which is only available at design-time and present in all views, is a view selector.  This is a special element and it’s intended to facilitate you to select a particular view in a form.  A view selector is located at the top-left corner of a view.  The TcxGridDesignSelectorHitTest class is responsible for hit information on a view selector and its corresponding hit code is htDesignSelector:

The following code example implements the technique described above to hide bands and columns within the Banded Table View named btvCars when an end-user clicks on them using the right mouse button.  The btvCarsMouseDown procedure represents the Banded Table View’s OnMouseDown event handler.

//Delphi

procedure TForm1.btvCarsMouseDown(Sender: TObject;

  Button: TMouseButton; Shift: TShiftState; X, Y: Integer);

var

  AHitTest: TcxCustomGridHitTest;

begin

  if (Button = mbRight) and (Sender is TcxGridSite) then

  begin

    AHitTest := TcxGridSite(Sender).ViewInfo.GetHitTest(X, Y);

    case AHitTest.HitTestCode of

      htBandHeader:

        TcxGridBandHeaderHitTest(AHitTest).Band.Visible := False;

      htColumnHeader:

        TcxGridColumnHeaderHitTest(AHitTest).Column.Visible := False;

    end;

  end;

end;

//C++ Builder

void __fastcall TForm1::btvCarsMouseDown(TObject *Sender,

      TMouseButton Button, TShiftState Shift, int X, int Y)

{

  TcxGridSite *ASite;

  if ((Button == mbRight) && ((ASite = dynamic_cast<TcxGridSite *>(Sender)) != NULL)) {

    TcxCustomGridHitTest *AHitTest;

    AHitTest = ASite->ViewInfo->GetHitTest(X, Y);

    switch (AHitTest->HitTestCode(AHitTest->ClassType())) {

      case htBandHeader:

        dynamic_cast<TcxGridBandHeaderHitTest *>(AHitTest)->Band->Visible = False;

        break;

      case htColumnHeader:

        dynamic_cast<TcxGridColumnHeaderHitTest *>(AHitTest)->Column->Visible = False;

    }

  }

}


Table View HitTests

See Also

Table Views represent data in a tabular format where columns correspond to data fields while rows represent data records.  The following image shows the table view layout and hit codes of the corresponding table view elements.

The table below contains all the table view elements and their corresponding hit codes and HitTest classes.

Grid View Element	Hit Code	HitTest Class
Cell	htCell	TcxGridRecordCellHitTest
Close Filter Button	htFilterCloseButton	TcxGridFilterCloseButtonHitTest
Column Header	htColumnHeader	TcxGridColumnHeaderHitTest
Column Header Horizontal Sizing Edge	htColumnHeaderHorzSizingEdge	TcxGridColumnHeaderHorzSizingEdgeHitTest
Column Header Filter Dropdown Button	htColumnHeaderFilterButton	TcxGridColumnHeaderFilterButtonHitTest
Column Header Indicator	htIndicatorHeader	TcxGridIndicatorHeaderHitTest
Customization Form	htCustomizationForm	TcxGridCustomizationFormHitTest
Expand Button	htExpandButton	TcxGridExpandButtonHitTest
Filter Panel	htFilter	TcxGridFilterHitTest
Filter Activation Button	htFilterActivateButton	TcxGridFilterActivateButtonHitTest
Filter Customization Button	htFilterCustomizeButton	TcxGridFilterCustomizeButtonHitTest
Filter MRU List Button	htFilterDropDownButton	TcxGridFilterDropDownButtonHitTest
Footer Panel	htFooter	TcxGridFooterHitTest
Footer Cell	htFooterCell	TcxGridFooterCellHitTest
Group By Box	htGroupByBox	TcxGridGroupByBoxHitTest
Group Footer	htGroupFooter	TcxGridGroupFooterHitTest
Group Footer Cell	htGroupFooterCell	TcxGridGroupFooterCellHitTest
Group Summary	htGroupSummary	TcxGridGroupSummaryHitTest
Header	htHeader	TcxGridHeaderHitTest
Indicator	htIndicator	TcxGridIndicatorHitTest
Preview Section	htPreview	TcxGridPreviewHitTest
Record	htRecord	TcxGridRecordHitTest
Row Indicator	htRowIndicator	TcxGridRowIndicatorHitTest
Row Level Indent	htRowLevelIndent	TcxGridRowLevelIndentHitTest
Row Sizing Edge	htRowSizingEdge	TcxGridRowSizingEdgeHitTest
Tab	htTab	TcxGridDetailsSiteTabHitTest
View Navigator	htNavigator	TcxGridNavigatorHitTest


Banded Table View HitTests

See Also

Table Views and Banded Table Views have much in common.  The Banded Table View extends the data representation capabilities of the Table View with the help of the bands feature.  The following image demonstrates the banded table view layout and hit codes of the corresponding table view elements.

The table below contains all the banded table view elements (which are unique to Banded Table Views) and their corresponding hit codes and HitTest classes.

Grid View Element	Hit Code	HitTest Class
Band	htBand	TcxGridBandHitTest
Band Header	htBandHeader	TcxGridBandHeaderHitTest
Band Header Indicator	htIndicatorBandHeader	TcxGridIndicatorBandHeaderHitTest
Band Header Sizing Edge	htBandHeaderSizingEdge	TcxGridBandHeaderSizingEdgeHitTest
Column Header Vertical Sizing Edge	htColumnHeaderVertSizingEdge	TcxGridColumnHeaderVertSizingEdgeHitTest


Card View HitTests

See Also

Card Views arrange database records in separate cards instead of table rows, as designed in tabular Views.  The image below shows the card view layout and hit codes of the corresponding table view elements.

The table below contains all the card view elements (which are unique to Card Views) and their corresponding hit codes and HitTest classes.

Grid View Element	Hit Code	HitTest Class
Card Category Row Children Indent	htCardRowIndent	TcxGridCardRowIndentHitTest
Card Category Row Expand Button	htCardRowExpandButton	TcxGridCardRowExpandButtonHitTest
Card Row Caption	htRowCaption	TcxGridCardRowCaptionHitTest
Card Row Cell	htCell	TcxGridCardRowCellHitTest
Card Row Filter Dropdown Button	htRowFilterButton	TcxGridCardRowFilterButtonHitTest
Card Scroll Down Button	htCardScrollButtonDown	TcxGridCardScrollButtonDownHitTest
Card Scroll Up Button	htCardScrollButtonUp	TcxGridCardScrollButtonUpHitTest
Card Separator	htSeparator	TcxGridCardViewSeparatorHitTest


Chart View HitTests

See Also

Chart Views visually represent the data in a database by using various diagrams which present the data in the form of graphical shapes (also called data markers) so that values can easily be compared.

The table below contains all the chart view elements (which are unique to Chart Views) and their corresponding hit codes and HitTest classes.

Grid View Element	Hit Code	HitTest Class
Category Axis Title	htCategoryAxisTitle	TcxGridChartHistogramCategoryAxisTitleHitTest
Chart’s Plot Area	htPlot	TcxGridChartHistogramPlotHitTest
Chart Title	htChartTitle	TcxGridChartTitleHitTest
Chart Toolbox	htChartToolBox	TcxGridChartToolBoxHitTest
Chart Value	htChartValue	TcxGridChartValueHitTest
Chart Legend	htLegend	TcxGridChartLegendHitTest
Customization Button	htChartCustomizeButton	TcxGridChartCustomizeButtonHitTest
Data Level	htDataLevelInfo	TcxGridChartDataLevelInfoHitTest
Data Level’s Active Value	htDataLevelActiveValueInfo	TcxGridChartDataLevelActiveValueInfoHitTest
Diagram Selector	htDiagramSelector	TcxGridChartDiagramSelectorHitTest
Legend Item	htLegendItem	TcxGridChartLegendItemHitTest
Value Axis Title	htValueAxisTitle	TcxGridChartHistogramValueAxisTitleHitTest


Managing Grid Menus

Like every VCL control the ExpressQuantumGrid control supports popup menus.  But unlike a standard VCL control, the ExpressQuantumGrid control provides advanced popup menu support.  This includes:

•	Three built-in grid menus for column headers, a View’s footers or group footers, and group rows that are provided by the cxGridPopupMenu component.  These menus allow you to easily:

o	sort, group or align row and cell values;

o	show and hide grid columns;

o	customize column or group summaries at runtime.

•	An unlimited number of custom popup menus that can be attached to any grid element (cell, column, band etc.)

•	The ability to add custom menu items (both standard VCL menu items and menu items from the ExpressBars Suite) to built-in popup menus.

To add a menu item to a built-in popup menu, do the following:

1.	Define a menu operation associated with the menu item.

2.	Define a set of operations available for a particular grid element type and include the created menu operation into this operation set.

3.	Define a popup menu that provides the specified operation set.

4.	Register the popup menu.

The following code demonstrates how to add a menu item that toggles merging column cells to the built-in column header popup menu.

uses

  ..., cxGridStdPopupMenu, cxGridMenuOperations, cxGridHeaderPopupMenuItems, cxGridCustomPopupMenu, cxGridPopupMenu;

  // Represents a column header menu operation associated with the menu item.

  // To provide an image for the menu item override the GetImageResourceName

  // function to return the name of the image from a resource file.

  // To link a resource file use the {$R } compiler directive. Note that this

  // file should be in the search path.

  TcxGridCellMergingMenuOperation = class(TcxGridHeaderPopupMenuOperation)

  protected

    procedure Execute(Sender: TObject); override;

    function GetDown: Boolean; override;

    function GetEnabled: Boolean; override;

  public

    constructor Create; override;

  end;

  // Represents a column header menu operation set that extends the built-in

  // operation set with a new menu operation

  TcxGridNewHeaderPopupMenuOperations = class(TcxGridHeaderPopupMenuOperations)

  protected

    procedure AddItems; override;

  end;

  // Represents a popup menu that includes the created operation set

  TcxGridNewHeaderMenu = class(TcxGridStdHeaderMenu)

  protected

    function GetOperationsClass: TcxGridPopupMenuOperationsClass; override;

  end;

// ...

implementation

// ...

// ...

resourcestring

  cxCellMerging = 'Merged Cells';

// Toggles a column’s cell merging option when clicking the menu item

procedure TcxGridCellMergingMenuOperation.Execute(Sender: TObject);

begin

  inherited;

  HitColumn.Options.CellMerging := not HitColumn.Options.CellMerging;

end;

// Determines whether a check is displayed to indicate whether the cell

// merging option is in effect for the column

function TcxGridCellMergingMenuOperation.GetDown: Boolean;

begin

  Result := HitColumn.Options.CellMerging;

end;

// The menu item is always enabled

function TcxGridCellMergingMenuOperation.GetEnabled: Boolean;

begin

  Result := True;

end;

// Creates a menu item and specifies its caption

constructor TcxGridCellMergingMenuOperation.Create;

begin

  inherited Create;

  ResCaption := cxCellMerging;

end;

// A menu item associated with the menu operation is added as the last

// menu item

procedure TcxGridNewHeaderPopupMenuOperations.AddItems;

begin

  inherited AddItems;

  AddItem(TcxGridCellMergingMenuOperation).BeginGroup := True;

end;

// Specifies the operation set for the column header popup menu

function TcxGridNewHeaderMenu.GetOperationsClass: TcxGridPopupMenuOperationsClass;

begin

  Result := TcxGridNewHeaderPopupMenuOperations;

end;

// ...

initialization

// ...

// Registers the column header popup menu

  RegisterPopupMenuClass(TcxGridNewHeaderMenu, [gvhtColumnHeader], TcxGridTableView);

Note:	Execute the RegisterPopupMenuClass method in the initialization section of the unit to guarantee that your popup menu is always registered.


Implementing Drag-And-Drop Functionality

Drag-and-drop allows end-users to drag one control (or its items) onto another control within the same application.  EQGrid supports drag-and-drop for grid records and root level tabs.  You can implement drag-and-drop to drag:

•	objects (list boxes, tree views, grid controls, etc.) and their items onto a grid view or a root level tab

•	grid records onto another control or within the same view

•	root level tabs onto another control

Root level tabs enable you to switch between root levels used to display data from non-related datasets.  Refer to the Data Representation section for more information.  The following image shows three root level tabs (Items, Projects and Users).

Options affecting drag-and-drop operations involving root level tabs are published in the TcxGrid class.  For instance, when you need to respond to dragging over a root level tab or dropping onto it, use the grid’s OnDragOver and OnDragDrop events respectively.  Conversely, options affecting drag-and-drop within a view are declared in the base view class (TcxCustomGridView).

To implement drag-and-drop from a source control to a target control, you need to:

•	Enable a user to start the operation within the source control

The manner in which drag & drop operations are initiated depends on the DragMode property value of the control to be dragged.  If this property value is dmAutomatic, dragging in initiated automatically as soon as the end-user presses the mouse button.  If the DragMode property is set to dmManual, you have to call the control’s BeginDrag method to start dragging.

•	Handle the target control’s OnDragOver event to accept or reject dragged items

•	Handle the target control’s OnDragDrop event to respond to the dropping of items within the control

A Dragged Object

A dragged object is the currently focused object at the time a drag-and-drop operation is initiated.  The dragged object is passed as a parameter to the OnDragOver and OnDragDrop events of the target control (the control hovered over and where the object is dropped).

When a drag-and-drop operation starts within EQGrid, an object of the TcxDragControlObject class is created.  Its Control property refers to the control about to be dragged.

If you start drag-and-drop by clicking on a root level tab of your grid control, the drag object will refer to the grid itself.

If drag-and-drop is initiated within cells of a grid view, the drag object will refer to the grid site containing this view.  Grid views are not controls; therefore they cannot start drag-and-drop.  When a user clicks within a view, the click on the grid is handled by the site control (a TcxGridSite object), containing the view.  You can obtain the view displayed by the site via its GridView property.

Starting Drag-And-Drop

The DragMode property published in the TcxGrid class affects the start of drag-and-drop within root level tabs.  The DragMode property declared in the TcxCustomGridView class affects the start of drag-and-drop within grid views.

Automatic start of drag-and-drop does not require any code.  Set the DragMode property to dmAutomatic to initiate the operation when a user clicks within the control and moves the mouse holding the key down.  However, you cannot control the initial point of the drag-and-drop operation in this mode.

If DragMode is set to dmManual, you need to start the drag-and-drop operation manually by handling mouse-down events.  A manual start of the operation allows you to control the initial point of drag-and-drop (for instance, when clicking within specific items, records, etc).  To drag a control manually, call the control’s BeginDrag method.  BeginDrag has a Boolean parameter called Immediate and, optionally, an integer parameter called Threshold.  If the Immediate parameter is set to True, the BeginDrag method initiates drag-and-drop from the current mouse position.  If it is set to False, dragging begins after the user moves the mouse the number of pixels specified by the Threshold parameter.  If Threshold is set to a value less than 0 (such as the default value for this parameter), BeginDrag uses the DragThreshold property of the global Mouse variable.

In order to start drag-and-drop manually for a grid view, you need to call the BeginDrag method of its grid site.

Accepting/Rejecting the Dragged Object

To accept or reject the dragged object, you should use the OnDragOver event of the target control.  When you intend to allow dragging over a grid view and dropping onto it, use its OnDragOver event.  The object being dragged is specified by the Source parameter.  If the source of the operation is a grid view, the Source parameter represents a TcxDragControlObject instance, whose Control property refers to the grid site containing the view.  You can test it to decide whether subsequent dropping is allowed.

Dropping items

Use the OnDragDrop event of the target control (or the target grid view) to respond to dropping the dragged object within the control.  This event is generated only if the dragged object was accepted in your OnDragOver event handler.  In the OnDragDrop event handler, you need to get the source control, which initiated the drag-and-drop operation and then perform specific actions using data from this source control.

Properties relating to drag-and-drop

EQGrid provides a number of options relating to drag-and-drop operations when dragging over grid views. These options can be accessed via a view’s OptionsBehavior object:

•	DragFocusing specifies whether focus is moved to the target record when dragging/dropping over the current view

•	DragHighlighting specifies whether the target record is highlighted when you perform drag-and-drop over the view

•	DragOpening forces master and group rows and detail level tabs to expand during drag-and-drop.  To expand root level tabs during drag-and-drop, use the grid’s DragOpening property.

•	DragScrolling specifies whether the view is scrolled automatically when dragging an object to the top, left, bottom or right view edges

Example

The following is an example of implementing drag-and-drop from a grid control onto a TMemo component.

When the end-user drags root grid level tabs onto the memo, it displays the hierarchical structure of child levels and views owned by the clicked root level in the following form:

<RootGridLevel Caption="Projects" View="tvProjects">

  <GridLevel Caption="" View="tvTeam"/>

</RootGridLevel>

When dragging grid records onto the memo, the latter displays information on the currently selected records (if the view’s OptionsSelection.MultiSelect property is set to True) or the focused record (if multi-selection is disabled).

For instance, the following text describes the values of three records from the tvItems view.  The values are quoted and preceded by the corresponding field names:

<GridLevel Caption="Items" View="tvItems">

  <Record NAME="Screen Redraw" TYPE="Bug" PROJECTID="Small-Business Accounting System" PRIORITY="Normal" STATUS="New" CREATORID="Dave Murrel" />

  <Record NAME="Faxing" TYPE="Bug" PROJECTID="Small-Business Accounting System" PRIORITY="Low" STATUS="New" CREATORID="Dave Murrel" />

  <Record NAME="Data Export" TYPE="Bug" PROJECTID="Small-Business Accounting System" PRIORITY="Normal" STATUS="Fixed" CREATORID="Ray Shipman" />

</GridLevel>

The following steps describe how to apply drag-and-drop functionality to the ColumnsShareDemo shipped with EQGrid.

1.	Open the ColumnsShareDemo and place a TMemo component onto the main form.

2.	Set the properties of the memo control to the following values:

•	Align to alRight

This keeps the memo on the right edge of the form.  You are now able to specify its width by dragging the control’s left margin.

•	WordWrap to False to prevent text wrapping at the right edge of the memo.

•	Scrollbars to ssBoth to enable horizontal and vertical scrollbars.

3.	For the grid control in the main form, set its DragMode property value to dmAutomatic.

4.	For the tvProjects, tvTeam and cvUsers views, enable automatic start of drag-and-drop by setting their DragMode properties to dmAutomatic.

5.	For the tvItems view, we will implement manual start of drag-and-drop for demonstrative purposes.  The DragMode property of the view must be set to dmManual (the default value).

Write an OnMouseDown event handler for the view as follows.  This code initiates drag-and-drop after a user clicks any record within a view and drags the mouse pointer a particular number of pixels (by default, 5):

//Delphi

procedure TColumnsShareDemoMainForm.tvItemsMouseDown(Sender: TObject;

  Button: TMouseButton; Shift: TShiftState; X, Y: Integer);

begin

//Start drag-and-drop only if the user clicks a grid record

  with TcxGridSite(Sender) do

  begin

    if ViewInfo.GetHitTest(X, Y).HitTestCode = htRecord then

      BeginDrag(False);

  end;

end;

//C++ Builder

void __fastcall TColumnsShareDemoMainForm::tvItemsMouseDown( TObject *Sender, TMouseButton Button, TShiftState Shift, int X, int Y) {

  //Start drag-and-drop only if the user clicks a grid record

  TcxGridSite * ASite = (TcxGridSite *)Sender;

  TcxCustomGridHitTest * ht = ASite->ViewInfo->GetHitTest(X, Y);

  if(ht->HitTestCode(ht->ClassType()) == htRecord)

    ASite->BeginDrag(false);

}

6.	Enable the multi-selection feature for the tvItems view by setting its OptionsSelection.MultiSelect property to True.

7.	Write an OnDragOver event handler for the memo as follows:

//Delphi

procedure TColumnsShareDemoMainForm.Memo1DragOver(Sender, Source: TObject;

  X, Y: Integer; State: TDragState; var Accept: Boolean);

begin

  if Source is TcxDragControlObject then

    with TcxDragControlObject(Source) do

      if (Control is TcxGridSite) or (Control is TcxGrid) then

          Accept := True;

end;

//C++ Builder

void __fastcall TColumnsShareDemoMainForm::Memo1DragOver(TObject *Sender, TObject *Source, int X, int Y, TDragState State, bool &Accept) {

  TcxDragControlObject * AObject;

  if (AObject = dynamic_cast<TcxDragControlObject *>(Source))

    if (dynamic_cast<TcxGridSite *>(AObject->Control) ||
        dynamic_cast<TcxGrid *>(AObject->Control))

      Accept = true;

}

This accepts the dragged object if the source of the operation is a grid control or a grid site.  If the source of the drag-and-drop operation is another control, the dragged object is rejected (the Accept parameter is False by default).

8.	Handle the OnDragDrop event for the memo and write it as follows:

The code ensures that the dragged object is a grid site or a grid control.  Then it performs different actions depending on the object type.  The GetSelectedRecordsInfo and GetGridInfo procedures used in the event handler will be defined in the next step.

//Delphi

procedure TColumnsShareDemoMainForm.Memo1DragDrop(Sender, Source: TObject;

  X, Y: Integer);

var

  AControl: TControl;

begin

  AControl := TDragControlObject(Source).Control;

  if AControl is TcxGridSite then

    GetSelectedRecordsInfo(TcxCustomGridTableView
      (TcxGridSite(AControl).GridView))

  else

    if AControl is TcxGrid then

      GetGridInfo(TcxGrid(AControl));

end;

//C++ Builder

void __fastcall TColumnsShareDemoMainForm::Memo1DragDrop
(TObject *Sender, TObject *Source, int X, int Y) {

  TControl * AControl = ((TDragControlObject*)Source)->Control;

  if (TcxGridSite * ASite = dynamic_cast<TcxGridSite*>
    (AControl))

    GetSelectedRecordsInfo((TcxCustomGridTableView*)
      ASite->GridView);  else

    if (TcxGrid * AGrid = dynamic_cast<TcxGrid*>(AControl))

      GetGridInfo(AGrid);

}

9.	Add four methods to the declaration of your TColumnsShareDemoMainForm class to obtain the information from the dropped grid and represent it in the desired form as described above:

//Delphi

TColumnsShareDemoMainForm = class(TForm)

  //...

  public

    procedure GetSelectedRecordsInfo(ASourceView: TcxCustomGridTableView);

    procedure GetGridInfo(ASourceGrid: TcxGrid);

    function GetRecordInfo(ARecord: TcxCustomGridRecord): string;

    function GetLevelInfo(ALevel: TcxGridLevel; APrefix, APostFix: string): string;

  end;

//C++ Builder

class TColumnsShareDemoMainForm : public TForm {

  //...

public:

  //...

  void GetSelectedRecordsInfo(TcxCustomGridTableView * ASourceView);

  void GetGridInfo(TcxGrid * ASourceGrid);

  String GetRecordInfo(TcxCustomGridRecord * ARecord);

  String GetLevelInfo(TcxGridLevel * ALevel, String APrefix, String APostFix);

};

GetSelectedRecordsInfo obtains data from selected or focused records from the source view.  This view is passed as the ASourceView parameter.  This code assumes that Grid Mode is not applied.  In this case, selected records can be obtained via the view’s Controller.SelectedRecords property.  The focused record is specified by the view’s Controller.FocusedRecord property.  Refer to the Focused/Selected Records section for more details.

//Delphi

procedure TColumnsShareDemoMainForm.GetSelectedRecordsInfo(

  ASourceView: TcxCustomGridTableView);

var

  AList: TStringList;

  I: Integer;

begin

  Memo1.Clear;

  AList := TStringList.Create;

  with AList do

  begin

    Add(GetLevelInfo(TcxGridLevel(ASourceView.Level), '<GridLevel', '>'));

    if ASourceView.OptionsSelection.MultiSelect then

      for I := 0 to ASourceView.Controller.SelectedRecordCount - 1 do

        Add('  ' + GetRecordInfo(
          ASourceView.Controller.SelectedRecords[I]))

    else

      Add('  ' + GetRecordInfo(
        ASourceView.Controller.FocusedRecord));

    Add('</GridLevel>');

  end;

  Memo1.Lines.Add(AList.Text);

  AList.Free;

end;

//C++ Builder

void TColumnsShareDemoMainForm::GetSelectedRecordsInfo
(TcxCustomGridTableView * ASourceView) {

  TStringList * AList = new TStringList();

  int i;

  Memo1->Clear();

  AList->Add(GetLevelInfo((TcxGridLevel*)ASourceView->Level,
    "<GridLevel", ">"));

  if (ASourceView->OptionsSelection->MultiSelect)

    for (i = 0; i < ASourceView->Controller->
      SelectedRecordCount; i++)

      AList->Add("  " + GetRecordInfo(        ASourceView->Controller->SelectedRecords[i]));

  else

    AList->Add("  " + GetRecordInfo(      ASourceView->Controller->FocusedRecord));

  AList->Add("</GridLevel>");

  Memo1->Lines->Add(AList->Text);

  delete AList;

}

GetRecordInfo retrieves values from a record as a formatted string in the following format:

<Record NAME="Small-Business Accounting System" MANAGERID="Dave Murrel" />

where NAME and MANAGERID are item names (or field names for data-aware items).

Item values are obtained from the record’s DisplayTexts property and are presented as quoted strings.

//Delphi

function TColumnsShareDemoMainForm.GetRecordInfo(

  ARecord: TcxCustomGridRecord): string;

var

  I: Integer;

  AItem: TcxCustomGridTableItem;

  AItemName: string;

begin

    if ARecord is TcxGridGroupRow then

    begin

      Result := '';

      Exit;

    end;

    Result := '<Record ';

    for I := 0 to ARecord.ValueCount - 1 do

    begin

      AItem := ARecord.GridView.Items[I];

      if AItem.DataBinding is TcxGridItemDBDataBinding then

        AItemName := TcxGridItemDBDataBinding(AItem.DataBinding).FieldName

      else

        AItemName := AItem.Name;

      Result := Result + AItemName +  '="' + ARecord.DisplayTexts[I] + '" ';

    end;

    Result := Result + '/>';

end;

//C++ Builder

String TColumnsShareDemoMainForm::GetRecordInfo
(TcxCustomGridRecord * ARecord) {

  if (dynamic_cast<TcxGridGroupRow *>(ARecord)) {

    return "";

  }

  int i;

  TcxCustomGridTableItem * AItem;

  String AItemName, Result;

  Result = "<Record ";

  for (i = 0; i < ARecord->ValueCount; i++) {

    AItem = ARecord->GridView->Items[i];

    if (TcxGridItemDBDataBinding * DB =
      dynamic_cast<TcxGridItemDBDataBinding*>
        (AItem->DataBinding))

      AItemName = DB->FieldName;

    else

      AItemName = AItem->Name;

    Result += AItemName +  "=\"" + ARecord->DisplayTexts[i] + "\" ";

  }

  Result += "/>";

  return Result;

}

GetGridInfo displays information on child levels and views of the active root grid level within the memo.  It navigates through all child levels and every level found is processed by the GetLevelInfo function.

The GetGridInfo function has the ASourceGrid parameter providing access to the source grid control.  The grid’s ActiveLevel property determines the root level the end-user has clicked.

//Delphi

procedure TColumnsShareDemoMainForm.GetGridInfo(ASourceGrid: TcxGrid);

var

  AList: TStringList;

  ACurrentLevel, ARootLevel: TcxGridLevel;

  AIndent : string;

  AChildIndex: Integer;

begin

  AList := TStringList.Create;

  AIndent := '';

  ARootLevel := ASourceGrid.ActiveLevel;

  ACurrentLevel := ARootLevel;

  AList.Add(AIndent + GetLevelInfo(ACurrentLevel, '<RootGridLevel', '>'));

  AChildIndex := -1;

  if ACurrentLevel.Count > 0 then

    repeat

      if AChildIndex < ACurrentLevel.Count - 1 then

      begin

        ACurrentLevel := ACurrentLevel.Items[AChildIndex + 1];

        AIndent := AIndent + '  ';

        AList.Add(AIndent + GetLevelInfo(ACurrentLevel, '<GridLevel', '/>'));

        AChildIndex := -1;

      end

      else

       begin

        AChildIndex := ACurrentLevel.Index;

        ACurrentLevel := ACurrentLevel.Parent;

        SetLength(AIndent, Length(AIndent) - 2);

       end;

    until (ACurrentLevel =ARootLevel) and (AChildIndex = ACurrentLevel.Count - 1);

  AList.Add(AIndent + '</RootGridLevel>');

  Memo1.Clear;

  Memo1.Lines.Add(AList.Text);

  AList.Free;

end;

//C++ Builder

void TColumnsShareDemoMainForm::GetGridInfo(TcxGrid * ASourceGrid) {

  String AIndent = "";

  TStringList * AList = new TStringList();

  TcxGridLevel * ARootLevel = ASourceGrid->ActiveLevel;

  TcxGridLevel * ACurrentLevel = ARootLevel;

  int AChildIndex = -1;

  AList->Add(AIndent + GetLevelInfo(ACurrentLevel, "<RootGridLevel", ">"));

  if (ACurrentLevel->Count > 0)

    do {

      if (AChildIndex < ACurrentLevel->Count - 1) {

        ACurrentLevel = ACurrentLevel->Items[AChildIndex + 1];

        AIndent = AIndent + "  ";

        AList->Add(AIndent +
          GetLevelInfo(ACurrentLevel, "<GridLevel", "/>"));

        AChildIndex = -1;

      }

      else {

        AChildIndex = ACurrentLevel->Index;

        ACurrentLevel = ACurrentLevel->Parent;

        AIndent.SetLength(AIndent.Length() - 2);

      }

    }while (!((ACurrentLevel == ARootLevel) && (AChildIndex == ACurrentLevel->Count - 1)));

  AList->Add(AIndent + "</RootGridLevel>");

  Memo1->Clear();

  Memo1->Lines->Add(AList->Text);

  delete AList;

}

The GetLevelInfo method is used to retrieve information for a given level.  It returns the Caption of the level and the view assigned, if any, in the following format:

<RootGridLevel Caption="Projects" View="tvProjects">

or

<GridLevel Caption="" View="tvTeam"/>

where ‘<RootGridLevel’ and ‘<GridLevel’ are passed as function parameters.

//Delphi

function TColumnsShareDemoMainForm.GetLevelInfo(ALevel: TcxGridLevel;

  APrefix, APostFix: string): string;

begin

  Result := APrefix + ' ';

  Result := Result + 'Caption="' + ALevel.Caption + '" ';

  if Assigned(ALevel.GridView) then

    Result := Result + 'View="' + ALevel.GridView.PatternGridView.Name + '"'

  else

    Result := Result + 'View="NIL"';

  Result := Result + APostfix;

end;

//C++ Builder

String TColumnsShareDemoMainForm::GetLevelInfo(TcxGridLevel * ALevel, String APrefix, String APostfix) {

  String Result = APrefix + " ";

  Result += "Caption=\"" + ALevel->Caption + "\" ";

  if (ALevel->GridView)

    Result += "View=\"" +
      ALevel->GridView->PatternGridView->Name + "\"";

  else

    Result += "View=\"NIL\"";

  Result += APostfix;

  return Result;

}

10.	Add the cxGridDBDataDefinitions and cxGridViewData modules to the uses section of the unit.

11.	Run the program.

Multi-select functionality is enabled for the tvItems view.  Select several records within the view and drag them onto the memo control.

After dropping the records, the memo will display record values as a list:

Dragging the Projects tab onto the memo displays child levels and the views associated with the corresponding root view (the tvProjects view).

There is only one detail (tvTeam) bound to the tvProjects view, which is displayed in the following image:

You can drag other root tabs (Items and Users) and records from other views onto the memo control.  This will display the appropriate information on details and records in a similar manner.


Data Representation

See Also

The ExpressQuantumGrid is capable of displaying data from several datasets.  Hierarchical data structures (such as master-detail relationships) within the ExpressQuantumGrid are implemented via grid levels.

A grid level is an object representing a specific data nesting level.  Each level is represented visually via the view assigned to that level.  Note that level objects only implement logical data structures, so levels are invisible without assigned views.

Master-detail data representation requires the presence of two levels (master view and detail view) that are connected to the datasets and linked by field values (see the Master-Detail topic for details).   Each time a master row gets expanded, the corresponding record(s) in the detail data set is displayed.  The detail view displaying those corresponding record(s) is called a "clone" view.  All "clone" views copy their settings from one view, which is controlled by the detail hierarchy level.  This view is called a "pattern" view and represents a template for all the detail views used in the relationship.

"Pattern" views are not displayed at runtime, they only provide settings for creating "clone" views.  However, each "clone" view may have individual settings, differing from the "pattern" view's settings.  This may happen if the "pattern" view has its Synchronization property set to False and its settings have been changed after the "clone" view was displayed on the screen.  In order to recreate "clone" views with the new "pattern" view's settings, call the DataController.ClearDetails.  To keep all "clone" views automatically synchronized with the "pattern" view, set the detail view’s Synchronization property to True.

A TcxGridLevel instance represents the specific grid level that owns the collection of dependant grid levels (GridLevel.Items).  Each grid level from this collection also has a child levels collection.  Thus, you can build unlimited tree-type data dependency structures using the ExpressQuantumGrid.

Grid levels (and thus their views) can be located at the same data nesting or at dependant hierarchy levels.  If several grid levels (views) are located at the same hierarchy level, navigation through them is implemented via the level tabs.

In order to enable tabs at the root nesting level, use the grid’s RootLevelOptions.DetailTabsPosition property.  The level’s Options.DetailTabsPosition property lets you specify the tab position of detail views.  Also, you need to set the Level.Caption property to identify the required level from amongst the other levels, otherwise its tab will be blank.


Working With Details At Runtime

The ExpressQuantumGrid is capable of displaying data in a hierarchical master-detail relationship (see the Data Representation and Master-Detail topics in this help system for more information).  Each visual nesting level is represented by a grid level with an associated view.

Every time a master row gets expanded the corresponding detail view is displayed.  This view is constructed based on the settings of the "pattern" view and the appropriate portion of the detail data set.  Such detail views are called "clones" and can be accessed individually by the View.Clones property.  Each "clone" is an instance of a "pattern" view class.  This allows a developer the ability to give each "clone" view different settings dynamically.  Settings that can be customized include:

•	Columns retrieved from a data set;

•	Column positions;

•	Grouping;

•	Filtering;

•	Sorting;

•	Summary calculations.

A convenient way to customize these settings is by using the TcxGridPopupMenu component.  It provides a set of menus that appear when an end-user right-clicks within a column header, View’s footer, group footer or group row.

If you want to synchronize all the opened detail views with the "pattern" view settings, call the DataController.ClearDetails method.  It destroys all the displayed detail views and recreates them with the "pattern" settings.  A convenient way to keep all "clone" views automatically synchronized with the "pattern" view is to set the detail view’s Synchronization property to True.


Master-Detail

See Also

ExpressQuantumGrid is capable of displaying data from several datasets.  You can present data either from independent datasets in one control or datasets that are linked by a master-detail relationship.  One-to-many relationships or master-detail relationships can be represented in one of two ways.  The first method is to use two grid controls.  A detail grid control displays only the records corresponding to the current record in a master table.  In the second method only one grid control is used to present master-detail relationships.  This method is specific to the ExpressQuantumGrid and employs grid levels to create a hierarchical data structure.

You can see, for instance, the MasterDetailTableDemo for a complete example of implementing a master-detail relationship.  This topic describes the basic principles involved in setting up master-detail relationships based on the database used in this demo.

Data in this example is loaded using the default loading mode (when Grid Mode is not applied).  Grid mode is a special loading mode provided where there are a large number of records.  The Grid Mode: Master-Detail section shows how to create a master-detail relationship between tables in grid mode.

EQGrid allows you to populate views with data from non data-aware sources using provider and unbound modes.  Refer to the Provider Mode: Master-Detail and Unbound Mode: Master-Detail sections to see how to set up master-detail relationships in these modes.

Database structure

Let us consider two tables that are shipped with the EQGrid demos: FILMS and FILMSPERSONSSTAFF.  The FILMS table contains information on the films in the catalog and contains fields such as CAPTION, YEAR, PHOTO, TAGLINE, ID and others.  ID is the table key field name.

The FILMSPERSONSSTAFF table describes people involved in film production.  It also has an ID field uniquely identifying records in the table.  Other fields are PERSONID, PERSONLINEID, DESCRIPTION and FILMID.  FILMID denotes a value of the ID field from the FILMS table.  It associates each record in the FILMSPERSONSSTAFF table with a specific film from the FILMS table.  Thus a master-detail relationship can be established between these tables in which FILMS is a master table and FILMSPERSONSSTAFF is a detail table.

Creating connections to tables

The Connecting to Data topic outlines the steps required to connect a grid control to a database.  It involves:

•	creating TDataSet and TDataSource objects for all data tables in the project

•	linking TDataSet to a database table

•	linking TDataSource to the TDataSet

Other steps relate to adjusting the grid's properties and will be discussed below.

We have created a table (dataset) and datasource objects for the FILMS table: tblFilms and dsFilms.  The dataset and data source for the FILMSPERSONSSTAFF table are tblFilmsPersonsStaff and dsFilmsPersonsStaff, respectively.

Creating the data structure

To display a master-detail relationship, you need to have at least two grid levels with associated DB views (one for a master table and the other for its detail table).  Views must be connected to data sources identifying master and detail tables respectively.  Please refer to the Working With Levels topic to learn more about creating a data structure within a grid control.  The following grid levels (TcxGridLevel) and views (TcxGridDBTableView) were created to represent the FILMS and FILMSPERSONSSTAFF tables:

•	The lvFilms level is linked to the tvFilms view connected to the dsFilms data source.

•	The lvFilmsPersonsStaff level is a child level of lvFilms.  It is associated with the tvFilmsPersonsStaff view connected to the dsFilmsPersonsStaff data source.

The following image shows the Structure Navigator with the levels and views created:

Also, you have to link views to corresponding TDataSource objects and add columns within these views to display the data in the tables.  See Connecting to Data and Create And Delete Columns for more details.

Setting up a master-detail relationship

To link the tables’ data, you need to set the DetailKeyFieldNames and MasterKeyFieldNames properties of the detail view’s data controller.

•	Set MasterKeyFieldNames of the detail view’s data controller to ID.  It identifies the field from a master table (FILMS).

•	Set DetailKeyFieldNames to FILMID.  FILMID specifies the field in the current detail table (FILMSPERSONSSTAFF).  It corresponds to the field(s) set via MasterKeyFieldNames.

•	Set KeyFieldNames to ID.  The KeyFieldNames property specifies one or more key field names to identify each dataset record uniquely.  This is not required for the actual master-detail relationship, but it is necessary for some operations to work, such as editing detail view data, deleting records, etc.

At design time, select the tvFilmsPersonsStaff view so that the Object Inspector displays its properties and then expand the DataController property.  The following image shows the Object Inspector with MasterKeyFieldNames, DetailKeyFieldNames and KeyFieldNames set to values as described above:

The following code performs the same operations:

//Delphi

  tvFilmsPersonsStaff.DataController.KeyFieldNames := 'ID';

  tvFilmsPersonsStaff.DataController.MasterKeyFieldNames := 'ID';

  tvFilmsPersonsStaff.DataController.DetailKeyFieldNames := 'FILMID';

//C++ Builder

  tvFilmsPersonsStaff->DataController->KeyFieldNames = "ID";

  tvFilmsPersonsStaff->DataController->MasterKeyFieldNames = "ID";

  tvFilmsPersonsStaff->DataController->DetailKeyFieldNames = "FILMID";

Sorting the detail dataset

The last step of setting up a master-detail relationship is to sort the detail dataset (for parameterized queries this is not necessary).  Providing that the detail dataset is sorted, the data controller will correctly retrieve all the necessary records from it.  The detail dataset must be sorted against the fields specified by the DetailKeyFieldNames property.

To enable sorting for query datasets, you should use the "ORDER BY" SQL command.  For TTable and TCustomADODataSet components, the sorting of dataset records is implemented via the IndexFieldNames property.  In this example, we need to set the IndexFieldNames property of the dsFilmsPersonsStaff dataset to FILMID (the same value as for the tvFilmsPersonsStaff.DataController.DetailKeyFieldNames property).

//Delphi

dsFilmsPersonsStaff.IndexFieldNames := 'FILMID';

//C++ Builder

dsFilmsPersonsStaff->IndexFieldNames = "FILMID";

The grid below demonstrates two tables linked by the ID & FILMID fields:


Working with Levels

See Also

Levels in the ExpressQuantumGrid are used to set up the data structure.  Each level is associated with a view representing data in a specific form (for instance, a table view or card view).

The Structure Navigator and Component Editor allow you to

•	create and delete levels;

•	create and delete views and associate them with levels;

•	create columns within views (or rows in card views) manually or by retrieving the fields from a linked data source.

When selecting a level or a view in the Structure Navigator or the Component Editor, its properties are automatically displayed in the Object Inspector.  You can also click the level’s tab in a grid to quickly select this level.

Root Levels

A grid control enables you to display data from several independent data sources.  It provides the Levels property, which maintains a collection of grid levels at the root nesting level.

By default a grid control contains a single root grid level when created.  At design time, you can use the Structure Navigator to add root grid levels.  Right-click the grid label and select the Add Level option

or via code:

//Delphi

var

  ARootLevel: TcxGridLevel;

//...

  ARootLevel := cxGrid1.Levels.Add;

//C++ Builder

  TcxGridLevel *ARootLevel;

  ARootLevel = cxGrid1->Levels->Add();

After adding a root level at design time, the Structure Navigator looks like:

The first root grid level is addressed by Levels[0], the second – by Levels[1] and so on.  Each level may contain child levels.  This allows you to create master-detail relationships.

Child Levels

Child (or detail) levels are used to present master-detail relationships between master and detail tables.  To add a child to a specific level at design time, right-click its label in the Structure Navigator and select the Add Level option.

or write code as follows:

//Delphi

var

  AChildLevel: TcxGridLevel;

//...

  AChildLevel := cxGrid1.Levels[0].Add;

//C++ Builder

  TcxGridLevel *AChildLevel;

  AChildLevel = cxGrid1->Levels[0]->Add();

At design time you will see the result:

To add another child level, just repeat the operation.

The Master-Detail topic describes the changes that need to be made to the view's properties to set up a master-detail relationship between tables.

Associate a Level with a View

To display data, a level must be associated with a view via the TcxGridLevel.GridView property.  You can assign one of the existing views or create a new view.

To create a new view and assign it to a level at design time, you can right-click its label and select the Create View option.  It will invoke the list of views:

You can create a view without assigning it to a level via the Component Editor.  Activate the Component Editor and switch to the Views panel.  Then press the Add View button and select the type of view you want to add.

To assign an existing View to a level, right-click the level to invoke its context menu and select the required View from a list of the existing Views:

Alternatively, you can select a level, open the Object Inspector to see the level’s properties and set its GridView property:

Use the following code to create a view at runtime and assign it to a level.  You should call the CreateView method, passing a view class as a parameter, and this will add a new view to the grid’s Views collection.

//Delphi

var

  AView: TcxGridDBTableView;

//...

  AView := TcxGridDBTableView(cxGrid1.CreateView(TcxGridDBTableView));

  cxGrid1Level2.GridView := AView;

//C++ Builder

  TcxGridDBTableView *AView;

  AView = (TcxGridDBTableView *)cxGrid1->CreateView (__classid(TcxGridDBTableView));

  cxGrid1Level2->GridView = AView;

After assigning a view to a level at design time, the Structure Navigator looks like:

Switching Between Levels At The Same Hierarchy Level

By default, a grid control does not allow a user to switch between levels placed at the same nesting level.  However, you can enable internal tabbed pages for this purpose.  To allow tabs to be displayed at the root nesting level, use the grid’s RootLevelOptions.DetailTabsPosition property.  If you want to display tabs to switch between the children of a specific level, use its Options.DetailTabsPosition attribute.

The following code displays root tabs at the top of the grid control:

//Delphi

  cxGrid1.RootLevelOptions.DetailTabsPosition := dtpTop;

//C++ Builder

  cxGrid1->RootLevelOptions->DetailTabsPosition = dtpTop;

Additionally, you should supply captions for the levels that are defined by the TcxGridLevel.Caption attribute.

The following code assigns captions to two root levels at runtime:

//Delphi

  cxGrid1Level1.Caption := 'Users';

  cxGrid1Level2.Caption := 'Items';

//C++ Builder

  cxGrid1Level1->Caption = "Users";

  cxGrid1Level2->Caption = "Items";

Now the grid control displays:

Refer to the Connecting to Data topic to learn more about connecting views to data sources.  The Create And Delete Columns section describes how to create columns within views (rows in card views).


Process Master Rows

Each data record in a master grid table view is represented by a TcxGridMasterDataRow object.  Most operations (getting cell values, selecting, focusing, expanding) for master rows can be performed in the same manner as for other row types.  However, some operations are specific to master rows:

•	getting the detail view for the given row.

The following code shows how to get the detail view corresponding to the focused master row within the currently focused master grid view.  The Expand method is used to create the detail view if it does not exist yet.  After the detail view has been created, it can be accessed via the ActiveDetailGridView property.

//Delphi

var

  ARecord: TcxCustomGridRecord;

  ADetailView: TcxCustomGridView;

//...

  ADetailView := nil;

  ARecord := TcxGridTableView(Grid.FocusedView).Controller.FocusedRecord;

  if ARecord is TcxGridMasterDataRow then

    with TcxGridMasterDataRow(ARecord) do

    begin

      Expand(False);

      ADetailView := ActiveDetailGridView;

    end;

//C++ Builder

  TcxCustomGridRecord * ARecord;

  TcxCustomGridView * ADetailView;

  TcxGridMasterDataRow * AMasterRow;

  ADetailView = NULL;

  ARecord = ((TcxGridTableView*)Grid->FocusedView)->Controller
->FocusedRecord;

  if (AMasterRow = dynamic_cast<TcxGridMasterDataRow*>(ARecord))

  {

    AMasterRow->Expand(false);

    ADetailView = AMasterRow->ActiveDetailGridView;

  }

•	switching between detail views for a specific master row

One master view can be associated with one or more detail views displayed at the same hierarchy level.  The next image shows the tvFilms view bound to three detail views (cvPeople, tvCompanies and cvPhotos).

The current active detail opened for a specific master row is determined by the ActiveDetailGridView property.  To switch between different sibling details programmatically, use the ActiveDetailIndex property.

The ToggleActiveDetail procedure allows you to switch between details for the focused master row within the currently focused master grid view.  When the tvFilms view is focused, this toggles between cvPeople, tvCompanies and cvPhotos details.

ToggleActiveDetail works even when the tab panel for switching between details is not visible (when the master level’s Options.DetailTabsPosition is set to dtpNone).

The helper NextVisibleLevelIndex routine is used to get the index of the next visible sibling level for the given TcxGridLevel object.

//Delphi

procedure TForm1.ToggleActiveDetail;

  function NextVisibleLevelIndex(ADetailLevel: TcxGridLevel): Integer;

  begin

    Result := 0;

    with ADetailLevel do

    begin

      if (Parent.VisibleCount > 1) and
        (VisibleIndex < Parent.VisibleCount - 1) then

        Result := Parent.VisibleItems[VisibleIndex + 1].Index;

    end;

  end;

var

  AView: TcxCustomGridTableView;

  ARecord: TcxCustomGridRecord;

begin

  AView := TcxCustomGridTableView(Grid.FocusedView);

  ARecord := AView.Controller.FocusedRecord;

  if ARecord is TcxGridMasterDataRow then

    with TcxGridMasterDataRow(ARecord) do

    begin

      Expand(False);

      ActiveDetailIndex := NextVisibleLevelIndex(ActiveDetailLevel);

    end;

end;

//C++ Builder

int NextVisibleLevelIndex(TcxGridLevel * ADetailLevel) {

  int AIndex = 0;

  if (ADetailLevel) {

    TcxGridLevel * AParent = ADetailLevel->Parent;

    if (AParent->VisibleCount > 1  &&
      ADetailLevel->VisibleIndex < AParent->VisibleCount - 1)

      AIndex = AParent->VisibleItems[ADetailLevel->VisibleIndex + 1]->Index;

  }

  return AIndex;

}

void __fastcall TForm1::ToggleActiveDetail() {

  TcxCustomGridTableView * AView =
    (TcxCustomGridTableView*)Grid->FocusedView;

  TcxCustomGridRecord * ARecord = AView->Controller->FocusedRecord;

  TcxGridMasterDataRow * AMasterRow;

  if (AMasterRow = dynamic_cast<TcxGridMasterDataRow*>(ARecord)) {

    AMasterRow->Expand(false);

    AMasterRow->ActiveDetailIndex =
      NextVisibleLevelIndex(AMasterRow->ActiveDetailLevel);

  }

}


TcxCustomGridOptions
TcxCustomGridOptions Object

Hierarchy          Properties

Represents the base class for all classes containing a set of options.

Unit

cxGridCustomView

TcxCustomGridOptions = class(TcxInterfacedPersistent);

Description

There are many options provided by the ExpressQuantumGrid control allowing you to customize its behavior and appearance.  These options are applied to views and view items.  They determine visibility, color and other appearance settings of the view elements, control the functionality such as grouping, moving, filtering and sorting, etc.  All these sets of options are represented by separate classes and these group the options according to their functions.  The TcxCustomGridOptions class is the base class for all option classes.  This class publishes the GridView property representing the view owning the current options set.


TcxCustomGridOptions Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |


Properties for TcxCustomGridOptions
TcxCustomGridOptions Properties

TcxCustomGridOptions          Legend

In TcxCustomGridOptions

GridView


TcxCustomGridOptions.GridView

TcxCustomGridOptions

Identifies the view owning the set of  options.

property GridView: TcxCustomGridView;

Description

Use the GridView property to access the grid view owning the current options set.  This property provides access to the views items, other options, styles sets, etc.

ReadOnly Property


TcxCustomGridOptionsSelection
TcxCustomGridOptionsSelection Object

Hierarchy          Properties

Represents the base class for sets of options concerned with selection functionality.

Unit

cxGridCustomView

TcxCustomGridOptionsSelection = class(TcxCustomGridOptions);

Description

The TcxCustomGridOptionsSelection class is the base class for the ExpressQuantumGrid options classes whose properties affect the selections within a view.  In its descendant classes, selection options determine whether to select individual cells or whole rows, whether the focus rectangle is displayed around the focused row and whether multiple rows can be selected, etc.


TcxCustomGridOptionsSelection Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |


Properties for TcxCustomGridOptionsSelection
TcxCustomGridOptionsSelection Properties

TcxCustomGridOptionsSelection          Legend

Derived from TcxCustomGridOptions

GridView


TcxCustomGridOptionsView
TcxCustomGridOptionsView Object

Hierarchy          Properties

Represents the base class for sets of options concerning the view’s appearance.

Unit

cxGridCustomView

TcxCustomGridOptionsView = class(TcxCustomGridOptions);

Description

The TcxCustomGridOptionsView class is the base class for the ExpressQuantumGrid classes concerned with the appearance of a view.  In general, these options specify visibility, color and width of view elements.


TcxCustomGridOptionsView Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |


Properties for TcxCustomGridOptionsView
TcxCustomGridOptionsView Properties

TcxCustomGridOptionsView          Legend

In TcxCustomGridOptionsView

ScrollBars

Derived from TcxCustomGridOptions

GridView


TcxCustomGridOptionsView.ScrollBars

TcxCustomGridOptionsView          See Also

Indicates whether the grid view contains scroll bars.

type TScrollStyle = (ssNone, ssHorizontal, ssVertical, ssBoth);

property ScrollBars: TScrollStyle;

Description

The ScrollBars property allows you to specify the scroll bars to display within the grid view.  Scroll bars appear when the view window is smaller than the entire view contents.  By default, a grid view is capable of displaying horizontal and vertical scroll bars.

TScrollStyle value	Description
ssNone	Prevents a grid view from displaying vertical and horizontal scroll bars.
ssHorizontal	Enables only the horizontal scroll bar to be displayed.  Vertical scroll bars are hidden.
ssVertical	Enables only the vertical scroll bar to be displayed.  Horizontal scroll bars are hidden.
ssBoth	Enables horizontal and vertical scroll bars.

Regardless of the scroll bars visibility, you can still scroll the view contents programmatically.  See the view’s Controller.MakeItemVisible, Controller.MakeRecordVisible methods, for instance.

The default value of the ScrollBars property is ssBoth.


TcxCustomGridOptionsBehavior
TcxCustomGridOptionsBehavior Object

Hierarchy          Properties

Represents the base class for all classes containing a set of options.

Unit

cxGridCustomView

TcxCustomGridOptionsBehavior = class(TcxCustomGridOptions);

Description

There are many options provided by the ExpressQuantumGrid control allowing you to customize its behavior and appearance.  These options are applied to views and view items.  They determine visibility, color and other appearance settings of the view elements, control the functionality such as grouping, moving, filtering and sorting, etc.  All these sets of options are represented by separate classes and these group the options according to their functions.  The TcxCustomGridOptions class is the base class for all option classes.  This class publishes the GridView property representing the view owning the current options set.


TcxCustomGridOptionsBehavior Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |


Properties for TcxCustomGridOptionsBehavior
TcxCustomGridOptionsBehavior Properties

TcxCustomGridOptionsBehavior          Legend

In TcxCustomGridOptionsBehavior

PostponedSynchronization

Derived from TcxCustomGridOptions

GridView


TcxCustomGridOptionsBehavior.PostponedSynchronization

TcxCustomGridOptionsBehavior          See Also

Specifies whether the synchronization of the "clone" views should be postponed and executed on demand.

property PostponedSynchronization: Boolean;

Description

Use the PostponedSynchronization property to specify whether the synchronization of the "clone" views with the "pattern" view should be done immediately or postponed and executed only when required at a later point.  "On demand" means that whenever the ViewInfo for a particular "clone" view is calculated, i.e. the "clone" view is about to be displayed; its settings (properties and events) are synchronized with (obtained from) the immediate "pattern" view.  Set the PostponedSynchronization property to True to improve the performance of the synchronization process if already you have a lot of "clone" views.

The default value of the PostponedSynchronization property is True.


TcxCustomGridRow
TcxCustomGridRow Object

Hierarchy          Properties          Methods          See Also

Represents the base class for records in a grid table view.

Unit

cxGridTableView

TcxCustomGridRow = class(TcxCustomGridRecord);

Description

The TcxCustomGridRow class is the base class for records in a table view.  Records in a table view are referred to as rows.  You can access rows currently displayed within a view via the view’s ViewData.Rows property.  A ViewData object reflects the current arrangement of visible rows within a view.  Any rows within collapsed group rows do not exist in the ViewData.Rows property.

There are several types of rows displayed in views derived from the TcxCustomGridRow class: group rows, data rows, master data rows and the new item row.

To return a value and text equivalent of a value in a column, use the Values and DisplayTexts arrays respectively.

The position of a row displayed in a view is determined by its Index property.  When the row position is changed after sorting or grouping, the index is also changed.  The RecordIndex property defines the position of the row in a data source.

For more information see the TcxCustomGridRecord class topic.


TcxCustomGridRow Hierarchy
Hierarchy

TObject

     |

TcxCustomGridRecord

     |


Properties for TcxCustomGridRow
TcxCustomGridRow Properties

TcxCustomGridRow          Legend

In TcxCustomGridRow

AsGroupRow

AsMasterDataRow

GridViewLevel

IsFilterRow

IsNewItemRow

ViewData

Derived from TcxCustomGridRecord

DisplayTexts

Expandable

Expanded

Focused

HasCells

GridView

Index

IsFirst

IsLast

IsNewItemRecord

IsParentRecordLast

LastParentRecordCount

Level

ParentRecord

RecordIndex

Selected

ValueCount

Values

ViewData

Visible


Methods for TcxCustomGridRow
TcxCustomGridRow Methods

TcxCustomGridRow          Legend

Derived from TcxCustomGridRecord

Collapse

Expand

GetFirstFocusableChild

GetLastFocusableChild

Invalidate

MakeVisible


TcxCustomGridRow.AsGroupRow

TcxCustomGridRow

Provides access to the current row as a group row.

property AsGroupRow: TcxGridGroupRow;

Description

Use the AsGroupRow property to access the properties and methods of the group row which is represented by the current row.  Using the AsGroupRow property in code lets you avoid casting the instance of the current row to the TcxGridGroupRow class.

Note:	If the current row doesn’t represent a group row, accessing the AsGroupRow property raises an exception.

ReadOnly Property


TcxCustomGridRow.AsMasterDataRow

TcxCustomGridRow

Provides access to the current row as a master data row.

property AsGroupRow: TcxGridMasterDataRow;

Description

Use the AsMasterDataRow property to access the properties and methods of the master data row which is represented by the current row.  Using the AsMasterDataRow property in code lets you avoid casting the instance of the current row to the TcxGridMasterDataRow class.

Note:	If the current row doesn’t represent a master data row, accessing the AsMasterDataRow property raises an exception.

ReadOnly Property


TcxCustomGridRow.GridViewLevel

TcxCustomGridRow

Row is the presentation of a data record in a grid table view. GridView is the [table] view which this row belongs to. GridViewLevel is a level object associated with this view

property GridViewLevel: TcxGridLevel;

Description

The presentation structure of the grid is built via levels (master and detail) and individual views linked to them.

ReadOnly Property


TcxCustomGridRow.IsFilterRow

TcxCustomGridRow          See Also

Determines whether the currently processed row is a filter row.

property IsFilterRow: Boolean;

Description

The IsFilterRow property returns True if the currently processed row is a filter row.  Otherwise – False.

ReadOnly Property


TcxCustomGridRow.IsNewItemRow

TcxCustomGridRow          See Also

Specifies whether the current row references the view’s new item row.

property IsNewItemRow: Boolean;

Description

The IsNewItemRow property returns True if the current row identifies the "new item row". This is used to enter new data within a view.  The new item row is referenced by the ViewData.NewItemRow property.  You enable the display of this row by setting the view’s OptionsView.NewItemRow property to True.

ReadOnly Property


TcxCustomGridRow.ViewData

TcxCustomGridRow

Identifies an object containing the current row.

property ViewData: TcxGridViewData;

Description

The ViewData property specifies an object of the TcxGridViewData class representing the current arrangement of rows within a view.  ViewData provides access to all rows displayed within a view (i.e. does not include the hidden ones within collapsed records).  The current row can be accessed as one of the TcxGridViewData.Rows collection elements.

ReadOnly Property


TcxGridDataRow
TcxGridDataRow Object

Hierarchy          Properties          Methods          See Also

Represents a row within a grid table view.

Unit

cxGridTableView

TcxGridDataRow = class(TcxCustomGridRow);

Description

The TcxGridDataRow class represents a data row in the TcxGridTableView control and this displays data in cells, one per column within the view.  Using the members of TcxGridDataRow, you can retrieve values and text representation of cells, get the group level of a row and get the row’s positions within the view & the data source.

You can access rows currently displayed using the view’s ViewData.Rows array.  It maintains a collection of currently visible rows, i.e. rows not hidden under collapsed row(s).  The first row in this collection identifies the top visible row.

TcxGridDataRow is also the base class for TcxGridMasterDataRow and TcxGridNewItemRow rows representing a row in a master view and a row for entering new data respectively.

For more information about rows see the TcxCustomGridRecord class topic.


TcxGridDataRow Hierarchy
Hierarchy

TObject

     |

TcxCustomGridRecord

     |

TcxCustomGridRow

     |


Properties for TcxGridDataRow
TcxGridDataRow Properties

TcxGridDataRow          Legend

Derived from TcxCustomGridRow

IsNewItemRow

ViewData

Derived from TcxCustomGridRecord

DisplayTexts

Expandable

Expanded

Focused

GridView

HasCells

Index

IsFirst

IsLast

IsNewItemRecord

IsParentRecordLast

LastParentRecordCount

Level

ParentRecord

RecordIndex

Selected

ValueCount

Values

ViewData

Visible


Methods for TcxGridDataRow
TcxGridDataRow Methods

TcxGridDataRow          Legend

Derived from TcxCustomGridRecord

Collapse

Expand

GetFirstFocusableChild

GetLastFocusableChild

Invalidate

MakeVisible


TcxGridFilterRow
TcxGridFilterRow Object

Hierarchy          Properties          Methods

The TcxGridFilterRow class implements a filter row.

Unit

cxGridTableView

TcxGridFilterRow = class(TcxGridNewItemRow)

Description

A filter row is a simpler alternative to filter dropdowns.  It’s located at the top of a view.

An end-user can filter results by any field currently allocated in the view (for more information on allocated fields, see the Customization Form).

You can specify the filter row’s options using the View’s FilterRow property.


TcxGridFilterRow Hierarchy
Hierarchy

TObject

     |

TcxCustomGridRecord

     |

TcxCustomGridRow

     |

TcxGridDataRow

     |

TcxGridNewItemRow

     |

TcxGridFilterRow


Properties for TcxGridFilterRow
TcxGridFilterRow Properties

TcxGridFilterRow          Legend

Derived from TcxCustomGridRow

IsNewItemRow

ViewData

Derived from TcxCustomGridRecord

DisplayTexts

Expandable

Expanded

Focused

GridView

HasCells

Index

IsFirst

IsLast

IsNewItemRecord

IsParentRecordLast

LastParentRecordCount

Level

ParentRecord

RecordIndex

Selected

ValueCount

Values

ViewData

Visible


Methods for TcxGridFilterRow
TcxGridFilterRow Methods

TcxGridFilterRow          Legend

Derived from TcxCustomGridRecord

Collapse

Expand

GetFirstFocusableChild

GetLastFocusableChild

Invalidate

MakeVisible


TcxGridFilterRowOptions
TcxGridFilterRowOptions Object

Hierarchy          Properties          Methods

The TcxGridFilterRowOptions class provides options for a filter row.

Unit

cxGridTableView

TcxGridFilterRowOptions = class(TcxGridSpecialRowOptions)

Description

The TcxGridFilterRowOptions class allows you to specify the filter row’s visibility (see the Visible property), its description (see the InfoText property), the width and color of the separator that visually divides the filter row from data rows (see SeparatorWidth and SeparatorColor properties), and the filtering mechanism used (see the ApplyChanges property).

The TcxGridFilterRowOptions object is referenced by the View’s FilterRow property.


TcxGridFilterRowOptions Hierarchy
Hierarchy

TcxCustomGridOptions

     |

TcxGridSpecialRowOptions

     |

TcxGridFilterRowOptions


Properties for TcxGridFilterRowOptions
TcxGridFilterRowOptions Properties

TcxGridFilterRowOptions          Legend

In TcxGridFilterRowOptions

ApplyChanges

Derived from TcxGridSpecialRowOptions

GridView

InfoText

SeparatorColor

SeparatorWidth

Visible


Methods for TcxGridFilterRowOptions
TcxGridFilterRowOptions Methods

TcxGridFilterRowOptions          Legend

Derived from TcxGridSpecialRowOptions

GetSeparatorColor


TcxGridFilterRowOptions.ApplyChanges

TcxGridFilterRowOptions

Specifies how filtering is applied to a view when a filter row is used.

type

  TcxGridFilterRowApplyChangesMode = (fracOnCellExit, fracImmediately);

property ApplyChanges: TcxGridFilterRowApplyChangesMode;

Description

A filter row provides two ways of filtering:

•	If the ApplyChanges property is set to fracOnCellExit, the filter row’s in-place editors introduce an auto-complete feature.  When you start entering values, the in-place editor automatically completes entry based on values contained in the column.  Pressing the Enter key updates the view with the filtered data.

•	If the ApplyChanges property is set to fracImmediately, the view is updated with the filtered data each time the end-user enters a character within the in-place editor.

The default value of the ApplyChanges property is fracOnCellExit.


TcxGridGroupRow
TcxGridGroupRow Object

Hierarchy          Properties          Methods          See Also

Represents a group row in a table view.

Unit

cxGridTableView

TcxGridGroupRow = class(TcxCustomGridRow);

Description

A group row in a table view displays information about its group.  Groups are created when you group data by one or more columns.  A group row displays a group column value and, optionally, group summaries (summaries calculated against records of this group).

To access visible rows (i.e. not hidden under collapsed group rows), see the view’s ViewData.Rows collection.  This collection provides access to all rows currently visible (data rows and group rows).  Group rows implement expanding/collapsing operations via the Expanded property and Expand and Collapse methods.

Every row in a view is identified by two indexes.  The Index property determines its visual position within a view.  It gets changed when you sort or group etc.  The RecordIndex property refers to its position within a data source and this value remains the same as when the view was created.  A group row does not have its own unique record index. The RecordIndex of a group row returns the record index of its first underlying data row.

Data rows within a view consist of the TcxGridDataRow class and its descendants.

Refer to the TcxCustomGridRecord for more details on presenting rows using ViewData.


TcxGridGroupRow Hierarchy
Hierarchy

TObject

     |

TcxCustomGridRecord

     |

TcxCustomGridRow

     |


Properties for TcxGridGroupRow
TcxGridGroupRow Properties

TcxGridGroupRow          Legend

In TcxGridGroupRow

DisplayCaption

DisplayText

GroupedColumn

GroupSummaryItems

Value

Derived from TcxCustomGridRow

IsNewItemRow

ViewData

Derived from TcxCustomGridRecord

DisplayTexts

Expandable

Expanded

Focused

GridView

HasCells

Index

IsFirst

IsLast

IsNewItemRecord

IsParentRecordLast

LastParentRecordCount

Level

ParentRecord

RecordIndex

Selected

ValueCount

Values

ViewData

Visible


Methods for TcxGridGroupRow
TcxGridGroupRow Methods

TcxGridGroupRow          Legend

In TcxGridGroupRow

GetGroupSummaryInfo

Derived from TcxCustomGridRecord

Collapse

Expand

GetFirstFocusableChild

GetLastFocusableChild

Invalidate

MakeVisible


TcxGridGroupRow.DisplayCaption

TcxGridGroupRow

Gets the caption of the currently processed group row.

property DisplayCaption: string;

Description

The DisplayCaption property returns a caption specified by the GroupedColumn.AlternateCaption property. If the GroupedColumn.AlternateCaption property contains an empty string, the GroupedColumn.Caption property’s value will be returned.

ReadOnly Property


TcxGridGroupRow.DisplayText

TcxGridGroupRow          See Also

Gets the text displayed in the current group row.

property DisplayText: string;

Description

The DisplayText property returns the text displayed in the group row.  This text identifies a group column value and group summaries, if any.  To get the value of the group column alone, see the Value property.

The next image shows data grouped by the PurchaseDate column.  The two group rows display the value of the group column and the summary calculating the number of records within a group.

For the first group row, the DisplayText property returns the 'PurchaseDate : 3/28/2002 (COUNT=4)' string while the Value property returns 3/28/2002 in TDateTime format.

ReadOnly Property


TcxGridGroupRow.GroupedColumn

TcxGridGroupRow

Represents the topmost grouping column.

property GroupedColumn: TcxGridColumn;

Description

In the grouping hierarchy, the GroupedColumn property specifies the topmost grouping column.

ReadOnly Property


TcxGridGroupRow.GroupSummaryItems

TcxGridGroupRow

Represents a collection of group summaries that are defined on the currently processed group row.

property GroupSummaryItems: TcxDataGroupSummaryItems;

Description

Use the GroupSummaryItems property to access group summaries calculated against grouped columns provided by the current grouped row.

ReadOnly Property


TcxGridGroupRow.Value

TcxGridGroupRow          See Also

Determines a value of the group column by which data is grouped.

property Value: Variant;

Description

Each group row contains one or more underlying rows having the same value within the group column. This value can be accessed via the Value property.  You can use the DisplayText member to get the text displayed in a group row (the text representation of a group column value along with group summaries if any).

The next image shows a grid view displaying three group rows created by grouping by the PurchaseDate column.  These group rows contain data rows with identical PurchaseDate column values.  The Value property for the first group row returns 3/28/2002 in TDateTime format.  The Value properties of the other two rows return 3/29/2002 and 3/30/2002 respectively.

ReadOnly Property


TcxGridGroupRow.GetGroupSummaryInfo

TcxGridGroupRow

Requests information on summaries of the currently processed group row.

function GetGroupSummaryInfo(var ASummaryItems: TcxDataSummaryItems; var ASummaryValues: PVariant): Boolean;

Description

The ASummaryItems parameter specifies a collection of summaries to be populated;

The ASummaryValues parameter represents values of the retrieved summaries.

The returned result is True, if the request is successful.


TcxGridMasterDataRow
TcxGridMasterDataRow Object

Hierarchy          Properties          Methods          See Also

Represents a row in a master view.

Unit

cxGridTableView

TcxGridMasterDataRow = class(TcxGridDataRow);

Description

When representing master/detail relationship in ExpressQuantumGrid, two views should be created (master and detail).  These views display data from the appropriate master and detail tables.  The TcxGridMasterDataRow class represents a data row in a master view.  It contains data from the master table record.  A master data row displays the ‘+’ button at the left enabling a user to expand the detail view.  When the detail is expanded, the ‘+’ button is changed into ‘–‘.  Clicking the ‘–‘ button results in hiding the detail.

The collection of rows visible within a view is provided by the view’s ViewData.Rows array.  This collection references both data rows and group rows.

You can determine the visual position of a row via the Index property.  The RecordIndex attribute provides the position of the row within the data source.  Refer to the TcxCustomGridRecord class topic to learn more about row indexing.

TcxGridMasterDataRow introduces properties providing the active detail view, the level of the master row and also indexed access to all the detail views created for the master row.  The ActiveDetailIndex property can be used to switch between detail views.  To refer to the first and the last records in a detail view, use the GetFirstFocusableChild and GetLastFocusableChild methods respectively.

Other properties can be used to focus the record, expand/collapse it and select it.


TcxGridMasterDataRow Hierarchy
Hierarchy

TObject

     |

TcxCustomGridRecord

     |

TcxCustomGridRow

     |

TcxGridDataRow

     |


Properties for TcxGridMasterDataRow
TcxGridMasterDataRow Properties

TcxGridMasterDataRow          Legend

In TcxGridMasterDataRow

ActiveDetailGridView

ActiveDetailGridViewExists

ActiveDetailIndex

ActiveDetailLevel

DetailGridViewCount

DetailGridViewExists

DetailGridViewHasData

DetailGridViews

HasChildren

Derived from TcxCustomGridRow

IsNewItemRow

ViewData

Derived from TcxCustomGridRecord

DisplayTexts

Expandable

Expanded

Focused

GridView

HasCells

Index

IsFirst

IsLast

IsNewItemRecord

IsParentRecordLast

LastParentRecordCount

Level

ParentRecord

RecordIndex

Selected

ValueCount

Values

ViewData

Visible


Methods for TcxGridMasterDataRow
TcxGridMasterDataRow Methods

TcxGridMasterDataRow          Legend

Derived from TcxCustomGridRecord

Collapse

Expand

GetFirstFocusableChild

GetLastFocusableChild

Invalidate

MakeVisible


TcxGridMasterDataRow.ActiveDetailGridView

TcxGridMasterDataRow          See Also

Returns the active detail view.

property ActiveDetailGridView: TcxCustomGridView;

Description

One master view can be associated with several detail views with the help of grid levels.  The ActiveDetailGridView property refers to the detail view that is active (i.e. displayed to the user).  You can test whether an active child view exists via the ActiveDetailGridViewExists property.  To access the level owning the active detail view, use the ActiveDetailLevel property.

To know more about establishing master-detail relationships see the Master-Detail topic.

ReadOnly Property


TcxGridMasterDataRow.ActiveDetailGridViewExists

TcxGridMasterDataRow          See Also

Specifies whether the master row contains an active detail view.

property ActiveDetailGridViewExists: Boolean;

Description

The ActiveDetailGridViewExists property returns True if there is an active detail view accessible via the ActiveDetailGridView property.  Otherwise, False is returned.

ReadOnly Property


TcxGridMasterDataRow.ActiveDetailIndex

TcxGridMasterDataRow          See Also

Specifies the index of the detail view (level) associated with the master view.

property ActiveDetailIndex: Integer;

Description

Master views can be associated with one or more detail (child) views.  Use the ActiveDetailIndex property to determine the index of the active detail (i.e. displayed to a user).  Setting the ActiveDetailIndex property results in activating the corresponding detail view.  To define the number of details associated with the master view, see the view’s Level.Count property.

To learn more about creating master-detail relationships refer to the Master-Detail topic.


TcxGridMasterDataRow.ActiveDetailLevel

TcxGridMasterDataRow          See Also

Refers to the grid level owning the active detail view.

property ActiveDetailLevel: TcxGridLevel;

Description

The ActiveDetailLevel property returns the grid level containing the active (i.e. displayed to a user) detail view.  You can get the active detail view via the ActiveDetailGridView property.  The view’s Level.Count property specifies the total number of child levels for this view.

To learn more about creating master-detail relationships refer to the Master-Detail topic.

ReadOnly Property


TcxGridMasterDataRow.DetailGridViewCount

TcxGridMasterDataRow          See Also

Determines the number of detail views associated with the current master row.

property DetailGridViewCount: Integer;

Description

Use the DetailGridViewCount property to determine the number of detail views associated with the current master row.  This is equal to the number of master-detail relationships that have been created for the current master row (child grid levels for the master view) and is returned by the view’s Level.Count property.

To learn more about creating master-detail relationships refer to the Master-Detail topic.

ReadOnly Property


TcxGridMasterDataRow.DetailGridViewExists

TcxGridMasterDataRow          See Also

Determines whether the master row contains a detail view for a particular grid level.

property DetailGridViewExists[Index: Integer]: Boolean;

Description

Use the DetailGridViewExists property to determine whether the master row contains a detail view for a particular grid level.  The grid level is identified by its index.  The DetailGridViewExists property returns True if the detail view is created for the specified grid level.  Otherwise, False is returned.

All the detail views which have been created for the current master row, can be accessed via the DetailGridViews property.

To learn more about creating master-detail relationships refer to the Master-Detail topic.

ReadOnly Property

------------------------------------------------------


TcxGridMasterDataRow.DetailGridViewHasData

TcxGridMasterDataRow          See Also

Determines whether the detail view of the currently processed master row has rows.

property DetailGridViewHasData[Index:Integer]: Boolean;

Description

The DetailGridViewHasData method returns True, if the Index detail view has rows.

The Index parameter specifies the index of a detail view (the level’s index) associated with the current master row.

ReadOnly Property


TcxGridMasterDataRow.DetailGridViews

TcxGridMasterDataRow          See Also

Provides access to all the detail views which have been created for the current master row.

property DetailGridViews[Index: Integer]: TcxCustomGridView;

Description

The DetailGridViews property provides indexed access to all the detail views which have been created for the current master row.  To access a particular detail view, specify the index of the grid level that the detail view is associated with.

Note:	When no detail view is associated with the specified grid level the DetailGridViews property returns a shallow clone of a grid view.  It’s advisable to first check the DetailGridViews property to determine whether there is a detail view for the specified grid level.

To learn more about creating master-detail relationships refer to the Master-Detail topic.

ReadOnly Property


TcxGridMasterDataRow.HasChildren

TcxGridMasterDataRow          See Also

Determines whether the current master row contains any non-empty detail views.

property HasChildren: Boolean;

Description

The HasChildren property returns True when the current master row contains at least one non-empty detail view.  Otherwise, False is returned.

This property is used internally to determine whether the expand button of a particular master row should be displayed when the view’s OptionsView.ExpandButtonsForEmptyDetails property is in effect.

To learn more about creating master-detail relationships refer to the Master-Detail topic.

ReadOnly Property


TcxGridNewItemRow
TcxGridNewItemRow Object

Hierarchy          Properties          Methods          See Also

Represents the data row for entering new data within a view.

Unit

cxGridTableView

TcxGridNewItemRow = class(TcxGridDataRow);

Description

The new item row is referenced by the view’s ViewData.NewItemRow object.  By default, a new item row is not visible.  Set the NewItemRow.Visible property to True, to display it onscreen.

Using attributes of the TcxGridNewItemRow class, you can focus the new item row, return values within row cells etc.

The view’s ViewData.Rows property provides access to data rows within this view.

Refer to the TcxCustomGridRecord class topic for more information on rows in a view.


TcxGridNewItemRow Hierarchy
Hierarchy

TObject

     |

TcxCustomGridRecord

     |

TcxCustomGridRow

     |

TcxGridDataRow

     |


Properties for TcxGridNewItemRow
TcxGridNewItemRow Properties

TcxGridNewItemRow          Legend

Derived from TcxCustomGridRow

IsNewItemRow

ViewData

Derived from TcxCustomGridRecord

DisplayTexts

Expandable

Expanded

Focused

GridView

HasCells

Index

IsFirst

IsLast

IsNewItemRecord

IsParentRecordLast

LastParentRecordCount

Level

ParentRecord

RecordIndex

Selected

ValueCount

Values

ViewData

Visible


Methods for TcxGridNewItemRow
TcxGridNewItemRow Methods

TcxGridNewItemRow          Legend

Derived from TcxCustomGridRecord

Collapse

Expand

GetFirstFocusableChild

GetLastFocusableChild

Invalidate

MakeVisible


TcxGridNewItemRowOptions
TcxGridNewItemRowOptions Object

Hierarchy          Properties          Methods

The TcxGridNewItemRowOptions class provides options for a new item row.

Unit

cxGridTableView

TcxGridNewItemRowOptions = class(TcxGridSpecialRowOptions)

Description

The TcxGridNewItemRowOptions class contains settings that allow you to set the new item row’s visibility (see the Visible property), its description (see the InfoText property), the width and color of the separator that visually divides the new item row from data rows (see SeparatorWidth and SeparatorColor properties).

The TcxGridNewItemRowOptions object is referenced by the view’s NewItemRow property.


TcxGridNewItemRowOptions Hierarchy
Hierarchy

TcxCustomGridOptions

     |

TcxGridSpecialRowOptions

     |

TcxGridNewItemRowOptions


Properties for TcxGridNewItemRowOptions
TcxGridNewItemRowOptions Properties

TcxGridNewItemRowOptions          Legend

Derived from TcxGridSpecialRowOptions

GridView

InfoText

SeparatorColor

SeparatorWidth

Visible


Methods for TcxGridNewItemRowOptions
TcxGridNewItemRowOptions Methods

TcxGridNewItemRowOptions          Legend

Derived from TcxGridSpecialRowOptions

GetSeparatorColor


TcxGridSpecialRowOptions
TcxGridSpecialRowOptions Object

Hierarchy          Properties          Methods          See Also

The TcxGridSpecialRowOptions class represents options common to a filter row and new item row.

Unit

cxGridTableView

TcxGridSpecialRowOptions = class(TcxCustomGridOptions)

Description

With these options, you can specify the row’s visibility (see the Visible property), its description (see the InfoText property), the width and color of the separator (see SeparatorWidth and SeparatorColor properties) that visually divides the specialized rows from data rows.

Do not use this class directly.  Use its descendants instead.


TcxGridSpecialRowOptions Hierarchy
Hierarchy

TcxCustomGridOptions

     |

TcxGridSpecialRowOptions


Properties for TcxGridSpecialRowOptions
TcxGridSpecialRowOptions Properties

TcxGridSpecialRowOptions          Legend

In TcxGridSpecialRowOptions

GridView

InfoText

SeparatorColor

SeparatorWidth

Visible


Methods for TcxGridSpecialRowOptions
TcxGridSpecialRowOptions Methods

TcxGridSpecialRowOptions          Legend

In TcxGridSpecialRowOptions

GetSeparatorColor


TcxGridSpecialRowOptions.GridView

TcxGridSpecialRowOptions          See Also

property GridView: TcxGridTableView;

Description

The utility row is either a filter row or new item row.

Use the GridView property to access the table view instance.

ReadOnly Property


TcxGridSpecialRowOptions.InfoText

TcxGridSpecialRowOptions          See Also

Specifies the descriptive name of the currently processed utility row.

property InfoText: string;

Description

The utility row is either a filter row or new item row.

Use the InfoText property to provide a description for a  given row.


TcxGridSpecialRowOptions.SeparatorColor

TcxGridSpecialRowOptions          See Also

Specifies the color of the utility row’s separator.

property SeparatorColor: TColor;

Description

The separator visually divides the utility row (either a filter row or new item row) from data rows in a table view.

The default value of the SeparatorColor property is clDefault.


TcxGridSpecialRowOptions.SeparatorWidth

TcxGridSpecialRowOptions          See Also

Specifies the width of the utility row’s separator in pixels.

property SeparatorWidth: Integer;

Description

The separator visually divides the utility row (either the filter row or new item row) from data rows in a table view.

Use the SeparatorWidth property to specify the separator’s width.

The default value of the SeparatorWidth property is cxGridCustomRowSeparatorDefaultWidth.


TcxGridSpecialRowOptions.Visible

TcxGridSpecialRowOptions          See Also

Specifies whether the currently processed utility row is visible.

property Visible: Boolean;

Description

The utility row is either the filter row or new item row.

The default value of the Visible property is False.


TcxGridSpecialRowOptions.GetSeparatorColor

TcxGridSpecialRowOptions          See Also

Returns a color of a separator that visually divides a filter row (or a new item row) from other data rows in a table view.

function GetSeparatorColor: TColor;

Description

Use the GetSeparatorColor method to determine the separator’s color.


TcxGridViewData
TcxGridViewData Object

Hierarchy          Properties          Methods          See Also

This is an intermediate class providing an interface or bridge between a data controller and a grid view.

Unit

cxGridTableView

TcxGridViewData = class(TcxCustomGridTableViewData);

Description

The TcxGridViewData class retrieves data from a data controller and presents it as an array of rows to a view.  Use the view’s ViewData property to get attributes of the associated ViewData object.

The collection of records provided by the TcxGridViewData class is supported by the Rows property.  Every row represents an object of the TcxCustomGridRow class allowing you to access different attributes relating to a row (an array of values corresponding to record fields, level of a record and others).

A ViewData object represents the records displayed within a view (i.e. does not include those hidden within collapsed records).  There are several types of records derived from TcxCustomGridRow:

•	A data row which displays cells with record values corresponding to item (column) fields.

•	A master data row represents a data row in a master view.

•	The new item row is a special row for entering new data.

•	A group row is a row displaying the column value by which data are grouped (and displaying group summaries, if any)

For more information refer to the TcxCustomGridRecord class, which is a base class for TcxCustomGridRow.


TcxGridViewData Hierarchy
Hierarchy

TObject

     |

TcxGridViewHandler

     |

TcxCustomGridViewData

     |

TcxCustomGridTableViewData

     |


Properties for TcxGridViewData
TcxGridViewData Properties

TcxGridViewData          Legend

In TcxGridViewData

FilterRow

NewItemRow

RowCount

Rows

Derived from TcxCustomGridTableViewData

NewItemRecord

RecordCount

Records

Derived from TcxGridViewHandler

Control

Controller

DataController

GridView

ViewData


Methods for TcxGridViewData
TcxGridViewData Methods

TcxGridViewData          Legend

In TcxGridViewData

HasFilterRow

Derived from TcxCustomGridTableViewData

Collapse

Expand

HasNewItemRecord

Derived from TcxGridViewHandler

BeginUpdate

Create

EndUpdate


TcxGridViewData.FilterRow

TcxGridViewData          See Also

Represents a filter row.

property FilterRow: TcxGridFilterRow;

Description

A filter row is a simpler alternative to filter dropdowns.  When initially drawn (or not focused and when filtering is not applied), it displays a text describing its functionality:

An end-user can filter the results by any field, which is currently allocated in the view.

ReadOnly Property


TcxGridViewData.NewItemRow

TcxGridViewData          See Also

Specifies the "new item row" in the grid view.

property NewItemRow: TcxGridNewItemRow;

Description

The NewItemRow property references the record where an end-user can enter new data in the grid.  The ‘new item row’ is displayed if the OptionsView.NewItemRow property is set to True.  Otherwise, this row is not displayed and NewItemRow contains NIL.

If the new item row is not visible, an end-user is still able to add new records.  If the view’s OptionsData.Appending property is True, pressing the down arrow key when the last record is focused adds a new record at the end of the dataset.  Setting the OptionsData.Inserting property to True allows an end-user to insert a record by pressing the Insert key.

ReadOnly Property


TcxGridViewData.RowCount

TcxGridViewData          See Also

Specifies the number of rows which are represented by the current ViewData class instance.

property RowCount: Integer;

Description

The RowCount property retrieves the number of rows provided by the Rows collection.

ReadOnly Property


TcxGridViewData.Rows

TcxGridViewData          See Also

Provides indexed access to the rows which are stored in the ViewData object.

property Rows[Index: Integer]: TcxCustomGridRow;

Description

Use the Rows property to access the rows which are visible or potentially visible by scrolling within the current View.  Each row represents an object of the TcxCustomGridRow class which provides information on the data record associated with the row (the record level, values of fields, text representations of values, etc.).

ReadOnly Property


TcxGridViewData.HasFilterRow

TcxGridViewData          See Also

Returns true, if the currently processed table view displays a filter row,

function HasFilterRow: Boolean; virtual;

Description

The HasFilterRow method returns True, if a filter row is shown in the table view (the FilterRow.Visible property’s value is True).  Otherwise – False.


TcxGridFilterRowApplyChangesMode
TcxGridFilterRowApplyChangesMode type

See Also

Enumerates the available types of updating the view when filtering items with a filter row.

Unit

cxGridTableView

TcxGridFilterRowApplyChangesMode = (fracOnCellExit, fracImmediately);

Description

The following table contains descriptions of the enumeration values:

Value	Meaning
fracOnCellExit	The view is updated with filtered data when pressing the Enter key
fracImmediately	The view is updated with filtered data every time an end-user starts typing in an in-place editor


cxGridCustomRowSeparatorDefaultWidth constant
cxGridCustomRowSeparatorDefaultWidth global constant

See Also

Specifies the default width of the utility row’s separator in pixels.

Unit

cxGridTableView

cxGridCustomRowSeparatorDefaultWidth = 6;

Description

The separator visually divides the utility row (either a filter row or new item row) and the other rows in a table view.

Use the cxGridCustomRowSeparatorDefaultWidth constant to specify another default width of the separator.


cxGridDBChartView Unit Overview
cxGridDBChartView Unit

Classes

TcxGridDBChartDataController

TcxGridDBChartItemDataBinding

TcxGridDBChartCategories

TcxGridDBChartDataGroup

TcxGridDBChartSeries

TcxGridDBChartView


TcxGridDBChartDataController
TcxGridDBChartDataController Object

Hierarchy          Properties          Methods          Events          See Also

Represents a data controller which manages and supplies the data in a TDataSet.

Unit

cxGridDBChartView

TcxGridDBChartDataController = class(TcxDBDataController, IcxCustomGridDataController, IcxGridChartViewItemsProvider)

Description

The TcxGridDBChartDataController provides data from a TDataSet to a data-aware ChartView.  A data controller enables you to perform a set of operations on the data (managing, addressing and setting options for sorting the data which correspond to the view items, i.e. categories and series).  You can use the view’s DataController property to get direct access to the data displayed by this view.  However, it's recommended that you use the view’s Categories, Series or ViewData properties for these purposes since they provide a more convenient way in which to manage the data associated with the view.


TcxGridDBChartDataController Hierarchy
Hierarchy

TPersistent

     |

TcxCustomDataController

     |

TcxDBDataController

     |


Properties for TcxGridDBChartDataController
TcxGridDBChartDataController Properties

TcxGridDBChartDataController          Legend

In TcxGridDBChartDataController

GridView

Derived from 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 TcxGridDBChartDataController
TcxGridDBChartDataController Methods

TcxGridDBChartDataController          Legend

In TcxGridDBChartDataController

BeginFullUpdate

EndFullUpdate

Derived from TcxDBDataController

BeginLocate

ChangeFieldName

EndLocate

GetItemByFieldName

GetItemField

GetItemFieldName

GetRecordId

LocateByKey

GetSelectedBookmark

Derived from TcxCustomDataController

Append

AppendRecord

BeginFullUpdate

BeginUpdate

Cancel

ChangeRowSelection

CheckFocusedSelected

ClearBookmark

ChangeDetailExpanding

ClearDetailLinkObject

ClearDetails

ClearSelection

ClearSorting

CollapseDetails

DeleteFocused

DeleteRecord

DeleteSelection

Edit

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 TcxGridDBChartDataController
TcxGridDBChartDataController Events

TcxGridDBChartDataController          Legend

Derived from TcxDBDataController

OnDetailHasChildren

Derived from TcxCustomDataController

OnAfterCancel

OnAfterDelete

OnAfterInsert

OnAfterPost

OnBeforeCancel

OnBeforeDelete

OnBeforeInsert

OnBeforePost

OnCompare

OnDataChanged

nDetailCollapsed

nDetailCollapsing

nDetailExpanded

nDetailExpanding

OnFilterRecord

OnGroupingChanged

OnRecordChanged

OnSortingChanged


TcxGridDBChartDataController.GridView

TcxGridDBChartDataController

Provides access to the data-aware ChartView whose data is managed by the data controller.

property GridView: TcxGridDBChartView;

Description

Use the GridView property to access the data-aware ChartView whose data is managed by the data controller.  This property provides access to the view items, style sets, etc.

ReadOnly Property


TcxGridDBChartDataController.BeginFullUpdate

TcxGridDBChartDataController

Prevents update notifications in the data controller and the data-aware ChartView that displays its data until the EndFullUpdate method is called.

procedure BeginFullUpdate; override;

Description

This method locks (postpones update notifications to) the data controller which manages the data displayed by the ChartView and also locks the view by internally calling the view’s BeginUpdate method.  This may be useful since locking only the data controller may result in multiple updates to the ChartView that displays the data when the data controller is unlocked.

When using the BeginFullUpdate and EndFullUpdate methods, the ChartView that displays the data is unlocked only after its data controller has been unlocked and this ensures that the ChartView is updated only once which gives a performance benefit.


TcxGridDBChartDataController.EndFullUpdate

TcxGridDBChartDataController

Unlocks the data controller and its associated data-aware ChartView after a call to the BeginFullUpdate method.

procedure EndFullUpdate; override;

Description

Use the EndFullUpdate method to unlock the data controller and the data-aware ChartView that displays its data after they have been locked by a call to the BeginFullUpdate method.  To do this the EndFullUpdate method internally calls the view’s EndUpdate method.  Note that the number of calls to the BeginFullUpdate method must match the number of calls to the EndFullUpdate method to ensure unlocking.  Thus, it's recommended to use try…finally statements when performing a batch update.

When using the BeginFullUpdate and EndFullUpdate methods, the ChartView that displays the data is unlocked only after its data controller has been unlocked and this ensures that the ChartView is updated only once which gives a performance benefit.


TcxGridDBChartItemDataBinding
TcxGridDBChartItemDataBinding Object

Hierarchy          Properties          Methods

Represents an object which links a chart view item with a dataset field.

Unit

cxGridDBChartView

TcxGridDBChartItemDataBinding = class(TcxGridChartItemDataBinding)

Description

Every chart view item (a category or a series) uses a DataBinding object to link to a dataset.  Generally, the data binding is used to determine the type of the value.  The value type is identified by the ValueTypeClass property. The ValueTypeClass determines the manner in which the data is represented (as a string, integer, date, Boolean, etc.).  In bound mode, you can associate an item with a data field in a dataset by setting the item’s DataBinding.FieldName property. The ValueTypeClass is assigned automatically based upon the field's type.  The ValueTypeClass and ValueType properties also provide ways in which to implement unbound items in data-aware views.


TcxGridDBChartItemDataBinding Hierarchy
Hierarchy

TPersistent

     |

TcxGridChartItemDataBinding

     |


Properties for TcxGridDBChartItemDataBinding
TcxGridDBChartItemDataBinding Properties

TcxGridDBChartItemDataBinding          Legend

In TcxGridDBChartItemDataBinding

DataController

Field

FieldName

Derived from TcxGridChartItemDataBinding

Data

DataController

DataIndex

GridView

SummaryIndex

SummaryItem

ValueType

ValueTypeClass


Methods for TcxGridDBChartItemDataBinding
TcxGridDBChartItemDataBinding Methods

TcxGridDBChartItemDataBinding          Legend

Derived from TcxGridChartItemDataBinding

GetValueDisplayText

IsValueTypeClassValid


TcxGridDBChartItemDataBinding.DataController

TcxGridDBChartItemDataBinding

Provides access to the data controller which manages the data-aware chart view item’s data.

property DataController: TcxGridDBChartDataController;

Description

Use the DataController property to access the object that provides the connection between a bound dataset and the chart view item which corresponds to the DataBinding object.  A data controller object implements the retrieval and posting of data.

ReadOnly Property


TcxGridDBChartItemDataBinding.Field

TcxGridDBChartItemDataBinding

Provides access to the field associated with the chart view item.

property Field: TField;

Description

The Field property references a TField object addressed by the FieldName property.  Set the FieldName property to change the field for the item.

ReadOnly Property


TcxGridDBChartItemDataBinding.FieldName

TcxGridDBChartItemDataBinding

Specifies the name of the item’s field.

property FieldName: string;

Description

The FieldName property addresses the field in the data controller which is associated with the item.  The field itself can be accessed via the Field object.

When the FieldName is assigned, the ValueTypeClass property which determines the value type of this item is set automatically based upon the dataset field's type.  This ensures the grid performs correctly when accessing, sorting and validating the values of items.


TcxGridDBChartCategories
TcxGridDBChartCategories Object

Hierarchy          Properties          Methods          Events          See Also

Represents categories in a data-aware Chart view.

Unit

cxGridDBChartView

TcxGridDBChartCategories = class(TcxGridChartCategories)

Description

A category is used to classify data for comparison.  Data groups are used to create a hierarchy of data levels which determine the categories into which series values are grouped/aggregated, and provide the drill-down functionality in Chart views.

The default categories provide a simple classification of series values without aggregation.  In terms of databases, the default category stands for a data column which uniquely identifies and refers to the values (series values) within a data record.

Categories in data-aware Chart views are represented by an instance of the TcxGridDBChartCategories class (the TcxGridChartCategories class in unbound Chart views).  This class provides the same abilities as its ancestor class and also allows you to bind the default categories to a specific data field in a dataset via the DataBinding.FieldName property of the DataBinding object.

To modify properties of the default categories at design time, you need to select the rightmost data level in a chart toolbox (provided that the view’s ToolBox.DataLevelsInfoVisible option is enabled) and switch to the Object Inspector.


TcxGridDBChartCategories Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |

TcxGridChartCategories

     |

TcxGridDBChartCategories


Properties for TcxGridDBChartCategories
TcxGridDBChartCategories Properties

TcxGridDBChartCategories          Legend

In TcxGridDBChartCategories

DataBinding

Derived from TcxGridChartCategories

DataBinding

DisplayText

GridView

ID

SortOrder

ValueCount

Values

VisibleDisplayTexts

VisibleValueCount

VisibleValues


Methods for TcxGridDBChartCategories
TcxGridDBChartCategories Methods

TcxGridDBChartCategories          Legend

Derived from TcxGridChartCategories

GetDisplayText

GetValueDisplayText


Events for TcxGridDBChartCategories
TcxGridDBChartCategories Events

TcxGridDBChartCategories          Legend

Derived from TcxGridChartCategories

OnGetValueDisplayText


TcxGridDBChartCategories.DataBinding

TcxGridDBChartCategories

Specifies an object which links categories to a dataset.

property DataBinding: TcxGridDBChartItemDataBinding;

Description

Use the DataBinding property to specify the object which links the categories that are associated with the TcxGridDBChartCategories object instance to a dataset.  You can use the properties of the DataBinding object to define the data type of the category values, link the categories to a specific data field in the dataset via the DataBinding.FieldName property, associate an arbitrary value (via the DataBinding.Data property) with the categories and perform other operations.

At design time, you can select a value type for the categories and choose a dataset field associated with the categories from the DataBinding.ValueType and DataBinding.FieldName properties which provide lists of the available values.


TcxGridDBChartSeries
TcxGridDBChartSeries Object

Hierarchy          Properties          Methods          Events          See Also

Represents a series in a data-aware Chart view.

Unit

cxGridDBChartView

TcxGridDBChartSeries = class(TcxGridChartSeries)

Description

Series and data groups represent chart items in Chart views.  Data groups are used to create a hierarchy of data levels which determine the categories into which series values are grouped/aggregated, and provide the drill-down functionality.  Series values are used to graphically represent data in the chart.  Series values are grouped into categories to represent data at a particular level of detail.

Compared with data groups, the default categories provide a simple classification of series values without aggregation.  In terms of databases, the default category stands for a data column which uniquely identifies and refers to the values (series values) within a data record.

Each series in data-aware Chart Views is represented by an instance of the TcxGridDBChartSeries class.  This class provides the same abilities as its ancestor class and also allows you to bind a series to a specific data field in a dataset via the DataBinding.FieldName property of the DataBinding object.

To access all series created in a data-aware Chart View, use the View’s Series collection.


TcxGridDBChartSeries Hierarchy
Hierarchy

TComponent

     |

TcxComponent

     |

TcxGridChartItem

     |

TcxGridChartSeries

     |

TcxGridDBChartSeries


Properties for TcxGridDBChartSeries
TcxGridDBChartSeries Properties

TcxGridDBChartSeries          Legend

In TcxGridDBChartSeries

DataBinding

Derived from TcxGridChartSeries

GroupSummaryKind

Styles

SumOfValues

ValueCaptionFormat

Derived from TcxGridChartItem

DataBinding

DisplayText

GridView

ID

Index

Order

SortOrder

ValueCount

Values

Visible

VisibleDisplayTexts

VisibleForCustomization

VisibleIndex

VisibleValueCount

VisibleValues

Derived from TComponent

Name

Tag


Methods for TcxGridDBChartSeries
TcxGridDBChartSeries Methods

TcxGridDBChartSeries          Legend

Derived from TcxGridChartSeries

AddValue

IsValue

Derived from TcxGridChartItem

GetDisplayText

GetValueDisplayText

IsValue


Events for TcxGridDBChartSeries
TcxGridDBChartSeries Events

TcxGridDBChartSeries          Legend

Derived from TcxGridChartSeries

OnCustomDrawValue

OnValueClick

Derived from TcxGridChartItem

OnGetStoredProperties

OnGetStoredPropertyValue

OnGetValueDisplayText

OnSetStoredPropertyValue


TcxGridDBChartSeries.DataBinding

TcxGridDBChartSeries

Specifies an object which links the series to a dataset.

property DataBinding: TcxGridDBChartItemDataBinding;

Description

Use the DataBinding property to specify the object which links the series to a dataset.  You can use the properties of the DataBinding object to define the data type of the series values, link the series to a specific data field in the dataset via the DataBinding.FieldName property, associate an arbitrary value (via the DataBinding.Data property) with the series and perform other operations.

At design time, you can select a value type for the series and choose a dataset field associated with the categories from the DataBinding.ValueType and DataBinding.FieldName properties which provide lists of the available values.


TcxGridDBChartView
TcxGridDBChartView Object

Hierarchy          Properties          Methods          Events          See Also          Tutorial

Represents a data-aware version of the view which implements data representation in the form of a chart.

Unit

cxGridDBChartView

TcxGridDBChartView = class(TcxGridChartView)

Description

The TcxGridDBChartView object represents the data-aware version of the ChartView.  It inherits all the functionality of its ancestor except for the data binding settings (for information about view functionality features see the TcxGridChartView class's description).  These settings are encapsulated in the DataController property.  The DataController.DataSource property specifies a TDataSet or its descendant which manages the view's connection to a dataset.  The other settings of the data controller specify the key fields for implementing master-detail relationships and the behavior options of the data controller.

As with its ancestor, the key elements of the data-aware Chart view are categories, data groups, and series.  However, the data-aware version uses the TcxGridDBChartCategories, TcxGridDBChartDataGroup TcxGridDBChartSeries classes to refer to these elements.  The difference between the regular classes and their data-aware versions are the DataBinding properties (DataBinding, DataBinding, and DataBinding, respectively) which provide a connection between the categories, data groups, series and, dataset fields.


TcxGridDBChartView Hierarchy
Hierarchy

TComponent

     |

TcxControlChildComponent

     |

TcxCustomGridView

     |

TcxGridChartView

     |


Properties for TcxGridDBChartView
TcxGridDBChartView Properties

TcxGridDBChartView          Legend

In TcxGridDBChartView

Categories

DataController

DataGroups

Series

Derived from TcxGridChartView

ActiveDataGroup

ActiveDataLevel

ActiveDiagram

AvailableDiagramCount

AvailableDiagrams

Categories

Controller

DataController

DataGroupCount

DataGroups

DataLevelCount

DataLevelObjects

DiagramArea

DiagramBar

DiagramColumn

DiagramCount

DiagramLine

DiagramPie

Diagrams

IsDataGrouped

Legend

OptionsBehavior

OptionsCustomize

OptionsView

Series

SeriesCount

SortedSeries

Styles

Title

ToolBox

ViewData

ViewInfo

VisibleDataGroupCount

VisibleDataGroups

VisibleSeries

VisibleSeriesCount

Derived from TcxCustomGridView

CloneCount

Clones

Controller

DataController

DragMode

Focused

IsControlFocused

IsDetail

IsMaster

IsPattern

Level

MasterGridRecordIndex

MasterGridView

MasterRecordIndex

OptionsSelection

OptionsView

PatternGridView

PopupMenu

Site

Styles

Synchronization

ViewData

ViewInfo

Visible

Derived from TcxControlChildComponent

Control

IsDestroying

IsLoading


Methods for TcxGridDBChartView
TcxGridDBChartView Methods

TcxGridDBChartView          Legend

In TcxGridDBChartView

CreateDataGroup

CreateSeries

FindDataGroupByFieldName

FindSeriesByFieldName

GetDataGroupClass

GetSeriesClass

Derived from TcxGridChartView

CanActivateDataLevel

ClearDataGroups

ClearSeries

CreateDataGroup

CreateImage

CreateSeries

FindDataGroupByID

FindDataGroupByName

FindDataGroupByTag

FindDiagramByDisplayText

FindDiagramByID

FindSeriesByID

FindSeriesByName

FindSeriesByTag

GetDataGroupClass

GetSeriesClass

Derived from TcxCustomGridView

BeginUpdate

CancelUpdate

EndUpdate

GetHitTest

LayoutChanged

RestoreDefaults

RestoreFromIniFile

RestoreFromRegistry

RestoreFromStream

SizeChanged

StoreToIniFile

StoreToRegistry

StoreToStream

ViewChanged

Derived from TcxControlChildComponent

CreateEx

Destroy


Events for TcxGridDBChartView
TcxGridDBChartView Events

TcxGridDBChartView          Legend

Derived from TcxGridChartView

OnActiveDataLevelChanged

OnActiveDiagramChanged

OnCustomDrawLegend

OnCustomDrawLegendItem

OnDataGroupPosChanged

OnFirstVisibleCategoryIndexChanged

OnGetValueHint

OnSeriesPosChanged

OnValueClick

Derived from TcxCustomGridView

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnGetStoredProperties

OnGetStoredPropertyValue

OnInitStoredObject

OnMouseDown

OnMouseEnter

OnMouseLeave

OnMouseUp

OnSetStoredPropertyValue

OnStartDrag


TcxGridDBChartView.Categories

TcxGridDBChartView          See Also

Specifies the categories used to classify the data within the data-aware view.

property Categories: TcxGridDBChartCategories;

Description

The categories in the data-aware ChartViews are represented by an instance of the TcxGridDBChartCategories class which enables you to link the categories to a specific dataset field and also provides various properties for customizing the appearance of the categories within the view.

Use the Categories property to specify the categories which will classify the data (the series values displayed) within the data-aware view for comparison purposes.


TcxGridDBChartView.DataController

TcxGridDBChartView

Specifies the data controller for the data-aware view.

property DataController: TcxGridDBChartDataController;

Description

Use the DataController property to access the object which manages the view's connection to a dataset.  A data controller object implements the retrieval and posting of the data which corresponds to the view items (i.e. categories and series) and, applies sorting to them.  You can use the DataController property to get direct access to the data displayed by the view.  However, it's recommended that you use the view’s Categories, Series or ViewData properties for these purposes since they provide a more convenient way in which to manage the data that is associated with the view.

Use the DataController.DataSource property to specify a TDataSet or its descendant which manages the view's connection to a dataset.  The other settings of the data controller specify the key fields for implementing master-detail relationships and the behavior options of the data controller.


TcxGridDBChartView.DataGroups

TcxGridDBChartView

Provides indexed access to all data groups in the data-aware view.

property DataGroups[Index: Integer]: TcxGridDBChartDataGroup;

Description

The index of a data group within the DataGroups collection is determined by the data group’s Index property.  Use the DataGroupCount property to get a count of all data groups within this collection.

To access data groups associated with data levels, use the VisibleDataGroups zero-based indexed collection.


TcxGridDBChartView.Series

TcxGridDBChartView          See Also

Provides indexed access to all the series which provide values for the data-aware view.

property Series[Index: Integer]: TcxGridDBChartSeries;

Description

A series in a data-aware Chart view is represented by an instance of the TcxGridDBChartSeries class which enables you to link the series to a specific dataset field and also provides various properties for customizing the appearance of the series within the view.

Use the Series zero-based indexed collection to access all the series which provide series values for rendering the data-aware Chart view.  Use the SeriesCount property to obtain the total number of series whose values are available for displaying within the diagrams of the view.  To access all the series whose values were used to render the view (i.e., that are visible within the view), use the VisibleSeries property instead.  A count of the total number of these series can be obtained from the VisibleSeriesCount property.  To control the general appearance of a specific series (its series values) within the view, set the Visible property of the series as required.


TcxGridDBChartView.CreateDataGroup

TcxGridDBChartView

Creates a data group in the data-aware View.

function CreateDataGroup: TcxGridDBChartDataGroup;

Description

This function creates a visible data group.  The created data group is added to the VisibleDataGroups collection.


TcxGridDBChartView.CreateSeries

TcxGridDBChartView          See Also

Creates a series for the data-aware view.

function CreateSeries: TcxGridDBChartSeries;

Description

Use the CreateSeries function to create a series for the data-aware view.  The created series is automatically added to the series whose values are used to render the view which can be accessed via the VisibleSeries collection.

You can use the DataBinding object of the created series to define the data type of the series values, link the series to a specific data field in the dataset via the DataBinding.FieldName property, associate an arbitrary value (via the DataBinding.Data property) with the series and perform other operations.


TcxGridDBChartView.FindDataGroupByFieldName

TcxGridDBChartView

Searches for a data group linked to a specified dataset field.

function FindDataGroupByFieldName(const AFieldName: string): TcxGridDBChartDataGroup;

Description

This function returns a data group whose DataBinding.FieldName property’s value is equal to the AFieldName parameter’s value.  If no data group is found, nil is returned.


TcxGridDBChartView.FindSeriesByFieldName

TcxGridDBChartView

Searches for a series linked to a specified dataset field.

function FindSeriesByFieldName(const AFieldName: string): TcxGridDBChartSeries;

Description

This function returns a series whose DataBinding.FieldName property’s value is equal to the AFieldName parameter’s value.  If no series is found, nil is returned.


TcxGridDBChartView.GetDataGroupClass

TcxGridDBChartView          See Also

Returns the class type associated with data groups in the data-aware View.

type

  TcxGridChartDataGroupClass = class of TcxGridChartDataGroup;

function GetDataGroupClass: TcxGridChartDataGroupClass; override;

Description

TcxGridChartView descendants override this function to return an appropriate class type for each particular View.

For data-aware views, this function returns TcxGridDBChartDataGroup.


TcxGridDBChartView.GetSeriesClass

TcxGridDBChartView          See Also

Returns the class type associated with series in the data-aware View.

type

  TcxGridChartSeriesClass = class of TcxGridChartSeries;

function GetSeriesClass: TcxGridChartSeriesClass; override;

Description

TcxGridChartView descendants override this function to return an appropriate class type for each particular View.

For data-aware Views, this function returns TcxGridDBChartSeries.


TcxGridDBChartDataGroup
TcxGridDBChartDataGroup Object

Hierarchy          Properties          Methods          Events

Represents a data group in a data-aware Chart View.

Unit

cxGridDBChartView

TcxGridDBChartDataGroup = class(TcxGridChartDataGroup)

Description

In addition to the settings inherited from the base TcxGridChartDataGroup class, the TcxGridDBChartDataGroup class introduces the DataBinding property that allows you to bind a data group to a specific data field in a dataset.

To access all data groups created in a data-aware Chart View, use the View’s DataGroups collection.


TcxGridDBChartDataGroup Hierarchy
Hierarchy

TComponent

     |

TcxComponent

     |

TcxGridChartItem

     |

TcxGridChartDataGroup

     |

TcxGridDBChartDataGroup


Properties for TcxGridDBChartDataGroup
TcxGridDBChartDataGroup Properties

TcxGridDBChartDataGroup          Legend

In TcxGridDBChartDataGroup

DataBinding

Derived from TcxGridChartDataGroup

Active

ActiveValue

ActiveValueDisplayText

DataLevel

SortOrder

Derived from TcxGridChartItem

DataBinding

DisplayText

GridView

ID

Index

Order

SortOrder

ValueCount

Values

Visible

VisibleDisplayTexts

VisibleForCustomization

VisibleIndex

VisibleValueCount

VisibleValues


Methods for TcxGridDBChartDataGroup
TcxGridDBChartDataGroup Methods

TcxGridDBChartDataGroup          Legend

Derived from TcxGridChartDataGroup

HasActiveValue

IsValue

Derived from TcxGridChartItem

GetDisplayText

GetValueDisplayText

IsValue


Events for TcxGridDBChartDataGroup
TcxGridDBChartDataGroup Events

TcxGridDBChartDataGroup          Legend

Derived from TcxGridChartItem

OnGetStoredProperties

OnGetStoredPropertyValue

OnGetValueDisplayText

OnSetStoredPropertyValue


TcxGridDBChartDataGroup.DataBinding

TcxGridDBChartDataGroup

Specifies an object, which links the data group to a dataset.

property DataBinding: TcxGridDBChartItemDataBinding;

Description

You can use the properties of the specified DataBinding object to:

•	define the data type of the data group’s values;

•	link the data group to a specific data field in a dataset via the DataBinding.FieldName property;

•	associate an arbitrary value with the data group via the DataBinding.Data property;

•	etc.

At design time, you can select:

•	the data type for a data group from its DataBinding.ValueType property;

•	a dataset field associated with the data from its DataBinding.FieldName property, which provides a list of the available data types.


Chart View Tutorial. Overview

Prev:	Next: View Creation
This tutorial describes how to create a fully functional data-aware application which uses the ExpressQuantumGrid to display data in the form of a chart.

Consider the CARS table that is shipped with the EQGrid demos and contains information on various cars.  This table will be connected to a ChartView within the grid control.

The tutorial covers the following topics:

1.	View Creation.  This topic describes how to create a grid control with a ChartView.  Creating a data source for the View and connecting the Grid control to data is also covered.  Read the Connecting To Data, Working With Levels, Data Representation topics for related information.

2.	Categories and Series.  This topic contains information on creating the categories and data series which provide the data rendered by the ChartView.  See the descriptions of the TcxGridChartCategories and TcxGridChartSeries classes for details.  Read the Create And Delete Series topic for more information on creating data series.

3.	Customizing the View.  This topic explains how to use the ChartView options to improve the appearance of the grid.

4.	Customizing the Diagram.  This topic provides details on using the diagram options to enhance the appearance of the grid.

5.	Applying Styles.  This topic shows how to use the cxStyles and Style Repository.  Here you will create and setup a style and assign it to a View element.


Chart View Tutorial. Step 1: View Creation

Prev: Overview	Next: Categories and Series
This topic explains how to create an ExpressQuantumGrid control which uses a ChartView and demonstrates how to bind it to a data source.

First, create an empty application project.  Then go to the Dev Express tab of the component palette and select the cxGrid control:

Double-click it to add the ExpressQuantumGrid to a form.  After the control appears, adjust its size as required.  The following screenshot demonstrates a form with a cxGrid component on it:

The Structure Navigator located at the bottom right part of the grid control is used to display and manage the grid's structure.  At the moment, the grid control shown above contains only one grid level (cxGrid1Level1) with an associated DB TableView (cxGrid1DBTableView1).  To display the properties of a level or a View in the Object Inspector, click on the corresponding label in the Structure Navigator (alternatively, you can use the Object TreeView).  For comprehensive information on the Structure Navigator, see the Structure Navigator topic.

Since the existing View is a TableView, we need to replace it with a ChartView.  Right-click the TableView box within the Structure Navigator and select the Delete View item from the dropdown menu:

After the TableView has been removed, right-click the level box within the Structure Navigator and expand the Create View item within the dropdown menu.  Select ‘DB Chart’ from the list to create a data-aware ChartView (‘Chart’ corresponds to a non data-aware version of the View).

Now the grid contains an empty ChartView:

Sequentially select the grid control, the created View and the existing level to use the Object Inspector to set their Name properties to Grid, chvCars and lvCars, respectively.  Here’s how the form looks at this point:

Now to create a grid data source, you should:

1.	Create a database which will be connected to the CARS table.  Place a TDatabase component [image] onto a form.  Set its properties as follows:

•	DatabaseName to DemosDB

•	DriverName to STANDARD

In order to specify the connection parameters for the database, double-click on the component.  In the Database Editor dialog which opens click the Defaults button to obtain a list of all the parameters, as well as their default values.  Set the PATH parameter to a string which defines a path to the directory where the CARS table is located.  Click the OK button to close the Database Editor dialog.

To connect the database to the table, set its Connected property to True.

2.	Activate the BDE tab of the component palette and place a TQuery component [image] onto the form.  Set its properties as follows:

•	DatabaseName to DemosDB

•	Name to qryCars

•	SQL to " SELECT Category, Cyl, Liter, Trademark + ' ' + Model As Model From Cars ".  This specifies the query which will select the Category, Cyl, Liter fields and also the Model field which represents the concatenated string produced by the Trademark and Model fields’ values in the CARS table.  To set the query, click the ellipsis button in the SQL property:

This activates the editor used to enter the query's text so you can type in the required string.

•	Active to True.  Note that the Active property must be set after all the other properties have been set.

3.	Switch to the Data Access tab of the component palette and place a TDataSource component [image] on the form and connect it to the qryCars dataset by setting its DataSet property to qryCars.  Rename the component to dsCars.

After the data source has been created and set up, it must be connected to the GridView.  Select the chvCars view from within the Structure Navigator window.  The Object Inspector will display the view’s properties.

Expand the DataController property.  It allows the data-aware properties of a View to be edited.   Use the combo box near the DataSource property to specify the TDataSource instance as the View's data source:

There’s also another and easier way to connect the grid to a data source.  You may want to use this approach whenever the ExpressQuantumGrid is placed on a form, a View is designated to display the data and all the necessary data sources have already been created and set up.  At this point, all you have to do to connect the grid to a data source is to right-click on the grid and choose the Link to <DataSource name> option from the dropdown menu as shown in the image below:

Currently, the grid will not display any data, because there aren't any items (categories and series) specified for the chvCars view yet.  For more detailed information on creating the grid control and binding it to data, see the Connecting To Data topic.

See the next topic for information on creating categories and data series.


Chart View Tutorial. Step 2: Categories and Series

Prev: View Creation	Next: Customizing The View

In the previous topic, we created a grid control containing a ChartView.  This View was bound to the CARS table in the DemosDB database.  By default, the column diagram becomes active once the View has been created.  Note that the grid control does not display any data yet:

The next step is to designate the categories within the ChartView.  To do this you must select the chvCars view from within the Structure Navigator window and expand the Categories property in the Object Inspector window.  Expand the DataBinding property which allows the data-aware properties of the categories to be edited.  Use the combo box near the FieldName property to choose the field from the View’s bound data source and select the Model field:

This will categorize the data within the ChartView by the car models.  The ChartView now displays tick-mark labels which correspond to category values:

Note that the categories are displayed in a zigzag manner and the text of the wide labels is automatically truncated and ends with ellipses to avoid clipping.  For demonstration purposes in this tutorial, we'll reduce the number of categories displayed within the chart by filtering the data in the bound dataset by the car category.  Select the qryCars dataset and set its Filter property to "Category = 'SALOON'" and the Filtered property to True as shown in the screenshot below:

As a result, the ChartView now contains information on the saloon cars only and thus the categories within the chart are limited to the ones shown in the following screenshot:

The next step is to create the data series which will provide the data to render the ChartView.  In order to do this, activate the Component Editor by clicking on the Customize… button of the Structure Navigator.  The Component Editor contains a Series tab on the right.  Click the Add… button to add a series.  This will display a dropdown menu which lists all the numeric data source fields.  Choose sequentially the Cyl and Liter fields.  The corresponding series will be created.  Note that the fields for which the series have been created in the View are displayed as checked in the dropdown menu:

Once data series have been added to the View, their names and the names of the fields linked to the series appear within the list on the Series page.  Here you can remove specific series from the View by pressing the Delete button or the Del key or, by unchecking the corresponding field in the dropdown menu which appears when the Add… button is clicked.  See the Create and Delete Series topic for details on creating series within ChartViews.

The following screenshot demonstrates how the grid control looks when both the series linked to the Cyl and Liter fields have been created:

The properties of each data series can be modified using the Component Editor and the Object Inspector.  Select the chvCarsSeries1 series which is linked to the Cyl field and change its name to "chvCarsSeriesCyl".

A data series can also be selected in a ChartView by clicking either the corresponding data marker in the chart’s plot area or the corresponding legend item.  Select the chvCarsSeries2 series which is linked to the Liter field and change its name to "chvCarsSeriesLiter" using any of the techniques described above.  Note that the borders of the data markers and the legend items that correspond to the selected data series are displayed in inverted color thus allowing you to easily distinguish which series is currently selected.

In a similar manner you can change any of the data series properties even the data binding settings.  See the TcxGridDBChartSeries class's description for details on the data-aware data series settings.

See the next topic for a snapshot of the View options setup.


Chart View Tutorial. Step 3: Customizing The View

Prev: Categories and Series	Next: Customizing The Diagram

The previous topic finished with creating the ChartView series and designating the categories.  The result is shown in the following screenshot:

This topic explains how to customize the layout and the appearance of ChartViews using the properties of the chart view elements.

Unlike the other views, a ChartView’s appearance depends entirely upon its elements and their options.  Thus to customize the appearance aspects of the ChartView’s we need to address the elements of the view.  In the previous topic we learned how to access the properties of the categories and data series.  When a specific ChartView is selected within the Structure Navigator or the Component Editor, all the other elements (diagrams, chart legend and chart title) and their corresponding options can be accessed via the Object Inspector.

First, let’s modify the manner in which the data in the ChartView is visualized (i.e. change the currently active column diagram to the bar diagram).  There are three possible ways to accomplish this.  Select the chvCars view using the Structure Navigator.  Now you can right-click the ChartView box within the Structure Navigator and select the Bar Diagram item within the dropdown menu.

In the Object Inspector you can select either a ‘Bar Diagram’ item from the list of available diagrams provided by the ActiveDiagram property or expand the DiagramBar property and set the Active property to True within the Object Inspector as shown in the following screenshot.

Note that the diagram which is currently active is checked within the invoked dropdown menu.  Here is the result of activating the bar diagram:

To arrange the chart legend horizontally under the active diagram and plot the border around it, expand the Legend property and set the Border and Position properties as shown in the image below:

As you can see, the chart’s plot area widens since the chart legend is now located under the diagram.  The orientation of the chart legend is changed according to the new Position property’s value.  The chart legend will be displayed using these settings in all the diagrams which will be activated unless the settings are modified within a specific diagram.

To specify the title which will be displayed on the top of the ChartView (the default position of the title), expand the Title property and assign the title text to the Text property as follows:

To systematize the data displayed within the ChartView and to simplify the process of comparing series values, we’ll sort the data by the values of the chvCarsSeriesLiter series.  Select the chvCarsSeriesLiter series and set the SortOrder property to soAscending as shown in the following screenshot.

The result is shown below:

The categories, data series, chart legend and chart title are elements which are common to all the diagrams, that’s why their properties can be set independently of the context of the diagrams within the ChartView.  All the properties of these elements which are specific to a diagram can be accessed via the corresponding properties of the diagram and override the settings of the corresponding properties assigned within the view.  See the next topic for the base information on customizing chart diagrams.


Chart View Tutorial. Step 4: Customizing The Diagram

Prev: Customizing The View	Next: Applying Styles

The previous topic finished with customizing the view by arranging the data series, chart legend and chart title.  The result is demonstrated in the following screenshot:

This topic explains how to customize the layout and the appearance of ChartViews using the properties of the chart diagrams.

Each diagram provides an extended set of options which control the appearance of the diagram elements such as the axes and their titles, data markers, tick marks and their labels.  All the options which control the appearance aspects such as the position, orientation and alignment of the diagram elements are initialized with default values that provide a standard appearance for charts.  There are two possible ways to access the properties of a specific diagram.  Select a ChartView within the Structure Navigator or the Component Editor, and now you can either right-click the ChartView box and select the required diagram from the dropdown menu (this results in the properties of the selected diagram being shown within the Object Inspector) or expand the property which corresponds to the diagram (for instance, DiagramBar for a bar diagram) in the Object Inspector.  The properties are self- explanatory and are grouped by the diagram elements.

Let’s assign a title for the category axis which represents the base for data markers (bars) and is the axis where categories (car models) are labeled.  To do this, expand the DiagramBar property, then expand the AxisCategory and Title properties to access the properties of the category axis title.  Set the Text property to ‘Car Models’.  The result is shown in the screenshot below.

As you can see, the title of the category axis is displayed vertically and centered along the axis.  To align the title to a specific side of the chart’s plot area, use the Alignment property.

To provide details on the series values displayed let’s display the captions of the series values (the data labels on the series values) outside the corresponding data markers and aligned to the end of the data markers.  To do this, expand the Values property and set the CaptionPosition property to cdvcpOutsideEnd.  The result is shown in the image below.

So far we haven't modified the style settings of the elements we arranged within the ChartView.  They were painted using the default styles.  See the next topic for details on improving the grid’s appearance.


Chart View Tutorial. Step 5: Applying Styles

Prev: Customizing The Diagram	Next:

The previous topic finished with customizing the view by arranging the diagram elements.  The result is shown in the following screenshot:

This topic demonstrates how to improve the grid’s appearance using styles and the Styles Repository.

Navigate to the Dev Express tab of the component palette and drop a cxStyleRepository control onto the form:

Using the Style Repository, you can create and manage styles.  Next we will create a style for the chart title.  Double-click the cxStyleRepository component on the form to invoke the editing dialog.  Activate the Styles page and click the Add button to create a new style.  Specify a name and set the properties of the created style as follows:

•	Expand the Style.Font property and set the font size to 12 and font style to fsBold.

•	Set the Style.Name property to ‘ChartTitleStyle’.

•	Set the Style.TextColor property value to clNavy.

After the style has been created and set up, it can be assigned to a ChartView or diagram element.  Select the ChartView using the Structure Navigator or the Component Editor.  Expand the Styles property.  Select the Styles.Title property and use the corresponding combo box to assign the ChartTitleStyle style to the title of the ChartView.  The result is shown in the following screenshot:

An easy and straightforward way to add a new style to the Style Repository and apply it to the view element is to use the corresponding entry in the combo box as shown in the following screenshot:

In a similar way you can create and apply the styles to all the visual elements of the ChartView and diagrams such as the chart legend, chart’s plot area, axes, their titles and corresponding gridlines, data markers, tick marks and their labels.  The styles can vary from diagram to diagram thus providing a unique appearance for each chart.

For comprehensive information on the Style Repository and using it, see the Style Repository topic.


cxGridDetailsSite Unit Overview
cxGridDetailsSite Unit

Classes

TcxGridDetailsSiteTabHitTest


TcxGridDetailsSiteTabHitTest
TcxGridDetailsSiteTabHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the tab (located within the tab panel displayed at the root or child (detail) grid level) which is located at the point being tested.

Unit

cxGridDetailsSite

TcxGridDetailsSiteTabHitTest = class(TcxCustomGridHitTest)

Description

The TcxGridDetailsSiteTabHitTest class designates the hit code (which is equal to the htTab) of the tab which is located at the point being tested and also provides general information on this tab such as the corresponding level and owning objects (the immediate parent object within the grid levels hierarchy), these can be accessed using the Level and Owner properties, respectively.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridDetailsSiteTabHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |


Properties for TcxGridDetailsSiteTabHitTest
TcxGridDetailsSiteTabHitTest Properties

TcxGridDetailsSiteTabHitTest          Legend

In TcxGridDetailsSiteTabHitTest

Level

Owner

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridDetailsSiteTabHitTest
TcxGridDetailsSiteTabHitTest Methods

TcxGridDetailsSiteTabHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridDetailsSiteTabHitTest.Level

TcxGridDetailsSiteTabHitTest

Provides access to the grid level at which the tab panel (and the tab that corresponds to the current HitTest object) is located.

property Level: TcxGridLevel;

Description

Use the Level property to access the grid level at which the tab panel (and the tab that corresponds to the current HitTest object) is located.  The owning object (the immediate parent object within the grid levels hierarchy) of this grid level can be accessed via the Owner property.


TcxGridDetailsSiteTabHitTest.Owner

TcxGridDetailsSiteTabHitTest

Provides access to the owning object for the grid level at which the tab that corresponds to the current HitTest object is located.

property Owner: TObject;

Description

Use the Owner property to access the owning object (the immediate parent object within the grid levels hierarchy) of the grid level (which is accessible via the Level property) at which the tab that corresponds to the current HitTest object is located.  By default, the grid control is the owner of the root grid levels and master records are the owners of the corresponding detail (child) levels.


cxGridRows Unit Overview
cxGridRows Unit

Classes

TcxGridPreviewHitTest


TcxGridPreviewHitTest
TcxGridPreviewHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the preview section which is located at the point being tested.

Unit

cxGridRows

TcxGridPreviewHitTest = class(TcxGridRecordCellHitTest)

Description

The TcxGridPreviewHitTest class does not introduce any new functionality, but instead designates the hit code (which is equal to htPreview) of the preview section which is located at the grid view’s point that is being tested.

Use the Item and GridRecord properties to access the properties and methods of the grid item and record for which the preview section being inspected is displayed, respectively.

The basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridPreviewHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxGridRecordHitTest

     |

TcxGridRecordCellHitTest

     |


Properties for TcxGridPreviewHitTest
TcxGridPreviewHitTest Properties

TcxGridPreviewHitTest          Legend

Derived from TcxGridRecordCellHitTest

Item

Derived from TcxGridRecordHitTest

GridRecord

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridPreviewHitTest
TcxGridPreviewHitTest Methods

TcxGridPreviewHitTest          Legend

Derived from TcxGridRecordHitTest

CanClick

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridChartTitleHitTest
TcxGridChartTitleHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the chart title which is located at the point being tested.

Unit

cxGridChartView

TcxGridChartTitleHitTest = class(TcxCustomGridViewHitTest)

Description

The TcxGridChartTitleHitTest class does not introduce any new functionality, but instead designates the hit code (which is equal to htChartTitle) of the chart title which is located at the Grid View’s point that is being tested.

Basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridChartTitleHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxGridChartTitleHitTest


Properties for TcxGridChartTitleHitTest
TcxGridChartTitleHitTest Properties

TcxGridChartTitleHitTest          Legend

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridChartTitleHitTest
TcxGridChartTitleHitTest Methods

TcxGridChartTitleHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridChartLegendHitTest
TcxGridChartLegendHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the chart legend which is located at the point being tested.

Unit

cxGridChartView

TcxGridChartLegendHitTest = class(TcxCustomGridViewHitTest)

Description

The TcxGridChartLegendHitTest class does not introduce any new functionality, but instead designates the hit code (which is equal to htLegend) of the chart legend which is located at the Grid View’s point that is being tested.

Basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridChartLegendHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxGridChartLegendHitTest


Properties for TcxGridChartLegendHitTest
TcxGridChartLegendHitTest Properties

TcxGridChartLegendHitTest          Legend

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridChartLegendHitTest
TcxGridChartLegendHitTest Methods

TcxGridChartLegendHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridChartLegendItemHitTest
TcxGridChartLegendItemHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the legend item which is located at the point being tested.

Unit

cxGridChartView

TcxGridChartLegendItemHitTest = class(TcxCustomGridViewHitTest)

Description

The TcxGridChartLegendItemHitTest class designates the hit code (which is equal to htLegendItem) of the legend item which is located at the Grid View’s point that is being tested and also provides information specific to legend items such as the position of the legend item within the chart legend and the series which corresponds to this legend item (that are accessible via the Index and Series properties, respectively).

Basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridChartLegendItemHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxGridChartLegendItemHitTest


Properties for TcxGridChartLegendItemHitTest
TcxGridChartLegendItemHitTest Properties

TcxGridChartLegendItemHitTest          Legend

In TcxGridChartLegendItemHitTest

Index

Series

ValueIndex

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridChartLegendItemHitTest
TcxGridChartLegendItemHitTest Methods

TcxGridChartLegendItemHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridChartLegendItemHitTest.Index

TcxGridChartLegendItemHitTest          See Also

Specifies the visual position of the inspected legend item within the chart legend.

Index: Integer;

Description

Use the Index field to determine the visual position of the inspected legend item within the chart legend according to the position of the corresponding series within the collection of series whose data is currently displayed within the View.


TcxGridChartLegendItemHitTest.Series

TcxGridChartLegendItemHitTest

Specifies the series which corresponds to the inspected legend item.

Series: TcxGridChartSeries;

Description

Use the Series field to access the series which corresponds to the inspected legend item and whose data is currently displayed within the View.


TcxGridChartLegendItemHitTest.ValueIndex

TcxGridChartLegendItemHitTest          See Also

Specifies the series value which corresponds to the inspected legend item.

ValueIndex: Integer;

Description

When only a single series is currently displayed within the View and the chart legend displays the colors associated with categories (the VaryColorsByCategory property is set to True) the ValueIndex field determines the series value within the category which corresponds to the inspected legend item.  In this case the ValueIndex field returns the position of the series value within the collection of series values that are visible within the current View.  Otherwise, –1 is returned.


TcxGridChartValueHitTest
TcxGridChartValueHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on a data marker located at the point being tested.

Unit

cxGridChartView

TcxGridChartValueHitTest = class(TcxCustomGridViewHitTest)

Description

In addition to the settings inherited from the base TcxCustomGridViewHitTest class, TcxGridChartValueHitTest introduces members that are used to:

•	designate the hit code (equal to htChartValue) for the data marker;

•	provide access to the series that corresponds to the data marker (Series);

•	return the index of the chart value displayed by this data marker within the VisibleValues collection of series (ValueIndex);

•	determine whether a drill-down on this value can be performed (CanDrillDown).

Basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridChartValueHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxGridChartValueHitTest


Properties for TcxGridChartValueHitTest
TcxGridChartValueHitTest Properties

TcxGridChartValueHitTest          Legend

In TcxGridChartValueHitTest

CanDrillDown

Series

ValueIndex

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridChartValueHitTest
TcxGridChartValueHitTest Methods

TcxGridChartValueHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridChartValueHitTest.CanDrillDown

TcxGridChartValueHitTest           See Also

Determines whether a drill-down on a chart value that corresponds to the inspected data marker can be performed.

CanDrillDown: Boolean;

Description

This field returns True when a drill-down on the chart value can be performed.  Otherwise, this value cannot be drilled down.

Note:	For the chart value at the highest data level, CanDrillDown returns False.


TcxGridChartValueHitTest.Series

TcxGridChartValueHitTest

Provides access to the series that corresponds to the inspected data marker.

Series: TcxGridChartSeries;


TcxGridChartValueHitTest.ValueIndex

TcxGridChartValueHitTest          See Also

Returns the index of the chart value displayed by the inspected data marker within the VisibleValues collection.

ValueIndex: Integer;


TcxGridChartDiagramSelectorHitTest
TcxGridChartDiagramSelectorHitTest Object

Hierarchy          Properties         Methods          See Also

Provides general information on the diagram selector located at the point being tested.

Unit

cxGridChartView

TcxGridChartDiagramSelectorHitTest = class(TcxCustomGridViewHitTest)

Description

In addition to the settings inherited from the base TcxCustomGridViewHitTest class, TcxGridChartDiagramSelectorHitTest introduces members that are used to:

•	designate the hit code (equal to htDiagramSelector) for the diagram selector;

•	determine whether the diagram selector’s drop-down list can be opened (CanDropDown).

Basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridChartDiagramSelectorHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxGridChartDiagramSelectorHitTest


Properties for TcxGridChartDiagramSelectorHitTest
TcxGridChartDiagramSelectorHitTest Properties

TcxGridChartDiagramSelectorHitTest          Legend

In TcxGridChartDiagramSelectorHitTest

CanDropDown

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridChartDiagramSelectorHitTest
TcxGridChartDiagramSelectorHitTest Methods

TcxGridChartDiagramSelectorHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridChartDiagramSelectorHitTest.CanDropDown

TcxGridChartDiagramSelectorHitTest

Indicates whether the diagram selector’s drop-down list can be opened.

CanDropDown: Boolean;

Description

This field returns False when only a single diagram is available within a Chart View.


TcxGridChartDataLevelInfoHitTest
TcxGridChartDataLevelInfoHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on a data level located at the point being tested.

Unit

cxGridChartView

TcxGridChartDataLevelInfoHitTest = class(TcxCustomGridViewHitTest)

Description

In addition to the settings inherited from the base TcxCustomGridViewHitTest class, the TcxGridChartDataLevelInfoHitTest introduces members that are used to:

•	designate the hit code (equal to htDataLevelInfo) for a data level;

•	determine the visual position of the inspected data level in the data level navigator (DataLevel);

•	provide access to the data group associated with the inspected data level and the container for this data group (DataLevelObject and DataLevelObjectContainerKind).

Basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridChartDataLevelInfoHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxGridChartDataLevelInfoHitTest


Properties for TcxGridChartDataLevelInfoHitTest
TcxGridChartDataLevelInfoHitTest Properties

TcxGridChartDataLevelInfoHitTest          Legend

In TcxGridChartDataLevelInfoHitTest

DataLevel

DataLevelObject

DataLevelObjectContainerKind

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridChartDataLevelInfoHitTest
TcxGridChartDataLevelInfoHitTest Methods

TcxGridChartDataLevelInfoHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridChartDataLevelInfoHitTest.DataLevel

TcxGridChartDataLevelInfoHitTest          See Also

Returns the visual position of the inspected data level in the data level navigator.

property DataLevel: Integer;

Description

Use the DataLevelObject property to determine the data group associated with the inspected data level.


TcxGridChartDataLevelInfoHitTest.DataLevelObject

TcxGridChartDataLevelInfoHitTest          See Also

Determines the data group associated with the inspected data level.

property DataLevelObject: TcxGridChartDataGroup;

Description

The DataLevelObjectContainerKind field returns the container where the data group is located.

Use the DataLevel property to determine the visual position of the inspected data level.


TcxGridChartDataLevelInfoHitTest.DataLevelObjectContainerKind

TcxGridChartDataLevelInfoHitTest

Returns the container for the data group associated with the inspected data level.

type

  TcxGridChartDataGroupContainerKind = Integer;

DataLevelObjectContainerKind: TcxGridChartDataGroupContainerKind;

Description

The table below lists all the possible values for this field.

Value	Meaning
ckCustomizationForm	The data group is located in the Chart View’s customization form.
ckToolBox	The data group is located within a chart toolbox.
ckNone	The data group is located in neither of the above containers.

The data group can be accessed via the DataLevelObject property.  To determine the visual position of the inspected data level, use the DataLevel property.


TcxGridChartDataLevelActiveValueInfoHitTest
TcxGridChartDataLevelActiveValueInfoHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on a data level’s active value located at the point being tested.

Unit

cxGridChartView

TcxGridChartDataLevelActiveValueInfoHitTest = class(TcxGridChartDataLevelInfoHitTest)

Description

This class does not introduce any new functionality, but designates the hit code (equal to htDataLevelActiveValueInfo) for the inspected data level’s active value.

The data group associated with the inspected data level’s active value can be accessed via the DataLevelObject property.

Basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridChartDataLevelActiveValueInfoHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxGridChartDataLevelInfoHitTest

     |

TcxGridChartDataLevelActiveValueInfoHitTest


Properties for TcxGridChartDataLevelActiveValueInfoHitTest
TcxGridChartDataLevelActiveValueInfoHitTest Properties

TcxGridChartDataLevelActiveValueInfoHitTest          Legend

Derived from TcxGridChartDataLevelInfoHitTest

DataLevel

DataLevelObject

DataLevelObjectContainerKind

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridChartDataLevelActiveValueInfoHitTest
TcxGridChartDataLevelActiveValueInfoHitTest Methods

TcxGridChartDataLevelActiveValueInfoHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridChartToolBoxHitTest
TcxGridChartToolBoxHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on a chart toolbox located at the point being tested.

Unit

cxGridChartView

TcxGridChartToolBoxHitTest = class(TcxCustomGridViewHitTest)

Description

This class does not introduce any new functionality, but designates the hit code (equal to htChartToolBox) for the inspected chart toolbox.

Basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridChartToolBoxHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxGridChartToolBoxHitTest


Properties for TcxGridChartToolBoxHitTest
TcxGridChartToolBoxHitTest Properties

TcxGridChartToolBoxHitTest          Legend

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridChartToolBoxHitTest
TcxGridChartToolBoxHitTest Methods

TcxGridChartToolBoxHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridChartCustomizeButtonHitTest
TcxGridChartCustomizeButtonHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the chart customization button located at the point being tested.

Unit

cxGridChartView

TcxGridChartCustomizeButtonHitTest = class(TcxCustomGridViewHitTest)

Description

This class does not introduce any new functionality, but designates the hit code (equal to htChartCustomizeButton) for the inspected chart customization button.

Basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridChartCustomizeButtonHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxGridChartCustomizeButtonHitTest


Properties for TcxGridChartCustomizeButtonHitTest
TcxGridChartCustomizeButtonHitTest Properties

TcxGridChartCustomizeButtonHitTest          Legend

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridChartCustomizeButtonHitTest
TcxGridChartCustomizeButtonHitTest Methods

TcxGridChartCustomizeButtonHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxCustomGridChartDiagramHitTest
TcxCustomGridChartDiagramHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on the diagram whose visual element is located at the point being tested.

Unit

cxGridChartView

TcxCustomGridChartDiagramHitTest = class(TcxCustomGridViewHitTest)

Description

The TcxCustomGridChartDiagramHitTest class extends its ancestor class with the Diagram field that provides access to the diagram whose visual element is located at the point being tested.  Descendants of the TcxCustomGridChartDiagramHitTest class provide information specific to the diagram element they correspond to.

Basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxCustomGridChartDiagramHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxCustomGridChartDiagramHitTest


Properties for TcxCustomGridChartDiagramHitTest
TcxCustomGridChartDiagramHitTest Properties

TcxCustomGridChartDiagramHitTest          Legend

In TcxCustomGridChartDiagramHitTest

Diagram

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxCustomGridChartDiagramHitTest
TcxCustomGridChartDiagramHitTest Methods

TcxCustomGridChartDiagramHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxCustomGridChartDiagramHitTest.Diagram

TcxCustomGridChartDiagramHitTest

Specifies the diagram whose visual element is located at the point being tested.

Diagram: TcxGridChartDiagram;

Description

Use this field to access the diagram whose visual element is located at the Chart View’s point being tested.


TcxGridChartPieSeriesSiteHitTest
TcxGridChartPieSeriesSiteHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on a pie diagram’s series site located at the point being tested.

Unit

cxGridChartView

TcxGridChartPieSeriesSiteHitTest = class(TcxCustomGridChartDiagramHitTest)

Description

In addition to the settings inherited from the base TcxCustomGridChartDiagramHitTest class, the TcxGridChartPieSeriesSiteHitTest introduces members that are used to:

•	designate the hit code (equal to htSeriesSite) for the inspected series site;

•	provide access to the series displayed by the series site (Series).

Basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridChartPieSeriesSiteHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxCustomGridChartDiagramHitTest

     |

TcxGridChartPieSeriesSiteHitTest


Properties for TcxGridChartPieSeriesSiteHitTest
TcxGridChartPieSeriesSiteHitTest Properties

TcxGridChartPieSeriesSiteHitTest          Legend

In TcxGridChartPieSeriesSiteHitTest

Series

Derived from TcxCustomGridChartDiagramHitTest

Diagram

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridChartPieSeriesSiteHitTest
TcxGridChartPieSeriesSiteHitTest Methods

TcxGridChartPieSeriesSiteHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridChartPieSeriesSiteHitTest.Series

TcxGridChartPieSeriesSiteHitTest          See Also

Provides access to the series displayed by the inspected series site.

Series: TcxGridChartSeries;


TcxGridChartPieSeriesSiteCaptionHitTest
TcxGridChartPieSeriesSiteCaptionHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on a pie diagram’s series site caption located at the point being tested.

Unit

cxGridChartView

TcxGridChartPieSeriesSiteCaptionHitTest = class(TcxGridChartPieSeriesSiteHitTest)

Description

This class does not introduce any new functionality, but designates the hit code (equal to htSeriesSiteCaption) for the inspected series site caption.

Basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridChartPieSeriesSiteCaptionHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxCustomGridChartDiagramHitTest

     |

TcxGridChartPieSeriesSiteHitTest

     |

TcxGridChartPieSeriesSiteCaptionHitTest


Properties for TcxGridChartPieSeriesSiteCaptionHitTest
TcxGridChartPieSeriesSiteCaptionHitTest Properties

TcxGridChartPieSeriesSiteHitTest          Legend

Derived from TcxGridChartPieSeriesSiteHitTest

Series

Derived from TcxCustomGridChartDiagramHitTest

Diagram

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridChartPieSeriesSiteCaptionHitTest
TcxGridChartPieSeriesSiteCaptionHitTest Methods

TcxGridChartPieSeriesSiteHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridChartValueLineHitTest
TcxGridChartValueLineHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on a line diagram’s data marker located at the point being tested.

Unit

cxGridChartView

TcxGridChartValueLineHitTest = class(TcxGridChartValueHitTest)

Description

This class does not introduce any new functionality, but designates the hit code (equal to htChartValueLine) for the inspected data marker.

Basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridChartValueLineHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxGridChartValueHitTest

     |

TcxGridChartValueLineHitTest


Properties for TcxGridChartValueLineHitTest
TcxGridChartValueLineHitTest Properties

TcxGridChartValueLineHitTest          Legend

Derived from TcxGridChartValueHitTest

CanDrillDown

Series

ValueIndex

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridChartValueLineHitTest
TcxGridChartValueLineHitTest Methods

TcxGridChartValueLineHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridChartValueAreaHitTest
TcxGridChartValueAreaHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on an area diagram’s data marker located at the point being tested.

Unit

cxGridChartView

TcxGridChartValueAreaHitTest = class(TcxGridChartValueHitTest)

Description

This class does not introduce any new functionality, but designates the hit code (equal to htChartValueArea) for the inspected data marker.

Basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridChartValueAreaHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxGridChartValueHitTest

     |

TcxGridChartValueAreaHitTest


Properties for TcxGridChartValueAreaHitTest
TcxGridChartValueAreaHitTest Properties

TcxGridChartValueAreaHitTest          Legend

Derived from TcxGridChartValueHitTest

CanDrillDown

Series

ValueIndex

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridChartValueAreaHitTest
TcxGridChartValueAreaHitTest Methods

TcxGridChartValueAreaHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxCustomGridChartHistogramAxisHitTest
TcxCustomGridChartHistogramAxisHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on an axis in a chart diagram located at the point being tested.

Unit

cxGridChartView

TcxCustomGridChartHistogramAxisHitTest = class(TcxCustomGridChartDiagramHitTest)

Description

This class does not introduce any new functionality.  Descendants of this class provide information specific to the axis element they correspond to.

Basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxCustomGridChartHistogramAxisHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxCustomGridChartDiagramHitTest

     |

TcxCustomGridChartHistogramAxisHitTest


Properties for TcxCustomGridChartHistogramAxisHitTest
TcxCustomGridChartHistogramAxisHitTest Properties

TcxCustomGridChartHistogramAxisHitTest          Legend

Derived from TcxCustomGridChartDiagramHitTest

Diagram

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxCustomGridChartHistogramAxisHitTest
TcxCustomGridChartHistogramAxisHitTest Methods

TcxCustomGridChartHistogramAxisHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridChartHistogramCategoryAxisTitleHitTest
TcxGridChartHistogramCategoryAxisTitleHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on a category axis title located at the point being tested.

Unit

cxGridChartView

TcxGridChartHistogramCategoryAxisTitleHitTest = class(TcxCustomGridChartHistogramAxisHitTest)

Description

This class does not introduce any new functionality, but designates the hit code (equal to htCategoryAxisTitle) for the inspected category axis title.

Basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridChartHistogramCategoryAxisTitleHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxCustomGridChartDiagramHitTest

     |

TcxCustomGridChartHistogramAxisHitTest

     |

TcxGridChartHistogramCategoryAxisTitleHitTest


Properties for TcxGridChartHistogramCategoryAxisTitleHitTest
TcxGridChartHistogramCategoryAxisTitleHitTest Properties

TcxGridChartHistogramCategoryAxisTitleHitTest          Legend

Derived from TcxCustomGridChartDiagramHitTest

Diagram

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridChartHistogramCategoryAxisTitleHitTest
TcxGridChartHistogramCategoryAxisTitleHitTest Methods

TcxGridChartHistogramCategoryAxisTitleHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridChartHistogramValueAxisTitleHitTest
TcxGridChartHistogramValueAxisTitleHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on a value axis title located at the point being tested.

Unit

cxGridChartView

TcxGridChartHistogramValueAxisTitleHitTest = class(TcxCustomGridChartHistogramAxisHitTest)

Description

This class does not introduce any new functionality, but designates the hit code (equal to htValueAxisTitle) for the inspected value axis title.

Basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridChartHistogramValueAxisTitleHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxCustomGridChartDiagramHitTest

     |

TcxCustomGridChartHistogramAxisHitTest

     |

TcxGridChartHistogramValueAxisTitleHitTest


Properties for TcxGridChartHistogramValueAxisTitleHitTest
TcxGridChartHistogramValueAxisTitleHitTest Properties

TcxGridChartHistogramValueAxisTitleHitTest          Legend

Derived from TcxCustomGridChartDiagramHitTest

Diagram

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridChartHistogramValueAxisTitleHitTest
TcxGridChartHistogramValueAxisTitleHitTest Methods

TcxGridChartHistogramValueAxisTitleHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridChartHistogramPlotHitTest
TcxGridChartHistogramPlotHitTest Object

Hierarchy          Properties          Methods          See Also

Provides general information on a chart’s plot area located at the point being tested.

Unit

cxGridChartView

TcxGridChartHistogramPlotHitTest = class(TcxCustomGridChartDiagramHitTest)

Description

This class does not introduce any new functionality, but designates the hit code (equal to htPlot) for the inspected chart’s plot area.

Basic HitTest concepts are described in the description of the TcxCustomGridHitTest class.


TcxGridChartHistogramPlotHitTest Hierarchy
Hierarchy

TObject

     |

TcxCustomGridHitTest

     |

TcxCustomGridViewHitTest

     |

TcxCustomGridChartDiagramHitTest

     |

TcxGridChartHistogramPlotHitTest


Properties for TcxGridChartHistogramPlotHitTest
TcxGridChartHistogramPlotHitTest Properties

TcxCustomGridChartDiagramHitTest          Legend

Derived from TcxCustomGridChartDiagramHitTest

Diagram

Derived from TcxCustomGridViewHitTest

GridView

Derived from TcxCustomGridHitTest

Pos

ViewInfo


Methods for TcxGridChartHistogramPlotHitTest
TcxGridChartHistogramPlotHitTest Methods

TcxCustomGridChartDiagramHitTest          Legend

Derived from TcxCustomGridHitTest

Cursor

HitTestCode


TcxGridChartHistogramStyles
TcxGridChartHistogramStyles Object

Hierarchy          Properties          Methods          See Also

Represents a set of styles that manage the appearance of all diagrams that provide axes for chart value measurements and comparisons.

Unit

cxGridChartView

TcxGridChartHistogramStyles = class(TcxGridChartDiagramStyles)

Description

In addition to the settings inherited from the base TcxGridChartDiagramStyles class, the TcxGridChartHistogramStyles class introduces properties that allow you to specify style attributes for:

•	all axes (Axis) and specifically for a category axis and value axis (CategoryAxis and ValueAxis);

•	axis titles (AxisTitle) and titles specifically for category and value axes (CategoryAxisTitle and ValueAxisTitle);

•	all chart gridlines (GridLines) and specifically for gridlines of category and value axes (CategoryGridLines and ValueGridLines);

•	a chart’s plot area (Plot).

To apply this set of styles to a diagram, use the diagram’s Styles property.


TcxGridChartHistogramStyles Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomStyles

     |

TcxStyles

     |

TcxCustomGridStyles

     |

TcxGridChartDiagramStyles

     |


Properties for TcxGridChartHistogramStyles
TcxGridChartHistogramStyles Properties

TcxGridChartHistogramStyles          Legend

In TcxGridChartHistogramStyles

Axis

AxisTitle

CategoryAxis

CategoryAxisTitle

CategoryGridLines

GridLines

Plot

ValueAxis

ValueAxisTitle

ValueGridLines

Derived from TcxGridChartDiagramStyles

Diagram

GridView

Legend

ValueCaptions

Values

Derived from TcxCustomGridStyles

GridView

Derived from TcxCustomStyles

StyleSheet


Methods for TcxGridChartHistogramStyles
TcxGridChartHistogramStyles Methods

TcxGridChartHistogramStyles          Legend

Derived from TcxCustomStyles

Assign

Create

Destroy


TcxGridChartHistogramStyles.Axis

TcxGridChartHistogramStyles          See Also

Specifies the style for all axes and their elements within a diagram.

property Axis: TcxStyle;

Description

Use this property to specify the following style attributes:

•	the color of axes and their tick marks;

•	font settings of tick-mark labels.

Note:	The style options specified for a specific axis (via the CategoryAxis or ValueAxis property) override the corresponding style settings set via the Axis property.


TcxGridChartHistogramStyles.AxisTitle

TcxGridChartHistogramStyles          See Also

Specifies the foreground color and font settings for all axis titles within a diagram.

property AxisTitle: TcxStyle;

Description

The style options specified for a specific axis title (via the CategoryAxisTitle or ValueAxisTitle property) override the corresponding style settings set via the AxisTitle property.


TcxGridChartHistogramStyles.CategoryAxis

TcxGridChartHistogramStyles          See Also

Specifies the style for a category axis and its elements.

property CategoryAxis: TcxStyle;

Description

Use this property to specify the following style attributes:

•	the color of a category axis and its tick marks;

•	font settings of tick-mark labels.

Note:	The style options specified via the CategoryAxis property override the corresponding style settings set via the Axis property.


TcxGridChartHistogramStyles.CategoryAxisTitle

TcxGridChartHistogramStyles          See Also

Specifies the foreground color and font settings for a category axis title.

property CategoryAxisTitle: TcxStyle;

Description

The style options specified via this property override the corresponding style settings set via the AxisTitle property.


TcxGridChartHistogramStyles.CategoryGridLines

TcxGridChartHistogramStyles          See Also

Specifies the color for category axis gridlines.

property CategoryGridLines: TcxStyle;

Description

The style options specified via this property override the corresponding style settings set via the GridLines property.


TcxGridChartHistogramStyles.GridLines

TcxGridChartHistogramStyles          See Also

Specifies the color for all chart gridlines within a diagram.

property GridLines: TcxStyle;

Description

The style options specified for chart gridlines of a specific axis (via the CategoryGridLines or ValueGridLines property) override the corresponding style settings set via the GridLines property.


TcxGridChartHistogramStyles.Plot

TcxGridChartHistogramStyles          See Also

Specifies the background color or bitmap for a chart’s plot area.

property Plot: TcxStyle;

Description

Handle the OnCustomDrawPlot event to custom paint a diagram’s plot area.


TcxGridChartHistogramStyles.ValueAxis

TcxGridChartHistogramStyles          See Also

Specifies the style for a value axis.

property ValueAxis: TcxStyle;

Description

Use this property to specify the following style attributes:

•	the color of a value axis and its tick marks;

•	font settings of tick-mark labels.

Note:	The style options specified via the ValueAxis property override the corresponding style settings set via the Axis property.


TcxGridChartHistogramStyles.ValueAxisTitle

TcxGridChartHistogramStyles          See Also

Specifies the foreground color and font settings for a value axis title.

property ValueAxisTitle: TcxStyle;

Description

The style options specified via this property override the corresponding style settings set via the AxisTitle property.


TcxGridChartHistogramStyles.ValueGridLines

TcxGridChartHistogramStyles          See Also

Specifies the color for value axis gridlines.

property ValueGridLines: TcxStyle;

Description

The style options specified via this property override the corresponding style settings set via the GridLines property.


TcxGridChartLineDiagramStyles
TcxGridChartLineDiagramStyles Object

Hierarchy          Properties          Methods          See Also

Represents a set of styles that manage the appearance of line diagram elements.

Unit

cxGridChartView

TcxGridChartLineDiagramStyles = class(TcxGridChartHistogramStyles)

Description

In addition to the settings inherited from the base TcxGridChartHistogramStyles class, the TcxGridChartLineDiagramStyles class introduces the ValueMarkers property that allows you to customize the color of value markers and their borderlines in a line diagram.

To apply this set of styles to a line diagram, use the diagram’s Styles property.


TcxGridChartLineDiagramStyles Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomStyles

     |

TcxStyles

     |

TcxCustomGridStyles

     |

TcxGridChartDiagramStyles

     |

TcxGridChartHistogramStyles

     |


Properties for TcxGridChartLineDiagramStyles
TcxGridChartLineDiagramStyles Properties

TcxGridChartHistogramStyles          Legend

In TcxGridChartLineDiagramStyles

ValueMarkers

Derived from TcxGridChartHistogramStyles

Axis

AxisTitle

CategoryAxis

CategoryAxisTitle

CategoryGridLines

GridLines

Plot

ValueAxis

ValueAxisTitle

ValueGridLines

Derived from TcxGridChartDiagramStyles

Diagram

GridView

Legend

ValueCaptions

Values

Derived from TcxCustomGridStyles

GridView

Derived from TcxCustomStyles

StyleSheet


Methods for TcxGridChartLineDiagramStyles
TcxGridChartLineDiagramStyles Methods

TcxGridChartHistogramStyles          Legend

Derived from TcxCustomStyles

Assign

Create

Destroy


TcxGridChartLineDiagramStyles.ValueMarkers

TcxGridChartHistogramStyles          See Also

Specifies the color for value markers and their borderlines.

property ValueMarkers: TcxStyle;

Description

Borderlines within line diagrams are not painted unless their color is explicitly specified via the ValueMarkers.TextColor property.


TcxGridChartAreaDiagramStyles
TcxGridChartAreaDiagramStyles Object

Hierarchy          Properties          Methods          See Also

Represents a set of styles that manage the appearance of area diagram elements.

Unit

cxGridChartView

TcxGridChartAreaDiagramStyles = class(TcxGridChartLineDiagramStyles)

Description

This class does not introduce any new functionality but enables area diagrams to draw borderlines for value markers by default.

Use the ValueMarkers property to customize the color of value markers and their borderlines.

To apply this set of styles to an area diagram, use the diagram’s Styles property.


TcxGridChartAreaDiagramStyles Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomStyles

     |

TcxStyles

     |

TcxCustomGridStyles

     |

TcxGridChartDiagramStyles

     |

TcxGridChartHistogramStyles

     |

TcxGridChartLineDiagramStyles

     |


Properties for TcxGridChartAreaDiagramStyles
TcxGridChartAreaDiagramStyles Properties

TcxGridChartAreaDiagramStyles          Legend

Derived from TcxGridChartLineDiagramStyles

ValueMarkers

Derived from TcxGridChartHistogramStyles

Axis

AxisTitle

CategoryAxis

CategoryAxisTitle

CategoryGridLines

GridLines

Plot

ValueAxis

ValueAxisTitle

ValueGridLines

Derived from TcxGridChartDiagramStyles

Diagram

GridView

Legend

ValueCaptions

Values

Derived from TcxCustomGridStyles

GridView

Derived from TcxCustomStyles

StyleSheet


Methods for TcxGridChartAreaDiagramStyles
TcxGridChartAreaDiagramStyles Methods

TcxGridChartAreaDiagramStyles          Legend

Derived from TcxCustomStyles

Assign

Create

Destroy


TcxGridChartDiagramStyles
TcxGridChartDiagramStyles Object

Hierarchy          Properties          Methods          See Also

Represents a set of styles that manage the appearance of a generic diagram in a Chart View.

Unit

cxGridChartView

TcxGridChartDiagramStyles = class(TcxCustomGridStyles)

Description

The TcxGridChartDiagramStyles class defines a set of properties and methods for specifying and determining the appearance aspects of a generic chart diagram’s visual elements such as its data markers, their captions, and a chart legend.  To set the styles for a chart diagram in a Chart View, use the TcxGridChartDiagram.Styles property.


TcxGridChartDiagramStyles Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomStyles

     |

TcxStyles

     |

TcxCustomGridStyles

     |


Properties for TcxGridChartDiagramStyles
TcxGridChartDiagramStyles Properties

TcxGridChartDiagramStyles          Legend

In TcxGridChartDiagramStyles

Diagram

GridView

Legend

ValueCaptions

Values

Derived from TcxCustomGridStyles

GridView

Derived from TcxCustomStyles

StyleSheet


Methods for TcxGridChartDiagramStyles
TcxGridChartDiagramStyles Methods

TcxGridChartDiagramStyles          Legend

Derived from TcxCustomStyles

Assign

Create

Destroy


TcxGridChartDiagramStyles.Diagram

TcxGridChartDiagramStyles          See Also

Provides access to the chart diagram, to whose elements the set of styles is applied.

property Diagram: TcxGridChartDiagram;

Description

Use the Diagram property to access the chart diagram to whose elements the set of styles is applied.  This property provides access to the diagram’s legend, style sets, etc.

ReadOnly Property


TcxGridChartDiagramStyles.GridView

TcxGridChartDiagramStyles          See Also

Provides access to the Chart View which displays the chart diagram.

property GridView: TcxGridChartView;

Description

Use the GridView property to access the Chart View which displays the chart diagram.  This property provides access to the View items, style sets, etc.

ReadOnly Property


TcxGridChartDiagramStyles.Legend

TcxGridChartDiagramStyles          See Also

Specifies the style of a chart legend.

property Legend: TcxStyle;

Description

The Legend property allows you to define the style (font settings and background color) of the chart legend’s elements (the border of a chart legend’s area, the border of a legend key and its description) within the chart diagram.

Note:	The style options specified by the chart diagram’s Legend property override the style settings which were set via the Chart View’s Legend property.


TcxGridChartDiagramStyles.ValueCaptions

TcxGridChartDiagramStyles          See Also

Specifies the style for the captions of values.

property ValueCaptions: TcxStyle;

Description

The ValueCaptions property allows you to define the style (font settings) for the captions of the values (i.e. the data markers) within a chart diagram.  The chart diagram’s CaptionPosition property controls the position at which the captions are displayed within the chart diagram.


TcxGridChartDiagramStyles.Values

TcxGridChartDiagramStyles          See Also

Specifies the generic style for values (their data markers).

property Values: TcxStyle;

Description

The Values property allows you to define the style of the values (their data markers) of a specific series and font settings for the corresponding value hints within a diagram.  Use the Values.TextColor Values.TextColor, Values.Color and Values.Bitmap properties to specify the border color, the background color and the background bitmap of the data markers, respectively.

Each series within a chart has a predefined default color for its data markers (which is applied when no style is defined for the series values in the series).  The default color is determined using the Order property’s value of the series.

Note:	The style options specified for data markers within a diagram via the diagram’s Styles.Values property override the style settings for specific values which were set via the Styles.Values property of the corresponding series.


TcxGridChartSeriesStyles
TcxGridChartSeriesStyles Object

Hierarchy          Properties          Methods          Events          See Also

Represents a set of styles which manage the appearance of a series in a Chart View.

Unit

cxGridChartView

TcxGridChartSeriesStyles = class(TcxCustomGridStyles)

Description

The TcxGridChartSeriesStyles class extends its ancestor class with the Values property which contains the styles for the data markers of the series values.  To set the styles for a specific series in a Chart View, use the Styles property of the series.

Note:	The style options specified for data markers within a diagram via the diagram’s Styles.Values property override the style settings for specific values which were set via the Styles.Values property of a particular series.


TcxGridChartSeriesStyles Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomStyles

     |

TcxStyles

     |

TcxCustomGridStyles

     |


Properties for TcxGridChartSeriesStyles
TcxGridChartSeriesStyles Properties

TcxGridChartSeriesStyles          Legend

In TcxGridChartSeriesStyles

Series

Values

Derived from TcxGridChartDiagramStyles

Diagram

GridView

Legend

ValueCaptions

Values

Derived from TcxCustomGridStyles

GridView

Derived from TcxCustomStyles

StyleSheet


Methods for TcxGridChartSeriesStyles
TcxGridChartSeriesStyles Methods

TcxGridChartSeriesStyles          Legend

Derived from TcxCustomStyles

Assign

Create

Destroy


Events for TcxGridChartSeriesStyles
TcxGridChartSeriesStyles Events

TcxGridChartSeriesStyles          Legend

In TcxGridChartSeriesStyles

OnGetValueStyle


TcxGridChartSeriesStyles.Series

TcxGridChartSeriesStyles          See Also

Provides access to the series, to whose values the set of styles is applied.

property Series: TcxGridChartSeries;

Description

Use the Series property to access the series to whose values (data markers) the set of styles is applied.  This property provides access to the values of the series, other options, style sets, etc.

ReadOnly Property


TcxGridChartSeriesStyles.Values

TcxGridChartSeriesStyles          See Also

Specifies the style of the values (their data markers) in a specific series.

property Values: TcxStyle;

Description

The Values property allows you to define the style of the values (data markers) in a specific series, and font settings for the corresponding value hints.  Use the Values.TextColor, Values.Color and Values.Bitmap properties to specify the border color, the background color and the background bitmap of the data markers, respectively.

Each series within a chart has a predefined default color for its data markers (which is applied when no style is defined for the series values of the series).  The default color is determined using the Order property’s value of a series.

Note:	The style options specified for data markers within a diagram via the diagram’s Styles.Values property override the style settings for specific values which were set via the Styles.Values property of a particular series.


TcxGridChartSeriesStyles.OnGetValueStyle

TcxGridChartSeriesStyles          See Also

Occurs whenever a series value (its data marker) should be redrawn.

type

  TcxGridChartSeriesGetValueStyleEvent = procedure(Sender: TcxGridChartSeries; AValueIndex: Integer; var AStyle: TcxStyle) of object;

property OnGetValueStyle: TcxGridChartSeriesGetValueStyleEvent;

Description

You can handle the OnGetValueStyle event to modify the style (the border color, the background color and the background bitmap of the data markers and font settings for the corresponding value hints) for individual series value.  This event occurs every time a series value (its data marker) of the series specified by the Sender parameter needs to be redrawn.  The series value that corresponds to the data marker being redrawn is addressed by the AValueIndex parameter which represents the index of the series value in the Values collection.  The style which is returned via the AStyle parameter overrides the styles for the series values defined by the Styles.Values properties of the corresponding series.


TcxGridChartViewStyles
TcxGridChartViewStyles Object

Hierarchy          Properties          Methods          See Also

Represents a set of styles which manage the appearance aspects of the elements of a Chart View.

Unit

cxGridChartView

TcxGridChartViewStyles = class(TcxCustomGridViewStyles)

Description

The TcxGridChartViewStyles class represents a set of styles which manage the appearance aspects of the elements of a Chart View such as a chart toolbox and its customization tools, chart legend, chart title, and the area of the Chart View which excludes the chart’s plot area.  Use the ToolBox, DataLevelsInfo, DiagramSelector, Legend, Title, and Background properties to access the corresponding styles, respectively.

Note:	The style options specified for the chart legend within a diagram via the diagram’s Styles.Legend property override the style settings which were set via the View’s Styles.Legend property.

The functionality of the TcxGridChartViewStyles class can be accessed via the View’s Styles property.


TcxGridChartViewStyles Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomStyles

     |

TcxStyles

     |

TcxCustomGridStyles

     |

TcxCustomGridViewStyles

     |

TcxGridChartViewStyles


Properties for TcxGridChartViewStyles
TcxGridChartViewStyles Properties

TcxGridChartViewStyles          Legend

In TcxGridChartViewStyles

ActiveDataLevelInfo

DataLevelActiveValueInfo

DataLevelsInfo

DiagramSelector

GridView

Legend

Title

ToolBox

Derived from TcxCustomGridViewStyles

Background

Derived from TcxCustomGridStyles

GridView

Derived from TcxCustomStyles

StyleSheet


Methods for TcxGridChartViewStyles
TcxGridChartViewStyles Methods

TcxGridChartViewStyles          Legend

In TcxGridChartViewStyles

GetDataLevelInfoParams

Derived from TcxCustomStyles

Assign

Create

Destroy


TcxGridChartViewStyles.ActiveDataLevelInfo

TcxGridChartViewStyles          See Also

Specifies font settings, the foreground color, and background color or a bitmap for an active data level’s label.

property ActiveDataLevelInfo: TcxStyle;

Description

Use the DataLevelsInfo property to specify style settings for the data level navigator.


TcxGridChartViewStyles.DataLevelActiveValueInfo

TcxGridChartViewStyles          See Also

Specifies font settings, the foreground color, and background color or a bitmap for an active data level value.

property DataLevelActiveValueInfo: TcxStyle;

Description

Use the DataLevelsInfo property to specify style settings for the data level navigator.


TcxGridChartViewStyles.DataLevelsInfo

TcxGridChartViewStyles          See Also

Specifies font settings, the foreground color, and background color or a bitmap for the data level navigator.

property DataLevelsInfo: TcxStyle;

Description

Use the ActiveDataLevelInfo and DataLevelActiveValueInfo properties to control appearance aspects of an active data level and data level active values, respectively.

Note:	The general appearance of the data level navigator in a chart toolbox is controlled by the View’s ToolBox.DataLevelsInfoVisible property.


TcxGridChartViewStyles.DiagramSelector

TcxGridChartViewStyles

Specifies the foreground color and font settings for the diagram selector.

property DiagramSelector: TcxStyle;

Description

The general appearance of the data level navigator in a chart toolbox is controlled by the View’s ToolBox.DiagramSelector property.


TcxGridChartViewStyles.GridView

TcxGridChartViewStyles

Provides access to the Chart View to which the set of styles is applied.

property GridView: TcxGridChartView;

ReadOnly Property


TcxGridChartViewStyles.Legend

TcxGridChartViewStyles          See Also

Specifies the style of a chart legend.

property Legend: TcxStyle;

Description

The Legend property allows you to define the style (font settings and background color or bitmap) of the chart legend’s elements (the border of a chart legend’s area, the border of a legend key and its description) within the chart diagram.

Note:	The style options specified by the chart diagram’s Legend property override the style settings which were set via the Chart View’s Legend property.


TcxGridChartViewStyles.Title

TcxGridChartViewStyles          See Also

Specifies the style of the chart title.

property Title: TcxStyle;

Description

The Title property allows you to define the style (font settings) of a chart title.


TcxGridChartViewStyles.ToolBox

TcxGridChartViewStyles          See Also

Specifies the style for a chart toolbox.

property ToolBox: TcxStyle;

Description

This property allows you to specify the following style attributes of a chart toolbox:

•	the background color or a bitmap;

•	font settings, the foreground color, and background color or a bitmap of the diagram selector and data level navigator together with its elements.

Note:	The general appearance of a chart toolbox is controlled by the View’s ToolBox.Visible property.


TcxGridChartViewStyles.GetDataLevelInfoParams

TcxGridChartViewStyles          See Also

Obtains the TcxViewParams record that contains information on style attributes of data levels in a chart toolbox.

procedure GetDataLevelInfoParams(ADataLevel: Integer; out AParams: TcxViewParams); virtual;

Description

The ADataLevel parameter identifies the data level by its on-screen position.

The AParams parameter returns style attributes that the GetDataLevelInfoParams method results in.


TcxGridChartPieDiagramStyles
TcxGridChartPieDiagramStyles Object

Hierarchy          Properties          Methods          See Also

Represents a set of styles that manage the appearance of pie diagram elements.

Unit

cxGridChartView

TcxGridChartPieDiagramStyles = class(TcxGridChartDiagramStyles)

Description

In addition to the settings inherited from the base TcxGridChartDiagramStyles class, the TcxGridChartPieDiagramStyles class introduces the SeriesSites and SeriesSiteCaptions properties that allow you to specify the appearance of series sites and their captions, respectively.

To apply this set of styles to a pie diagram, use the diagram’s Styles property.


TcxGridChartPieDiagramStyles Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomStyles

     |

TcxStyles

     |

TcxCustomGridStyles

     |

TcxGridChartDiagramStyles

     |


Properties for TcxGridChartPieDiagramStyles
TcxGridChartPieDiagramStyles Properties

TcxGridChartPieDiagramStyles          Legend

In TcxGridChartPieDiagramStyles

SeriesSiteCaptions

SeriesSites

Derived from TcxGridChartDiagramStyles

Diagram

GridView

Legend

ValueCaptions

Values

Derived from TcxCustomGridStyles

GridView

Derived from TcxCustomStyles

StyleSheet


Methods for TcxGridChartPieDiagramStyles
TcxGridChartPieDiagramStyles Methods

TcxGridChartPieDiagramStyles          Legend

Derived from TcxCustomStyles

Assign

Create

Destroy


TcxGridChartPieDiagramStyles.SeriesSiteCaptions

TcxGridChartPieDiagramStyles          See Also

Specifies font settings, the foreground color, and background color or a bitmap for series site captions.

property SeriesSiteCaptions: TcxStyle;


TcxGridChartPieDiagramStyles.SeriesSites

TcxGridChartPieDiagramStyles          See Also

Specifies the style for series sites.

property SeriesSites: TcxStyle;

Description

Use this property to specify the following style attributes:

•	the background color or a bitmap of series sites;

•	the color of series site borderlines.


TcxCustomGridChartDiagramOptions
TcxCustomGridChartDiagramOptions Object

Hierarchy          Properties

Contains options which control various appearance aspects of a chart diagram.

Unit

cxGridChartView

TcxCustomGridChartDiagramOptions = class(TPersistent)

Description

The TcxCustomGridChartDiagramOptions class is the base class for classes which represent option sets that are specific to the visual elements of chart diagrams such as the axes and series values.  The TcxCustomGridChartDiagramOptions class publishes the Diagram and GridView properties, which correspond to the chart diagram whose option settings are addressed by the current class instance and the View which displays the chart diagram, respectively.


TcxCustomGridChartDiagramOptions Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxCustomGridChartDiagramOptions
TcxCustomGridChartDiagramOptions Properties

TcxCustomGridChartDiagramOptions          Legend

In TcxCustomGridChartDiagramOptions

Diagram

GridView


TcxCustomGridChartDiagramOptions.Diagram

TcxCustomGridChartDiagramOptions          See Also

Provides access to the chart diagram which owns the options that are referenced by the current instance of the class.

property Diagram: TcxGridChartDiagram;

ReadOnly Property


TcxCustomGridChartDiagramOptions.GridView

TcxCustomGridChartDiagramOptions

Provides access to the Chart View which displays the chart diagram that owns the options that are referenced by the current instance of the class.

property GridView: TcxGridChartView;

ReadOnly Property


TcxCustomGridChartTitle
TcxCustomGridChartTitle Object

Hierarchy          Properties          Methods          See Also

Represents the base class for the titles displayed in charts.

Unit

cxGridChartView

TcxCustomGridChartTitle = class(TcxCustomGridOptions)

Description

A standard title in a chart represents a string which describes a specific area or element such as a chart’s title or axis title.  The TcxCustomGridChartTitle class provides the properties and methods that are used to specify the text string for a title's text, arrange it within a chart and determine its current position within the chart.  All the properties which control the appearance aspects such as the position and alignment of the title's text are initialized with default values that provide a standard appearance for charts.


TcxCustomGridChartTitle Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |

TcxCustomGridChartTitle


Properties for TcxCustomGridChartTitle
TcxCustomGridChartTitle Properties

TcxCustomGridChartTitle          Legend

In TcxCustomGridChartTitle

Alignment

 	Position

Text

Derived from TcxCustomGridOptions

GridView


Methods for TcxCustomGridChartTitle
TcxCustomGridChartTitle Methods

TcxCustomGridChartTitle          Legend

In TcxCustomGridChartTitle

GetAlignment

GetOrientation

GetPosition

GetText


TcxCustomGridChartTitle.Alignment

TcxCustomGridChartTitle          See Also

Specifies the alignment applied to the title's text.

type

  TcxGridChartPartAlignment = (cpaDefault, cpaStart, cpaCenter, cpaEnd);

property Alignment: TcxGridChartPartAlignment;

Description

Set the Alignment property to apply a specific alignment to the title text.  All the possible values for this property are listed in the TcxGridChartPartAlignment type topic.

The default value of the Alignment property is cpaDefault.


TcxCustomGridChartTitle.Position

TcxCustomGridChartTitle          See Also

Specifies the position of the title text within the chart.

type

  TcxGridChartPartPosition = (cppDefault, cppNone, cppLeft, cppTop, cppRight, cppBottom);

property Position: TcxGridChartPartPosition;

Description

Set the Position property to designate the visual position of the text title within the chart.  All the possible values for this property are listed in the TcxGridChartPartPosition type topic.

The default value of the Position property is cppDefault.


TcxCustomGridChartTitle.Text

TcxCustomGridChartTitle

Specifies the text string of the title text.

property Text: string;

Description

Set the Text property to specify the text which will appear as the title in the chart.  The title text is not displayed unless its Text property is set.  If this property is assigned an empty string, the default text will be displayed as the title text.  TcxCustomGridChartTitle descendants provide their own values as the default texts.  To get the text which is displayed as the title, use the GetText function.

Use the title text’s Alignment and Position properties to manage its appearance aspects within the chart.


TcxCustomGridChartTitle.GetAlignment

TcxCustomGridChartTitle

Determines the alignment of the title text.

type

  TcxGridChartPartAlignment = (cpaDefault, cpaStart, cpaCenter, cpaEnd);

function GetAlignment: TcxGridChartPartAlignment;

Description

Call the GetAlignment function to determine the alignment of the title text within the chart.  Use the Alignment property to apply a specific alignment to the title text.


TcxCustomGridChartTitle.GetOrientation

TcxCustomGridChartTitle

Determines the orientation of the title text.

type

  TcxGridChartPartOrientation = (cpoDefault, cpoHorizontal, cpoVertical);

function GetOrientation: TcxGridChartPartOrientation;

Description

Call the GetOrientation function to determine the orientation of the title text within the chart.  The default orientation is determined using the current position of the title text which can be set via the Position property.


TcxCustomGridChartTitle.GetPosition

TcxCustomGridChartTitle

Determines the position of the title text.

type

  TcxGridChartPartPosition = (cppDefault, cppNone, cppLeft, cppTop, cppRight, cppBottom);

function GetPosition: TcxGridChartPartPosition;

Description

Call the GetPosition function to determine the position of the title text within the chart.  Use the Position property to designate the specific position of the title text.


TcxCustomGridChartTitle.GetText

TcxCustomGridChartTitle

Returns the text displayed as a title.

function GetText: string;

Description

By default, this function returns the text specified via the Text property.  If this property is assigned an empty string, the default text is returned.  TcxCustomGridChartTitle descendants (such as the TcxGridChartHistogramAxisTitle class) provide their own default texts for return values of the GetText function.


TcxGridChartHistogramAxis
TcxGridChartHistogramAxis Object

Hierarchy          Properties          Methods          See Also

Represents a generic axis in a chart diagram.

Unit

cxGridChartView

TcxGridChartHistogramAxis = class(TcxCustomGridChartDiagramOptions)

Description

The TcxGridChartHistogramAxis class is the base class for the classes which represent category and value axes.  The TcxGridChartHistogramAxis class introduces options, which control the following appearance aspects of an axis and its elements:

•	the general appearance of an axis (Visible);

•	the position and appearance settings of an axis title, tick marks and their labels (via the Title, TickMarkKind, and TickMarkLabels properties, respectively);

•	the general appearance of axis gridlines (GridLines).

Note:	TcxGridChartHistogramAxis descendants have to implement the GetPosition function to return meaningful values according to the axis type they correspond to.


TcxGridChartHistogramAxis Hierarchy
Hierarchy

TPersistent

     |

TcxCustomGridChartDiagramOptions

     |


Properties for TcxGridChartHistogramAxis
TcxGridChartHistogramAxis Properties

TcxGridChartHistogramAxis          Legend

In TcxGridChartHistogramAxis

Diagram

GridLines

TickMarkKind

TickMarkLabels

Title

Visible

Derived from TcxCustomGridChartDiagramOptions

Diagram

GridView


Methods for TcxGridChartHistogramAxis
TcxGridChartHistogramAxis Methods

TcxGridChartHistogramAxis          Legend

In TcxGridChartHistogramAxis

GetPosition


TcxGridChartHistogramAxis.Diagram

TcxGridChartHistogramAxis

Provides access to the chart diagram which displays the axis.

property Diagram: TcxGridChartHistogram;

ReadOnly Property


TcxGridChartHistogramAxis.GridLines

TcxGridChartHistogramAxis          See Also

Specifies the general appearance of chart gridlines associated with the axis.

property GridLines: Boolean;

Description

Set this property to True to display chart gridlines for the axis.  Otherwise, gridlines will be hidden.

The default value of the GridLines property is True.


TcxGridChartHistogramAxis.TickMarkLabels

TcxGridChartHistogramAxis          See Also

Specifies the general appearance of tick-mark labels associated with the axis.

property TickMarkLabels: Boolean;

Description

Set this property to True to display tick-mark labels for the axis.  Otherwise, tick-mark labels will be hidden.

The default value of the TickMarkLabels property is True.


TcxGridChartHistogramAxis.TickMarkKind

TcxGridChartHistogramAxis          See Also

Specifies the manner in which tick marks are displayed for the axis.

type

  TcxGridChartHistogramTickMarkKind = (tmkNone, tmkCross, tmkInside, tmkOutside);

property TickMarkKind: TcxGridChartHistogramTickMarkKind;

Description

All possible values for this property are listed in the following table.

Value	Meaning
tmkNone	No tick marks are displayed.
tmkCross	Tick marks intersect the axis so that they are visible inside and outside of a chart’s plot area.  Visually this appears like when the TickMarkKind property has both the tmkInside and tmkOutside styles applied.
tmkInside	Tick marks extend from the axis into an inside of a chart’s plot area.
tmkOutside	Tick marks extend from the axis into an outside of a chart’s plot area.

The default value of the TickMarkKind property is tmkOutside.


TcxGridChartHistogramAxis.Title

TcxGridChartHistogramAxis

Specifies axis title appearance settings.

property Title: TcxGridChartHistogramAxisTitle;

Description

Refer to the description of the TcxGridChartHistogramAxisTitle class to learn about available appearance settings.


TcxGridChartHistogramAxis.Visible

TcxGridChartHistogramAxis

Specifies the general appearance of the axis and its elements within a chart diagram.

property Visible: Boolean;

Description

Set this property to True to display the axis and its elements within a diagram.  Otherwise, the axis will be hidden.

The default value of the Visible property is True.


TcxGridChartHistogramAxis.GetPosition

TcxGridChartHistogramAxis

When implemented, determines the position of the axis within a chart diagram.

type

  TcxGridChartAxisPosition = (cppLeft, cppTop, cppRight, cppBottom);

function GetPosition: TcxGridChartAxisPosition; virtual; abstract;

Description

This is an abstract function.  TcxGridChartHistogramAxis descendants have to implement this function to return meaningful values based upon specific aspects of the axes they correspond to.


TcxGridChartHistogramAxisCategory
TcxGridChartHistogramAxisCategory Object

Hierarchy          Properties          Methods          See Also

Represents the base class for category axes in all diagrams that provide axes for chart value measurement and comparison.

Unit

cxGridChartView

TcxGridChartHistogramAxisCategory = class(TcxGridChartHistogramAxis)

Description

In addition to the settings inherited from the base TcxGridChartHistogramAxis class, the TcxGridChartHistogramAxisCategory class introduces properties that allow you to control the following category axis attributes:

•	the position at which a value axis intersects a category axis (ValueAxisAtMaxCategory and ValueAxisBetweenCategories);

•	the plotting order of categories (CategoriesInReverseOrder).

An instance of the TcxGridChartHistogramAxisCategory class can be accessed via a diagram’s AxisCategory property.


TcxGridChartHistogramAxisCategory Hierarchy
Hierarchy

TPersistent

     |

TcxCustomGridChartDiagramOptions

     |

TcxGridChartHistogramAxis

     |


Properties for TcxGridChartHistogramAxisCategory
TcxGridChartHistogramAxisCategory Properties

TcxGridChartHistogramAxisCategory          Legend

In TcxGridChartHistogramAxisCategory

CategoriesInReverseOrder

ValueAxisAtMaxCategory

ValueAxisBetweenCategories

Derived from TcxGridChartHistogramAxis

Diagram

GridLines

TickMarkKind

TickMarkLabels

Title

Visible

Derived from TcxCustomGridChartDiagramOptions

Diagram

GridView


Methods for TcxGridChartHistogramAxisCategory
TcxGridChartHistogramAxisCategory Methods

TcxGridChartHistogramAxisCategory          Legend

In TcxGridChartHistogramAxisCategory

GetPosition

Derived from TcxGridChartHistogramAxis

GetPosition


TcxGridChartHistogramAxisCategory.CategoriesInReverseOrder

TcxGridChartHistogramAxisCategory          See Also

Specifies whether categories represented by the category axis are displayed in reverse order.

property CategoriesInReverseOrder: Boolean;

Description

By default, categories are displayed in the order in which their values are stored in the View’s data controller.  The following options affect the plotting order of categories:

•	Diagram type.  In column, line, and area diagrams, categories are displayed from left to right.  In bar diagrams, they are plotted from bottom to top.

•	Sorting order applied to categories (via the View’s Categories.SortOrder property).

•	Sorting order applied to a particular series (via the SortOrder property of this series).

Set the CategoriesInReverseOrder property to True to reverse the plotting order specified by the options above.  Note that this only changes display order and doesn’t affect the order in which category and series values are stored in the Values, VisibleValues, and VisibleDisplayTexts collections.

The default value of the CategoriesInReverseOrder property is False.


TcxGridChartHistogramAxisCategory.ValueAxisAtMaxCategory

TcxGridChartHistogramAxisCategory          See Also

Specifies whether a value axis intersects the category axis at the maximum category.  This position corresponds to the last displayed category when categories are painted in the default plotting order.

property ValueAxisAtMaxCategory: Boolean;

Description

When the ValueAxisAtMaxCategory property is set to True a value axis is displayed at the maximum category.  Otherwise, a value axis intersects the category axis at the minimum category.

You can reverse the plotting order of categories via the CategoriesInReverseOrder property.  This repositions a value axis based upon the new plotting order.

The default value of the ValueAxisAtMaxCategory property is False.


TcxGridChartHistogramAxisCategory.ValueAxisBetweenCategories

TcxGridChartHistogramAxisCategory

Specifies whether a value axis crosses the category axis between categories.

property ValueAxisBetweenCategories: Boolean;

Description

Set the ValueAxisBetweenCategories property to False to specify that a value axis should cross the category axis at a category tick mark.  Otherwise, the intersection is between two adjacent category tick marks.

The default value of the ValueAxisBetweenCategories property is True.


TcxGridChartHistogramAxisCategory.GetPosition

TcxGridChartHistogramAxisCategory

Determines the position at which the category axis is displayed within a chart diagram.

type

  TcxGridChartAxisPosition = (cppLeft, cppTop, cppRight, cppBottom);

function GetPosition: TcxGridChartAxisPosition; override;

Description

By default, the return value of this function equals the value returned by the diagram’s GetCategoryAxisPosition function.


TcxGridChartHistogramAxisTitle
TcxGridChartHistogramAxisTitle Object

Hierarchy          Properties          Methods

Represents an axis title in a chart diagram.

Unit

cxGridChartView

TcxGridChartHistogramAxisTitle = class(TcxCustomGridChartTitle)

Description

In addition to the settings inherited from the base TcxCustomGridChartTitle class, the TcxGridChartHistogramAxisTitle class introduces an Axis property that provides access to the axis which this title corresponds to.

An instance of the TcxGridChartHistogramAxisTitle class can be accessed via a diagram’s AxisCategory.Title and AxisValue.Title properties.


TcxGridChartHistogramAxisTitle Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |

TcxCustomGridChartTitle

     |

TcxGridChartHistogramAxisTitle


Properties for TcxGridChartHistogramAxisTitle
TcxGridChartHistogramAxisTitle Properties

TcxGridChartHistogramAxisTitle          Legend

In TcxGridChartHistogramAxisTitle

Axis

Derived from TcxCustomGridChartTitle

Alignment

Text


Methods for TcxGridChartHistogramAxisTitle
TcxGridChartHistogramAxisTitle Methods

TcxGridChartHistogramAxisTitle          Legend

Derived from TcxCustomGridChartTitle

GetAlignment

GetOrientation

GetPosition

GetText


TcxGridChartHistogramAxisTitle.Axis

TcxGridChartHistogramAxisTitle

Provides access to settings of an axis that the title corresponds to.

property Axis: TcxGridChartHistogramAxis;

ReadOnly Property


TcxGridChartHistogramAxisValue
TcxGridChartHistogramAxisValue Object

Hierarchy          Properties          Methods          See Also

Represents a value axis in all diagrams that provide axes for chart value measurements and comparisons.

Unit

cxGridChartView

TcxGridChartHistogramAxisValue = class(TcxGridChartHistogramAxis)

Description

In addition to the settings inherited from the base TcxGridChartHistogramAxis class, the TcxGridChartHistogramAxisValue class introduces properties that allow you to control the following value axis attributes:

•	the display range of values (MinMaxValues, MinValue, and MaxValue);

•	the format pattern for tick-mark labels (TickMarkLabelFormat).

An instance of the TcxGridChartHistogramAxisValue class can be accessed via a diagram’s AxisValue property.


TcxGridChartHistogramAxisValue Hierarchy
Hierarchy

TPersistent

     |

TcxCustomGridChartDiagramOptions

     |

TcxGridChartHistogramAxis

     |


Properties for TcxGridChartHistogramAxisValue
TcxGridChartHistogramAxisValue Properties

TcxGridChartHistogramAxisValue          Legend

In TcxGridChartHistogramAxisValue

MaxValue

MinMaxValues

MinValue

TickMarkLabelFormat

Derived from TcxGridChartHistogramAxis

Diagram

GridLines

TickMarkKind

TickMarkLabels

Title

Visible

Derived from TcxCustomGridChartDiagramOptions

Diagram

GridView


Methods for TcxGridChartHistogramAxisValue
TcxGridChartHistogramAxisValue Methods

TcxGridChartHistogramAxisValue          Legend

In TcxGridChartHistogramAxisValue

GetPosition

GetTickMarkLabel

GetTickMarkLabelFormat

Derived from TcxGridChartHistogramAxis

GetPosition


TcxGridChartHistogramAxisValue.MinMaxValues

TcxGridChartHistogramAxisValue          See Also

Specifies the display range type for the value axis.

type

  TcxGridChartHistogramMinMaxValues = (mmvZeroBasedAuto, mmvAuto, mmvCustom);

property MinMaxValues: TcxGridChartHistogramMinMaxValues;

Description

All possible values for the MinMaxValues property are listed in the following table.

Value	Meaning	Example
mmvZeroBasedAuto	The display range is calculated automatically based on chart values.  The value axis displays zero-based chart values.
mmvAuto	The display range is calculated automatically based on chart values.
mmvCustom	The upper and lower limits of the display range can be set via the MaxValue and MinValue properties. The following image displays a value axis restricted to the range of 10000 – 30000.


TcxGridChartHistogramAxisValue.MaxValue

TcxGridChartHistogramAxisValue

Specifies the maximum range value for the value axis.

property MaxValue: Extended;

Description

Setting this property automatically assigns mmvCustom to the MinMaxValues property.

Use the MinValue property to specify the minimum range value for the value axis.


TcxGridChartHistogramAxisValue.MinValue

TcxGridChartHistogramAxisValue

Specifies the minimum range value for the value axis.

property MinValue: Extended;

Description

Setting this property automatically assigns mmvCustom to the MinMaxValues property.

Use the MaxValue property to specify the maximum range value for the value axis.


TcxGridChartHistogramAxisValue.TickMarkLabelFormat

TcxGridChartHistogramAxisValue          See Also

Specifies the format pattern to be used when formatting tick-mark labels of the value axis.

property TickMarkLabelFormat: string;

Description

A tick-mark label is created using the corresponding tick-mark value via standard routines unless the format pattern is set via the TickMarkLabelFormat property.  In this instance, the specified pattern is used to format the resulting tick-mark label.

For instance, when a tick-mark label is determined using ‘Profit/Loss = $,0.00;-$,0.00’ pattern, the pattern will be treated as follows.  The 0.00 portion will be substituted with the tick-mark value.  The two zeros after the point identify the number of digits in the resulting tick-mark label to the right of the decimal point.  The comma represents the ThousandSeparator global variable.  The semicolon separates two patterns used to display positive and negative values, respectively.  Other characters do not have any special meaning and are displayed as is.

Note:	Refer to the description of the FormatFloat function for additional information on formatting numeric values.


TcxGridChartHistogramAxisValue.GetPosition

TcxGridChartHistogramAxisValue

Determines the position of the value axis within a chart diagram.

type

  TcxGridChartAxisPosition = (cppLeft, cppTop, cppRight, cppBottom);

function GetPosition: TcxGridChartAxisPosition; override;

Description

The return value of this function equals the value returned by the diagram’s GetValueAxisPosition function.


TcxGridChartHistogramAxisValue.GetTickMarkLabel

TcxGridChartHistogramAxisValue

Determines the label for a tick-mark value specified by the ATickMarkValue parameter.

function GetTickMarkLabel(const ATickMarkValue: Variant): string; virtual;

Description

The pattern used to format the return value of this function is determined by the GetTickMarkLabelFormat function.  When the GetTickMarkLabelFormat function’s return property equals an empty string, the tick-mark label is obtained from the specified tick-mark value which is converted to a string using the format pattern of the first visible series with an assigned format pattern for series value captions.  When there is no series displayed, or no format pattern for series found, the label is obtained from the tick-mark value using standard routines.


TcxGridChartHistogramAxisValue.GetTickMarkLabelFormat

TcxGridChartHistogramAxisValue          See Also

Gets the format pattern (if any) used to format labels for tick-mark values.

function GetTickMarkLabelFormat(AConsiderSeriesFormat: Boolean): string; virtual;

Description

By default, the return value of this function is the format pattern which is set via the TickMarkLabelFormat property.  If this property is not set and the AConsiderSeriesFormat parameter is set to True, then the format pattern is obtained from the visible series with an assigned format pattern for series value captions.  The first format pattern found is returned by the GetTickMarkLabelFormat function only if the other patterns for series value captions are identical to this one.  Otherwise, an empty string is returned.


TcxGridChartHistogramValues
TcxGridChartHistogramValues Object

Hierarchy          Properties          Methods

Represents base appearance options for data markers in all diagrams that provide axes for chart value measurements and comparisons.

Unit

cxGridChartView

TcxGridChartHistogramValues = class(TcxCustomGridChartDiagramOptions)

Description

In addition to the settings inherited from the base TcxCustomGridChartDiagramOptions class, the TcxGridChartHistogramValues class introduces properties that control the following appearance settings of data markers:

•	stacking type (Stacking);

•	color relative to categories (VaryColorsByCategory).

An instance of the TcxGridChartHistogramValues class can be accessed via a diagram’s Values property.


TcxGridChartHistogramValues Hierarchy
Hierarchy

TPersistent

     |

TcxCustomGridChartDiagramOptions

     |


Properties for TcxGridChartHistogramValues
TcxGridChartHistogramValues Properties

TcxGridChartHistogramValues          Legend

In TcxGridChartHistogramValues

Stacking

VaryColorsByCategory

Derived from TcxCustomGridChartDiagramOptions

Diagram

GridView


Methods for TcxGridChartHistogramValues
TcxGridChartHistogramValues Methods

TcxGridChartHistogramValues          Legend

In TcxGridChartHistogramValues

GetVaryColorsByCategory


TcxGridChartHistogramValues.Stacking

TcxGridChartHistogramValues

Specifies the stacking type applied to data markers.

type

  TcxGridChartValuesStacking = (vsNone, vsNormal, vs100Percent);

property Stacking: TcxGridChartValuesStacking;

Description

Use this property to produce stacked diagrams.

All possible values for the Stacking property are listed in the following table.

Value	Meaning	Diagram Type	Example
vsNone	Chart values are compared across categories.  The corresponding data markers are painted sequentially within categories.  No stacking of data markers is applied.	Clustered diagram
vsNormal	Data markers are painted stacked within each category thus showing the relationship of individual chart values to the whole - comparing the contribution of each value to the total across categories.	Normal stacked diagram
vs100Percent	Data markers are painted stacked within each category thus showing the percentage each chart value contributes to the total across categories.	100% stacked diagram

The default value of the Stacking property is vsNone.


TcxGridChartHistogramValues.VaryColorsByCategory

TcxGridChartHistogramValues

Specifies whether the colors of data markers are different for each category.

property VaryColorsByCategory: Boolean;

Description

Set this property to True to vary the colors of all data markers in a diagram from category to category.  The GetVaryColorsByCategory function determines the conditions under which this option will take effect.

Property Value equals	False	True

Note:	When the VaryColorsByCategory option is enabled, a chart legend displays categories (not series as it normally does) and the colors associated with these categories.

The default value of the VaryColorsByCategory property is False.


TcxGridChartHistogramValues.GetVaryColorsByCategory

TcxGridChartHistogramValues

Determines whether all data markers in a diagram can be painted using different colors for each category.

function GetVaryColorsByCategory: Boolean; virtual;

Description

This function returns True when the conditions for applying different colors to data markers are met.

By default, the GetVaryColorsByCategory function returns True when a single series is displayed within a diagram and the VaryColorsByCategory property is set to True.


TcxGridChartColumnDiagramValues
TcxGridChartColumnDiagramValues Object

Hierarchy          Properties          Methods

Represents appearance options for data markers in column and bar diagrams.

Unit

cxGridChartView

TcxGridChartColumnDiagramValues = class(TcxGridChartHistogramValues)

Description

In addition to the settings inherited from the base TcxGridChartHistogramValues class, the TcxGridChartColumnDiagramValues class introduces properties that control the following appearance settings of these data markers:

•	the width of the border for data markers (BorderWidth);

•	the position of data labels on the corresponding chart values (CaptionPosition).

An instance of the TcxGridChartColumnDiagramValues class can be accessed via a diagram’s Values property.


TcxGridChartColumnDiagramValues Hierarchy
Hierarchy

TPersistent

     |

TcxCustomGridChartDiagramOptions

     |

TcxGridChartHistogramValues

     |


Properties for TcxGridChartColumnDiagramValues
TcxGridChartColumnDiagramValues Properties

TcxGridChartColumnDiagramValues          Legend

In TcxGridChartColumnDiagramValues

BorderWidth

CaptionPosition

Derived from TcxGridChartHistogramValues

Stacking

VaryColorsByCategory

Derived from TcxCustomGridChartDiagramOptions

Diagram

GridView


Methods for TcxGridChartColumnDiagramValues
TcxGridChartColumnDiagramValues Methods

TcxGridChartColumnDiagramValues          Legend

Derived from TcxGridChartHistogramValues

GetVaryColorsByCategory


TcxGridChartColumnDiagramValues.BorderWidth

TcxGridChartColumnDiagramValues

Specifies the width of the border (in pixels) for values (data markers).

property BorderWidth: Integer;

Description

Use the BorderWidth property to specify the width of the border (in pixels) for all the data markers within the diagram.  Setting this property to 0 means that the data markers don't have borders.

The default value of the BorderWidth property is specified by the cxGridChartColumnDiagramDefaultBorderWidth constant.


TcxGridChartColumnDiagramValues.CaptionPosition

TcxGridChartColumnDiagramValues

Specifies the position of data labels on chart values.

type

  TcxGridChartColumnDiagramValueCaptionPosition = (cdvcpNone, cdvcpInsideBase, cdvcpCenter, cdvcpInsideEnd, cdvcpOutsideEnd);

property CaptionPosition: TcxGridChartColumnDiagramValueCaptionPosition;

Description

Use this property to specify the position of data labels on the chart values within a diagram.

All the possible values are listed in the following table.

Value	Meaning
cdvcpNone	Data labels on series values are not displayed.
cdvcpInsideBase	Data labels are displayed inside the data markers and aligned to the base of the marker.
cdvcpCenter	Data labels are displayed centered within the data markers.
cdvcpInsideEnd	Data labels are displayed inside the data markers and aligned to the end of the corresponding data markers.
cdvcpOutsideEnd	Data labels are displayed outside the data markers and aligned to the end of the corresponding data markers.

The ValueCaptionFormat property of series specifies the formatting pattern for the captions of the series values (the data labels on series values).

The default value of the CaptionPosition property is cdvcpNone.


TcxGridChartLineDiagramValues
TcxGridChartLineDiagramValues Object

Hierarchy          Properties          Methods          Events

Represents appearance options for data markers in line and area diagrams.

Unit

cxGridChartView

TcxGridChartLineDiagramValues = class(TcxGridChartHistogramValues)

Description

In addition to the settings inherited from the base TcxGridChartHistogramValues class, the TcxGridChartLineDiagramValues class introduces properties that control the following appearance settings of these data markers:

•	the position of data labels on the corresponding data markers (CaptionPosition).

•	the width and style of lines that connect value points (LineWidth and LineStyle);

•	the size and style of value markers (MarkerSize and MarkerStyle);

•	the width of value hotspot areas (HotSpotSize).

The TcxGridChartLineDiagramValues class also publishes the Stacking property to enable the customization of stacking diagram type for line and area diagrams.

An instance of the TcxGridChartLineDiagramValues class can be accessed via a diagram’s Values property.


TcxGridChartLineDiagramValues Hierarchy
Hierarchy

TPersistent

     |

TcxCustomGridChartDiagramOptions

     |

TcxGridChartHistogramValues

     |


Properties for TcxGridChartLineDiagramValues
TcxGridChartLineDiagramValues Properties

TcxGridChartLineDiagramValues          Legend

In TcxGridChartLineDiagramValues

CaptionPosition

Diagram

HotSpotSize

LineStyle

LineWidth

MarkerSize

MarkerStyle

Derived from TcxGridChartHistogramValues

Stacking

VaryColorsByCategory

Derived from TcxCustomGridChartDiagramOptions

Diagram

GridView


Methods for TcxGridChartLineDiagramValues
TcxGridChartLineDiagramValues Methods

TcxGridChartLineDiagramValues          Legend

In TcxGridChartLineDiagramValues

GetHotSpotSize

GetLineStyle

GetMarkerStyle

Derived from TcxGridChartHistogramValues

GetVaryColorsByCategory


Events for TcxGridChartLineDiagramValues
TcxGridChartLineDiagramValues Events

TcxGridChartLineDiagramValues          Legend

In TcxGridChartLineDiagramValues

OnGetLineStyle

OnGetMarkerStyle


TcxGridChartLineDiagramValues.CaptionPosition

TcxGridChartLineDiagramValues          See Also

Specifies the position of data labels on data markers.

type

  TcxGridChartLineDiagramValueCaptionPosition = (ldvcpNone, ldvcpLeft, ldvcpAbove, ldvcpRight, ldvcpBelow, ldvcpCenter)

property CaptionPosition: TcxGridChartLineDiagramValueCaptionPosition;

Description

All possible values for this property are listed in the following table.

Value	Meaning
ldvcpNone	Data labels are not displayed.
ldvcpLeft	Data labels are displayed on the left of the corresponding value markers.
ldvcpAbove	Data labels are displayed above the corresponding value markers.
ldvcpRight	Data labels are displayed on the right of the corresponding value markers.
ldvcpBelow	Data labels are displayed below the corresponding value markers.
ldvcpCenter	Data labels are displayed passing the center point of the corresponding value markers.

The default value of the CaptionPosition property is ldvcpNone.


TcxGridChartLineDiagramValues.Diagram

TcxGridChartLineDiagramValues

Provides access to a chart diagram that uses the set of options.

property Diagram: TcxGridChartLineDiagram;

ReadOnly Property


TcxGridChartLineDiagramValues.HotSpotSize

TcxGridChartLineDiagramValues

Specifies the width (in pixels) of all value hotspot areas within a chart diagram.

property HotSpotSize: Integer;

Description

The display width of value hotspot areas is determined by the GetHotSpotSize function as the greater of the values specified by the HotSpotSize and MarkerSize properties.

The default value of the HotSpotSize property is specified by the cxGridChartLineDiagramDefaultHotSpotSize constant.


TcxGridChartLineDiagramValues.LineStyle

TcxGridChartLineDiagramValues          See Also

Specifies line style that connects value points.

type

  TcxGridChartLineStyle = (clsNone, clsSolid, clsDash, clsDot, clsDashDot, clsDashDotDot);

property LineStyle: TcxGridChartLineStyle;

Description

All possible values for this property are listed in the description of the TcxGridChartLineStyle type.

Note:	You can handle the OnGetLineStyle event to specify the line style for individual series.

The default value of the LineStyle property is clsSolid.


TcxGridChartLineDiagramValues.LineWidth

TcxGridChartLineDiagramValues          See Also

Specifies the width (in pixels) of lines that connect value points.

property LineWidth: Integer;

Description

Use the LineStyle property to specify the style of these lines.

The default value of this property is specified by the cxGridChartLineDiagramDefaultLineWidth constant.


TcxGridChartLineDiagramValues.MarkerSize

TcxGridChartLineDiagramValues          See Also

Specifies the size (in pixels) of value markers.

property MarkerSize: Integer;

Description

The value of this property specifies the side length of a square zone centered on the value point within which a value marker is painted.

Note that the property value is also used to determine the display width of value hotspot areas.  Refer to the description of the HotSpotSize property for additional information on value hotspots.

The default value of the MarkerSize property is specified by the cxGridChartLineDiagramDefaultMarkerSize constant.


TcxGridChartLineDiagramValues.MarkerStyle

TcxGridChartLineDiagramValues          See Also

Specifies the style (graphical shapes) of value markers.

type

  TcxGridChartMarkerStyle = (cmsNone, cmsSquare, cmsTriangle, cmsDiamond, cmsCircle);

property MarkerStyle: TcxGridChartMarkerStyle;

Description

All possible values for this property are listed in the description of TcxGridChartMarkerStyle.

Note:	You can handle the OnGetMarkerStyle event to specify value marker style for individual series.

The default value of the MarkerStyle property is cmsNone.


TcxGridChartLineDiagramValues.GetHotSpotSize

TcxGridChartLineDiagramValues

Determines the display width of value hotspot areas.

function GetHotSpotSize: Integer; virtual;

Description

By default, this function returns the greater of the values specified by the HotSpotSize and MarkerSize properties.  Use the HotSpotSize property to set a specific width to all value hotspot areas within a chart diagram.


TcxGridChartLineDiagramValues.GetLineStyle

TcxGridChartLineDiagramValues

Determines line style that connects value points of the series addressed by the ASeries parameter.

type

  TcxGridChartLineStyle = (clsNone, clsSolid, clsDash, clsDot, clsDashDot, clsDashDotDot);

function GetLineStyle(ASeries: TcxGridChartSeries): TcxGridChartLineStyle; virtual;

Description

By default, line style is determined by the LineStyle property.  To customize the line style for individual series, handle the OnGetLineStyle event.


TcxGridChartLineDiagramValues.GetMarkerStyle

TcxGridChartLineDiagramValues

Determines the style of value markers that identify value points of the series addressed by the ASeries parameter.

type

  TcxGridChartMarkerStyle = (cmsNone, cmsSquare, cmsTriangle, cmsDiamond, cmsCircle);

function GetMarkerStyle(ASeries: TcxGridChartSeries): TcxGridChartMarkerStyle; virtual;

Description

By default, value marker style is determined by the MarkerStyle property.  To customize value marker style for individual series, handle the OnGetMarkerStyle event.


TcxGridChartLineDiagramValues.OnGetLineStyle

TcxGridChartLineDiagramValues

Occurs when line style that connects value points of the series addressed by the ASeries parameter needs to be determined.

type

  TcxGridChartLineStyle = (clsNone, clsSolid, clsDash, clsDot, clsDashDot, clsDashDotDot);

  TcxGridChartLineDiagramGetLineStyleEvent = procedure(Sender: TcxGridChartLineDiagram; ASeries: TcxGridChartSeries; var AStyle: TcxGridChartLineStyle) of object;

property OnGetLineStyle: TcxGridChartLineDiagramGetLineStyleEvent;

Description

The line style for this series is returned via the AStyle parameter.  This parameter’s value is initially equal to the LineStyle property value.


TcxGridChartLineDiagramValues.OnGetMarkerStyle

TcxGridChartLineDiagramValues

Occurs when value marker style that identifies value points of the series addressed by the ASeries parameter needs to be determined.

type

  TcxGridChartMarkerStyle = (cmsNone, cmsSquare, cmsTriangle, cmsDiamond, cmsCircle);

  TcxGridChartLineDiagramGetMarkerStyleEvent = procedure(Sender: TcxGridChartLineDiagram; ASeries: TcxGridChartSeries; var AStyle: TcxGridChartMarkerStyle) of object;

property OnGetMarkerStyle: TcxGridChartLineDiagramGetMarkerStyleEvent;

Description

The value marker style is returned via the AStyle parameter.  This parameter’s value is initially equal to the MarkerStyle property value.


TcxGridChartPieDiagramValues
TcxGridChartPieDiagramValues Object

Hierarchy          Properties          Methods

Represents appearance options for pie slices in pie diagrams.

Unit

cxGridChartView

TcxGridChartPieDiagramValues = class(TcxCustomGridChartDiagramOptions)

Description

In addition to the settings inherited from the base TcxCustomGridChartDiagramOptions class, the TcxGridChartPieDiagramValues class introduces properties that control the following appearance settings of pie slices:

•	the angular position of the first pie slice (AngleOfFirstSlice).

•	the content and display position of pie slice labels (CaptionItems, CaptionItemSeparator, PercentageCaptionFormat, and CaptionPosition).

An instance of the TcxGridChartPieDiagramValues class can be accessed via a pie diagram’s Values property.


TcxGridChartPieDiagramValues Hierarchy
Hierarchy

TPersistent

     |

TcxCustomGridChartDiagramOptions

     |


Properties for TcxGridChartPieDiagramValues
TcxGridChartPieDiagramValues Properties

TcxGridChartPieDiagramValues          Legend

In TcxGridChartPieDiagramValues

AngleOfFirstSlice

CaptionItems

CaptionPosition

CaptionItemSeparator

PercentageCaptionFormat

Derived from TcxCustomGridChartDiagramOptions

Diagram

GridView


Methods for TcxGridChartPieDiagramValues
TcxGridChartPieDiagramValues Methods

TcxGridChartPieDiagramValues          Legend

In TcxGridChartPieDiagramValues

GetCaptionItemSeparator

GetCaptionPosition

GetPercentageCaptionFormat


TcxGridChartPieDiagramValues.AngleOfFirstSlice

TcxGridChartPieDiagramValues

Specifies the angle (from 0 degrees which is at the top of the pie circle, clockwise to 360 degrees) at which the first pie slice is drawn.

property AngleOfFirstSlice: Integer;

Description

The following table shows the examples of using the AngleOfFirstSlice property.

Property Value equals	0	90

The default value of the AngleOfFirstSlice property is 0.


TcxGridChartPieDiagramValues.CaptionItems

TcxGridChartPieDiagramValues

Specifies a set of detail items to be included into pie slice labels.

type

  TcxGridChartPieDiagramValueCaptionItem = (pdvciCategory, pdvciValue, pdvciPercentage);

  TcxGridChartPieDiagramValueCaptionItems = set of TcxGridChartPieDiagramValueCaptionItem;

property CaptionPosition: TcxGridChartPieDiagramValueCaptionItems;

Description

All possible values for this property are listed in the following table.

Value	Meaning
pdvciCategory	Labels include category values.
pdvciValue	Labels include chart values which correspond to pie slices.
pdvciPercentage	Labels include percentage values of the corresponding pie slices within a pie chart. Use the PercentageCaptionFormat property to specify the format pattern used to create string representations of these percentage values.

Each detail item in pie slice labels is separated using the separator string as specified by the GetCaptionItemSeparator function.

The default value of the CaptionItems property is [pdvciValue].


TcxGridChartPieDiagramValues.CaptionItemSeparator

TcxGridChartPieDiagramValues

Specifies a separator string for detail items to be included into pie slice labels.

property CaptionItemSeparator: string;

Description

If this property value is not specified, the GetCaptionItemSeparator function returns the default separator string used to separate these detail items.

Refer to the description of the CaptionItems property to learn about detail items available to display in pie slice labels.


TcxGridChartPieDiagramValues.CaptionPosition

TcxGridChartPieDiagramValues          See Also

Specifies the general appearance and display position of pie slice labels.

type

  TcxGridChartPieDiagramValueCaptionPosition = (pdvcpNone, pdvcpCenter, pdvcpInsideEnd, pdvcpOutsideEnd, pdvcpOutsideEndWithLeaderLines);

property CaptionPosition: TcxGridChartPieDiagramValueCaptionPosition;

Description

All possible values for this property are listed in the description of the TcxGridChartPieDiagramValueCaptionPosition.

The default value of the CaptionPosition property is pdvcpNone.


TcxGridChartPieDiagramValues.PercentageCaptionFormat

TcxGridChartPieDiagramValues

Specifies the format pattern used to determine the string representation of percentage values in pie slice labels.

property PercentageCaptionFormat: string;

Description

For instance, the ‘0%‘ format pattern will be treated as follows.  The 0 portion will be substituted with a percentage value rounded to the nearest integer.  The percent character has no special meaning and will be displayed as is.

If the PercentageCaptionFormat property value is not specified, the GetPercentageCaptionFormat function returns the default pattern used to format percentage values.

To add percentage values in pie slice labels, enable the pdvciPercentage option in the CaptionItems property.

Note:	For additional information on formatting numeric values see the FormatFloat function topic.


TcxGridChartPieDiagramValues.GetCaptionItemSeparator

TcxGridChartPieDiagramValues

Determines the separator string for detail items which are included into pie slice labels.

function GetCaptionItemSeparator: string;

Description

The GetCaptionItemSeparator function returns the CaptionItemSeparator property value.  If this property is assigned an empty string, the function returns a semicolon followed by the space character (‘; ’).

Refer to the description of the CaptionItems property to learn about detail items available to display in pie slice labels.


TcxGridChartPieDiagramValues.GetCaptionPosition

TcxGridChartPieDiagramValues

Determines the display position of pie slice labels.

type

  TcxGridChartPieDiagramValueCaptionPosition = (pdvcpNone, pdvcpCenter, pdvcpInsideEnd, pdvcpOutsideEnd, pdvcpOutsideEndWithLeaderLines);

function GetCaptionPosition: TcxGridChartPieDiagramValueCaptionPosition; virtual;

Description

By default, this function returns the CaptionPosition property value.  If the CaptionItems property value equals [], the GetCaptionPosition function returns pdvcpNone.

All possible return values of this function are listed in the description of the TcxGridChartPieDiagramValueCaptionPosition.


TcxGridChartPieDiagramValues.GetPercentageCaptionFormat

TcxGridChartPieDiagramValues

Determines the format pattern used to determine the string representation of percentage values in pie slice labels.

function GetPercentageCaptionFormat: string;

Description

The GetPercentageCaptionFormat function returns the PercentageCaptionFormat property value.  If this property is assigned an empty string, the function returns a ‘0%’ string.

To add percentage values in pie slice labels, enable the pdvciPercentage option in the CaptionItems property.


TcxGridChartLineDiagramAxisCategory
TcxGridChartLineDiagramAxisCategory Object

Hierarchy          Properties          Methods          See Also

Represents a category axis in line and area diagrams.

Unit

cxGridChartView

TcxGridChartLineDiagramAxisCategory = class(TcxGridChartHistogramAxisCategory)

Description

The TcxGridChartLineDiagramAxisCategory class does not introduce any new functionality, but instead modifies the default position of a category axis in these diagrams.  You can modify this position via the ValueAxisBetweenCategories property.

An instance of the TcxGridChartLineDiagramAxisCategory class can be accessed via a diagram’s AxisCategory property.


TcxGridChartLineDiagramAxisCategory Hierarchy
Hierarchy

TPersistent

     |

TcxCustomGridChartDiagramOptions

     |

TcxGridChartHistogramAxis

     |

TcxGridChartHistogramAxisCategory

     |


Properties for TcxGridChartLineDiagramAxisCategory
TcxGridChartLineDiagramAxisCategory Properties

TcxGridChartLineDiagramAxisCategory          Legend

In TcxGridChartLineDiagramAxisCategory

ValueAxisBetweenCategories

Derived from TcxGridChartHistogramAxisCategory

CategoriesInReverseOrder

ValueAxisAtMaxCategory

ValueAxisBetweenCategories

Derived from TcxGridChartHistogramAxis

Diagram

GridLines

TickMarkKind

TickMarkLabels

Title

Visible

Derived from TcxCustomGridChartDiagramOptions

Diagram

GridView


Methods for TcxGridChartLineDiagramAxisCategory
TcxGridChartLineDiagramAxisCategory Methods

TcxGridChartLineDiagramAxisCategory          Legend

Derived from TcxGridChartHistogramAxisCategory

GetPosition

Derived from TcxGridChartHistogramAxis

GetPosition


TcxGridChartLineDiagramAxisCategory.ValueAxisBetweenCategories

TcxGridChartLineDiagramAxisCategory

Specifies whether a value axis crosses the category axis between categories.

property ValueAxisBetweenCategories: Boolean;

Description

The TcxGridChartLineDiagramAxisCategory class only modifies the default position of the category axis specific to line and area diagrams.  Refer to the description of the ValueAxisBetweenCategories property in the ancestor class for details on specifying the position of a value axis.

The default value of the ValueAxisBetweenCategories property is False.


TcxGridChartLegend
TcxGridChartLegend Object

Hierarchy          Properties          Methods          See Also

Represents a chart legend in a diagram.

Unit

cxGridChartView

TcxGridChartLegend = class(TcxCustomGridOptions)

Description

The chart legend is the key for chart diagrams which identifies the patterns (background bitmaps) or colors that are assigned to the data displayed in a chart diagram.  A chart legend is displayed outside the chart’s plot area and provides information on what is displayed in the chart.

The TcxGridChartLegend class provides properties and methods for specifying the appearance aspects of a chart legend, arranging it within the chart and determining its current position within the chart.  All the properties which control the appearance aspects such as the position and orientation of the chart legend are initialized with default values that provide a standard appearance for charts.  Use the Chart View’s Legend property and the diagram’s Legend property to access the chart legend’s appearance options.


TcxGridChartLegend Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |


Properties for TcxGridChartLegend
TcxGridChartLegend Properties

TcxGridChartLegend          Legend

In TcxGridChartLegend

Alignment

Border

KeyBorder

Orientation

Position

Derived from TcxCustomGridOptions

GridView


Methods for TcxGridChartLegend
TcxGridChartLegend Methods

TcxGridChartLegend          Legend

In TcxGridChartLegend

GetAlignment

GetBorder

GetKeyBorder

GetOrientation

GetPosition


TcxGridChartLegend.Alignment

TcxGridChartLegend          See Also

Specifies the alignment applied to a chart legend.

type

  TcxGridChartPartAlignment = (cpaDefault, cpaStart, cpaCenter, cpaEnd);

property Alignment: TcxGridChartPartAlignment;

Description

Set the Alignment property to apply a specific alignment to the chart legend.  All possible values for this property are listed in the TcxGridChartPartAlignment type topic.

The default value of the Alignment property is cpaDefault.


TcxGridChartLegend.Border

TcxGridChartLegend          See Also

Specifies the border style of a chart legend.

type

  TcxGridChartLegendBorder = (lbDefault, lbNone, lbSingle);

property Border: TcxGridChartLegendBorder;

Description

A chart legend encloses all the legend keys and the display texts of a series shown in the chart.  Use the Border property to specify the border style of the chart legend.  All possible values for this property are listed in the TcxGridChartLegendBorder type topic.

The default value of the Border property is lbDefault.


TcxGridChartLegend.KeyBorder

TcxGridChartLegend          See Also

Specifies the border style of the legend keys.

type

  TcxGridChartLegendBorder = (lbDefault, lbNone, lbSingle);

property KeyBorder: TcxGridChartLegendBorder;

Description

A legend key provides an indication of each data marker followed by the display text of the series for each series shown in the diagram.  Use the KeyBorder property to specify the border style of the legend keys.  All possible values for this property are listed in the TcxGridChartLegendBorder type topic.

The default value of the KeyBorder property is lbDefault.


TcxGridChartLegend.Orientation

TcxGridChartLegend          See Also

Specifies the orientation of the chart legend within the chart.

type

  TcxGridChartPartOrientation = (cpoDefault, cpoHorizontal, cpoVertical);

property Orientation: TcxGridChartPartOrientation;

Description

Set the Orientation property to designate the orientation of the chart legend (either vertical or horizontal) and arrange the chart legend within the chart in the best way possible (for instance, depending upon the type of the diagram displayed in the chart).  All possible values for this property are listed in the TcxGridChartPartOrientation type topic.

The default value of the Orientation property is cpoDefault.


TcxGridChartLegend.Position

TcxGridChartLegend          See Also

Specifies the position of the chart legend within the chart.

type

  TcxGridChartPartPosition = (cppDefault, cppNone, cppLeft, cppTop, cppRight, cppBottom);

property Position: TcxGridChartPartPosition;

Description

Set the Position property to designate the visual position of the chart legend within the chart.  All possible values for this property are listed in the TcxGridChartPartPosition type topic.

The default value of the Position property is cppDefault.


TcxGridChartLegend.GetAlignment

TcxGridChartLegend

Determines the alignment of the chart legend.

type

  TcxGridChartPartAlignment = (cpaDefault, cpaStart, cpaCenter, cpaEnd);

function GetAlignment: TcxGridChartPartAlignment;

Description

Call the GetAlignment function to determine the alignment of the chart legend within the chart.  Use the Alignment property to apply a specific alignment to the chart legend.


TcxGridChartLegend.GetBorder

TcxGridChartLegend

Determines the border style of a chart legend.

type

  TcxGridChartLegendBorder = (lbDefault, lbNone, lbSingle);

function GetBorder: TcxGridChartLegendBorder;

Description

Call the GetBorder function to determine the border style of the chart legend within the chart.  Use the Border property to apply a specific border style to the chart legend.


TcxGridChartLegend.GetKeyBorder

TcxGridChartLegend

Determines the border style of legend keys.

type

  TcxGridChartLegendBorder = (lbDefault, lbNone, lbSingle);

function GetKeyBorder: TcxGridChartLegendBorder;

Description

Call the GetKeyBorder function to determine the border style of the legend keys within the chart legend.  Use the KeyBorder property to apply a specific border style to the legend keys currently displayed in the chart legend.


TcxGridChartLegend.GetOrientation

TcxGridChartLegend

Determines the orientation of the chart legend within a chart.

type

  TcxGridChartPartOrientation = (cpoDefault, cpoHorizontal, cpoVertical);

function GetOrientation(APosition: TcxGridChartPartPosition = cppDefault): TcxGridChartPartOrientation;

Description

Call the GetOrientation function to determine the orientation (vertical or horizontal) of the chart legend within the chart.  Use the Orientation property to change the chart legend's orientation.


TcxGridChartLegend.GetPosition

TcxGridChartLegend

Determines the position of the chart legend within a chart.

type

  TcxGridChartPartPosition = (cppDefault, cppNone, cppLeft, cppTop, cppRight, cppBottom);

function GetPosition: TcxGridChartPartPosition;

Description

Call the GetPosition function to determine the position of the chart legend within the chart.  Use the Position property to specify the position of the chart legend.


TcxGridChartOptionsBehavior
TcxGridChartOptionsBehavior Object

Hierarchy          Properties          Methods

Represents a set of options which determine how Chart Views respond to end-user actions.

Unit

cxGridChartView

TcxGridChartOptionsBehavior = class(TcxCustomGridOptionsBehavior)

Description

TcxGridChartOptionsBehavior represents a set of options which determine the response of Chart Views to end-user actions.  The ValueHints property controls the appearance of hints when an end-user hovers the mouse pointer over the data markers.  The ValueHotTrack property allows you to specify when the values (their data markers) can be hot-tracked by end-users.

You can also specify the type of synchronization which is used to keep all the created "clone" Views’ settings synchronized with their "pattern" View’s settings.

Use the Chart View’s OptionsBehavior property to access this set of options.


TcxGridChartOptionsBehavior Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |

TcxCustomGridOptionsBehavior

     |


Properties for TcxGridChartOptionsBehavior
TcxGridChartOptionsBehavior Properties

TcxGridChartOptionsBehavior          Legend

In TcxGridChartOptionsBehavior

ValueHints

ValueHotTrack

Derived from TcxCustomGridOptionsBehavior

PostponedSynchronization

Derived from TcxCustomGridOptions

GridView


Methods for TcxGridChartOptionsBehavior
TcxGridChartOptionsBehavior Methods

TcxGridChartOptionsBehavior          Legend

In TcxGridChartOptionsBehavior

GetValueHotTrack


TcxGridChartOptionsBehavior.ValueHints

TcxGridChartOptionsBehavior          See Also

Specifies whether hints are displayed when an end-user hovers the mouse pointer over the values within a chart.

property ValueHints: Boolean;

Description

To provide detailed information on the values (their data markers) shown in the chart, Chart Views are capable of displaying value hints when an end-user hovers the mouse over the values.  This information includes the display text for the corresponding series and string representations of the corresponding category label and series value (as they appear in the chart based upon the corresponding formats applied) for the value which is currently located under the mouse pointer.  The resulting information string is determined by the View’s Controller.GetValueHintText function using the format string as specified by the scxGridChartValueHintFormat resource string.

Set the ValueHints to True to enable displaying the value hints within the Chart View.  Otherwise, the value hints will not be displayed.

The default value of the ValueHints property is True.


TcxGridChartOptionsBehavior.ValueHotTrack

TcxGridChartOptionsBehavior

Specifies how data markers are highlighted (hot-tracked) in a chart when an end-user hovers the mouse pointer over them.

type

  TcxGridChartValueHotTrack = (vhDefault, vhNever, vhAlways);

property ValueHotTrack: TcxGridChartValueHotTrack;

Description

All possible values for this property are listed in the following table.

Value	Meaning
vhDefault	Data markers are only highlighted when an end-user hovers the mouse pointer over the grouped chart values (the values that can be drilled down).  This option is in effect provided that the View’s OptionsCustomize.DataDrillDown property is set to True.
vhNever	Data markers are not highlighted in a chart.
vhAlways	Data markers are always highlighted when an end-user hovers the mouse pointer over them.

Call the GetValueHotTrack function to determine whether the data marker under the mouse pointer is highlighted.

The default value of the ValueHotTrack property is vhDefault.


TcxGridChartOptionsBehavior.GetValueHotTrack

TcxGridChartOptionsBehavior

Returns True when the data marker under the mouse pointer is highlighted in a chart.

property GetValueHotTrack: Boolean;

Description

Use the ValueHotTrack property to specify when data markers can be highlighted by end-users.


TcxGridChartOptionsCustomize
TcxGridChartOptionsCustomize Object

Hierarchy          Properties

Represents a set of options, which control the availability of end-user customization features.

Unit

cxGridChartView

TcxGridChartOptionsCustomize = class(TcxCustomGridOptions)

Description

In addition to the settings inherited from the base TcxCustomGridOptions class, the TcxGridChartOptionsCustomize class introduces properties that control the following end-user customization features:

•	data mining (DataDrillDown and DataDrillUpMethod);

•	customization of data levels using drag and drop (DataGroupHiding and DataGroupMoving);

•	features available via the customization form (OptionsCustomization and SeriesCustomization).

Use the View’s OptionsCustomize property to access these options.


TcxGridChartOptionsCustomize Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |

TcxGridChartOptionsCustomize


Properties for TcxGridChartOptionsCustomize
TcxGridChartOptionsCustomize Properties

TcxGridChartOptionsCustomize          Legend

In TcxGridChartOptionsCustomize

DataDrillDown

DataDrillUpMethod

DataGroupHiding

DataGroupMoving

OptionsCustomization

SeriesCustomization

Derived from TcxCustomGridOptions

GridView


TcxGridChartOptionsCustomize.DataDrillDown

TcxGridChartOptionsCustomize          See Also

Specifies whether end-users are able to drill down data.

property DataDrillDown: Boolean;

Description

When this property is set to True end-users are able to drill down data either by navigating data levels in a chart toolbox or by clicking data markers.  Otherwise, a drill-down can be performed only programmatically (for instance, using the View’s Controller.DataDrillDown method).

The default value of the DataDrillDown property is True.


TcxGridChartOptionsCustomize.DataDrillUpMethod

TcxGridChartOptionsCustomize          See Also

Specifies the manner in which end-users can drill up data.

type

  TcxGridChartDataDrillUpMethod = (ddumNone, ddumValueMouseRightButtonClick, ddumMouseRightButtonClick);

property DataDrillUpMethod: TcxGridChartDataDrillUpMethod;

Description

You can also use this property to prohibit end-users from activating lower levels of details (relative to the currently active data level).

All possible values for the DataDrillUpMethod property are listed in the following table.

Value	Meaning
DdumNone	End-users are unable to perform a drill-up.
ddumValueMouseRightButtonClick	End-users can perform a drill-up by right-clicking data markers of the corresponding series values.
ddumMouseRightButtonClick	End-users can perform a drill-up by right-clicking anywhere in the View’s area.

Use the View’s ActiveDataGroup and ActiveDataLevel properties to programmatically navigate data levels.

The default value of the DataDrillUpMethod property is ddumMouseRightButtonClick.


TcxGridChartOptionsCustomize.DataGroupHiding

TcxGridChartOptionsCustomize          See Also

Specifies the manner in which end-users can hide data groups in a chart toolbox.

property DataGroupHiding: Boolean;

Description

When this property is set to False, end-users can temporarily hide data groups and their corresponding data levels by dragging data group headers from a chart toolbox to the customization form.  Otherwise, end-users can hide data groups and data levels in this manner even if the customization form is not displayed.

The default value of the DataGroupHiding property is False.


TcxGridChartOptionsCustomize.DataGroupMoving

TcxGridChartOptionsCustomize          See Also

Specifies whether end-users can move and reposition data groups and their corresponding data levels in a Chart View by dragging data group headers.

property DataGroupMoving: Boolean;

Description

Set this property to True to allow end-users to move and reposition data groups in a chart toolbox and the ‘Data Groups’ tab in the customization form by dragging their headers.  Setting the DataGroupMoving property to False prohibits end-users from moving data groups and also hides the ‘Data Groups’ tab in the customization form.

The default value of the DataGroupMoving property is True.


TcxGridChartOptionsCustomize.OptionsCustomization

TcxGridChartOptionsCustomize          See Also

Specifies whether end-users can customize appearance aspects of a Chart View via the customization form.

property OptionsCustomization: Boolean;

Description

Set this property to True to display the ‘Options’ tab in the customization form.  This tab contains a number of settings that allow end-users to customize various appearance aspects of a Chart View’s visual elements such as a chart toolbox, chart legend, etc.

The default value of the OptionsCustomization property is True.


TcxGridChartOptionsCustomize.SeriesCustomization

TcxGridChartOptionsCustomize          See Also

Specifies whether end-users can customize the general appearance of series and arrange chart values in a Chart View via the customization form.

property SeriesCustomization: Boolean;

Description

Set this property to True to display the ‘Series’ tab in the customization form.  This tab contains a list of all series that provide values for rendering a chart and allows end-users to:

•	specify the series that should be displayed in a Chart View;

•	customize the plotting order of chart values by repositioning series within the list and applying sorting to a particular series.

The default value of the SeriesCustomization property is True.


TcxGridChartOptionsView
TcxGridChartOptionsView Object

Hierarchy          Properties

Represents appearance options for a Chart View.

Unit

cxGridChartView

TcxGridChartOptionsView = class(TcxCustomGridOptionsView)

Description

The TcxGridChartOptionsView class extends its ancestor class with the CategoriesPerPage property.  This property introduces paging capabilities and controls the number of categories simultaneously displayed within the active chart diagram.  Note that pie diagrams don’t support paging.

Use the View’s OptionsView property to access this set of options.


TcxGridChartOptionsView Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |

TcxCustomGridOptionsView

     |

TcxGridChartOptionsView


Properties for TcxGridChartOptionsView
TcxGridChartOptionsView Properties

TcxGridChartOptionsView          Legend

In TcxGridChartOptionsView

CategoriesPerPage

GridView

Derived from TcxCustomGridOptionsView

ScrollBars

Derived from TcxCustomGridOptions

GridView


TcxGridChartOptionsView.CategoriesPerPage

TcxGridChartOptionsView          See Also

Specifies the maximum number of categories simultaneously displayed within the active chart diagram.

property CategoriesPerPage: Integer;

Description

When this property is set to a value other than the default, a paging capability is introduced in the currently active diagram.  This value specifies the maximum number of categories simultaneously displayed within the diagram (fits in "a page").  Otherwise, all categories will be displayed.

When categories do not fit in a single page, a scroll bar is displayed along a category axis.

To specify the index of the first visible category in a paged diagram, use the View’s Controller.FirstVisibleCategoryIndex property.

Use the View’s Controller.ActiveDiagramSupportsPaging property to determine whether the currently active diagram supports paging.

Note:	By default, all diagrams except for pie diagrams support paging.

The default value of the CategoriesPerPage property is 0.


TcxGridChartOptionsView.GridView

TcxGridChartOptionsView

Provides access to the Chart View that owns the set of options.

property GridView: TcxGridChartView;

ReadOnly Property


TcxGridChartCategories
TcxGridChartCategories Object

Hierarchy          Properties          Methods          Events          See Also

Represents categories in a Chart View.

Unit

cxGridChartView

TcxGridChartCategories = class(TcxCustomGridOptions)

Description

A category is used to classify data for comparison.  Data groups are used to create a hierarchy of data levels which determine the categories into which series values are grouped/aggregated, and provide the drill-down functionality in Chart Views.

The default categories provide a simple classification of series values without aggregation.  In terms of databases, the default category stands for a data column which uniquely identifies and refers to the values (series values) within a data record.

Categories in unbound Chart Views are represented by an instance of the TcxGridChartCategories class (the TcxGridDBChartCategories class in data-aware Chart Views).  Like any chart item (a series or data group), this class provides an identifier which is used to address categories as a View item by the ID (accessible via the ID property).  Use the VisibleValues property to access the collection of values which correspond to the categories (called category values) that are displayed in the chart.  To access the category values which correspond to the default categories, use the Values property.

The default categories retrieve data from a data store with the help of the DataBinding object which provides properties that are used to define the data type of the category values, associate an arbitrary value (via the DataBinding.Data property) with the default categories and perform any additional operations required.

To modify properties of the default categories at design time, you need to select the rightmost data level in a chart toolbox (provided that the View’s ToolBox.DataLevelsInfoVisible option is enabled) and switch to the Object Inspector.


TcxGridChartCategories Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |

TcxGridChartCategories


Properties for TcxGridChartCategories
TcxGridChartCategories Properties

TcxGridChartCategories          Legend

In TcxGridChartCategories

DataBinding

DisplayText

GridView

ID

SortOrder

ValueCount

Values

VisibleDisplayTexts

VisibleValueCount

VisibleValues

Derived from TcxCustomGridOptions

GridView


Methods for TcxGridChartCategories
TcxGridChartCategories Methods

TcxGridChartCategories          Legend

In TcxGridChartCategories

GetDisplayText

GetValueDisplayText


Events for TcxGridChartCategories
TcxGridChartCategories Events

TcxGridChartCategories          Legend

In TcxGridChartCategories

OnGetValueDisplayText


TcxGridChartCategories.DataBinding

TcxGridChartCategories

Specifies an object which links the default categories to a data store.

property DataBinding: TcxGridChartItemDataBinding;

Description

Use the DataBinding property to specify the object which links the default categories that are associated with the current TcxGridChartCategories object instance to a data store.  You can use the properties of the DataBinding object to define the data type of category values, associate an arbitrary value (via the DataBinding.Data property) with the default categories and perform other operations.

At design time, you can select a value’s type for the default categories from the DataBinding.ValueType property which provides a list of the available data types.


TcxGridChartCategories.DisplayText

TcxGridChartCategories          See Also

Specifies the descriptive text for default categories.

property DisplayText: string;

Description

Use the GetDisplayText function to determine the descriptive text displayed for default categories.


TcxGridChartCategories.GridView

TcxGridChartCategories

Provides access to a Chart View which displays categories.

property GridView: TcxGridChartView;

ReadOnly Property


TcxGridChartCategories.ID

TcxGridChartCategories          See Also

Specifies the unique identifier assigned to categories.

property ID: Integer;

Description

Items in a View (series, data groups and categories in a Chart View) can be distinguished by their IDs.  IDs provide the unique identity of the items within the View.  When an item is deleted, a newly created item might get the ID of the deleted item.  Thus the IDs of items won't be reused within the current state of the View, but may be reused within the lifetime of the View.  This is a limit unique to these IDs.

ReadOnly Property


TcxGridChartCategories.SortOrder

TcxGridChartCategories

Specifies the order in which the values of the default categories are sorted.

type

  TcxDataSortOrder = (soNone, soAscending, soDescending);

property SortOrder: TcxDataSortOrder;

Description

The SortOrder property value directly affects the appearance of the default categories within the chart.  By default, the default categories are displayed in the order in which their values are stored in the View’s data controller.  The default plotting order of the default categories can be modified by applying sorting to them either via the SortOrder property or via the SortOrder property of the series.

Note:	The sorting applied to the series takes priority over the sorting by the default categories or data group.  Only a single type of sorting (either by the default categories/data group or series values) is active at a time within the chart.

To reverse the plotting order specified by these properties, set the category axis’s CategoriesInReverseOrder property to True.

The default value of the SortOrder property is soNone.


TcxGridChartCategories.ValueCount

TcxGridChartCategories          See Also

Specifies the total number of category values (the default categories) used to render the current View.

property ValueCount: Integer;

Description

All category values (the default categories) used to render the current View are stored within the Values collection.  Use the ValueCount property to obtain the total number of values within this collection.

By setting the ValueCount property for the default categories you can explicitly specify the total number of category values that will be used to render the current View.  This is useful when the chart needs to be displayed for some of series values or the available default categories only.  Setting the ValueCount property automatically affects all the series which are contained within the View (actually, all the records within the View’s data controller which correspond to the series and default categories displayed within the View).  If the new value that this property is set to is less than the old value then only the first ValueCount default categories (based upon the order of the default categories within the View’s data controller) are left within the View’s data controller.

Note:	If the new value of this property is greater than the old value of the property then a corresponding number of empty records are added to the data store of the View’s data controller.  This is a special case and is valid only in provider and unbound modes.


TcxGridChartCategories.Values

TcxGridChartCategories          See Also

Provides indexed access to the collection of category values that are used to render the current View.

property Values[Index: Integer]: Variant;

Description

Use the Values property to access category values (values of the default categories) that are used to render the current View.  To access category values that are displayed in the chart, use the VisibleValues zero-based indexed collection.

Use the ValueCount property to determine the number of the default categories in the chart.  The index of a category value corresponds to the order in which category values are stored in the View’s data controller.  Note that the View’s Categories.SortOrder property and the SortOrder property of series and data groups determine this order.


TcxGridChartCategories.VisibleDisplayTexts

TcxGridChartCategories

Returns the display text for a particular category value displayed within a chart.

property VisibleDisplayTexts[Index: Integer]: string;

Description

You can access category values displayed within a chart via the VisibleValues zero-based indexed collection.  The display text for a particular value from this collection can be obtained from the VisibleDisplayTexts collection using the same index.

By default, the display text for a category value can be determined using the GetValueDisplayText function.  You can handle the OnGetValueDisplayText event to customize a string representation of any category value.

Note:	a diagram’s AxisCategory.CategoriesInReverseOrder property has no effect on the order of elements within the VisibleDisplayTexts and VisibleValues collections.

ReadOnly Property


TcxGridChartCategories.VisibleValueCount

TcxGridChartCategories

Determines the total number of category values that are displayed within a Chart View.

property VisibleValueCount: Integer;

Description

Use the VisibleValues zero-based collection to access a particular category value.

ReadOnly Property


TcxGridChartCategories.VisibleValues

TcxGridChartCategories          See Also

Provides indexed access to the collection of category values that are displayed within a Chart View.

property VisibleValues[Index: Integer]: Variant;

Description

To get a particular category value, pass the category’s on-screen position as an index to the VisibleValues zero-based indexed collection.

Use the VisibleValueCount property to determine the total number of elements within the VisibleValues collection.

Compared with Values, the VisibleValues collection contains only category values that are displayed in a chart and these are sorted based upon display order.

You can use the View’s Categories.SortOrder and SortOrder properties of series and data groups to customize the display order of categories.

Note:	a diagram’s AxisCategory.CategoriesInReverseOrder property has no effect on the order of elements within the VisibleValues and VisibleDisplayTexts collections.

ReadOnly Property


TcxGridChartCategories.GetDisplayText

TcxGridChartCategories          See Also

Determines the descriptive text that is displayed for default categories.

function GetDisplayText: string;

Description

To specify this text, use the DisplayText property.  If not assigned, the scxGridChartCategoriesDisplayText resource string determines the descriptive text.

The text returned by the GetDisplayText function will appear in:

•	the category axis title (provided that a diagram’s AxisCategory.Title.Text property is assigned to an empty string);

•	a chart toolbox for the corresponding data level.


TcxGridChartCategories.GetValueDisplayText

TcxGridChartCategories          See Also

Determines the display text for the category value passed as the AValue .parameter

function GetValueDisplayText(const AValue: Variant): string;

Description

The text returned by this function is used to display:

•	value hints;

•	tick-mark labels.

You can handle the OnGetValueDisplayText event to customize display texts for category values.

Use the VisibleDisplayTexts zero-based indexed collection to obtain the display text for a particular category value by its on-screen position.


TcxGridChartCategories.OnGetValueDisplayText

TcxGridChartCategories          See Also

Occurs when the display text for a category value is to be determined.

type

  TcxGridChartGetValueDisplayTextEvent = procedure(Sender: TObject; const AValue: Variant; var ADisplayText: string) of object;

property OnGetValueDisplayText: TcxGridChartGetValueDisplayTextEvent;

Description

The Sender parameter references options for default categories.

A category value is passed as the AValue parameter.

Return the category value display text via the ADisplayText parameter pre-initialized by a string representation of this value.


TcxGridChartTitle
TcxGridChartTitle Object

Hierarchy          Properties          Methods

Represents a title within a chart.

Unit

cxGridChartView

TcxGridChartTitle = class(TcxCustomGridChartTitle)

Description

The TcxGridChartTitle class represents a title for a chart.  This class does not introduce any new functionality, but instead publishes the Position property which is inherited from the base class.  Use the Text property to specify the text of a title.


TcxGridChartTitle Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |

TcxCustomGridChartTitle

     |


Properties for TcxGridChartTitle
TcxGridChartTitle Properties

TcxGridChartTitle          Legend

Derived from TcxCustomGridChartTitle

Alignment

Position

Text

Derived from TcxCustomGridOptions

GridView


Methods for TcxGridChartTitle
TcxGridChartTitle Methods

TcxGridChartTitle          Legend

Derived from TcxCustomGridChartTitle

GetAlignment

GetOrientation

GetPosition

GetText


TcxGridChartToolBox
TcxGridChartToolBox Object

Hierarchy          Properties          Methods

Represents a panel (called a chart toolbox) to display tools that provide end-user customization of a diagram’s appearance.

Unit

cxGridChartView

TcxGridChartToolBox = class(TcxCustomGridOptions)

Description

In addition to the settings inherited from the base TcxCustomGridOptions class, the TcxGridChartToolBox class introduces properties that control the appearance of the following customization tools:

•	data level navigator (DataLevelsInfoVisible, DataLevelActiveValueDropDownCount, and DataLevelActiveValueDropDownWidth);

•	chart customization button (CustomizeButton);

•	diagram selector (DiagramSelector).

The TcxGridChartToolBox class also provides properties, which control appearance settings of a chart toolbox, as follows:

•	general appearance and position in a Chart View (Visible and Position);

•	border style (Border).

Use the View’s ToolBox property to access these options.


TcxGridChartToolBox Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomGridOptions

     |

TcxGridChartToolBox


Properties for TcxGridChartToolBox
TcxGridChartToolBox Properties

TcxGridChartToolBox          Legend

In TcxGridChartToolBox

Border

CustomizeButton

DataLevelActiveValueDropDownCount

DataLevelActiveValueDropDownWidth

DataLevelsInfoVisible

DiagramSelector

GridView

Position

Visible

Derived from TcxCustomGridOptions

GridView


Methods for TcxGridChartToolBox
TcxGridChartToolBox Methods

TcxGridChartToolBox          Legend

In TcxGridChartToolBox

GetDataLevelsInfoVisible

GetVisible


TcxGridChartToolBox.Border

TcxGridChartToolBox

Specifies the border style of the chart toolbox.

type

  TcxGridChartToolBoxBorder = (tbNone, tbSingle);

property Border: TcxGridChartToolBoxBorder;

Description

All possible values for this property are listed in the following table.

Value	Meaning
tbNone	No border is displayed around a chart toolbox.
tbSingle	A chart toolbox has a single-pixel line border displayed around it.

The default value of the Border property is tbSingle.


TcxGridChartToolBox.CustomizeButton

TcxGridChartToolBox          See Also

Specifies whether the chart customization button is displayed in the chart toolbox.

property CustomizeButton: Boolean;

Description

Set this property to True to display the chart customization button in the chart toolbox.  End-users can click this button to invoke or hide the customization form.

The default caption of this button (‘Customize Chart’) is determined by the scxGridChartToolBoxCustomizeButtonCaption resource string.

The default value of the CustomizeButton property is False.


TcxGridChartToolBox.DataLevelActiveValueDropDownCount

TcxGridChartToolBox          See Also

Specifies the maximum number of possible active values displayed in a data level dropdown at a given time.

property DataLevelActiveValueDropDownCount: Integer;

Description

If this property's value equals 0, the visible portion of a data level’s dropdown displays all possible active values associated with this data level.

The default value of the DataLevelActiveValueDropDownCount property is specified by the cxGridChartDefaultDataLevelActiveValueDropDownCount constant.


TcxGridChartToolBox.DataLevelActiveValueDropDownWidth

TcxGridChartToolBox          See Also

Specifies the width (in pixels) of all dropdowns associated with data levels that have active values assigned.

property DataLevelActiveValueDropDownWidth: Integer;

Description

Use the DataLevelActiveValueDropDownWidth property to limit the width of these dropdowns if their items are long strings.  By default, the width of a data level’s dropdown is calculated automatically to fit all its possible active values.  If the DataLevelActiveValueDropDownWidth property is set to a positive integer, the width of a dropdown is calculated as the maximum of a dropdown item’s width and the DataLevelActiveValueDropDownWidth value.  Thus, if this property's value exceeds the width of a dropdown item, then it specifies the actual width of a dropdown.  Otherwise, the width of a dropdown will be equal to the width of its item.

The default value of the DataLevelActiveValueDropDownWidth property is 0.


TcxGridChartToolBox.DataLevelsInfoVisible

TcxGridChartToolBox          See Also

Specifies whether the data level navigator is displayed in the chart toolbox.

type

  TcxGridChartDataLevelsInfoVisible = (dlivNever, dlivNonEmpty, dlivAlways);

property DataLevelsInfoVisible: TcxGridChartDataLevelsInfoVisible;

Description

All possible values for this property are listed in the following table.

Value	Meaning
dlivNever	The data level navigator is not displayed in a chart toolbox.  Note that in this instance, the ‘Data Groups’ tab will be hidden in the Customization Form and end-users will be unable to customize data levels and groups in a Chart View.
dlivNonEmpty	A chart toolbox displays the data level navigator when there is at least a single visible data group.
dlivAlways	The data level navigator is always displayed in a chart toolbox.  Compared to a value of dlivNonEmpty, when there are no visible data groups, only the data level associated with the default categories is displayed.

To determine whether the data level navigator is displayed in the chart toolbox, call the GetDataLevelsInfoVisible function.

The default value of the DataLevelsInfoVisible property is dlivNonEmpty.


TcxGridChartToolBox.DiagramSelector

TcxGridChartToolBox          See Also

Specifies whether the diagram selector is displayed in the chart toolbox.

property DiagramSelector: Boolean;

Description

Set this property to True to display the diagram selector within the chart toolbox.  Otherwise, this customization tool will be hidden.

The default value of the DiagramSelector property is False.


TcxGridChartToolBox.GridView

TcxGridChartToolBox

Provides access to a Chart View that displays the chart toolbox.

property GridView: TcxGridChartView;

ReadOnly Property


TcxGridChartToolBox.Position

TcxGridChartToolBox

Specifies the position of the chart toolbox within a chart.

type

  TcxGridChartToolBoxPosition = (tpTop, tpBottom);

property Position: TcxGridChartToolBoxPosition;

Description

All possible values for this property are listed in the following table.

Value	Meaning
tpTop	Chart toolbox is displayed above a diagram.
tpBottom	Chart toolbox is displayed under a diagram.

The default value of the Position property is tpTop.


TcxGridChartToolBox.Visible

TcxGridChartToolBox

Specifies whether the chart toolbox is displayed in a Chart View.

type

  TcxGridChartToolBoxVisible = (tvNever, tvNonEmpty, tvAlways);

property Visible: TcxGridChartToolBoxVisible;

Description

All possible values for this property are listed in the following table.

Value	Meaning
tvNever	Chart toolbox is hidden.
tvNonEmpty	Chart toolbox is displayed when at least a single customization tool is visible (the data level navigator, chart customization button or diagram selector).
tvAlways	Chart toolbox is always displayed, regardless of the availability of its customization tools.

To determine whether the chart toolbox is displayed in a Chart View, call the GetVisible function.

The default value of the Visible property is tvNonEmpty.


TcxGridChartToolBox.GetDataLevelsInfoVisible

TcxGridChartToolBox

Determines whether the data level navigator is displayed in the chart toolbox.

function GetDataLevelsInfoVisible: Boolean;

Description

This function returns True when the data level navigator is displayed in the chart toolbox.  Otherwise, this customization tool is hidden.

Use the DataLevelsInfoVisible property to control the general appearance of the data level navigator within a Chart View.


TcxGridChartToolBox.GetVisible

TcxGridChartToolBox

Determines whether the chart toolbox is displayed in a Chart View.

function GetVisible: Boolean;

Description

This function returns True when the chart toolbox is displayed in a Chart View.  Otherwise, this visual element is hidden.

Use the Visible property to control the general appearance of the chart toolbox within a Chart View.


TcxGridChartAxisPosition
TcxGridChartAxisPosition type

Enumerates the available positions for the axes within a chart.

Unit

cxGridChartView

type

  TcxGridChartAxisPosition = (cppLeft, cppTop, cppRight, cppBottom);

Description

The position of the axis within a chart is determined automatically based upon the type of the diagram and axis (either a category axis or a value axis) and, the options such as the CategoriesInReverseOrder property which also affect the position of the value axis.

All the possible values are listed in the following table.

Value	Meaning
cppLeft	An axis is displayed vertically on the left side of a chart’s plot area.
cppTop	An axis is displayed horizontally on the top side of a chart’s plot area.
cppRight	An axis is displayed vertically on the right side of a chart’s plot area.
cppBottom	An axis is displayed horizontally on the bottom side of a chart’s plot area.


TcxGridChartLegendBorder
TcxGridChartLegendBorder type

Enumerates the available border styles for legend elements.

Unit

cxGridChartView

type

  TcxGridChartLegendBorder = (lbDefault, lbNone, lbSingle);

Description

Use the Border and KeyBorder properties to set the border style of the chart legend and legend keys, respectively.

All the possible values are listed in the following table.

Value	Meaning
lbDefault	A legend element has the default (predefined) border style applied which actually represents one of the other possible values.
lbNone	No border is displayed around a legend element.
lbSingle	A legend element has a thin border (single-pixel width line) displayed around it.


TcxGridChartPartAlignment
TcxGridChartPartAlignment type

Enumerates the available alignments for the elements in a chart.

Unit

cxGridChartView

type

  TcxGridChartPartAlignment = (cpaDefault, cpaStart, cpaCenter, cpaEnd);

Description

There are several alignment options which can be applied to chart elements (for instance, a chart title and a chart legend).  The visual aspect of the alignment options depends also upon the element’s orientation (vertical or horizontal) within the chart.

All the possible values are listed in the following table.

Value	Meaning
cpaDefault	A chart element has the default (predefined) alignment within the chart which actually represents one of the other possible values.
cpaStart	A chart element is aligned to the top or left side of the chart’s plot area for a vertically or horizontally oriented chart element, respectively.
cpaCenter	A chart element is centered along the corresponding vertical or horizontal direction.
cpaEnd	A chart element is aligned to the bottom or right side of the chart’s plot area for a vertically or horizontally oriented chart element, respectively.


TcxGridChartPartOrientation
TcxGridChartPartOrientation type

Enumerates the available orientations for the elements in a chart.

Unit

cxGridChartView

type

  TcxGridChartPartOrientation = (cpoDefault, cpoHorizontal, cpoVertical);

Description

There are several orientation options for chart elements (for instance, a chart title and a chart legend).

All the possible values are listed in the following table.

Value	Meaning
cpoDefault	A chart element has the default (predefined) orientation within a chart which actually represents one of the other possible values.
cpoHorizontal	A chart element is horizontally oriented within a chart.
cpoVertical	A chart element is vertically oriented within a chart.


TcxGridChartPartPosition
TcxGridChartPartPosition type

Enumerates the available positions for the elements in a chart.

Unit

cxGridChartView

type

  TcxGridChartPartPosition = (cppDefault, cppNone, cppLeft, cppTop, cppRight, cppBottom);

Description

There are several possible positioning options for chart elements (for instance, a chart title, chart axis titles and a chart legend) whose positions are determined relative to the diagram’s area.

All the possible values are listed in the following table.

Value	Meaning
cppDefault	A chart element has the default (predefined) position within a chart which actually represents one of the other possible values.
cppNone	A chart element is not displayed within a chart.
cppLeft	A chart element is displayed to the left of the diagram.
cppTop	A chart element is displayed above the diagram.
cppRight	A chart element is displayed to the right of the diagram.
cppBottom	A chart element is displayed under the diagram.


TcxGridChartLineStyle
TcxGridChartLineStyle type

Enumerates the available line styles in chart diagrams.

Unit

cxGridChartView

type

  TcxGridChartLineStyle = (clsNone, clsSolid, clsDash, clsDot, clsDashDot, clsDashDotDot);

Description

Chart diagrams use various line styles to connect points.  For instance, you can customize line styles that connect adjacent value points in line and area diagrams.

All the possible values are listed in the following table.

Value	Meaning	Sample
clsNone	Points are not connected.
clsSolid	Points are connected using solid lines.
clsDash	Points are connected using dashed lines.
clsDot	Points are connected using dotted lines.
clsDashDot	Points are connected using dash-dotted lines.
clsDashDotDot	Points are connected using dash-double-dotted lines.


TcxGridChartMarkerStyle
TcxGridChartMarkerStyle type

Enumerates the available value marker styles in chart diagrams.

Unit

cxGridChartView

type

  TcxGridChartMarkerStyle = (cmsNone, cmsSquare, cmsTriangle, cmsDiamond, cmsCircle);

Description

You can use the following value marker styles to identify series in line and area diagrams.

Value	Meaning	Sample
cmsNone	Value markers are not displayed.
cmsSquare	Value markers represent squares.
cmsTriangle	Value markers represent triangles.
cmsDiamond	Value markers represent diamonds.
cmsCircle	Value markers represent circles.


TcxGridChartPieDiagramValueCaptionPosition
TcxGridChartPieDiagramValueCaptionPosition type

Enumerates the available positions of data labels on pie slices in pie diagrams.

Unit

cxGridChartView

type

  TcxGridChartPieDiagramValueCaptionPosition = (pdvcpNone, pdvcpCenter, pdvcpInsideEnd, pdvcpOutsideEnd, pdvcpOutsideEndWithLeaderLines);

Description

All the possible values are listed in the following table.

Value	Meaning
pdvcpNone	Data labels are not displayed.
pdvcpCenter	Data labels are drawn in the center of the corresponding pie slices.
pdvcpInsideEnd	Data labels are displayed inside pie slices and aligned to the end (the arc) of the corresponding pie slices.
pdvcpOutsideEnd	Data labels are displayed outside the data markers and aligned to the end (the arc) of the corresponding pie slices.
pdvcpOutsideEndWithLeaderLines	Data labels are displayed outside the pie slices.  A leader line is drawn from each pie slice to a corresponding data label.


cxGridChartView Unit Overview
cxGridChartView Unit

Classes

TcxCustomGridChartDiagramHitTest

TcxCustomGridChartDiagramOptions

TcxCustomGridChartHistogramAxisHitTest

TcxCustomGridChartTitle

TcxGridChartAreaDiagram

TcxGridChartAreaDiagramStyles

TcxGridChartBarDiagram

TcxGridChartCategories

TcxGridChartColumnDiagram

TcxGridChartColumnDiagramValues

TcxGridChartController

TcxGridChartCustomizeButtonHitTest

TcxGridChartDataController

TcxGridChartDataGroup

TcxGridChartDataLevelActiveValueInfoHitTest

TcxGridChartDataLevelActiveValuePopup

TcxGridChartDiagram

TcxGridChartDiagramSelectorPopup

TcxGridChartDiagramStyles

TcxGridChartHistogram

TcxGridChartHistogramAxis

TcxGridChartHistogramAxisCategory

TcxGridChartHistogramAxisTitle

TcxGridChartHistogramAxisValue

TcxGridChartHistogramCategoryAxisTitleHitTest

TcxGridChartHistogramPlotHitTest

TcxGridChartHistogramStyles

TcxGridChartHistogramValueAxisTitleHitTest

TcxGridChartHistogramValues

TcxGridChartItem

TcxGridChartItemDataBinding

TcxGridChartLegend

TcxGridChartLegendHitTest

TcxGridChartLegendItemHitTest

TcxGridChartLineDiagramAxisCategory

TcxGridChartLineDiagramStyles

TcxGridChartLineDiagramValues

TcxGridChartOptionsBehavior

TcxGridChartOptionsCustomize

TcxGridChartOptionsView

TcxGridChartPieDiagram

TcxGridChartPieDiagramStyles

TcxGridChartPieDiagramValues

TcxGridChartPieSeriesSiteCaptionHitTest

TcxGridChartPieSeriesSiteHitTest

TcxGridChartSeries

TcxGridChartSeriesStyles

TcxGridChartTitle

TcxGridChartTitleHitTest

TcxGridChartToolBox

TcxGridChartToolBoxHitTest

TcxGridChartValueAreaHitTest

TcxGridChartValueHitTest

TcxGridChartValueLineHitTest

TcxGridChartView

TcxGridChartViewData

TcxGridChartViewStyles

Other Types

TcxGridChartAxisPosition

TcxGridChartColumnDiagramValueCaptionPosition

TcxGridChartDataDrillUpMethod

TcxGridChartDataLevelsInfoVisible

TcxGridChartHistogramMinMaxValues

TcxGridChartHistogramTickMarkKind

TcxGridChartLegendBorder

TcxGridChartLineDiagramValueCaptionPosition

TcxGridChartLineStyle

TcxGridChartMarkerStyle

TcxGridChartPartAlignment

TcxGridChartPartOrientation

TcxGridChartPartPosition

TcxGridChartPieDiagramValueCaptionPosition

TcxGridChartToolBoxBorder

TcxGridChartToolBoxPosition

TcxGridChartToolBoxVisible

TcxGridChartValuesStacking

TcxGridChartPieDiagramValueCaptionItem

TcxGridChartPieDiagramValueCaptionItems

Global Constants

cxGridChartColumnDiagramDefaultBorderWidth

cxGridChartDefaultDataLevelActiveValueDropDownCount

cxGridChartItemDefaultSummaryKind

cxGridChartLineDiagramDefaultHotSpotSize

cxGridChartLineDiagramDefaultLineWidth

cxGridChartLineDiagramDefaultMarkerSize


TcxGridChartController
TcxGridChartController Object

Hierarchy          Properties          Methods

Represents a view controller for a Chart View.

Unit

cxGridChartView

TcxGridChartController = class(TcxCustomGridController)

Description

In addition to the settings inherited from the base TcxCustomGridController class, the TcxGridChartController class introduces members that allow you to:

•	drill down on a particular value (DataDrillDown);

•	drill up at a lower data level relative to the currently active data level (DataDrillUp);

•	obtain a value hint’s text for a specific chart value (GetValueHintText);

•	provide access to the customization form associated with the Chart View;

•	specify the index of the first visible category in a paged diagram.

The functionality of the TcxGridChartController class can be accessed via the View’s Controller property.


TcxGridChartController Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxGridViewHandler

     |

TcxCustomGridController

     |


Properties for TcxGridChartController
TcxGridChartController Properties

TcxGridChartController          Legend

In TcxGridChartController

CustomizationForm

FirstVisibleCategoryIndex

GridView

IsDataGroupMoving

MovingDataGroup

VisibleCategoryCount

Derived from TcxGridViewHandler

Control

Controller

DataController

GridView

ViewData


Methods for TcxGridChartController
TcxGridChartController Methods

TcxGridChartController          Legend

In TcxGridChartController

ActiveDiagramSupportsPaging

DataDrillDown

DataDrillUp

GetValueHintText

IsDataDrillDownPossible

Derived from TcxCustomGridController

Scroll

Derived from TcxGridViewHandler

BeginUpdate

Create

EndUpdate


TcxGridChartController.CustomizationForm

TcxGridChartController

Provides access to the customization form associated with the View controller.

property CustomizationForm: TcxGridChartCustomizationForm;

Description

When the customization form is not displayed, this property returns nil.

Use the View’s Controller.Customization property to toggle the visibility of the customization form.

The TcxGridChartCustomizationForm class is a TForm descendant.  To get the dimensions and position of the form, you can use the members inherited from TForm such as the BoundsRect or CustomizationFormBounds property.

Note:	All form properties except for CustomizationFormBounds can only be set only when the form is open.

The following code demonstrates how to open the customization form and make it translucent:

//Delphi

  if Grid.FocusedView is TcxGridChartView then

    with TcxGridChartController(Grid.FocusedView.Controller) do

      begin

        Customization := True;

        CustomizationForm.AlphaBlendValue := 200;

        CustomizationForm.AlphaBlend := True;

      end;

//C++ Builder

  if (dynamic_cast< TcxGridChartView *>(Grid->FocusedView)) {

    TcxGridChartController * AController =

      ((TcxGridChartController *)Grid->FocusedView)->Controller;

    AController->Customization = true;

    AController->CustomizationForm->AlphaBlendValue = 200;

    AController->CustomizationForm->AlphaBlend = true;

  }

ReadOnly Property


TcxGridChartController.FirstVisibleCategoryIndex

TcxGridChartController          See Also

Specifies the index of the first visible category in a paged diagram.

property FirstVisibleCategoryIndex: Integer;

Description

The specified category will become either the first visible category or will simply be scrolled into a view.  In the latter instance, the FirstVisibleCategoryIndex property will return the index of the first visible category.

The result of specifying this property depends upon the following settings:

•	the total number of categories in the View (ViewData.VisibleCategoryCount);

•	the number of categories displayed at a given time in a paged diagram (OptionsView.CategoriesPerPage);

•	the order used to display categories in a diagram (AxisCategory.CategoriesInReverseOrder).

After the first visible category has been changed, the View’s OnFirstVisibleCategoryIndex event is fired.


TcxGridChartController.GridView

TcxGridChartController

Provides access to the Chart View, which is controlled by the View controller.

property GridView: TcxGridChartView;

ReadOnly Property


TcxGridChartController.IsDataGroupMoving

TcxGridChartController

Indicates whether a data group is being moved/dragged within the Chart View.

property IsDataGroupMoving: Boolean;

Description

The IsDataGroupMoving returns True when a data group is being moved/dragged within the Chart View.  Otherwise, False is returned.

End-users are able to move data groups by dragging:

•	their headers in the ‘Data Groups’ tab of the customization form;

•	the corresponding data levels displayed in the data level navigator.

To access the data group being moved, use the MovingDataGroup property.

The IsDataGroupMoving property is useful when handling drag-and-drop operations on data groups and data levels.  Refer to the Implementing Drag-And-Drop Functionality topic for additional information.

ReadOnly Property


TcxGridChartController.MovingDataGroup

TcxGridChartController          See Also

Provides access to a data group being moved/dragged within the Chart View.

property MovingDataGroup: TcxGridChartDataGroup;

Description

Use the IsDataGroupMoving property to determine whether dragging of a data group has started in the Chart View.

The MovingDataGroup property is useful when handling drag-and-drop operations on data groups (data levels).  Refer to the Implementing Drag-And-Drop Functionality topic for additional information.

ReadOnly Property


TcxGridChartController.VisibleCategoryCount

TcxGridChartController

Returns the total number of categories that are currently visible in a diagram.

property VisibleCategoryCount: Integer;

Description

In a paged diagram, the value of the View’s OptionsView.CategoriesPerPage property limits the number of categories displayed in this diagram at a given time.  Otherwise, all categories are visible in a diagram.

Use the View’s Categories or ViewData.Categories property to access all category values associated with the View.  To access the category values that are currently visible in the View, use the View’s ViewData.VisibleCategories property.  This property is a zero-based indexed collection.

Note:	To display a particular category in a paged diagram, use the FirstVisibleCategoryIndex property.

ReadOnly Property


TcxGridChartController.ActiveDiagramSupportsPaging

TcxGridChartController          See Also

Determines whether the active diagram supports paging capabilities.

function ActiveDiagramSupportsPaging: Boolean;

Description

This function returns True when the active diagram supports paging capabilities.  Otherwise, False is returned.

By default, all diagrams except for pie diagrams support paging capabilities.


TcxGridChartController.DataDrillDown

TcxGridChartController          See Also

Performs a drill-down on the specified category value of the active data group.

function DataDrillDown(AValueIndex: Integer): Boolean; virtual;

Description

The AValueIndex parameter references the category value by its index in the active data group’s Values zero-based collection.  This function returns True when a drill-down was successful.  Otherwise, False is returned.

Alternatively, you can assign a category value to the active data group’s ActiveValue property to perform a drill-down on this value.

Note:	A drill-down cannot be performed on the default categories which represent the highest level of detail.

End-users are able to drill down data using the data level navigator.  To determine whether an end-user is able to drill down on a particular category value, call the IsDataDrillDownPossible function.

To perform a drill-up, call the DataDrillUp function.


TcxGridChartController.DataDrillUp

TcxGridChartController          See Also

Performs a drill-up (activates a lower data level relative to the currently active data level).

function DataDrillUp: Boolean; virtual;

Description

This function returns True when a drill-up was successful.  Otherwise, False is returned.

To activate a particular data level, use the View’s ActiveDataLevel or ActiveDataGroup property.

Note:	A drill-up cannot be performed at the lowest level of detail which corresponds to the first visible data group.

End-users are able to drill up data using the data level navigator.

To perform a drill-down on a particular category value of the active data group, call the DataDrillDown function.


TcxGridChartController.GetValueHintText

TcxGridChartController          See Also

Determines a value hint text for a specific chart value.

function GetValueHintText(ASeries: TcxGridChartSeries; AValueIndex: Integer): string; virtual;

Description

A chart value is referenced by a series and the value index in the Values collection of this series.  These values are passed as the ASeries and AValueIndex parameters, respectively.

By default, a value hint’s text includes the following:

•	the display text for the corresponding series;

•	labels on the category and series values which correspond to the value currently located under the mouse pointer.

The resulting text is determined using the format string specified by the scxGridChartValueHintFormat resource string.

To customize value hint text, handle the View’s OnGetValueHint event which uses the GetValueHintText function’s return value as its initial value string.

Use the View’s OptionsBehavior.ValueHints property to control the general appearance of value hints in the View.


TcxGridChartController.IsDataDrillDownPossible

TcxGridChartController

Determines whether an end-user can perform a drill-down on a particular category value of the active data group.

function IsDataDrillDownPossible(AValueIndex: Integer): Boolean;

Description

This function returns True when an end-user is able to perform a drill-down on the category value referenced by its index in the active data group’s Values zero-based collection.  The index is passed as the AValueIndex parameter

To drill down on a particular category value programmatically, call the DataDrillDown function and pass this category value as its parameter.

Note:	You can disable runtime drill-down functionality via the View’s OptionsCustomize.DataDrillDown property.


TcxGridChartDataController
TcxGridChartDataController Object

Hierarchy          Properties          Methods          Events         See Also

Represents a data controller which implements the functionality required to work with a data store.

Unit

cxGridChartView

TcxGridChartDataController = class(TcxDataController, IcxCustomGridDataController)

Description

A data controller implements the functionality required to work with a data store and perform operations on it (managing, addressing and setting options for sorting the data which correspond to the View items, i.e. categories and series).  The data controller provides information to a View.  You can use the View’s DataController property to get direct access to the data displayed by this View.  However, it's recommended that you use the View’s Categories, Series or ViewData properties for these purposes since they provide a more convenient way to manage the data which is associated with the View.

TcxGridChartDataController implements working in provider and unbound modes and enables you to populate a View from custom data sources.  To connect to a dataset, use a data-aware Chart View instead.  It retrieves and sets data using the TcxGridDBChartDataController class.

In provider mode, you need to create your own data source by deriving it from the TcxCustomDataSource class and by assigning its instance to the CustomDataSource property.  A data controller will retrieve data from the CustomDataSource by calling its methods internally.  You must override them to supply a data controller with the data which corresponds to each record/item.  In order to enable an end-user to post data to a custom data source, you must override the SetValue method declared by the TcxCustomDataSource class.

In contrast, for unbound mode, you have to populate a data controller record by record.  First, you must set the number of records via the RecordCount property.  Then each record value must be set manually via the Values property (for instance, by using the for operator).

Refer to the Data Loading Modes, Provider Mode and Unbound Mode sections for more details.


TcxGridChartDataController Hierarchy
Hierarchy

TPersistent

     |

TcxCustomDataController

     |

TcxDataController

     |


Properties for TcxGridChartDataController
TcxGridChartDataController Properties

TcxGridChartDataController          Legend

In TcxGridChartDataController

GridView

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 TcxGridChartDataController
TcxGridChartDataController Methods

TcxGridChartDataController          Legend

In TcxGridChartDataController

BeginFullUpdate

EndFullUpdate

Derived from TcxCustomDataController

Append

AppendRecord

BeginFullUpdate

BeginUpdate

Cancel

ChangeDetailExpanding

ChangeRowSelection

CheckFocusedSelected

ClearBookmark

ClearDetailLinkObject

ClearDetails

ClearSelection

ClearSorting

CollapseDetails

DeleteFocused

DeleteRecord

DeleteSelection

Edit

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 TcxGridChartDataController
TcxGridChartDataController Events

TcxGridChartDataController          Legend

Derived from TcxCustomDataController

OnAfterCancel

OnAfterDelete

OnAfterInsert

OnAfterPost

OnBeforeCancel

OnBeforeDelete

OnBeforeInsert

OnBeforePost

OnCompare

OnDataChanged

OnDetailCollapsed

OnDetailCollapsing

OnDetailExpanded

OnDetailExpanding

OnFilterRecord

OnGroupingChanged

OnNewRecord

OnRecordChanged

OnSortingChanged


TcxGridChartDataController.GridView

TcxGridChartDataController

Provides access to the Chart View whose data is managed by the data controller.

property GridView: TcxGridChartView;

ReadOnly Property


TcxGridChartDataController.BeginFullUpdate

TcxGridChartDataController

Prevents update notifications in the data controller and the Chart View that displays its data until a call to the EndFullUpdate method is made.

procedure BeginFullUpdate; override;

Description

This method locks (postpones update notifications to) the data controller which manages the data displayed in the Chart View and also locks the View by calling the View’s BeginUpdate method.  This may be useful since if only the data controller is locked multiple updates to the Chart View that displays the data may occur when the data controller is unlocked.

When using the BeginFullUpdate and EndFullUpdate methods, the Chart View that displays the data is unlocked only after its data controller has been unlocked and this ensures that the Chart View is updated only once which provides a performance benefit.


TcxGridChartDataController.EndFullUpdate

TcxGridChartDataController

Unlocks the data controller and its associated Chart View after a call to the BeginFullUpdate method.

procedure EndFullUpdate; override;

Description

Use the EndFullUpdate method to unlock the data controller and the Chart View that displays its data after they have been locked using the BeginFullUpdate method.  For this purpose the EndFullUpdate method calls the View’s EndUpdate method.  Note that the number of calls to the BeginFullUpdate method must match the number of EndFullUpdate method calls to ensure unlocking.  Thus, it's recommended to enclose the code performing the updates within try…finally blocks when performing a batch update.

When using the BeginFullUpdate and EndFullUpdate methods, the Chart View that displays the data is unlocked only after its data controller has been unlocked and this ensures that the Chart View is updated only once which gives a performance benefit.


TcxGridChartItemDataBinding
TcxGridChartItemDataBinding Object

Hierarchy          Properties          Methods

Represents an object which links a Chart View item to a data store.

Unit

cxGridChartView

TcxGridChartItemDataBinding = class(TPersistent)

Description

All Chart View items (series, data groups and the default categories) use a DataBinding object to link to a data store.  Generally, the data binding is used to determine the value's type.  The value’s type is identified by the ValueTypeClass property whose value determines the manner in which the data is represented (as a string, integer, date, boolean, etc.).  In bound mode the ValueTypeClass is assigned automatically based upon the field's type.  In the unbound and provider modes the ValueTypeClass has to be specified manually to ensure that the item works correctly. The ValueTypeClass and ValueType properties also provide a way in which unbound items can be implemented in data-aware Views.

The Data property is useful in provider mode, e.g. for indexing categories and series.  When in provider mode the custom data source cannot track changes to the displayed items (for instance, moving items) so data referencing is inadequate.  Use the Data property to assign a unique value to the items.  When using your custom data source refer to the Data property to identify the items.  See the Provider Mode topic for more information.

For series, the SummaryItem property of a DataBinding object provides access to a group summary calculated for the series.


TcxGridChartItemDataBinding Hierarchy
Hierarchy

TPersistent

     |

TcxGridChartItemDataBinding


Properties for TcxGridChartItemDataBinding
TcxGridChartItemDataBinding Properties

TcxGridChartItemDataBinding          Legend

In TcxGridChartItemDataBinding

Data

DataController

DataIndex

GridView

SummaryIndex

SummaryItem

ValueType

ValueTypeClass


Methods for TcxGridChartItemDataBinding
TcxGridChartItemDataBinding Methods

TcxGridChartItemDataBinding          Legend

In TcxGridChartItemDataBinding

GetValueDisplayText

IsValueTypeClassValid


TcxGridChartItemDataBinding.Data

TcxGridChartItemDataBinding

Allows you to store additional data within the data binding.

property Data: TObject;

Description

Use this property to store additional data within the TcxGridChartItemDataBinding class instance.

The Data property can be used to identify Chart View items when implementing a custom data source in provider mode.  A custom data source cannot recognize Chart View items by reading their indexes because they don't reflect any changes to the displayed items such as changes to their order.  Assign a unique value to the Data property and use this when getting/setting a value from/to a custom data source.  Refer to the Provider Mode topic for an example.


TcxGridChartItemDataBinding.DataController

TcxGridChartItemDataBinding

Provides access to the data controller which manages the Chart View item’s data.

property DataController: TcxCustomDataController;

ReadOnly Property


TcxGridChartItemDataBinding.DataIndex

TcxGridChartItemDataBinding

Determines the index of the item (a data field) in the data controller’s data store, which corresponds to the Chart View item’s DataBinding object.

property DataIndex: Integer;

Description

Use the DataIndex property value to determine the index of the item in the data controller’s data store, which corresponds to the Chart View item’s DataBinding object (for instance, to access the value of a specific item in the data controller’s data store which is accessible via the controller’s Values property).

ReadOnly Property


TcxGridChartItemDataBinding.GridView

TcxGridChartItemDataBinding

Provides access to the Chart View which displays the DataBinding item.

property GridView: TcxGridChartView;

ReadOnly Property


TcxGridChartItemDataBinding.SummaryIndex

TcxGridChartItemDataBinding

Determines the index of a group summary associated with the DataBinding object.

property SummaryIndex: Integer;

Description

If the DataBinding object is linked to a series, a group summary (a TcxDataSummaryItem object type) is automatically created for the linked series.  Once created, the group summary object can be accessed via the SummaryItem property.  The SummaryIndex property returns the index of the summary object in the View’s DataController.Summary.DefaultGroupSummaryItems collection.

ReadOnly Property


TcxGridChartItemDataBinding.SummaryItem

TcxGridChartItemDataBinding          See Also

Provides access to a group summary object created for a series linked to the DataBinding object.

property SummaryItem: TcxDataSummaryItem;

Description

Since only series provide values to calculate group summaries in Chart Views, a TcxDataSummaryItem group summary object type is automatically created for each series and can be accessed via the SummaryItem property.  For data groups and the default categories, the SummaryItem property returns nil.

The SummaryIndex property returns the index of the group summary object in the View’s DataController.Summary.DefaultGroupSummaryItems collection.

ReadOnly Property


TcxGridChartItemDataBinding.ValueType

TcxGridChartItemDataBinding

Specifies the string representation of the value type class.

property ValueType: string;

Description

The ValueType property specifies the string representation of the data type which the data binding provides.  Usually, you should only set the ValueType for unbound and provider modes.  This automatically designates the ValueTypeClass associated with this data type.  At design time, each item in a Chart View has the DataBinding.ValueType property which is represented by a list of the available data types.

In bound mode, the ValueTypeClass and ValueType properties are automatically assigned based on the field type.  To create an unbound item of the specified type in your data-aware Views, customize these properties as needed.  This also requires the DataBinding.FieldName property to be unassigned, the DataController.DataModeController.SmartRefresh property to be set to True and the DataController.KeyFieldNames property to have a value.


TcxGridChartItemDataBinding.ValueTypeClass

TcxGridChartItemDataBinding          See Also

Determines the data type of the data binding.

property ValueTypeClass: TcxValueTypeClass;

Description

The ValueTypeClass property specifies the data type of the data binding, thus determining the type of value an item represents.  Usually ValueTypeClass should only be set for the unbound and provider modes.  This ensures correct memory allocation, validation and sorting of item values.  The ValueType property specifies the string representation of the data type.  This property can be used to set an item’s data type at design time.

In bound mode, the ValueTypeClass and ValueType properties are assigned automatically based upon the field's type.  To create an unbound item of the specified type in your data-aware Views, customize these properties as needed.  This also requires the DataBinding.FieldName property to be unassigned, the DataController.DataModeController.SmartRefresh property to be set to True and the DataController.KeyFieldNames property to have a value.


TcxGridChartItemDataBinding.GetValueDisplayText

TcxGridChartItemDataBinding

Determines the display text for the chart item value passed as the AValue parameter.

function GetValueDisplayText(const AValue: Variant): string; virtual;

Description

Handle the chart item’s OnGetDisplayText event to customize display text values.


TcxGridChartItemDataBinding.IsValueTypeClassValid

TcxGridChartItemDataBinding          See Also

Determines whether the specified data type is valid for the DataBinding object.

function IsValueTypeClassValid(AValueTypeClass: TcxValueTypeClass): Boolean; virtual;

Description

Valid data types for series values (displayed as chart values in diagrams) are restricted to numeric data types, including binary-coded decimals (BCD) stored in TFMTBCDField fields.  As for categories, any data type is valid for data binding.  Use the IsValueTypeClassValid function to determine whether a specific data type is valid for the DataBinding object.  If the data type specified by the AValueTypeClass parameter is valid for data binding, the IsValueTypeClassValid function returns True.  Otherwise, it returns False.


TcxGridChartView
TcxGridChartView Object

Hierarchy          Properties          Methods          Events          See Also          Tutorial

Represents a View which displays data as a chart diagram.

Unit

cxGridChartView

TcxGridChartView = class(TcxCustomGridView)

Description

The TcxGridChartView class represents an unbound Chart View and provides the ability to visualize data using the following chart diagrams: bar, column, line, area, and pie diagrams.  A Chart View displays a single diagram at a time.

Series, data groups, and the default categories are called chart items.  These items provide data to be displayed in Chart Views.

Chart Views can optionally display a chart toolbox, a specially designed tools panel that provides:

•	end-user customization of a diagram’s appearance (the diagram selector and chart customization button);

•	an interactive data mining mechanism (the data level navigator).

In addition to the settings inherited from the base TcxCustomGridView class, the TcxGridChartView class introduces properties that control the following Chart View attributes, items, and visual elements:

•	appearance settings of each diagram type (DiagramBar, DiagramColumn, DiagramLine, DiagramArea, and DiagramPie);

•	the diagram that is used to render the View (ActiveDiagram);

•	diagram types available to render the View (AvailableDiagrams and AvailableDiagramCount);

•	series (Series, SeriesCount, VisibleSeries, VisibleSeriesCount, and SortedSeries);

•	data groups (DataGroups, DataGroupCount, VisibleDataGroups, and VisibleDataGroupCount);

•	the data level used to categorize chart values in the View and the data group which corresponds to this data level (ActiveDataLevel and ActiveDataGroup);

•	appearance settings of all categories, a chart’s title, toolbox, and legend (Categories, Title, Toolbox, and Legend, respectively);

•	option sets to customize various aspects of the Chart View, such as appearance settings, customization capabilities, and behavior in response to end-user actions (OptionsView, OptionsCustomize, and OptionsBehavior);

•	a set of styles of view elements (Styles);

•	data and view controllers (DataController and Controller).


TcxGridChartView Hierarchy
Hierarchy

TComponent

     |

TcxControlChildComponent

     |

TcxCustomGridView

     |


Properties for TcxGridChartView
TcxGridChartView Properties

TcxGridChartView          Legend

In TcxGridChartView

ActiveDataGroup

ActiveDataLevel

ActiveDiagram

AvailableDiagramCount

AvailableDiagrams

Categories

Controller

DataController

DataGroupCount

DataGroups

DataLevelCount

DataLevelObjects

DiagramArea

DiagramBar

DiagramColumn

DiagramCount

DiagramLine

DiagramPie

Diagrams

IsDataGrouped

Legend

OptionsBehavior

OptionsCustomize

OptionsView

Series

SeriesCount

SortedSeries

Styles

Title

ToolBox

ViewData

ViewInfo

VisibleDataGroupCount

VisibleDataGroups

VisibleSeries

VisibleSeriesCount

Derived from TcxCustomGridView

CloneCount

Clones

Controller

DataController

DragMode

Focused

IsControlFocused

IsDetail

IsMaster

IsPattern

Level

MasterGridRecordIndex

MasterGridView

MasterRecordIndex

OptionsSelection

OptionsView

PatternGridView

PopupMenu

Site

Styles

Synchronization

ViewData

ViewInfo

Visible

Derived from TcxControlChildComponent

Control

IsDestroying

IsLoading


Methods for TcxGridChartView
TcxGridChartView Methods

TcxGridChartView          Legend

In TcxGridChartView

CanActivateDataLevel

ClearDataGroups

ClearSeries

CreateDataGroup

CreateImage

CreateSeries

FindDataGroupByID

FindDataGroupByName

FindDataGroupByTag

FindDiagramByDisplayText

FindDiagramByID

FindSeriesByID

FindSeriesByName

FindSeriesByTag

GetDataGroupClass

GetSeriesClass

Derived from TcxCustomGridView

BeginUpdate

CancelUpdate

EndUpdate

GetHitTest

LayoutChanged

RestoreDefaults

RestoreFromIniFile

RestoreFromRegistry

RestoreFromStream

SizeChanged

StoreToIniFile

StoreToRegistry

StoreToStream

ViewChanged

Derived from TcxControlChildComponent

CreateEx

Destroy


Events for TcxGridChartView
TcxGridChartView Events

TcxGridChartView          Legend

In TcxGridChartView

OnActiveDataLevelChanged

OnActiveDiagramChanged

OnCustomDrawLegend

OnCustomDrawLegendItem

OnDataGroupPosChanged

OnFirstVisibleCategoryIndexChanged

OnGetValueHint

OnSeriesPosChanged

OnValueClick

Derived from TcxCustomGridView

OnDblClick

OnDragDrop

OnDragOver

OnEndDrag

OnGetStoredProperties

OnGetStoredPropertyValue

OnInitStoredObject

OnMouseDown

OnMouseEnter

OnMouseLeave

OnMouseUp

OnSetStoredPropertyValue

OnStartDrag


TcxGridChartView.ActiveDataGroup

TcxGridChartView          See Also

Specifies the active data group in the View.

property ActiveDataGroup: TcxGridChartDataGroup;

Description

The ActiveDataGroup and ActiveDataLevel properties allow you to implement data level navigation in code.

Once the ActiveDataGroup property is assigned a data group, this data group and the corresponding data level become active, provided that the data group is visible, and all data groups at lower data levels have their active values assigned.

Note that when the highest data level is active, the ActiveDataGroup property returns nil.

The following list summarizes operations carried out when activating a data group.

•	A drill-down to the sublevel - determined by its parent data level’s active value - is performed.

•	The data group’s Active property is set to True.

•	The ActiveDataLevel property is assigned to the data level that corresponds to this data group.  This fires the OnActiveDataLevelChanged event.

Once a data group is activated, its unique values determine the categories into which chart values are arranged in a chart.

Note:	To determine whether a particular data level (and the corresponding data group or default categories) can be activated, call the CanActivateDataLevel function.  To determine whether an active value is assigned to a data group, use the group’s HasActiveValue property.


TcxGridChartView.ActiveDataLevel

TcxGridChartView          See Also

Specifies the level of detail (also called the active data level) which is in effect in the View.

property ActiveDataLevel: Integer;

Description

The ActiveDataLevel and ActiveDataGroup properties allow you to implement level navigation in code.  Refer to the description of the ActiveDataGroup property to learn about activating data groups and levels in Chart Views.

The total number of data levels which are displayed within the View can be obtained via the DataLevelCount property.

Note that when the highest data level is active, the ActiveDataLevel property returns the DataLevelCount property value minus 1.


TcxGridChartView.ActiveDiagram

TcxGridChartView          See Also

Specifies the diagram which will be displayed (or active) within the View.

property ActiveDiagram: TcxGridChartDiagram;

Description

The chart displays a single diagram at a time.  The diagram which is currently displayed within the View (its Active property is set to True) is called active.  Set the ActiveDiagram property to specify the diagram which will be active within the View.  In order to make the specified diagram active its Enabled property needs to be set to True.  When the active diagram is changed the OnActiveDiagramChanged event is fired.  When the ActiveDiagram property is set to nil the first enabled diagram within the View’s Diagrams collection is activated and displayed within the View.  In this case the OnActiveDiagramChanged event is not raised.

Note:	To activate a specific diagram at design time, you can either choose the required diagram from the list of the available diagrams via the ActiveDiagram property in the Object Inspector window, or select the one using the Chart View’s diagram selector.


TcxGridChartView.AvailableDiagramCount

TcxGridChartView          See Also

Returns a count of chart diagrams within the AvailableDiagrams zero-based indexed collection.

property AvailableDiagramCount: Integer;

ReadOnly Property


TcxGridChartView.AvailableDiagrams

TcxGridChartView          See Also

Provides indexed access to all chart diagrams that can be displayed within the View.

property AvailableDiagrams[Index: Integer]: TcxGridChartDiagram;

Description

Use the AvailableDiagramCount property to obtain a count of diagrams within this collection.

ReadOnly Property


TcxGridChartView.Categories

TcxGridChartView          See Also

Specifies the categories used to classify data within the View.

property Categories: TcxGridChartCategories;

Description

Use the Categories property to specify the categories which will classify the data (the series values displayed) within the View for comparison purposes.  The categories in a Chart View are represented by an instance of the TcxGridChartCategories class which provides various properties for customizing the appearance of the categories within the View.


TcxGridChartView.Controller

TcxGridChartView

Provides access to the View's controller.

property Controller: TcxGridChartController;

Description

Refer to the description of the TcxGridChartController class to learn about the capabilities of a View controller.

ReadOnly Property


TcxGridChartView.DataController

TcxGridChartView

Specifies a data controller for the View.

property DataController: TcxGridChartDataController;

Description

Refer to the description of the TcxGridChartDataController class to learn about the capabilities of a data controller.


TcxGridChartView.DataGroupCount

TcxGridChartView          See Also

Gets a count of data groups in the View.

property DataGroupCount: Integer;

Description

To access a particular data group, use the DataGroups zero-based collection.

ReadOnly Property


TcxGridChartView.DataGroups

TcxGridChartView          See Also

Provides indexed access to all data groups in the View.

property DataGroups[Index: Integer]: TcxGridChartDataGroup;

Description

The index of a data group within the DataGroups collection is determined by the data group’s Index property.  Use the DataGroupCount property to get a count of all data groups within this collection.

To access data groups associated with data levels, use the VisibleDataGroups zero-based indexed collection.


TcxGridChartView.DataLevelCount

TcxGridChartView          See Also

Returns the total number of data levels defined in the View.

property DataLevelCount: Integer;

Description

Use the DataLevelObjects zero-based indexed collection to access data groups associated with data levels.

ReadOnly Property


TcxGridChartView.DataLevelObjects

TcxGridChartView          See Also

Provides indexed access to data groups associated with data levels in the View.

property DataLevelObjects[Index: Integer]: TcxGridChartDataGroup;

Description

This property returns the data group which is associated with the data level passed as an index.  For the data level that corresponds to default categories, nil is returned.

ReadOnly Property


TcxGridChartView.DiagramArea

TcxGridChartView          See Also

Provides access to appearance settings of area diagrams associated with the View.

property DiagramArea: TcxGridChartAreaDiagram;

Description

Refer to the description of the TcxGridChartAreaDiagram class to learn about area diagram appearance settings.


TcxGridChartView.DiagramBar

TcxGridChartView          See Also

Provides access to appearance settings of bar diagrams associated with the View.

property DiagramBar: TcxGridChartBarDiagram;

Description

Refer to the description of the TcxGridChartBarDiagram class to learn about bar diagram appearance settings.


TcxGridChartView.DiagramColumn

TcxGridChartView          See Also

Provides access to appearance settings of column diagrams associated with the View.

property DiagramColumn: TcxGridChartColumnDiagram;

Description

Refer to the description of the TcxGridChartColumnDiagram class to learn about column diagram appearance settings.


TcxGridChartView.DiagramCount

TcxGridChartView

Determines the total number of diagrams which are contained within the View.

property DiagramCount: Integer;

Description

Use the DiagramCount property to get the total number of diagrams which are contained within the View.  Use the Diagrams zero-based collection to access a specific diagram by its index.

ReadOnly Property


TcxGridChartView.DiagramLine

TcxGridChartView          See Also

Provides access to appearance settings of line diagrams associated with the View.

property DiagramLine: TcxGridChartLineDiagram;

Description

Refer to the description of the TcxGridChartLineDiagram class to learn about line diagram appearance settings.


TcxGridChartView.DiagramPie

TcxGridChartView          See Also

Provides access to appearance settings of pie diagrams associated with the View.

property DiagramPie: TcxGridChartPieDiagram;

Description

Refer to the description of the TcxGridChartPieDiagram class to learn about pie diagram appearance settings.


TcxGridChartView.Diagrams

TcxGridChartView          See Also

Provides indexed access to the diagrams which are contained within the View.

property Diagrams[Index: Integer]: TcxGridChartDiagram;

Description

Use the Diagrams zero-based indexed collection to access all the diagrams which are contained within the View.  Use the DiagramCount property to obtain a count of the total number of diagrams which are contained within the collection.

ReadOnly Property


TcxGridChartView.IsDataGrouped

TcxGridChartView          See Also

Determines whether series values displayed in the View are grouped in the same categories.

property IsDataGrouped: Boolean;

Description

This property returns True when at least a single data group is visible.

For grouped series values, chart values are calculated as specified by the GroupSummaryKind property of the series.

ReadOnly Property


TcxGridChartView.Legend

TcxGridChartView          See Also

Specifies the chart legend for the View.

property Legend: TcxGridChartLegend;

Description

Use the Legend property to specify the chart legend which can be displayed in the View for the currently active diagram to provide a key to what is displayed in the diagram.

An instance of the TcxGridChartLegend class represents a chart legend in a Chart View.  The TcxGridChartLegend class provides properties and methods for specifying the appearance aspects of a chart legend, arranging it within the chart and determining its current position within the chart.  All the properties which control the appearance aspects such as the position and orientation of the chart legend are initialized with default values that provide a standard appearance for charts.  Use the Chart View’s Legend property and the diagram’s Legend property to access the chart legend’s appearance options.

Note:	When there isn’t any series (series values) displayed within a diagram (the Visible property of the series is set to False) the chart legend is hidden as it isn't required.


TcxGridChartView.OptionsBehavior

TcxGridChartView          See Also

Provides access to settings that determine the View’s response to end-user actions.

property OptionsBehavior: TcxGridChartOptionsBehavior;

Description

Refer to the description of the TcxGridChartOptionsBehavior class to learn about available settings.


TcxGridChartView.OptionsCustomize

TcxGridChartView          See Also

Provides access to settings that determine end-user customization capabilities in the View.

property OptionsCustomize: TcxGridChartOptionsCustomize;

Description

Refer to the description of the TcxGridChartOptionsCustomize class to learn about available settings.


TcxGridChartView.OptionsView

TcxGridChartView          See Also

Provides access to settings that determine appearance aspects of the View.

property OptionsView: TcxGridChartOptionsView;

Description

Refer to the description of the TcxGridChartOptionsView class to learn about available settings.


TcxGridChartView.Series

TcxGridChartView          See Also

Provides indexed access to all the series for the View.

property Series[Index: Integer]: TcxGridChartSeries;

Description

Use the Series zero-based indexed collection to access all the series which provide series values for rendering the View.  The index of a series within this collection is determined by the Index property of the series.  Use the SeriesCount property to obtain a count of the total number of series whose values are available for displaying within the diagrams of the View.

To access all the series whose values were used to render the View (i.e., that are visible within the View), use the VisibleSeries property instead.  The total number of these series is accessible via the VisibleSeriesCount property.  To control the generic appearance of a specific series (its series values) within the View, set the Visible property of the series as needed.


TcxGridChartView.SeriesCount

TcxGridChartView          See Also

Gets a count of the total number of series within the View.

property SeriesCount: Integer;

Description

Use the SeriesCount property to obtain a count of the total number of series which provide series values for displaying within the View.  Use the Series zero-based collection to access a specific series by its index.  To access all the series whose values were used to render the View (i.e., that are visible within the View), use the VisibleSeries property instead.  The total number of these series is accessible via the VisibleSeriesCount property.

ReadOnly Property


TcxGridChartView.SortedSeries

TcxGridChartView

Specifies the series whose chart values are used to determine the plotting order of categories in the View.

property SortedSeries: TcxGridChartSeries;

Description

To cancel sorting by chart values, assign nil to the SortedSeries property.

Note:	Alternatively, you can apply sorting to a series via its SortOrder property.

End-users are able to customize sorting applied to series using the Customization Form.


TcxGridChartView.Styles

TcxGridChartView          See Also

Specifies a set of styles which manage the appearance aspects of the View's elements.

property Styles: TcxGridChartViewStyles;

Description

Use the Styles property to specify a set of styles which manage the appearance aspects of the elements of the View such as the chart legend and chart title and, the area of the Chart View which excludes the chart’s plot area.  Use the Legend, Title and Background properties to access the corresponding styles, respectively.

Note:	The style options specified for the chart legend within a diagram via the diagram’s Styles.Legend property override the style settings which were set via the View’s Styles.Legend property.


TcxGridChartView.Title

TcxGridChartView

Specifies the chart's title.

property Title: TcxGridChartTitle;

Description

Use the Title property to specify a chart title.  The TcxGridChartTitle class represents a chart title.  Use the Text property of this class to specify the text for the title.  You can manage the position of the title within the View via the Alignment and Position properties.


TcxGridChartView.ToolBox

TcxGridChartView

Provides access to appearance settings of a chart toolbox for the View.

property ToolBox: TcxGridChartToolBox;

Description

Refer to the description of the TcxGridChartToolBox class to learn about available appearance settings.


TcxGridChartView.ViewData

TcxGridChartView          See Also

Provides access to the data in the data store which correspond to the category values and series values.

property ViewData: TcxGridChartViewData;

Description

Use the ViewData property to access the data which is adapted from the data controller for displaying within the View and is represented by the category values and series values via the Categories and Values collections, respectively.  The position (index) of these values depends upon the order in which they are stored within the data controller (this in turn depends upon the sorting options applied via the View’s Categories.SortOrder property and the SortOrder properties of series).

Use the ViewData property to access the properties of the TcxGridChartViewData class for the View and modify the category values and series values as your needs dictate.

ReadOnly Property


TcxGridChartView.ViewInfo

TcxGridChartView

Provides access to the object which contains the information used to paint the View.

property ViewInfo: TcxGridChartViewInfo;

Description

The information provided by the ViewInfo property value is used internally and generally you don't need to use this property in your applications.

Note:	Along with providing the View’s painting information, the returned object allows you to determine the View element located at a particular point.  Since version 5 of the grid control, this can also be performed using a View’s GetHitTest method.

ReadOnly Property


TcxGridChartView.VisibleDataGroupCount

TcxGridChartView          See Also

Gets a count of data groups associated with data levels in the View.  These data groups are called visible data groups.

property VisibleDataGroupCount: Integer;

Description

To access a particular visible data group, use the VisibleDataGroups zero-based collection.

ReadOnly Property


TcxGridChartView.VisibleDataGroups

TcxGridChartView          See Also

Provides indexed access to all data groups associated with data levels in the View.  These data groups are called visible data groups.

property VisibleDataGroups[Index: Integer]: TcxGridChartDataGroup;

Description

Use the VisibleDataGroupCount property to get a count of all visible data groups within the VisibleDataGroups collection.

To access all data groups in the View, use the DataGroups zero-based indexed collection.

ReadOnly Property


TcxGridChartView.VisibleSeries

TcxGridChartView          See Also

Provides indexed access to all the series whose values are rendered in the View.

property VisibleSeries[Index: Integer]: TcxGridChartSeries;

Description

Use the VisibleSeries zero-based indexed collection to access all the series which provide series values for rendering the View (i.e., that are visible within the View).  For all these series the Visible property is set to True.  To hide the series values of a specific series set its Visible property to False.  Use the VisibleSeriesCount property to get a count of the total number of series that are currently visible within the View.  In order to access all the series within the View, use the Series collection and the SeriesCount property to obtain the total number of these series.

A series in a Chart View is represented by an instance of the TcxGridChartSeries class which provides various properties for customizing the appearance of the series within the View.

ReadOnly Property


TcxGridChartView.VisibleSeriesCount

TcxGridChartView          See Also

Gets a count of the total number of series whose values are rendered in the View.

property VisibleSeriesCount: Integer;

Description

Use the VisibleSeriesCount property to get a count of the total number of series which provide values for rendering the View (i.e., that are visible within the View).  Use the VisibleSeries zero-based collection to access a specific series by its index.  To access all the series whose series values are available for displaying within the View, use the Series collection instead.  The total number of these series is accessible via the SeriesCount property.

ReadOnly Property


TcxGridChartView.CanActivateDataLevel

TcxGridChartView

Determines whether the specified data level can be activated.

function CanActivateDataLevel(ALevel: Integer): Boolean;

Description

The data level is identified by its on-screen position passed as the ALevel parameter.

Note:	A data level becomes active provided that all lower data levels have their active values assigned.


TcxGridChartView.ClearDataGroups

TcxGridChartView          See Also

Removes all data groups from the View.

procedure ClearDataGroups;

Description

Calling this function removes all data groups from the DataGroups collection and results in categorizing series values by the default categories in a chart.


TcxGridChartView.ClearSeries

TcxGridChartView          See Also

Removes all the series that are associated with the View.

procedure ClearSeries;

Description

Call the ClearSeries method to remove all the series which provide series values for displaying within the View.  This automatically removes all the series from the Series collection and results in an empty View of the currently active diagram.


TcxGridChartView.CreateDataGroup

TcxGridChartView          See Also

Creates a data group in the View.

function CreateDataGroup: TcxGridChartDataGroup;

Description

This function creates a visible data group.  The generated data group is added to the VisibleDataGroups collection.


TcxGridChartView.CreateImage

TcxGridChartView

Creates an image of the Chart View.

function CreateImage(AGraphicClass: TGraphicClass; AWidth: Integer = 0; AHeight: Integer = 0): TGraphic;

Description

Call the CreateImage function to obtain a graphical representation (an image of the specified graphic class) of the Chart View.  The AGraphicClass parameter specifies the graphic class (either a bitmap or a metafile).  The optional AWidth and AHeight parameters specify the width and the height of the resulting image.  When the values of these parameters are equal to 0, the corresponding dimension of the image is calculated using the View’s visual parameters.  The CreateImage function returns nil for pattern Views and the graphic classes which do not inherit from the TBitmap or TMetafile classes.


TcxGridChartView.CreateSeries

TcxGridChartView          See Also

Creates a series for the View.

function CreateSeries: TcxGridChartSeries;

Description

Use the CreateSeries function to create a series for the View.  The created series is automatically added to the series whose values are used to render the View, which can be accessed via the VisibleSeries collection.


TcxGridChartView.FindDataGroupByID

TcxGridChartView          See Also

Searches for a data group which has a specified identifier.

function FindDataGroupByID(AID: Integer): TcxGridChartDataGroup;

Description

This function returns a data group whose ID property value equals the AID parameter value.  If no data group is found, nil is returned.

Note:	A data-aware Chart View includes a FindDataGroupByFieldName method to locate data groups that are connected to specific dataset fields.


TcxGridChartView.FindDataGroupByName

TcxGridChartView          See Also

Searches for a data group which has a specified name.

function FindDataGroupByName(const AName: string): TcxGridChartDataGroup;

Description

This function returns a data group whose Name property value equals the AName parameter value.  If no data group is found, nil is returned.


TcxGridChartView.FindDataGroupByTag

TcxGridChartView          See Also

Searches for a data group which has a specified tag value.

function FindDataGroupByTag(ATag: TTag): TcxGridChartDataGroup;

Description

This function returns a data group whose Tag property value equals the ATag parameter value.  If no data group is found, nil is returned.


TcxGridChartView.FindDiagramByDisplayText

TcxGridChartView          See Also

Searches for a diagram which has a specified descriptive text.

function FindDiagramByDisplayText(const ADisplayText: string): TcxGridChartDiagram;

Description

This function returns a diagram whose DisplayText property value equals the ADisplayText parameter value.  If no diagram is found, nil is returned.


TcxGridChartView.FindDiagramByID

TcxGridChartView

Searches for a diagram which has a specified identifier.

function FindDiagramByID(const AID: string): TcxGridChartDiagram;

Description

This function returns a diagram whose ID property value equals the AID parameter value.  If no diagram is found, nil is returned.


TcxGridChartView.FindSeriesByID

TcxGridChartView          See Also

Searches for a series within the View which has the specified identifier.

function FindSeriesByID(AID: Integer): TcxGridChartSeries;

Description

Call the FindSeriesByID function to locate a series within the View according to the identifier which is assigned to the series via the ID property.  This function returns the series with the identifier specified by the AID parameter.  If no series is found, nil is returned.

A data-aware Chart View has the FindSeriesByFieldName method to locate series which are connected to specific dataset fields.


TcxGridChartView.FindSeriesByName

TcxGridChartView          See Also

Searches for a series which has the specified name.

function FindSeriesByName(const AName: string): TcxGridChartSeries;

Description

Call the FindSeriesByName function to locate a series with the name specified by the AName parameter.  The name can be assigned to a series via its Name property.  This function returns the series with the specified name.  If no series is found, nil is returned.


TcxGridChartView.FindSeriesByTag

TcxGridChartView          See Also

Searches for a series which has the specified tag value.

function FindSeriesByTag(ATag: TTag): TcxGridChartSeries;

Description

Call the FindSeriesByTag function to locate a series with the tag value specified by the ATag parameter.  This can be useful when creating series and accessing them at runtime.  The tag value can be assigned to a series via its Tag property.  This function returns the series with the specified tag value.  If no series is found, nil is returned.


TcxGridChartView.GetDataGroupClass

TcxGridChartView          See Also

Returns the class type associated with data groups in the View.

type

  TcxGridChartDataGroupClass = class of TcxGridChartDataGroup;

function GetDataGroupClass: TcxGridChartDataGroupClass; virtual;

Description

By default, this function returns TcxGridChartDataGroup.  TcxGridChartView descendants (for instance, data-aware Chart Views of the TcxGridDBChartView class) override this function to return an appropriate class type for each particular View.


TcxGridChartView.GetSeriesClass

TcxGridChartView          See Also

Returns the class type associated with series in the View.

type

  TcxGridChartSeriesClass = class of TcxGridChartSeries;

function GetSeriesClass: TcxGridChartSeriesClass; virtual;

Description

By default, this function returns TcxGridChartSeries.  TcxGridChartView descendants (for instance, data-aware Chart Views of the TcxGridDBChartView class) override this function to return an appropriate class type for each particular View.


TcxGridChartView.OnActiveDataLevelChanged

TcxGridChartView          See Also

Occurs after the active data level has been changed.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnActiveDataLevelChanged: TNotifyEvent;

Description

This event is fired if:

•	a data level is activated via the ActiveDataLevel property;

•	a data group is activated via the ActiveDataGroup or the group’s Active property.

The Sender parameter specifies the View in which the active data level has been changed.

End-users can navigate data levels and perform drill-down and drill-up operations using the data level navigator.


TcxGridChartView.OnActiveDiagramChanged

TcxGridChartView          See Also

Occurs when an active diagram is changed.

type

  TcxGridChartDiagramEvent = procedure(Sender: TcxGridChartView; ADiagram: TcxGridChartDiagram) of object;

property OnActiveDiagramChanged: TcxGridChartDiagramEvent;

Description

The OnActiveDiagramChanged event is fired when the currently active diagram (which is accessible via the ActiveDiagram property) is changed.  The ADiagram parameter refers to the diagram which becomes active within the View specified by the Sender parameter.

To activate a specific diagram, set the diagram’s Active property to True.

Note:	When the ActiveDiagram property is set to nil and the first enabled diagram within the View’s Diagrams collection is activated and displayed within the View the OnActiveDiagramChanged event is not raised.


TcxGridChartView.OnCustomDrawLegend

TcxGridChartView          See Also

Occurs when a chart legend within the View needs to be painted.

type

  TcxGridChartLegendCustomDrawEvent = procedure(Sender: TcxGridChartView; ACanvas: TcxCanvas; AViewInfo: TcxGridChartLegendViewInfo; var ADone: Boolean) of object;

property OnCustomDrawLegend: TcxGridChartLegendCustomDrawEvent;

Description

The OnCustomDrawLegend event occurs every time a chart legend’s area within the View needs to be painted.  As with other custom draw events it provides a canvas for the grid control (the ACanvas parameter), ViewInfo (the AViewInfo parameter and its Bounds property) to get the bounding rectangle of the painted element (in this case the chart legend).  Sender is usually the element that caused the repaint.  The ADone parameter’s value is initially False.  Set it to True to tell the grid that you have chosen to custom draw the chart legend.

Note:	The Chart View’s OnCustomDrawLegend event can override the diagram’s OnCustomDrawLegend event since the former is fired after the latter.

To learn more about custom drawing, please refer to the Custom Draw topic.


TcxGridChartView.OnCustomDrawLegendItem

TcxGridChartView          See Also

Occurs when a legend item within the View needs to be painted.

type

  TcxGridChartLegendItemCustomDrawEvent = procedure(Sender: TcxGridChartView; ACanvas: TcxCanvas; AViewInfo: TcxGridChartLegendItemViewInfo; var ADone: Boolean) of object;

property OnCustomDrawLegendItem: TcxGridChartLegendItemCustomDrawEvent;

Description

The OnCustomDrawLegendItem event occurs every time a legend item (a legend key and its description, i.e. the display text of the series that corresponds to the legend item) within the View needs to be painted.  As with other custom draw events it provides a canvas for the grid control (the ACanvas parameter), ViewInfo (the AViewInfo parameter and its Bounds property) to get the bounding rectangle of the painted element (in this case the legend item).  Sender is usually the element that caused the repaint.  The ADone parameter’s value is initially False.  Set it to True to tell the grid that you have chosen to custom draw the legend item.

Note:	The Chart View’s OnCustomDrawLegendItem event can override the diagram’s OnCustomDrawLegendItem event since the former is fired after the latter.

To learn more about custom drawing, please refer to the Custom Draw topic.


TcxGridChartView.OnDataGroupPosChanged

TcxGridChartView          See Also

Occurs when an end-user repositions a data level in the data level navigator.

type

  TcxGridChartDataGroupEvent = procedure(Sender: TcxGridChartView; ADataGroup: TcxGridChartDataGroup) of object;

property OnDataGroupPosChanged: TcxGridChartDataGroupEvent;

Description

This event is fired after the position of a data level associated with the ADataGroup visible data group has been modified.

Note:	The data level associated with the default categories cannot be repositioned in this manner.

The general appearance of the data level navigator within a chart toolbox is controlled by the View’s ToolBox.DataLevelsInfoVisible property.

You can modify the position of a data level in code using the corresponding data group’s Index property.  Note that this doesn’t fire the OnDataGroupPosChanged event.


TcxGridChartView.OnFirstVisibleCategoryIndexChanged

TcxGridChartView

Occurs after the first visible category in a paged diagram has been changed.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnFirstVisibleCategoryIndexChanged: TNotifyEvent;

Description

The fist visible category can be changed either by scrolling, or by assigning a new value to the Controller.FirstVisibleCategoryIndex property.

The Sender parameter specifies the Chart View which displays the paged diagram.

Note:	A diagram is considered to be paged when the OptionsView.CategoriesPerPage property is set to a value other than 0.


TcxGridChartView.OnGetValueHint

TcxGridChartView          See Also

Occurs when the text of a hint for a series value in the View needs to be determined.

type

  TcxGridChartGetValueHintEvent = procedure(Sender: TcxGridChartView; ASeries: TcxGridChartSeries; AValueIndex: Integer; var AHint: string) of object;

property OnGetValueHint: TcxGridChartGetValueHintEvent;

Description

To provide detailed information on the values (their data markers) shown in the chart, Chart Views are capable of displaying value hints when an end-user hovers the mouse over the values.  Handle the View’s OnGetValueHint event to customize the text of the value hint for a series value in the View specified by the Sender parameter.  The series value is addressed by the ASeries and AValueIndex parameters which specify the series and the index of the series value in the Values collection of the corresponding series, respectively.  The text of the value hint is returned via the AHint parameter which initially equals the GetValueHintText function’s return value.

By default, the text of the value hints which is returned by the GetValueHintText function includes the display text for the corresponding series and string representations of the corresponding category label and series value (as they appear in the chart according to the corresponding formats applied) for the value which is currently under the mouse pointer.  The resulting information string is determined using the format string as specified by the scxGridChartValueHintFormat resource string.

Use the Chart View’s OptionsBehavior.ValueHints property to control the general appearance of the value hints within the View.


TcxGridChartView.OnSeriesPosChanged

TcxGridChartView

Occurs when an end-user modifies the visible position of a series in categories.

type

  TcxGridChartSeriesEvent = procedure(Sender: TcxGridChartView; ASeries: TcxGridChartSeries) of object;

property OnSeriesPosChanged: TcxGridChartSeriesEvent;

Description

End-users are able to modify the visible position of series in categories via a checklist in the ’Series’ tab of the Customization Form.  The OnSeriesPosChanged event is fired if:

•	the display order of series is changed via drag and drop in the checklist.  The ASeries parameter specifies the series being dragged;

•	the visible state of a series is modified using the corresponding check box in the checklist.  The ASeries parameter specifies the series whose visible state is changed.

Note:	The general appearance of the ’Series’ tab is controlled by the View’s OptionsCustomize.SeriesCustomization property.

You can modify the visible position and state of a series in code via its Index and Visible properties, respectively.  Note that this doesn’t fire the OnSeriesPosChanged event.


TcxGridChartView.OnValueClick

TcxGridChartView

Occurs when a data marker for a particular chart value is clicked.

type

  TcxGridChartValueClickEvent = procedure(Sender: TcxGridChartView; ASeries: TcxGridChartSeries; AValueIndex: Integer; var AHandled: Boolean) of object;

property OnValueClick: TcxGridChartValueClickEvent;

Description

This event is fired for instance, when a drill-down is performed.  Note that this event is fired even when:

•	the drill-down functionality is disabled via the View’s OptionsCustomize.DataDrillDown property;

•	a drill-down cannot be performed (the View’s Controller.IsDataDrillDownPossible function returns False).

The Sender parameter references the Chart View.

The ASeries parameter identifies the series whose value has been clicked.

The AValueIndex corresponds to the index of the chart value being clicked in the VisibleValues collection of ASeries.

Set the AHandled parameter to True to cancel a drill-down operation.

Note:	The OnValueClick event of a series can override the View’s OnValueClick event since the series OnValueClick event is fired last.


TcxGridChartViewData
TcxGridChartViewData Object

Hierarchy          Properties          Methods          See Also

Represents the class which provides data from data store as category values and series values.

Unit

cxGridChartView

TcxGridChartViewData = class(TcxCustomGridViewData)

Description

The TcxGridChartViewData class is a bridge between the data controller and the Chart View’s data representation.  This class adapts values provided by the data controller for displaying within the View (accessible via the Categories and Values collections) and represents them on screen as category values and series values (accessible via the VisibleCategories and VisibleValues collections, respectively) according to the sorting options applied via the View’s Categories.SortOrder property and the SortOrder property of series and data groups.

The View’s ViewData property allows you to access the properties of the TcxGridChartViewData class for this View and modify the category values and series values as required for display purposes.


TcxGridChartViewData Hierarchy
Hierarchy

TObject

     |

TcxGridViewHandler

     |

TcxCustomGridViewData

     |


Properties for TcxGridChartViewData
TcxGridChartViewData Properties

TcxGridChartViewData          Legend

In TcxGridChartViewData

Categories

CategoryCount

GridView

GroupValues

SumOfValues

VisibleCategories

Values

VisibleCategoryCount

VisibleGroupValueCount

VisibleGroupValues

VisibleValues

Derived from TcxGridViewHandler

Control

Controller

DataController

GridView

ViewData


Methods for TcxGridChartViewData
TcxGridChartViewData Methods

TcxGridChartViewData          Legend

In TcxGridChartViewData

GetVisibleGroupValues

Derived from TcxGridViewHandler

BeginUpdate

Create

EndUpdate


TcxGridChartViewData.Categories

TcxGridChartViewData          See Also

Provides indexed access to values of the default categories associated with the View.

property Categories[AIndex: Integer]: Variant;

Description

Use the Categories zero-based indexed collection to access and modify a specific category value provided by the data controller for displaying within the View.  The AIndex parameter specifies the index of the category value in the collection of category values.  Alternatively, you can use the View’s Categories.Values collection for this purpose.

Use the VisibleCategories collection to access values of the default categories that are currently displayed in the View.

Note:	The View’s Categories.SortOrder property and the SortOrder property of series and data groups don’t affect the order in which category values are stored within the Categories collection.


TcxGridChartViewData.GridView

TcxGridChartViewData

Provides access to the Chart View which displays the data.

property GridView: TcxGridChartView;

Description

Use the GridView property to access the Chart View that displays the data associated with the ViewData object.  This property provides access to the View items, style sets, etc.

ReadOnly Property


TcxGridChartViewData.GroupValues

TcxGridChartViewData          See Also

Provides indexed access to category values associated with data groups.

property GroupValues[ADataGroupIndex, AIndex: Integer]: Variant;

Description

The ADataGroupIndex parameter specifies the index of a data group in the DataGroups collection.

The AIndex parameter specifies the index of the category value within the data group’s Values collection.

Note:	The View’s Categories.SortOrder property and the SortOrder property of series and data groups don’t affect the order of storing values within the GroupValues collection.

To access category values associated with a particular visible data group, use the VisibleGroupValues collection.


TcxGridChartViewData.SumOfValues

TcxGridChartViewData          See Also

Returns the sum of values of the series whose index is passed as the ASeriesIndex parameter.

property SumOfValues[ASeriesIndex: Integer]: Variant;

Description

The index of a series can be obtained via its Index property.

ReadOnly Property


TcxGridChartViewData.CategoryCount

TcxGridChartViewData          See Also

Specifies the total number of series values within each series used to render the View.

property CategoryCount: Integer;

Description

Use the CategoryCount property to obtain the total number of series values within each series used to render the View.  Values of all series, data groups, and the default categories provided by the data controller can be accessed via the Values, GroupValues, and Categories collections, respectively.

By setting the CategoryCount property you can explicitly specify the total number of series values in each series that will be used to render the View.  This is useful when it's necessary to display the chart for a portion of series values.  Setting the CategoryCount property automatically affects all the series which are contained within the View (i.e., all the records within the data controller which correspond to the series displayed within the View).  If the new value of this property is less than the current value of the property then only the first CategoryCount series values (according to the order of the series values within the View’s data controller) are left within the View’s data controller.

Note:	If the new value of this property is greater than the current value of the property then the corresponding number of empty records is added to the data store of the View’s data controller.  This is a special case and is valid only in provider and unbound modes.


TcxGridChartViewData.Values

TcxGridChartViewData          See Also

Provides indexed access to series values associated with the View.

property Values[ASeriesIndex, AIndex: Integer]: Variant;

Description

Use the Values zero-based indexed collection to access and modify a specific series value provided by the data controller for displaying in the View.  The ASeriesIndex and AIndex parameters specify correspondingly the index of the series in the collection of series and the index of the series value within the collection of series values in this series.  Alternatively, you can use the Values collection of a specific series for this purpose.

Note:	The View’s Categories.SortOrder property and the SortOrder property of series and data groups don’t affect the order in which series values are stored within the Values collection.


TcxGridChartViewData.VisibleCategories

TcxGridChartViewData

Provides indexed access to values of the categories displayed within the View.

property VisibleCategories[AIndex: Integer]: Variant;

Description

A category value is referenced by its on-screen position passed as an index to the VisibleCategories zero-based collection.

Use the View’s Controller.VisibleCategoryCount to determine the total number of categories displayed within the View.

To access and modify values of the default categories, use the Categories collection.

You can use the View’s Categories.SortOrder and SortOrder properties of series and data groups to customize the order of elements in the VisibleCategories collection.

ReadOnly Property


TcxGridChartViewData.VisibleGroupValueCount

TcxGridChartViewData

Determines the total number of category values associated with a particular visible data group.

property VisibleGroupValueCount[AVisibleDataGroupIndex: Integer]: Integer;

Description

A visible data group is referenced by its index passed as the AVisibleDataGroupIndex parameter.  Note that the VisibleGroupValueCount property returns 0 when the data group at a lower level (relative to the specified visible data group) has no active value assigned.

To access category values associated with a particular visible data group, use the VisibleGroupValues collection.

ReadOnly Property


TcxGridChartViewData.VisibleGroupValues

TcxGridChartViewData          See Also

Provides indexed access to category values associated with a particular visible data group.

property VisibleGroupValues[AVisibleDataGroupIndex, AIndex: Integer]: Variant;

Description

The AVisibleDataGroupIndex parameter specifies the index of a visible data group in the VisibleDataGroups collection.

The AIndex parameter specifies the index of the category value within the data group’s VisibleValues collection.

Use the VisibleGroupValueCount property to determine the total number of category values associated with a particular visible data group.

To access category values associated with a particular data group, use the GroupValues collection.

ReadOnly Property


TcxGridChartViewData.VisibleCategoryCount

TcxGridChartViewData          See Also

Determines the total number of categories into which chart values are arranged in a chart.

property VisibleCategoryCount: Integer;

Description

In a paged diagram, this property value includes categories that don’t fit into the currently displayed page.

To access a particular category value, use the VisibleCategories zero-based indexed collection.

ReadOnly Property


TcxGridChartViewData.VisibleValues

TcxGridChartViewData          See Also

Provides indexed access to the chart values displayed within the View.

property VisibleValues[ASeriesIndex, AIndex: Integer]: Variant;

Description

The ASeriesIndex parameter specifies the index of a series in the View’s Series collection.

The AIndex parameter specifies the on-screen position of the category in which the chart value is displayed.  In a paged diagram, this parameter’s value includes categories that don’t fit into the currently displayed page.

To access all series values associated with the View, use the Values collection.

You can use the View’s Categories.SortOrder and SortOrder properties of series and data groups to customize the order of elements in the VisibleValues collection.

ReadOnly Property


TcxGridChartViewData.GetVisibleGroupValues

TcxGridChartViewData          See Also

Returns the values and their string representations of categories associated with a particular visible data group.

procedure GetVisibleGroupValues(ADataGroup: TcxGridChartDataGroup; AStrings: TStrings; out AValues: TVariantArray);

Description

The ADataGroup parameter specifies the visible data group.

Category values associated with this data group and their string representations are returned as arrays via the AStrings and AValues parameters.

Note:	When a visible data group and the data level associated with this data group cannot be activated, empty arrays are returned.  For hidden data groups, the GetVisibleGroupValues method returns category values associated with the data group at the lowest level of detail (the first visible data group).

Use the View’s CanActivateDataLevel function to determine whether a visible data group/level can be activated.


cxGridChartColumnDiagramDefaultBorderWidth constant
cxGridChartColumnDiagramDefaultBorderWidth global constant

Specifies the default width of the border (in pixels) for values (data markers).

Unit

cxGridChartView

cxGridChartColumnDiagramDefaultBorderWidth = 1;

Description

This constant determines the default value of a column or bar diagram’s Values.BorderWidth property which specifies the width of the border (in pixels) for all data markers within the diagram.


cxGridChartDefaultDataLevelActiveValueDropDownCount constant
cxGridChartDefaultDataLevelActiveValueDropDownCount global constant

Specifies the maximum number of values displayed at one time by default in a data level dropdown.

Unit

cxGridChartView

cxGridChartDefaultDataLevelActiveValueDropDownCount = 15;

Description

This constant determines the default value of the View’s Toolbox.DataLevelActiveValueDropDownCount property.


cxGridChartItemDefaultSummaryKind constant
cxGridChartItemDefaultSummaryKind global constant

Specifies the default summary function which is used to calculate group summaries against series values.

Unit

cxGridChartView

cxGridChartItemDefaultSummaryKind = skSum;

Description

This constant determines the default value of the GroupSummaryKind property of a series.


cxGridChartLineDiagramDefaultHotSpotSize constant
cxGridChartLineDiagramDefaultHotSpotSize global constant

Specifies the default width (in pixels) of value hotspots.

Unit

cxGridChartView

cxGridChartLineDiagramDefaultHotSpotSize = 15;

Description

This constant determines the default value of a line or area diagram’s Values.HotSpotSize property.


cxGridChartLineDiagramDefaultLineWidth constant
cxGridChartLineDiagramDefaultLineWidth global constant

Specifies the default width (in pixels) of lines that connect value points in line and area diagrams.

Unit

cxGridChartView

cxGridChartLineDiagramDefaultLineWidth = 1;

Description

This constant determines the default value of a line or area diagram’s Values.LineWidth property.


cxGridChartLineDiagramDefaultMarkerSize constant
cxGridChartLineDiagramDefaultMarkerSize global constant

Specifies the default size (in pixels) of value markers in line and area diagrams.

Unit

cxGridChartView

cxGridChartLineDiagramDefaultMarkerSize = 7;

Description

This constant determines the default value of a line or area diagram’s Values.MarkerSize property.


TcxGridChartDiagram
TcxGridChartDiagram Object

Hierarchy          Properties          Methods          Events          See Also

Represents a generic diagram which can be displayed within a Chart View.

Unit

cxGridChartView

TcxGridChartDiagram = class(TPersistent)

Description

The TcxGridChartDiagram class is the base class for classes which represent chart diagrams within a Chart View.  Each chart diagram has two properties which control its general appearance within a Chart View, Active and Enabled.  The Legend property provides access to a chart legend and its options.

Use the Styles property to control specific appearance aspects of the diagram’s elements such as a chart legend, data markers and their captions.  Complete control over the appearance of these elements can be obtained by handling the OnCustomDraw… events such as OnCustomDrawLegend, OnCustomDrawLegendItem and OnCustomDrawValue.


TcxGridChartDiagram Hierarchy
Hierarchy

TPersistent

     |

TcxGridChartDiagram


Properties for TcxGridChartDiagram
TcxGridChartDiagram Properties

TcxGridChartDiagram          Legend

In TcxGridChartDiagram

Active

DisplayText

Enabled

GridView

ID

Legend

 	Styles


Methods for TcxGridChartDiagram
TcxGridChartDiagram Methods

TcxGridChartDiagram          Legend

In TcxGridChartDiagram

IsAvailable

GetValueCaption


Events for TcxGridChartDiagram
TcxGridChartDiagram Events

TcxGridChartDiagram          Legend

In TcxGridChartDiagram

OnCustomDrawLegend

OnCustomDrawLegendItem

OnCustomDrawValue


TcxGridChartDiagram.Active

TcxGridChartDiagram          See Also

Specifies whether the chart diagram is visible within a Chart View.

property Active: Boolean;

Description

Set the Active property to True to make a chart diagram active and visible within a Chart View.  Since only one chart diagram can be displayed at a time if any other chart diagram is active when this method is called it will be inactivated (its Active property is set to False) and the chart diagram for which this property is set will be activated and made visible within the View.

Note:	A chart diagram cannot be activated once it's been disabled (its Enabled property has been set to False).  The Active property’s value of the currently active chart diagram cannot be changed directly by setting this property to False.  One of the possible ways to hide the currently active chart diagram from the View is to activate another diagram.  The other way is to set the currently active diagram’s Enabled property to False.  As a result, one of the diagrams available for displaying (which is enabled) will be activated.  If all diagrams are disabled, nothing will be displayed within the View in this case.

To activate a specific diagram, set the View’s ActiveDiagram property.

Once the active diagram has been changed, the View’s OnActiveDiagramChanged event is fired.

The default value of the Active property is False.


TcxGridChartDiagram.DisplayText

TcxGridChartDiagram          See Also

Returns the text which describes the chart diagram.

property DisplayText: string;

Description

By default, this property returns the value of the ID property.  Various diagrams (descendants of the TcxGridChartDiagram class) return the descriptive text according to the diagram type they represent.  This text is used, for instance, to identify diagrams in the diagram selector.

The scxGridChartColumnDiagramDisplayText, scxGridChartBarDiagramDisplayText, scxGridChartLineDiagramDisplayText, scxGridChartAreaDiagramDisplayText and scxGridChartPieDiagramDisplayText resource strings provide the descriptive text for column, bar, line, area and pie diagrams, respectively.

ReadOnly Property


TcxGridChartDiagram.Enabled

TcxGridChartDiagram

Specifies whether the chart diagram can be displayed within a Chart View.

property Enabled: Boolean;

Description

Set the Enabled property to True to make a chart diagram available for displaying within a Chart View.  To make the chart diagram visible within the View, set its Active property to True.

Note:	A chart diagram cannot be activated once it's been disabled (its Enabled property is set to False).  The Active property’s value of the currently active chart diagram cannot be changed directly by setting this property to False.  One of the possible ways to hide the currently active chart diagram from the view is to activate another diagram.  The other way is to set the currently active diagram’s Enabled property to False.  As a result, one of the diagrams available for displaying (which is enabled) will be activated.  If all diagrams are disabled, nothing will be displayed within the View.

The default value of the Enabled property is True.


TcxGridChartDiagram.GridView

TcxGridChartDiagram

Provides access to the Chart View which displays the chart diagram.

property GridView: TcxGridChartView;

Description

Use the GridView property to access the Chart View which displays the chart diagram.  This property provides access to the View items, style sets, etc.

ReadOnly Property


TcxGridChartDiagram.ID

TcxGridChartDiagram          See Also

Returns the text which describes the chart diagram.

property ID: string;

Description

Use the ID property to get the descriptive text which is displayed for the chart diagram (for instance, in Object Inspector).  The text is determined from the classname of the diagram and usually identifies the type of the diagram.  Each diagram provides its own value for the ID property according to the diagram’s type.  For instance, this property returns ‘Bar Diagram’ for a bar diagram.

ReadOnly Property


TcxGridChartDiagram.Legend

TcxGridChartDiagram          See Also

Specifies a chart legend for a chart diagram.

property Legend: TcxGridChartLegend;

Description

Use the Legend property to access the chart legend’s appearance options. Chart legends provide information on what is displayed in the chart diagram via legend items.

Note:	When there isn’t any series (series values) displayed within a diagram (the Visible property of the series is set to False) the chart legend is hidden as it isn't required.


TcxGridChartDiagram.Styles

TcxGridChartDiagram          See Also

Provides access to a set of styles, which define the appearance of the chart diagram’s elements.

property Styles: TcxGridChartDiagramStyles;

Description

Use the Styles property to access a set of styles, which define the appearance of the chart diagram’s elements such as the chart legend and data markers.  This set is expanded when the Styles property is redefined by the TcxGridChartDiagram descendants.


TcxGridChartDiagram.GetValueCaption

TcxGridChartDiagram          See Also

Determines the caption of a chart value.

function GetValueCaption(ASeries: TcxGridChartSeries; AValueIndex: Integer): string; virtual;

Description

Descendants of the TcxGridChartDiagram class can display captions (data labels) as additional information to data markers.  A chart value whose caption is returned by this function is identified by:

•	a series (passed as the ASeries parameter);

•	the value’s position in the VisibleValues collection of this series (passed as the AValueIndex parameter).


TcxGridChartDiagram.IsAvailable

TcxGridChartDiagram          See Also

Determines whether the chart diagram can be displayed within a Chart View.

function IsAvailable: Boolean; virtual;

Description

Use the IsAvailable function to determine whether the chart diagram is available for displaying within a Chart View.  To make a chart diagram available for displaying within a Chart View, set the Enabled property to True.

By default, the IsAvailable function returns the Enabled property’s value.


TcxGridChartDiagram.OnCustomDrawLegend

TcxGridChartDiagram          See Also

Occurs when a chart legend needs to be painted.

type

  TcxGridChartDiagramLegendCustomDrawEvent = procedure(Sender: TcxGridChartDiagram; ACanvas: TcxCanvas; AViewInfo: TcxGridChartLegendViewInfo; var ADone: Boolean) of object;

property OnCustomDrawLegend: TcxGridChartDiagramLegendCustomDrawEvent;

Description

The OnCustomDrawLegend event occurs every time a chart legend’s area needs to be painted.  As with other custom draw events it provides a canvas for the grid control (the ACanvas parameter), ViewInfo (the AViewInfo parameter and its Bounds property) to get the bounding rectangle of the painted element (in this case the chart legend).  Sender is normally the element that caused the repaint.  The ADone parameter’s value is initially set to False.  Set it to True to prevent the grid from performing the default painting and painting over any custom painting.

Note:	The Chart View’s OnCustomDrawLegend event can override the diagram’s OnCustomDrawLegend event since the former is fired after the latter.

To learn more about custom drawing, please refer to the Custom Draw topic.


TcxGridChartDiagram.OnCustomDrawLegendItem

TcxGridChartDiagram          See Also

Occurs when a legend item needs to be painted.

type

  TcxGridChartDiagramLegendItemCustomDrawEvent = procedure(Sender: TcxGridChartDiagram; ACanvas: TcxCanvas; AViewInfo: TcxGridChartLegendItemViewInfo; var ADone: Boolean) of object;

property OnCustomDrawLegendItem: TcxGridChartDiagramLegendItemCustomDrawEvent;

Description

The OnCustomDrawLegendItem event occurs every time a legend item (a legend key and its description, i.e. the display text of the series that corresponds to the legend item) needs to be painted.  As with other custom draw events it provides a canvas for the grid control (the ACanvas parameter), ViewInfo (the AViewInfo parameter and its Bounds property) to get the bounding rectangle of the painted element (in this case the legend item).  Sender is usually the element that caused the repaint.  The ADone parameter’s value is initially False.  Set it to True to prevent the grid control from performing default drawing painting over the custom painting performed.

Note:	The Chart View’s OnCustomDrawLegendItem event can override the diagram’s OnCustomDrawLegendItem event since the former is fired after the latter.

To learn more about custom drawing, please refer to the Custom Draw topic.


TcxGridChartDiagram.OnCustomDrawValue

TcxGridChartDiagram

Occurs when a data marker needs to be painted.

type

  TcxGridChartDiagramValueCustomDrawEvent = procedure(Sender: TcxGridChartDiagram; ACanvas: TcxCanvas; AViewInfo: TcxGridChartDiagramValueViewInfo; var ADone: Boolean) of object;

property OnCustomDrawValue: TcxGridChartDiagramValueCustomDrawEvent;

Description

The OnCustomDrawValue event occurs every time a data marker (for instance, a bar for a bar diagram or a column for a column diagram) needs to be painted.  As with other custom draw events it provides a canvas for the grid control (the ACanvas parameter), ViewInfo (the AViewInfo parameter and its Bounds property) to get the bounding rectangle of the painted element (in this case the data marker).  Sender is usually the element that caused the repaint.  The ADone parameter’s value is initially False.  Set it to True to prevent the grid from performing the default painting and painting over any custom painting.  Note that the diagram’s OnCustomDrawValue event for a specific series is fired only when the OnCustomDrawValue event handler of this series has not finished drawing the data marker.

To learn more about custom drawing, please refer to the Custom Draw topic.


TcxGridChartHistogram
TcxGridChartHistogram Object

Hierarchy          Properties          Methods          Events          See Also

Represents the base class for all diagrams that provide axes for chart value measurement and comparison.

Unit

cxGridChartView

TcxGridChartHistogram = class(TcxGridChartDiagram)

Description

A list of derived diagram types includes the following: area bar, column, and line diagrams.

This class introduces members that allow you to control the following diagram attributes:

•	general appearance settings of the diagram’s axes (AxisCategory and AxisValue);

•	appearance settings of the diagram’s data markers, plot area, axes and their elements, gridlines, etc.  These appearance settings include the Values and Styles properties and OnCustomDrawPlot event.


TcxGridChartHistogram Hierarchy
Hierarchy

TPersistent

     |

TcxGridChartDiagram

     |


Properties for TcxGridChartHistogram
TcxGridChartHistogram Properties

TcxGridChartHistogram          Legend

In TcxGridChartHistogram

AxisCategory

AxisValue

Styles

Values

Derived from TcxGridChartDiagram

Active

DisplayText

Enabled

GridView

ID

Legend


Methods for TcxGridChartHistogram
TcxGridChartHistogram Methods

TcxGridChartHistogram          Legend

In TcxGridChartHistogram

GetCategoryAxisPosition

GetValueAxisPosition

Derived from TcxGridChartDiagram

GetValueCaption

IsAvailable


Events for TcxGridChartHistogram
TcxGridChartHistogram Events

TcxGridChartHistogram          Legend

In TcxGridChartHistogram

OnCustomDrawPlot

Derived from TcxGridChartDiagram

OnCustomDrawLegend

OnCustomDrawLegendItem

OnCustomDrawValue


TcxGridChartHistogram.AxisCategory

TcxGridChartHistogram          See Also

Specifies appearance settings for the diagram’s category axis.

property AxisCategory: TcxGridChartHistogramAxisCategory;

Description

Refer to the description of the TcxGridChartHistogramAxisCategory class to learn about appearance settings that can customized.


TcxGridChartHistogram.AxisValue

TcxGridChartHistogram          See Also

Specifies appearance settings for the diagram’s value axis.

property AxisValue: TcxGridChartHistogramAxisValue;

Description

Refer to the description of the TcxGridChartHistogramAxisValue class to learn about appearance settings that can customized.


TcxGridChartHistogram.Styles

TcxGridChartHistogram          See Also

Provides access to a set of styles which control the appearance of the diagram’s elements.

property Styles: TcxGridChartHistogramStyles;

Description

Refer to the description of the TcxGridChartHistogramStyles class to learn about styles available for customization.

Note:	You can custom paint a chart’s plot area by handling the OnCustomDrawPlot event.


TcxGridChartHistogram.Values

TcxGridChartHistogram

Specifies appearance settings for chart values in the diagram.

property Values: TcxGridChartHistogramValues;

Description

Refer to the description of the TcxGridChartHistogramValues class to learn about appearance settings that can customized.


TcxGridChartHistogram.GetCategoryAxisPosition

TcxGridChartHistogram          See Also

Returns the position of a category axis within the diagram.

type

  TcxGridChartAxisPosition = (cppLeft, cppTop, cppRight, cppBottom);

function GetCategoryAxisPosition: TcxGridChartAxisPosition; virtual;

Description

By default, this function returns cppBottom.  Refer to the description of TcxGridChartAxisPosition to learn about available options for axes.

Note:	TcxGridChartHistogram descendants override the GetCategoryAxisPosition function to provide return values specific to the diagram type they represent.


TcxGridChartHistogram.GetValueAxisPosition

TcxGridChartHistogram          See Also

Returns the position of a value axis within the diagram.

type

  TcxGridChartAxisPosition = (cppLeft, cppTop, cppRight, cppBottom);

function GetValueAxisPosition: TcxGridChartAxisPosition; virtual;

Description

Refer to the description of TcxGridChartAxisPosition to learn about available options for axes.

Use the AxisCategory.ValueAxisAtMaxCategory and AxisCategory.CategoriesInReverseOrder properties to modify the default position of a value axis.

Note:	TcxGridChartHistogram descendants override the GetValueAxisPosition function to provide return values specific to the diagram type they represent.


TcxGridChartHistogram.OnCustomDrawPlot

TcxGridChartHistogram

Occurs when a chart’s plot area needs to be painted.

type

  TcxGridChartHistogramPlotCustomDrawEvent = procedure(Sender: TcxGridChartHistogram; ACanvas: TcxCanvas; AViewInfo: TcxGridChartHistogramViewInfo; const ABounds: TRect; var ADone: Boolean) of object;

property OnCustomDrawPlot: TcxGridChartHistogramPlotCustomDrawEvent;

Description

The Sender parameter provides access to the diagram that caused a chart’s plot area to be repainted.

The ACanvas and AViewInfo parameters provide access to the canvas and ViewInfo of the grid control.

The ABounds parameter specifies the bounding rectangle of a chart’s plot area being painted.  Note that the same information is accessible via the AViewInfo.PlotBounds property.

As with other custom drawing events, the ADone parameter’s value is initially False.  Set it to True to prevent the grid control from performing default painting.

To learn more about custom draw, refer to the Custom Draw topic.


TcxGridChartBarDiagram
TcxGridChartBarDiagram Object

Hierarchy          Properties          Methods          Events          See Also

Represents a bar diagram.

Unit

cxGridChartView

TcxGridChartBarDiagram = class(TcxGridChartColumnDiagram)

Description

The TcxGridChartBarDiagram class does not extend its ancestor class with new properties and events; it simply designates the default positions (specific to bar diagrams) of the category axis (which is on the left side of a chart’s plot area) and the value axis (see the GetCategoryAxisPosition and GetValueAxisPosition functions, respectively).


TcxGridChartBarDiagram Hierarchy
Hierarchy

TPersistent

     |

TcxGridChartDiagram

     |

TcxGridChartHistogram

     |

TcxGridChartColumnDiagram

     |


Properties for TcxGridChartBarDiagram
TcxGridChartBarDiagram Properties

TcxGridChartBarDiagram          Legend

Derived from TcxGridChartColumnDiagram

Values

Derived from TcxGridChartHistogram

AxisCategory

AxisValue

Styles

Values

Derived from TcxGridChartDiagram

Active

DisplayText

Enabled

GridView

ID

Legend


Methods for TcxGridChartBarDiagram
TcxGridChartBarDiagram Methods

TcxGridChartBarDiagram          Legend

In TcxGridChartBarDiagram

GetCategoryAxisPosition

GetValueAxisPosition

Derived from TcxGridChartHistogram

GetCategoryAxisPosition

GetValueAxisPosition

Derived from TcxGridChartDiagram

GetValueCaption

IsAvailable


Events for TcxGridChartBarDiagram
TcxGridChartBarDiagram Events

TcxGridChartBarDiagram          Legend

Derived from TcxGridChartHistogram

OnCustomDrawPlot

Derived from TcxGridChartDiagram

OnCustomDrawLegend

OnCustomDrawLegendItem

OnCustomDrawValue


TcxGridChartBarDiagram.GetCategoryAxisPosition

TcxGridChartBarDiagram          See Also

Determines the position of a category axis within a bar diagram.

type

  TcxGridChartAxisPosition = (cppLeft, cppTop, cppRight, cppBottom);

function GetCategoryAxisPosition: TcxGridChartAxisPosition; override;

Description

Call the GetCategoryAxisPosition function to determine the position of a category axis within a bar diagram.  The default return value of this function is cppLeft which indicates that the category axis is displayed vertically on the left side of a chart’s plot area.


TcxGridChartBarDiagram.GetValueAxisPosition

TcxGridChartBarDiagram          See Also

Determines the position of a value axis within a bar diagram.

type

  TcxGridChartAxisPosition = (cppLeft, cppTop, cppRight, cppBottom);

function GetValueAxisPosition: TcxGridChartAxisPosition; override;

Description

Call the GetValueAxisPosition function to determine the position of a value axis within a bar diagram.  By default, the value axis is displayed horizontally on the top (cppTop value) or on the bottom (cppBottom value) side of a chart’s plot area.  The actual position depends upon the values of the axis category’s ValueAxisAtMaxCategory and CategoriesInReverseOrder properties and is equal to cppBottom when the values of these properties are equal.  Otherwise, the return value is cppTop.


TcxGridChartColumnDiagram
TcxGridChartColumnDiagram Object

Hierarchy          Properties          Methods          Events          See Also

Represents a column diagram.

Unit

cxGridChartView

TcxGridChartColumnDiagram = class(TcxGridChartHistogram)

Description

The TcxGridChartColumnDiagram class extends its ancestor class with appearance options for series values specific to column and bar diagrams (which are accessible via the Values property).


TcxGridChartColumnDiagram Hierarchy
Hierarchy

TPersistent

     |

TcxGridChartDiagram

     |

TcxGridChartHistogram

     |


Properties for TcxGridChartColumnDiagram
TcxGridChartColumnDiagram Properties

TcxGridChartColumnDiagram          Legend

In TcxGridChartColumnDiagram

Values

Derived from TcxGridChartHistogram

AxisCategory

AxisValue

Styles

Values

Derived from TcxGridChartDiagram

Active

DisplayText

Enabled

GridView

ID

Legend


Methods for TcxGridChartColumnDiagram
TcxGridChartColumnDiagram Methods

TcxGridChartColumnDiagram          Legend

Derived from TcxGridChartHistogram

GetCategoryAxisPosition

GetValueAxisPosition

Derived from TcxGridChartDiagram

GetValueCaption

IsAvailable


Events for TcxGridChartColumnDiagram
TcxGridChartColumnDiagram Events

TcxGridChartColumnDiagram          Legend

Derived from TcxGridChartHistogram

OnCustomDrawPlot

Derived from TcxGridChartDiagram

OnCustomDrawLegend

OnCustomDrawLegendItem

OnCustomDrawValue


TcxGridChartColumnDiagram.Values

TcxGridChartColumnDiagram

Specifies options for series values (their data markers) in a column diagram.

property Values: TcxGridChartColumnDiagramValues;

Description

Use the Values property to set the options which control the appearance aspects of series values such as the border width of the data markers (columns for a column diagram) and the captions of series values.


TcxGridChartLineDiagram
TcxGridChartLineDiagram Object

Hierarchy          Properties          Methods          Events          See Also

Represents a line diagram.

Unit

cxGridChartView

TcxGridChartLineDiagram = class(TcxGridChartHistogram)

Description

The TcxGridChartLineDiagram class extends its ancestor class with:

•	appearance options for the line diagram’s category axis and chart values (AxisCategory and Values, respectively);

•	additional styles specific to line diagram elements (Styles).

Note:	To plot a stacked line diagram, use the diagram’s Values.Stacking property to specify its stacking type.


TcxGridChartLineDiagram Hierarchy
Hierarchy

TPersistent

     |

TcxGridChartDiagram

     |

TcxGridChartHistogram

     |


Properties for TcxGridChartLineDiagram
TcxGridChartLineDiagram Properties

TcxGridChartLineDiagram          Legend

In TcxGridChartLineDiagram

AxisCategory

Styles

Values

Derived from TcxGridChartHistogram

AxisCategory

AxisValue

Styles

Values

Derived from TcxGridChartDiagram

Active

DisplayText

Enabled

GridView

ID

Legend


Methods for TcxGridChartLineDiagram
TcxGridChartLineDiagram Methods

TcxGridChartLineDiagram          Legend

Derived from TcxGridChartHistogram

GetCategoryAxisPosition

GetValueAxisPosition

Derived from TcxGridChartDiagram

GetValueCaption

IsAvailable


Events for TcxGridChartLineDiagram
TcxGridChartLineDiagram Events

TcxGridChartLineDiagram          Legend

Derived from TcxGridChartHistogram

OnCustomDrawPlot

Derived from TcxGridChartDiagram

OnCustomDrawLegend

OnCustomDrawLegendItem

OnCustomDrawValue


TcxGridChartLineDiagram.AxisCategory

TcxGridChartLineDiagram          See Also

Specifies appearance settings for the category axis.

property AxisCategory: TcxGridChartLineDiagramAxisCategory;

Description

Refer to the description of the TcxGridChartLineDiagramAxisCategory class to learn about appearance settings that can be customized.


TcxGridChartLineDiagram.Styles

TcxGridChartLineDiagram          See Also

Provides access to a set of styles which control the appearance of the line diagram’s elements.

property Styles: TcxGridChartLineDiagramStyles;

Description

Refer to the description of the TcxGridChartLineDiagramStyles class to learn about styles available for customization.


TcxGridChartLineDiagram.Values

TcxGridChartLineDiagram

Specifies appearance settings for chart values in the line diagram.

property Values: TcxGridChartLineDiagramValues;

Description

Refer to the description of the TcxGridChartLineDiagramValues class to learn about appearance settings that can be customized.


TcxGridChartAreaDiagram
TcxGridChartAreaDiagram Object

Hierarchy          Properties          Methods          Events          See Also

Represents an area diagram.

Unit

cxGridChartView

TcxGridChartAreaDiagram = class(TcxGridChartLineDiagram)

Description

The TcxGridChartAreaDiagram class introduces members that allow you to control the following area diagram attributes:

•	additional styles specific to area diagram elements (Styles);

•	appearance settings of the diagram’s value area (OnCustomDrawValueArea).

Note:	To plot a stacked area diagram, use the diagram’s Values.Stacking property to specify its stacking type.


TcxGridChartAreaDiagram Hierarchy
Hierarchy

TPersistent

     |

TcxGridChartDiagram

     |

TcxGridChartHistogram

     |

TcxGridChartLineDiagram

     |


Properties for TcxGridChartAreaDiagram
TcxGridChartAreaDiagram Properties

TcxGridChartAreaDiagram          Legend

In TcxGridChartAreaDiagram

Styles

Derived from TcxGridChartLineDiagram

AxisCategory

Styles

Values

Derived from TcxGridChartHistogram

AxisCategory

AxisValue

Styles

Values

Derived from TcxGridChartDiagram

Active

DisplayText

Enabled

GridView

ID

Legend


Methods for TcxGridChartAreaDiagram
TcxGridChartAreaDiagram Methods

TcxGridChartAreaDiagram          Legend

Derived from TcxGridChartHistogram

GetCategoryAxisPosition

GetValueAxisPosition

Derived from TcxGridChartDiagram

GetValueCaption

IsAvailable


Events for TcxGridChartAreaDiagram
TcxGridChartAreaDiagram Events

TcxGridChartAreaDiagram          Legend

In TcxGridChartAreaDiagram

OnCustomDrawValueArea

Derived from TcxGridChartHistogram

OnCustomDrawPlot

Derived from TcxGridChartDiagram

OnCustomDrawLegend

OnCustomDrawLegendItem

OnCustomDrawValue


TcxGridChartAreaDiagram.Styles

TcxGridChartAreaDiagram          See Also

Provides access to a set of styles which control the appearance of the area diagram’s elements.

property Styles: TcxGridChartAreaDiagramStyles;

Description

Refer to the description of the TcxGridChartAreaDiagramStyles class to learn about styles available for customization.


TcxGridChartAreaDiagram.OnCustomDrawValueArea

TcxGridChartAreaDiagram

Occurs when a value area for a data marker needs to be painted.

type

  TcxGridChartAreaDiagramValueAreaCustomDrawEvent = procedure(Sender: TcxGridChartAreaDiagram; ACanvas: TcxCanvas; AViewInfo: TcxGridChartAreaDiagramValueViewInfo; var ADone: Boolean) of object;

property OnCustomDrawValueArea: TcxGridChartAreaDiagramValueAreaCustomDrawEvent;

Description

In area diagrams, data markers are painted in two passes.  An area diagram’s value area is drawn first, and then value markers and lines that connect adjacent value points are painted.  You can handle the OnCustomDrawValueArea event to custom paint a value area for each data marker.  To custom paint value markers and lines connecting adjacent value points after the first pass, handle the diagram's OnCustomDrawValue or the corresponding series.

The Sender parameter provides access to the area diagram that caused a value area to be repainted;

The ACanvas and AViewInfo parameters provide access to the canvas and ViewInfo of the grid control.  The bounding rectangle of the value area being painted can be obtained via the AViewInfo.Bounds property;

As with other custom drawing events, the ADone parameter’s value is initially False.

To learn more about custom drawing, please refer to the Custom Draw topic.


TcxGridChartPieDiagram
TcxGridChartPieDiagram Object

Hierarchy          Properties          Methods          Events          See Also

Represents a pie diagram.

Unit

cxGridChartView

TcxGridChartPieDiagram = class(TcxGridChartDiagram)

Description

The TcxGridChartPieDiagram class extends its ancestor class with options which control the following pie diagram attributes:

•	appearance settings of series sites and their captions (SeriesSites, SeriesCaptions, OnCustomDrawSeriesSite, and OnCustomDrawSeriesSiteCaption);

•	the number of columns in which series sites are arranged horizontally (SeriesColumnCount);

•	appearance options of chart values (Values);

•	additional styles specific to pie diagram elements (Styles).


TcxGridChartPieDiagram Hierarchy
Hierarchy

TPersistent

     |

TcxGridChartDiagram

     |


Properties for TcxGridChartPieDiagram
TcxGridChartPieDiagram Properties

TcxGridChartPieDiagram          Legend

In TcxGridChartPieDiagram

SeriesCaptions

SeriesColumnCount

SeriesSites

Styles

Values

Derived from TcxGridChartDiagram

Active

DisplayText

Enabled

GridView

ID

Legend


Methods for TcxGridChartPieDiagram
TcxGridChartPieDiagram Methods

TcxGridChartPieDiagram          Legend

In TcxGridChartPieDiagram

GetSeriesColumnCount

GetValueCaption

Derived from TcxGridChartDiagram

GetValueCaption

IsAvailable


Events for TcxGridChartPieDiagram
TcxGridChartPieDiagram Events

TcxGridChartPieDiagram          Legend

In TcxGridChartPieDiagram

OnCustomDrawSeriesSite

OnCustomDrawSeriesSiteCaption

Derived from TcxGridChartDiagram

OnCustomDrawLegend

OnCustomDrawLegendItem

OnCustomDrawValue


TcxGridChartPieDiagram.SeriesCaptions

TcxGridChartPieDiagram

Specifies whether series site captions are visible.

property SeriesCaptions: Boolean;

Description

Series site captions identify series.  To display series site captions, set the SeriesCaptions property to True.  Otherwise, series site captions are hidden.  In this instance, the OnCustomDrawSeriesSiteCaption event is not raised.

You can specify the caption text via the DisplayText property of the corresponding series.

Note:	Use the SeriesSite property to control the general appearance of series sites within the pie diagram.

The default value of the SeriesCaptions property is True.


TcxGridChartPieDiagram.SeriesColumnCount

TcxGridChartPieDiagram          See Also

Specifies the maximum number of columns into which series sites are arranged horizontally.

property SeriesColumnCount: Integer;

Description

The property’s value of 0 indicates that all series sites are painted horizontally in a single row.  Otherwise, series sites are divided visually into the specified number of columns.

Call the GetSeriesColumnCount function to determine the actual number of columns in which series sites are arranged horizontally within the pie diagram.

The default value of the SeriesColumnCount property is 0.


TcxGridChartPieDiagram.SeriesSites

TcxGridChartPieDiagram          See Also

Specifies whether series sites are visible.

property SeriesSites: Boolean;

Description

Set this property to True to display the series site for each pie.  Otherwise, series sites are hidden.  In this instance, the OnCustomDrawSeriesSite event is not raised.

Note:	Use the SeriesCaptions property to control the general appearance of series site captions within the pie diagram.

The default value of the SeriesSites property is False.


TcxGridChartPieDiagram.Styles

TcxGridChartPieDiagram          See Also

Provides access to a set of styles which control the appearance of the pie diagram’s elements.

property Styles: TcxGridChartPieDiagramStyles;

Description

Refer to the description of the TcxGridChartPieDiagramStyles class to learn about styles available for customization.

Note:	You can custom paint series sites and their captions by handling the OnCustomDrawSeriesSite and OnCustomDrawSeriesSiteCaption events, respectively.


TcxGridChartPieDiagram.Values

TcxGridChartPieDiagram

Specifies appearance settings for chart values.

property Values: TcxGridChartPieDiagramValues;

Description

Refer to the description of the TcxGridChartPieDiagramValues class to learn about appearance settings that can be customized.


TcxGridChartPieDiagram.GetSeriesColumnCount

TcxGridChartPieDiagram

Determines the actual number of columns into which series sites are arranged horizontally.

function GetSeriesColumnCount: Integer; virtual;

Description

The return value of this function does not exceed the number of series which are currently visible within the diagram.

To specify the maximum number of columns into which series sites should be arranged horizontally, use the SeriesColumnCount property.


TcxGridChartPieDiagram.GetValueCaption

TcxGridChartPieDiagram          See Also

Determines the caption of a particular chart value.

function GetValueCaption(ASeries: TcxGridChartSeries; AValueIndex: Integer): string; override;

Description

In a pie diagram, you can specify how captions (data labels) of chart values are made up via the diagram’s Values.CaptionItems property.

A chart value whose caption is returned by this function is identified by:

•	a series (passed as the ASeries parameter);

•	the value’s position in the VisibleValues collection of this series (passed as the AValueIndex parameter).


TcxGridChartPieDiagram.OnCustomDrawSeriesSite

TcxGridChartPieDiagram          See Also

Occurs when a series site’s area needs to be painted.

type

  TcxGridChartPieDiagramSeriesSiteCustomDrawEvent = procedure(Sender: TcxGridChartPieDiagram; ACanvas: TcxCanvas; AViewInfo: TcxGridChartPieSeriesSiteViewInfo; var ADone: Boolean) of object;

property OnCustomDrawSeriesSite: TcxGridChartPieDiagramSeriesSiteCustomDrawEvent;

Description

The Sender parameter provides access to the pie diagram that caused a series site’s area to be repainted.

The ACanvas and AViewInfo parameters provide access to the canvas and ViewInfo of the grid control.  The bounding rectangle of the series site’s area being painted can be obtained via the AViewInfo.Bounds property.  The series whose site is being painted can be accessed via the AViewInfo.Series property.

As with other custom drawing events, the ADone parameter’s value is initially False.

To learn more about custom draw, refer to the Custom Draw topic.


TcxGridChartPieDiagram.OnCustomDrawSeriesSiteCaption

TcxGridChartPieDiagram          See Also

Occurs when a series site’s caption needs to be painted.

type

  TcxGridChartPieDiagramSeriesSiteCaptionCustomDrawEvent = procedure(Sender: TcxGridChartPieDiagram; ACanvas: TcxCanvas; AViewInfo: TcxGridChartPieSeriesSiteCaptionViewInfo; var ADone: Boolean) of object;

property OnCustomDrawSeriesSiteCaption: TcxGridChartPieDiagramSeriesSiteCaptionCustomDrawEvent;

Description

The Sender parameter provides access to the pie diagram that caused the series site’s caption to be repainted.

The ACanvas and AViewInfo parameters provide access to the canvas and ViewInfo of the grid control.  The bounding rectangle of the series site’s caption being painted can be obtained via the AViewInfo.Bounds property.  The series whose site is being painted can be accessed via the AViewInfo.Series property.

As with other custom drawing events, the ADone parameter’s value is initially False.

To learn more about custom draw, refer to the Custom Draw topic.


TcxGridChartDiagramSelectorPopup
TcxGridChartDiagramSelectorPopup Object

Hierarchy          Properties          See Also

Represents a diagram selector’s dropdown list.

Unit

cxGridChartView

TcxGridChartDiagramSelectorPopup = class(TcxCustomGridPopup)

Description

A diagram selector represents one of the customization tools displayed in a chart toolbox.  Users can click a diagram selector to choose the diagram type from its dropdown list.  This list contains all the available diagrams in a Chart View.

Use the View’s ToolBox.DiagramSelector property to control the general appearance of the diagram selector in the chart toolbox.


TcxGridChartDiagramSelectorPopup Hierarchy
Hierarchy

TForm

     |

TcxPopupWindow

     |

TcxCustomPopupWindow

     |

TcxCustomGridPopup

     |

TcxGridChartDiagramSelectorPopup


Properties for TcxGridChartDiagramSelectorPopup
TcxGridChartDiagramSelectorPopup Properties

TcxGridChartDiagramSelectorPopup          Legend

In TcxGridChartDiagramSelectorPopup

GridView

ImageOffset


TcxGridChartDiagramSelectorPopup.GridView

TcxGridChartDiagramSelectorPopup

Provides access to the Chart View which displays the diagram selector.

property GridView: TcxGridChartView;

ReadOnly Property


TcxGridChartDiagramSelectorPopup.ImageOffset

TcxGridChartDiagramSelectorPopup

Returns the offset (in pixels) of images in the diagram selector’s dropdown list relative to its left edge.

property ImageOffset: Integer;

Description

List items display diagram type captions and corresponding images.  You can adjust the position of item images via the ImageOffset property.

TcxGridChartDiagramSelectorPopup descendants can override the GetImageOffset function that represents the setter of the ImageOffset property so as to provide custom values for this property.

ReadOnly Property


TcxGridChartItem
TcxGridChartItem Object

Hierarchy          Properties          Methods          Events          See Also

Represents a chart item (a series or data group) in Chart Views.

Unit

cxGridChartView

TcxGridChartItem = class(TcxComponent, IcxGridChartItem, IcxStoredObject)

Description

The TcxGridChartItem class represents the base class for chart items.  This class provides the following capabilities:

•	Appearance Control.

•	The general appearance of a chart item in a chart (Visible);

•	The display order of chart items (Index and SortOrder);

•	The descriptive text for a chart item (DisplayText and OnGetValueDisplayText).

•	Identity.

Address a chart item by its ID and visual position (ID and VisibleIndex).

•	Data Binding.

A chart item retrieves data from a data store with the help of the DataBinding object which provides properties used to define the data type of item values, associate an arbitrary value (via the DataBinding.Data property) with the item and perform other operations.

•	Persistence Control.

You can customize the list of a chart item properties and their values that can be stored/restored to/from an external data store such as a file, registry or stream as a part of the Chart View (OnGetStoredProperties, OnGetStoredPropertyValue and OnSetStoredPropertyValue);

To access a chart item’s properties at design time, select the item via the Component Editor or click it within a chart.


TcxGridChartItem Hierarchy
Hierarchy

TComponent

     |

TcxComponent

     |

TcxGridChartItem


Properties for TcxGridChartItem
TcxGridChartItem Properties

TcxGridChartItem          Legend

In TcxGridChartItem

DataBinding

DisplayText

GridView

ID

Index

Order

SortOrder

ValueCount

Values

Visible

VisibleDisplayTexts

VisibleForCustomization

VisibleIndex

VisibleValueCount

VisibleValues


Methods for TcxGridChartItem
TcxGridChartItem Methods

TcxGridChartItem          Legend

In TcxGridChartItem

GetDisplayText

GetValueDisplayText

IsValue


Events for TcxGridChartItem
TcxGridChartItem Events

TcxGridChartItem          Legend

In TcxGridChartItem

OnGetStoredProperties

OnGetStoredPropertyValue

OnGetValueDisplayText

OnSetStoredPropertyValue


TcxGridChartItem.DataBinding

TcxGridChartItem

Specifies an object, which links the chart item to a data store.

property DataBinding: TcxGridChartItemDataBinding;

Description

You can use the properties of the specified DataBinding object to:

•	define the data type of item values;

•	associate an arbitrary value with the chart item via the DataBinding.Data property;

•	etc.

At design time, you can select a data type for a chart item from its DataBinding.ValueType property, which provides a list of the available data types.


TcxGridChartItem.DisplayText

TcxGridChartItem

Specifies the descriptive text for the chart item.

property DisplayText: string;

Description

To specify the descriptive text for categories, use the View’s Categories.DisplayText property.

Use the GetDisplayText function to determine the descriptive text displayed for the chart item.

For series, the descriptive text will appear in:

•	a chart legend;

•	value hints.

For categories and data groups, the descriptive text will appear in:

•	the category axis title provided that the diagram’s AxisCategory.Title.Text property is assigned to an empty string;

•	a chart toolbox.


TcxGridChartItem.GridView

TcxGridChartItem

Provides access to the Chart View, which displays the chart item.

property GridView: TcxGridChartView;

ReadOnly Property


TcxGridChartItem.ID

TcxGridChartItem          See Also

Specifies the unique identifier assigned to the chart item.

property ID: Integer;

Description

All items in a View (categories, series and data groups in a Chart View) can be distinguished by their unique IDs.  When an item is deleted, a newly created item might get the ID of the deleted item.  Thus item IDs won't be reused within the current state of the View, but may be reused within the lifetime of the View.  This is a limitation of these IDs.

To locate series and data groups by their IDs, use the Chart View’s FindSeriesByID and FindDataGroupByID functions, respectively.

ReadOnly Property


TcxGridChartItem.Index

TcxGridChartItem

Specifies the position of the chart item (a series or data group) within the Series and DataGroups collections.

property Index: Integer;

Description

To obtain a count of elements in these collections, use the View’s SeriesCount and DataGroupCount properties, respectively.

To access chart items whose values are used to render a chart, use the View’s VisibleSeries and VisibleDataGroups collections.  The position of a chart item in these collections is determined by the VisibleIndex property.


TcxGridChartItem.Order

TcxGridChartItem          See Also

Determines the position of the chart item in a list of chart items sorted by their IDs.

property Order: Integer;

Description

This property is for internal use only.

This property is used to distinguish chart items based upon their IDs.  For instance, the values of this property determine the default color for data markers.

ReadOnly Property


TcxGridChartItem.SortOrder

TcxGridChartItem

Specifies the order in which to display chart item values.

type

  TcxDataSortOrder = (soNone, soAscending, soDescending);

property SortOrder: TcxDataSortOrder;

Description

By default, chart item values are displayed in the order in which they are stored in the VisibleValues property.  You can set the SortOrder property to modify the default plotting order.

The series whose values are sorted can be accessed via the View’s SortedSeries property.  End-users are able to customize sorting applied to series using the Customization Form.

You can also use the SortOrder property of the default categories and data groups to apply sorting by their values.

Note:	Sorting applied to series takes priority over sorting by default categories or a data group.  Only a single type of sorting (either by default categories/a data group or series values) is active at one time within a chart.  To reverse the applied plotting order, set a diagram’s AxisCategory.CategoriesInReverseOrder property to True.

The default value of the SortOrder property is soNone.


TcxGridChartItem.ValueCount

TcxGridChartItem          See Also

Specifies how many records in the View’s data controller are available to render a chart.

property ValueCount: Integer;

Description

If a new value set to this property is less than the old value, only the first ValueCount records (based upon the order of records in the View’s data controller) are left within the data controller.

Note:	If the new value for this property is greater than the current value then the corresponding number of empty records is added to the data controller’s data store.  This is valid only in provider and unbound modes.

Use the Values property to access an individual item value.


TcxGridChartItem.Values

TcxGridChartItem          See Also

Provides indexed access to a collection of item values available to render a chart.

property Values[AIndex: Integer]: Variant;

Description

Items in this collection are stored based upon the order of records in the View’s data controller.

Note:	The following properties have no effect on this order:

•	the View’s Categories.SortOrder and a diagram’s AxisCategory.CategoriesInReverseOrder properties;

•	the SortOrder property of series and data group.

Use the ValueCount property to determine the total number of values in the Values collection.


TcxGridChartItem.Visible

TcxGridChartItem

Specifies whether the chart item is displayed in a chart.

property Visible: Boolean;

Description

Set this property to True to display the chart item in a chart.  Otherwise, the item will be hidden.

End-users are able to customize the general appearance of chart items via the customization form.

You can access an individual series and data group displayed in a chart via the View’s VisibleSeries and VisibleDataGroups zero-based indexed collections, respectively.

The position of a chart item in these collections is determined by its VisibleIndex property.

The default value of the Visible property is True.


TcxGridChartItem.VisibleDisplayTexts

TcxGridChartItem

Returns the display text for a particular item value from the VisibleValues collection.

property VisibleDisplayTexts[AIndex: Integer]: string;

Description

By default, the display text is determined using the GetValueDisplayText function.

You can handle the chart item’s OnGetValueDisplayText event to customize the display text for each item value displayed in a chart.

ReadOnly Property


TcxGridChartItem.VisibleForCustomization

TcxGridChartItem

Specifies whether the chart item is displayed within the customization form.

property VisibleForCustomization: Boolean;

Description

A hidden chart item appears in the customization form provided that the item’s VisibleForCustomization property is set to True.  Otherwise, end-users will be unable to place the chart item back to the View since it’s hidden in the customization form.To display the customization form, set the View’s Controller.Customization property to True.

The default value of the VisibleForCustomization property is True.


TcxGridChartItem.VisibleIndex

TcxGridChartItem

Determines the position of the chart item (a series or data group) within the VisibleSeries or VisibleDataGroups collection.

property VisibleIndex: Integer;

Description

For hidden chart items, the VisibleIndex property returns –1.

Use the View’s VisibleSeriesCount and VisibleDataGroupCount properties to obtain the total number of elements in these collections.

To access all series and data groups contained within a Chart View, use the View’s Series and DataGroups collections, respectively.  The position of a chart item in these collections is specified by the item’s Index property.

ReadOnly Property


TcxGridChartItem.VisibleValueCount

TcxGridChartItem

Gets a count of elements in the VisibleValues collection.

property VisibleValueCount: Integer;

ReadOnly Property


TcxGridChartItem.VisibleValues

TcxGridChartItem          See Also

Provides indexed access to the collection of item values that are used to render a chart.

property VisibleValues[AIndex: Integer]: Variant;

Description

To access a particular item value within this collection, use the chart item’s on-screen position as an index.

Note that the order of elements in this collection is determined by:

•	the View’s Categories.SortOrder property;

•	the SortOrder property of series or data group.

Use the VisibleValueCount property to determine the total number of elements within the VisibleValues collection.

To access the display text for a particular item value from the VisibleValues collection, use the VisibleDisplayTexts property.

Note:	A diagram’s AxisCategory.CategoriesInReverseOrder property has no effect on the order of elements within the VisibleValues and VisibleDisplayTexts collections.

ReadOnly Property


TcxGridChartItem.GetDisplayText

TcxGridChartItem          See Also

Determines the descriptive text displayed for the chart item.

function GetDisplayText: string;

Description

To specify this text, use the DisplayText property.

For series, the descriptive text will appear in:

•	a chart legend;

•	value hints.

For data groups, the descriptive text will appear in:

•	a category axis title (provided that a diagram’s AxisCategory.Title.Text property is assigned to an empty string);

•	a chart toolbox.

Note:	To determine the descriptive text displayed for the default categories, call the View’s Categories.GetDisplayText function.


TcxGridChartItem.GetValueDisplayText

TcxGridChartItem          See Also

Determines the display text for AValue that is used to render a chart.

function GetValueDisplayText(const AValue: Variant): string;

Description

The text returned by this function will appear in:

•	value hints;

•	data labels on chart values;

•	tick-mark labels.

For chart values, the display text is formatted as specified by the ValueCaptionFormat property of a series.

Use the VisibleDisplayTexts zero-based indexed collection to get a string representation of a particular item value by its index.

You can handle the item’s OnGetValueDisplayText event to customize a string representation of item values.


TcxGridChartItem.IsValue

TcxGridChartItem          See Also

Determines whether the chart item provides values for calculating group summaries.

class function IsValue: Boolean; virtual;

Description

This function is for internal use only.

By default, this function returns True which indicates that chart item values are used to calculate group summaries when these values are grouped by any category associated with data groups.

TcxGridChartItem descendants override this function to return relevant values specific to the items they correspond to.


TcxGridChartItem.OnGetStoredProperties

TcxGridChartItem          See Also          Example

Enables you to customize the list of chart item properties that will be stored if an external store is produced.

type

  TcxGridChartItemGetStoredPropertiesEvent = procedure(Sender: TcxGridChartItem; AProperties: TStrings) of object;

property OnGetStoredProperties: TcxGridChartItemGetStoredPropertiesEvent;

Description

Handle this event to customize the list of chart item properties that will be stored in an external store like a file, registry or stream as a part of the owner View.  Whenever storing is initiated, a list of properties is produced.  When the OnGetStoredProperties event is fired, the list already contains the names of chart item properties stored by default.  The set of properties in the list depends upon chart item type (whether it is a series, category or data group).

The Sender parameter specifies the chart item whose properties will be stored.

The AProperties parameter specifies the list of properties to be stored.

For more information, see the example on how to handle the OnGetStoredProperties event for tabular Views.


TcxGridChartItem.OnGetStoredPropertyValue

TcxGridChartItem          See Also          Example

Enables you to specify chart item property values to be stored in an external store.

type

  TcxGridChartItemGetStoredPropertyValueEvent = procedure(Sender: TcxGridChartItem; const AName: string; var AValue: Variant) of object;

property OnGetStoredPropertyValue: TcxGridChartItemGetStoredPropertyValueEvent;

Description

Having customized the list of properties to be stored to an external store on the OnGetStoredProperties event, handle the OnGetStoredPropertyValue event to specify their values.  These values will be saved in the resulting output.

The Sender parameter specifies the chart item whose properties will be stored.

The AName parameter denotes the name of the chart item’s property in the resulting output.

In order to store a specific value for the AName property, assign the value to the AValue parameter.

For more information, see the example on how to handle the OnGetStoredProperties event for tabular Views.


TcxGridChartItem.OnGetValueDisplayText

TcxGridChartItem          See Also

Enables you to customize the display text for a value of the chart item.

type

  TcxGridChartGetValueDisplayTextEvent = procedure(Sender: TObject; const AValue: Variant; var ADisplayText: string) of object;

property OnGetValueDisplayText: TcxGridChartGetValueDisplayTextEvent;

Description

The text returned by handling this event will appear in:

•	value hints;

•	data labels on chart values;

•	tick-mark labels.

The chart item and its value are passed as the Sender and AValue parameters, respectively.

Return the value’s display text via the ADisplayText parameter, which is pre-initialized by the default string for this value.  Note that for chart values, this string is formatted as specified by the ValueCaptionFormat property of a series.

Use the VisibleDisplayTexts zero-based indexed collection to get a string representation of a particular chart value by its index.


TcxGridChartItem.OnSetStoredPropertyValue

TcxGridChartItem

Enables you to restore chart item property values from an external store.

type

  TcxGridChartItemSetStoredPropertyValueEvent = procedure(Sender: TcxGridChartItem; const AName: string; const AValue: Variant) of object;

property OnSetStoredPropertyValue: TcxGridChartItemSetStoredPropertyValueEvent;

Description

Handle the OnSetStoredPropertyValue event to restore chart item property values that are not stored by default and whose names and values were explicitly specified on the OnGetStoredProperties and OnGetStoredPropertyValue events.  These values will be restored from an external store.

The Sender parameter specifies the chart item whose properties are being restored.

The AName parameter denotes the name of the chart item’s property whose value is being restored from an external store.  This value is returned by the AValue parameter.

For more information, see the example on how to handle the OnGetStoredProperties event for tabular Views.


TcxGridChartDataGroup
TcxGridChartDataGroup Object

Hierarchy          Properties          Methods          Events          See Also

Represents a data group in Chart Views.

Unit

cxGridChartView

TcxGridChartDataGroup = class(TcxGridChartItem)

Description

A data group determines the categories in which series values are grouped/aggregated.

Data groups associated with data levels are called visible data groups.  The visible data group that provides categories to render a chart is called active.  Only one data group can be active at one time.

With the data level navigator, end-users can customize the level of detail in a chart by switching active data levels/groups and choosing their active values.

In unbound Chart Views, a data group is represented by an instance of the TcxGridChartDataGroup class.  To access all data groups created in a Chart View, use the View’s DataGroups collection.

In addition to the settings inherited from the base TcxGridChartItem class, the TcxGridChartDataGroup class introduces members that allow you to:

•	activate a data group (Active);

•	specify an active value for a data group and determine whether it has an active value assigned (ActiveValue and HasActiveValue);

•	specify the position of the data level that corresponds to a data group within the data level navigator (DataLevel);

•	specify the order in which to display categories and data markers once a group is activated (SortOrder);

•	etc.

To access a data group’s properties at design time, you need to select the data group either via the Component Editor or click the corresponding data level within the data level navigator.


TcxGridChartDataGroup Hierarchy
Hierarchy

TComponent

     |

TcxComponent

     |

TcxGridChartItem

     |

TcxGridChartDataGroup


Properties for TcxGridChartDataGroup
TcxGridChartDataGroup Properties

TcxGridChartDataGroup          Legend

In TcxGridChartDataGroup

Active

ActiveValue

ActiveValueDisplayText

DataLevel

SortOrder

Derived from TcxGridChartItem

DataBinding

DisplayText

GridView

ID

Index

Order

SortOrder

ValueCount

Values

Visible

VisibleDisplayTexts

VisibleForCustomization

VisibleIndex

VisibleValueCount

VisibleValues


Methods for TcxGridChartDataGroup
TcxGridChartDataGroup Methods

TcxGridChartDataGroup          Legend

In TcxGridChartDataGroup

HasActiveValue

IsValue

Derived from TcxGridChartItem

GetDisplayText

GetValueDisplayText

IsValue


Events for TcxGridChartDataGroup
TcxGridChartDataGroup Events

TcxGridChartDataGroup          Legend

Derived from TcxGridChartItem

OnGetStoredProperties

OnGetStoredPropertyValue

OnGetValueDisplayText

OnSetStoredPropertyValue


TcxGridChartDataGroup.Active

TcxGridChartDataGroup

Specifies whether the data group provides categories to render a chart (i.e. is active).

property Active: Boolean;

Description

Set this property to True to make the data group active within a Chart View.  Since only one data group can be active at one time, the Active property of any other data group returns False.

Note:	A data group cannot be activated unless all data groups at lower data levels have their active values assigned.

To access the data group which is currently active in the View, use the View’s ActiveDataGroup property.

End-users are able to activate data groups/levels via the data level navigator.


TcxGridChartDataGroup.ActiveValue

TcxGridChartDataGroup          See Also

Specifies the active value for the data group.

property ActiveValue: Variant;

Description

To determine whether the active value is assigned to the data group, use the HasActiveValue property.  The ActiveValueDisplayText property returns a string representation of this value.

Use the VisibleValues property to access all the possible active values for the data group.


TcxGridChartDataGroup.ActiveValueDisplayText

TcxGridChartDataGroup          See Also

Returns a string representation of the data group’s active value as it appears in the data level navigator.

property ActiveValueDisplayText: string;

Description

If the ActiveValue property is not assigned, the ActiveValueDisplayText property returns an empty string.  In this instance, the scxGridChartToolBoxDataLevelSelectValue resource string specifies the text that will be displayed for the group’s active value.

ReadOnly Property


TcxGridChartDataGroup.DataLevel

TcxGridChartDataGroup          See Also

Specifies the on-screen position of the data level associated with the data group in the data level navigator.

property DataLevel: Integer;

Description

Modifying this property for a hidden data group makes this data group visible.

After this property’s value has been changed, elements in the View’s DataLevelObjects, DataGroups, and VisibleDataGroups collections are rearranged respectively.

Note:	Setting the DataLevel property to –1 hides the data group within the View.


TcxGridChartDataGroup.SortOrder

TcxGridChartDataGroup

Specifies the order in which the data group’s categories are displayed once this group becomes active.

type

  TcxDataSortOrder = (soNone, soAscending, soDescending);

property SortOrder: TcxDataSortOrder;

Description

By default, a data group’s categories are displayed in the order in which their values are stored in the VisibleValues property.  You can set the SortOrder property to modify the default plotting order.  A value of soNone cannot be assigned to this property.

Also you can use the SortOrder property of the default categories and series to apply sorting by their values.

Note:	Sorting applied to series takes priority over sorting by default categories or a data group.  Only a single type of sorting (either by default categories/a data group or series values) is active at one time within a chart.

To reverse the applied plotting order, set the View’s AxisCategory.CategoriesInReverseOrder property to True.

The default value of the SortOrder property is soAscending.


TcxGridChartDataGroup.HasActiveValue

TcxGridChartDataGroup

Determines whether an active value is assigned to the data group.

function HasActiveValue: Boolean;

Description

This function returns True when the ActiveValue property is assigned.  Otherwise, False is returned.


TcxGridChartDataGroup.IsValue

TcxGridChartDataGroup          See Also

Determines whether the data group provides values for calculating group summaries.

class function IsValue: Boolean; override;

Description

This function is for internal use only.

For data groups, this function returns False.


TcxGridChartSeries
TcxGridChartSeries Object

Hierarchy          Properties          Methods          Events          See Also

Represents a series in Chart Views.

Unit

cxGridChartView

TcxGridChartSeries = class(TcxGridChartItem)

Description

In unbound Chart Views, a series is represented by an instance of the TcxGridChartSeries class.  To access all series created in a Chart View, use the View’s Series collection.

The TcxGridChartSeries class extends its ancestor class with the members that specify appearance settings, control group summary (aggregate chart values) calculation and provide new series values.

The following list contains a summary on the main abilities that are introduced by the TcxGridChartSeries class.

•	Appearance Control.  To customize the appearance aspects of the elements of a series, use the Styles property.  Use the ValueCaptionFormat properties to specify the format pattern for the captions of series values.  To provide in-depth customization of series (both the data markers and the captions of series values), handle the OnCustomDrawValue event.

•	Aggregate Values.  To specify how series values within the same category are aggregated to produce group summaries, set the GroupSummaryKind property.  Use the SumOfValues property to get the sum of series values.

•	Series Values.  Call the AddValue function to add a new series value into the Values collection.

•	Data Drill-Down Control.  By handling the OnValueClick event you can provide custom logic when an end-user clicks a data marker to drill down on a chart value (for instance, you can prohibit data drilling in this manner).

To access series properties at design time, you need to select it either via the Component Editor or by clicking the corresponding data marker or legend item within a chart.


TcxGridChartSeries Hierarchy
Hierarchy

TComponent

     |

TcxComponent

     |

TcxGridChartItem

     |

TcxGridChartSeries


Properties for TcxGridChartSeries
TcxGridChartSeries Properties

TcxGridChartSeries          Legend

In TcxGridChartSeries

GroupSummaryKind

Styles

SumOfValues

ValueCaptionFormat

Derived from TcxGridChartItem

DataBinding

DisplayText

GridView

ID

Index

Order

SortOrder

ValueCount

Values

Visible

VisibleDisplayTexts

VisibleForCustomization

VisibleIndex

VisibleValueCount

VisibleValues

Derived from TComponent

Name

Tag


Methods for TcxGridChartSeries
TcxGridChartSeries Methods

TcxGridChartSeries          Legend

In TcxGridChartSeries

AddValue

IsValue

Derived from TcxGridChartItem

GetDisplayText

GetValueDisplayText

IsValue


Events for TcxGridChartSeries
TcxGridChartSeries Events

TcxGridChartSeries          Legend

In TcxGridChartSeries

OnCustomDrawValue

OnValueClick

Derived from TcxGridChartItem

OnGetStoredProperties

OnGetStoredPropertyValue

OnGetValueDisplayText

OnSetStoredPropertyValue


TcxGridChartSeries.GroupSummaryKind

TcxGridChartSeries          See Also

Specifies the summary function used to calculate group summaries against series values grouped within categories associated with visible data groups.

type

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

property GroupSummaryKind: TcxSummaryKind;

Description

The resulting summary values represent chart values visualized in a chart by data markers.  Note that the value of skNone cannot be assigned to this property.

The default value for the GroupSummaryKind property is specified by the cxGridChartItemDefaultSummaryKind constant.


TcxGridChartSeries.Styles

TcxGridChartSeries

Specifies the set of styles which define the appearance of the series.

property Styles: TcxGridChartSeriesStyles;

Description

Use the Styles property to access the set of styles which define the style (the color and background bitmap) of the data markers (for instance, bars for a bar diagram and columns for a column diagram) which correspond to the series.


TcxGridChartSeries.SumOfValues

TcxGridChartSeries

Returns the sum of series values that are used to render a chart.

property SumOfValues: Variant;

Description

To obtain the sum of values of a specific series, use the View’s ViewData.SumOfValues property.

ReadOnly Property


TcxGridChartSeries.ValueCaptionFormat

TcxGridChartSeries          See Also

Specifies the formatting pattern used to determine the captions of the series values.

property ValueCaptionFormat: string;

Description

The caption of a value in a series (a data label on a series value) is determined using the series values of the series by means of standard routines unless the formatting pattern is set via the ValueCaptionFormat property.  In this case, the pattern is used to format the resulting caption of the series value.  For instance, when a caption is determined using the ‘Profit/Loss = $,0.00;-$,0.00’ pattern, the pattern will be treated as follows.  The 0.00 portion will be substituted with the series value.  The two zeros after the point identify the number of digits in the resulting caption of the series value to the right of the decimal point.  The comma represents the ThousandSeparator global variable.  A semicolon separates the two patterns used to display positive and negative values, respectively.  Other characters do not have any special meaning and are displayed as they are.

Note:	For additional information on formatting numeric values, see the FormatFloat function topic.

The diagram’s CaptionPosition property controls the generic appearance of the captions of series values and their positions within the chart.

Note:	The value of the ValueCaptionFormat property is also used to determine tick-mark labels (see the description of the TcxGridChartHistogramAxisValue.GetTickMarkLabel function for details).


TcxGridChartSeries.AddValue

TcxGridChartSeries          See Also

Adds a new series value to the series.

function AddValue(const AValue: Variant): Integer;

Description

Call the AddValue function to add a new series value which is specified by the AValue parameter to the series (into the Values collection of this series).  The AddValue function returns the position (zero-based index) that the value was added at in the collection.


TcxGridChartSeries.IsValue

TcxGridChartSeries          See Also

Determines whether the series provides values for calculating group summaries.

class function IsValue: Boolean; override;

Description

This function is for internal use only.

For series, this function returns True.


TcxGridChartSeries.OnCustomDrawValue

TcxGridChartSeries

Occurs when a data marker in the series needs to be painted.

type

  TcxGridChartSeriesValueCustomDrawEvent = procedure(Sender: TcxGridChartSeries; ACanvas: TcxCanvas; AViewInfo: TcxGridChartDiagramValueViewInfo; var ADone: Boolean) of object;

property OnCustomDrawValue: TcxGridChartSeriesValueCustomDrawEvent;

Description

The OnCustomDrawValue event occurs every time a data marker needs to be painted.  As with other custom draw events it provides a canvas for the grid control (the ACanvas parameter), ViewInfo (the AViewInfo parameter and its Bounds property) to get the bounding rectangle of the painted element (in this case the data marker).  Sender is usually the element that caused the repaint.  The ADone parameter’s value is initially set to False.  Set it to True to tell the grid that you have finished drawing the data marker of the series.  In this case the diagram’s OnCustomDrawValue event for the series won't be fired.

To learn more about custom drawing, please refer to the Custom Draw topic.


TcxGridChartSeries.OnValueClick

TcxGridChartSeries          See Also

Occurs when a data marker is clicked.

type

  TcxGridChartValueClickEvent = procedure(Sender: TcxGridChartView; ASeries: TcxGridChartSeries; AValueIndex: Integer; var AHandled: Boolean) of object;

property OnValueClick: TcxGridChartValueClickEvent;

Description

This event is fired when a drill-down is performed.  Note that this event is fired even when:

•	the drill-down functionality is disabled via the View’s OptionsCustomize.DataDrillDown property;

•	a drill-down cannot be performed (the View’s Controller.IsDataDrillDownPossible function returns False).

The Sender and ASeries parameters identify the Chart View and the series whose value is clicked, respectively.

The AValueIndex corresponds to the index of the chart value being clicked in the VisibleValues collection of ASeries.

Set the AHandled parameter to True to cancel a drill-down operation.  In this instance the View’s OnValueClick event for this series won't be fired.


TcxGridChartDataLevelActiveValuePopup
TcxGridChartDataLevelActiveValuePopup Object

Hierarchy          Properties

Represents a data level’s dropdown.

Unit

cxGridChartView

TcxGridChartDataLevelActiveValuePopup = class(TcxCustomGridPopup)

Description

This class introduces the DataGroup property which allows you to access a visible data group associated with the data level.

Inherited members of the TcxGridChartDataLevelActiveValuePopup class (such as Popup and ClosePopup) allow you to change the drop-down list’s state.


TcxGridChartDataLevelActiveValuePopup Hierarchy
Hierarchy

TForm

     |

TcxPopupWindow

     |

TcxCustomPopupWindow

     |

TcxCustomGridPopup

     |

TcxGridChartDataLevelActiveValuePopup


Properties for TcxGridChartDataLevelActiveValuePopup
TcxGridChartDataLevelActiveValuePopup Properties

TcxGridChartDataLevelActiveValuePopup          Legend

In TcxGridChartDataLevelActiveValuePopup

DataGroup

GridView


TcxGridChartDataLevelActiveValuePopup.DataGroup

TcxGridChartDataLevelActiveValuePopup          See Also

Provides access to the visible data group which provides values for the data level dropdown.

property DataGroup: TcxGridChartDataGroup;

ReadOnly Property


TcxGridChartDataLevelActiveValuePopup.GridView

TcxGridChartDataLevelActiveValuePopup          See Also

Provides access to the Chart View, which displays the data level dropdown.

property GridView: TcxGridChartView;

ReadOnly Property


TcxCustomGridCardRowLayoutObject
TcxCustomGridCardRowLayoutObject Object

Hierarchy          Properties          Methods

TcxCustomGridCardRowLayoutObject is the base class for classes that implement different types of card layouts.

Unit

cxGridCardView

TcxCustomGridCardRowLayoutObject = class(TObject)

Description

A Card View provides an advanced item arrangement in a card.  Items can be organized in a column or row orientation (see the View’s RowLayout property) within a card.  When in a vertical orientation, items go down a column.

In horizontal row orientation, items are organized from left to right across a row.

Additionally, a card can be split into a required number of columns or rows.  In this context, a common term for columns and rows is "layers".  The developer must specify how many items are to be located in a particular layer (see the item’s Position.BeginsLayer property).

The TcxCustomGridCardRowLayoutObject class implements common logic that provides details on split layouts:

•	Card layout type (items are organized either in vertical or horizontal orientation);

•	If a card is split into layers, the total number of layers in a card, and the number of items in a particular layer (see the LayerCount and LayerRowCount);

•	A particular item’s location in a card.  The item’s location is defined by two types of coordinates.  With the first, the item’s location is determined as the sequential ordering of layers in a card and the sequential ordering of items in a particular layer (see the GetPosition method).  The second assumes that splitting a card into layers makes up a matrix of items.  As such, the item’s location is identified through the row-and-column dimension (see the GetCoordinates method);

•	A random access to the collection of items in a layer (see the LayerRows property).


TcxCustomGridCardRowLayoutObject Hierarchy
Hierarchy

TObject

     |

TcxCustomGridCardRowLayoutObject


Properties for TcxCustomGridCardRowLayoutObject
TcxCustomGridCardRowLayoutObject Properties

TcxCustomGridCardRowLayoutObject          Legend

In TcxCustomGridCardRowLayoutObject

LayerCount

LayerFirstRow

LayerFirstRowIndex

LayerRowCount

LayerRows

Layout


Methods for TcxCustomGridCardRowLayoutObject
TcxCustomGridCardRowLayoutObject Methods

TcxCustomGridCardRowLayoutObject          Legend

In TcxCustomGridCardRowLayoutObject

 GetCoordinates

 GetIndexInLayer

 GetLayerIndex

 GetOffsetInLayer

 GetPosition

 GetRowAtOffset

 IsFirstInLayer

 IsLastInLayer

 IsWholeLine


TcxCustomGridCardRowLayoutObject.LayerCount

TcxCustomGridCardRowLayoutObject          See Also

Gets a count of layers in a card.

property LayerCount: Integer;

Description

Use the LayerCount property to determine the total number of layers in a card.

ReadOnly Property


TcxCustomGridCardRowLayoutObject.LayerFirstRow

TcxCustomGridCardRowLayoutObject          See Also

Gets the first card row from a ALayerIndex layer.

property LayerFirstRow[ALayerIndex:Integer]: TcxGridCardViewRow;

Description

Use the LayerFirstRow property to obtain a reference to the first card row in the ALayerIndex layer.

ReadOnly Property


TcxCustomGridCardRowLayoutObject.LayerFirstRowIndex

TcxCustomGridCardRowLayoutObject          See Also

Gets an index of the first card row in a ALayerIndex layer.

property LayerFirstRowIndex[ALayerIndex:Integer]: Integer;

Description

Use the LayerFirstRowIndex property to obtain an index of the first card row in the ALayerIndex layer.

ReadOnly Property


TcxCustomGridCardRowLayoutObject.LayerRowCount

TcxCustomGridCardRowLayoutObject          See Also

Returns the total number of items in the ALayerIndex layer.

property LayerRowCount[ALayerIndex:Integer]: Integer;

Description

Use the LayerRowCount property to determine the number of items in the ALayerIndex layer.


TcxCustomGridCardRowLayoutObject.LayerRows

TcxCustomGridCardRowLayoutObject          See Also

Provides indexed access to card rows in a ALayerIndex layer.

property LayerRows[ALayerIndex,AIndex:Integer]: TcxGridCardViewRow;

Description

Use the LayerRows property to obtain a reference to a card row at the AIndex position in a ALayerIndex layer.

ReadOnly Property


TcxCustomGridCardRowLayoutObject.Layout

TcxCustomGridCardRowLayoutObject          See Also

Gets the card row’s sequence orientation.

property Layout: TcxGridCardViewRowLayout;

Description

The Layout property returns one of the two available types of card row arrangements in a card: either rlHorizontal, if card rows are organized into rows, or rlVertical, if card rows are organized into columns.

ReadOnly Property


TcxCustomGridCardRowLayoutObject.GetCoordinates

TcxCustomGridCardRowLayoutObject          See Also

Returns a card row’s location in a card - in row-and-column coordinates.

type

  TcxGridCardRowPosition = record

    LayerIndex: Integer;

    IndexInLayer: Integer;

  end;

  TcxGridCardRowCoordinates = record

  ColIndex: Integer;

  RowIndex: Integer;

  end;

Overloaded Variants

function GetCoordinates(const APosition: TcxGridCardRowPosition): TcxGridCardRowCoordinates;

function GetCoordinates(ARow: TcxGridCardViewRow): TcxGridCardRowCoordinates;

Description

The card row’s location in a card can be determined in one of two ways:

•	Layer-and-item – the index position of a layer in the card and the card row’s position in a layer (returned by the TcxGridCardRowPosition record).

•	Row-and-column – the absolute position in row-and-column coordinates (returned by the TcxGridCardRowCoordinates record).

The GetCoordinates method calculates the item’s location in row-and-column coordinates.

The first overload accepts the TcxGridCardRowPosition record containing information on the item’s position in layer-and-item coordinates and converts it into row-and-column coordinates.

The second calculates row-and-column coordinates of the passed ARow item.


TcxCustomGridCardRowLayoutObject.GetIndexInLayer

TcxCustomGridCardRowLayoutObject          See Also

Returns the ARow item’s index in the corresponding layer.

function GetIndexInLayer(ARow: TcxGridCardViewRow): Integer;

Description

Use the GetIndexInLayer method to determine the ARow item’s position in the layer.


TcxCustomGridCardRowLayoutObject.GetLayerIndex

TcxCustomGridCardRowLayoutObject          See Also

Returns the index of a layer that contains the specified card row.

Overloaded Variants

function GetLayerIndex(ARowIndex: Integer): Integer;

function GetLayerIndex(ARow: TcxGridCardViewRow): Integer;

Description

A card row can be identified by its index (as in the first overload), or an instance of the item can be passed to the method (as in the second overload).


TcxCustomGridCardRowLayoutObject.GetOffsetInLayer

TcxCustomGridCardRowLayoutObject          See Also

Returns the card row’s position in a layer (in lines).

Overloaded Variants

function GetOffsetInLayer(ALayerIndex, AIndexInLayer: Integer): Integer;

function GetOffsetInLayer(ARow: TcxGridCardViewRow): Integer;

Description

The GetOffsetInLayer method returns the index position of the line occupied by the specified card row in the layer.

The first overload takes two arguments – the index position of a layer in a card (the ALayerIndex parameter) and the index position of a card row in a layer (the AIndexInLayer parameter).

The second takes a card row’s instance as an argument whose offset is to be identified.


TcxCustomGridCardRowLayoutObject.GetPosition

TcxCustomGridCardRowLayoutObject          See Also

Returns an item’s location in a card - in layer-and-item coordinates.

Overloaded Variants

type

  TcxGridCardRowPosition = record

    LayerIndex: Integer;

    IndexInLayer: Integer;

  end;

  TcxGridCardRowCoordinates = record

  ColIndex: Integer;

  RowIndex: Integer;

  end;

function GetPosition(const ACoordinates: TcxGridCardRowCoordinates): TcxGridCardRowPosition;

function GetPosition(ARowIndex: Integer): TcxGridCardRowPosition;

function GetPosition(ARow: TcxGridCardViewRow): TcxGridCardRowPosition;

Description

The card row’s location in a card can be determined in one of two ways:

•	Layer-and-item – the index position of a layer in the card and the item’s position in a layer (returned by the TcxGridCardRowPosition record).

•	Row-and-column – the absolute position in row-and-column coordinates (returned by the TcxGridCardRowCoordinates record).

The GetPosition method calculates the item’s location in layer-and-item coordinates.

The first overload converts row-and-column coordinates into layer-and-item coordinates.

The second uses the item’s index in the corresponding layer as coordinates.

The third overload calculates the location of the ARow item passed in layer-and-item coordinates.


TcxCustomGridCardRowLayoutObject.GetRowAtOffset

TcxCustomGridCardRowLayoutObject          See Also

Returns a card row by the index position of the line it occupies.

function GetRowAtOffset(ALayerIndex, AOffset: Integer): TcxGridCardViewRow;

Description

A layer can contain an arbitrary number of card rows, and each card row in a layer can occupy the specified number of lines (see the view’s Position.LineCount property).

As a result, the card row’s position can be identified through the index position of the line it occupies in a layer.

The ALayerIndex parameter specifies the index position of a layer in a card;

The AOffset parameter specifies the index position of a line that a specific card row occupies.


TcxCustomGridCardRowLayoutObject.IsFirstInLayer

TcxCustomGridCardRowLayoutObject          See Also

Gets whether the ARow item occupies the first position in the corresponding layer.

function IsFirstInLayer(ARow: TcxGridCardViewRow): Boolean;

Description

The IsFirstInLayer method returns True, if the ARow item occupies the first position in the layer, otherwise – False.


TcxCustomGridCardRowLayoutObject.IsLastInLayer

TcxCustomGridCardRowLayoutObject          See Also

Gets whether the ARow item occupies the last position in the holding layer.

function IsLastInLayer(ARow: TcxGridCardViewRow): Boolean;

Description

The IsLastInLayer method returns True, if the ARow item occupies the last position in the layer, otherwise – False.


TcxCustomGridCardRowLayoutObject.IsWholeLine

TcxCustomGridCardRowLayoutObject          See Also

Determines whether the ARow item occupies the entire width of a row.

function IsWholeLine(ARow: TcxGridCardViewRow): Boolean;

Description

If a card is split into horizontal layers (the view’s RowLayout property is set to rlHorizontal) and a layer (wherein the ARow item is located) contains two or more card rows, IsWholeLine returns False.

IsWholeLine returns True if the ARow item comprises the entire layer.

When under a vertical layout, IsWholeLine always returns True.


TcxGridCardRowLayoutObject
TcxGridCardRowLayoutObject Object

Hierarchy          Properties          Methods

The TcxGridCardRowLayoutObject class is the base class for classes representing visual layouts of a card.

Unit

cxGridCardView

TcxGridCardRowLayoutObject = class(TcxCustomGridCardRowLayoutObject)

Description

The TcxGridCardRowLayoutObject class allows you to specify the card layout and provide a layout object with visible items that a layer is to be populated with.


TcxGridCardRowLayoutObject Hierarchy
Hierarchy

TObject

     |

TcxCustomGridCardRowLayoutObject

     |

TcxGridCardRowLayoutObject


Properties for TcxGridCardRowLayoutObject
TcxGridCardRowLayoutObject Properties

TcxGridCardRowLayoutObject          Legend

In TcxGridCardRowLayoutObject

Layout

Derived from TcxCustomGridCardRowLayoutObject

LayerCount

LayerFirstRow

LayerFirstRowIndex

LayerRowCount

LayerRows

Layout


Methods for TcxGridCardRowLayoutObject
TcxGridCardRowLayoutObject Methods

TcxGridCardRowLayoutObject          Legend

In TcxGridCardRowLayoutObject

 Fill

Derived from TcxCustomGridCardRowLayoutObject

 GetCoordinates

 GetIndexInLayer

 GetLayerIndex

 GetOffsetInLayer

 GetPosition

 GetRowAtOffset

 IsFirstInLayer

 IsLastInLayer

 IsWholeLine


TcxGridCardRowLayoutObject.Layout

TcxGridCardRowLayoutObject          See Also

Gets the card row’s sequence orientation.

property Layout: TcxGridCardViewRowLayout;

Description

The Layout property returns one of two available types of card row arrangements in a card: either rlHorizontal, if card rows are organized into rows, or rlVertical, if card rows are organized into columns.


TcxGridCardRowLayoutObject.Fill

TcxGridCardRowLayoutObject          See Also

Provides a layout object with ARows visible items to be drawn in a layer.

procedure Fill(ARows: TList);

Description

Use the Fill method each time information on visible items in a card has been changed.

The ARows parameter specifies a list of new visible items that the layer is to be populated with.


TcxGridCardViewRow
TcxGridCardViewRow Object

Hierarchy          Properties          Methods          Events          See Also

Represents an item in a card view.

Unit

cxGridCardView

TcxGridCardViewRow = class(TcxCustomGridTableItem);

Description

Every card (TcxGridCardView) consists of card view rows (items) and each of them in turn represents an instance of the TcxGridCardViewRow class. The TcxGridCardView class has a Rows property, thus allowing you to access a collection of card view rows.

Most of the functionality is implemented in the TcxCustomGridTableItem class.  The TcxGridCardViewRow class introduces properties specific to card view data representation.

In a card view, you can edit data in the same manner as you do in a table view.  To assign an editor to a specific card view row, you should use either of the RepositoryItem or PropertiesClass objects.

TcxGridCardViewRow is a base class for a data-aware version of a card view row presented by the TcxGridDBCardViewRow class.


TcxGridCardViewRow Hierarchy
Hierarchy

TComponent

     |

TcxCustomGridTableItem

     |


Properties for TcxGridCardViewRow
TcxGridCardViewRow Properties

TcxGridCardViewRow          Legend

In TcxGridCardViewRow

CaptionAlignmentHorz

CaptionAlignmentVert

CategoryItemCount

CategoryItems

CategoryRow

Expandable

Expanded

Kind

Options

Position

Styles

Derived from TcxCustomGridTableItem

ActuallyVisible

Caption

DataBinding

Editing

EditValue

Filtered

Focused

GridView

GroupIndex

HeaderAlignmentHorz

HeaderAlignmentVert

Hidden

ID

IncSearching

Index

IsFirst

IsLast

MinWidth

Options

Properties

PropertiesClass

RepositoryItem

SortOrder

Styles

Visible

VisibleForCustomization

VisibleIndex

Width


Methods for TcxGridCardViewRow
TcxGridCardViewRow Methods

TcxGridCardViewRow          Legend

In TcxGridCardViewRow

HasCardExpandButton

HasExpandButton

IsVisibleInCard

MoveTo

Derived from TcxCustomGridTableItem

ApplyBestFit

GetProperties

RestoreDefaults


Events for TcxGridCardViewRow
TcxGridCardViewRow Events

TcxGridCardViewRow          Legend

Derived from TcxCustomGridTableItem

 OnCustomDrawCell

 OnGetCellHint

 OnGetDataText

 OnGetDisplayText

 OnGetFilterDisplayText

 OnGetFilterValues

 OnGetProperties

 OnGetStoredProperties

 OnGetStoredPropertyValue

 OnInitFilteringDateRanges

 OnSetStoredPropertyValue

 OnUserFiltering


TcxGridCardViewRow.CaptionAlignmentHorz

TcxGridCardViewRow          See Also

Specifies the horizontal alignment of a card view row caption.

property CaptionAlignmentHorz: TAlignment;

Description

The CaptionAlignmentHorz property allows you to set the alignment of the card view row caption.  It is possible to align it to the left, right or center it.

To access the card view row caption, use the Caption member.


TcxGridCardViewRow.CaptionAlignmentVert

TcxGridCardViewRow          See Also

Defines the vertical alignment of the card view row caption.

type

  TcxAlignmentVert = (vaTop, vaBottom, vaCenter);

property CaptionAlignmentVert: TcxAlignmentVert;

Description

Use the CaptionAlignmentVert property to specify the vertical alignment of the card view row caption.  Possible values include:

Value	Meaning
vaTop	The text is aligned to the top.
vaBottom	The text is aligned to the bottom.
vaCenter	The text is centered vertically.

The vertical alignment takes effect when you set different fonts for row content and the row caption.


TcxGridCardViewRow.CategoryItemCount

TcxGridCardViewRow

Gets a count of the category row’s children in the CategoryItems collection.

property CategoryItemCount: Integer;

Description

Use the CategoryItemCount property to obtain the number of the category row‘s children.

ReadOnly Property


TcxGridCardViewRow.CategoryItems

TcxGridCardViewRow          See Also

Provides indexed access to the category row‘s children.

property CategoryItems[AIndex: Integer]: TcxGridCardViewRow;

Description

Use the CategoryItems property to retrieve the category row’s child at the position specified by the AIndex parameter.

ReadOnly Property


TcxGridCardViewRow.CategoryRow

TcxGridCardViewRow          See Also

Represents a category row.

property CategoryRow: TcxGridCardViewRow;

Description

A row that is displayed in the card view is a category row if its Kind property is set to rkCategory.

If the currently processed row is a child of a category row, use the CategoryRow property to access the parent’s instance.

The CategoryRow property returns nil if the currently processed row has no parent.


TcxGridCardViewRow.Expandable

TcxGridCardViewRow          See Also

Gets whether the currently processed row is a category row.

property Expandable: Boolean;

Description

A hierarchical row in a card view is a category row (the Kind property is set to rkCategory).

The Expandable property returns True if the currently processed row is a category row.

ReadOnly Property


TcxGridCardViewRow.Expanded

TcxGridCardViewRow          See Also

Expands or collapses the currently processed row if it’s a category row.

property Expanded: Boolean;

Description

Set the Expanded property to True to expand a row if it is a category row (the Kind property is set to rkCategory).  Otherwise it will be collapsed.

The default value of the Expanded property is True.


TcxGridCardViewRow.Kind

TcxGridCardViewRow          See Also

Specifies card row type.

type

  TcxGridCardViewRowKind = (rkData, rkCaption, rkCategory);

property Kind: TcxGridCardViewRowKind;

Description

The enumeration values specify three types of card rows that can be shown in a card:

rkData specifies data rows.  End-users can edit their values.

rkCaption represents caption rows.  These rows cannot be edited at runtime.  Their background is colored differently to visually distinguish them from data rows.

rkCategory specifies a category row type.  If the currently processed row is a category, the rows that follow it are its children.  A category row is used to logically organize related rows into group.  This group is drawn in a card view in a tree-like manner.  The expand button that appears in the category row to the left of its caption, allows end-users to expand or collapse it.  Unlike caption rows, category rows can be edited.

The default value of the Kind property is rkData.


TcxGridCardViewRow.Options

TcxGridCardViewRow

Specifies different options for managing, manipulating and displaying card view rows.

property Options: TcxGridCardViewRowOptions;

Description

The Options object contains a set of attributes which manage the appearance and behavior of card view rows.  These options include the editing capability, focusing of card view rows and whether captions are displayed.

To adjust the general behavior and appearance common to all rows in a card, use the corresponding options of the TcxGridCardView class instance instead.


TcxGridCardViewRow.Position

TcxGridCardViewRow          See Also

Represents card row layout options.

property Position: TcxGridCardViewRowPosition;

Description

With the options provided, you can:

•	place a row in a new layer (see the BeginsLayer property);

•	reposition a row between other rows or between layers (see the ColIndex, IndexInLayer and RowIndex properties);

•	specify the number of visual lines it will occupy in a card (see the LineCount property), and the row’s width (see the Width property).


TcxGridCardViewRow.Styles

TcxGridCardViewRow          See Also

Contains styles managing the appearance of card view row elements.

property Styles: TcxGridCardViewRowStyles;

Description

Use the Styles object to access the properties and events controlling the appearance of card view row elements such as caption, content regions and the caption row (Kind is set to rkCaption).  By handling style events, it is possible to provide a different appearance for individual records.

The view’s Styles property can be used to define styles common to all card view rows.


TcxGridCardViewRow.HasCardExpandButton

TcxGridCardViewRow

Determines whether the card expand button is visible within the current card row.

function HasCardExpandButton: Boolean;

Description

Use the HasCardExpandButton method to determine whether the current card row has the card expand button.  If the card expand button is visible within the current card row, the method returns True.  Otherwise, False is returned.


TcxGridCardViewRow.HasExpandButton

TcxGridCardViewRow

Determines whether the expand button is available in the currently processed row.

function HasExpandButton: Boolean; virtual;

Description

The expand button will be drawn in the currently processed row (HasExpandButton returns True), if the row is a category row (the Kind property is set to rkCategory), the OptionsCustomize.RowExpanding property is set to True, and the Options.Expanding property is also set to True.


TcxGridCardViewRow.IsVisibleInCard

TcxGridCardViewRow          See Also

Determines whether the card row is visible within the specified card.

function IsVisibleInCard(ACard: TcxGridCard): Boolean;

Description

Use the IsVisibleInCard method to determine whether the card row is visible within the card specified by the ACard parameter.  If the row is visible within the specified card, the method returns True.  Otherwise, False is returned.

Please refer to the TcxGridCard.GetVisibleRows method description for details on when card rows may be not visible within particular cards.


TcxGridCardViewRow.MoveTo

TcxGridCardViewRow          See Also

Moves the currently processed row to the AIndex visual position in the current card.

procedure MoveTo(AIndex: Integer; AMoveSubItems: Boolean);

Description

Use the MoveTo method to reposition the currently processed row in the card it’s located in.

The AIndex parameter specifies a new position;

The AMoveSubItems parameter specifies whether the row’s children are to be moved along with the row, if the row is a category row (the Kind property is set to rkCategory).  Set the AMoveSubItems parameter to True to move the row with its children.


TcxGridCardViewRowOptions
TcxGridCardViewRowOptions Object

Hierarchy          Properties          See Also

Contains options managing the appearance and behavior of a card row.

Unit

cxGridCardView

TcxGridCardViewRowOptions = class(TcxCustomGridTableItemOptions);

Description

TcxGridcardViewRowOptions publishes properties specific to a card row.  For example, you can prevent a user from editing and focusing a row.  Also, it is possible to hide the caption region of a row via the ShowCaption property.

To set options for a card row, use the row’s Options member.  The card view itself contains a set of options managing the appearance of all card rows.


TcxGridCardViewRowOptions Hierarchy
Hierarchy

TPersistent

     |

TcxCustomGridTableItemCustomOptions

     |

TcxCustomGridTableItemOptions

     |


Properties for TcxGridCardViewRowOptions
TcxGridCardViewRowOptions Properties

TcxGridCardViewRowOptions          Legend

In TcxGridCardViewRowOptions

Expanding

ShowData

Derived from TcxCustomGridTableItemOptions

Editing

Filtering

FilteringFilteredItemsList

FilteringMRUItemsList

FilteringPopup

FilteringPopupMultiSelect

Focusing

IgnoreTimeForFiltering

IncSearch

Moving

ShowCaption

ShowEditButtons


TcxGridCardViewRowOptions.Expanding

TcxGridCardViewRowOptions

Specifies whether the expand button appears in the row that the current settings are applied to (if this row is a category row).

property Expanding: Boolean;

Description

Set the Expanding property to True to make the expand button visible in the currently processed row.  The expand button only appears if this row is a category row (the Kind property is set to rkCategory).

Note: the Expanding property has priority over the OptionsCustomize.RowExpanding property.

The default value of the Expanding property is True.


TcxGridCardViewRowOptions.ShowData

TcxGridCardViewRowOptions

Specifies whether the value in the currently processed row is to be shown.

property ShowData: Boolean;

Description

Set the ShowData property to False to hide data in the row.

Note: the row’s filter dropdown button will also be hidden.

The default value of the ShowData property is True.


TcxGridCardViewRowPosition
TcxGridCardViewRowPosition Object

Hierarchy          Properties          Methods

The TcxGridCardViewRowPosition class represents layout options for a card row.

Unit

cxGridCardView

TcxGridCardViewRowPosition = class(TcxCustomGridTableItemCustomOptions)

Description

With the options provided, you can:

•	specify that the specified card row will start a new layer (see the BeginsLayer property);

•	reposition a row between other rows or between layers (see the ColIndex, IndexInLayer and RowIndex properties);

•	specify the number of visual lines it will occupy in a card (see the LineCount property), and select the row’s width (see the Width property).

The TcxGridCardViewRowPosition object is referenced by the row’s Position property.


TcxGridCardViewRowPosition Hierarchy
Hierarchy

TPersistent

     |

TcxCustomGridTableItemCustomOptions

     |

TcxGridCardViewRowPosition


Properties for TcxGridCardViewRowPosition
TcxGridCardViewRowPosition Properties

TcxGridCardViewRowPosition          Legend

In TcxGridCardViewRowPosition

BeginsLayer

ColIndex

GridView

IndexInLayer

Item

LayerIndex

LayerVisibleIndex

LineCount

RowIndex

VisibleColIndex

VisibleIndexInLayer

VisibleRowIndex

Width


Methods for TcxGridCardViewRowPosition
TcxGridCardViewRowPosition Methods

TcxGridCardViewRowPosition          Legend

In TcxGridCardViewRowPosition

 IsWholeLine


TcxGridCardViewRowPosition.BeginsLayer

TcxGridCardViewRowPosition          See Also

Specifies whether the currently processed row and subsequent rows will be put upon a new layer.

property BeginsLayer: Boolean;

Description

A Card View allows you to specify two card row layouts:

•	Card rows can be arranged into a row — a chain of items from left to right when the View’s RowLayout property is set to rlHorizontal:

•	They can be shown in a column orientation — one under another when the View’s RowLayout property is set to rlVertical:

A card layout, however, is not limited to a card row only orientation.  The grid control offers a more advanced layout technique: you can divide the card into an arbitrary number of rows or columns.  In this split layout, rows and columns are named "layers".  Each layer can hold a different set of card rows.  You simply specify which row will begin a separate layer.

Set the BeginsLayer property to True, to create a new layer that the current row (see the Item property) will start.  Otherwise, the present row will be located in the same layer as the next row.

Note: the BeginsLayer property is always set to True for the first row in a card.


TcxGridCardViewRowPosition.ColIndex

TcxGridCardViewRowPosition          See Also

Specifies the horizontal position of the currently processed row in a card.

property ColIndex: Integer;

Description

Use the ColIndex property to change the current card row’s position within a row when two or more card rows are located on this row. (Card rows within a card are laid out in a row if the view’s RowLayout property is set to rlHorizontal).

Use the ColIndex property to move the current card row between columns if the view’s RowLayout property is set to rlVertical and the card is split into two or more columns (see the BeginsLayer property).


TcxGridCardViewRowPosition.GridView

TcxGridCardViewRowPosition

Represents a card view where the card row that the current settings are applied to is located in.

property GridView: TcxGridCardView;

Description

Use the GridView property to obtain a reference to the card view instance.

ReadOnly Property


TcxGridCardViewRowPosition.IndexInLayer

TcxGridCardViewRowPosition          See Also

Specifies the ordinal number of the currently processed card row in a layer.

property IndexInLayer: Integer;

Description

Use the IndexInLayer property to position the current card row (see the Item property) in the holding layer.


TcxGridCardViewRowPosition.Item

TcxGridCardViewRowPosition

Represents a card row that current layout settings are applied to.

property Item: TcxGridCardViewRow;

Description

Use the Item property to obtain a reference to the card row instance.

ReadOnly Property


TcxGridCardViewRowPosition.LayerIndex

TcxGridCardViewRowPosition          See Also

Specifies the ordinal number of a layer in a card that the currently processed card row resides in.

property LayerIndex: Integer;

Description

The LayerIndex property provides a straight ordering of layers in a card and its value doesn’t depend upon whether the specified layer is hidden in a card view or not (if card rows it contains are not displayed).

Use the LayerIndex property to change the position of the layer (which contains the current card row) in a card.


TcxGridCardViewRowPosition.LayerVisibleIndex

TcxGridCardViewRowPosition          See Also

Gets the visible position of the layer that contains the currently processed card row.

property LayerVisibleIndex: Integer;

Description

The LayerVisibleIndex property’s value doesn’t match the LayerIndex property value if the current card row (or a set of card rows, if two or more card rows are located in the layer) is hidden (its Visible property is set to False).

Use the LayerVisibleIndex property to determine the visible position of the layer that the current card row (see the Item property) resides in.

ReadOnly Property


TcxGridCardViewRowPosition.LineCount

TcxGridCardViewRowPosition          See Also

Specifies the number of lines occupied by the currently processed card row.

property LineCount: Integer;

Description

Use the LineCount property to specify the number of lines occupied by the current card row (see the Item property).

The default value of the LineCount property is 1.


TcxGridCardViewRowPosition.RowIndex

TcxGridCardViewRowPosition          See Also

Specifies the vertical position of the currently processed card row in a card.

property RowIndex: Integer;

Description

Use the RowIndex property to change the current card row’s vertical position in a column (card rows in a card are laid out veritically if the view’s RowLayout property is set to rlVertical).

Use the RowIndex property to move the current card row between rows, if the view’s RowLayout property is set to rlHorizontal (card rows are organized in a horizontal orientation) and the card is split into two or more rows (see the BeginsLayer property).


TcxGridCardViewRowPosition.VisibleColIndex

TcxGridCardViewRowPosition          See Also

Gets the horizontal coordinate of the card row’s visible position in a card.

property VisibleColIndex: Integer;

Description

Use the VisibleColIndex property to determine the card row’s horizontal position in a visible card matrix.

ReadOnly Property


TcxGridCardViewRowPosition.VisibleIndexInLayer

TcxGridCardViewRowPosition          See Also

Gets the currently processed card row’s visible position in the corresponding layer.

property VisibleIndexInLayer: Integer;

Description

Use the VisibleIndexInLayer property to determine the visible position of the current card row (see the Item property) in the corresponding layer.

ReadOnly Property


TcxGridCardViewRowPosition.VisibleRowIndex

TcxGridCardViewRowPosition          See Also

Gets the vertical coordinate of card row’s visible position in a card.

property VisibleRowIndex: Integer;

Description

Use the VisibleRowIndex property to determine the card row’s vertical position in a visible card matrix.

ReadOnly Property


TcxGridCardViewRowPosition.Width

TcxGridCardViewRowPosition

Specifies the width of the currently processed card row.

property Width: Integer;

Description

Use the Width property to specify the width of a card row.

Note: if the Width property value is 0, the required width is calculated automatically.

The default value of the Width property is 0.


TcxGridCardViewRowPosition.IsWholeLine

TcxGridCardViewRowPosition          See Also

Determines whether the currently processed card row occupies the entire layer.

function IsWholeLine: Boolean;

Description

If a card is split into horizontal layers (the view’s RowLayout property is set to rlHorizontal) and the layer (which ARow is located in) contains only ARow, IsWholeLine returns True.  Otherwise – False.

When using vertical layering (a card is split into columns – card rows in columns flow downward, one under another), IsWholeLine always returns True.


TcxGridCardViewRowLayoutController
TcxGridCardViewRowLayoutController Object

Hierarchy          Properties          Methods

The TcxGridCardViewRowLayoutController class represents a card layout dispatcher.

Unit

cxGridCardView

TcxGridCardViewRowLayoutController = class(TObject)

Description

The TcxGridCardViewRowLayoutController class provides access both to the entire structure of the card and to the structure of the card’s visual layout.  It also allows you to manage the card layout dynamically, obtain information on different layouts, navigate in a card matrix and reposition items within a card.

The TcxGridCardViewRowLayoutController object is referenced by the view’s RowLayoutController property.


TcxGridCardViewRowLayoutController Hierarchy
Hierarchy

TObject

     |

TcxGridCardViewRowLayoutController


Properties for TcxGridCardViewRowLayoutController
TcxGridCardViewRowLayoutController Properties

TcxGridCardViewRowLayoutController          Legend

In TcxGridCardViewRowLayoutController

BeginsLayer

GridView

Layout

LayoutObject

VisibleLayoutObject


Methods for TcxGridCardViewRowLayoutController
TcxGridCardViewRowLayoutController Methods

TcxGridCardViewRowLayoutController          Legend

In TcxGridCardViewRowLayoutController

 FindNextRow

 FindNextRowHorizontally

 FindNextRowVertically

 GetCoordinates

 GetPosition

 GetVisibleCoordinates

 GetVisiblePosition

 IsHorizontalLayout

 IsSimpleLayout

 IsWholeLine

 SetCoordinates

 SetPosition


TcxGridCardViewRowLayoutController.BeginsLayer

TcxGridCardViewRowLayoutController

Specifies whether the ARow card row and subsequent card rows will be placed in a new layer.

property BeginsLayer[ARow: TcxGridCardViewRow]: Boolean;

Description

A Card View allows you to specify two card row layouts:

•	Card rows can be arranged into a row – a chain of card rows goes from left to right, if the View’s RowLayout property is set to rlHorizontal:

•	They can be shown in a column orientation, one under another if the View’s RowLayout property is set to rlVertical:

In addition, a card can be split into an arbitrary number of columns or rows.  Under the split layout, the resulting columns and rows are named "layers".  Creating a new layer is performed by setting the BeginsLayer property of the card row that will start the new layer to True.

Note: the BeginsLayer property is always set to True for the first card row in a card.


TcxGridCardViewRowLayoutController.GridView

TcxGridCardViewRowLayoutController

Represents the card view that the current layout is applied to.

property GridView: TcxGridCardView;

Description

Use the GridView property to obtain a reference to the card view instance.

ReadOnly Property


TcxGridCardViewRowLayoutController.Layout

TcxGridCardViewRowLayoutController

Represents the card row’s sequence orientation.

property Layout: TcxGridCardViewRowLayout;

Description

Two types of card row arrangement are available in a card:

•	Card rows in a card are arranged horizontally, from left to right – the Layout property returns rlHorizontal;

•	Card rows in a card are arranged into a column, one under another – the Layout property returns rlVertical.

ReadOnly Property


TcxGridCardViewRowLayoutController.LayoutObject

TcxGridCardViewRowLayoutController

Represents the entire structure of a card.

property LayoutObject: TcxGridCardViewRowLayoutObject;

Description

This object allows manipulation of layers in a card and changing the positions of card rows in the layers.

ReadOnly Property


TcxGridCardViewRowLayoutController.VisibleLayoutObject

TcxGridCardViewRowLayoutController

Represents the visual layout of a card.

property VisibleLayoutObject: TcxGridCardViewVisibleRowLayoutObject;

Description

The visual layout keeps track of the card’s visible card rows and describes how they are spread over layers.

ReadOnly Property


TcxGridCardViewRowLayoutController.FindNextRow

TcxGridCardViewRowLayoutController

Traverses a card in a specified direction and returns a reference to the card row next (or previous) to ARow.

function FindNextRow(ACard: TcxGridCard; ARow: TcxGridCardViewRow; ASameLayer, AGoForward, AGoOnCycle: Boolean; out ACycleChanged: Boolean): TcxGridCardViewRow;

Description

The FindNextRow method performs navigation in both directions.  To perform navigation in a horizontal direction (in a horizontally layered card), use the FindNextRowHorizontally method.  For vertical navigation (in a vertically layered card), use the FindNextRowVertically method.

The ACard parameter specifies the card to be navigated;

The ARow parameter specifies the card row that is the start point of navigation;

The ASameLayer parameter specifies whether navigation is bounded by ARow’s layer.  Set the ASameLayer parameter to True to perform navigation in one layer.  Otherwise navigation will be performed in the next layer if ARow is the last in the current layer and the AGoForward parameter is set to True (or in the previous layer, if ARow is first in the layer and the AGoForward parameter is set to False);

The AGoForward parameter specifies the direction of navigation.  Set the AGoForward parameter to True to move forward.  Otherwise backward navigation will be performed;

The AGoOnCycle parameter specifies whether navigation wraps at the end or at the start of the layer (if the ASameLayer parameter is set to True) or the card (if the ASameLayer parameter is set to False).  Set the AGoOnCycle parameter to True, to continue clockwise navigation (if the AGoForward parameter is set to True), or counterclockwise navigation (if the AGoForward parameter is set to False);

The ACycleChanged parameter specifies whether the AGoOnCycle parameter is set to True when forward navigation is performed (the AGoForward parameter’s value is True).  It returns True, if both parameters (the AGoOnCycle and AGoForward) are True.


TcxGridCardViewRowLayoutController.FindNextRowHorizontally

TcxGridCardViewRowLayoutController          See Also

Traverses a card in a horizontal direction and returns a reference to the card row next (or previous) to ARow.

function FindNextRowHorizontally(ACard: TcxGridCard; ARow: TcxGridCardViewRow; AGoForward, AGoOnCycle: Boolean; out ACycleChanged: Boolean): TcxGridCardViewRow;

Description

The FindNextRowHorizontally method is designed for navigation in a horizontally layered card (see the view’s RowLayout property and the card row’s Position.BeginsLayer property).

The ACard parameter specifies the card to be navigated;

The ARow parameter specifies the card row that is the start point of navigation;

The ASameLayer parameter specifies whether navigation is bounded by ARow’s layer.  Set the ASameLayer parameter to True to perform a lookup in one layer.  Otherwise, navigation will be performed in the next layer if ARow is the last in the current layer, and the AGoForward parameter is set to True (or in the previous layer, if ARow is first in the layer and the AGoForward parameter is set to False);

The AGoForward parameter specifies the direction of navigation.  Set the AGoForward parameter to True, to move forward.  Otherwise backward navigation will be performed;

The AGoOnCycle parameter specifies whether navigation wraps at the end or at the start of the layer.  Set the AGoOnCycle parameter to True to continue clockwise cycling (if the AGoForward parameter is set to True), or counterclockwise cycling (if the AGoForward parameter is set to False);

The ACycleChanged parameter specifies whether the AGoOnCycle parameter is set to True when forward navigation is performed (the AGoForward parameter’s value is True).  It returns True if both parameters (the AGoOnCycle and AGoForward) are True.


TcxGridCardViewRowLayoutController.FindNextRowVertically

TcxGridCardViewRowLayoutController          See Also

Traverses a card in a vertical direction and returns a reference to the card row next (or previous) to ARow.

function FindNextRowVertically(ACard: TcxGridCard; ARow: TcxGridCardViewRow; AGoForward, AGoOnCycle: Boolean; out ACycleChanged: Boolean): TcxGridCardViewRow;

Description

The FindNextRowVertically method is designed for navigation in a vertically layered card (see the view’s RowLayout property and the card row’s Position.BeginsLayer property).

The ACard parameter specifies the card to be navigated;

The ARow parameter specifies the card row that is the start point of navigation;

The AGoForward parameter specifies the direction of navigation.  Set the AGoForward parameter to True to move forward.  Otherwise backward navigation will be performed;

The AGoOnCycle parameter specifies whether navigation wraps at the end or at the start of a layer.  Set the AGoOnCycle parameter to True to continue clockwise cycling (if the AGoForward parameter is set to True), or counterclockwise cycling (if the AGoForward parameter is set to False);

The ACycleChanged parameter specifies whether the AGoOnCycle parameter is set to True when forward navigation is performed (the AGoForward parameter’s value is True).  It returns True if both parameters (the AGoOnCycle and AGoForward) are True.


TcxGridCardViewRowLayoutController.GetCoordinates

TcxGridCardViewRowLayoutController          See Also

Returns ARow’s location in a card - in row-and-column coordinates.

function GetCoordinates(ARow: TcxGridCardViewRow): TcxGridCardRowCoordinates;

Description

The card row’s location in a card can be determined in one of the following two ways:

•	Layer-and-item – the index position of a layer in the card and the card row’s position in a layer (returned by the TcxGridCardRowPosition record).

•	Row-and-column – the absolute position in row-and-column coordinates (returned by the TcxGridCardRowCoordinates record).

The ARow parameter specifies the card row whose location is to be obtained.


TcxGridCardViewRowLayoutController.GetPosition

TcxGridCardViewRowLayoutController          See Also

Returns ARow’s location in a card - in layer-and-item coordinates.

function GetPosition(ARow: TcxGridCardViewRow): TcxGridCardRowPosition;

Description

The card row’s location in a card can be determined in one of the following two ways:

•	Layer-and-item – the index position of a layer in the card and the card row’s position in a layer (returned by the TcxGridCardRowPosition record).

•	Row-and-column – the absolute position in row-and-column coordinates (returned by the TcxGridCardRowCoordinates record).

The ARow parameter specifies the card row whose location is to be obtained.


TcxGridCardViewRowLayoutController.GetVisibleCoordinates

TcxGridCardViewRowLayoutController          See Also

Returns ARow’s visible location in a card - in row-and-column coordinates.

function GetVisibleCoordinates(ARow: TcxGridCardViewRow): TcxGridCardRowCoordinates;

Description

Unlike the GetCoordinates method (which returns the card row’s coordinates in the entire card structure), the GetVisibleCoordinates method returns coordinates of the visible card row.

As a result, if ARow is not visible in a card (for example, ARow is a child of the category row and the latter one is collapsed), the corresponding column and row indexes in the TcxGridCardRowCoordinates record store the value of –1.

The ARow parameter specifies the card row whose location is to be obtained.


TcxGridCardViewRowLayoutController.GetVisiblePosition

TcxGridCardViewRowLayoutController          See Also

Returns ARow’s visible location in a card - in layer-and-item coordinates.

function GetVisiblePosition(ARow: TcxGridCardViewRow): TcxGridCardRowPosition;

Description

Unlike the GetPosition method (which returns the card row’s coordinates in the entire card structure), the GetVisiblePosition method returns coordinates of the visible card row.

As a result, if ARow is not visible in a card (for example, ARow is a child of the category row and the latter one is collapsed), the layer and item indexes in the TcxGridCardRowPosition record store the value of –1.


TcxGridCardViewRowLayoutController.IsHorizontalLayout

TcxGridCardViewRowLayoutController

Determines whether card rows are horizontally arranged within a card.

function IsHorizontalLayout: Boolean;

Description

If card rows are arranged horizontally (the view’s RowLayout property is set to rlHorizontal), the IsHorizontalLayout method returns True.

For a vertical layout (the view’s RowLayout property is set to rlVertical), IsHorizontalLayout returns False.


TcxGridCardViewRowLayoutController.IsSimpleLayout

TcxGridCardViewRowLayoutController

Determines whether a card has a one-dimensional structure.

function IsSimpleLayout: Boolean;

Description

If a card is split into horizontal layers with one card row per layer, IsSimpleLayout returns True.  Otherwise – False.

In the vertical layout (the view’s RowLayout property is set to rlVertical), if card rows are collected in a single column (one under another), IsSimpleLayout returns True.  Otherwise – False.


TcxGridCardViewRowLayoutController.IsWholeLine

TcxGridCardViewRowLayoutController

Determines whether ARow occupies the entire layer.

function IsWholeLine(ARow: TcxGridCardViewRow): Boolean;

Description

If a card is split into horizontal layers (the view’s RowLayout property is set to rlHorizontal) and the layer (which the ARow is located in) contains only ARow, IsWholeLine returns True.  Otherwise – False.

When using vertical layering, IsWholeLine always returns True.


TcxGridCardViewRowLayoutController.SetCoordinates

TcxGridCardViewRowLayoutController          See Also

Places ARow at a specified position.

Overloaded Variants

procedure SetCoordinates(ARow: TcxGridCardViewRow; AColIndex, ARowIndex: Integer); overload;

procedure SetCoordinates(ARow: TcxGridCardViewRow; ACoordinates: TcxGridCardRowCoordinates); overload;

Description

To place ARow at a new location, the SetCoordinates method accepts the card row’s new coordinates specified in row-and-column dimensions (see the card row’s Position.ColIndex and Position.RowIndex properties).

The ARow parameter specifies the card row to be placed at a new location;

The first overload accepts row-and-column coordinates through the AColIndex and ARowIndex parameters;

The second accepts row-and-column coordinates through the ACoordinates record.


TcxGridCardViewRowLayoutController.SetPosition

TcxGridCardViewRowLayoutController          See Also

Places ARow at a specified position.

procedure SetPosition(ARow: TcxGridCardViewRow; ALayerIndex, AIndexInLayer: Integer);

Description

To place ARow at a new location, the SetPosition method accepts the card row’s new coordinates specified in layer-and-item dimensions (see the card row’s Position.LayerIndex and Position.IndexInLayer properties).

The ARow parameter specifies the card row to be placed at a new location;

The ALayerIndex parameter specifies the layer’s position in a card and the AIndexInLayer parameter specifies the ARow’s position in a layer.


TcxGridCardViewRowLayoutObject
TcxGridCardViewRowLayoutObject Object

Hierarchy          Properties          Methods

The TcxGridCardViewRowLayoutObject class provides layered card layout information.

Unit

cxGridCardView

TcxGridCardViewRowLayoutObject = class(TcxCustomGridCardRowLayoutObject)

Description

The TcxGridCardViewRowLayoutObject class provides the means for handling the structure of a layered card.

The TcxGridCardViewRowLayoutObject object is referenced by the View’s RowLayoutController.LayoutObject property.


TcxGridCardViewRowLayoutObject Hierarchy
Hierarchy

TObject

     |

TcxCustomGridCardRowLayoutObject

     |

TcxGridCardViewRowLayoutObject


Properties for TcxGridCardViewRowLayoutObject
TcxGridCardViewRowLayoutObject Properties

TcxGridCardViewRowLayoutObject          Legend

In TcxGridCardViewRowLayoutObject

BeginsLayer

GridView

Derived from TcxCustomGridCardRowLayoutObject

LayerCount

LayerFirstRow

LayerFirstRowIndex

LayerRowCount

LayerRows

Layout


Methods for TcxGridCardViewRowLayoutObject
TcxGridCardViewRowLayoutObject Methods

TcxGridCardViewRowLayoutObject          Legend

In TcxGridCardViewRowLayoutObject

 BreakLayer

 IsSimpleLayout

 MergeLayer

 SetCoordinates

 SetIndexInLayer

 SetLayerIndex

 SetPosition

Derived from TcxCustomGridCardRowLayoutObject

 GetCoordinates

 GetIndexInLayer

 GetLayerIndex

 GetOffsetInLayer

 GetPosition

 GetRowAtOffset

 IsFirstInLayer

 IsLastInLayer

 IsWholeLine


TcxGridCardViewRowLayoutObject.BeginsLayer

TcxGridCardViewRowLayoutObject          See Also

Specifies whether the ARow card row and subsequent card rows will be placed in a new layer.

property BeginsLayer[ARow: TcxGridCardViewRow]: Boolean;

Description

A Card View allows you to specify one of two card row layouts:

•	Card rows can be arranged horizontally – a chain of card rows goes from left to right, if the View’s RowLayout property is set to rlHorizontal.

•	They can be shown in a vertical orientation, one under another, if the View’s RowLayout property is set to rlVertical.

In addition, a card can be split into an arbitrary number of columns or rows.  In a split layout, the resulting columns and rows are named "layers".  Creating a new layer is performed by setting the BeginsLayer property of the card row that will start the new layer to True.

Note: the first item in a card has its BeginsLayer property always set to True.


TcxGridCardViewRowLayoutObject.GridView

TcxGridCardViewRowLayoutObject

Represents the card view that the current layout is applied to.

property GridView: TcxGridCardView;

Description

Use the GridView property to access a card view instance.

ReadOnly Property


TcxGridCardViewRowLayoutObject.BreakLayer

TcxGridCardViewRowLayoutObject          See Also

Creates a new layer that follows ALayerIndex and places items starting from AIndexInLayer into the new layer.

procedure BreakLayer(ALayerIndex, AIndexInLayer: Integer);

Description

The BreakLayer method shifts down the indexes of any subsequent card layers.

The ALayerIndex parameter specifies a layer that the newly created layer will follow.

The AIndexInLayer parameter specifies the item that starts the list of items to be moved from ALayerIndex.


TcxGridCardViewRowLayoutObject.IsSimpleLayout

TcxGridCardViewRowLayoutObject          See Also

Determines whether a card has a one-dimensional structure.

function IsSimpleLayout: Boolean;

Description

If a card is split into horizontal layers with one card row per layer, the IsSimpleLayout method returns True.  Otherwise – False.

In a vertical layout (the view’s RowLayout property is set to rlVertical), if card rows are collected in a single column (one under another), the IsSimpleLayout method returns True.  Otherwise – False.


TcxGridCardViewRowLayoutObject.MergeLayer

TcxGridCardViewRowLayoutObject          See Also

Incorporates ALayerIndex with the previous layer.

procedure MergeLayer(ALayerIndex: Integer);

Description

All ALayerIndex’s card rows are moved to the previous layer.  These items are added to the end of the target layer’s items.

The MergeLayer method shifts up the indexes of any subsequent card layers.


TcxGridCardViewRowLayoutObject.SetCoordinates

TcxGridCardViewRowLayoutObject          See Also

Places ARow at a position specified by the ACoordinates record.

procedure SetCoordinates(ARow: TcxGridCardViewRow; const ACoordinates: TcxGridCardRowCoordinates);

Description

To place ARow at a new location, the SetCoordinates method accepts the card row’s new coordinates in row-and-column dimension (see the card row’s Position.ColIndex and Position.RowIndex properties).

The ARow parameter specifies the card row to be placed in a new location;

The ACoordinates parameter specifies the ARow’s new coordinates, in row-and-column dimensions.


TcxGridCardViewRowLayoutObject.SetIndexInLayer

TcxGridCardViewRowLayoutObject          See Also

Moves ARow to the AValue position in the corresponding layer.

procedure SetIndexInLayer(ARow: TcxGridCardViewRow; AValue: Integer; AMoveSubItems: Boolean = False);

Description

The ARow parameter specifies the card row to be moved to the AValue position;

The AValue parameter specifies the new card row’s location in a layer;

The AMoveSubItems parameter specifies whether the ARow ‘s existing children (if ARow is a category row – see the TcxGridCardViewRow.Kind property) are to be moved with the parent.  Set the AMoveSubItems parameter to True to move the children.


TcxGridCardViewRowLayoutObject.SetLayerIndex

TcxGridCardViewRowLayoutObject

Places ARow in the AValue layer.

procedure SetLayerIndex(ARow: TcxGridCardViewRow; AValue: Integer; ANewLayer: Boolean = False; AMoveSubItems: Boolean = False);

Description

The ARow parameter specifies the category row to be moved to the AValue layer;

The AValue parameter specifies the index of a layer;

The ANewLayer parameter specifies whether a new layer should be created.  Set the ANewLayer parameter to True to create a new layer.

The AMoveSubItems parameter specifies whether the ARow ‘s existing children (if ARow is a category row – see the TcxGridCardViewRow.Kind property) are to be moved with the parent.  Set the AMoveSubItems parameter to True to move the children.


TcxGridCardViewRowLayoutObject.SetPosition

TcxGridCardViewRowLayoutObject          See Also

Places ARow at a new position specified by the APosition record.

procedure SetPosition(ARow: TcxGridCardViewRow; const APosition: TcxGridCardRowPosition);

Description

To place ARow at a new location, the SetPosition method accepts the card row’s new coordinates in the layer-and-item dimension (see the item’s Position.LayerIndex and Position.IndexInLayer properties).

The ARow parameter specifies the card row to be placed in a new location;

The APosition parameter specifies the ARow’s new coordinates, in layer-and-item dimension.


TcxGridCardViewRowStyles
TcxGridCardViewRowStyles Object

Hierarchy          Properties          Methods          Events          See Also

Represents settings managing the style of card view row elements.

Unit

cxGridCardView

TcxGridCardViewRowStyles = class(TcxCustomGridTableItemStyles);

Description

The TcxGridCardViewRowStyles class provides a set of properties and events managing the appearance of card view row elements.  See the TcxGridCardViewRow.Styles property to define the style for caption and content regions of a card view row.  Also, it is possible to define a style for a caption row (a card view row with the Kind property set to rkCaption value).  Events allow you to define different styles for individual records.

A card view allows you to set the same styles for all card view items via the TcxGridCardView.Styles property.  Using members of TcxGridCardViewRowStyles, you can redefine the style for particular card items.


TcxGridCardViewRowStyles Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomStyles

     |

TcxStyles

     |

TcxCustomGridStyles

     |

TcxCustomGridTableItemStyles

     |


Properties for TcxGridCardViewRowStyles
TcxGridCardViewRowStyles Properties

TcxGridCardViewRowStyles          Legend

In TcxGridCardViewRowStyles

Caption

CaptionRow

CategoryRow

GridView

Item

Derived from TcxCustomGridTableItemStyles

Content

GridView

Item

Derived from TcxCustomGridStyles

GridView

Derived from TcxCustomStyles

StyleSheet


Methods for TcxGridCardViewRowStyles
TcxGridCardViewRowStyles Methods

TcxGridCardViewRowStyles          Legend

In TcxGridCardViewRowStyles

 GetCaptionParams

 GetCaptionRowParams

 GetCategoryRowParams

Derived from TcxCustomStyles

 Assign

 Create

 Destroy


Events for TcxGridCardViewRowStyles
TcxGridCardViewRowStyles Events

TcxGridCardViewRowStyles          Legend

In TcxGridCardViewRowStyles

 OnGetCaptionRowStyle

 OnGetCaptionStyle

 OnGetCategoryRowStyle

Derived from TcxCustomGridTableItemStyles

 OnGetContentStyle


TcxGridCardViewRowStyles.Caption

TcxGridCardViewRowStyles          See Also

Specifies the style for the caption region of a card view row.

property Caption: TcxStyle;

Description

Assign a style to the Caption property to redefine the default style for the caption region.  The default style can be set in a number of ways:

•	via the view’s Styles.Content property.  It defines the style for both the content and caption regions of a card (but only if the view’s Styles.RowCaption is not assigned).

•	via the row’s Styles.Content properties.  This style redefines the view’s Styles.Content property.

•	via the view’s Styles.RowCaption.  This attribute defines the style for all caption regions in a card.

You can handle the OnGetCaptionStyle event to redefine the style of the caption region for individual records.


TcxGridCardViewRowStyles.CaptionRow

TcxGridCardViewRowStyles          See Also

Specifies the style for a caption row.

property CaptionRow: TcxStyle;

Description

The CaptionRow property specifies the style for a row if its Kind property is set to rkCaption.  Otherwise, the style is determined by the Content and Caption properties.  To specify the style of a caption row for all cards in a view, use the view’s Styles.CaptionRow attribute.

The OnGetCaptionRowStyle event allows you to redefine the style of a caption row for specific records.


TcxGridCardViewRowStyles.CategoryRow

TcxGridCardViewRowStyles          See Also

Specifies style attributes for a category row.

property CategoryRow: TcxStyle;

Description

Use the CategoryRow property to specify the style for a category type card row (the row’s Kind property is set to kCategory).

To dynamically apply the specified style to the category row, use the OnGetCategoryRowStyle event.

Note: to make a style common to the entire row (to the caption and to its contents), set the row’s Options.Editing property to False.


TcxGridCardViewRowStyles.GridView

TcxGridCardViewRowStyles

Identifies the card view holding an item for which the style is applied.

property GridView: TcxGridCardView;

Description

The GridView property provides access to properties of the card view holding the card view row for which the current TcxGridCardViewRowStyles instance is applied.

ReadOnly Property


TcxGridCardViewRowStyles.Item

TcxGridCardViewRowStyles

Specifies the card row that the current styles are applied to.

property Item: TcxGridCardViewRow;

Description

Use the Item property to access the card row instance.

ReadOnly Property


TcxGridCardViewRowStyles.GetCaptionParams

TcxGridCardViewRowStyles          See Also

Gets the TcxViewParams record containing information on style attributes of the row’s caption.

procedure GetCaptionParams(ARecord: TcxCustomGridRecord; out AParams: TcxViewParams); virtual;

Description

The ARecord parameter specifies a record that the currently processed row corresponds to;

The AParams parameter specifies style attributes that the method applies.


TcxGridCardViewRowStyles.GetCaptionRowParams

TcxGridCardViewRowStyles          See Also

Gets the TcxViewParams record containing information on the caption row’s style attributes.

procedure GetCaptionRowParams(ARecord: TcxCustomGridRecord; out AParams: TcxViewParams); virtual;

Description

The ARecord parameter specifies a record that the currently processed caption row corresponds to;

The AParams parameter specifies style attributes that the method applies.


TcxGridCardViewRowStyles.GetCategoryRowParams

TcxGridCardViewRowStyles          See Also

Gets the TcxViewParams record containing information on the category row’s style attributes.

procedure GetCategoryRowParams(ARecord: TcxCustomGridRecord; out AParams: TcxViewParams); virtual;

Description

The ARecord parameter specifies a record that the currently processed caption row corresponds to;

The AParams parameter specifies style attributes that the method applies.


TcxGridCardViewRowStyles.OnGetCaptionRowStyle

TcxGridCardViewRowStyles          See Also

Occurs when a row of "caption" type should be redrawn.

type

  TcxGridGetCellStyleEvent = procedure(Sender: TcxCustomGridTableView; ARecord: TcxCustomGridRecord; AItem: TcxCustomGridTableItem; out AStyle: TcxStyle) of object;

property OnGetCaptionRowStyle: TcxGridGetCellStyleEvent;

Description

Handle the OnGetCaptionRowStyle event to override the default style of a caption row (a card view row whose Kind property is set to rkCaption) for individual records.  To set the default style for a caption row, use the CaptionRow attribute.

The ARecord parameter determines a record for which the event is generated.  The Sender and AItem parameters define the view and an item (a card view row) respectively.

To redefine the style, you need to create a TcxStyle object and return it via the AStyle parameter.  You should not create the style in the event handler.  Instead, use the style repository (the TcxStyleRepository component) to create individual styles.


TcxGridCardViewRowStyles.OnGetCaptionStyle

TcxGridCardViewRowStyles          See Also

Occurs when repainting the caption region of a card view row.

type

  TcxGridGetCellStyleEvent = procedure(Sender: TcxCustomGridTableView; ARecord: TcxCustomGridRecord; AItem: TcxCustomGridTableItem; out AStyle: TcxStyle) of object;

property OnGetCaptionStyle: TcxGridGetCellStyleEvent;

Description

The OnGetCaptionStyle event occurs every time that the caption of a card view row should be redrawn.  You can handle this event to redefine the style of a caption for individual records identified by the ARecord parameter.  The default style of a card view row caption is set in the Caption property.  To redefine the style, you need to create a TcxStyle object and return it via the AStyle parameter. You should not create the style in the event handler.  Instead, use the style repository (the TcxStyleRepository component) to create individual styles.

The Sender and AItem parameters define a card view and an item (a card view row) respectively.


TcxGridCardViewRowStyles.OnGetCategoryRowStyle

TcxGridCardViewRowStyles          See Also

Fires each time the category row is about to be drawn.

type

  TcxGridGetCellStyleEvent = procedure(Sender: TcxCustomGridTableView; ARecord: TcxCustomGridRecord; AItem: TcxCustomGridTableItem; out AStyle: TcxStyle) of object;

property OnGetCategoryRowStyle: TcxGridGetCellStyleEvent;

Description

Implement the OnGetCategoryRowStyle event handler to manually apply a custom style to a specific category row.

The Sender parameter specifies the card view containing the currently processed category row;

The ARecord parameter specifies the record that the currently processed category row corresponds to;

The AItem parameter specifies the currently processed category row;

The AStyle parameter specifies style attributes to be applied to the category row.


TcxGridCardViewVisibleRowLayoutObject
TcxGridCardViewVisibleRowLayoutObject Object

Hierarchy          Properties          Methods

The TcxGridCardViewVisibleRowLayoutObject class represents the visual layout of a layered card.

Unit

cxGridCardView

TcxGridCardViewVisibleRowLayoutObject = class(TcxGridCardRowLayoutObject)

Description

The TcxGridCardViewVisibleRowLayoutObject class keeps track of visible card rows in a layered card.  It describes how they are spread between layers.

The TcxGridCardViewVisibleRowLayoutObject object is referenced by the View’s RowLayoutController.VisibleLayoutObject property.


TcxGridCardViewVisibleRowLayoutObject Hierarchy
Hierarchy

TObject

     |

TcxCustomGridCardRowLayoutObject

     |

TcxGridCardRowLayoutObject

     |

TcxGridCardViewVisibleRowLayoutObject


Properties for TcxGridCardViewVisibleRowLayoutObject
TcxGridCardViewVisibleRowLayoutObject Properties

TcxGridCardViewVisibleRowLayoutObject          Legend

In TcxGridCardViewVisibleRowLayoutObject

GridView

Derived from TcxGridCardRowLayoutObject

Layout

Derived from TcxCustomGridCardRowLayoutObject

LayerCount

LayerFirstRow

LayerFirstRowIndex

LayerRowCount

LayerRows

Layout


Methods for TcxGridCardViewVisibleRowLayoutObject
TcxGridCardViewVisibleRowLayoutObject Methods

TcxGridCardViewVisibleRowLayoutObject          Legend

In TcxGridCardViewVisibleRowLayoutObject

 GetLastVisibleSubItem

 GetLayerCount

 IsWholeLayer

Derived from TcxGridCardRowLayoutObject

 Fill

Derived from TcxCustomGridCardRowLayoutObject

 GetCoordinates

 GetIndexInLayer

 GetLayerIndex

 GetOffsetInLayer

 GetPosition

 GetRowAtOffset

 IsFirstInLayer

 IsLastInLayer

 IsWholeLine


TcxGridCardViewVisibleRowLayoutObject.GridView

TcxGridCardViewVisibleRowLayoutObject

Represents a card view that the current layout is applied to.

property GridView: TcxGridCardView;

Description

Use the GridView property to access the card view instance.

ReadOnly Property


TcxGridCardViewVisibleRowLayoutObject.GetLastVisibleSubItem

TcxGridCardViewVisibleRowLayoutObject

Provides access to the last child of the ARow.

function GetLastVisibleSubItem(ARow: TcxGridCardViewRow): TcxGridCardViewRow;

Description

If ARow is a category row (the ARow’s Kind property is set to rkCategory) and it’s expanded (the value of its Expanded property is True), the GetLastVisibleSubItem method returns a reference to the ARow’s last child.

Otherwise the method returns a reference to the ARow itself.


TcxGridCardViewVisibleRowLayoutObject.GetLayerCount

TcxGridCardViewVisibleRowLayoutObject

Determines the number of layers occupied by ARow and its children.

function GetLayerCount(ARow: TcxGridCardViewRow): Integer;

Description

If ARow is a category row (the ARow’s Kind property is set to rkCategory), ARow and its children can be divided between different layers (see the view’s Position.BeginsLayer property).

The GetLayerCount method returns how many layers ARow and its children reside in.


TcxGridCardViewVisibleRowLayoutObject.IsWholeLayer

TcxGridCardViewVisibleRowLayoutObject

Determines whether ARow and its children comprise the entire layer.

function IsWholeLayer(ARow: TcxGridCardViewRow): Boolean;

Description

An ARow item can have children if it is a category row (the ARow’s Kind property is set to rkCategory).

IsWholeLayer returns True, if only ARow and its children reside in a particular layer.


TcxGridCardVisibleRowLayoutObject
TcxGridCardVisibleRowLayoutObject Object

Hierarchy          Properties          Methods

The TcxGridCardVisibleRowLayoutObject class implements the card rows layout in a layered card.

Unit

cxGridCardView

TcxGridCardVisibleRowLayoutObject = class(TcxGridCardRowLayoutObject)

Description

With the GetLayerRows (or GetRowsAtOffset) and inherited Fill methods, the TcxGridCardVisibleRowLayoutObject class allows the manipulation of visible card rows in a layered card.


TcxGridCardVisibleRowLayoutObject Hierarchy
Hierarchy

TObject

     |

TcxCustomGridCardRowLayoutObject

     |

TcxGridCardRowLayoutObject

     |

TcxGridCardVisibleRowLayoutObject


Properties for TcxGridCardVisibleRowLayoutObject
TcxGridCardVisibleRowLayoutObject Properties

TcxGridCardVisibleRowLayoutObject          Legend

In TcxGridCardVisibleRowLayoutObject

Card

Derived from TcxGridCardRowLayoutObject

Layout

Derived from TcxCustomGridCardRowLayoutObject

LayerCount

LayerFirstRow

LayerFirstRowIndex

LayerRowCount

LayerRows

Layout


Methods for TcxGridCardVisibleRowLayoutObject
TcxGridCardVisibleRowLayoutObject Methods

TcxGridCardVisibleRowLayoutObject          Legend

In TcxGridCardVisibleRowLayoutObject

 GetInsertionParams

 GetLayerRows

 GetRowsAtOffset

Derived from TcxGridCardRowLayoutObject

 Fill

Derived from TcxCustomGridCardRowLayoutObject

 GetCoordinates

 GetIndexInLayer

 GetLayerIndex

 GetOffsetInLayer

 GetPosition

 GetRowAtOffset

 IsFirstInLayer

 IsLastInLayer

 IsWholeLine


TcxGridCardVisibleRowLayoutObject.Card

TcxGridCardVisibleRowLayoutObject

Represents a card that the current layout is applied to.

property Card: TcxGridCard;

Description

Use the Card property to access the card instance.

ReadOnly Property


TcxGridCardVisibleRowLayoutObject.GetInsertionParams

TcxGridCardVisibleRowLayoutObject

Calculates the position of the ARow to be placed in the specified layer, in layer-and-item coordinates.

procedure GetInsertionParams(ARow: TcxGridCardViewRow; APosition: TcxPosition; out AInsertionIndex: Integer; out AInsertionPos: TcxGridCardRowInsertionPos);

Description

The ARows parameter specifies a card row to be positioned;

The APosition parameter specifies the direction of card row movement;

The AInsertionIndex parameter specifies the ARow’s index position in a layer on which the ARow is to be placed;

The AInsertionPos parameter specifies which layer the ARow is to be placed in.


TcxGridCardVisibleRowLayoutObject.GetLayerRows

TcxGridCardVisibleRowLayoutObject          See Also

Populates the ARows collection with visible card rows, which are located in the layer indicated by the ARowInLayer.

procedure GetLayerRows(ARowInLayer: TcxGridCardViewRow; ARows: TList);

Description

Use the GetLayerRows method to cache card rows of a particular layer.

The ARowInLayer parameter specifies a card row that identifies a corresponding layer;

The ARows parameter specifies a cache to be populated with card rows.


TcxGridCardVisibleRowLayoutObject.GetRowsAtOffset

TcxGridCardVisibleRowLayoutObject          See Also

Populates the ARows collection with visible card rows beginning from the first card row and ending with the ARowAtOffset card row.

procedure GetRowsAtOffset(ARowAtOffset: TcxGridCardViewRow; ARows: TList);

Description

Use the GetRowsAtOffset method to cache a set of card rows bound by the specified card row.

The ARowAtOffset parameter specifies the card row, which is the upper bound of the card rows to be cached;

The ARows parameter specifies the cache to be populated with card rows.


TcxGridCardRowCoordinates
TcxGridCardRowCoordinates type

See Also

Contains information on the card row’s position in a card, in row-and-column coordinates.

Unit

cxGridCardView

type

  TcxGridCardRowCoordinates = record

  ColIndex: Integer;

  RowIndex: Integer;

end;

Description

The ColIndex field specifies the layer’s index position in a card, if the view’s RowLayout property is set to rlVertical, or the card row’s index position in a layer, if the view’s RowLayout property is set to rlHorizontal.

The RowIndex field specifies the card row’s index position in a layer, if the view’s RowLayout property is set to rlVertical, or the layer’s index position in a card, if the view’s RowLayout property is set to rlHorizontal.


TcxGridCardRowInsertionPos
TcxGridCardRowInsertionPos type

See Also

Unit

cxGridCardView

type

  TcxGridCardRowInsertionPos = (ripPrevLayer, ripNewLayer, ripSameLayer);

Description

The following table contains descriptions of enumeration values:

Value	Meaning
ripPrevLayer	The card row will be placed in the previous layer
ripNewLayer	The card row will be placed in a newly created layer
ripSameLayer	The card row will be placed in the same layer


TcxGridCardRowPosition
TcxGridCardRowPosition type

See Also

Contains information on layer and card row positions in a card.

Unit

cxGridCardView

type

  TcxGridCardRowPosition = record

    LayerIndex: Integer;

    IndexInLayer: Integer;

  end;

Description

The LayerIndex field specifies the layer’s (row’s or column’s) index position in a card.

The IndexInLayer field specifies the card row’s index position in a layer.


TcxGridCardViewRowLayout
TcxGridCardViewRowLayout type

See Also

Unit

cxGridCardView

TcxGridCardViewRowLayout = (rlHorizontal, rlVertical);

Description

The following table contains descriptions of enumeration values:

Value	Meaning
rlHorizontal	Card rows in a card are arranged horizontally, from left to right
rlVertical	Card rows in a card are arranged vertically, one under another


cxGridExportLink Unit Overview

Routines

ExportGridToExcel

ExportGridToHTML

ExportGridToText

ExportGridToXML

Global Constants

cxGridFooterCellIndent


ExportGridToExcel

See Also

Exports the currently active root level’s content into a file in the MS Excel format.

Unit

cxGridExportLink

procedure ExportGridToExcel(const AFileName: string; AGrid: TcxGrid; AExpand: Boolean = True; ASaveAll: Boolean = True; AUseNativeFormat: Boolean = True; const AFileExt: string = ‘xls’);

Description

Use the ExportGridToExcel method to export the grid control’s content into an XLS file.  The target file’s name is specified by the AFileName parameter.  Note that you should not specify the file’s extension using this parameter.  The extension will be automatically replaced with the AFileExt parameter value.

The grid control whose content is to be copied is specified by the AGrid parameter.  Note that only the currently active root level’s content will be exported.  Excel export doesn’t support master-detail data.

The AExpand parameter indicates whether to export all records displayed within the exported level including records hidden within collapsed groups.  If this parameter value is True, the grid expands all group and master records before exporting.  If this parameter value is False, the records’ expanded state remains unchanged and only visible records’ content is written to the file.

The ASaveAll parameter indicates whether to export all or selected records.  Set the parameter to False to export only the current selection.

If the AUseNativeFormat parameter is True, the export routine tries to convert display text of grid cells to the corresponding Excel format (Currency, Date, Time or Float).  If you specify an editor to an item, the display text of all cells in the item is converted to a proper MS Excel format according to the following table:

An editor assigned to a grid cell	The corresponding MS Excel format
TcxCurrencyEdit	Currency
TcxMaskEditProperties or TcxCalcEditProperties	Currency, if the editor is bound to the field whose values are formatted as currency values (see the field’s Currency property). Otherwise, Number.
TcxDateEdit	Date
TcxTimeEdit	Time
TcxSpinEdit	Number
Note:	if columns don’t use editors listed above, values from that columns are exported as strings regardless of the AUseNativeFormat parameter value.  If a particular cell’s text cannot be converted to the required format (if the cell contains invalid characters, for instance) or the data type of an underlying data field does not exactly correspond to the data type associated with the assigned editor (for instance, a numeric data field used to store currency values), it is exported as a string.

If the AUseNativeFormat parameter value is False, all values are exported as strings.

The following image shows sample data exported to MS Excel format:


ExportGridToHTML

See Also

Exports the grid control’s content to a file in HTML format.

Unit

cxGridExportLink

procedure ExportGridToHTML(const AFileName: string; AGrid: TcxGrid; AExpand: Boolean = True; ASaveAll: Boolean = True; const AFileExt: string = ‘html’);

Description

Use the ExportGridToHTML method to export the AGrid control’s contents to an HTML file.  The target file’s name is specified by the AFileName parameter.  Note that you should not specify the file extension by this parameter.  The extension is automatically replaced with the AFileExt parameter value.

The AExpand parameter indicates whether to export all records displayed by the grid including those hidden within collapsed groups and collapsed details.  Note that if the parameter is set to True, all group and master records are automatically expanded prior to exporting data.  If AExpand is False, only the currently visible records are written to the file.

The ASaveAll parameter indicates whether to export all or selected records.  Set the parameter to False to export only the current selection.

The following image shows sample data exported to HTML format:


ExportGridToText

See Also

Exports the contents of a grid control to a text file.

Unit

cxGridExportLink

procedure ExportGridToText(const AFileName: string; AGrid: TcxGrid; AExpand: Boolean = True; ASaveAll: Boolean = True; const ASeparator: string = ''; const ABeginString: string = ''; const AEndString: string = '');

Description

Use the ExportGridToText method to save the AGrid control’s contents to a text file.

 ExportGridToText does not allow you to export detail views.  When writing to text format, cell styles and borders are not supported.  Only the cell arrangement and cell contents are exported to the file.

The AFileName parameter specifies the name and the path of the text file.  The ‘.txt’ extension is added automatically by the method.  If the filename already contains an extension, it will replaced with ‘.txt’.

The AExpand parameter indicates whether to export all records displayed in the grid including those hidden within collapsed groups.  If AExpand is False, only visible records are written to the file.

The ASaveAll parameter indicates whether to export selected or all records.

You can use the ASeparator parameter to specify the string to delimit cells being exported as text format.  In addition, you can define the prefix and postfix strings to add to each cells contents via ABeginString and AEndString.

The following image shows sample data exported to text format with the ABeginString parameter set to ‘|’.


ExportGridToXML

See Also

Exports records of the grid control in XML format.

Unit

cxGridExportLink

procedure ExportGridToXML(const AFileName: string; AGrid: TcxGrid; AExpand: Boolean = True; ASaveAll: Boolean = True);

Description

Use the ExportGridToXML method to save the AGrid control’s contents to an XML file.

The AFileName parameter specifies the name and the path of the XML file.  The ‘.xml’ extension is automatically added to the filename or replaces the existing extension.

The AExpand parameter indicates whether to export all records displayed in a grid control including those hidden within collapsed groups or are in detail views.  If AExpand is False, only visible records are written to the file.

The ASaveAll parameter indicates whether to export selected or all records.

The following image shows data exported to XML format:


cxGridFooterCellIndent
cxGridFooterCellIndent global constant

See Also

Specifies the indent when exporting the grid control with footer and group footer cells to various formats.

Unit

cxGridExportLink

cxGridFooterCellIndent: Integer = 0;

Description

Use this constant to specify the indent that is used to mark footer and group footer cells in the exported file so that they appear similar to the cells in the grid control.

Note:	When exporting to a file in the MS Excel format, footer and group cell indents are made up with additional columns and rows.

The image below shows a sample grid control exported to XLS format.

The following table shows the examples of exported data using various values for the cxGridFooterCellIndent constant.

Value	Sample Output
0
2


TcxCustomGridStyles
TcxCustomGridStyles Object

Hierarchy          Properties          Methods          See Also

Represents settings controlling the style of grid elements.

Unit

cxGridCustomView

TcxCustomGridStyles = class(TcxStyles);

Description

The TcxCustomGridStyles class declares properties allowing you to customize the appearance of view elements.  Descendants of TcxCustomGridStyles publish additional properties specific to particular types of grid item.


TcxCustomGridStyles Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomStyles

     |

TcxStyles

     |


Properties for TcxCustomGridStyles
TcxCustomGridStyles Properties

TcxCustomGridStyles          Legend

In TcxCustomGridStyles

GridView

Derived from TcxCustomStyles

StyleSheet


Methods for TcxCustomGridStyles
TcxCustomGridStyles Methods

TcxCustomGridStyles          Legend

Derived from TcxCustomStyles

 Assign

 Create

 Destroy


TcxCustomGridStyles.GridView

TcxCustomGridStyles

Specifies the view for which a style is applied.

property GridView: TcxCustomGridView;

Description

Use the GridView property to access the grid view to which the current style is applied.

ReadOnly Property


TcxCustomGridViewStyles
TcxCustomGridViewStyles Object

Hierarchy          Properties          Methods          See Also

Represents settings controlling the style of view elements.

Unit

cxGridCustomView

TcxCustomGridViewStyles = class(TcxCustomGridStyles);

Description

The TcxCustomGridViewStyles class declares properties and methods allowing you to customize the appearance of view elements.  Descendants of TcxCustomGridViewStyles publish other properties specific to particular views (table or card).  To adjust the appearance of a view, see the TcxCustomGridView.Styles property.


TcxCustomGridViewStyles Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomStyles

     |

TcxStyles

     |

TcxCustomGridStyles

     |


Properties for TcxCustomGridViewStyles
TcxCustomGridViewStyles Properties

TcxCustomGridViewStyles          Legend

In TcxCustomGridViewStyles

Background

Derived from TcxCustomGridStyles

GridView


Methods for TcxCustomGridViewStyles
TcxCustomGridViewStyles Methods

TcxCustomGridViewStyles          Legend

Derived from TcxCustomStyles

 Assign

 Create

 Destroy


TcxCustomGridViewStyles.Background

TcxCustomGridViewStyles

Specifies the style for a view background.

property Background: TcxStyle;

Description

The Background property allows you to define the style (font, background color) for a view background.

The following image shows a grid control with its background painted in turquoise ($00D0E040):

The Background property can also be used to specify the style for the ‘<No data to display>’ label which is displayed in an empty grid view (refer to the OptionsView.NoDataToDisplayInfoText property for details).