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


cxBlobEdit Unit Overview
cxBlobEdit Unit

Classes

TcxBlobEdit

TcxBlobEditProperties

TcxCustomBlobEdit

TcxCustomBlobEditProperties

Global Variables

imgBlobImages

SBlobButtonCancel

SBlobButtonClose

SBlobButtonOK


TcxBlobEdit
 TcxBlobEdit Object

Hierarchy          Properties          Methods          Events          See Also

Represents the BLOB editor.

Unit

cxBlobEdit

TcxBlobEdit = class(TcxCustomBlobEdit);

Description

The TcxBlobEdit object represents the BLOB (Binary Large Object) editor.  It can store and edit two data types: memo and image data.  When an editor is in memo mode, the editor dropdown window displays memo text.  When an editor is in picture mode, the editor dropdown window displays the stored image.  A BLOB editor allows a user to cut, copy and paste the data stored within an editor.  All these actions are accessed through the popup menu which appears when a user right-clicks within the editor dropdown window.

The appearance and the functionality of the BLOB editor can be accessed via the Use the style (the Style, StyleDisabled, StyleFocused and StyleHot) and Properties members.

The following image demonstrates the BLOB editor containing an image:


TcxBlobEdit Hierarchy
Hierarchy

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomPopupEdit

     |

TcxCustomBlobEdit

     |


Properties for TcxBlobEdit
TcxBlobEdit Properties

TcxBlobEdit          Legend

Derived from TcxCustomBlobEdit

ActiveProperties

Properties

Text

Derived from TcxCustomPopupEdit

ActiveProperties

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxBlobEdit
TcxBlobEdit Methods

TcxBlobEdit          Legend

Derived from TcxCustomPopupEdit

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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxBlobEdit
TcxBlobEdit Events

TcxBlobEdit          Legend

Derived from TcxCustomBlobEdit

OnGetGraphicClass

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxBlobEditProperties
TcxBlobEditProperties Object

Hierarchy          Properties          Methods          Events

Contains settings specific to BLOB editors.

Unit

cxBlobEdit

TcxBlobEditProperties = class(TcxCustomBlobEditProperties);

Description

The TcxBlobEditProperties class represents a set of attributes that control the behavior of BLOB editors.  Properties of an editor are set via the Properties member of the corresponding editor.  To control any changes made to the editor’s DisplayFormat, EditFormat, MaxLength, MaxValue, MinValue and ReadOnly properties and reverse their values back to the default ones, use the AssignedValues property.

The type of data stored within an editor is specified via the BlobEditKind property.  Other TcxBlobEditProperties members determine the manner in which the Enter and Tab keys are used within the dropdown window, the maximum number of characters which can be entered into an editor, the scrollbars displayed within the editor dropdown, specify the manner in which a picture is displayed within the editor dropdown window, the file type filter for "Open" and "Save As" dialogs etc.


TcxBlobEditProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |

TcxCustomDropDownEditProperties

     |

TcxCustomPopupEditProperties

     |

TcxCustomBlobEditProperties

     |


Properties for TcxBlobEditProperties
TcxBlobEditProperties Properties

TcxBlobEditProperties          Legend

Derived from TcxCustomBlobEditProperties

AlwaysSaveData

BlobEditKind

BlobPaintStyle

MemoAutoReplace

MemoCharCase

MemoMaxLength

MemoOEMConvert

MemoScrollBars

MemoWantReturns

MemoWantTabs

MemoWordWrap

PictureAutoSize

PictureClipboardFormat

PictureFilter

PictureGraphicClass

PictureGraphicClassName

PictureTransparency

ShowExPopupItems

ShowPicturePopup

Derived from TcxCustomPopupEditProperties

PopupControl

PopupSizeable

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

IncrementalSearch

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 TcxBlobEditProperties
TcxBlobEditProperties Methods

TcxBlobEditProperties          Legend

Derived from TcxCustomPopupEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults


Events for TcxBlobEditProperties
TcxBlobEditProperties Events

TcxBlobEditProperties          Legend

Derived from TcxCustomBlobEditProperties

OnAssignPicture

OnGetGraphicClass

Derived from TcxCustomDropDownEditProperties

OnCloseQuery

OnCloseUp

OnInitPopup

OnPopup

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomBlobEdit
TcxCustomBlobEdit Object

Hierarchy          Properties          Methods          Events

Represents the base class for the TcxBlobEdit and TcxDBBlobEdit objects.

Unit

cxBlobEdit

TcxCustomBlobEdit = class(TcxCustomPopupEdit);

Description

The TcxCustomBlobEdit class is the base class for the TcxBlobEdit, TcxDBBlobEdit classes and for user-defined classes representing an editor used for working with BLOB (Binary Large OBject) data.  It provides properties and methods defining the basic functionality of BLOB editors.

The BLOB editors are capable of storing and editing two data types: memo and image data.  The visual representation of the type of data stored within an editor is defined via the BlobPaintStyle property.  The type of edited data is determined via the BlobEditKind property.  This property value affects the entire editor functionality.


TcxCustomBlobEdit Hierarchy
Hierarchy

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomPopupEdit

     |


Properties for TcxCustomBlobEdit
TcxCustomBlobEdit Properties

TcxCustomBlobEdit          Legend

In TcxCustomBlobEdit

ActiveProperties

Properties

Text

Derived from TcxCustomPopupEdit

ActiveProperties

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading


Methods for TcxCustomBlobEdit
TcxCustomBlobEdit Methods

TcxCustomBlobEdit          Legend

Derived from TcxCustomPopupEdit

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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCustomBlobEdit
TcxCustomBlobEdit Events

TcxCustomBlobEdit          Legend

In TcxCustomBlobEdit

OnGetGraphicClass

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCustomBlobEdit.ActiveProperties

TcxCustomBlobEdit          See Also

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

property ActiveProperties: TcxCustomBlobEditProperties;

Description

Use the ActiveProperties property to obtain the properties of the current BLOB editor that are currently in effect.  This property is especially useful when the BLOB 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 BLOB editor.  Otherwise, the inherent BLOB editor’s properties are returned.

ReadOnly Property


TcxCustomBlobEdit.Properties

TcxCustomBlobEdit

Contains settings specific to BLOB editors.

property Properties: TcxCustomBlobEditProperties;

Description

Use the Properties property to set up the attributes specific to BLOB editors.  These properties are stored in the TcxCustomBlobEditProperties class.


TcxCustomBlobEdit.Text

TcxCustomBlobEditProperties

Specifies the text stored within a BLOB editor.

property Text: string;

Description

The Text property value specifies the text stored within a BLOB editor when it is in bekMemo mode.  This text (or its portion) is displayed within the BLOB editor edit region if the BlobPaintStyle property value is bpsText.


TcxCustomBlobEdit.OnGetGraphicClass

TcxCustomBlobEditProperties

Occurs when the graphic class of the image assigned to a BLOB editor in bekPict mode is being determined.

type

  TcxImageEditGraphicClassEvent = procedure(Sender: TObject; APastingFromClipboard: Boolean; var AGraphicClass: TGraphicClass) of object;

property OnGetGraphicClass: TcxImageEditGraphicClassEvent;

Description

Handle the OnGetGraphicClass event to specify the graphic class which describes the graphical data that will be stored within the BLOB editor in bekPict mode.  The APastingFromClipboard parameter indicates the condition at which the image is assigned and is equal to True when the image is pasted from the clipboard, and False in all other cases.  The AGraphicClass parameter specifies the graphic class assigned to the image.  This can be a non-registered graphic class (not a bitmap graphic, metafile graphic, icon, JPEG compressed image data).


TcxCustomBlobEditProperties
TcxCustomBlobEditProperties Object

Hierarchy          Properties          Methods          Events

Contains settings specific to BLOB editors.

Unit

cxBlobEdit

TcxCustomBlobEditProperties = class(TcxCustomPopupEditProperties);

Description

The TcxCustomBlobEditProperties class represents a set of attributes that control the behavior of the BLOB editors.  Properties of an editor are set via the Properties member of the corresponding editor.

The type of data stored within an editor is specified via the BlobEditKind property.  Other TcxBlobEditProperties members determine the manner in which the Enter and Tab keys are used within the dropdown window, the maximum number of characters which can be entered into an editor, the scrollbars displayed within the editor dropdown, specify the manner in which a picture is displayed within the editor dropdown window, the file type filter for "Open" and "Save As" dialogs etc.


TcxCustomBlobEditProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |

TcxCustomDropDownEditProperties

     |

TcxCustomPopupEditProperties

     |


Properties for TcxCustomBlobEditProperties
TcxCustomBlobEditProperties Properties

TcxCustomBlobEditProperties          Legend

In TcxCustomBlobEditProperties

AlwaysSaveData

BlobEditKind

BlobPaintStyle

MemoAutoReplace

MemoCharCase

MemoMaxLength

MemoOEMConvert

MemoScrollBars

MemoWantReturns

MemoWantTabs

MemoWordWrap

PictureAutoSize

PictureClipboardFormat

PictureFilter

PictureGraphicClass

PictureGraphicClassName

PictureTransparency

ShowExPopupItems

ShowPicturePopup

Derived from TcxCustomPopupEditProperties

PopupControl

PopupSizeable

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

IncrementalSearch

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 TcxCustomBlobEditProperties
TcxCustomBlobEditProperties Methods

TcxCustomBlobEditProperties          Legend

Derived from TcxCustomPopupEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults


Events for TcxCustomBlobEditProperties
TcxCustomBlobEditProperties Events

TcxCustomBlobEditProperties          Legend

In TcxCustomBlobEditProperties

OnAssignPicture

OnGetGraphicClass

Derived from TcxCustomDropDownEditProperties

OnCloseQuery

OnCloseUp

OnInitPopup

OnPopup

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomBlobEditProperties.AlwaysSaveData

TcxCustomBlobEditProperties

Determines whether the data entered into an editor is saved when the editor’s dropdown window is closed.

property AlwaysSaveData: Boolean;

Description

Use the AlwaysSaveData property to determine whether the data entered into the editor is saved when the editor loses focus or the editor dropdown window gets closed.  If this property value is False, then data entered into the editor is saved only when a user clicks the OK button within the editor dropdown window.

The default value of the AlwaysSaveData property is True.


TcxCustomBlobEditProperties.BlobEditKind

TcxCustomBlobEditProperties

Specifies the type of data contained within a BLOB editor.

type

  TcxBlobEditKind = (bekAuto, bekMemo, bekPict, bekOle, bekBlob);

property BlobEditKind: TcxBlobEditKind;

Description

Use the BlobEditKind property to specify the type of data stored within a BLOB editor.

Value	Meaning
bekAuto	Stored data type is obtained from the database field settings (for DB aware BLOB editors only).
bekMemo	Represents memo data.
bekPict	Represents an image.
bekOle	Represents OLE data.
bekBlob	Represents the BLOB data.

Each data type supported by the BLOB edit has its own visual representation within an editor (if the BlobPaintStyle property is set to bpsIcon value).  Data of the Memo and Image types can be edited via the BLOB editor initially, but the Blob and Ole data editing must be implemented by a user.  So the bekBlob and bekOle values are used only for visual representation purposes.

The default value of the BlobEditKind property is bekMemo.


TcxCustomBlobEditProperties.BlobPaintStyle

TcxCustomBlobEditProperties

Specifies the manner in which the type of data stored within the BLOB editor is labeled within the edit region.

type

  TcxBlobPaintStyle = (bpsDefault, bpsIcon, bpsText);

property BlobPaintStyle: TcxBlobPaintStyle;

Description

Use the BlobPaintStyle property to specify the manner in which the user is notified about the type of data stored within the BLOB editor.

Value	Picture	Meaning
bpsDefault		Identification text in braces is used: (picture) - for an image, (memo) - for a memo.
bpsIcon		Identification icon is used.
bpsText		Identification text is used (for the BLOB editor in memo mode this text is the part of the editor contents).

The default value of the BlobPaintStyle property is bpsIcon.


TcxCustomBlobEditProperties.MemoAutoReplace

TcxCustomBlobEditProperties

Determines whether the BLOB editor contents in memo mode are instantly replaced with the characters typed.

property MemoAutoReplace: Boolean

Description

The MemoAutoReplace property specifies whether the text contained within the BLOB editor in memo mode is instantly replaced with the characters typed.  This property affects characters typed only when the editor dropdown is closed.  If this property value is False, then the typed text is added to the BLOB editor contents.

The default value of the MemoAutoReplace property is False


TcxCustomBlobEditProperties.MemoCharCase

TcxCustomBlobEditProperties

Specifies the case conversion settings applied to the text entered into a BLOB editor in memo mode.

type

  TEditCharCase = (ecNormal, ecUpperCase, ecLowerCase);

property MemoCharCase: TEditCharCase;

Description

Use the MemoCharCase property to specify the case conversion settings for the BLOB editor in memo mode.  These settings are applied both to text entered by typing or pasting within the memo editor and to text specified via the EditValue property.

Value	Meaning
ecLowerCase	The memo text is converted to lower case.
ecNormal	No case conversion is performed.
ecUpperCase	The memo text is converted to upper case.

The default value of the MemoCharCase property is ecNormal.


TcxCustomBlobEditProperties.MemoMaxLength

TcxCustomBlobEditProperties

Specifies the maximum number of characters which can be entered into a BLOB editor in memo mode.

property MemoMaxLength: Integer;

Description

Use the MemoMaxLength property to specify the maximum number of characters which can be entered into a BLOB editor in memo mode.  The default value of this property specifies that there is no limit to the number of characters which can be stored.

The default value of the MemoMaxLength property is 0.


TcxCustomBlobEditProperties.MemoOEMConvert

TcxCustomBlobEditProperties

Determines whether characters entered into a BLOB editor in memo mode are converted from ANSI to OEM and then back.

property MemoOEMConvert: Boolean;

Description

To ensure that all characters typed into an in-place editor can be converted to the OEM character set, set this property to True.  This converts all characters from ANSI to OEM and then back to ANSI.  Set the MemoOEMConvert property to False to avoid mapping to the OEM format.  This property is most useful when editors are used to enter file names for applications not using Unicode file names.

The default value of the MemoOEMConvert property is False.


TcxCustomBlobEditProperties.MemoScrollBars

TcxCustomBlobEditProperties

Specifies which scrollbars are displayed within the BLOB editor dropdown window.

type

  TScrollStyle = (ssNone, ssHorizontal, ssVertical, ssBoth);

property MemoScrollBars: TScrollStyle;

Description

Use the MemoScrollBars property to specify the BLOB editor dropdown scrollbars.

Value	Meaning
ssBoth	The horizontal and vertical scrollbars are displayed.
ssHorizontal	The horizontal scrollbar is displayed. If this option is active, then MemoWordWrap property is not in effect.
ssNone	There are no scrollbars within the BLOB editor dropdown.
ssVertical	The vertical scrollbar is displayed.

The default value of the MemoScrollBars property is ssNone.


TcxCustomBlobEditProperties.MemoWantReturns

TcxCustomBlobEditProperties

Determines whether the Enter key inserts a carriage return into the entered text.

property MemoWantReturns: Boolean;

Description

Use the MemoWantReturns property to determine whether the BLOB editor accepts carrige returns during text input.  If this property value is True, then the Enter key is used to insert the carrige returns into the BLOB editor in memo mode.  Otherwise, the Enter key is used to submit changes made to the editor contents and to close the dropdown window (to submit changes made to the editor contents when the MemoWantsReturns property value is True use the Ctrl+Enter keys combination).

The default value of the MemoWantReturns property is True.


TcxCustomBlobEditProperties.MemoWantTabs

TcxCustomBlobEditProperties

Determines whether the TAB character can be inserted into a BLOB editor in memo mode.

property MemoWantTabs: Boolean;

Description

Use the MemoWantsTabs property to determine whether a BLOB editor can accept the TAB character during text input.  If this property value is True, then the pressing the Tab key inserts the TAB character into the BLOB editor in memo mode.  If this property value is False, then pressing the Tab key removes the focus from the BLOB editor dropdown.

The default value of the MemoWantTabs property is True.


TcxCustomBlobEditProperties.MemoWordWrap

TcxCustomBlobEditProperties

Determines whether text entered into a BLOB editor in memo mode is wrapped at the right margin.

property MemoWordWrap: Boolean;

Description

Use the MemoWordWrap property to determine whether text entered into a BLOB editor in memo mode is wrapped.  Setting this property to False value forces the BLOB editor to display text in a single line until the carriage return is entered.

Note: this property is not in effect if the BLOB editor dropdown has a horizontal scrollbar.

The default value of the MemoWordWrap property is True.


TcxCustomBlobEditProperties.PictureAutoSize

TcxCustomBlobEditProperties

Determines whether the BLOB editor dropdown window is resized according to the picture size.

property PictureAutoSize: Boolean;

Description

Use the PictureAutoSize property to determine whether the BLOB editor dropdown should be resized when a picture is stored within it.  If this property value is True, then the dropdown is resized in order to display the stored picture at a 1:1 scale.  Otherwise, the picture is scaled according to the dropdown window size.

The default value of the PictureAutoSize property is True.


TcxCustomBlobEditProperties.PictureClipboardFormat

TcxCustomBlobEditProperties

Specifies the format in which graphical data is stored within the clipboard.

property PictureClipboardFormat: Word;

Description

Use the PictureClipboardFormat property to specify the format in which graphical data is stored within the clipboard.  Some of the possible values of the PictureClipboardFormat property follow.

Value	Meaning
CF_BITMAP	A Windows bitmap graphic.
CF_METAFILEPICT	A Windows metafile graphic.
CF_PICTURE	A TPicture type object.


TcxCustomBlobEditProperties.PictureFilter

TcxCustomBlobEditProperties

Specifies the file type filter applied to "Open" and "Save As" picture dialogs of the BLOB editor.

property PictureFilter: string;

Description

Use the PictureFilter property to specify the file type filter applied to the "Open" and "Save As" picture dialogs of a BLOB editor.  The filter string can contain wildcards.  An example of a file type filter string is shown below:

  cxBlobEdit1.Properties.PictureFilter := 'Windows Meta Files(*.wmf)|*.wmf';

If the PictureFilter property value is an empty string, then the BLOB editor dialog displays the files of all allowed types.  BLOB editors are capable of displaying the following graphic files types: icons (*.ICO), bitmaps (*.BMP), windows metafiles and enhanced metafiles (*.WMF, *.EMF) and JPEG images (*.JPG, *.JPEG).


TcxCustomBlobEditProperties.PictureGraphicClass

TcxCustomBlobEditProperties          See Also

Specifies the custom graphic class describing data stored within a BLOB editor.

property PictureGraphicClass: TGraphicClass;

Description

Use the PictureGraphicClass property to specify the custom graphic class representing graphical data displayed within a BLOB editor.  Unlike the PictureGraphicClassName property, this property can be assigned to a non-registered graphic class.


TcxCustomBlobEditProperties.PictureGraphicClassName

TcxCustomBlobEditProperties          See Also

Specifies the name of the custom graphic class describing data stored within a BLOB editor.

property PictureGraphicClassName: string;

Description

Use the PictureGraphicClassName property to specify the name of the graphic class representing graphical data displayed within a BLOB editor.  Unlike the PictureGraphicClass property, this property must be assigned the registered graphic class name.  Otherwise, it is not in effect.


TcxCustomBlobEditProperties.PictureTransparency

TcxCustomBlobEditProperties

Specifies the background transparency for an image within a BLOB editor.

type

  TcxImageTransparency = (gtDefault, gtOpaque, gtTransparent);

property PictureTransparency: TcxImageTransparency;

Description

Use the GraphicTransparency property to specify the background transparency settings for the image editor.

Value	Meaning
gtDefault	Background transparency settings are obtained from the image itself (transparent for metafiles and icons, opaque for bitmaps).
gtOpaque	Background transparency is set to opaque.
gtTransparent	Background transparency is set to transparent.

The default value of the PictureTransparency property is gtDefault.


TcxCustomBlobEditProperties.ShowExPopupItems

TcxCustomBlobEditProperties

Determines whether two additional items are displayed within the picture popup menu of the BLOB editor dropdown window.

property ShowExPopupItems: Boolean;

Description

Use the ShowExPopupItems property to determine whether to display the additional items within the picture popup menu.  These items are "Load…" and "SaveTo…".  If this property value is False, then the popup menu displays only standard items:

The following image demonstrates a BLOB editor in bekPict mode with an activated popup menu containing additional items:

The default value of the ShowExPopupItems property is True.


TcxCustomBlobEditProperties.ShowPicturePopup

TcxCustomBlobEditProperties

Determines whether the BLOB editor popup menu is displayed.

property ShowPicturePopup: Boolean;

Description

Use the ShowPicturePopup property to determine whether the BLOB editor popup menu is displayed.  If this property value is False, then the popup menu is not displayed when a user right-clicks within the BLOB editor dropdown window.  Otherwise, the popup menu is displayed.  The appearance of that menu depends on the BlobEditKind property value.

The default value of the ShowPicturePopup property is True.


TcxCustomBlobEditProperties.OnAssignPicture

TcxCustomBlobEditProperties

Occurs before posting the graphical data to an editor.

type

  TcxImageAssignPictureEvent = procedure(Sender: TObject; const Picture: TPicture) of object;

property OnAssignPicture: TcxImageAssignPictureEvent;

Description

Write an OnAssignPicture event handler to process posting of the graphical data to an editor.  The Sender parameter identifies an editor where posting occurs.  The Picture parameter identifies an instance of the TPicture class or its descendant representing an image posted to the editor.


TcxCustomBlobEditProperties.OnGetGraphicClass

TcxCustomBlobEditProperties

Occurs when the graphic class of the image assigned to a BLOB editor, which is used as an in-place editor, is being determined.

type

  TcxImageGraphicClassEvent = procedure(AItem: TObject; ARecordIndex: Integer; APastingFromClipboard: Boolean; var AGraphicClass: TGraphicClass) of object;

property OnGetGraphicClass: TcxImageGraphicClassEvent;

Description

This event is fired whenever the graphic class of the graphical data which is assigned to a BLOB editor is determined, i.e. when the Properties.PictureGraphicClass property value is not set.  The OnGetGraphicClass event is useful when the editor is used as an in-place editor (in a grid control, for example) and should display graphical data of various types.  You can set specific graphic class for each data record (represented by its index) and the item in this record (a column or row) for which the BLOB editor is displayed, which are represented by the ARecordIndex and AItem parameters correspondingly.  The APastingFromClipboard parameter is equal to True when the image assigned to the editor is pasted from the clipboard and False in all other cases.  The AGraphicClass parameter specifies the graphic class assigned to the image.  This can be a non-registered graphic class (not a bitmap graphic, metafile graphic, icon, JPEG compressed image data).


TcxDBBlobEdit
 TcxDBBlobEdit Object

Hierarchy          Properties          Methods          Events          See Also

Represents a data-aware control used for displaying and editing BLOB data from a data source.

Unit

cxDBEdit

TcxDBBlobEdit = class(TcxCustomBlobEdit);

Description

The TcxDBBlobEdit class represents a control used for working with BLOB (Binary Large OBject) data obtained from a data source.  The BLOB editors are capable of storing and editing two data types: memo and image data.  The visual representation of the type of data stored within an editor is defined via the BlobPaintStyle property.  The type of edited data is determined via the BlobEditKind property.  This property value affects the entire editor functionality.

Since the BLOB data is just a sequence of bytes, the BLOB editor needs exact instructions about data interpretation.  For instance, if the BLOB editor is connected to a data source field containing graphic data, then the BlobEditKind property must be set to bekPict.


TcxDBBlobEdit Hierarchy
Hierarchy

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomPopupEdit

     |

TcxCustomBlobEdit

     |


Properties for TcxDBBlobEdit
TcxDBBlobEdit Properties

TcxDBBlobEdit          Legend

In TcxDBBlobEdit

DataBinding

Derived from TcxCustomBlobEdit

ActiveProperties

Properties

Text

Derived from TcxCustomPopupEdit

ActiveProperties

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxDBBlobEdit
TcxDBBlobEdit Methods

TcxDBBlobEdit          Legend

Derived from TcxCustomPopupEdit

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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxDBBlobEdit
TcxDBBlobEdit Events

TcxDBBlobEdit          Legend

Derived from TcxCustomBlobEditProperties

OnGetGraphicClass

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxDBBlobEdit.DataBinding

TcxDBBlobEdit

Specifies an object binding an editor to a data source.

property DataBinding: TcxDBEditDataBinding;

Description

Use the DataBinding property to access a TcxDBEditDataBinding instance establishing a connection between a BLOB editor and a data source.  Use the TcxDBEditDataBinding.DataSource and TcxDBEditDataBinding.DataField properties to specify the data source and the data source field whose values are to be displayed within a BLOB editor.

Since the BLOB data is just a sequence of bytes, the BLOB editor needs exact instructions about data interpretation.  For instance, if the BLOB editor is connected to a data source field containing graphic data, then the BlobEditKind property must be set to bekPict.


imgBlobImages variable
imgBlobImages global variable

Specifies the TImageList object containing the list of images representing the different BLOB editor states.

Unit

cxBlobEdit

imgBlobImages : TImageList = nil;

Description

Use the imgBlobImages variable to specify a TImageList object instance containing images representing different BLOB editors states.

Picture	Meaning
	Represents a BLOB editor in memo mode when the editor contains no text
	Represents a BLOB editor in memo mode containing text
	Represents a BLOB editor in picture mode when the editor contains no image
	Represents a BLOB editor in picture mode containing image


SBlobButtonCancel variable
SBlobButtonCancel global variable

Specifies the Cancel button caption.

Unit

cxBlobEdit

SBlobButtonCancel : string = cxSBlobButtonCancel;

Description

Use the SBlobButtonCancel variable to specify the caption of the BLOB editor button used for rejecting input.


SBlobButtonClose variable
SBlobButtonClose global variable

Specifies the Close button caption.

Unit

cxBlobEdit

SBlobButtonClose : string = cxSBlobButtonClose;

Description

Use the SBlobButtonClose variable to specify the caption of the BLOB editor button used for closing the editor dropdown window.


SBlobButtonOK variable
SBlobButtonOK global variable

Specifies the OK button caption.

Unit

cxBlobEdit

SBlobButtonOK : string = cxSBlobButtonOK;

Description

Use the SBlobButtonOK variable to specify the caption of the BLOB editor button used for confirming input.


cxButtonEdit Unit Overview
cxButtonEdit Unit

Classes

TcxButtonEdit

TcxButtonEditProperties

TcxCustomButtonEdit

TcxCustomButtonEditProperties


TcxButtonEdit
 TcxButtonEdit Object

Hierarchy          Properties          Methods          Events           See Also

Represents an edit control with embedded buttons.

Unit

cxButtonEdit

TcxButtonEdit = class(TcxCustomButtonEdit);

Description

The TcxButtonEdit class represents an editor which allows the displaying of a number of buttons within its client area.

The collection of buttons is accessible via the Buttons property of the Properties member.  Similar to other ExpressEditors, the TcxButtonEdit class allows managing various attributes (such as text alignment, the mask for entering values, the auto select feature, etc.) via the Properties property.

Use the Style, StyleDisabled, StyleFocused and StyleHot properties to adjust the look & feel of an editor in various control’s states.


TcxButtonEdit Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomButtonEdit

     |


Properties for TcxButtonEdit
TcxButtonEdit Properties

TcxButtonEdit          Legend

In TcxButtonEdit

Text

Derived from TcxCustomButtonEdit

ActiveProperties

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxButtonEdit
TcxButtonEdit Methods

TcxButtonEdit          Legend

Derived from TcxCustomMaskEdit

CutToClipboard

PasteFromClipboard

Derived from TcxCustomTextEdit

Clear

ClearSelection

CopyToClipboard

Create

SelectAll

SetSelection

Undo

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Create

CreateInnerEdit

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SetSize

ValidateEdit


Events for TcxButtonEdit
TcxButtonEdit Events

TcxButtonEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxButtonEdit.Text

TcxButtonEdit

Determines the text displayed within an editor.

property Text: TCaption;

Description

Use the Text property to specify the text displayed within the TcxButtonEdit editor.


TcxButtonEditProperties
TcxButtonEditProperties Object

Hierarchy          Properties          Methods          Events         See also

Contains settings specific to button editors.

Unit

cxButtonEdit

TcxButtonEditProperties = class(TcxCustomButtonEditProperties);

Description

The TcxButtonEditProperties class represents a set of attributes which control the behavior of button editors.  Editor properties are set via the Properties member of the corresponding editor.  To control any changes made to the editor’s DisplayFormat, EditFormat, MaxLength, MaxValue, MinValue and ReadOnly properties and reverse their values back to the default ones, use the AssignedValues property.  The TcxButtonEditProperties class simply publishes the necessary inherited properties and events.  The TcxButtonEdit control represents a button editor itself.


TcxButtonEditProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |

TcxCustomButtonEditProperties

     |


Properties for TcxButtonEditProperties
TcxButtonEditProperties Properties

TcxButtonEditProperties          Legend

Derived from TcxCustomMaskEditProperties

AlwaysShowBlanksAndLiterals

CaseInsensitive

EditMask

IgnoreMaskBlank

IsMasked

MaskKind

Derived from TcxCustomTextEditProperties

AssignedValues

CharCase

DisplayFormat

EchoMode

EditFormat

HideCursor

HideSelection

ImeMode

ImeName

IncrementalSearch

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 TcxButtonEditProperties
TcxButtonEditProperties Methods

TcxButtonEditProperties          Legend

Derived from TcxCustomMaskEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomTextEditProperties

IsDisplayValueValid

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue


Events for TcxButtonEditProperties
TcxButtonEditProperties Events

TcxButtonEditProperties          Legend

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomButtonEdit
TcxCustomButtonEdit Object

Hierarchy          Properties          Methods           Events         See also

Represents the base class for controls with embedded buttons.

Unit

cxButtonEdit

TcxCustomButtonEdit = class(TcxCustomMaskEdit);

Description

The TcxCustomButtonEdit class is the base class for editors which display buttons within their client area.  Do not create instances of the TcxCustomButtonEdit class, use its descendants instead.  The TcxButtonEdit class publishes various members of TcxCustomButtonEdit so that a user can work with a button editor.


TcxCustomButtonEdit Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |


Properties for TcxCustomButtonEdit
TcxCustomButtonEdit Properties

TcxCustomButtonEdit          Legend

In TcxCustomButtonEdit

ActiveProperties

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading


Methods for TcxCustomButtonEdit
TcxCustomButtonEdit Methods

TcxCustomButtonEdit          Legend

Derived from TcxCustomMaskEdit

CutToClipboard

PasteFromClipboard

Derived from TcxCustomTextEdit

Clear

ClearSelection

CopyToClipboard

Create

SelectAll

SetSelection

Undo

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Create

CreateInnerEdit

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SetSize

ValidateEdit


Events for TcxCustomButtonEdit
TcxCustomButtonEdit Events

TcxCustomButtonEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCustomButtonEdit.ActiveProperties

TcxCustomButtonEdit           See Also

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

property ActiveProperties: TcxCustomButtonEditProperties;

Description

Use the ActiveProperties property to obtain the properties of the current button editor that are currently in effect.  This property is especially useful when the button 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 button editor.  Otherwise, the inherent button editor’s properties are returned.

ReadOnly Property


TcxCustomButtonEdit.Properties

TcxCustomButtonEdit           See Also

Defines settings specific to a button editor.

property Properties: TcxCustomButtonEditProperties;

Description

Use Properties to set specific attributes which control the editor behavior.  They define the alignment of the editor’s contents, the collection of buttons that can be displayed within it, the read-only status, etc.  Properties specific to button editors are stored in the TcxCustomButtonEditProperties class.


TcxCustomButtonEditProperties
  TcxCustomButtonEditProperties Object

Hierarchy          Properties          Methods           Events         See also

Contains settings specific to button edit controls.

Unit

cxButtonEdit

TcxCustomButtonEditProperties = class(TcxCustomMaskEditProperties);

Description

The TcxCustomButtonEditProperties class represents a set of attributes controlling the behavior of button editors.  Editor properties are set via the Properties member of the TcxCustomButtonEdit editor.


TcxCustomButtonEditProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |


Properties for TcxCustomButtonEditProperties
TcxCustomButtonEditProperties Properties

TcxCustomButtonEditProperties          Legend

Derived from TcxCustomMaskEditProperties

AlwaysShowBlanksAndLiterals

CaseInsensitive

EditMask

IgnoreMaskBlank

IsMasked

MaskKind

Derived from TcxCustomTextEditProperties

AssignedValues

CharCase

DisplayFormat

EchoMode

EditFormat

HideCursor

HideSelection

ImeMode

ImeName

IncrementalSearch

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 TcxCustomButtonEditProperties
TcxCustomButtonEditProperties Methods

TcxCustomButtonEditProperties          Legend

Derived from TcxCustomMaskEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomTextEditProperties

IsDisplayValueValid

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue


Events for TcxCustomButtonEditProperties
TcxCustomButtonEditProperties Events

TcxCustomButtonEditProperties          Legend

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


cxButtons Unit Overview
cxButtons Unit

Classes

TcxButton

TcxButtonColors

TcxCustomButton


TcxButton
 TcxButton Object

Hierarchy          Properties          Events

Represents an enhanced variant of the TButton component.

Unit

cxButtons

TcxButton = class(TcxCustomButton);

Description

The TcxButton object represents an enhanced variant of TButton.  It does not provide any other functionality than that defined in the TcxCustomButton class.

TcxButton works in three different modes, defined via the Kind property.  In standard mode TcxButton functions as a regular button.  If the Kind property value is set to the cxbkDropDown or cxbkDropDownButton value and the DropDownMenu property is assigned a TPopupMenu instance, clicking a button (or the dropdown button located at the right side of this button) results in opening the specified popup menu.  When in cxbkDropDown mode, TcxButton does not generate an OnClick event when a user presses it.  Instead, the OnPopup event of an appropriate TPopupMenu must be handled to respond to user actions.

The look & feel of a button can be specified via the LookAndFeel property.  The LookAndFeel.NativeStyle property determines whether a button is painted in the XP theme.  The LookAndFeel.Kind property specifies the borders, colors and highlighting settings applied to a button.

The following image demonstrates the TcxButton instance with the LookAndFeel.NativeStyle property set to True:


TcxButton Hierarchy
Hierarchy

TButton

     |

TcxCustomButton

     |


Properties for TcxButton
TcxButton Properties

TcxButton          Legend

Derived from TcxCustomButton

Colors

DropDownMenu

Glyph

Kind

Layout

LookAndFeel

Margin

NumGlyphs

PopupAlignment

Spacing

UseSystemPaint


Events for TcxButton
TcxButton Events

TcxButton          Legend

Derived from TcxCustomButton

OnDropDownMenuPopup


TcxButtonColors
TcxButtonColors Object

Hierarchy          Properties          See Also

Contains a list of colors, representing different button states.

Unit

cxButtons

TcxButtonColors = class(TPersistent)

Description

The state of a TcxButton control can be represented in two manners: by assigning images corresponding to different states using the button’s Glyph property and/or by specifying background colors via the button’s Colors property.

The TcxButtonColors class provides access to the list of colors associated with button states.

You can use the Colors property to designate colors for different button states.

The Colors property represents an object of the TcxButtonColors class.  It allows you to designate colors for different button states (normal, disabled, hot-tracked, pressed and when your button is Default).

When a button is painted in the XP scheme, the Colors property settings are not in effect.  The XP style is applied to a button when:

1.	The button’s LookAndFeel.NativeStyle property is set to True.

2.	The button’s LookAndFeel.Kind property is set to lfStandard and the UseSystemPaint property is set to True.


TcxButtonColors Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxButtonColors
TcxButtonColors Properties

TcxButtonColors          Legend

In TcxButtonColors

AssignedColors

Default

Disabled

Hot

Normal

Pressed


TcxButtonColors.AssignedColors

TcxButtonColors

Specifies which button states have their corresponding color assigned by the Colors property.

type

  TcxButtonState = (cxbsDefault, cxbsNormal, cxbsHot, cxbsPressed, cxbsDisabled);

  TcxButtonAssignedColors = set of TcxButtonState;

property AssignedColors: TcxButtonAssignedColors;

Description

The AssignedColors property contains a set of flags defining which button states have corresponding colors assigned by the Colors property.

Specifying a color for a specific button state results in activating the corresponding flag in the AssignedColors set.  If a flag is deactivated, the corresponding Colors property member is set to clDefault.

Setting the background color for a specific state to clDefault enables painting based on the LookAndFeel and UseSystemPaint property settings.


TcxButtonColors.Default

TcxButtonColors          See Also

Specifies the background color representing the normal state of a button when its Default property is set to True.

property Default: TColor;

Description

Use the Default property to specify the background color representing the normal state of a button when its Default property is set to True.

If this property value is not assigned, the button background is painted based on the Normal or the LookAndFeel and UseSystemPaint property settings.

The default property value (clDefault) specifies that the button’s background color is provided by the LookAndFeel and UseSystemPaint property settings.  If this property value is other than default, the corresponding flag is activated in AssignedColors.  Deactivating this flag sets the property to its default value.

You can also specify colors for the following cxButton states: Disabled, Hot, Normal and Pressed.

When a button is painted in the XP scheme, the Colors property settings are not in effect.  The XP style is applied to a button when:

1.	The button’s LookAndFeel.NativeStyle property is set to True.

2.	The button’s LookAndFeel.Kind property is set to lfStandard and the UseSystemPaint property is set to True.


TcxButtonColors.Disabled

TcxButtonColors          See Also

Specifies the background color for a disabled button.

property Disabled: TColor;

Description

Use the Disabled property to specify the background color for a button when its Enabled property is set to False.

If this property value is not assigned, the button background is painted based on the Normal or the LookAndFeel and UseSystemPaint property settings.

The default property value (clDefault) specifies that the background color of a button is provided by the LookAndFeel and UseSystemPaint property settings.  If this property value is other than default, the corresponding flag is activated in AssignedColors.  Deactivating this flag sets the property to its default value.

You can also specify colors for the following cxButton states: Default, Hot, Normal and Pressed.

When a button is painted in the XP scheme, the Colors property settings are not in effect.  The XP style is applied to a button when:

1.	The button’s LookAndFeel.NativeStyle property is set to True.

2.	The button’s LookAndFeel.Kind property is set to lfStandard and the UseSystemPaint property is set to True.


TcxButtonColors.Hot

TcxButtonColors          See Also

Specifies the background color for a button when the mouse pointer is positioned over it.

property Hot: TColor;

Description

If this property value is not assigned, the button background is painted based on the Normal or the LookAndFeel and UseSystemPaint property settings.

The default property value (clDefault) specifies that the background color of a button is provided by the LookAndFeel and UseSystemPaint property settings.  If this property value is other than default, the corresponding flag is activated in AssignedColors.  Deactivating this flag sets the property to its default value.

You can also specify colors for the following cxButton states: Default, Disabled, Normal and Pressed.

When a button is painted in the XP scheme, the Colors property settings are not in effect.  The XP style is applied to a button when:

1.	The button’s LookAndFeel.NativeStyle property is set to True.

2.	The button’s LookAndFeel.Kind property is set to lfStandard and the UseSystemPaint property is set to True.


TcxButtonColors.Normal

TcxButtonColors          See Also

Specifies the background color representing the normal state of a button when its Default property is set to False.

property Normal: TColor;

Description

Use the Normal property to specify the background color representing the normal state of a button when its Default property is set to False.

If this property value is not assigned, the button background is painted based on the Default or the LookAndFeel and UseSystemPaint property settings.

The default property value (clDefault) specifies that the background color of a button is provided by the LookAndFeel and UseSystemPaint property settings.  If this property value is other than default, the corresponding flag is activated in AssignedColors.  Deactivating this flag sets the property to its default value.

You can also specify colors for the following cxButton states: Default, Disabled, Hot and Pressed.

When a button is painted in the XP scheme, the Colors property settings are not in effect. The XP style is applied to a button when:

1.	The button’s LookAndFeel.NativeStyle property is set to True.

2.	The button’s LookAndFeel.Kind property is set to lfStandard and the UseSystemPaint property is set to True.


TcxButtonColors.Pressed

TcxButtonColors          See Also

Specifies the background color for a pressed button.

property Pressed: TColor;

Description

Use the Pressed property to specify the background color for a pressed button.

If this property value is not assigned, the button background is painted based on the Normal or the LookAndFeel and UseSystemPaint property settings.

The default property value (clDefault) specifies that the background color of a button is provided by the LookAndFeel and UseSystemPaint property settings.  If this property value is other than default, the corresponding flag is activated in AssignedColors.  Deactivating this flag sets the property to its default value.

You can also specify colors for the following cxButton states: Default, Disabled, Hot and Normal.

When a button is painted in the XP scheme, the Colors property settings are not in effect.  The XP style is applied to a button when:

1.	The button’s LookAndFeel.NativeStyle property is set to True.

2.	The button’s LookAndFeel.Kind property is set to lfStandard and the UseSystemPaint property is set to True.


TcxCustomButton
TcxCustomButton Object

Hierarchy          Properties          Events

Represents an enhanced variant of the TButton component.

Unit

cxButtons

TcxCustomButton = class(TButton);

Description

The TcxCustomButton object represents an enhanced variant of TButton.  TcxCustomButton works in three different modes, defined via the Kind property.  In standard mode, the TcxCustomButton functions as a regular button.  If the Kind property value is set to the cxbkDropDown or cxbkDropDownButton value and the DropDownMenu property is assigned a TPopupMenu instance, clicking a button (or the dropdown button located at the right side of this button) results in opening the specified popup menu.  When in cxbkDropDown mode, TcxCustomButton does not generate an OnClick event when a user presses it.  Instead, the OnPopup event of an appropriate TPopupMenu must be handled to respond to user actions.

The look & feel of a button can be specified via the LookAndFeel property.  The LookAndFeel.NativeStyle property determines whether a button is painted in the XP theme.  The LookAndFeel.Kind property specifies the borders, colors and highlighting settings applied to a button.


TcxCustomButton Hierarchy
Hierarchy

TButton

     |


Properties for TcxCustomButton
TcxCustomButton Properties

TcxCustomButton          Legend

In TcxCustomButton

Colors

DropDownMenu

Glyph

Kind

Layout

LookAndFeel

Margin

NumGlyphs

PopupAlignment

Spacing

UseSystemPaint


Events for TcxCustomButton
TcxCustomButton Events

TcxCustomButton          Legend

In TcxCustomButton

 OnDropDownMenuPopup


TcxCustomButton.DropDownMenu

TcxCustomButton           See also

Identifies a TPopupMenu instance used as a dropdown menu for a specific ExpressButton.

property DropDownMenu: TPopupMenu;

Description

Use the DropDownMenu property to identify a TPopupMenu instance used as a dropdown menu for a specific ExpressButton.  To incorporate a dropdown menu, the Kind property of a specific button must be set to cxbkDropDown or cxbkDropDownButton.  The specified menu appears when a user clicks a button (or the dropdown button located at the right side of this button).

Handle the OnDropDownMenuPopup event to specify the dropdown menu at run time.


TcxCustomButton.Colors

TcxCustomButton          See Also

Contains a list of colors, representing different button states.

property Colors: TcxButtonColors;

Description

Use the Colors property to specify the color used for painting a button’s background, based on the button state: default, normal, disabled, hot tracked and pressed.

Another way to distinguish different button states is to use the Glyph property.

When a button is painted in the XP scheme, the Colors property settings are not in effect.  The XP style is applied to a button when:

1.	The button’s LookAndFeel.NativeStyle property is set to True.

2.	The button’s LookAndFeel.Kind property is set to lfStandard and the UseSystemPaint property is set to True.


TcxCustomButton.Glyph

TcxCustomButton          See Also

Specifies the image displayed within a button.

property Glyph: TBitmap;

Description

Use this property to specify the bitmap displayed within a button.  The Layout property defines the image position within a button.  The distance (in pixels) between the Glyph image and the button's Caption is specified by the Spacing property.

The Glyph bitmap can be subdivided into 4 equal parts arranged in a single row.  Each image portion corresponds to a specific button state:

Image position	Button state	Description
First	Up	Appears when the button is up (unselected). This image is also used when the button has focus (for example, if a user tabs to it); in this case, a focus rectangle is drawn around the button. If no other images exist in the bitmap, bit buttons also use this image for all other states.
Second	Disabled	Usually appears dimmed to indicate that the button can't be selected.
Third	Clicked	Appears when the button is clicked. The Up image reappears when a user releases the mouse button.
Fourth	Down	Appears when the button remains down (indicating that it is left selected).

The number of parts to divide the Glyph bitmap is specified by the NumGlyphs property.  The following screenshot demonstrates a sample bitmap:

Note:	The lower left pixel of the bitmap is reserved for the "transparent" color. Any pixel in the bitmap matching that lower left pixel will be transparent.


TcxCustomButton.Kind

TcxCustomButton

Specifies button behavior.

type

  TcxButtonKind = (cxbkStandard, cxbkDropDown, cxbkDropDownButton);

property Kind: TcxButtonKind;

Description

Use the Kind property to specify button behavior.  If this property value is default (cxbkStandard), the ExpressButton functions as a standard button.  If the Kind property is set to the cxbkDropDown or cxbkDropDownButton value, the dropdown menu specified via the DropDownMenu property appears when a user clicks a button (or the dropdown button located at the right side of this button).  The horizontal position of the dropdown menu is controlled by the PopupAlignment property.

Value	Button Appearance	Meaning
cxbkStandard		Button behavior does not differ from TButton..
cxbkDropDown		The dropdown menu appears when a user presses a button.  The OnPopup event of the appropriate TPopupMenu must be handled instead of OnClick.
cxbkDropDownButton		The dropdown menu appears when a user presses the dropdown button located at the right of the button.

The default value of the Kind property is cxbkStandard.


TcxCustomButton.Layout

TcxCustomButton          See Also

Specifies the location of an image within a button.

type

  TButtonLayout = (blGlyphLeft, blGlyphRight, blGlyphTop, blGlyphBottom);

property Layout: TButtonLayout;

Description

Use the Glyph property to specify the bitmap displayed within a button.

The Layout property determines the image position within a button:

Layout settings	Image Position
blGlyphLeft
blGlyphRight
blGlyphTop
blGlyphBottom

The default value of the Layout property is blGlyphLeft.


TcxCustomButton.LookAndFeel

TcxCustomButton

Specifies look & feel options for a button.

property LookAndFeel: TcxLookAndFeel;

Description

Use the LookAndFeel property to define look & feel options for a button.  The LookAndFeel.NativeStyle property determines whether a button is painted in the XP theme.  The LookAndFeel.Kind property specifies the borders, colors and highlighting settings applied to your button.


TcxCustomButton.Margin

TcxCustomButton          See Also

Specifies the number of pixels between the edge of the image, specified by the Glyph property, and the button edge.

property Margin: Integer;

Description

The margin is the space separating a Glyph image and the button edge along which a bitmap is aligned.  The margin location depends on the Layout property value.  For instance, if Layout is set to blGlyphLeft, the Margin property specifies the space between the left edge of the Glyph and a button.

The following screenshots demonstrate how Margin controls the space between a glyph and a button edge when different layouts are applied:

Layout settings	Margin position
blGlyphLeft
blGlyphTop

The default value of this property (–1) specifies that the button’s Caption and the Glyph image are centered within a button.  In this case, the number of pixels between the Glyph edge and the button edge is equal to the number of pixels between the button’s Caption and the opposite button edge.

The default value of the Margin property is -1.


TcxCustomButton.NumGlyphs

TcxCustomButton          See Also

Specifies the number of images included in the Glyph property.

property NumGlyphs: TNumGlyphs;

Description

You can use the Glyph property to set a bitmap to display within a button.

The bitmap specified by the Glyph property can be divided into several parts.  Each image portion corresponds to a specific button state.

The number of portions in a Glyph bitmap is specified by the NumGlyphs property.

The default value of the NumGlyphs property is 1.


TcxCustomButton.PopupAlignment

TcxCustomButton

Specifies the manner in which the dropdown menu is aligned relative to the button.

property PopupAlignment: TPopupAlignment;

Description

Use the PopupAlignment property to specify the horizontal placement of the dropdown menu specified via the DropDownMenu property relative to the button.  The dropdown menu can be aligned either to its left edge, right edge or centered.  See the TPopupAlignment type description in Delphi (C++ Builder) documentation for more information on the available values.  The table below shows how property values affect the appearance of the dropdown menu for the TcxButton control.  The button’s Kind property is set to cxbkDropDown.

Value	Dropdown Menu Appearance
paLeft
paRight
paCenter

The default value of the PopupAlignment property is paLeft.


TcxCustomButton.Spacing

TcxCustomButton          See Also

Specifies the distance in pixels between a Glyph image and the button's Caption text.

property Spacing: Integer;

Description

Use this property to specify the distance between an image and the text within a button.

If this property’s value is 0, then no pixels are between the text and the image.  Setting the Spacing property value to -1 centers the text between the image and the opposite button edge:

The default value of the Spacing property is 4.


TcxCustomButton.UseSystemPaint

TcxCustomButton

This property is obsolete. The manner in which the button is painted is specified using the LookAndFeel property.

property UseSystemPaint: Boolean;

Description

In previous versions of the Express Editors library, the UseSystemPaint property was used to specify whether the button should be painted in the same manner as the standard button control.  It only had effect when no image was assigned to the button, the LookAndFeel.Kind property was set to cxbkStandard and the LookAndFeel.NativeStyle property was set to True.

Now, the UseSystemPaint property has the same effect but its value cannot be set at design-time.  Additionally, dropping a TcxButton control onto the form will set the UseSystemPaint property value for all previously created buttons to False.  Thus, you may have to update your applications so that the correct painting style is specified by the LookAndFeel property.

Note: the UseSystemPaint property value can still be changed at runtime.  If you have initialized TcxButton controls at runtime, their painting mechanism will not be changed.

The default value of the UseSystemPaint property is False.


TcxCustomButton.OnDropDownMenuPopup

TcxCustomButton           See also

Occurs when a dropdown menu is about to be displayed on screen.

type

  TcxButtonDropDownMenuPopupEvent = procedure(Sender: TObject; var APopupMenu: TPopupMenu; var AHandled: Boolean) of object;

property OnDropDownMenuPopup: TcxButtonDropDownMenuPopupEvent;

Description

The OnDropDownMenuPopup event is fired when the dropdown menu is about to be displayed on screen for buttons with the Kind property set to cxbkDropDown or cxbkDropDownButton.

Handling the OnDropDownMenuPopup event is useful, for instance, if you want to handle the dropdown menu appearance in a custom way or designate the popup menu to be displayed at run time.  The APopupMenu parameter specifies the popup menu object that will be displayed.  By default, it refers to the TPopupMenu instance set to the DropDownMenu property.  When the DropDownMenu property is not set, the APopupMenu parameter value is nil (Delphi) or NULL (C++).

Set the AHandled parameter to True (the default value is False) and the dropdown menu will not be displayed automatically.


cxCalc Unit Overview
cxCalc Unit

Classes

TcxCalcEdit

TcxCalcEditProperties

TcxCalcEditPropertiesValues

TcxCustomCalcEdit

TcxCustomCalculator

TcxPopupCalculator

Other Types

TcxCalcButtonKind

Global Constants

BtnCaptions


TcxCalcEdit
 TcxCalcEdit Object

Hierarchy          Properties          Methods          Events          See Also

Represents an editor with a dropdown calculator window.

Unit

cxCalc

TcxCalcEdit = class(TcxCustomCalcEdit);

Description

The TcxCalcEdit editor incorporates a dropdown calculator.  The calculator is displayed within the popup window and allows a user to perform arithmetic operations such as '/', '*', '-', '+', 'square root', '%', '1/x' and store the result in the edit value of the TcxCalcEdit control.  A user can calculate a value either by pressing the appropriate keys or by clicking the buttons on the calculator window.

The following image demonstrates two calculator editors painted in default and XP styles.

To access a stored value (result) in the editor you can use either the EditValue or the Value property.  The Value property always returns the actual number, while EditValue is a variant and in some cases it can specify NULL.

Pressing the Enter key in the dropdown calculator evaluates the last operation and closes the dropdown window.  If the dropdown window is opened, pressing the Esc key results in closing it.  If pressing the Esc key repeats, then the changes made to the editor value are discarded and the editor value reverts to the old one.

Use the Properties and style (the Style, StyleDisabled, StyleFocused and StyleHot) members to specify the behavior and appearance of your calculator editor.  Working with the style is discussed in the TcxCustomEditStyle class topic.


TcxCalcEdit Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomPopupEdit

     |

TcxCustomCalcEdit

     |


Properties for TcxCalcEdit
TcxCalcEdit Properties

TcxCalcEdit          Legend

In TcxCalcEdit

EditValue

Derived from TcxCustomCalcEdit

ActiveProperties

Calculator

Properties

Value

Derived from TcxCustomPopupEdit

ActiveProperties

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxCalcEdit
TcxCalcEdit Methods

TcxCalcEdit          Legend

Derived from TcxCustomPopupEdit

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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCalcEdit
TcxCalcEdit Events

TcxCalcEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCalcEdit.EditValue

TcxCalcEdit          See Also

Represents the value stored by a TcxCalcEdit control.

type

  TcxEditValue = Variant;

property EditValue: TcxEditValue;

Description

Use the EditValue property to get and set a value, stored by the TcxCalcEdit editor.  The value calculated by the calculator is stored in this property.  EditValue is a variant and can store either numbers of double type or NULL values.  EditValue specifies NULL if no operations were performed via the calculator and no numerical value was assigned.  To ensure that a numerical value is provided, use the inherited Value property.  The value returned by the Value property is calculated from EditValue.  If EditValue is set to NULL, Value returns 0.


TcxCustomCalcEdit
TcxCustomCalcEdit Object

Hierarchy          Properties          Methods          Events          See also

Represents the base class for the editors incorporating the dropdown calculator.

Unit

cxCalc

TcxCustomCalcEdit = class(TcxCustomPopupEdit, IcxFormatContollerListener);

Description

The TcxCustomCalcEdit class extends functionality of the TcxCustomPopupEdit class and embeds a calculator object in the popup window.  To access its properties use the protected Calculator member.

To set the properties of the TcxCustomCalcEdit control use the Properties member.  Use the Style, StyleDisabled, StyleFocused and StyleHot properties to adjust the look & feel of an editor in various control’s states.  They contain the PopupBorderStyle attribute, which controls the look & feel of the dropdown calculator.

Do not create instances of the TcxCustomCalcEdit class, use its descendants such as TcxCalcEdit and TcxDBCalcEdit.


TcxCustomCalcEdit Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomPopupEdit

     |


Properties for TcxCustomCalcEdit
TcxCustomCalcEdit Properties

TcxCustomCalcEdit          Legend

In TcxCustomCalcEdit

ActiveProperties

Calculator

Properties

Value

Derived from TcxCustomPopupEdit

ActiveProperties

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading


Methods for TcxCustomCalcEdit
TcxCustomCalcEdit Methods

TcxCustomCalcEdit          Legend

Derived from TcxCustomPopupEdit

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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCustomCalcEdit
TcxCustomCalcEdit Events

TcxCustomCalcEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCustomCalcEdit.ActiveProperties

TcxCustomCalcEdit          See Also

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

property ActiveProperties: TcxCustomCalcEditProperties;

Description

Use the ActiveProperties property to obtain the properties of the current calculator editor that are currently in effect.  This property is especially useful when the calculator 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 calculator editor.  Otherwise, the inherent calculator editor’s properties are returned.

ReadOnly Property


TcxCustomCalcEdit.Calculator

TcxCustomCalcEdit          See Also

Returns a reference to a dropdown calculator control.

property Calculator: TcxPopupCalculator;

Description

The Calculator property returns a reference to the object of the class, which represents a dropdown calculator embedded in the TcxCustomCalcEdit control.

ReadOnly Property


TcxCustomCalcEdit.Properties

TcxCustomCalcEdit          See Also

Contains different settings specific to a calculator editor.

property Properties: TcxCustomCalcEditProperties;

Description

Use Properties to set specific attributes which control the editor behavior.  They define the alignment of the editor contents, the collection of buttons that can be displayed within the editor, the read-only status, etc.  The TcxCustomCalcEditProperties class declares additional properties specific to calculator editors.


TcxCustomCalcEdit.Value

TcxCustomCalcEdit          See Also

Specifies the numeric value stored within a calculator editor.

property Value: Extended;

Description

Use the Value property to get and set a numeric value stored within the TcxCustomCalcEdit editor.  When assigning a value to this property it actually changes the EditValue member.  When reading the value of this property the result is calculated using the value of the EditValue property.  EditValue can specify NULL in some cases (for instance, at the beginning of the calculator work when nothing was assigned to its value).  If so, the Value property returns 0.


TcxCustomCalcEditProperties
TcxCustomCalcEditProperties Object

Hierarchy          Properties          Methods          Events          See Also

Represents settings specific to editors with a dropdown calculator.

Unit

cxCalc

TcxCustomCalcEditProperties = class(TcxCustomPopupEditProperties);

Description

The TcxCustomCalcEditProperties class represents a set of attributes that control the behavior of calculator editors.  Properties for an editor are set via the Properties member of the corresponding editor.  The TcxCalcEditProperties class publishes all properties introduced in the TcxCustomCalcEditProperties class.


TcxCustomCalcEditProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |

TcxCustomDropDownEditProperties

     |

TcxCustomPopupEditProperties

     |


Properties for TcxCustomCalcEditProperties
TcxCustomCalcEditProperties Properties

TcxCustomCalcEditProperties          Legend

In TcxCustomCalcEditProperties

AssignedValues

BeepOnError

Precision

QuickClose

ScientificFormat

UseThousandSeparator

Derived from TcxCustomPopupEditProperties

PopupControl

PopupSizeable

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

IncrementalSearch

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 TcxCustomCalcEditProperties
TcxCustomCalcEditProperties Methods

TcxCustomCalcEditProperties          Legend

In TcxCustomCalcEditProperties

StrToFloatEx

Derived from TcxCustomMaskEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults


Events for TcxCustomCalcEditProperties
TcxCustomCalcEditProperties Events

TcxCustomCalcEditProperties          Legend

Derived from TcxCustomDropDownEditProperties

OnCloseQuery

OnCloseUp

OnInitPopup

OnPopup

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomCalcEditProperties.AssignedValues

TcxCustomCalcEditProperties

Contains the property flags that indicate which properties specific to a calculator editor have been changed.

property AssignedValues: TcxCalcEditPropertiesValues;

Description

Use the AssignedValues property to track the changes made to a calculator editor’s DisplayFormat, EditFormat, MaxLength, MaxValue, MinValue, Precision and ReadOnly properties and undo them.  Once the property being tracked is set to a value other than the default one, the changes are reflected in the AssignedValues property (its corresponding property flag is set to True).  To undo the changes made and reverse the property back to its default value, set the corresponding property flag to False or call the AssignedValues.RestoreDefaults method to reverse all these properties back to their default values and reset all the property flags.  Use the AssignedValues.BeginUpdate and AssignedValues.EndUpdate methods to control when the editor repaints and avoid any flickering when the property flags are modified.


TcxCustomCalcEditProperties.BeepOnError

TcxCustomCalcEditProperties

Specifies whether a calculator editor generates the system default sound when an error occurs.

property BeepOnError: Boolean;

Description

Set the BeepOnError property to True to enable playing sounds when errors occur.  An error occurs, for instance, when trying to divide by zero.

The default value of the BeepOnError property is True.


TcxCustomCalcEditProperties.Precision

TcxCustomCalcEditProperties

Defines the value precision in a calculator editor.

property Precision: Byte;

Description

The Precision property determines the number of digits a calculator editor can display.

The default value of the Precision property is cxDefCalcPrecision.  cxDefCalcPrecision is a constant declared in the cxCalc unit.


TcxCustomCalcEditProperties.QuickClose

TcxCustomCalcEditProperties

Specifies whether the calculator window is closed by pressing the ‘=’ keyboard button.

property QuickClose: Boolean;

Description

Set the QuickClose property to True to enable closing the calculator dropdown window when a user presses the ‘=’ keyboard key.  Clicking the ‘=’ button in the calculator window by the mouse does not close it.

The default value of the QuickClose property is False.


TcxCustomCalcEditProperties.ScientificFormat

TcxCustomCalcEditProperties

Specifies whether the editor uses scientific notation to display a value.

property ScientificFormat: Boolean;

Description

Set the ScientificFormat property to True to display the value as a numeral with a decimal point and exponent also known as ‘scientific notation/format’.  The images below show how this property affects the value’s appearance within the editor.

Property’s Value	False	True

The default value of the ScientificFormat property is False.


TcxCustomCalcEditProperties.UseThousandSeparator

TcxCustomCalcEditProperties

Specifies whether thousand separators are displayed in the editor when it has focus.

property UseThousandSeparator: Boolean;

Description

Set the UseThousandSeparator property to True to make your editor display thousand separators when it’s focused.  Otherwise, thousand separators are not displayed.  To obtain the thousands separator, use the global ThousandSeparator variable declared in the SysUtils unit.

Note:	Thousand separators are used for formatting the display value whenever the editor reacquires its focus.

The default value of the UseThousandSeparator property is False.


TcxCustomCalcEditProperties.StrToFloatEx

TcxCustomCalcEditProperties

Converts a specific string to a floating-point value.

function StrToFloatEx(S: string; var Value: Double): Boolean;

Description

The StrToFloatEx function returns True if the string was converted successfully and the evaluated number falls within the range between the minimum (5.0e-324) and maximum (1.7e+308) values.  Otherwise, the function returns False and the Value parameter returns 0.  The StrToFloatEx method accepts formatted strings with thousand separators.


TcxCalcEditProperties
TcxCalcEditProperties Object

Hierarchy          Properties          Methods          Events          See Also

Represents settings specific to editors with dropdown calculators.

Unit

cxCalc

TcxCalcEditProperties = class(TcxCustomCalcEditProperties);

Description

The TcxCalcEditProperties class represents a set of attributes that control the behavior of the TcxCustomCalcEdit editors.  Editor properties are set via the Properties member of the corresponding editor.  To control any changes made to the editor’s DisplayFormat, EditFormat, MaxLength, MaxValue, MinValue, Precision and ReadOnly properties and reverse their values back to the default ones, use the AssignedValues property.

TcxCalcEditProperties does not provide any new functionality but publishes the properties introduced in the TcxCustomCalcEditProperties class.


TcxCalcEditProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |

TcxCustomDropDownEditProperties

     |

TcxCustomPopupEditProperties

     |

TcxCustomCalcEditProperties

     |


Properties for TcxCalcEditProperties
TcxCalcEditProperties Properties

TcxCalcEditProperties          Legend

Derived from TcxCustomCalcEditProperties

AssignedValues

BeepOnError

Precision

QuickClose

ScientificFormat

UseThousandSeparator

Derived from TcxCustomPopupEditProperties

PopupControl

PopupSizeable

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

IncrementalSearch

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 TcxCalcEditProperties
TcxCalcEditProperties Methods

TcxCalcEditProperties          Legend

Derived from TcxCustomCalcEditProperties

StrToFloatEx

Derived from TcxCustomMaskEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults


Events for TcxCalcEditProperties
TcxCalcEditProperties Events

TcxCalcEditProperties          Legend

Derived from TcxCustomDropDownEditProperties

OnCloseQuery

OnCloseUp

OnInitPopup

OnPopup

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCalcEditPropertiesValues
TcxCalcEditPropertiesValues Object

Hierarchy          Properties          Methods

Contains the property flags that indicate which properties specific to an editor with a dropdown calculator have been changed.

Unit

cxCalc

TcxCalcEditPropertiesValues = class(TcxTextEditPropertiesValues);

Description

The TcxCalcEditPropertiesValues class tracks the changes made to the DisplayFormat, EditFormat, MaxLength, MaxValue, MinValue, Precision and ReadOnly properties of an editor with a dropdown calculator.  Once one of these properties is set to a value other than the default one, the changes are reflected in the TcxCalcEditPropertiesValues class (its corresponding property flag is set to True).  To undo the changes made and reverse the property back to its default value, set the corresponding property flag to False or call the RestoreDefaults method to reverse all these properties back to their default values and reset all the property flags.  Use the BeginUpdate and EndUpdate methods to control when the editor repaints and avoid any flickering when the property flags are modified.


TcxCalcEditPropertiesValues Hierarchy
Hierarchy

TPersistent

     |

TcxCustomEditPropertiesValues

     |

TcxTextEditPropertiesValues

     |


Properties for TcxCalcEditPropertiesValues
TcxCalcEditPropertiesValues Properties

TcxCalcEditPropertiesValues          Legend

In TcxCalcEditPropertiesValues

Precision

Derived from TcxTextEditPropertiesValues

DisplayFormat

EditFormat

MaxLength

MaxValue

MinValue

Derived from TcxCustomEditPropertiesValues

ReadOnly


Methods for TcxCalcEditPropertiesValues
TcxCalcEditPropertiesValues Methods

TcxCalcEditPropertiesValues          Legend

In TcxCalcEditPropertiesValues

RestoreDefaults

Derived from TcxCustomEditPropertiesValues

BeginUpdate

EndUpdate


TcxCalcEditPropertiesValues.Precision

TcxCalcEditPropertiesValues          See Also

Specifies whether the number of digits displayed in a calculator control has been changed.

property Precision; Boolean;

Description

Once the Precision property of an editor with a dropdown calculator is set to a value other than the default one, the Precision property flag is set to True.  Otherwise, it’s set to False.  To undo the changes made to the editor’s Precision property and reverse it back to its default value, call the RestoreDefaults method which resets all the property flags or set the Precision property flag to False.


TcxCalcEditPropertiesValues.RestoreDefaults

TcxCalcEditPropertiesValues          See Also

Reverses the values of the properties (changes to which are being tracked) back to their default values.

procedure RestoreDefaults; override;

Description

The RestoreDefaults method undoes any changes made to the properties and resets their values back to the default ones.  Calling this method sets the editor’s properties being tracked (DisplayFormat, EditFormat, MaxLength, MaxValue, MinValue, Precision, and ReadOnly) to the default values and resets the corresponding property flags to False.  Setting the property flag of each property being tracked to False has the same result as calling the RestoreDefaults method.


TcxCustomCalculator
TcxCustomCalculator Object

Hierarchy          Properties          Methods          Events          See also

Represents a calculator control that performs arithmetic operations.

Unit

cxCalc

TcxCustomCalculator = class(TcxControl);

Description

The TcxCustomCalculator class represents a control, which displays a calculator window with buttons.  It is possible to evaluate an arithmetic expression by pressing these buttons and by storing the result in the Value property.  TcxCustomCalculator is the base class for the classes, which employ a calculator control.  It also allows embedding itself in popup windows of other controls.  TcxPopupCalculator derives from TcxCustomCalculator and provides the ability to embed a calculator in the popup window of the TcxCustomCalcEdit control.


TcxCustomCalculator Hierarchy
Hierarchy

TcxControl

     |


Properties for TcxCustomCalculator
TcxCustomCalculator Properties

TcxCustomCalculator          Legend

In TcxCustomCalculator

AutoFontSize

BeepOnError

EditorValue

Memory

Precision

ShowFocusRect

Value


Methods for TcxCustomCalculator
TcxCustomCalculator Methods

TcxCustomCalculator          Legend

In TcxCustomCalculator

ButtonClick

GetButtonKindAt

GetButtonKindChar

GetButtonKindKey


Events for TcxCustomCalculator
TcxCustomCalculator Events

TcxCustomCalculator          Legend

In TcxCustomCalculator

OnButtonClick

OnDisplayChange

OnError

OnHidePopup

OnResult

Derived from TcxControl

OnMouseEnter

OnMouseLeave


TcxCustomCalculator.AutoFontSize

TcxCustomCalculator

Specifies whether a calculator automatically selects buttons font size.

property AutoFontSize: Boolean;

Description

The AutoFontSize property value is used internally to determine whether the font size of calculator buttons is selected automatically when the control repaints itself.  If this property is set to True, the font size changes when the calculator is resized and a new font size is calculated based upon the button size.  If this property is set to False, the font size is a constant.

The default value of the AutoFontSize property is True.


TcxCustomCalculator.BeepOnError

TcxCustomCalculator

Determines whether a calculator control generates a warning sound when an error occurs.

property BeepOnError: Boolean;

Description

If the BeepOnError property is set to True, a standard sound is played on an error.

The default value of the BeepOnError property is True.


TcxCustomCalculator.EditorValue

TcxCustomCalculator          See also

Specifies the text representation of the value calculated via a calculator control.

property EditorValue: string;

Description

The EditorValue property defines the value calculated via a calculator control and converted to a string.  It may contain a NULL value. To ensure that a valid numeric value is returned, use the Value property instead.


TcxCustomCalculator.Memory

TcxCustomCalculator

Defines the data stored in memory.

property Memory: Extended;

Description

When using the calculator, you can store any value by pressing the 'MS' button and retrieve it by pressing the 'MR' button.  The Memory property contains this stored data.

ReadOnly Property


TcxCustomCalculator.Precision

TcxCustomCalculator

Determines the number of digits displayed in a calculator control.

property Precision: Byte;

Description

The Precision property defines the maximum number of digits the calculator can display.  It includes both integer and fractional parts.

The default value of the Precision property is cxDefCalcPrecision.


TcxCustomCalculator.ShowFocusRect

TcxCustomCalculator

Specifies whether a focus rectangle is drawn around the "equals" (=) button.

property ShowFocusRect: Boolean;

Description

If the ShowFocusRect property is set to True, a focus rectangle is displayed around the "equals" (=) button when the control has focus.

The default value of the ShowFocusRect property is True.


TcxCustomCalculator.Value

TcxCustomCalculator

Identifies the value calculated via a calculator control.

property Value: Extended;

Description

The Value property defines the result of calculations.


TcxCustomCalculator.ButtonClick

TcxCustomCalculator

Performs specific actions based on the calculator button passed in.

procedure ButtonClick(ButtonKind: TcxCalcButtonKind);

Description

The ButtonClick method is used internally to perform specific actions based on the type of the calculator button defined by the ButtonKind parameter.


TcxCustomCalculator.GetButtonKindAt

TcxCustomCalculator

Returns the calculator button type based on its position.

type

  TcxCalcButtonKind = (cbBack, cbCancel, cbClear, cbMC, cbMR, cbMS, cbMP, cbNum0, cbNum1, cbNum2, cbNum3, cbNum4, cbNum5, cbNum6, cbNum7, cbNum8, cbNum9, cbSign, cbDecimal, cbDiv, cbMul, cbSub, cbAdd, cbSqrt, cbPercent, cbRev, cbEqual, cbNone);

function GetButtonKindAt(X, Y: Integer): TcxCalcButtonKind;

Description

The GetButtonKindAt method determines the calculator button type at the position specified by the X and Y parameters.  This method is used internally when a user clicks a calculator button.


TcxCustomCalculator.GetButtonKindChar

TcxCustomCalculator

Returns the calculator button type based on the pressed key.

type

  TcxCalcButtonKind = (cbBack, cbCancel, cbClear, cbMC, cbMR, cbMS, cbMP, cbNum0, cbNum1, cbNum2, cbNum3, cbNum4, cbNum5, cbNum6, cbNum7, cbNum8, cbNum9, cbSign, cbDecimal, cbDiv, cbMul, cbSub, cbAdd, cbSqrt, cbPercent, cbRev, cbEqual, cbNone);

function GetButtonKindChar(Ch: Char): TcxCalcButtonKind;

Description

The GetButtonKindChar method determines the calculator button type by the pressed ASCII character.  This method is used internally when a user presses a keyboard key.


TcxCustomCalculator.GetButtonKindKey

TcxCustomCalculator

Determines the calculator button type by the pressed key.

type

  TcxCalcButtonKind = (cbBack, cbCancel, cbClear, cbMC, cbMR, cbMS, cbMP, cbNum0, cbNum1, cbNum2, cbNum3, cbNum4, cbNum5, cbNum6, cbNum7, cbNum8, cbNum9, cbSign, cbDecimal, cbDiv, cbMul, cbSub, cbAdd, cbSqrt, cbPercent, cbRev, cbEqual, cbNone);

function GetButtonKindKey(Key: Word; Shift: TShiftState): TcxCalcButtonKind;

Description

The GetButtonKindKey method determines the button type based on the pressed key.  This method is used internally when a user presses a keyboard key.  The Key parameter is a keyboard key.  If a non-alphanumeric key was pressed, the Key parameter defines a virtual key code.  The Shift parameter indicates whether the Shift, Alt, or Ctrl key is combined with a keystroke.


TcxCustomCalculator.OnButtonClick

TcxCustomCalculator

Occurs when a user clicks a calculator button.

type

  TcxCalcButtonKind = (cbBack, cbCancel, cbClear, cbMC, cbMR, cbMS, cbMP, cbNum0, cbNum1, cbNum2, cbNum3, cbNum4, cbNum5, cbNum6, cbNum7, cbNum8, cbNum9, cbSign, cbDecimal, cbDiv, cbMul, cbSub, cbAdd, cbSqrt, cbPercent, cbRev, cbEqual, cbNone);

  TcxCalcButtonClick = procedure(Sender: TObject; var ButtonKind: TcxCalcButtonKind) of object;

property OnButtonClick: TcxCalcButtonClick;

Description

The OnButtonClick event is generated when a user presses a calculator button either by clicking it by the mouse or by pressing an appropriate keyboard key.  This event occurs before the internal result calculation is performed.  The Sender parameter defines the TcxCustomCalculator object.  The button, which the user has activated, is identified by the ButtonKind parameter.


TcxCustomCalculator.OnDisplayChange

TcxCustomCalculator

Occurs when changing the display value.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnDisplayChange: TNotifyEvent;

Description

The OnDisplayChange event is generated after the display value within a calculator control has been changed.  The Sender parameter defines the calculator control for which this event occurred.


TcxCustomCalculator.OnError

TcxCustomCalculator

Occurs when the calculator generates an error.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnError: TNotifyEvent;

Description

The OnError event is generated when an error occurs.  The Sender parameter defines the calculator control, which has raised the error.


TcxCustomCalculator.OnHidePopup

TcxCustomCalculator

Occurs on hiding the calculator incorporated into the popup window.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnHidePopup: TNotifyEvent;

Description

The OnHidePopup event is generated when the calculator embedded in the popup window is about to be hidden.  The Sender parameter defines the calculator control for which this event occurred.


TcxCustomCalculator.OnResult

TcxCustomCalculator

Occurs when a user presses or clicks the "equals" (=) or the "percent"  (%) calculator button.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnResult: TNotifyEvent;

Description

The OnResult event is generated when a user activates the "equals" (=) or the "percent"  (%) calculator button by clicking it with the mouse or by pressing the corresponding keyboard key.  The Sender parameter defines the calculator control for which this event occurred.


TcxDBCalcEdit
 TcxDBCalcEdit Object

Hierarchy          Properties          Methods          Events           See also

Represents a data-aware control that enables editing a value via a popup calculator.

Unit

cxDBEdit

TcxDBCalcEdit = class(TcxCustomCalcEdit);

Description

Use the TcxDBCalcEdit control to edit the contents of a numerical dataset field via a popup calculator.  The following image demonstrates two calculator editors painted in the default and XP styles accordingly.

Pressing the Enter key in the dropdown calculator evaluates the last operation and closes the dropdown window.  If the dropdown window is opened, pressing the Esc key  closes it but the last operation is not calculated in this case.  While editing a value in the edit box of your control, you can press the Esc key to discard the value changes made and revert to the original value.

In order to connect a data-aware control to a dataset, it is necessary to set the DataSource and DataField properties of the DataBinding object.

The adjustment of different calculator settings and style properties is the same as for the TcxCalcEdit control.  Use the Properties and style (the Style, StyleDisabled, StyleFocused and StyleHot) members to specify the behavior and look & feel of the calculator editor.  The PopupBorderStyle property of the style members allows you to define the look & feel of the calculator itself.  Working with styles is discussed in the TcxCustomEditStyle class topic.


TcxDBCalcEdit Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomPopupEdit

     |

TcxCustomCalcEdit

     |


Properties for TcxDBCalcEdit
TcxDBCalcEdit Properties

TcxDBCalcEdit          Legend

In TcxDBCalcEdit

DataBinding

Derived from TcxCustomCalcEdit

ActiveProperties

Calculator

Properties

Value

Derived from TcxCustomPopupEdit

ActiveProperties

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxDBCalcEdit
TcxDBCalcEdit Methods

TcxDBCalcEdit          Legend

Derived from TcxCustomPopupEdit

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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxDBCalcEdit
TcxDBCalcEdit Events

TcxDBCalcEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxDBCalcEdit.DataBinding

TcxDBCalcEdit          See also

Specifies the dataset connection.

property DataBinding: TcxDBEditDataBinding;

Description

Use the DataBinding property to access a TcxDBEditDataBinding instance via which a connection with the dataset is established.  To make a TcxDBCalcEdit control edit the value from a specific dataset field set the DataSource and DataField properties of the DataBinding object.


TcxPopupCalculator
TcxPopupCalculator Object

Hierarchy          Properties          Methods          Events          See also

Represents a calculator control, which can be embedded in the popup window of TcxCustomPopupEdit descendants.

Unit

cxCalc

TcxPopupCalculator = class(TcxCustomCalculator);

Description

The TcxPopupCalculator class extends TcxCustomCalculator functionality and allows embedding a calculator control in the popup window of a TcxCustomCalcEdit control.


TcxPopupCalculator Hierarchy
Hierarchy

TcxControl

     |

TcxCustomCalculator

     |


Properties for TcxPopupCalculator
TcxPopupCalculator Properties

TcxPopupCalculator          Legend

In TcxPopupCalculator

Edit

Derived from TcxCustomCalculator

AutoFontSize

BeepOnError

EditorValue

Memory

Precision

ShowFocusRect

Value


Methods for TcxPopupCalculator
TcxPopupCalculator Methods

TcxPopupCalculator          Legend

Derived from TcxCustomCalculator

ButtonClick

GetButtonKindAt

GetButtonKindChar

GetButtonKindKey


Events for TcxPopupCalculator
TcxPopupCalculator Events

TcxPopupCalculator          Legend

Derived from TcxCustomCalculator

OnButtonClick

OnDisplayChange

OnError

OnHidePopup

OnResult

Derived from TcxControl

OnMouseEnter

OnMouseLeave


TcxPopupCalculator.Edit

TcxPopupCalculator

Specifies the calculator editor, owning the current calculator.

property Edit: TcxCustomCalcEdit;

Description

Use the Edit property to get and set the calculator editor, which owns the current calculator.  The editor specified by this property embeds the calculator in its popup window.


TcxCalcButtonKind
TcxCalcButtonKind type

Enumerates calculator buttons types.

Unit

cxCalc

type

  TcxCalcButtonKind = (cbBack, cbCancel, cbClear, cbMC, cbMR, cbMS, cbMP, cbNum0, cbNum1, cbNum2, cbNum3, cbNum4, cbNum5, cbNum6, cbNum7, cbNum8, cbNum9, cbSign, cbDecimal, cbDiv, cbMul, cbSub, cbAdd, cbSqrt, cbPercent, cbRev, cbEqual, cbNone);

Description

TcxCalcButtonKind enumerates the calculator button types.  TcxCalcButtonKind is used in methods and events of the TcxCustomCalculator class to identify a specific button.

The following table describes the button types.

Value	Meaning	Value	Meaning
cbBack	The 'Back' button.	cbNum7	The '7' button.
cbCancel	The 'CE' button.	cbNum8	The '8' button.
cbClear	The 'C' button.	cbNum9	The '9' button.
cbMC	The 'MC' button.	cbSign	The '+/-' button.
cbMR	The 'MR' button.	cbDecimal	The ‘,’ button.
cbMS	The 'MS' button.	cbDiv	The ‘/’ button.
cbMP	The 'M+' button.	cbMul	The ‘*’ button.
cbNum0	The '0' button.	cbSub	The ‘-‘ button.
cbNum1	The '1' button.	cbAdd	The ‘+’ button.
cbNum2	The '2' button.	cbSqrt	The ‘sqrt’ button.
cbNum3	The '3' button.	cbPercent	The ‘%’ button.
cbNum4	The '4' button.	cbRev	The ‘1/x’ button.
cbNum5	The '5' button.	cbEqual	The ‘=’ button.
cbNum6	The '6' button.	cbNone	Does not identify any of calculator buttons.


BtnCaptions constant
BtnCaptions global constant

Describes the captions displayed on the calculator button surfaces.

Unit

cxCalc

BtnCaptions : array [cbBack..cbEqual] of string[4] = ('Back', 'CE', 'C', 'MC', 'MR', 'MS', 'M+', '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', '+/-', ',', '/', '*', '-', '+', 'sqrt', '%', '1/x', '=');

Description

The TcxCustomCalculator control uses the BtnCaptions constant to get the caption displayed on a specific calculator button.  Button types are enumerated by the TcxCalcButtonKind type.


cxCheckBox Unit Overview
cxCheckBox Unit

Classes

TcxCheckBox

TcxCheckBoxProperties

TcxCustomCheckBox

TcxCustomCheckBoxProperties

Other Types

TcxCheckBoxNullValueShowingStyle

TcxCheckBoxState

TcxCheckStatesValueFormat

Routines

CalculateCheckStates

CalculateCheckStatesValue


TcxCheckBox
 TcxCheckBox Object

Hierarchy          Properties          Methods          Events          See also

Represents a check box control that allows selecting an option.

Unit

cxCheckBox

TcxCheckBox = class(TcxCustomCheckBox);

Description

The TcxCheckBox class represents a check box by which a user can select an option.  A check box can have two (checked, unchecked) or three (checked, unchecked and grayed) states.  A TcxCheckBox control includes a check box and a caption region.  Users can edit data within an editor by checking or unchecking the check box.  The caption region contains the description of the check box.  The following image displays the check box editor painted in the Windows XP look & feel:

Use the Properties and style (the Style, StyleDisabled, StyleFocused and StyleHot) members to specify the behavior and look & feel of the check box editor.  Working with styles is discussed in the TcxCustomEditStyle class topic.

For your check box have three states, set the AllowGrayed property of the Properties object to True.  A user can switch between these states by clicking the editor with the mouse or by pressing the keyboard space bar.  To set the state programmatically, use either the Checked or the State property. The Checked property is of type Boolean and can identify only checked and unchecked states.  The State property is more powerful and allows you to select one of the three states.

It is possible to associate a variant value with each check box state.  These values are retrieved by the EditValue property from the corresponding members of the Properties object.  EditValue returns values of the ValueChecked, ValueUnchecked and ValueGrayed members for checked, unchecked and grayed states, respectively.


TcxCheckBox Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomCheckBox

     |


Properties for TcxCheckBox
TcxCheckBox Properties

TcxCheckBox          Legend

Derived from TcxCustomCheckBox

ActiveProperties

Checked

Properties

State

Derived from TcxCustomEdit

ActiveProperties

AutoSize

DataBinding

EditModified

EditValue

InnerEdit

ModifiedAfterEnter

Properties

RepositoryItem

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TControl

Align

Caption


Methods for TcxCheckBox
TcxCheckBox Methods

TcxCheckBox          Legend

Derived from TcxCustomCheckBox

Toggle

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCheckBox
TcxCheckBox Events

TcxCheckBox          Legend

In TcxCheckBox

OnClick

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCheckBox.OnClick

TcxCheckBox

Occurs when a user clicks a check box with the mouse or presses the keyboard space bar.

type

  TNotifyEvent = procedure (Sender: TObject) of object;

property OnClick: TNotifyEvent;

Description

When a user clicks a check box or presses the space bar while the editor has focus, the state of the check box editor is switched.  Before the state is changed, the OnClick event is generated.


TcxCheckBoxProperties
TcxCheckBoxProperties Object

Hierarchy          Properties          Methods          Events          See Also

Contains properties specific to check box editors.

Unit

cxCheckBox

TcxCheckBoxProperties = class(TcxCustomCheckBoxProperties);

Description

The TcxCheckBoxProperties class represents a set of attributes controlling the behavior of check box editors.  Use the Properties member of the TcxCustomCheckBox control to specify different settings.  To control any changes made to the editor’s ReadOnly property and reverse its value back to the default one, use the AssignedValues property.

TcxCheckBoxProperties does not introduce any new behavior but publishes properties and events inherited from base classes.  Properties allow you to define different settings such as alignment of the check box caption, custom images to draw instead of the check box itself and many others.  The AllowGrayed property enables a check box to have three states.  When a user clicks it, the checked, unchecked and grayed states are set one after another.  The ValueChecked, ValueGrayed and ValueUnchecked members specify variant values retrieved via the editor’s EditValue property when the check box is set to the checked, grayed or unchecked state respectively.


TcxCheckBoxProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomCheckBoxProperties

     |


Properties for TcxCheckBoxProperties
TcxCheckBoxProperties Properties

TcxCheckBoxProperties          Legend

Derived from TcxCustomCheckBoxProperties

Alignment

AllowGrayed

Caption

DisplayChecked

DisplayGrayed

DisplayUnchecked

FullFocusRect

Glyph

GlyphCount

MultiLine

NullStyle

UseAlignmentWhenInplace

ValueChecked

ValueGrayed

ValueUnchecked

Derived from TcxCustomEditProperties

Alignment

AssignedValues

AutoSelect

BeepOnError

Buttons

ButtonsViewStyle

ClearKey

ClickKey

ImmediatePost

ReadOnly

UseLeftAlignmentOnEditing

UseMouseWheel

ValidateOnEnter


Methods for TcxCheckBoxProperties
TcxCheckBoxProperties Methods

TcxCheckBoxProperties          Legend

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue


Events for TcxCheckBoxProperties
TcxCheckBoxProperties Events

TcxCheckBoxProperties          Legend

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomCheckBox
TcxCustomCheckBox Object

Hierarchy          Properties          Methods          Events          See Also

Represents the base class for check box controls.

Unit

cxCheckBox

TcxCustomCheckBox = class(TcxCustomEdit);

Description

A check box control allows selecting an option.  A user can check, uncheck or choose a "grayed" state.  The TcxCustomCheckBox control provides the Checked and State properties by which you can control the editor state.  The Checked property is of Boolean type and can identify only checked and unchecked states.  The State property is more powerful and allows you to select one of the three states.

The Properties member provides many settings controlling the behavior and look & feel of check box editors.  It specifies the check box alignment, images displayed instead of the check box and many other settings.  Properties also contains an AllowGrayed member which determines whether a check box can have three states.

It is possible to associate a variant value with each check box state.  These values are retrieved by the EditValue property from the corresponding members of the Properties object.  EditValue returns values of the ValueChecked, ValueUnchecked and ValueGrayed members for checked, unchecked and grayed states, respectively.

Do not create instances of the TcxCustomCheckBox class.  Use its descendants such as TcxCheckBox or TcxDBCheckBox instead.


TcxCustomCheckBox Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |


Properties for TcxCustomCheckBox
TcxCustomCheckBox Properties

TcxCustomCheckBox          Legend

In TcxCustomCheckBox

ActiveProperties

Checked

Properties

State

Derived from TcxCustomEdit

ActiveProperties

AutoSize

DataBinding

EditModified

EditValue

InnerEdit

ModifiedAfterEnter

Properties

RepositoryItem

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading


Methods for TcxCustomCheckBox
TcxCustomCheckBox Methods

TcxCustomCheckBox          Legend

In TcxCustomCheckBox

Toggle

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCustomCheckBox
TcxCustomCheckBox Events

TcxCustomCheckBox          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCustomCheckBox.ActiveProperties

TcxCustomCheckBox          See Also

Obtains the properties that are currently applied to a check box editor.

property ActiveProperties: TcxCustomCheckBoxProperties;

Description

Use the ActiveProperties property to obtain the properties of the current check box editor that are currently in effect.  This property is especially useful when the check box 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 check box editor.  Otherwise, the inherent check box editor’s properties are returned.

ReadOnly Property


TcxCustomCheckBox.Checked

TcxCustomCheckBox          See also

Determines whether an editor has a checked or unchecked state.

property Checked: Boolean;

Description

Use the Checked property to specify the checked or unchecked states for a check box editor.  The Checked property allows you to represent Boolean values (True and False).  Using the State property you can specify one of the three states for your check box (checked, unchecked or grayed).  If State is set to cbsGrayed, the Checked property returns False.


TcxCustomCheckBox.Properties

TcxCustomCheckBox          See Also

Contains settings specific to check box editors.

property Properties: TcxCustomCheckBoxProperties;

Description

Use Properties to specify the alignment of the check box and set specific attributes which control the editor's behavior and look & feel.  The AllowGrayed property, which is accessible via the Properties object, defines whether a user can select the "grayed" state or not.  It is possible to use images instead of a standard check box.  In this case it is necessary to set the Glyph and GlyphCount properties.  The Properties object contains the ValueChecked, ValueGrayed, and ValueUnchecked members identifying values retrieved by the EditValue property based on the current check box state.


TcxCustomCheckBox.State

TcxCustomCheckBox          See Also

Determines whether an editor has a checked, unchecked or grayed state.

property State: TcxCheckBoxState;

Description

The State property defines the state of your check box.  It is possible to set one of the three states: checked, unchecked and grayed.  A user can switch a check box to the grayed state only if the AllowGrayed property of the Properties object is set to True.  But it is possible to set the grayed state via code regardless of the AllowGrayed property value.

The Checked property also allows setting the check box state.  It is of type Boolean and therefore only the checked or unchecked state can be set.

The default value of the State property is cbsUnchecked.


TcxCustomCheckBox.Toggle

TcxCustomCheckBox          See Also

Changes the state of the check box editor.

procedure Toggle; virtual;

Description

The Toggle method changes the state of the check box.  If the AllowGrayed member of the Properties object is set to True, the Toggle method selects the unchecked, grayed and checked states one after another.  If AllowGrayed is set to False, the method switches among checked and unchecked states only.  To get the check box state read the Checked or State property.

Descendants of the TcxCustomCheckBox class can override this method to provide an appropriate switch mechanism.


TcxCustomCheckBoxProperties
TcxCustomCheckBoxProperties Object

Hierarchy          Properties          Methods          Events          See Also

Represents settings specific to check box editors.

Unit

cxCheckBox

TcxCustomCheckBoxProperties = class(TcxCustomEditProperties);

Description

The TcxCustomCheckBoxProperties class represents a set of attributes controlling the behavior of check box editors.  Properties of a check box editor are set via the Properties member.

These properties allow you to define different settings such as alignment of the check box caption, custom images to draw instead of the check box itself and many others.  The AllowGrayed property enables your check box to be in three states.  When a user clicks the check box, the checked, unchecked and grayed states are set one after another.  The ValueChecked, ValueGrayed, ValueUnchecked members specify variant values retrieved via the editor’s EditValue property when the check box is set to the checked, grayed or unchecked state respectively.


TcxCustomCheckBoxProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |


Properties for TcxCustomCheckBoxProperties
TcxCustomCheckBoxProperties Properties

TcxCustomCheckBoxProperties          Legend

In TcxCustomCheckBoxProperties

Alignment

AllowGrayed

Caption

DisplayChecked

DisplayGrayed

DisplayUnchecked

FullFocusRect

Glyph

GlyphCount

MultiLine

NullStyle

UseAlignmentWhenInplace

ValueChecked

ValueGrayed

ValueUnchecked

Derived from TcxCustomEditProperties

Alignment

AssignedValues

AutoSelect

BeepOnError

Buttons

ButtonsViewStyle

ClearKey

ClickKey

ImmediatePost

ReadOnly

UseLeftAlignmentOnEditing

UseMouseWheel

ValidateOnEnter


Methods for TcxCustomCheckBoxProperties
TcxCustomCheckBoxProperties Methods

TcxCustomCheckBoxProperties          Legend

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue


Events for TcxCustomCheckBoxProperties
TcxCustomCheckBoxProperties Events

TcxCustomCheckBoxProperties          Legend

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomCheckBoxProperties.Alignment

TcxCustomCheckBoxProperties

Specifies the alignment of a check box editor.

type

  TAlignment = (taLeftJustify, taRightJustify, taCenter);

property Alignment: TAlignment;

Description

Use the Alignment property to define the manner in which your check box and caption are aligned.  The following table describes the meaning of TAlignment values.  The following images are painted using the Windows XP style.

Value	Meaning
taLeftJustify	The check box and caption are aligned to the left edge of the editor.
taRightJustify	The check box and caption are aligned to the right edge of the editor.
taCenter	The caption is not drawn.  The check box is drawn in the center of the editor.

Note:	By default, the caption is not drawn within the in-place checkbox editors and the check box is painted in the center of the editors.  In order to specify that the check box and caption are aligned according to the Alignment property’s value, set the UseAlignmentWhenInplace property to True.


TcxCustomCheckBoxProperties.AllowGrayed

TcxCustomCheckBoxProperties          See Also

Specifies whether the grayed state is enabled.

property AllowGrayed: Boolean;

Description

Set the AllowGrayed property to True to enable a user to set the grayed state.  Otherwise, he/she can only switch between the checked and unchecked states (but it is possible to set the grayed state via code regardless of the AllowGrayed property value).  To change the check box state use the Checked or State property of the TcxCustomCheckBox control.

The default value of the AllowGrayed property is False.


TcxCustomCheckBoxProperties.Caption

TcxCustomCheckBoxProperties          See Also

Identifies the text which describes a check box.

property Caption: TCaption;

Description

The Caption property defines the text which is displayed beside the check box of the TcxCustomCheckBox editor.  The manner in which the text is displayed is specified by the Alignment and MultiLine properties.

Note:	This property is obsolete.  To specify a caption for an editor, use its Caption property.


TcxCustomCheckBoxProperties.DisplayChecked

TcxCustomCheckBoxProperties

Specifies the text representing the checked state.

property DisplayChecked: WideString;

Description

The DisplayChecked property specifies the text which represents a check box set to the checked state.  DisplayChecked is used in specific situations such as exporting a grid control with check boxes as in-place editors and within the filter dropdown list for a grid column assigned a check box as an editor.


TcxCustomCheckBoxProperties.DisplayGrayed

TcxCustomCheckBoxProperties

Specifies the text representing the grayed state.

property DisplayGrayed: WideString;

Description

The DisplayGrayed property specifies the text which represents a check box set to the grayed state.  DisplayGrayed is used in specific situations such as exporting a grid control with check boxes as in-place editors and within the filter dropdown list for a grid column assigned a check box as an editor.


TcxCustomCheckBoxProperties.DisplayUnchecked

TcxCustomCheckBoxProperties

Specifies the text representing the unchecked state.

property DisplayUnchecked: WideString;

Description

The DisplayUnchecked property specifies the text which represents a check box set to the unchecked state.  DisplayUnchecked is used in specific situations such as exporting a grid control with check boxes as in-place editors and within the filter dropdown list for a grid column assigned a check box as an editor.


TcxCustomCheckBoxProperties.FullFocusRect

TcxCustomCheckBoxProperties

Specifies whether the focus rectangle is drawn around the entire caption region or around the caption text only.

property FullFocusRect: Boolean;

Description

The FullFocusRect property defines whether the focus rectangle is drawn around the entire caption region or around the caption text of the TcxCustomCheckBox editor.  Set this property to True to draw the focus rectangle around the entire caption region taking into account the editor size.  If the FullFocusRect property value is False, the focus rectangle is drawn around the text as closely as possible.

The default value of the FullFocusRect property is False.


TcxCustomCheckBoxProperties.Glyph

TcxCustomCheckBoxProperties          See Also

Defines the image displayed instead of an editor check box.

property Glyph: TBitmap;

Description

Use the Glyph property to specify the custom image to draw instead of the check box.  It is possible to provide up to six images within a single bitmap.  A TcxCustomCheckBox control uses one of these images depending on the check box state.  All images must be of the same size and placed next to each other within a row.  The number of images is determined by the GlyphCount property.


TcxCustomCheckBoxProperties.GlyphCount

TcxCustomCheckBoxProperties          See Also

Specifies the number of images within a bitmap provided by the Glyph property.

property GlyphCount: Integer;

Description

By using the Glyph property it is possible to specify images for different check box states.  Images are provided within a single bitmap.  They must be of the same size and placed next to each other within a row.  To let the TcxCustomCheckBox control know the number of images you should set the GlyphCount property.  Depending on this value the check box editor determines what image should be displayed based on its state.  The following table describes possible GlyphCount values:

Value	Meaning
0	A glyph is not used.  The standard check box is displayed.
1	A full size image is displayed instead of the check box.
2	The Glyph bitmap contains two parts (images).  The first image is used to represent the unchecked state.  The second image represents the checked state.
3	The Glyph bitmap contains three parts (images).  They represent the unchecked, checked, and grayed states respectively.
6	The Glyph bitmap contains six parts (images).  The first, second and third images represent the unchecked, checked and grayed states respectively when the check box is not pressed.  Other three images represent the same states when the check box is pressed.

The default value of the GlyphCount property is 6.


TcxCustomCheckBoxProperties.MultiLine

TcxCustomCheckBoxProperties          See Also

Determines whether the check box caption is drawn across several lines.

property MultiLine: Boolean;

Description

Set the MultiLine property to True to enable check box text wrapping.  Otherwise, text is drawn in a single line.  To set the check box text, use the Caption property.

The default value of the MultiLine property is False.


TcxCustomCheckBoxProperties.NullStyle

TcxCustomCheckBoxProperties          See Also

Specifies the manner in which a check box editor presents NULL values.

type

  TcxCheckBoxNullValueShowingStyle = (nssUnchecked, nssInactive, nssGrayedChecked);

property NullStyle: TcxCheckBoxNullValueShowingStyle;

Description

If the EditValue property of the TcxCustomCheckBox control specifies NULL, the check box is drawn in the manner defined by the NullStyle property.  Possible styles to represent NULL values are enumerated by the TcxCheckBoxNullValueShowingStyle type.

The default value of the NullStyle property is nssGrayedChecked.


TcxCustomCheckBoxProperties.UseAlignmentWhenInplace

TcxCustomCheckBoxProperties

Specifies the manner in which the check box and caption are aligned within an in-place checkbox editor.

property UseAlignmentWhenInplace: Boolean;

Description

By default, the caption is not drawn within in-place checkbox editors and the check box is painted in the center of the editors.  In order to specify that the check box and caption are aligned according to the Alignment property’s value, set the UseAlignmentWhenInplace property to True.

The default value of the UseAlignmentWhenInplace property is False.


TcxCustomCheckBoxProperties.ValueChecked

TcxCustomCheckBoxProperties          See Also

Specifies the value the EditValue property returns when in the checked state.

type

  TcxEditValue = Variant;

property ValueChecked: TcxEditValue;

Description

If the check box editor is in the checked state, the EditValue property returns the value defined by the ValueChecked member.  In case of other check box states the EditValue property returns ValueGrayed or ValueUnchecked.

A data aware check box editor (the TcxDBCheckBox control) posts a ValueChecked, ValueUnchecked or ValueGrayed property value in case of the corresponding state (checked, unchecked or grayed).  Conversely, when the data aware check box editor retrieves data from the dataset, it is set to one of the abovementioned states:

•	the checked state if the field specifies the ValueChecked property value;

•	the unchecked state if the field specifies the ValueUnchecked property value;

•	the grayed state if the field identifies neither the ValueChecked nor the ValueUnchecked property value.


TcxCustomCheckBoxProperties.ValueGrayed

TcxCustomCheckBoxProperties          See Also

Specifies the value the EditValue property returns when in the grayed state.

type

  TcxEditValue = Variant;

property ValueGrayed: TcxEditValue;

Description

If the check box editor is in the grayed state, the EditValue property returns the value defined by the ValueGrayed member.  For other check box states, the EditValue property returns ValueChecked or ValueUnchecked.

A data aware check box editor (the TcxDBCheckBox control) posts a ValueChecked, ValueUnchecked or ValueGrayed property value in case of the corresponding state (checked, unchecked or grayed).  Conversely, when the data aware check box editor retrieves data from the dataset, it is set to one of the abovementioned states:

•	the checked state if the field specifies the ValueChecked property value;

•	the unchecked state if the field specifies the ValueUnchecked property value;

•	the grayed state if the field identifies neither the ValueChecked nor the ValueUnchecked property value.


TcxCustomCheckBoxProperties.ValueUnchecked

TcxCustomCheckBoxProperties          See Also

Specifies the value the EditValue property returns when in the unchecked state.

type

  TcxEditValue = Variant;

property ValueUnchecked: TcxEditValue;

Description

If the check box editor is in the unchecked state, the EditValue property returns the value defined by the ValueUnchecked member.  For other check box states, the EditValue property returns ValueGrayed or ValueChecked.

A data aware check box editor (the TcxDBCheckBox control) posts a ValueChecked, ValueUnchecked or ValueGrayed property value in case of the corresponding state (checked, unchecked or grayed).  Conversely, when the data aware check box editor retrieves data from the dataset, it is set to one of the abovementioned states:

•	the checked state if the field specifies the ValueChecked property value;

•	the unchecked state if the field specifies the ValueUnchecked property value;

•	the grayed state if the field identifies neither the ValueChecked nor the ValueUnchecked property value.


TcxCheckBoxNullValueShowingStyle
TcxCheckBoxNullValueShowingStyle type

Represents possible styles for representing NULL values by TcxCustomCheckBox controls.

Unit

cxCheckBox

type

  TcxCheckBoxNullValueShowingStyle = (nssUnchecked, nssInactive, nssGrayedChecked);

Description

The TcxCheckBoxNullValueShowingStyle type enumerates styles to represent NULL values by TcxCustomCheckBox controls.  To specify the manner in which NULL values are displayed use the TcxCustomCheckBoxProperties.NullStyle property.  The following table lists possible styles.

Value	Meaning
nssUnchecked	The check box is drawn unchecked.
nssInactive	The check box is drawn inactive.
nssGrayedChecked	The check box is drawn grayed.


TcxCheckBoxState
TcxCheckBoxState type

Represents states for the TcxCustomCheckBox editor.

Unit

cxCheckBox

type

  TcxCheckBoxState = (cbsUnchecked, cbsChecked, cbsGrayed);

  TcxCheckStates = array of TcxCheckBoxState;

Description

The TcxCheckBoxState class enumerates possible values for the check box state.  The check box state is set via the State property of the TcxCustomCheckBox class.  It affects the look & feel of the check box.  The following table describes TcxCheckBoxState values (screenshots are made using standard and Windows XP look & feel):

Value	Meaning
cbsUnchecked	The check box has no check mark, indicating that the user has not selected the option.
cbsChecked	The check box has a check mark in it, indicating that the user has selected the option.
cbsGrayed	The check box has a check mark in it, but it is grayed.


TcxCheckStatesValueFormat
TcxCheckStatesValueFormat type

Specifies the edit value format of a check box.

Unit

cxCheckBox

type

  TcxCheckStatesValueFormat = (cvfCaptions, cvfIndices, cvfInteger, cvfStatesString);

Description

The TcxCheckStatesValueFormat class enumerates possible interpretations of the check box state into the edit value.  The following options are available.

Value	Meaning
cvfCaptions	The edit value is a string containing two substrings delimited by a semicolon.  The substring before the semicolon contains the list of the grayed items’ captions.  The substring following the semicolon contains the list of the checked items’ captions.  Note that each caption is preceded by a number indicating the caption length.  The number is delimited from the corresponding caption by a colon. Edit value sample: ‘5:first;5:third6:fourth’
cvfIndices	The edit value is a string containing two substrings delimited by a semicolon.  The substring before the semicolon contains the comma-separated list of the grayed items’ indexes.  The substring following the semicolon contains the comma-separated list of the checked items’ indexes. Edit value sample: ‘0;2,3’
cvfInteger	The edit value is an integer representing the checked items’ bitwise combination.  Each check item corresponds to an integer that is a power of 2.  Thus, the items’ corresponding integers are 1, 2, 4, 8, 16, etc.  The edit value is the sum of integers corresponding to the checked items. Edit value sample: 12 (= 4 + 8)
cvfStatesString	The edit value is a string indicating the state of all items.  Each character in a string corresponds to a check item in the corresponding position.  The ‘0’, ‘1’ and ‘2’ characters correspond to the unchecked, checked and grayed states respectively. Edit value sample: ‘2011’
Samples in the table above are produced for the following check controls.

TcxCheckGroup	TcxCheckComboBox	TcxCheckListBox

Note:	Since the TcxCheckComboBox does not support grayed items, the values which correspond to these items are equal to zero and the edit values in this case will be as follows.

Value	Meaning
cvfCaptions	Edit value sample: ‘;5:third6:fourth’
cvfIndices	Edit value sample: ‘;2,3’
cvfInteger	Edit value sample: 12 (= 4 + 8)
cvfStatesString	Edit value sample: ‘0011’


CalculateCheckStates
CalculateCheckStates Function

Calculates the check box items’ check states for the specified edit value of a check box.

Unit

cxCheckBox

type

  TcxEditValue = Variant;

  TcxCheckBoxState = (cbsUnchecked, cbsChecked, cbsGrayed);

  TcxCheckStates = array of TcxCheckBoxState;

function CalculateCheckStates(const AValue: TcxEditValue; AItems: IcxCheckItems; AValueFormat: TcxCheckStatesValueFormat; var ACheckStates: TcxCheckStates): Boolean;

Description

The CalculateCheckStates function calculates the items’ check states for a particular edit value of the specified format and returns the successful result of the calculation.  This might be useful for data-aware editors.

The AValue and AValueFormat parameters represent the edit value for which the calculation is performed and its format, respectively.  The AItems parameter corresponds to the check box items whose states are checked (for instance, via the Properties.Items property of the check group box editor).  The instance of the TcxCheckStates type which will contain the check state values is passed as the ACheckStates parameter.

If successful, the result of the calculation is True and the ACheckStates parameter represents an array of check states which match the specified edit value.  Otherwise, the result is False.

Note:	The CalculateCheckStatesValues function represents the inverse operation for the CalculateCheckStates function.


CalculateCheckStatesValue
CalculateCheckStatesValue Function

Calculates the edit value by the check box items’ check states.

Unit

cxCheckBox

type

  TcxEditValue = Variant;

  TcxCheckBoxState = (cbsUnchecked, cbsChecked, cbsGrayed);

  TcxCheckStates = array of TcxCheckBoxState;

function CalculateCheckStatesValue(const ACheckStates: TcxCheckStates; AItems: IcxCheckItems; AValueFormat: TcxCheckStatesValueFormat): TcxEditValue;

Description

The CalculateCheckStatesValue function calculates the edit value in the specified format by the items’ check states and returns this value as the result.  This might be useful for data-aware editors (for example, when it is necessary to perform additional validation of the value prior to it being posted to a database).

The AValueFormat parameter represents the format of the calculated edit value.  The AItems parameter corresponds to the check box items whose states are checked (for instance, via the Properties.Items property of the check group box editor).  The ACheckStates parameter represents an array of check states which match the calculated edit value.

Note:	The CalculateCheckStates function represents the inverse operation for the CalculateCheckStatesValue function.


cxCheckComboBox Unit Overview
cxCheckComboBox Unit

Classes

TcxCheckComboBox

TcxCheckComboBoxItem

TcxCheckComboBoxItems

TcxCheckComboBoxProperties

TcxCustomCheckComboBox

TcxCustomCheckComboBoxProperties


TcxCheckComboBox
 TcxCheckComboBox Object

Hierarchy          Properties          Methods          Events

Represents a combo box which displays items with checkboxes, thus allowing the user to select one or several items.

Unit

cxCheckComboBox

TcxCheckComboBox = class(TcxCustomCheckComboBox)

Description

A TcxCheckComboBox control represents a combo box which can display items with checkboxes within the dropdown window.  This can be useful when the end-user needs to select several options from the dropdown at once.  For instance, in a time-scheduling application, you can use a check combo box with the names of weekdays allowing the end user to select one or more days.

A check combo box editor consists of the edit region and the check list box displayed in the dropdown.  The editor displays the selected items in its edit box.  Once you check/uncheck an item, it is automatically added to/removed from the edit box.  Edit box items are separated by delimiters (see the Properties.Delimiter property).  To specify descriptions for the items displayed in the edit box and the dropdown window of the check combo box, use the ShortDescription and Description properties of the items, correspondingly.

The following screenshot shows an editor with three items selected with the dropdown closed:

and when the dropdown is open:

The items’ check states are represented by the Value property, which stores an integer value.  This matches the editor’s edit value and consists of a bit for each item.  The first bit controls the checked state of the first item, the second bit specifies the state of the second item and so on.  An item is checked when the corresponding bit is set to 1.  Otherwise, the item is unchecked.

Suppose the Value is set to 10, represented by 1010 in binary notation.  This means that the second and the fourth items are displayed checked.  Other items are unchecked.  Do not use the Value property to set the editor’s value at run time, use the EditValue and States properties instead.  The States property also provides the CheckStates editor which lets you easily customize the check states of items at design time.

The CalculateCheckStatesValue and CalculateCheckStates methods let you calculate the editor’s edit value by the items’ check states and vice versa.

TcxCheckComboBox doesn’t introduce new functionality but publishes properties and methods of its ancestor (TcxCustomCheckComboBox).

You can use TcxCheckListBox for the same purposes as a TcxCheckComboBox editor.  However, the latter occupies less space on the form and provides an edit box displaying the selected options.


TcxCheckComboBox Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomComboBox

     |

TcxCustomCheckComboBox

     |


Properties for TcxCheckComboBox
TcxCheckComboBox Properties

TcxCheckComboBox          Legend

Derived from TcxCustomCheckComboBox

ActiveProperties

States

Value

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxCheckComboBox
TcxCheckComboBox Methods

TcxCheckComboBox          Legend

Derived from TcxCustomCheckComboBox

GetItemState

SetItemState

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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCheckComboBox
TcxCheckComboBox Events

TcxCheckComboBox          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCheckComboBoxItem
TcxCheckComboBoxItem Object

Hierarchy          Properties          See Also

Represents an individual item for a check combo box editor.

Unit

cxCheckComboBox

TcxCheckComboBoxItem = class(TcxButtonGroupItem)

Description

A TcxCheckComboBoxItem object represents an item for a check combobox editor.  Items denote available options and are displayed in the dropdown window of the editor.  To specify items, see its Properties.Items property.

The following screenshot shows a check combo box with three items selected:

An item provides properties that allow you to specify its text representation and enabled state.

At design time, you can create items by activating the items editor in the Object Inspector:

Clicking the ellipsis button activates the items editor:

Buttons at the top of the editor enable you to add, move and remove items.  Select item(s) and then switch to the Object Inspector in order to set their properties:

At run time, you create items using the Add method as follows:

//Delphi

procedure TForm1.Button1Click(Sender: TObject);

var

  Item: TcxCheckComboBoxItem;

begin

  Item := cxCheckComboBox1.Properties.Items.Add;

  Item.Description := 'Sunday';

  Item.ShortDescription := 'Sun';

end;

or using the AddCheckItem method as shown in the following code example:

//Delphi

procedure TForm1.Button1Click(Sender: TObject);

begin

  cxCheckComboBox1.Properties.Items.AddCheckItem('Sunday', 'Sun');

end;


TcxCheckComboBoxItem Hierarchy
Hierarchy

TCollectionItem

     |

TcxButtonGroupItem

     |


Properties for TcxCheckComboBoxItem
TcxCheckComboBoxItem Properties

TcxCheckComboBoxItem          Legend

In TcxCheckComboBoxItem

Description

ShortDescription

Derived from TcxButtonGroupItem

Caption

Enabled

Tag


TcxCheckComboBoxItem.Description

TcxCheckComboBoxItem          See Also

Specifies the string which represents an item in the dropdown window of a check combo box editor.

property Description: TCaption;

Description

The Description property enables you to specify the string which represents an item in the dropdown window of a check combo box editor.  To specify the description of an item in a check combo box, use the ShortDescription property.

Note that when the ShortDescription property is not set the Description property value is used to represent an item in a check combo box.

The following code changes the description of the first item displayed by the dropdown window.

//Delphi

procedure TForm1.Button1Click(Sender: TObject);

begin

  cxCheckComboBox1.Properties.Items[0].Description := 'Changed item';

end;


TcxCheckComboBoxItem.ShortDescription

TcxCheckComboBoxItem          See Also

Specifies the string that represents an item in the edit box of a check combo box.

property ShortDescription: TCaption;

Description

The ShortDescription property enables you to specify the string that represents an item in the edit box of a check combo box editor.  To specify the description of the item in the dropdown window of a check combo box, use the Description property.

Note that when the ShortDescription property is not set the Description property value is used instead to represent an item in the edit box.

The following code changes the description of the first item displayed in the edit box.

//Delphi

procedure TForm1.Button1Click(Sender: TObject);

begin

  cxCheckComboBox1.Properties.Items[0].ShortDescription := '<Changed >';

end;


TcxCheckComboBoxItems
TcxCheckComboBoxItems Object

Hierarchy          Properties          Methods             See Also

Represents a collection of items for a check combo box editor.

Unit

cxCheckComboBox

TcxCheckComboBoxItems = class(TcxButtonGroupItems)

Description

The TcxCheckComboBoxItems class represents a collection of items for a check combo box editor.  Each item specifies a TcxCheckComboBoxItem object and this allows you to specify the item’s caption and whether the item’s state can be changed at runtime.

To access the check box editor’s item collection, see its Properties.Items collection.


TcxCheckComboBoxItems Hierarchy
Hierarchy

TOwnedCollection

     |

TcxButtonGroupItems

     |


Properties for TcxCheckComboBoxItems
TcxCheckComboBoxItems Properties

TcxCheckComboBoxItems          Legend

In TcxCheckComboBoxItems

Items

Derived from TcxButtonGroupItems

Items


Methods for TcxCheckComboBoxItems
TcxCheckComboBoxItems Methods

TcxCheckComboBoxItems          Legend

In TcxCheckComboBoxItems

Add

AddCheckItem


TcxCheckComboBoxItems.Items

TcxCheckComboBoxItems

Provides access to individual items within the collection.

property Items[Index: Integer]: TcxCheckComboBoxItem;

Description

You can use the Items property to access a check box item and customize its properties.

The Index parameter specifies an integer value between 0 and Count – 1.

The following example replaces empty item captions with the ‘None’ string:

//Delphi

procedure TForm1.Button3Click(Sender: TObject);

var

  I: Integer;

begin

  with cxCheckComboBox1.Properties.Items do

  begin

    for I := 0 to Count - 1 do

      if Items[I].Description = '' then

        Items[I].Description := 'None';

  end;

end;


TcxCheckComboBoxItems.Add

TcxCheckComboBoxItems          See Also

Creates a new item and adds it to the items collection.

function Add: TcxCheckComboBoxItem;

Description

The Add function enables you to create a new item in the collection.  Use the object returned by this function to customize the item, i.e. specify its descriptions and enabled status.

The AddCheckItem method enables you to add a new item and initialize its Description and ShortDescription properties.

The following code creates three items in a check combo box editor and sets their description and enabled status as appropriate:

//Delphi

var

  I:Integer;

//...

with cxCheckComboBox1.Properties.Items do

begin

  Clear();

  for I := 0 to 2 do

  with Add do

    case I of

    0:

      begin

        Description := 'Sources';

        Enabled := False;

      end;

      1:

      begin

        Description := 'Demos';

        Enabled := True;

      end;

      2:

      begin

        Description := 'Documentation';

        ShortDescription := 'Docs';

        Enabled := True;

      end

    end;

end;


TcxCheckComboBoxItems.AddCheckItem

TcxCheckComboBoxItems          See Also

Creates a new item with the specified caption and adds it to the current collection.

function AddCheckItem(const ADescription: TCaption; const AShortDescription: TCaption = ''): TcxCheckComboBoxItem;

Description

The AddCheckItem function allows you to create a new item in the current collection and set its Description and ShortDescription properties.  The values used to initialize these properties are passed as the ADescription and AShortDescription parameters correspondingly.

You can use the AddCheckItem method as follows:

//Delphi

procedure TForm1.Button1Click(Sender: TObject);

begin

  cxCheckComboBox1.Properties.Items.AddCheckItem('New item', '<New>');

end;

The Add method allows you to add an item with an empty description and short description.  You should then use the item’s properties to specify its descriptions and enabled status.


TcxCheckComboBoxProperties
TcxCheckComboBoxProperties Object

Hierarchy          Properties          Methods          Events          See Also

Provides properties specific to check combo box controls.

Unit

cxCheckComboBox

TcxCheckComboBoxProperties = class(TcxCustomCheckComboBoxProperties)

Description

The TcxCheckComboBoxProperties class provides settings specific to check combo box controls.  To access these settings, see the TcxCustomCheckComboBox.Properties property.  To control any changes made to the control’s DisplayFormat, EditFormat, MaxLength, MaxValue, MinValue and ReadOnly properties and reverse their values back to the default ones, use the AssignedValues property.

The TcxCheckComboBoxProperties class doesn’t introduce new functionality but simply publishes properties inherited from base classes.  Refer to the TcxCustomCheckComboBoxProperties topic for more information.


TcxCheckComboBoxProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |

TcxCustomDropDownEditProperties

     |

TcxCustomComboBoxProperties

     |

TcxCustomCheckComboBoxProperties

     |


Properties for TcxCheckComboBoxProperties
TcxCheckComboBoxProperties Properties

TcxCheckComboBoxProperties          Legend

Derived from TcxCustomCheckComboBoxProperties

Delimiter

EditValueFormat

EmptySelectionText

Glyph

GlyphCount

Items

ShowEmptyText

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

IncrementalSearch

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 TcxCheckComboBoxProperties
TcxCheckComboBoxProperties Methods

TcxCheckComboBoxProperties          Legend

Derived from TcxCustomMaskEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults


Events for TcxCheckComboBoxProperties
TcxCheckComboBoxProperties Events

TcxCheckComboBoxProperties          Legend

Derived from TcxCustomComboBoxProperties

OnClickCheck

OnEditValueToStates

OnStatesToEditValue

Derived from TcxCustomComboBoxProperties

OnDrawItem

OnMeasureItem

Derived from TcxCustomDropDownEditProperties

OnCloseQuery

OnCloseUp

OnInitPopup

OnPopup

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomCheckComboBox
TcxCustomCheckComboBox Object

Hierarchy          Properties          Methods          Events

Represents the base class for check combo box controls.

Unit

cxCheckComboBox

TcxCustomCheckComboBox = class(TcxCustomComboBox)

Description

TcxCustomCheckComboBox implements the basic functionality of check combo box controls.  These controls let an end-user select one or more items in the dropdown window.

The check states of all items are stored in the Value property.  This matches the editor’s edit value and consists of a bit for each item.  Refer to the Value topic for more information.

Use TcxCustomCheckComboBox as a base class when implementing your own check combo box with custom behavior.

Do not create instances of the TcxCustomCheckComboBox class.  Instead use TcxCheckComboBox or its data-aware version (TcxDBCheckComboBox).


TcxCustomCheckComboBox Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomComboBox

     |


Properties for TcxCustomCheckComboBox
TcxCustomCheckComboBox Properties

TcxCustomCheckComboBox          Legend

In TcxCustomCheckComboBox

ActiveProperties

ItemIndex

Properties

States

Value

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading


Methods for TcxCustomCheckComboBox
TcxCustomCheckComboBox Methods

TcxCustomCheckComboBox          Legend

In TcxCustomCheckComboBox

SetItemState

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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCustomCheckComboBox
TcxCustomCheckComboBox Events

TcxCustomCheckComboBox          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCustomCheckComboBox.ActiveProperties

TcxCustomCheckComboBox          See Also

Obtains the properties that are currently applied to an editor.

property ActiveProperties: TcxCustomCheckComboBoxProperties;

Description

Use the ActiveProperties property to obtain the properties of the current editor that are currently in effect.  This property is especially useful when the 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 editor.  Otherwise, the inherent editor’s properties are returned.

ReadOnly Property


TcxCustomCheckComboBox.ItemIndex

TcxCustomCheckComboBox          See Also

Specifies the item to be selected when opening the dropdown window.

property ItemIndex: Integer;

Description

The ItemIndex property specifies the zero-based index of the item selected (highlighted) when opening the dropdown window.  This is useful when you want to suggest a default option to check.  Note that setting ItemIndex does not change the check state for the item.  To set an item’s check state, see the SetItemState method.

For instance, the following code selects the second item when the combobox is dropped down:

//Delphi

procedure TForm1.Button2Click(Sender: TObject);

begin

  cxCheckComboBox1.ItemIndex := 1;

end;

The following image illustrates this:


TcxCustomCheckComboBox.Properties

TcxCustomCheckComboBox

Provides access to settings specific to the check combobox control.

property Properties: TcxCustomCheckComboBoxProperties;

Description

Use the Properties property to access the TcxCustomCheckComboBoxProperties object, which provides settings specific to the check combobox control.  These allow you to specify the control’s items collection, the delimiter separating checked items in the edit box, etc.


TcxCustomCheckComboBox.States

TcxCustomCheckListBox

Specifies check states for individual check boxes.

type

  TcxCheckBoxState = (cbsUnchecked, cbsChecked, cbsGrayed);

property States[Index: Integer]: TcxCheckBoxState;

Description

Use the States property to obtain or change the check state of an individual item within the check combo box.  The item whose state is to be returned or modified is specified by its index via the Index parameter.  The first item’s index is zero.  The last item’s index is the number of items decremented by one.  Specifying an invalid item index will raise an exception.

Setting this property at design time invokes the "cxCheckComboBox – CheckStates editor" which helps you to customize the items’ check states.

Note:	Use the CalculateCheckStatesValue and CalculateCheckStates methods to calculate the editor’s edit value by the items’ check states and vice versa.


TcxCustomCheckComboBox.Value

TcxCustomCheckComboBox

This value represents the checked status of the items in the collection.

property Value: Variant;

Description

A check combo box control stores the check state of all its items in its Value property.  This consists of a bit for each item in the collection.  The first bit controls the check state of the first item, the second bit specifies the state of the second item and so on.  An item is checked when the corresponding bit is set to 1.  Otherwise, the item is unchecked.

Suppose the Value is set to 10, represented by 1010 in binary notation.  This means that the second and the fourth items are displayed checked.  Other items are unchecked.

The Value property is linked to the EditValue property, i.e. changing the Value property automatically changes EditValue and vice versa.

Although you can use the Value property to get/set states for particular items, it is mostly intended for internal use.  The GetItemState and SetItemState methods provide a more convenient way of managing item states.

Note:	Use the CalculateCheckStatesValue and CalculateCheckStates methods to calculate the editor’s edit value by the items’ check states and vice versa.


TcxCustomCheckComboBox.GetItemState

TcxCustomCheckComboBox          See Also

Returns the check state of an item.

type

  TcxCheckBoxState = (cbsUnchecked, cbsChecked, cbsGrayed);

function GetItemState(const AIndex: Integer): TcxCheckBoxState;

Description

The GetItemState function returns the state (checked or unchecked) of the specified item.  The item is addressed by the AIndex parameter, providing its position within the Properties.Items collection.

You can set the item’s state using the SetItemState method.

The Value property stores states of all items.  Each bit in this value corresponds to the state of a specific item.

Suppose you need to delete selected entries from your media library.  A check combo box is used to represent all the artists in your collection.  The end-user can select items no longer required (note that you can prevent individual items from being deleted by setting their Enabled state to False).  The following screenshot shows a check combo box with two items selected.

Now the user can press, say, a Delete button, to initiate the deletions. Your code for such an action may look like the following:

//Delphi

procedure TForm1.Button1Click(Sender: TObject);

var

  I: Integer;

begin

  with cxCheckComboBox1 do

  begin

    for I := Pred(Properties.Items.Count) downto 0 do

      if GetItemState(I) = cbsChecked then

      begin

        { some action }

        Properties.Items.Delete(I);

      end;

    Value := 0;

  end;

end;

Note:	As with all similar operations performing indexed deletions, the collection needs to be traversed in reverse order.


TcxCustomCheckComboBox.SetItemState

TcxCustomCheckComboBox          See Also

Sets the checked state of an item.

type

  TcxCheckBoxState = (cbsUnchecked, cbsChecked, cbsGrayed);

procedure SetItemState(const AIndex: Integer; AState: TcxCheckBoxState);

Description

The SetItemState method enables you to change the checked state of an item at runtime.  The item is addressed by the AIndex parameter specifying the item’s zero based position within the collection.  The new state is specified by the AState parameter.

The TcxCheckBoxState type provides three enumerated values (cbsUnchecked, cbsChecked and cbsGrayed) representing states for a check box control.  However, items within a check combo box control only support two states: checked and unchecked.  So if AState is cbsGrayed, the method does nothing.

The SetItemState method does not affect the enabled status of the item.  To get/set the item’s enabled state, use the Enabled property.

The end-user can toggle an item’s check state by clicking its check box in the dropdown window or by pressing the spacebar while the item is focused.  The following images show items with checked and unchecked states:

Checked item	Unchecked item

The text displayed in the edit box of the editor reflects the state of all checked items.  When you uncheck a specific item, it is automatically removed from the edit box.

To get the check state of a particular item, see the GetItemState method.

The following example checks the first item and unchecks the second:

//Delphi

MycxCheckComboBox.SetItemState(0, cbsChecked);

MycxCheckComboBox.SetItemState(1, cbsUnchecked);


TcxCustomCheckComboBoxProperties
TcxCustomCheckComboBoxProperties Object

Hierarchy          Properties          Methods          Events          See Also

Stores settings specific to check combo box controls.

Unit

cxCheckComboBox

TcxCustomCheckComboBoxProperties = class(TcxCustomComboBoxProperties)

Description

TcxCustomCheckComboBoxProperties serves as the base class for the TcxCheckComboBoxProperties class.  The latter just publishes properties and events introduced in TcxCustomCheckComboBoxProperties or its ancestors.

TcxCustomCheckComboBoxProperties provides settings specific to check combo box controls.  These allow you to specify the delimiter separating checked items in the edit box, the text displayed when no items are selected, etc.

You can access settings for a check combo box control via its Properties object.


TcxCustomCheckComboBoxProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |

TcxCustomDropDownEditProperties

     |

TcxCustomComboBoxProperties

     |


Properties for TcxCustomCheckComboBoxProperties
TcxCustomCheckComboBoxProperties Properties

TcxCustomCheckComboBoxProperties          Legend

In TcxCustomCheckComboBoxProperties

Delimiter

EditValueFormat

EmptySelectionText

Glyph

GlyphCount

Items

ShowEmptyText

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

IncrementalSearch

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 TcxCustomCheckComboBoxProperties
TcxCustomCheckComboBoxProperties Methods

TcxCustomCheckComboBoxProperties          Legend

Derived from TcxCustomComboBoxProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults


Events for TcxCustomCheckComboBoxProperties
TcxCustomCheckComboBoxProperties Events

TcxCustomCheckComboBoxProperties          Legend

In TcxCustomCheckComboBoxProperties

OnClickCheck

OnEditValueToStates

OnStatesToEditValue

Derived from TcxCustomComboBoxProperties

OnDrawItem

OnMeasureItem

Derived from TcxCustomDropDownEditProperties

OnCloseQuery

OnCloseUp

OnInitPopup

OnPopup

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomCheckComboBoxProperties.Delimiter

TcxCustomCheckComboBoxProperties

Specifies the delimiter separating checked items in the edit box.

property Delimiter: string;

Description

The Delimiter property allows you to specify the string used to separate checked items in the edit box.  By default, checked items are separated by semicolons.  However you can set Delimiter to any string depending on your needs.  The following screenshots show controls with two selected items separated by a semicolon and "@" character respectively:

Value	Sample
;
@

The following example sets Delimiter to the ‘-/-‘ string:

//Delphi

MycxCheckComboBox.Properties.Delimiter := ‘-/-‘;


TcxCustomCheckComboBoxProperties.EditValueFormat

TcxCustomCheckComboBoxProperties

Specifies the edit value format.

type

  TcxCheckStatesValueFormat = (cvfCaptions, cvfIndices, cvfInteger, cvfStatesString);

property EditValueFormat: TcxCheckStatesValueFormat;

Description

Use the EditValueFormat to specify how the editor interprets the states of the checked items into the edit value.  See the TcxCheckStatesValueFormat type description for the list of available options.

Note that you can provide a custom conversion from check states to the edit value.  To do so, you should handle the Properties.OnStatesToEditValue and Properties.OnEditValueToStates events.

The default value of the EditValueFormat property is cvfInteger.


TcxCustomCheckComboBoxProperties.EmptySelectionText

TcxCustomCheckComboBoxProperties          See Also

Specifies the text displayed in the control’s edit box when no items are checked.

property EmptySelectionText: string;

Description

The EmptySelectionText property specifies the string displayed in the edit box when no items are selected in the editor.  By default, EmptySelectionText specifies the ‘None selected’ string.

When some of items are checked, the control displays their captions in the edit box separated by Delimiter strings.

The following image shows a sample check combo box with no items selected and the EmptySelectionText property set to ‘Empty’:

Value	Sample
‘Empty’

You can disable displaying the string specified by the EmptySelectionText property.  For this purpose, set the ShowEmptyText property to False.

The following example sets the EmptySelectionText property to ‘Empty’ when a form is created.

//Delphi

procedure TForm1.FormCreate(Sender: TObject);

begin

  cxCheckComboBox1.Properties.EmptySelectionText := 'Empty';

end;


TcxCustomCheckComboBoxProperties.Glyph

TcxCustomCheckComboBoxProperties

Provides custom images for check boxes.

property Glyph: TBitmap;

Description

The Glyph property allows up to 4 custom images to be specified to represent various check box states.  These images are used for the unchecked, checked and pressed states of the check box.

The bitmap assigned to the Glyph property should contain the desired number of images arranged horizontally one after another.  Each image (a bitmap part) will be used for a particular check box state.  Note that the number of images supplied within the bitmap should be assigned to the GlyphCount property.  For instance, if the GlyphCount property’s value is 2, the bitmap supplied will be divided into two equal parts horizontally and these parts will be used to represent the unchecked and checked states, respectively.

Please refer to the GlyphCount property’s description for details.


TcxCustomCheckComboBoxProperties.GlyphCount

TcxCustomCheckComboBoxProperties          See Also

Specifies the number of images supplied by the Glyph bitmap.

property GlyphCount: Integer;

Description

The GlyphCount property should be used if you supply custom images for check states.  This property specifies the number of parts within the bitmap supplied by the Glyph property.  Each part, in turn, corresponds to a particular check state.  The following table describes the possible GlyphCount values:

Value	Meaning
0	A glyph is not used.  The standard check box is displayed.
1	A full size image is displayed instead of the check box.
2	The Glyph bitmap contains two parts (images).  The first image is used to represent the unchecked state.  The second image represents the checked state.
3	The Glyph bitmap contains three parts (images).  They represent the unchecked, checked, and grayed states respectively.
6	The Glyph bitmap contains six parts (images).  This represents the case when the same bitmap is used for both the check combo box controls and other controls which provide custom images for check states such as the check list box, check group, etc.  The first and second images represent the unchecked and checked states respectively when the check box is not pressed.  The fourth and fifth images represent the same states when the check box is pressed.
The default value of the GlyphCount property is 6.


TcxCustomCheckComboBoxProperties.Items

TcxCustomCheckComboBoxProperties

Specifies the collection of items to display in the dropdown window.

property Items: TcxCheckComboBoxItems;

Description

The Items property represents a collection of objects displayed in the list part of TcxCustomCheckComboBox descendants.  This provides access to individual items and their properties and allows you to add and remove individual elements.

At design time, you can manipulate check combo box control items using the standard collection editor, which can be activated via the Object Inspector:

Clicking the ellipsis button activates the items editor:

To add, move and remove items, use the buttons displayed at the top of the editor.

You can select item(s) in the editor and then switch to the Object Inspector in order to set properties:

At run-time, you create items using the Add and AddCheckItem methods.


TcxCustomCheckComboBoxProperties.ShowEmptyText

TcxCustomCheckComboBoxProperties          See Also

Defines whether the text specified by the EmptySelectionText property is displayed when no items are selected.

property ShowEmptyText: Boolean;

Description

The ShowEmptyText property specifies whether to display the text specified by the EmptySelectionText property when no items are checked.  By default, the ‘None selected’ string is displayed in the edit box in this case.

If ShowEmptyText is set to False, the control doesn’t display text when no items are checked.

The following screenshots show editors with the ShowEmptyText property set to True and False respectively:

Value	Image
True
False

The default value of the ShowEmptyText property is True.


TcxCustomCheckComboBoxProperties.OnClickCheck

TcxCustomCheckComboBoxProperties

Occurs when the user tries to toggle the state of an item.

type

  TcxCheckComboClickCheckEvent = procedure(Sender: TObject; var AllowToggle: Boolean) of object;

property OnClickCheck: TcxCheckComboClickCheckEvent;

Description

The OnClickCheck event allows you to control whether the state of an item can be changed when the user clicks it with the mouse or presses the space bar while it is focused.

The Sender parameter specifies the check combo box control initiating the event.  The AllowToggle parameter specifies whether the item’s state can be changed.  Set it to False to prevent toggling the item’s state.  Otherwise, the item’s state will be changed after executing your OnClickCheck event handler.

The item clicked is determined by the ItemIndex property.

Suppose you are releasing two versions of a program: one is a fully functional version for registered users and the other one is a demo version.  Your IsFullyFunctionalVersion function returns whether the program is fully functional or just a demo.  A check combo box control enables you to select components (Sources, Documentation, Demo programs) to include into the release package.

The demo version cannot include the Sources component.  So this item’s state is set to unchecked when building the demo package.  The demo version must always contain demo programs.  So the Demo item is checked.

In order to prevent toggling states of the Demo and Sources items, we handle the OnClickCheck event and set the AllowToggle parameter to False for these items.  The state of the Documentation item can be freely changed at runtime.

//Delphi

//Declare indexes for check combo box items

var

  FSourcesItemIndex, FDocItemIndex, FDemoItemIndex: Integer;

//...

//Add items for a check combo box

  with cxCheckComboBox1.Properties.Items do

  begin

    Clear;

    FSourcesItemIndex := AddCheckItem('Sources').Index;

    FDocItemIndex := AddCheckItem('Documentation').Index;

    FDemoItemIndex := AddCheckItem('Demos').Index;

  end;

  if not IsFullyFunctionalVersion then

  begin

    cxCheckComboBox1.SetItemState(FSourcesItemIndex, cbsUnchecked);

    cxCheckComboBox1.SetItemState(FDocItemIndex, cbsUnchecked);

    cxCheckComboBox1.SetItemState(FDemoItemIndex, cbsChecked);

  end;

procedure TForm1.cxCheckComboBox1ClickCheck(Sender: TObject; var AllowToggle: Boolean);

var

  ASelectedIndex: Integer;

begin

  ASelectedIndex := (Sender As TcxCheckComboBox).ItemIndex;

  if not IsFullyFunctionalVersion then

  begin

    if (ASelectedIndex = FSourcesItemIndex) OR (ASelectedIndex = FDemoItemIndex)

      then AllowToggle := False;

  end;

end;


TcxCustomCheckComboBoxProperties.OnEditValueToStates

TcxCustomCheckComboBoxProperties

Enables you to convert the edit value into a check state manually.

type

  TcxEditValue = Variant;

  TcxCheckBoxState = (cbsUnchecked, cbsChecked, cbsGrayed);

  TcxCheckStates = array of TcxCheckBoxState;

  TcxValueToCheckStatesEvent = procedure(Sender: TObject; const AValue: TcxEditValue; var ACheckStates: TcxCheckStates) of object;

property OnEditValueToStates: TcxValueToCheckStatesEvent;

Description

The OnEditValueToStates event fires each time the editor needs to update its check states (for instance, when changing the edit value).  You should handle this event if you use a check combo box control to display data stored in a format that is not supported by the control.  For the supported formats list, refer to the EditValueFormat topic.

Note that manual conversion of edit values to check states generally requires a custom conversion of check states to the edit value.  Otherwise, the control may not work correctly.  Thus, you will need to handle the OnEditValueToStates event in combination with the Properties.OnStatesToEditValue event.  There are cases, however, when you don’t need to handle the Properties.OnStatesToEditValue event.  For instance, you may want to display a data field’s values using a read-only check combo box editor.

The event’s Sender parameter specifies the editor whose edit value is converted to its check states.  The AValue parameter enables you to determine the new edit value.  The corresponding check states should be written to the ACheckStates parameter.


TcxCustomCheckComboBoxProperties.OnStatesToEditValue

TcxCustomCheckComboBoxProperties

Enables you to convert a check state into an edit value manually.

type

  TcxEditValue = Variant;

  TcxCheckBoxState = (cbsUnchecked, cbsChecked, cbsGrayed);

  TcxCheckStates = array of TcxCheckBoxState;

  TcxCheckStatesToValueEvent = procedure(Sender: TObject; const ACheckStates: TcxCheckStates; out AValue: TcxEditValue) of object;

property OnStatesToEditValue: TcxCheckStatesToValueEvent;

Description

The OnStatesToEditValue event fires each time the check states change (when an end user clicks individual check boxes or when the check states are changed via code using the control’s Value property).  Handle this event if none of the supported edit value formats suit your needs.  Note that in this case, you should also handle the Properties.OnEditValueToStates event.  Please refer to the latter event description for details.

The event’s Sender parameter specifies the editor whose check states are converted to edit value.  The ACheckStates parameter enables you to determine the current check states.  The corresponding edit value should be written to the AValue parameter.


cxCheckListBox Unit Overview
cxCheckListBox Unit

Classes

TcxCheckListBox

TcxCheckListBoxItem

TcxCheckListBoxItems

TcxCustomCheckListBox


TcxCheckListBox
 TcxCheckListBox Object

Hierarchy          Properties          Methods          Events

Represents a list box control that enables checking/un-checking of one or more items.

Unit

cxCheckListBox

TcxCheckListBox = class(TcxCustomCheckListBox)

Description

The TcxCheckListBox is similar to the standard list box control, but it also displays a check box for every item, thus allowing a user to select and unselect items.

This can be useful when you need let the end-user select several options at once.  For instance, in a time-scheduling application, you can use a list box with names of weekdays allowing the end user to select day(s) for a particular event.

To specify items for the check list box, see its Items collection.

It is possible to display items in a grayed state by setting the AllowGrayed property to True.

The CalculateCheckStatesValue and CalculateCheckStates methods let you calculate the editor’s edit value by the items’ check states and vice versa.


TcxCheckListBox Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomCheckListBox

     |


Properties for TcxCheckListBox
TcxCheckListBox Properties

TcxCheckListBox          Legend

Derived from TcxCustomCheckListBox

AllowDblClickToggle

AllowGrayed

AutoComplete

AutoCompleteDelay

Columns

Count

EditValue

EditValueFormat

Glyph

GlyphCount

ImageLayout

Images

IntegralHeight

ItemIndex

Items

ReadOnly

ScrollWidth

Selected

ShowChecks

Sorted

TopIndex

Derived from TcxContainer

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName

Derived from TControl

Align


Methods for TcxCheckListBox
TcxCheckListBox Methods

TcxCheckListBox          Legend

Derived from TcxCustomCheckListBox

 Clear

 CopySelection

 DeleteSelected

 ItemAtPos

 ItemRect

 MoveSelection

 Sort

Derived from TcxControl

 Create

 Destroy

 InvalidateRect


Events for TcxCheckListBox
TcxCheckListBox Events

TcxCheckListBox          Legend

Derived from TcxCustomCheckListBox

 OnClickCheck

 OnDrawItem

 OnEditValueChanged

 OnEditValueToCheckStates

 OnMeasureItem

 OnCheckStatesToEditValue


TcxCustomCheckListBox
TcxCustomCheckListBox Object

Hierarchy          Properties          Methods          Events

Represents the base class for check list box controls.

Unit

cxCheckListBox

TcxCustomCheckListBox = class(TcxContainer)

Description

The TcxCustomCheckListBox implements the basic functionality of a check list box control.  Do not create instances of the TcxCustomCheckListBox class.  Instead, use its descendants such as TcxCheckListBox and TcxDBCheckListBox.

A check list box is a control which gives the user the ability to select and unselect several items/options.

Each item can have two or three states.  If the AllowGrayed property is False, the item can only be checked and unchecked.  If AllowGrayed is True, each item can be set to one of three states (checked, unchecked or grayed).  The grayed state can be thought of as an indeterminate state.

Use TcxCustomCheckListBox as the base class when creating custom check list boxes.


TcxCustomCheckListBox Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |


Properties for TcxCustomCheckListBox
TcxCustomCheckListBox Properties

TcxCustomCheckListBox          Legend

In TcxCustomCheckListBox

AllowDblClickToggle

AllowGrayed

AutoComplete

AutoCompleteDelay

Columns

Count

EditValue

EditValueFormat

Glyph

GlyphCount

ImageLayout

Images

IntegralHeight

ItemIndex

Items

ReadOnly

ScrollWidth

ShowChecks

Selected

Sorted

TopIndex

Derived from TcxContainer

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading


Methods for TcxCustomCheckListBox
TcxCustomCheckListBox Methods

TcxCustomCheckListBox          Legend

In TcxCustomCheckListBox

 Clear

 CopySelection

 DeleteSelected

 ItemAtPos

 ItemRect

 MoveSelection

 Sort

Derived from TcxControl

 Create

 Destroy

 InvalidateRect


Events for TcxCustomCheckListBox
TcxCustomCheckListBox Events

TcxCustomCheckListBox          Legend

In TcxCustomCheckListBox

 OnClickCheck

 OnDrawItem

 OnEditValueChanged

 OnEditValueToCheckStates

 OnMeasureItem

 OnCheckStatesToEditValue


TcxCustomCheckListBox.AllowDblClickToggle

TcxCustomCheckListBox

Specifies whether the end-user can toggle an item’s state by double-clicking the item’s caption.

property AllowDblClickToggle: Boolean;

Description

If the AllowDblClickToggle property is set to True, the end-user can change the item’s state by double-clicking the item’s caption.  If AllowDblClickToggle is False, the user can only toggle the item’s state by clicking the item’s check box or by pressing the spacebar when the item is focused.

The default value of the AllowDblClickToggle property is True.


TcxCustomCheckListBox.AllowGrayed

TcxCustomCheckListBox          See Also

Enables list box items to be in one of three states (enabled, disabled and grayed).

property AllowGrayed: Boolean;

Description

The AllowGrayed property enables a user to set items into a grayed state.  If AllowGrayed is set to False, items can only be checked or unchecked.  If AllowGrayed is True, items can also be grayed (i.e. an indeterminate state).

Note:	To provide support for grayed items in an editor, set its EditValueFormat property to a value other than a cvfInteger value.

An end-user can switch state by clicking the item’s check box or by pressing the spacebar when the item is focused.

The following images display list boxes with the first four items in grayed state.  Screenshots were made using XP and classic Windows schemes:

To get the state of a specific item, see its State property.

Suppose you have a catalog of documents and you want to revise them by deleting outdated and unnecessary documents.  A check list box control displays all available documents.  A user can check items and then click, say a Delete button, in order to delete the corresponding documents.  Unchecked items will not be affected.  If items are set to the grayed state, a dialog will appear to confirm the delete operation.

The code to delete the selected documents can be implemented as follows:

procedure TForm1.ButtonDeleteClick(Sender: TObject);

var

  I: Integer;

  ADelete: Boolean;

begin

  for I := Pred(cxCheckListBox1.Items.Count) downto 0 do

  begin

    ADelete := False;

    case cxCheckListBox1.State[I] of

      cbsUnchecked: ;

      cbsChecked: ADelete := True;

      cbsGrayed:

        if MessageDlg('Delete ' + cxCheckListBox1.Items[I] + '?',

        mtConfirmation, [mbYes, mbNo], 0) = mrYes then

          ADelete := True;

    end;

   if ADelete then

   begin

     cxCheckListBox1.Items.Delete(I);

     {some actions}

   end;

  end;

end;

The default value of the AllowGrayed property is False.


TcxCustomCheckListBox.AutoComplete

TcxCustomCheckListBox

Specifies whether the end-user can focus items by typing in the list box.

property AutoComplete: Boolean;

Description

The AutoComplete property provides an incremental search feature.  If AutoComplete is set to True, typing within the list box focuses the item which starts with the characters typed.  If the property is set to False, characters typed are ignored.

Suppose you have a list box control displaying a list of countries.

Pressing the ‘u’ character focuses the ‘Ukraine’ item.

Then pressing the ‘s’ character focuses the ‘USA’ item as it starts with the characters typed (‘us’)


TcxCustomCheckListBox.AutoCompleteDelay

TcxCustomCheckListBox

Specifies the time interval (in milliseconds) during which any additional key presses that are made will be treated as an addition to the filter string used in the incremental search.

property AutoCompleteDelay: Cardinal;

Description

This property is in effect only when the incremental search feature is on (the AutoComplete property is set to True).  Any successive keystroke that are made within the time specified by the AutoCompleteDelay property will be treated as an addition to the filter string used in the incremental search.  When the number of milliseconds specified by the AutoCompleteDelay property has passed, the filter string is reset so that it consists only of the last key pressed.

The default value of this property is specified by the cxDefaultAutoCompleteDelay global constant.


TcxCustomCheckListBox.Columns

TcxCustomCheckListBox

Defines the number of columns visible within the checklist box.

property Columns: Integer;

Description

A list box control enables you to display items within multiple columns.  The Columns property specifies the number of columns displayed within the control.

If Columns is set to 0, all items are displayed in a single column and a vertical scrollbar is used to navigate through items.

If Columns is set to a value greater than 0, the vertical scroll bar is hidden and items are placed down then across.  The number of visible columns is specified by the current Columns property value.  If all items cannot be displayed within the visible portion of the list box, a horizontal scroll bar is displayed thus allowing scrolling.  The following screenshot shows a list box with the Columns property set to 2:


TcxCustomCheckListBox.Count

TcxCustomCheckListBox

Returns the number of items displayed in the checklist box.

property Count: Integer;

Description

Read the Count property to determine the number of items displayed in the checklist box. This property is useful when you need to iterate all the control’s items, for instance.  See the Items property to access individual items.

The following example demonstrates how to check all items at run-time:

//Delphi

var

  I: Integer;

//...

  for i:=0 to cxCheckListBox1.Count-1 do

    cxCheckListBox1.Checked[i] := True;

Below is the result of running this code for a sample check list box.


TcxCustomCheckListBox.EditValue

TcxCustomCheckListBox          See Also

An overall value representing the state of all the check list box’s items.

type

  TcxEditValue = Variant;

property EditValue: TcxEditValue;

Description

The EditValue property specifies an integer number representing the combined state of all items within the check list box.  Each bit in the edit value defines the state of the corresponding item in the Items collection.  The first bit corresponds to the first item.  If it is set to 0, the first item is unchecked, i.e. the Items[0].State statement returns cbsUnchecked.  Otherwise, the item is checked and the Items[0].State statement returns cbsChecked.  Similarly if you change the state of a particular item, the corresponding bit in the edit value is automatically toggled.

You cannot change the edit value if the AllowGrayed property is set to True.  In this case, you can only change an item’s state via its State property.

If an item is set to grayed, the corresponding bit in the edit value is set to 0.

Suppose that the EditValue is set to 10, i.e. 1010 in binary notation.  The second and the fourth items will be displayed checked and other items are unchecked.

Note:	This property is obsolete.  Do not use the EditValue property to set the states of the check list box’s items at design time, set their State properties instead.


TcxCustomCheckListBox.EditValueFormat

TcxCustomCheckListBox

Specifies the edit value format.

type

  TcxCheckStatesValueFormat = (cvfCaptions, cvfIndices, cvfInteger, cvfStatesString);

property EditValueFormat: TcxCheckStatesValueFormat;

Description

Use the EditValueFormat to specify how the editor interprets the checked items’ states into the edit value.  See the TcxCheckStatesValueFormat type description for the list of available options.

Note that you can provide a custom conversion from check states to the edit value.  To do so, you should handle the OnCheckStatesToEditValue and OnEditValueToCheckStates events.

The default value of the EditValueFormat property is cvfInteger.

Note:	To provide support for grayed items in an editor, set its EditValueFormat property to a value other than a cvfInteger value.


TcxCustomCheckListBox.Glyph

TcxCustomCheckListBox          See Also

Specifies the image to display instead of standard check boxes.

property Glyph: TBitmap;

Description

The Glyph property specifies the bitmap to represent different item states.  If Glyph is not assigned a bitmap, standard check boxes are used.

It is possible to provide up to six images within a single bitmap.  These images correspond to different item states.  All images must be of the same size and placed next to each other within a row.  You also have to specify the number of images in the Glyph using the GlyphCount property.  Refer to this property for more information.

The following image shows a sample bitmap that you can assign to the Glyph property:

This consists of three images used to represent the unchecked, checked and grayed states respectively.  So the GlyphCount property must be set to 3.  The next image shows a combo box editor using this.  The second item is grayed.  Items 5 and 6 are checked.  Other elements are unchecked:


TcxCustomCheckListBox.GlyphCount

TcxCustomCheckListBox          See Also

Specifies the number of images within the bitmap referenced by the Glyph property.

property GlyphCount: Integer;

Description

By using the Glyph property, it is possible to specify custom images for different check box states.  Images are provided within a single bitmap.  They must be of the same size and placed next to each other within a row.  See the Glyph topic for a screenshot of a combo box editor after applying a sample glyph.

Set the GlyphCount property to inform the TcxCustomCheckListBox control of the number of images.  Depending on this value, the check box editor determines what image should be displayed for each item, depending on the latter’s state.  The following table describes the possible GlyphCount values.

Value	Meaning
0	A glyph is not used.  Standard check boxes are displayed.
1	A same (full size) image is displayed instead of the check box for each state.
2	The Glyph bitmap contains two parts (images).  The first image is used to represent the unchecked state.  The second image represents the checked state.
3	The Glyph bitmap contains three parts (images).  They represent the unchecked, checked, and grayed states respectively.
6	The Glyph bitmap contains six parts (images).  The first, second and third images represent the unchecked, checked and grayed states respectively when the check box is not pressed.  The other three images represent the same states when the check box is pressed.

The default value of the GlyphCount property is 6.


TcxCustomCheckListBox.ImageLayout

TcxCustomCheckListBox

Specifies where the images associated with check list box items are displayed relative to their corresponding check list box items.

type

  TcxCheckListBoxImageLayout = (ilBeforeChecks, ilAfterChecks);

property ImageLayout: TcxCheckListBoxImageLayout;

Description

Use the ImageLayout property to specify where the images designated by the Images property will be displayed within the check list box.

All the possible values for this property are listed in the following table.

Value	Meaning	Example
ilBeforeChecks	Images are displayed before checks.
ilAfterChecks	Images are displayed after checks.

The default value of the ImageLayout property is ilBeforeChecks.


TcxCustomCheckListBox.Images

TcxCustomCheckListBox

Specifies the images list which will be used as the source for the small images displayed along with check list box items.

property Images: TCustomImageList;

Description

The Images property specifies the TCustomImageList object which contains the images that are displayed adjacent to check list box items.  To assign an image to an item, edit the item’s ImageIndex property.  If no image is required for an item, set the property's value to –1 (the default value).  Use the ImageLayout property to specify the position where the images will be displayed relative to their corresponding check list box items.

The following screenshot shows the check list box control which contains three items displaying custom images:


TcxCustomCheckListBox.IntegralHeight

TcxCustomCheckListBox

Specifies whether the list box can display partial items.

property IntegralHeight: Boolean;

Description

The height of the control can be such that the last visible item in the list box is only partially displayed.  The IntegralHeight property enables you to avoid displaying partial items.

If the value of the IntegralHeight property is equal to False, the control’s height can be set to any value, but the last item may not be fully displayed.

The following screenshots show list boxes with the IntegralHeight property set to False and True, respectively.

Property’s Value	Image
False
True


TcxCustomCheckListBox.ItemIndex

TcxCustomCheckListBox          See Also

Specifies the index of the selected (focused) item.

property ItemIndex: Integer;

Description

The ItemIndex property specifies the zero-based index of the focused item.  This returns a value between 0 and Count – 1.

You can assign ItemIndex, for instance, to offer the end-user a default option to select.


TcxCustomCheckListBox.Items

TcxCustomCheckListBox

Specifies a collection of items in the current list box.

property Items: TcxCheckListBoxItems;

Description

The Items property provides access to individual items displayed by the check list box control.  This allows adding, removing and customizing items depending on your needs.  You can return the total number of items via the Count property.

Each item represents an object of the TcxCheckListBoxItem class.  You can use TcxCheckListBoxItem properties to specify item’s text (caption), state, enabled status and object associated with it.


TcxCustomCheckListBox.ReadOnly

TcxCustomCheckListBox

Specifies whether end users can change the check states of items.

property ReadOnly: Boolean;

Description

Set the ReadOnly property to True to restrict end users from changing the check states of the items within the check list box control.  Otherwise, end users are able to toggle the check states of items in a standard manner.

The default value of the ReadOnly property is False.


TcxCustomCheckListBox.ScrollWidth

TcxCustomCheckListBox

Specifies the width (in pixels) by which end-users are allowed to scroll the list box horizontally.

property ScrollWidth: Integer;

Description

The ScrollWidth property enables you to specify the width of a scrolling region.  This can be useful when items cannot be fully displayed because of the client control’s fixed width.  When the ScrollWidth is greater than the client width, a horizontal scroll bar appears in the checklist box.  When the ScrollWidth is less than or equal to the client width, the horizontal scroll bar disappears.

The following screenshots show a combo box editor with different values of the ScrollWidth property.

ScrollWidth is set to 0
ScrollWidth is set to 200 A scrollbar appears enabling horizontal scrolling.


TcxCustomCheckListBox.Selected

TcxCustomCheckListBox          See Also

Indicates whether a specific item is selected.

property Selected[Index: Integer]: Boolean;

Description

The Selected property specifies the selection status of an item in the checklist box.  If the item specified by the Index parameter is selected (highlighted) in the list box, the Selected property returns True. If the specified item is not selected, the property returns False.


TcxCustomCheckListBox.ShowChecks

TcxCustomCheckListBox

Indicates whether check boxes are displayed within a check list box.

property ShowChecks: Boolean;

Description

The ShowChecks property controls the visibility of check boxes which indicate the items’ state within a check list box.  Note that the item’s state can be changed by means of standard manipulations, though the result of these manipulations will not be displayed.

The table below shows the manner in which the ShowChecks property affects the check list box view.

Property’s Value	False	True

The default value of the ShowChecks property is True.


TcxCustomCheckListBox.Sorted

TcxCustomCheckListBox          See Also

Specifies whether list items are sorted alphabetically.

property Sorted: Boolean;

Description

Use the Sorted property to sort items in alphabetical order.  Set this property to True and items will be rearranged in alphabetical order within the list.  When adding items, they are automatically inserted into appropriate positions to preserve the sort order:

Setting the Sorted property to False does not revert the order. However, items added will not then be automatically placed into positions to preserve the sort order.


TcxCustomCheckListBox.TopIndex

TcxCustomCheckListBox

Specifies the index of the top visible item in the list box.

property TopIndex: Integer;

Description

The TopIndex property indicates the index of the item, which is currently displayed at the top of the list box.  This property allows you to scroll list boxes via code.

Initially the value of the TopIndex property is 0 meaning that the first item is displayed at the top of the checklist box.  When the user scrolls the list box vertically the TopIndex value is changed accordingly.

Property’s Value	Image
0 The January item is displayed at the top
1 The February item is displayed at the top


TcxCustomCheckListBox.Clear

TcxCustomCheckListBox          See Also

Removes all items from the checklist box.

procedure Clear;

Description

The Clear method deletes all items from the checklist box control.  After calling this method the Count property will return 0.

To delete individual items, use the Delete method provided by the item collection.


TcxCustomCheckListBox.CopySelection

TcxCustomCheckListBox          See Also

Copies selected items from the current checklist box to another list box control.

procedure CopySelection(ADestination: TcxCustomCheckListBox);

Description

Use CopySelection to copy selected items from the current list box to the specified one.  Selected items are those that are displayed highlighted.  See the Selected property to specify the selection state for specific items.

The ADestination parameter represents the check list box to which selected items should be copied.

Consider the following handler for the OnDblClick event of the source check list box control.  This copies the selected item when double-clicking the control to another check list box.

procedure TForm1.cxCheckListBox1DblClick(Sender: TObject);

begin

  cxCheckListBox1.CopySelection(cxCheckListBox2);

end;

The MoveSelection method enables you to copy selected items to another check list box while deleting them from the current control.


TcxCustomCheckListBox.DeleteSelected

TcxCustomCheckListBox          See Also

Removes selected items from the checklist box.

procedure DeleteSelected;

Description

Use the DeleteSelected method to remove selected items from the checklist box control.  Selected items are those that are displayed highlighted.  See the Selected property to specify item selection states.


TcxCustomCheckListBox.ItemAtPos

TcxCustomCheckListBox

Returns the index of the item at the specified coordinates.

function ItemAtPos(const APos: TPoint; AExisting: Boolean): Integer;

Description

The ItemAtPos function returns the index of the item at the specified position.  The APos parameter specifies the item’s coordinates relative to the top left corner of the control.  If the coordinates refer to a point outside the control’s bounds, the function returns –1.

The AExisting parameter determines the value returned when the specified point is within the list box, but does not refer to an existing item.  If AExisting is True, the function will return valid indexes only if the point belongs to an existing item.  Otherwise, the function returns –1.  If AExisting is False and the point does not belong to an existing item, the function will return the index of the last item in the list box plus one.

The following example shows how you can inform the user about the item currently located under the mouse cursor while moving over the list box.  A handler for the control’s OnMouseMove event is listed below:

procedure TForm1.cxCheckListBox1MouseMove(Sender: TObject;

  Shift: TShiftState; X, Y: Integer);

var

  ItemIndex: Integer;

begin

  ItemIndex := cxCheckListBox1.ItemAtPos(Point(X, Y), True);

  if ItemIndex <> -1 then

    StatusBar1.SimpleText := cxCheckListBox1.Items[ItemIndex];

end;


TcxCustomCheckListBox.ItemRect

TcxCustomCheckListBox

Returns the rectangle surrounding the specified item.

function ItemRect(Index: Integer): TRect;

Description

The ItemRect function returns the coordinates (starting position and size) of an item.  The item is referenced by the Index parameter and this specifies the item’s zero-based index (see the Items property).  If the parameter value is negative or exceeds the last available item index, an empty rectangle is returned (i.e. all coordinates are zeros).

ItemRect is mostly used internally, for instance, by the ItemAtPos method.


TcxCustomCheckListBox.MoveSelection

TcxCustomCheckListBox          See Also           Example

Moves selected items to the specified list box control.

procedure MoveSelection(ADestination: TcxCustomCheckListBox);

Description

The MoveSelection method copies selected items from the current check list box to the specified list box control and then deletes them from the current control.  The ADestination parameter specifies the list box to which selected items should be copied.

The CopySelection method enables you to copy selected items without removing them from the source list box.

See the Selected property to specify the selection state for specific items.


TcxCustomCheckListBox.Sort

TcxCustomCheckListBox          See Also

Sorts list items alphabetically.

property Sort;

Description

Use the Sort procedure to rearrange items in alphabetical order (by their captions) within the list.  A call to this Sort procedure does not change the check list box’s Sorted property value in any way thus items which are added after this call are placed according to the current Sorted property's value.


TcxCustomCheckListBox.OnClickCheck

TcxCustomCheckListBox

Occurs when the end-user toggles the state of a specific item.

type

  TcxClickCheckEvent = procedure(Sender: TObject; AIndex: Integer; APrevState, ANewState: TcxCheckBoxState) of object;

property OnClickCheck: TcxClickCheckEvent;

Description

The OnClickCheck event provides notification when an item’s state has changed.  The item clicked is identified by the AIndex parameter and this specifies the item’s zero-based index within the collection of items (see the Items property).  The new and old states are specified by the ANewState and APrevState parameters. Sender specifies the checklist box control itself.

Consider a check list box displaying four items corresponding to different font styles (bold, italic, underline and strikeout).  The end-user is able to check/uncheck items and thus control the font settings of a label displaying a sample string.

In the OnClickCheck event handler, call the custom ChangeFont procedure with parameters identifying the font attribute and its state.

//Create items and store their indexes to identify the clicked items

//in an OnClickCheck event handler

var

  FBoldIndex, FItalicIndex, FUnderlineIndex, FStrikeOutIndex: Integer;

//...

  with cxCheckListBox1.Items do

  begin

    with Add do

    begin

      Text := 'Bold';

      FBoldIndex := Index;

    end;

    with Add do

    begin

      Text := 'Italic';

      FItalicIndex := Index;

    end;

    with Add do

    begin

      Text := 'Underline';

      FUnderlineIndex := Index;

    end;

    with Add do

    begin

      Text := 'StrikeOut';

      FStrikeOutIndex := Index;

    end;

  end;

//The OnClickCheck event handler

procedure TForm1.cxCheckListBox1ClickCheck(Sender: TObject; AIndex: Integer; APrevState, ANewState: TcxCheckBoxState);

begin

  if AIndex = FBoldIndex then

    ChangeFont([fsBold], ANewState = cbsChecked)

  else

  if AIndex = FItalicIndex then

    ChangeFont([fsItalic], ANewState = cbsChecked)

  else

  if AIndex = FUnderlineIndex then

    ChangeFont([fsUnderline], ANewState = cbsChecked)

  else

  if AIndex = FStrikeOutIndex then

    ChangeFont([fsStrikeOut], ANewState = cbsChecked)

end;

//Apply font changes to a label

procedure TForm1.ChangeFont(AFontChange: TFontStyles; AChecked: Boolean);

var

  AFont: TFont;

begin

  AFont := Label1.Font;

  if AChecked then

    AFont.Style := AFont.Style + AFontChange

  else

    AFont.Style := AFont.Style - AFontChange

end;

The following image shows a check list box with the Bold and Underline items checked.

The label, to which these font settings are applied has the following look:


TcxCustomCheckListBox.OnDrawItem

TcxCustomCheckListBox          See Also

Occurs when a checklist box item should be repainted.

type

  TDrawItemEvent = procedure(Control: TWinControl; Index: Integer; Rect: TRect; State: TOwnerDrawState) of object;

property OnDrawItem: TDrawItemEvent;

Description

You can handle the OnDrawItem event to perform custom painting of list box items.  This event is called for each list box item.  The check list box is passed as the Control parameter.  The canvas to perform custom draw can be obtained via the Canvas property of the control's InnerCheckListBox property.

The item to draw is passed by its index within the Items collection.  The area where you can draw is passed as the Rect parameter.  The AState parameter provides information on whether the current item is selected, focused, etc.

The following code shows an OnDrawItem handler.  Checked items are drawn using bold font.  Grayed items are drawn in gray.  Check boxes are also painted in a custom manner.  For each state, a different bitmap is drawn.  A result of custom draw is shown below:

var

  FBmpGrayed, FBmpChecked, FBmpUnchecked: TBitmap;

//...

//Load bitmaps representing item states

procedure TForm1.FormCreate(Sender: TObject);

begin

  FBmpGrayed := TBitmap.Create;

  FBmpGrayed.LoadFromFile('grayed.bmp');

  FBmpChecked := TBitmap.Create;

  FBmpChecked.LoadFromFile('checked.bmp');

  FBmpUnchecked := TBitmap.Create;

  FBmpUnchecked.LoadFromFile('unchecked.bmp');

end;

//Destroy images when disposing of the form

procedure TForm1.FormDestroy(Sender: TObject);

begin

  FBmpGrayed.Free;

  FBmpChecked.Free;

  FBmpUnchecked.Free;

end;

//OnDrawItem event handler

procedure TForm1.cxCheckListBox2DrawItem(Control: TWinControl;

  Index: Integer; Rect: TRect; State: TOwnerDrawState);

var

  ACanvas: TcxCanvas;

  AText: string;

  ATextRect: TRect;

  AGlyphWidth: Integer;

  AListBox: TcxCheckListBox;

  ACheckBmp: TBitmap;

  ACanvasFont: TFont;

  AItemState: TcxCheckBoxState;

  AItemEnabled: Boolean;

begin

  AListBox := (Control as TcxCheckListBox);

  ACanvas := AListBox.InnerCheckListBox.Canvas;

  ACanvasFont := ACanvas.Font;

  AItemState := AListBox.Items[Index].State;

  AItemEnabled := AListBox.Items[Index].Enabled;

  case AItemState of

    cbsUnchecked:

      begin

        ACheckBmp := FBmpUnchecked;

        ACanvasFont.Color := clBlack;

      end;

    cbsChecked:

      begin

        ACheckBmp := FBmpChecked;

        ACanvasFont.Style := [fsBold];

        ACanvasFont.Color := clBlack;

      end;

    cbsGrayed:

      begin

        ACheckBmp := FBmpGrayed;

        ACanvasFont.Color := clGray;

      end;

  end;

  ACanvas.Brush.Color := clWhite;

  ACanvas.FillRect(Rect);

  AGlyphWidth := ACheckBmp.Width;

  ACanvas.DrawGlyph(Rect.Left, Rect.Top, ACheckBmp, AItemEnabled);

  AText := AListBox.Items[Index].Text;

  ATextRect := Rect;

  ATextRect.Left := ATextRect.Left + 3 + AGlyphWidth;

  ACanvas.DrawTexT(AText, ATextRect, 0);

end;


TcxCustomCheckListBox.OnEditValueChanged

TcxCustomCheckListBox

Occurs on changing the control’s EditValue property.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnEditValueChanged: TNotifyEvent;

Description

The OnEditValueChanged event occurs after changing the control’s edit value.  This happens after assigning a new value to the EditValue property (only if AllowGrayed is set to False) or when the state of an item is changed (by the end-user or in your code).

Do not change the edit value in your OnEditValueChanged event handler, as this can result in stack overflow.  Use this event to get notification that the edit value has changed.


TcxCustomCheckListBox.OnMeasureItem

TcxCustomCheckListBox          See Also

Occurs when it is necessary to repaint an item.

type

  TMeasureItemEvent = procedure(Control: TWinControl; Index: Integer; var Height: Integer) of object;

property OnMeasureItem: TMeasureItemEvent;

Description

The OnMeasureItem event allows you to change the height of individual list box items.  This can be useful when you perform custom painting by handling the OnDrawItem event.  OnMeasureItem is called whenever an item should be repainted.  The default height is passed as the Height parameter.  You can assign another value to the parameter in order to change its height.

The item referenced by the event is identified by the AIndex parameter.  This represents the index of the item in the Items collection.  The editor itself is passed as the Control parameter.

Note:	This event is obsolete.  Do not use this event to specify the item’s height.


TcxCustomCheckListBox.OnEditValueToCheckStates

TcxCustomCheckListBox

Enables you to convert edit value to check states manually.

type

  TcxEditValue = Variant;

  TcxCheckBoxState = (cbsUnchecked, cbsChecked, cbsGrayed);

  TcxCheckStates = array of TcxCheckBoxState;

  TcxEditValueToCheckStatesEvent = procedure(Sender: TObject; const AEditValue: TcxEditValue; var ACheckStates: TcxCheckStates) of object;

property OnEditValueToCheckStates: TcxEditValueToCheckStatesEvent;

Description

The OnEditValueToCheckStates event fires each time the editor needs to update its check states (for instance, when changing the edit value).  You should handle this event if you use a check list box control to display data stored in a format that is not supported by the control.  For the supported formats list, refer to the EditValueFormat topic.

Note that manual conversion of edit values to check states generally requires a custom conversion of check states to the edit value.  Otherwise, the control may not work correctly.  Thus, you will need to handle the OnEditValueToCheckStates event in combination with the OnCheckStatesToEditValue event.  There are cases, however, when you don’t need to handle the OnCheckStatesToEditValue event.  For instance, you may want to display a data field’s values using a read-only check list box editor.

The event’s AEditValue parameter enables you to determine the new edit value.  The corresponding check states should be written to the ACheckStates parameter.

Note:	Use the CalculateCheckStatesValue and CalculateCheckStates methods to calculate the editor’s edit value by the items’ check states and vice versa.


TcxCustomCheckListBox.OnCheckStatesToEditValue

TcxCustomCheckListBox

Enables you to convert check states to the edit value manually.

type

  TcxEditValue = Variant;

  TcxCheckBoxState = (cbsUnchecked, cbsChecked, cbsGrayed);

  TcxCheckStates = array of TcxCheckBoxState;

  TcxCheckStatesToEditValueEvent = procedure(Sender: TObject; const ACheckStates: TcxCheckStates; out AEditValue: TcxEditValue) of object;

property OnCheckStatesToEditValue: TcxCheckStatesToEditValueEvent;

Description

The OnCheckStatesToEditValue event fires each time the check states change (when an end user clicks individual check boxes or when the check states are changed via code using the items’ State property or editor’s EditValue property).  Handle this event if none of supported edit value formats suits your needs.  Note that in this case, you should also handle the OnEditValueToCheckStates event.  Please refer to the latter event description for details.

The event’s ACheckStates parameter enables you to determine the current check states.  The corresponding edit value should be written to the AEditValue parameter.

Note:	Use the CalculateCheckStatesValue and CalculateCheckStates methods to calculate the editor’s edit value by the items’ check states and vice versa.


TcxCheckListBoxItem
TcxCheckListBoxItem Object

Hierarchy          Properties          See Also

Represents an item contained within a check list box control.

Unit

cxCheckListBox

TcxCheckListBoxItem = class(TCollectionItem)

Description

The TcxCheckListBoxItem class represents an item for check list box controls (descendants of the TcxCustomCheckListBox class).  You can access items via the Items property.

For each item, you can access its caption, checked state, enabled status and object associated with it.


TcxCheckListBoxItem Hierarchy
Hierarchy

TCollectionItem

     |


Properties for TcxCheckListBoxItem
TcxCheckListBoxItem Properties

TcxCheckListBoxItem          Legend

In TcxCheckListBoxItem

Checked

Enabled

ImageIndex

ItemObject

State

Tag

Text


TcxCheckListBoxItem.Checked

TcxCheckListBoxItem          See Also

Specifies whether the current item is checked or unchecked.

property Checked: Boolean;

Description

Use the Checked property to get and set the state of an item.  This property allows switching between the checked and unchecked states.  If you allow use of the grayed state, see the State property instead to specify the item’s state as this allows you to switch between checked, unchecked and grayed states.  Note: to enable the grayed state, set the control’s AllowGrayed property to True.

The Checked property returns True for the checked state and False for the unchecked and grayed states.

The following example shows how to toggle the state of the second item in a checklist box:

  cxCheckListBox1.Items[1].Checked := not cxCheckListBox1.Items[1].Checked;


TcxCheckListBoxItem.Enabled

TcxCheckListBoxItem

Specifies whether the state of the current item can be changed.

property Enabled: Boolean;

Description

The Enabled property specifies whether the item’s state can be changed by the end-user.  Disabled items appear grayed and the user cannot change their state by clicking or pressing the spacebar when items are focused.  However, the state of disabled items can be changed via code.

The default value of the Enabled property is True.


TcxCheckListBoxItem.ImageIndex

TcxCheckListBoxItem          See Also

Specifies the index of the image associated with a check list box item.

property ImageIndex: TImageIndex;

Description

The ImageIndex property enables you to display an image adjacent to an item.  The TCustomImageList object, providing the images for items is identified by the cxCheckListBox.Images property.  The default property value (-1) specifies that an item does not display an image.

The following screenshot shows the check list box control which displays an image with its first, second and third items:

	Property’s Value
	0 1 1 -1

The default value of the ImageIndex property is -1.


TcxCheckListBoxItem.ItemObject

TcxCheckListBoxItem          See Also

Specifies the object associated with the current item.

property ItemObject: TObject;

Description

Set the ItemObject property to associate an object with the current item.  Note that you have to provide complete management for the objects you that want to associate with items in a check list box.


TcxCheckListBoxItem.State

TcxCheckListBoxItem          See Also

Specifies the state of the current item.

type

  TcxCheckBoxState = (cbsUnchecked, cbsChecked, cbsGrayed);

property State: TcxCheckBoxState;

Description

Use the State property to programmatically change the state of the current item.

The item’s state is automatically changed when an end-user clicks the item with the mouse or presses the space bar when an item is focused.  This is True only for enabled items, i.e. for items with the Enabled property set to True.  If an item is disabled, its state can be changed only via code.

If the TcxCustomCheckListBox.AllowGrayed property is set to True, it is possible to switch between three states: checked, unchecked and grayed.  Otherwise, only two states are available: checked and unchecked.  In this case, you are not able to set State to cbsGrayed.  The cbsGrayed state will be substituted by cbsUnchecked.

Note:	To provide support for grayed items in an editor, set its EditValueFormat property to a value other than a cvfInteger value.

The default value of the State property is cbsUnchecked.

Note:	Use the CalculateCheckStatesValue and CalculateCheckStates methods to calculate the editor’s edit value by the items’ check states and vice versa.


TcxCheckListBoxItem.Tag

TcxCheckListBoxItem

Stores a value associated with the item.

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 items or when you need to have an additional item identification mechanism.


TcxCheckListBoxItem.Text

TcxCheckListBoxItem          See Also

Specifies the item’s caption.

property Text: TCaption;

Description

By default an item is created without a caption.  Use the Text property to specify the string used to represent the item in the check list box.

When the Sorted property is set to True, the check list control sorts items in the collection by their display text.  Also, when you change the item’s caption, it is automatically moved to the appropriate position to maintain the sort order.  When Sorted is False, changing the item’s caption does not affect the item’s position in the collection.


TcxCheckListBoxItems
TcxCheckListBoxItems Object

Hierarchy          Properties          Methods          See Also

Represents a collection of items for a check list box control.

Unit

cxCheckListBox

TcxCheckListBoxItems = class(TCollection, IcxCheckItems);

Description

The TcxCheckListBoxItems class encapsulates a collection of items for check list box controls (descendants of the TcxCustomCheckListBox class).  Use the control’s TcxCustomCheckListBox.Items property to access the item collection.

TcxCheckListBoxItems provides methods to add, remove and access individual items.  Items in the collection represent TcxCheckListBoxItem objects.  For each item, you can specify its state, text, enabled status and object associated with it.


TcxCheckListBoxItems Hierarchy
Hierarchy

TCollection

     |


Properties for TcxCheckListBoxItems
TcxCheckListBoxItems Properties

TcxCheckListBoxItems          Legend

In TcxCheckListBoxItems

Items

Objects


Methods for TcxCheckListBoxItems
TcxCheckListBoxItems Methods

TcxCheckListBoxItems          Legend

In TcxCheckListBoxItems

 Add

 Delete

 IndexOf


TcxCheckListBoxItems.Items

TcxCheckListBoxItems

Provides access to individual items within the collection.

property Items[Index: Integer]: TcxCheckListBoxItem;

Description

Use the Items property to access individual items within the collection.  For each item, you can specify its checked state, text and enabled status.

To add items to the collection, use the Add method.  The Delete method enables you to delete specific items.  The IndexOf method lets you get a particular item’s index position within the collection by its caption.


TcxCheckListBoxItems.Objects

TcxCheckListBoxItems          See Also

Lists the objects associated with each item within the collection.

property Objects[Index: Integer]: TObject;

Description

Use the Objects property to access the object associated with a particular item within the collection.  Each item has a corresponding ItemObject property to refer to the object associated with it.

Note:	The TcxCheckListBoxItems collection does not own the objects in the Objects list.  Objects added to the Objects property still exist even if the collection is destroyed.  They must be explicitly destroyed by the application.


TcxCheckListBoxItems.Add

TcxCheckListBoxItems

Adds a new item to the current collection.

function Add: TcxCheckListBoxItem;

Description

The Add method creates a new item within the current collection.  Add returns a new item object and this allows you to customize the item (set its text, state, and enabled status).

Individual items can be accessed via the Items property.

At design time you can add items by invoking the item editor for the TcxCustomCheckListBox.Items property by using the Object Inspector.

The following code adds three items for a check list box control and set their properties as appropriate:

  with cxCheckListBox1.Items.Add do

  begin

    Text := 'Sources';

    Enabled := False;

    State := cbsChecked;

  end;

  with cxCheckListBox1.Items.Add do

  begin

    Text := 'Demos';

    State := cbsGrayed;

  end;

  with cxCheckListBox1.Items.Add do

  begin

    Text := 'Documentation';

  end;


TcxCheckListBoxItems.Delete

TcxCheckListBoxItems          See Also

Deletes the specified item from the collection.

procedure Delete(Index: Integer);

Description

The Delete method allows you to delete specific items via code.  The Index parameter specifies the item’s index to delete.  Index can vary between 0 and Count – 1.

The list box’s Clear method lets you delete all items from the collection.

To delete only selected (highlighted) items, see the control’s DeleteSelected method.


TcxCheckListBoxItems.IndexOf

TcxCheckListBoxItems          See Also

Returns the index position of an item in the current collection.

function IndexOf(const S: TCaption): Integer;

Description

The IndexOf function returns the zero-based index position of the item whose caption matches the string representation specified by the S parameter.  Otherwise, it returns -1.  The text comparison is case insensitive.


Example: TcxCustomCheckListBox.MoveSelection

Consider an example of implementing drag-and-drop from the source check list box to another check list box control.  During drag-and-drop, selected items are moved from one control into the destination control using the TcxCustomCheckListBox.MoveSelection method.

For the source check list box, we set the DragMode property to dmManual and start drag-and-drop in the OnMouseDown event.

procedure TForm1.cxCheckListBoxSourceMouseDown(Sender: TObject;

  Button: TMouseButton; Shift: TShiftState; X, Y: Integer);

begin

  (Sender as TcxCustomCheckListBox).BeginDrag(False);

end;

The BeginDrag method starts drag-and-drop when the user presses the control with the mouse button and then moves the mouse by holding the button down.  BeginDrag creates a drag object that is passed as a Source parameter in the OnDragOver and OnDragDrop events of the destination control.  The drag object refers to the control which initiates drag-and-drop.

For the destination check list box, you need to handle the OnDragOver and OnDragDrop events which are fired when the user moves and drops the dragged object respectively.

In our OnDragOver event handler, we need to enable dropping the dragged object if drag-and-drop was started in another checklist box control.  First we determine the type of the dragged object.  If drag-and-drop was initiated by any editor from the cxLibrary, the drag object specifies an instance of the TcxDragControlObject class.  Its Control property refers to the control itself.

procedure TForm1.cxCheckListBoxDestDragOver(Sender, Source: TObject; X,

  Y: Integer; State: TDragState; var Accept: Boolean);

begin

  if Source is TcxDragControlObject then

    with TcxDragControlObject(Source) do

      Accept := Control is TcxCustomCheckListBox;

end;

In the OnDragDrop event, we get the control that initiates the drag-and-drop operation and call its TcxCustomCheckListBox.MoveSelection method provided that the control represents a TcxCustomCheckListBox object.

procedure TForm1.cxCheckListBoxDestDragDrop(Sender, Source: TObject; X,

  Y: Integer);

begin

  if Source is TcxDragControlObject then

    with TcxDragControlObject(Source) do

      if Control is TcxCustomCheckListBox then

        (TcxCustomCheckListBox(Control)).MoveSelection(Sender as TcxCustomCheckListBox);

end;


cxColorComboBox Unit Overview
cxColorComboBox Unit

Classes

TcxColorComboBox

TcxColorComboBoxItem

TcxColorComboBoxItems

TcxColorComboBoxProperties

TcxCustomColorComboBox

TcxCustomColorComboBoxProperties


TcxColorComboBox
 TcxColorComboBox Object

Hierarchy          Properties          Methods          Events

Represents a color combo box control.

Unit

cxColorComboBox

TcxColorComboBox = class(TcxCustomColorComboBox)

Description

Use the TcxColorComboBox control to add a color combo box to your form.  With it, you can display a list of colors (with text descriptions), which can be selected via a dropdown window.  There are four predefined sets of colors provided and you can also create color sets manually.  Additionally, end-users can select custom colors using a standard or a custom color editing dialog.  The control also provides a ‘most recently used’ feature so that end-users can easily reuse recently selected colors.

The images below show sample appearances of the TcxColorComboBox control.

All the properties, methods and events of the color combo box control can be accessed via its Properties property, an instance of the TcxColorComboBoxProperties class.  Please refer to its description for a more detailed list of features and links to the members that provide this functionality.

If you need to use a data-aware color combo box control, please refer to the TcxDBColorComboBox control description for additional assistance.


TcxColorComboBox Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomComboBox

     |

TcxCustomColorComboBox

     |


Properties for TcxColorComboBox
TcxColorComboBox Properties

TcxColorComboBox          Legend

Derived from TcxCustomColorComboBox

ActiveProperties

ColorValue

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxColorComboBox
TcxColorComboBox Methods

TcxColorComboBox          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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxColorComboBox
TcxColorComboBox Events

TcxColorComboBox          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxColorComboBoxItem
TcxColorComboBoxItem Object

Hierarchy          Properties          Methods

Represents an item in the color combo box controls.

Unit

cxColorComboBox

TcxColorComboBoxItem = class(TCollectionItem)

Description

All items displayed by the color combo boxes are stored in its Properties.Items property.  This property is represented by a TcxColorComboBoxItems collection and contains a TcxColorComboBoxItem object for each item.  These objects are also used to represent items in the most recently used list of the color combo box.  This list can be accessed via the editor’s Properties.MRUColors property.

The TcxColorComboBoxItem class introduces two properties specifying item settings.  The Color property specifies the color represented by the item.  The Description property provides the explanatory text displayed for the color.  Note that you can disable the text display using the color combo’s Properties.ShowDescription property.

You can choose between two methods of populating the color combo with items:

1.	Add your own items and adjust their properties as needed.

2.	Load a predefined color set into the combo.

Note that in the second case, you can also access TcxColorComboBoxItem objects representing items and change their settings as needed.  Please refer to the TcxColorComboBoxItems class description for details on how to implement both methods.


TcxColorComboBoxItem Hierarchy
Hierarchy

TCollectionItem

     |


Properties for TcxColorComboBoxItem
TcxColorComboBoxItem Properties

TcxColorComboBoxItem          Legend

In TcxColorComboBoxItem

Color

Description

Tag


Methods for TcxColorComboBoxItem
TcxColorComboBoxItem Methods

TcxColorComboBoxItem          Legend

In TcxColorComboBoxItem

Assign

Create


TcxColorComboBoxItem.Color

TcxColorComboBoxItem          See Also

Specifies the color represented by the item.

property Color: TColor;

Description

Use the Color property to set or get the color represented by the item.  This property value is returned by the EditValue of the color combo box when the item is selected.  Also, a box populated with this color is displayed within the item (provided that the Properties.ColorBoxWidth property is set to a value greater than 0).

Note that if you set the Color property to one of the system colors, it may display differently on different computers.  This depends on how system colors are specified within the operating system.


TcxColorComboBoxItem.Description

TcxColorComboBoxItem          See Also

Specifies the text displayed within an item.

property Description: TCaption;

Description

Use the Description property to obtain or set the text displayed within an item.  This property is in effect only when the Properties.NamingConvention property of the editor is set to cxncNone.  Otherwise, the description of the item is automatically provided by the currently applied naming convention.  If there is no such color in the naming convention applied, the RGB code is displayed.  The format of the RGB color code is specified by the Properties.ColorValueFormat property.  These settings can be overridden by handling the Properties.OnNamingConvention event.

The text displayed within the editor when no color is selected is specified by the Properties.DefaultDescription property.

Note: you can disable the display of color descriptions by setting the Properties.ShowDescription property to False.


TcxColorComboBoxItem.Tag

TcxColorComboBoxItem

Stores a value associated with the item.

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 items or when you need to have an additional item identification mechanism.


TcxColorComboBoxItem.Assign

TcxColorComboBoxItem

Assigns settings of one color combo box item to another.

procedure Assign(Source: TPersistent); override;

Description

Use the Assign method to copy settings of one TcxColorComboBoxItem object to another.  The source object is specified by the Source parameter.  The caller is the destination object.

The Assign method is useful if you need to create a number of items with similar or the same settings.  In such an instance, you can customize a single item and then copy its settings to others.


TcxColorComboBoxItem.Create

TcxColorComboBoxItem

Creates a color combo box item.

procedure Create(Collection: TCollection); override;

Description

The constructor creates a new TcxColorComboBoxItem object and initializes its properties to default values.  Normally, you will have no need to use this constructor in applications.  To add a new item to the color combo box control, use the AddColor or InsertColor method of the TcxColorComboBoxItems collection.


TcxColorComboBoxItems
TcxColorComboBoxItems Object

Hierarchy          Properties          Methods

Holds the collection of items displayed by color combo box controls.

Unit

cxColorComboBox

TcxColorComboBoxItems = class(TOwnedCollection)

Description

The TcxColorComboBoxItems object holds two properties of the color combo box.  These are the Properties.Items and Properties.MRUColors properties that provide access to the entire list of items within the control together with its most recently used list.

There are several ways to populate the combo box with items.  The first is to add items manually.  This can be done using the Object Inspector (at design-time) or by calling the AddColor or InsertColor method of the TcxColorComboBoxItems object (at runtime).  In such an instance, the color combo box will display the specified set of items.  A second way is to leave the Properties.Items collection empty and set the editor’s Properties.NamingConvention property to a value other than cxncNone.  In this instance, the color combo box will be populated with the set of items specified by the Properties.NamingConvention property.  You can then add items or remove items from this list at runtime.  Use the TcxColorComboBoxItems object’s methods for this purpose.

End-users can add items to the color combo box.  Set the Properties.AllowSelectColor property of the editor to True for this purpose.  In this instance, the editor will display an ellipsis button to invoke the color editing dialog.  The selected color is added to the combo box (if not rejected by handling the OnSelectCustomColor event). The most recently used list is populated automatically when end-users select items.  However, you can still access this list programmatically and populate it with the desired colors or perform other actions that suit your specific needs.

The Assign method of the TcxColorComboBoxItems object can be used to copy the contents of one collection to another.  This can be useful if you need to provide a common list of items (or common most recently used lists) for multiple controls.

Items within the collection are represented by TcxColorComboBoxItem objects.  Please refer to this object’s description for details on item settings.


TcxColorComboBoxItems Hierarchy
Hierarchy

TOwnedCollection

     |


Properties for TcxColorComboBoxItems
TcxColorComboBoxItems Properties

TcxColorComboBoxItems          Legend

In TcxColorComboBoxItems

Items


Methods for TcxColorComboBoxItems
TcxColorComboBoxItems Methods

TcxColorComboBoxItems          Legend

In TcxColorComboBoxItems

AddColor

Assign

ClearCustom

ClearNonCustom

FindColorItem

GetColorByIndex

GetIndexByColor

InsertColor


TcxColorComboBoxItems.Items

TcxColorComboBoxItems

Provides indexed access to items displayed by the color combo box.

property Items[Index: Integer]: TcxColorComboBoxItem; default;

Description

Use the Items property to access an individual item within the color combo box.  The Index parameter specifies the index of the item to be obtained.  Item indexes are zero-based.  If the specified index is either negative or exceeds the last available item index, an exception is raised.  The index of the last available item is the Count property value decremented by one.

Note that you can omit the Items property since it is the default property for the TcxColorComboBoxItems class.

If you need to get the color of an item specified by its index or vice versa, consider using the GetColorByIndex and GetIndexByColor methods.


TcxColorComboBoxItems.InsertColor

TcxColorComboBoxItems          See Also

Inserts an item with the specified color and description within the collection.

function InsertColor(Index: Integer; const AColor: TColor; const ADescription: string): TcxColorComboBoxItem; virtual;

Description

Use the InsertColor method to insert a new item in the collection at a specified position.  The position of the inserted item is specified by the Index parameter.  If this parameter value is negative or exceeds the maximum available item position, an exception is raised.  The maximum available item position is specified by the Count property of the collection.  If the Index parameter value is the same as the value of this property, the item is added to the end of the collection.  Note that items can also be added to the end of the collection using the AddColor method.

The AColor parameter specifies the color represented by the inserted item and the ADescription parameter provides its textual description.  These values are assigned to the inserted item’s Color and Description properties, respectively.

If the AColor color item already exists within the list, the method does nothing and returns nil.  Otherwise, it returns a reference to the inserted item.


TcxColorComboBoxItems.Assign

TcxColorComboBoxItems          See Also

Assigns the contents of one item collection to another.

procedure Assign(ASource: TcxColorComboBoxItems);

Description

Use the Assign method to copy the contents of one item collection to another.  The ASource parameter specifies the source collection.  The caller is the destination collection.

The Assign method is useful if you need to provide a common list of items (or common most recently used list) for multiple controls.


TcxColorComboBoxItems.AddColor

TcxColorComboBoxItems          See Also

Adds a new item with the specified color and description.

function AddColor(const AColor: TColor; const ADescription: string): TcxColorComboBoxItem; virtual;

Description

Use the AddColor method to add a new item with the specified color and description.  The item is added to the end of the collection.  The AColor parameter specifies the color represented by the new item.  This value is assigned to the item’s Color property.  The ADescription parameter value specifies the description of the color.  This value is assigned to the item’s Description property.

Note: if an item is found within the list whose Color property matches the AColor parameter value, the method does nothing and returns nil.  Otherwise, a reference to the new item is returned.

To add an item at a specified position within the list, use the InsertColor method.


TcxColorComboBoxItems.ClearCustom

TcxColorComboBoxItems          See Also

Removes all the items which represent custom colors within the color combo box.

procedure ClearCustom; virtual;

Description

Call the ClearCustom procedure to remove all the items which represent custom colors within the color combo box.  As a result, the control’s Properties.CustomColors collection is emptied and the Properties.Items collection contains only the items from the corresponding predefined set.


TcxColorComboBoxItems.ClearNonCustom

TcxColorComboBoxItems          See Also

Removes all the items which represent non-custom colors within the color combo box.

procedure ClearNonCustom; virtual;

Description

Call the ClearNonCustom procedure to remove all the items which represent non-custom colors (from the predefined sets) within the color combo box.  As a result, the control’s Properties.Items collection contains only the items from the Properties.CustomColors collection.


TcxColorComboBoxItems.FindColorItem

TcxColorComboBoxItems          See Also

Returns an item representing a specified color.

function FindColorItem(const AColor: TColor): TcxColorComboBoxItem; virtual;

Description

Use the FindColorItem method to obtain the combo box item representing a specified color.  The color is specified by the AColor parameter.  If the specified color is not assigned to the Color property of any item, the method returns nil.  Otherwise, it returns a reference to the TcxColorComboBoxItem object representing the item.

The FindColorItem method is useful if you want direct access to the item representing the specified color.  For instance, you may want to change the description of the black color item.  The code below allows you to do this.

// Delphi

var Item: TcxColorComboBoxItem;

// ...

Item := cxColorComboBox1.Properties.Items.FindColorItem(clBlack);

Item.Description := 'Black color description';


TcxColorComboBoxItems.GetColorByIndex

TcxColorComboBoxItems          See Also

Gets the color represented by the item at the specified index.

function GetColorByIndex(AIndex: Integer; ADefaultColor: TColor): TColor;

Description

Use the GetColorByIndex method if you need to determine the color represented by the item at a specified index.  This can be used, for instance, if traversing through the items and performing specific operations on items whose color satisfies a predefined condition.

The AIndex parameter specifies the index of the item whose color is to be retrieved.  Note that item indexes are zero based.  The highest available item index is the Count property value decremented by one.  If the specified AIndex parameter value is negative or exceeds the maximum available index, the color specified by the ADefaultColor parameter value is returned instead.

The following sample code traverses all items within a color combo box control and removes items that are shades of red (with red channel equal to 255, while the green and blue channels are identical).

// Delphi

var

  I: Integer;

  AColor: TColor;

// ...

  I := 0;

  while I <> cxColorComboBox1.Properties.Items.Count do

  begin

    AColor := cxColorComboBox1.Properties.Items.GetColorByIndex(I, clBlack);

    if (ColorIsShadeOfRed(AColor)) then

      cxColorComboBox1.Properties.Items.Delete(I)

    else

      Inc(I);

  end;

// ...

function TForm1.ColorIsShadeOfRed(AColor: TColor): Boolean;

var

  R, G, B: Integer;

  RGB: string;

begin

  RGB := IntToHex(AColor, 6);

  B := StrToInt('$' + LeftStr(RGB, 2));

  G := StrToInt('$' + MidStr(RGB, 3, 2));

  R := StrToInt('$' + RightStr(RGB, 2));

  if (R = 255) and (G = B) then

    Result := True

  else Result := False;

end;


TcxColorComboBoxItems.GetIndexByColor

TcxColorComboBoxItems          See Also

Gets the index of the item representing a specified color.

function GetIndexByColor(AColor: TColor): Integer;

Description

Use the GetIndexByColor method to obtain the index of the item representing the specified color.  The color to find is specified by the AColor parameter.  If this color is not represented by any item within the collection, the method returns –1.

This method is useful when you want to perform actions for particular colors.  For instance, you may want to display Delphi colors within your combo box, but without showing black.  In this instance, set the Properties.NamingConvention property value to cxncDelphi and remove black from the list at application startup.  To remove the color, first call the GetIndexByColor method to obtain the item index and then call the collection’s Delete method specifying the item index as its parameter:

// Delphi

var BlackColorIndex: Integer;

// ...

BlackColorIndex := cxColorComboBox1.Properties.Items.GetIndexByColor(clBlack);

cxColorComboBox1.Properties.Items.Delete(BlackColorIndex);


TcxColorComboBoxProperties
TcxColorComboBoxProperties Object

Hierarchy          Properties          Methods          Events

Contains settings of the TcxColorComboBox editor.

Unit

cxColorComboBox

TcxColorComboBoxProperties = class(TcxCustomColorComboBoxProperties)

Description

The TcxColorComboBoxProperties object contains settings defining the appearance and behavior of the color combo box control.  This object can be accessed via the control’s Properties property.  To control any changes made to the editor’s DisplayFormat, EditFormat, MaxLength, MaxValue, MinValue and ReadOnly properties and reverse their values back to the default ones, use the AssignedValues property.

The TcxColorComboBoxProperties class is derived from the TcxCustomColorComboBoxProperties and simply publishes its properties and events.  Please refer to the ancestor’s description for details of available properties and methods.


TcxColorComboBoxProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |

TcxCustomDropDownEditProperties

     |

TcxCustomComboBoxProperties

     |

TcxCustomColorComboBoxProperties

     |


Properties for TcxColorComboBoxProperties
TcxColorComboBoxProperties Properties

TcxColorComboBoxProperties          Legend

Derived from TcxCustomColorComboBoxProperties

AllowSelectColor

ColorBoxAlign

ColorBoxFrameColor

ColorBoxWidth

ColorComboStyle

ColorDialogType

ColorValueFormat

CustomColors

DefaultColor

DefaultColorStyle

DefaultDescription

Items

NamingConvention

MaxMRUColors

PrepareList

ShowDescriptions

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

IncrementalSearch

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 TcxColorComboBoxProperties
TcxColorComboBoxProperties Methods

TcxColorComboBoxProperties          Legend

Derived from TcxCustomColorComboBoxProperties

Assign

PrepareDelphiColorList

PrepareHTML4ColorList

PrepareX11ColorList

PrepareX11OrderedColorList

Derived from TcxCustomMaskEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults


Events for TcxColorComboBoxProperties
TcxColorComboBoxProperties Events

TcxColorComboBoxProperties          Legend

Derived from TcxCustomColorComboBoxProperties

OnAddedMRUColor

OnDeletedMRUColor

OnGetDefaultColor

OnNamingConvention

OnSelectCustomColor

Derived from TcxCustomComboBoxProperties

OnDrawItem

OnMeasureItem

Derived from TcxCustomDropDownEditProperties

OnCloseQuery

OnCloseUp

OnInitPopup

OnPopup

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomColorComboBox
TcxCustomColorComboBox Object

Hierarchy          Properties          Methods          Events

Serves as the base for color combo box controls.

Unit

cxColorComboBox

TcxCustomColorComboBox = class(TcxCustomComboBox)

Description

The TcxCustomColorComboBox object implements the basic functionality of color combo box controls.  These are controls that allow end-users to select a color from a dropdown list.  Dropdown Items can show color boxes, textual descriptions of colors or both.  You can allow end-users to add custom colors to the list using a standard dialog.  Color descriptions displayed can differ based upon the naming convention currently applied.  Additionally, you can make use of four predefined color sets or create your own manually.

Do not create instances of the TcxCustomColorComboBox class in applications.  If you need to add a color combo box control to your application, use the TcxColorComboBox or TcxDBColorComboBox objects instead.  The TcxCustomColorComboBox class can be used to derive your own color combo box controls.


TcxCustomColorComboBox Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomComboBox

     |


Properties for TcxCustomColorComboBox
TcxCustomColorComboBox Properties

TcxCustomColorComboBox          Legend

In TcxCustomColorComboBox

ActiveProperties

ColorValue

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading


Methods for TcxCustomColorComboBox
TcxCustomColorComboBox Methods

TcxCustomColorComboBox          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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCustomColorComboBox
TcxCustomColorComboBox Events

TcxCustomColorComboBox          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCustomColorComboBox.ActiveProperties

TcxCustomColorComboBox          See Also

Obtains the properties that are currently applied to an editor.

property ActiveProperties: TcxCustomColorComboBoxProperties;

Description

Use the ActiveProperties property to obtain the properties of the current editor that are currently in effect.  This property is especially useful when the 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 editor.  Otherwise, the inherent editor’s properties are returned.

ReadOnly Property


TcxCustomColorComboBox.ColorValue

TcxCustomColorComboBox          See Also

Specifies the selected color.

property ColorValue: TColor;

Description

Use the ColorValue property to set or obtain the currently selected color.  Setting this property to a specific color forces the editor to select the item representing this color.  If there is no item with the specified color, the behavior of the color combo box is determined by the ColorComboStyle property.  You can also use this property to obtain the currently selected color.  For instance, you can handle the Properties.OnChange event and read the ColorValue property value to assign the currently selected color to a target control.

The default value of the Color property is clWindow.


TcxCustomColorComboBox.Properties

TcxCustomColorComboBox

Holds settings specific to color combo box controls.

property Properties: TcxCustomColorComboBoxProperties;

Description

The Properties property enables you to access properties and events specific to the color combo box.  This property is represented by the TcxCustomColorComboBoxProperties object.  Please refer to its description for details on available settings.


TcxCustomColorComboBoxProperties
TcxCustomColorComboBoxProperties Object

Hierarchy          Properties          Methods          Events

Holds specific settings of color combo box controls.

Unit

cxColorComboBox

TcxCustomColorComboBoxProperties = class(TcxCustomComboBoxProperties)

Description

Settings specific to color combo box controls can be accessed using their Properties property.  This property is represented by the TcxCustomColorComboBoxProperties object and its properties and events can be used to customize the color combo box.

Since the TcxCustomColorComboBoxProperties class is derived from TcxCustomComboBoxProperties, it provides you a number of properties and events to customize the behavior and appearance of the dropdown window.  For instance, you can customize the width of the dropdown window and the number of items displayed within it.  Please refer to the TcxCustomComboBoxProperties class description for details.

Additionally, the TcxCustomColorComboBoxProperties class introduces a number of properties and events specific to the color combo box.  For instance, you can change the alignment, width and border color of color boxes displayed within each item (the ColorBoxAlign, ColorBoxWidth and ColorBoxFrameColor properties).  Also, you can specify the appearance and behavior of the control when no color is selected (the ColorComboStyle, DefaultColor, DefaultColorStyle and DefaultDescription properties).

You can specify the naming conventions for colors and their display format when they have no appropriate name in the current naming convention (the NamingConvention and ColorValueFormat properties, the OnNamingConvention event).  If you want to allow end-users to select custom colors and add them to the list, you can set the AllowSelectColor property to True and handle the OnSelectCustomColor event as needed.  You can also control the number of the most recently used colors displayed within the drop down using the MaxMRUColors property.  Adding and deleting colors from the most recently used list can be controlled by handling the OnAddedMRUColor and OnDeletedMRUColor events.

Do not create instances of the TcxCustomColorComboBoxProperties class directly.  It is automatically created when a color combo box control initializes its Properties property.  The TcxCustomColorComboBoxProperties class can be used to derive your own class holding editor specific properties.


TcxCustomColorComboBoxProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |

TcxCustomDropDownEditProperties

     |

TcxCustomComboBoxProperties

     |


Properties for TcxCustomColorComboBoxProperties
TcxCustomColorComboBoxProperties Properties

TcxCustomColorComboBoxProperties          Legend

In TcxCustomColorComboBoxProperties

AllowSelectColor

ColorBoxAlign

ColorBoxFrameColor

ColorBoxWidth

ColorComboStyle

ColorDialogType

ColorValueFormat

CustomColors

DefaultColor

DefaultColorStyle

DefaultDescription

Items

NamingConvention

MaxMRUColors

PrepareList

ShowDescriptions

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

IncrementalSearch

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 TcxCustomColorComboBoxProperties
TcxCustomColorComboBoxProperties Methods

TcxCustomColorComboBoxProperties          Legend

In TcxCustomColorComboBoxProperties

Assign

PrepareDelphiColorList

PrepareHTML4ColorList

PrepareX11ColorList

PrepareX11OrderedColorList

Derived from TcxCustomMaskEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults


Events for TcxCustomColorComboBoxProperties
TcxCustomColorComboBoxProperties Events

TcxCustomColorComboBoxProperties          Legend

In TcxCustomColorComboBoxProperties

OnAddedMRUColor

OnDeletedMRUColor

OnGetDefaultColor

OnNamingConvention

OnSelectCustomColor

Derived from TcxCustomComboBoxProperties

OnDrawItem

OnMeasureItem

Derived from TcxCustomDropDownEditProperties

OnCloseQuery

OnCloseUp

OnInitPopup

OnPopup

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomColorComboBoxProperties.AllowSelectColor

TcxCustomColorComboBoxProperties          See Also

Specifies whether a user is allowed to select custom colors.

property AllowSelectColor: Boolean;

Description

Set the AllowSelectColor property to True to allow end-users to select custom colors.  If so, the editor displays an additional ellipsis button that can be clicked to invoke the standard color-editing dialog.

By default, selecting a color that is already in the list, selects the corresponding item of the color combo box.  If the selected color is not already in the list, a new item is added to the combo box.

You can, however, enforce additional control over custom color selection..  Handle the OnSelectCustomColor event for this purpose.  The event enables you to specify whether the selected color should be added to the list.  Additionally, you can modify the description of the selected color.

The behavior described above is the default.  You can change it by setting the ColorDialogType property to cxcdtCustom.  In this instance, clicking the ellipsis button simply raises the OnSelectCustomColor event.  The event must be handled to invoke a custom color dialog and to determine whether the selected color is accepted.  See the Creating Custom Color Editing Dialogs topic for details.

The default value of the AllowSelectColor property is False.


TcxCustomColorComboBoxProperties.ColorBoxAlign

TcxCustomColorComboBoxProperties

Specifies the alignment of color boxes within items of the color combo box.

type

  TcxColorBoxAlign = (cbaLeft, cbaRight);

property ColorBoxAlign: TcxColorBoxAlign;

Description

Use the ColorBoxAlign property to specify whether color boxes are located on the right or the left side of combo box items.  The following values are available for this property.

Property’s Value	Meaning	Effect
cbaLeft	Color boxes are aligned to the left side of the combo box.
cbaRight	Color boxes are aligned to the right side of the combo box.

The default value of the ColorBoxAlign property is cbaLeft.


TcxCustomColorComboBoxProperties.ColorBoxFrameColor

TcxCustomColorComboBoxProperties          See Also

Specifies the color of the border painted around color boxes within color combo box items.

property ColorBoxFrameColor: TColor;

Description

By default, a single line border is painted around each item’s color box.  You can change the color of this border using the ColorBoxFrameColor property.  Note: if this property is set to the same color as the Style.Color property of the control, no border is displayed.  (The Style.Color property specifies the background color of the editor in the normal state.)  However, when no border is displayed, color boxes may merge with the control’s background color.

The images below show samples of the color combo box’s appearance when ColorBoxFrameColor is set to different values.

The default value of the ColorBoxFrameColor property is clBtnShadow.


TcxCustomColorComboBoxProperties.ColorDialogType

TcxCustomColorComboBoxProperties          See Also

Specifies whether the standard color-editing dialog is used to select custom colors.

type

  TcxColorDialogType = (cxcdtDefault, cxcdtCustom);

property ColorDialogType: TcxColorDialogType;

Description

End-users are allowed to add custom colors to the list when the AllowSelectColor property is set to True.  In this instance, the editor displays an ellipsis button that can be clicked to invoke the standard color edit dialog.  The OnSelectCustomColor event can be handled to specify whether the selected color should be added to the list.

This behavior is the default and can be changed by setting the ColorDialogType property to cxcdtCustom.  In this instance, clicking the ellipsis button raises the OnSelectCustomColor event.  The event should be handled to then provide a custom color edit dialog to end-users and to specify whether the selected color can be added to the list.

Please refer to the Creating Custom Color Editing Dialogs topic for additional details.

The default value of the ColorDialogType property is cxcdtDefault.


TcxCustomColorComboBoxProperties.ColorBoxWidth

TcxCustomColorComboBoxProperties          See Also

Specifies the width of color boxes displayed within color combo box control items.

property ColorBoxWidth: Integer;

Description

Use the ColorBoxWidth property if you need to change the width of color boxes displayed within color combo box items.  The width is specified in pixels.  Note that setting this property to 0 hides color boxes.

The height of color boxes is the same as the height of items, which in turn depends on the applied font.  The font used to paint color combo box items is specified by the Font property of the control’s current style (for example, the Style.Font property for the control in the normal state).

Note that the ColorBoxWidth property has no effect if the ShowDescriptions property is set to False.  In this instance, color combo boxes are expanded to occupy the entire area of the items.

The images below show examples of the color combo box when the ColorBoxWidth property is set to 30 and 15 respectively.

The default value of the ColorBoxWidth property is 30.


TcxCustomColorComboBoxProperties.ColorComboStyle

TcxCustomColorComboBoxProperties          See Also

Specifies the color combo box reaction to user input.

type

  TcxColorComboStyle = (cxccsComboList, cxccsComboEdit);

property ColorComboStyle: TcxColorComboStyle;

Description

Use the ColorComboStyle property to specify color combo box reaction to posting the color value.  You can set the selected color via the ColorValue property.  If this property designates a TColor value, which has no corresponding item within the color combo box Items collection, then the color combo box can react in two ways.  The reaction itself is determined by the ColorComboStyle property value.

Property’s Value	Meaning
cxccsComboList	The color combo box can only navigate through the values stored within its Items property.  If the color specified via the ColorValue property has no corresponding item within the color combo box, then no color is selected.  The edit region of the color combo box displays the Properties.DefaultColor and Properties.DefaultDescription property values.
cxccsComboEdit	If the color specified via the ColorValue property has no corresponding item within the color combo box, then this color appears within the edit region of the color combo box.  The edit region of the color combo box displays the color sample with a description (this description depends on the Properties.NamingConvention property value).

The default value of the ColorComboStyle property is cxccsComboEdit.


TcxCustomColorComboBoxProperties.ColorValueFormat

TcxCustomColorComboBoxProperties          See Also

Specifies the format of descriptions for colors not recognized by the current naming convention.

type

  TcxColorValueFormat = (cxcvRGB, cxcvHexadecimal, cxcvInteger);

property ColorValueFormat: TcxColorValueFormat;

Description

If the ShowDescriptions property is set to True, each item of the color combo box displays a textual description of the color it represents.  The description for each color depends upon the NamingConvention property and the Description property of the corresponding item.  If the NamingConvention property is set to cxncNone, the value specified by the item’s Description property controls the description.  Otherwise, the control searches for the color description in the naming convention applied.  If found, the description is displayed, otherwise the numeric code of the color is displayed.  The format of the numeric code depends upon the ColorValueFormat property value and the following values are available:

Property’s Value	Meaning	Effect
cxcvHexadecimal	Hexadecimal style.  The color is displayed as three pairs of digits.  The first pair represents the red intensity.  The second and third pairs represent the intensity of green and blue respectively.
cxcvInteger	Integer style.  This value is obtained by swapping the first and third pairs of the hexadecimal value and translating it into decimal scale.
cxcvRGB	RGB style.  This value consists of three numbers representing the intensity of red, green and blue delimited by dots.
Note: You can also specify the descriptions of colors using the OnSelectCustomColor and OnNamingConvention events.

The default value of the ColorValueFormat property is cxcvRGB.


TcxCustomColorComboBoxProperties.CustomColors

TcxCustomColorComboBoxProperties          See Also

Provides access to the list of items which represent custom colors within the color combo box.

property CustomColors: TcxColorComboBoxItems;

Description

All the items added to the Items collection either by you (at design time or programmatically) or by end-users represent custom colors and can be accessed via the CustomColors property.  At design time, adding items to the CustomColors collection results in these items being added to the Items collection when the color combo box is initialized.

Note:	Set the AllowSelectColor property to True to let end-users add custom colors to the list at runtime.  You can specify whether each selected color should be added to the list by handling the OnSelectCustomColor event.

The CustomColors property like the Items property is represented by the TcxColorComboBoxItems object, a TCollection descendant.  You can use the properties and methods of this object to traverse through items and manage the list.  Please refer to the TcxColorComboBoxItems class description for details.


TcxCustomColorComboBoxProperties.DefaultColor

TcxCustomColorComboBoxProperties          See Also

Specifies the color of the color box displayed when no color is selected.

property DefaultColor: TColor;

Description

There may be situations when no color has been selected (the EditValue property of the control returns nil).  See the DefaultColorStyle property description for details on when such situations occur.

If no color is currently selected, the DefaultColorStyle property specifies the appearance of the editor.  If it is set to cxdcColor, the editor displays the color box and the string specified by the DefaultDescription property.  The color of the color box is specified by the DefaultColor property.  This property also sets the color of the hatched brush that populates the color box when the DefaultColorStyle property is set to cxdcHatched.

Images below show samples of the color combo box when the DefaultColor property is set to different values.

Property’s Value	DefaultColorStyle is cxdcColor	DefaultColorStyle is cxdcHatched
clRed
clGreen

The default value of the DefaultColor property is clWindow.


TcxCustomColorComboBoxProperties.DefaultColorStyle

TcxCustomColorComboBoxProperties          See Also

Specifies the appearance of the control when no color is selected.

type

  TcxDefaultColorStyle = (cxdcClear, cxdcColor, cxdcHatched, cxdcText, cxdcCustom);

property DefaultColorStyle: TcxDefaultColorStyle;

Description

Color combo box controls do not require that a color be selected.  By default, no color is selected at application startup.  End-users can also force the editor to accept this state by pressing the ESC key.  Also, lack of a selected color can occur when the AddToList parameter of the OnSelectCustomColor event is set to False.  (The AllowSelectColor property must be set to True to allow custom colors to be selected.)

The appearance of the editor when no color is selected is provided by the DefaultColorStyle property.  The following values are available:

Property’s Value	Meaning	Effect
cxdcClear	The color box is populated with the same color as the background.
cxdcColor	The color box is populated with the color specified by the DefaultColor property.
cxdcHatched	The box has a diagonal hatch brush.  The brush color is specified by the DefaultColor property.
cxdcText	The color box is not displayed.
cxdcCustom	Handle the OnGetDefaultColor event to provide a custom color.
Note:  The text displayed when no color is selected is specified by the DefaultDescription property.  Text visibility is specified by the ShowDescriptions property.

The default value of the DefaultColorStyle property is cxdcColor.


TcxCustomColorComboBoxProperties.DefaultDescription

TcxCustomColorComboBoxProperties          See Also

Specifies the text displayed by the color combo box when no color is selected.

property DefaultDescription: string;

Description

When the ShowDescriptions property value is True, items of the color combo box display textual descriptions of the colors.  The description displayed when no color is selected is specified by the DefaultDescription property.  Please refer to the DefaultColorStyle property description for information on situations when no color is selected.

The default value of the DefaultDescription property is ‘Color not selected’.


TcxCustomColorComboBoxProperties.Items

TcxCustomColorComboBoxProperties

Provides access to the list of items displayed within the color combo box.

property Items: TcxColorComboBoxItems;

Description

Initially, the collection of items represented by the Items property is populated with standard Delphi colors.  There are three ways to populate this collection with items (i.e. display items within the control):

1.	Add items to the collection manually at runtime.  At design time, adding items to the CustomColors collection results in these items being added to the Items collection when the color combo box is initialized.

2.	Set the PrepareList property or call the PrepareDelphiColorList, PrepareHTML4ColorList, PrepareX11ColorList or PrepareX11OrderedColorList method at runtime.  This populates the combo box with a predefined set of items.

3.	Set the NamingConvention property to a value different from cxncNone at design time and leave the Items collection empty.  In this instance, the combo box will be populated with a predefined set of items at application startup.

Note that the last alternative uses one of the methods listed in the second to perform its task.  Thus, these two approaches are almost the same.

Note:	Set the AllowSelectColor property to True to let end-users add custom colors to the list at runtime.  You can specify whether each selected color should be added to the list by handling the OnSelectCustomColor event.

All the items added to the Items collection either by you (at design time or programmatically) or by end-users can be accessed via the CustomColors property.

The Items property is represented by the TcxColorComboBoxItems object, a TCollection descendant.  You can use the properties and methods of this object to traverse through items and manage the list.  Please refer to the TcxColorComboBoxItems class description for details.


TcxCustomColorComboBoxProperties.MRUColors

TcxCustomColorComboBoxProperties          See Also

Provides access to the color values most recently used.

property MRUColors: TcxColorComboBoxItems;

Description

If the MaxMRUColors property value is greater than zero, the color combo box control provides a ‘most recently used list’ feature.  When a color is selected, it is moved to the top of the most recently used list (displayed at the top of the dropdown window above the main list).  This feature is very helpful to end-users when they need to use a limited number of colors frequently.  Selecting a color will move it to the top of the list, so the end-users will not have to spend time finding it again.

The MRUColors property allows you to access the list of items currently stored within the most recently used list.  This property can be used, for instance, to populate this list with colors at application startup.

The MRUColors property can also provide a common ‘most recently used list’ for several color combo boxes.  To do this, you must track changes to the list of each editor and store them in a global list.  When a color combo box dropdown is opened, you simply need to assign the global list to its most recently used list.  The changes to the most recently used list can be tracked using the OnAddedMRUColor and OnDeletedMRUColor events.  See their description for an example of implementing a common list.


TcxCustomColorComboBoxProperties.NamingConvention

TcxCustomColorComboBoxProperties          See Also

Specifies the naming convention for colors displayed within the color combo box.

type

  TcxColorNamingConvention = (cxncNone, cxncDelphi, cxncHTML4, cxncX11);

property NamingConvention: TcxColorNamingConvention;

Description

The NamingConvention property specifies the correspondence between colors and their textual descriptions.  If the current naming convention includes a color, this color’s description is displayed within the item.  Otherwise, the RGB representation of the color is displayed.  The format of displaying RGB codes is specified by the ColorValueFormat property.

The table below describes the values available for the NamingConvention property.

Property’s Value	Meaning
cxncDelphi	The Delphi naming convention is used.  If a color is one of the colors from the standard Delphi set, the corresponding description is displayed.  This value is likely to be used when populating the combo box with items using the PrepareDelphiColorList method.
cxncHTML	The HTML4 naming convention is used.  If a color is one of the colors from the HTML4 set, the corresponding description is displayed.  This value is likely to be used when the combo box is populated with items using the PrepareHTML4ColorList method.
cxncX11	The X11 naming convention is used.  If a color is one of the colors from the X11 set, the corresponding description is displayed.  This value is likely to be used when the combo box is populated with items using the PrepareX11ColorList or PrepareX11OrderedColorList method.
cxncNone	No naming convention is used.  The Description property of combo box items specifies the display text.

Note that you can also provide description for items using the OnNamingConvention and OnSelectCustomColor events.

The NamingConvention property can also be used to populate the control with items.  For this purpose, set the NamingConvention property to a value other than cxncNone and leave the Items collection empty at design-time. In this instance, the control will populate the items list with the color set corresponding to the specified naming convention at application startup.  Note that this is equivalent to calling one of the following methods: PrepareDelphiColorList, PrepareHTML4ColorList or PrepareX11ColorList.

The default value of the NamingConvention property is cxncNone.


TcxCustomColorComboBoxProperties.MaxMRUColors

TcxCustomColorComboBoxProperties

Specifies the maximum number of items that can be displayed within the most recently used list.

property MaxMRUColors: Integer;

Description

Color combo boxes provide a most recently used items list to end-users.  This feature means that each time an item is selected, it is moved to the top of the most recently used list, located at the top of the dropdown.  The number of items in this list grows each time a new item is selected until the number of items is equal to the MaxMRUColors property value.  When the maximum number is achieved, selecting a new color deletes the oldest item from this list.

The images below show the behavior of the color combo box when selecting three items sequentially with MaxMRUColors set to 2.  First, gray is selected and added to the most recently used list.  Next, maroon is selected and appears at the top of the list.  When white is then selected, gray is removed from the list (since only two colors are allowed in the MRU).

Set the MaxMRUColors property to 0 to disable the ‘most recently used list’ feature.

Note:	You can access the most recently used list of colors via the MRUColors property.

The default value of the MaxMRUColors property is 10.


TcxCustomColorComboBoxProperties.PrepareList

TcxCustomColorComboBoxProperties          See Also

Specifies the colors list loaded into the color combo box.

type

  TcxColorPrepareList = (cxplNone, cxplDelphi, cxplHTML4, cxplX11, cxplX11Ordered);

property PrepareList: TcxColorPrepareList;

Description

Setting the PrepareList property specifies the predefined list of colors that will be loaded into the color combo box at its initialization.  Setting this property to either cxplDelphi, cxplHTML4, cxplX11 or cxplX11Ordered is similar to calling the PrepareDelphiColorList, PrepareHTML4ColorList, PrepareX11ColorList or PrepareX11OrderedColorList methods at the combo box’s initialization.  The cxplNone value corresponds to the situation when no predefined list of colors is loaded (the Items collection list will be empty in this case).

Note: when loading a predefined color set into the color combo box, be sure that the Properties.NamingConvention property is set to the corresponding value or cxncNone.  For instance, if calling the PrepareDelphiColorList method, ensure that the Properties.NamingConvention property value is cxncDelphi or cxncNone.  Otherwise, colors that are not recognized by the specified naming convention will be displayed using RGB codes.  Note that this only matters if color descriptions are displayed (the Properties.ShowDescription property value is True).

The default value of the PrepareList property is cxplDelphi.


TcxCustomColorComboBoxProperties.ShowDescriptions

TcxCustomColorComboBoxProperties          See Also

Specifies whether color combo box items display textual descriptions of colors.

property ShowDescriptions: Boolean;

Description

Set the ShowDescriptions property to False to hide the textual descriptions displayed within items.  If set to True, descriptions are displayed.  Note that if descriptions are not displayed, color boxes displayed within items are stretched to fit the entire width allowed.  In this instance, you may wish to reduce the control’s width.

The images below show the appearance of the color combo box when text descriptions for items are shown and hidden, respectively.

The following members allow you to specify the text displayed within items of the color combo box: the control’s Properties.NamingConvention and Properties.ColorValueFormat properties, the control’s Properties.OnNamingConvention and Properties.OnSelectCustomColor events and the items’ Description property.

The default value of the ShowDescriptions property is True.


TcxCustomColorComboBoxProperties.Assign

TcxCustomColorComboBoxProperties

Assigns the content of one object holding color combo box settings to another.

procedure Assign(Source: TPersistent); override;

Description

Use the Assign method to copy settings of one TcxCustomColorComboBoxProperties object (or descendant) to another.  The Source parameter specifies the source object.  The caller is the destination object.

The Assign method is useful if you need to create several color combo box objects with the same or similar settings.  Using the method, you can customize a single editor and copy its settings to others as needed.


TcxCustomColorComboBoxProperties.PrepareDelphiColorList

TcxCustomColorComboBox          See Also

Populates the color combo box with the default Delphi color list.

procedure PrepareDelphiColorList(const ASaveCustom, ASaveMRU: Boolean);

Description

Use the PrepareDelphiColorList method to populate the color combo box editor with standard Delphi colors. The method first clears the list of displayed items and then adds all the colors from the Delphi set (descriptions are also assigned to items using the corresponding naming convention).

To populate the color combo box control with colors from another predefined set, use the PrepareHTML4ColorList, PrepareX11ColorList or PrepareX11OrderedColorList method.

The ASaveCustom parameter identifies whether user-defined colors are saved when the new color set is loaded into the color combo box.  The ASaveMRU parameter identifies whether the MRU colors list is saved when the new color set is loaded.

Note that you can specify the color list used in the color combo box at design-time using the Properties.NamingConvention property.  However, this property only has an effect when the Properties.Items collection is empty.  Otherwise, it simply changes the color naming convention.  Also, changing the Properties.NamingConvention property at runtime has no effect on the set of colors displayed by the control.  Thus, if you need to load a predefined color set, use one of the methods listed above.  Another use of these methods is to reset the list of colors.  This is useful, for instance, if you allow end-users to add their own colors to the list, but want to have the ability to discard changes made by them.

The following is a sample color combo box populated with default Delphi colors:

Note that when Delphi color list is loaded into the control, all color descriptions start with a ‘cl’ string (as in the Delphi IDE).  Sometimes, you may want to avoid such behavior by handling the Properties.OnNamingConvention event as shown below. (The event lets you correct the description of each color).

// Delphi

procedure TForm1.cxColorComboBox1PropertiesNamingConvention(

  Sender: TObject; const AColor: TColor; var AColorDescription: string);

begin

  if LeftStr(AColorDescription, 2) = 'cl' then

    AColorDescription := MidStr(AColorDescription, 3, Length(AColorDescription) - 2);

end;

If the event is handled as above, the combo box will look as displayed below.

Note: when loading a predefined color set into the color combo box, be sure that the Properties.NamingConvention property is set to the corresponding value or cxncNone.  For instance, if calling the PrepareDelphiColorList method, ensure that the Properties.NamingConvention property value is cxncDelphi or cxncNone.  Otherwise, colors that are not recognized by the specified naming convention will be displayed using RGB codes.  Note that this only matters if color descriptions are displayed (the Properties.ShowDescription property value is True).


TcxCustomColorComboBoxProperties.PrepareHTML4ColorList

TcxCustomColorComboBox          See Also

Populates the color combo box with the default HTML 4 color list.

procedure PrepareHTML4ColorList(const ASaveCustom, ASaveMRU: Boolean);

Description

Use the PrepareHTML4ColorList method to populate the color combo box editor with standard HTML4 colors. The method clears the displayed items list and then adds the colors from the HTML4 set (descriptions are also assigned to the items using the corresponding naming convention).

To populate the color combo box control with colors from another predefined set, use the PrepareDelphiColorList, PrepareX11ColorList or PrepareX11OrderedColorList method.  See the PrepareDelphiColorList method description for details on using these methods.

The ASaveCustom parameter identifies whether user-defined colors are saved when the new color set is loaded into the color combo box.  The ASaveMRU parameter identifies whether the MRU colors list is saved when the new color set is loaded.

The following is a sample color combo box populated with the default HTML 4 colors:


TcxCustomColorComboBox.PrepareX11ColorList
TcxCustomColorComboBoxProperties.PrepareX11ColorList

TcxCustomColorComboBox          See Also

Populates the color combo box with the default X11 color list.

procedure PrepareX11ColorList(const ASaveCustom, ASaveMRU: Boolean);

Description

Use the PrepareX11ColorList method to populate the color combo box with the standard colors used in the X11 environment. The method clears the displayed items list and then adds the colors from the X11 set (descriptions are also assigned to the items using the corresponding naming convention).

To populate the color combo box control with colors from another predefined set, use the PrepareDelphiColorList, PrepareHTML4ColorList or PrepareX11OrderedColorList method.  See the PrepareDelphiColorList method description for details on using these methods.

The ASaveCustom parameter identifies whether \ user-defined colors are saved when the new color set is loaded into the color combo box.  The ASaveMRU parameter identifies whether the MRU colors list is saved when the new color set is loaded.

The following is a sample color combo box populated with the default X11 colors:

Note: The PrepareX11OrderedColorList method populates the control with the same colors.  The only difference is that the colors are ordered so that shades of the same color are displayed close to one another.


TcxCustomColorComboBoxProperties.PrepareX11OrderedColorList

TcxCustomColorComboBox          See Also

Populates the color combo box with the set of the ordered X11 colors.

procedure PrepareX11OrderedColorList(const ASaveCustom, ASaveMRU: Boolean);

Description

Use the PrepareX11OrderedColorList method to populate the color combo box with standard colors used in the X11 environment. The method clears the displayed items list and then adds the colors from the X11 set (descriptions are also assigned to items using the corresponding naming convention).  The colors are sorted so that the shades of the same color are positioned near each other.

To populate the color combo box control with colors from another predefined set, use the PrepareDelphiColorList, PrepareHTML4ColorList or PrepareX11ColorList method.  See the PrepareDelphiColorList method description for details on using these methods.

The ASaveCustom parameter identifies whether user-defined colors are saved when the new color set is loaded into the color combo box.  The ASaveMRU parameter identifies whether the MRU colors list is saved when the new color set is loaded.

The following is a sample color combo box populated with an ordered list of the X11 colors:


TcxCustomColorComboBoxProperties.OnAddedMRUColor

TcxCustomColorComboBoxProperties

Fires after a color has been added to the most recently used list or when a color was moved to the top of it.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnAddedMRUColor: TNotifyEvent;

Description

When a user selects a color that is not in the most recently used list, the color is added to the top of that list.  If the selected color is already in the list, but not at the top, it is moved to that position.  The OnAddedMRUColor event fires for both cases.  The event’s Sender parameter specifies the color box control whose most recently used list has been changed.

If a color is removed from the most recently used list, the OnDeletedMRUColor event is raised.

The OnAddedMRUColor event can be used for synchronizing most recently used lists of several editors.  When a color is added to the list of an editor, this editor’s most recently used list must be written to a global version.  When a dropdown window of an editor is invoked, the global most recently used list must be assigned to this editor.  For this purpose, the OnAddedMRUColor and OnInitPopup events of all the synchronized editors must be handled in the same manner.  The code below shows how you can do this. (The list of the most recently used colors is available via the MRUColors property.)

// Delphi

type

  TForm1 = class(TForm)

// ...

  public

    MRUGlobal: TcxColorComboBoxItems;

// ...

constructor TForm1.Create(AOwner: TComponent);

begin

  inherited;

  MRUGlobal := TcxColorComboBoxItems.Create(Self, TcxColorComboBoxItem);

end;

procedure TForm1.cxColorComboBox1PropertiesInitPopup(Sender: TObject);

begin

  (sender as TcxColorComboBox).Properties.MRUColors.Assign(MRUGlobal);

end;

procedure TForm1.cxColorComboBox1PropertiesAddedMRUColor(Sender: TObject);

var

  GridColorCombo : TcxColorComboBoxProperties;

begin

  GridColorCombo := Sender as TcxColorComboBoxProperties;

  MRUGlobal.Assign(GridColorCombo.MRUColors);

end;

Note: the most recently used feature is available if the MaxMRUColors property is set to a value greater than 0.


TcxCustomColorComboBoxProperties.OnDeletedMRUColor

TcxCustomColorComboBoxProperties

Fires when a color is removed from the most recently used list.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnDeletedMRUColor: TNotifyEvent;

Description

The number of colors that can reside in the most recently used list is specified by the MaxMRUColors property.  If the number of colors residing in this list is equal to this property value, then selecting a color that is not in the list will delete the oldest item.  Also, the oldest item(s) of the most recently used list can be deleted if the MaxMRUColors property value is reduced sufficiently.  In all these cases, the OnDeletedMRUColor event is raised.

You can handle the OnDeletedMRUColor event, for instance, to synchronize the most recently used lists of several combo boxes.  See the OnAddedMRUColor event description for details.


TcxCustomColorComboBoxProperties.OnGetDefaultColor

TcxCustomColorComboBoxProperties

Enables you to specify the color used to populate the color box when none of its items are selected.

type

  TcxGetDefaultColorEvent = procedure(Sender: TObject; var AColor: TColor) of object;

property OnGetDefaultColor: TcxGetDefaultColorEvent;

Description

The DefaultColorStyle property lets you define the appearance of the color combo box when none of its items are selected.  If this property is set to cxdcCustom, the color box and the default description string are displayed by the control.  You can modify this color using the OnGetDefaultColor event handler.  To specify color, assign the proper value to the AColor parameter.  The Sender parameter enables you to identify the color combo box that raised the event.

The OnGetDefaultColor event must be handled if you want to provide different colors for the unspecified state of the combo box depending upon specific external condition, e.g. the color of another control on the form.  In this instance, you can assign the current color of that control to the AColor parameter and the color combo will display the correct control’s color regardless of whether any item is selected.

If the unspecified state of the color combo box needs the same color as the color box, set the DefaultColorStyle property to cxdcColor and assign the desired color to the DefaultColor property.


TcxCustomColorComboBoxProperties.OnNamingConvention

TcxCustomColorComboBoxProperties

Enables you to specify the text description of each color represented by the control.

type

  TcxOnNamingConventionEvent = procedure(Sender: TObject; const AColor: TColor; var AColorDescription: string) of object;

property OnNamingConvention: TcxOnNamingConventionEvent;

Description

The textual descriptions of items in the color combo box depends upon the following settings – the Properties.NamingConvention and Properties.ColorValueFormat properties of the editor and the Description property of items.  These settings can all be overridden by handling the OnNamingConvention event.  This event is extremely useful if you want to construct or modify descriptions for each item in a consistent manner.  For instance, you may need to remove the ‘cl’ prefix from descriptions when the Delphi naming convention is applied.  Another example is to display color descriptions in a hexadecimal format with a ‘#’ prefix as in HTML.

The Sender parameter of the event identifies the control that raised the event.  The AColor parameter enables you to determine the color whose description is to be modified or constructed.  The AColorDescription parameter holds the color description specified by the settings mentioned above.  You can modify it or assign it a new value to change the text representation of the color.

The sample code below shows you how to display descriptions for all colors in hexadecimal format with a ‘#’ prefix.

// Delphi

procedure TForm1.cxColorComboBox1PropertiesNamingConvention(

  Sender: TObject; const AColor: TColor; var AColorDescription: string);

begin

  AColorDescription := '#' + IntToHex(AColor, 6);

end;

The result of handling the event in this manner is shown in the image below.


TcxCustomColorComboBoxProperties.OnSelectCustomColor

TcxCustomColorComboBoxProperties

Enables you to handle the ability to add custom colors to the color list.

type

  TcxOnSelectCustomColorEvent = procedure(Sender: TObject; var AColor: TColor; var AColorDescription: string; var AddToList: Boolean) of object;

property OnSelectCustomColor: TcxOnSelectCustomColorEvent;

Description

You can allow end-users to add custom colors to the list by setting the AllowSelectColor property to True.  In this instance, the editor displays an ellipsis button to invoke the standard color edit dialog.  By default, when the user clicks the OK button within this dialog, the chosen color is added to the list and is selected.  You can, however, override this default behavior by handling the OnSelectCustomColor event.

The AColor parameter is initially set to the chosen color.  You can change it by specifying a custom color.

The AColorDescription parameter allows you to specify the description string for the color.

If you want to prohibit adding the color to the list, set the AddToList parameter to False.  This parameter’s default value is True, and thus you don’t need to modify it if the color is to be accepted.  Note that if the AddToList parameter is set to False, none of the combo box items are selected.  See the DefaultColorStyle property description for details when no items are selected.

The color combo box enables you to provide a custom color edit dialog to end-users.  To do so, you need to set the ColorDialogType property to cxcdtCustom.  In this instance, clicking the ellipsis button displayed by the editor only raises the OnSelectCustomColor event.  Thus, you need to provide your own custom color edit dialog for end-users within the event handler.  Please refer to the Creating Custom Color Editing Dialog topic for details on doing so.

The following sample describes a way in which to handle the OnSelectCustomColor event.  The handler allows shades of only gray to be selected.  Descriptions are assigned to the new colors in the following format: ‘Shade of grey <number>’, where number is the intensity of white, 0 for black and 255 for white.

// Delphi

procedure TForm1.cxColorComboBox1PropertiesSelectCustomColor(

  Sender: TObject; var AColor: TColor; var AColorDescription: string;

  var AddToList: Boolean);

var

  R, G, B: Integer;

  RGB: string;

begin

  RGB := IntToHex(AColor, 6);

  R := StrToInt('$' + LeftStr(RGB, 2));

  G := StrToInt('$' + MidStr(RGB, 3, 2));

  B := StrToInt('$' + RightStr(RGB, 2));

  if (R = G) and (G = B) then

    AColorDescription := 'Shade of grey ' + IntToStr(R)

  else

  begin

    AddToList := False;

    MessageDlg('Only shades of grey are allowed', mtError, [mbOk], 0);

  end;

end;

The image below shows the appearance of the color combo box after performing such event handling.

Note: modifying the color description in the OnSelectCustomColor event handler only takes effect if the NamingConvention property value is cxncNone.  Also, description modifications can be overridden by handling the OnNamingConvention event.


Creating Custom Color Editing Dialogs

See Also

Color combo boxes (TcxColorComboBox and TcxDBColorComboBox controls) can be customized so that end-users are capable of selecting custom colors.  To do this, the Properties.AllowSelectColor property must be set to True.  In this instance, the editor displays an ellipsis button that invokes the standard color-editing dialog.  You may, however, want to provide a custom color-editing dialog instead so as to change the appearance of the dialog or use a new dialog to restrict user input to a predefined range of colors.

To implement a custom color-editing dialog for color combo boxes you need to set the Properties.ColorDialogType property to cxcdtCustom.  In this instance, the standard dialog is not invoked when clicking the ellipsis button.  Button clicks invoke the OnSelectCustomColor event.  You need to handle this event to display your custom dialog manually.  This topic describes how to do this.

The example in this topic will create an application with two forms.  One form will contain the color combo box control.  Another form will provide a custom color editing dialog.  It will allow users to select shades of blue.  The TcxTrackBar control will be used to adjust the intensity of the blue channel.  The color editing dialog will look as displayed below:

Follow the steps listed below to create the application.

•	Create a new application.  Place the TcxColorComboBox control on the form.  Set its Properties.AllowSelectColor property to True and the Properties.ColorDialogType property to cxcdtCustom.

•	Add a new form to the application.  Place a TcxTrackBar control on it.  Set its Properties.Min and Properties.Max properties to 0 and 255 respectively.  Set its Properties.ShowTicks property to False.

•	Add a TcxGroupBox control to the second form.  This will be used to display the currently selected color’s sample.  Modify the control’s properties as shown in the image below.

•	Add OK and Cancel buttons to the form (TcxButton controls).  Set their names to ‘btnOk’ and ‘btnCancel’ respectively.  Write the following handlers for their OnClick events.

// Delphi

type

TForm2 = class(TForm)

// ...

public

  ColorAccepted: Boolean;

// ...

procedure TForm2.btnOkClick(Sender: TObject);

begin

  ColorAccepted := True;

  Close;

end;

procedure TForm2.btnCancelClick(Sender: TObject);

begin

  Close;

end;

•	Declare the following function that calculates the color according to the track bar’s thumb position.

// Delphi

type

TForm2 = class(TForm)

// ...

public

  function GetColorByThumbPosition: TColor;

// ...

function TForm2.GetColorByThumbPosition: TColor;

begin

  Result := $10100 * cxTrackBar1.Position + $FF;

end;

•	Write the following handlers for the OnCreate event of the form and the Properties.OnChange event of the track bar.

// Delphi

procedure TForm2.FormCreate(Sender: TObject);

begin

  ColorAccepted := False;

  cxGroupBox1.Color := GetColorByThumbPosition;

end;

procedure TForm2.cxTrackBar1Click(Sender: TObject);

begin

  cxGroupBox1.Color := GetColorByThumbPosition;

end;

•	Now return to the main form and write the following handler for the color combo box’s Properties.OnSelectCustomColor event.

// Delphi

procedure TForm1.cxColorComboBox1PropertiesSelectCustomColor(

Sender: TObject; var AColor: TColor; var AColorDescription: string;

var AddToList: Boolean);

var frmEditor: TForm2;

begin

  frmEditor := TForm2.Create(Application);

  frmEditor.ShowModal;

  AColor := frmEditor.GetColorByThumbPosition;

  AddToList := frmEditor.ColorAccepted;

end;

•	Run the application.  Click on the color combo box’s ellipsis button to invoke the custom color editing dialog.  Use the track bar to modify the color.  Click the OK button to add the selected color to the combo box.


cxCurrencyEdit Unit Overview
cxCurrencyEdit Unit

Classes

TcxCurrencyEdit

TcxCurrencyEditProperties

TcxCurrencyEditPropertiesValues

TcxCustomCurrencyEdit

TcxCustomCurrencyEditProperties


TcxCurrencyEdit
 TcxCurrencyEdit Object

Hierarchy          Properties          Methods          Events          See Also

Represents an editor enabling editing currency data.

Unit

cxCurrencyEdit

TcxCurrencyEdit = class(TcxCustomCurrencyEdit);

Description

The TcxCurrencyEdit class represents a currency edit control.  The following image demonstrates the currency editor displaying the value using English (United States) regional settings.

A currency editor allows you to specify the format for the display value.  Use the Properties object to adjust various settings specific to currency editors.  They include display format, number of decimal places, range of legal values and many others.  To access a value stored in a currency editor use the Value property.  It always returns floating-point data while the EditValue property may specify NULL.  EditValue is of type Variant.  It contains NULL unless a valid value is assigned to EditValue or Value.

The Style property manages the look & feel of an editor.  Working with styles is discussed in the TcxCustomEditStyle class topic.

TcxCurrencyEdit does not introduce any new functionality.  It simply publishes properties inherited from base classes.

All currency editors employ the same default display currency format.  It is obtained from the CurrencyFormat property of the global TcxFormatController class instance.  The CurrencyFormat property is constructed based on system locale settings.  To get a reference to the global format controller call the cxFormatController function.

Currency editors implement the IcxFormatControllerListener interface, which provides notification of currency format changes from the global format controller.  There are three ways to change the default display currency format:

•	set the system locale settings.  The format controller will notify editors of these changes by setting the TApplication.UpdateFormatSettings property to True.  If you want to avoid updating default currency formats due to locale settings changes you have to set the TApplication.UpdateFormatSettings property to False.

•	set the CurrencyString, CurrencyFormat and CurrencyDecimals properties defined in the SysUtils unit.  Editors will not receive notifications automatically.  You need to manually call the GetFormats and NotifyListeners functions of the global format controller.

•	set the CurrencyFormat property of the global format controller directly.

If you explicitly set the currency display format via the DisplayFormat member of the Properties object, the default currency format is not taken into account.  To reset the currency format to the default value call the RestoreDefaults method of the Properties object.


TcxCurrencyEdit Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomCurrencyEdit

     |


Properties for TcxCurrencyEdit
TcxCurrencyEdit Properties

TcxCurrencyEdit          Legend

In TcxCurrencyEdit

EditValue

Derived from TcxCustomCurrencyEdit

ActiveProperties

Properties

Value

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxCurrencyEdit
TcxCurrencyEdit Methods

TcxCurrencyEdit          Legend

Derived from TcxCustomTextEdit

Clear

ClearSelection

CopyToClipboard

Create

CutToClipboard

SelectAll

SetSelection

Undo

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCurrencyEdit
TcxCurrencyEdit Events

TcxCurrencyEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCurrencyEdit.EditValue

TcxCurrencyEdit          See Also

Specifies the value stored by the TcxCurrencyEdit control.

type

  TcxEditValue = Variant;

property EditValue: TcxEditValue;

Description

Use the EditValue property to get and set the value stored by the TcxCurrencyEdit control.  To access a value converted to the floating-point type read the Value property.  EditValue is of the Variant type and can store NULL values.  If so, the Value property will return zero.  It is possible to specify the manner in which NULL values are represented via the Properties object.

The EditValue property contains the currently edited value.  When a user presses the Enter key or sets focus to another control, the text provided by the Text property is converted to EditValue.


TcxCurrencyEditProperties
TcxCurrencyEditProperties Object

Hierarchy          Properties          Methods          Events          See Also

Contains settings specific to currency editors.

Unit

cxCurrencyEdit

TcxCurrencyEditProperties = class(TcxCustomCurrencyEditProperties);

Description

The TcxCurrencyEditProperties class publishes various settings declared in base classes.  To adjust settings of currency editors use the Properties object of a corresponding class (TcxCustomCurrencyEdit.Properties, for instance).  To control any changes made to the editor’s DisplayFormat, EditFormat, MaxLength, MaxValue, MinValue and ReadOnly properties and reverse their values back to the default ones, use the AssignedValues property.

A number of properties control the way a currency value is presented.  The DisplayFormat defines the format for a value.  Use the Nullable and NullString properties to specify the manner in which NULL values are displayed.


TcxCurrencyEditProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomCurrencyEditProperties

     |


Properties for TcxCurrencyEditProperties
TcxCurrencyEditProperties Properties

TcxCurrencyEditProperties          Legend

Derived from TcxCustomCurrencyEditProperties

DecimalPlaces

Nullable

NullString

UseThousandSeparator

Derived from TcxCustomTextEditProperties

AssignedValues

CharCase

DisplayFormat

EchoMode

EditFormat

HideCursor

HideSelection

ImeMode

ImeName

IncrementalSearch

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 TcxCurrencyEditProperties
TcxCurrencyEditProperties Methods

TcxCurrencyEditProperties          Legend

Derived from TcxCustomCurrencyEditProperties

StrToFloatEx

Derived from TcxCustomTextEditProperties

IsDisplayValueValid

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue


Events for TcxCurrencyEditProperties
TcxCurrencyEditProperties Events

TcxCurrencyEditProperties          Legend

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCurrencyEditPropertiesValues
TcxCurrencyEditPropertiesValues Object

Hierarchy          Properties          Methods

Contains the property flags that indicate which properties specific to a currency editor have been changed.

Unit

cxCurrencyEdit

TcxCurrencyEditPropertiesValues = class(TcxTextEditPropertiesValues);

Description

The TcxCurrencyEditPropertiesValues class tracks the changes made to the DecimalPlaces, EditFormat, MaxLength, MaxValue, MinValue and ReadOnly properties of a currency editor.  Once one of these properties is set to a value other than the default one, the changes are reflected in the TcxCurrencyEditPropertiesValues class (its corresponding property flag is set to True).  To undo the changes made and reverse the property back to its default value, set the corresponding property flag to False or call the RestoreDefaults method to reverse all these properties back to their default values and reset all the property flags.  Use the BeginUpdate and EndUpdate methods to control when the editor repaints and avoid any flickering when the property flags are modified.


TcxCurrencyEditPropertiesValues Hierarchy
Hierarchy

TPersistent

     |

TcxCustomEditPropertiesValues

     |

TcxTextEditPropertiesValues

     |


Properties for TcxCurrencyEditPropertiesValues
TcxCurrencyEditPropertiesValues Properties

TcxCurrencyEditPropertiesValues          Legend

In TcxCurrencyEditPropertiesValues

DecimalPlaces

Derived from TcxTextEditPropertiesValues

DisplayFormat

EditFormat

MaxLength

MaxValue

MinValue

Derived from TcxCustomEditPropertiesValues

ReadOnly


Methods for TcxCurrencyEditPropertiesValues
TcxCurrencyEditPropertiesValues Methods

TcxCurrencyEditPropertiesValues          Legend

In TcxCurrencyEditPropertiesValues

RestoreDefaults

Derived from TcxCustomEditPropertiesValues

BeginUpdate

EndUpdate


TcxCurrencyEditPropertiesValues.DecimalPlaces

TcxCurrencyEditPropertiesValues          See Also

Specifies whether the number of digits to the right of the decimal point in a currency editor has been changed.

property DecimalPlaces; Boolean;

Description

Once the DecimalPlaces property of a currency editor is set to a value other than the default one, the DecimalPlaces property flag is set to True.  Otherwise, it’s set to False.  To undo the changes made to the editor’s DecimalPlaces property and reverse it back to its default value, call the RestoreDefaults method which resets all the property flags or set the DecimalPlaces property flag to False.


TcxCurrencyEditPropertiesValues.RestoreDefaults

TcxCurrencyEditPropertiesValues          See Also

Reverses the values of the properties (changes to which are being tracked) back to their default values.

procedure RestoreDefaults; override;

Description

The RestoreDefaults method undoes any changes made to the properties and resets their values back to the default ones.  Calling this method sets the editor’s properties being tracked (DecimalPlaces, DisplayFormat, EditFormat, MaxLength, MaxValue, MinValue, and ReadOnly) to the default values and resets the corresponding property flags to False.  Setting the property flag of each property being tracked to False has the same result as calling the RestoreDefaults method.


TcxCustomCurrencyEdit
TcxCustomCurrencyEdit Object

Hierarchy          Properties          Methods          Events          See Also

Represents the base class for the controls representing currency data.

Unit

cxCurrencyEdit

TcxCustomCurrencyEdit = class(TcxCustomTextEdit, IcxFormatContollerListener);

Description

The TcxCustomCurrencyEdit class represents the base class for the controls representing currency data.  It provides the ability to edit numerical values and present them using a given format.  The Value member stores the currency value of the floating-point type.  To adjust various settings use the Properties member.  It allows you to specify display format, number of decimal places, range of legal values and many others.

Use the Style, StyleDisabled, StyleFocused and StyleHot properties to adjust the look & feel of an editor.  Working with styles is discussed in the TcxCustomEditStyle class topic.

Do not create instances of the TcxCustomCurrencyEdit class.  Use its descendants such as TcxCurrencyEdit or TcxDBCurrencyEdit instead.

All currency editors employ the same default display currency format.  It is obtained from the CurrencyFormat property of the global TcxFormatController class instance.  The CurrencyFormat property is constructed based on system locale settings.  To get a reference to the global format controller call the cxFormatController function.

Currency editors implement the IcxFormatControllerListener interface, which provides notification of currency format changes from the global format controller.  There are three ways to change the default display currency format:

•	set the system locale settings.  The format controller will notify editors of these changes by providing the TApplication.UpdateFormatSettings property set to True.  If you want to avoid updating the default currency formats due to locale settings changes you have to set the TApplication.UpdateFormatSettings property to False.

•	set the CurrencyString, CurrencyFormat and CurrencyDecimals properties defined in the SysUtils unit.  Editors will not receive notifications automatically.  You need to manually call the GetFormats and NotifyListeners functions of the global format controller.

•	set the CurrencyFormat property of the global format controller directly.

If you explicitly set the currency display format via the DisplayFormat member of the Properties object, the default currency format is not taken into account.  To reset the currency format to the default value call the RestoreDefaults method of the Properties object.


TcxCustomCurrencyEdit Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |


Properties for TcxCustomCurrencyEdit
TcxCustomCurrencyEdit Properties

TcxCustomCurrencyEdit          Legend

In TcxCustomCurrencyEdit

ActiveProperties

Properties

Value

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading


Methods for TcxCustomCurrencyEdit
TcxCustomCurrencyEdit Methods

TcxCustomCurrencyEdit          Legend

Derived from TcxCustomTextEdit

Clear

ClearSelection

CopyToClipboard

Create

CutToClipboard

SelectAll

SetSelection

Undo

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCustomCurrencyEdit
TcxCustomCurrencyEdit Events

TcxCustomCurrencyEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCustomCurrencyEdit.ActiveProperties

TcxCustomCurrencyEdit          See Also

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

property ActiveProperties: TcxCustomCurrencyEditProperties;

Description

Use the ActiveProperties property to obtain the properties of the current currency editor that are currently in effect.  This property is especially useful when the currency 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 currency editor.  Otherwise, the inherent currency editor’s properties are returned.

ReadOnly Property


TcxCustomCurrencyEdit.Properties

TcxCustomCurrencyEdit          See Also

Defines settings specific to currency editors.

property Properties: TcxCustomCurrencyEditProperties;

Description

Use the Properties object to set various settings specific to currency editors.  These are display format, number of decimal places, range of legal values, alignment, read-only status and many others.


TcxCustomCurrencyEdit.Value

TcxCustomCurrencyEdit          See Also

Specifies the floating-point value stored by a currency editor.

property Value: Double;

Description

Use the Value property to get and set the floating-point data, stored by a currency editor.  EditValue and Value refer to the same data.  The Value property is an EditValue wrapper.  EditValue is of type Variant and can store NULL values.  If EditValue specifies NULL, the Value property returns zero.

After a user presses the Enter key or sets focus to another control, the edit text is validated and converted to the EditValue property.


TcxCustomCurrencyEditProperties
TcxCustomCurrencyEditProperties Object

Hierarchy          Properties          Methods          Events          See Also

Represents settings specific to currency editors.

Unit

cxCurrencyEdit

TcxCustomCurrencyEditProperties = class(TcxCustomTextEditProperties);

Description

The TcxCustomCurrencyEditProperties class provides settings specific to currency editors.  The TcxCurrencyEditProperties class publishes them for access from currency editors.  To adjust settings of currency editors, use the Properties object of a corresponding class (TcxCustomCurrencyEdit.Properties, for instance).

TcxCustomCurrencyEditProperties members control the way a currency value is presented.  The DisplayFormat defines the format for a value.  Use the Nullable and NullString properties to specify the manner in which NULL values are displayed.


TcxCustomCurrencyEditProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |


Properties for TcxCustomCurrencyEditProperties
TcxCustomCurrencyEditProperties Properties

TcxCustomCurrencyEditProperties          Legend

In TcxCustomCurrencyEditProperties

DecimalPlaces

Nullable

NullString

UseThousandSeparator

Derived from TcxCustomTextEditProperties

AssignedValues

CharCase

DisplayFormat

EchoMode

EditFormat

HideCursor

HideSelection

ImeMode

ImeName

IncrementalSearch

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 TcxCustomCurrencyEditProperties
TcxCustomCurrencyEditProperties Methods

TcxCustomCurrencyEditProperties          Legend

In TcxCustomCurrencyEditProperties

StrToFloatEx

Derived from TcxCustomTextEditProperties

IsDisplayValueValid

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue


Events for TcxCustomCurrencyEditProperties
TcxCustomCurrencyEditProperties Events

TcxCustomCurrencyEditProperties          Legend

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomCurrencyEditProperties.DecimalPlaces

TcxCustomCurrencyEditProperties          See Also

Defines the number of decimal places.

property DecimalPlaces: Integer;

Description

The DecimalPlaces property defines the number of digits to the right of the decimal point.  A user cannot enter more digits after the decimal point than the value of the DecimalPlaces property.  DecimalPlaces affects the presentation of the currency fractional part only when the editor has focus.  If it doesn’t, the number’s presentation is completely controlled by the DisplayFormat member.

The default value of the DecimalPlaces property is determined by the global CurrencyDecimals variable declared in the SysUtils unit.


TcxCustomCurrencyEditProperties.Nullable

TcxCustomCurrencyEditProperties          See Also

Defines whether NULL values are displayed in a specific manner.

property Nullable: Boolean;

Description

Set the Nullable property to True to enable a currency editor to represent NULL values in a specific manner.  In this instance, if the editor’s EditValue property is set to NULL, the editor displays the string defined by the NullString property.  If the Nullable property is set to False, the editor displays ‘0’ to represent NULL.

The default value of the Nullable property is True.


TcxCustomCurrencyEditProperties.NullString

TcxCustomCurrencyEditProperties          See Also

Specifies the string to represent NULL values within currency editors.

property NullString: string;

Description

Use the NullString property to represent NULL values in currency editors.  An editor will display this string if its EditValue property is set to NULL and the Nullable property is set to True.  If Nullable is False, the editor displays ‘0’.


TcxCustomCurrencyEditProperties.UseThousandSeparator

TcxCustomCurrencyEditProperties

Determines whether a user may type thousand separators while entering a currency value.

property UseThousandSeparator: Boolean;

Description

Set the UseThousandSeparator property to True to make your editor accept and display thousand separators while a user enters a currency value.  Otherwise, thousand separators are not allowed and not displayed.  To obtain a thousand separator, use the global ThousandSeparator variable declared in the SysUtils unit.

The default value of the UseThousandSeparator property is False.


TcxCustomCurrencyEditProperties.StrToFloatEx

TcxCustomCurrencyEditProperties

Converts a specific string to a floating-point value.

function StrToFloatEx(S: string; var Value: Double): Boolean;

Description

The StrToFloatEx function returns True if the string was converted successfully and the evaluated number falls within the range between the minimum (5.0e-324) and maximum (1.7e+308) values.  Otherwise, the function returns False and the Value parameter returns 0.  The StrToFloatEx method accepts formatted strings with thousand separators.


TcxDBCurrencyEdit
 TcxDBCurrencyEdit Object

Hierarchy          Properties          Methods          Events          See Also

Represents a data-aware control that enables editing currency data.

Unit

cxDBEdit

TcxDBCurrencyEdit = class(TcxCustomCurrencyEdit);

Description

Use the TcxDBCurrencyEdit control to edit the contents of a numerical dataset field and represent it using a currency format.  The following image demonstrates the currency editor displaying the value using English (United States) regional settings.

To connect a data aware control to a dataset set the DataSource and DataField properties of the DataBinding object.

The adjustment of different settings and style properties is the same as for the TcxCurrencyEdit control.  Use the Properties and style (Style, StyleDisabled, StyleFocused and StyleHot) members to specify the behavior and appearance of a currency editor.  Working with styles is discussed in the TcxCustomEditStyle class topic.

All currency editors employ the same default display currency format.  It is obtained from the CurrencyFormat property of the global TcxFormatController class instance.  The CurrencyFormat property is constructed based on system locale settings.  To get a reference to the global format controller call the cxFormatController function.

Currency editors implement the IcxFormatControllerListener interface, which provides notification of currency format changes from the global format controller.  There are three ways to change the default display currency format:

•	set the system locale settings.  The format controller will notify editors of these changes by providing the TApplication.UpdateFormatSettings property set to True.  If you want to avoid updating default currency formats due to locale settings changes you have to set TApplication.UpdateFormatSettings property to False.

•	set the CurrencyString, CurrencyFormat and CurrencyDecimals properties defined in the SysUtils unit.  Editors will not receive notifications automatically.  You need to manually call the GetFormats and NotifyListeners functions of the global format controller.

•	set the CurrencyFormat property of the global format controller directly.

If you explicitly set the currency display format via the DisplayFormat member of the Properties object, the default currency format is not taken into account.  To reset the currency format to the default value call the RestoreDefaults method of the Properties object.


TcxDBCurrencyEdit Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomCurrencyEdit

     |


Properties for TcxDBCurrencyEdit
TcxDBCurrencyEdit Properties

TcxDBCurrencyEdit          Legend

In TcxDBCurrencyEdit

DataBinding

Derived from TcxCustomCurrencyEdit

ActiveProperties

Properties

Value

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxDBCurrencyEdit
TcxDBCurrencyEdit Methods

TcxDBCurrencyEdit          Legend

Derived from TcxCustomTextEdit

Clear

ClearSelection

CopyToClipboard

Create

CutToClipboard

SelectAll

SetSelection

Undo

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxDBCurrencyEdit
TcxDBCurrencyEdit Events

TcxDBCurrencyEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxDBCurrencyEdit.DataBinding

TcxDBCurrencyEdit          See Also

Specifies the connection to a dataset.

property DataBinding: TcxDBEditDataBinding;

Description

Use the DataBinding property to access a TcxDBEditDataBinding instance via which the connection with the dataset is established.  To make the TcxDBCurrencyEdit control edit values from a specific field in the dataset, it is necessary to set the TcxDBEditDataBinding.DataSource and TcxDBEditDataBinding.DataField properties.


cxDateUtils Unit Overview
cxDateUtils Unit

The cxDateUtils unit provides a library of functions that process date/time values, convert them to a text representation and construct masks to input date values.

Types

TcxDateElement

TcxFirstWeekOfYear

TDay

TDays

Routines

ChangeMonth

CheckDay

cxGetDateFormat

DateOf

DateTimeToText

DateTimeToTextEx

DateToLongDateStr

DaysPerMonth

DecMonth

GetDateElement

GetWeekNumber

GetDateRegularExpession

IncMonth

IsLeapYear

SmartTextToDate

StrToDateDef

TextToDateEx

TimeOf

Global Constants

NullDate

SmartTextToDateFunc


cxGetDateFormat
cxGetDateFormat Function

Converts the ADate date into a date string.

Unit

cxDateUtils

function cxGetDateFormat(ADate: TDateTime; out AFormatDate: string; AFlags: Integer; AFormat: string = ''): Boolean;

Description

Use the cxGetDateFormat function to convert the ADate date into the AFormatDate format string. This function uses the system API to obtain the format string. The cxGetDateFormat function returns a value of True if the host environment supports this operations.

The ADate parameter specifies the date to be converted into the AFormatDate string;

The AFormatDate parameter provides the resulting string which is formatted in accordance with the AFormat date format (if specified) or with the date format of the default user locale;

The AFlags parameter specifies the function’s options. This parameter should be set to 0 if the AFormat parameter is specified. The table below lists the available options:

Value	Meaning
LOCALE_NOUSEROVERRIDE	If set, the function formats the string using the system default date format for the specified locale. If not set, the function formats the string using any user overrides to the locale's default date format
LOCALE_USE_CP_ACP	Uses the system ANSI code page for string translation instead of the locale's code page
DATE_SHORTDATE	Uses the short date format. This is the default. This value cannot be used with DATE_LONGDATE or DATE_YEARMONTH.
DATE_LONGDATE	Uses the long date format. This value cannot be used with DATE_SHORTDATE or DATE_YEARMONTH
DATE_YEARMONTH	Uses the year/month format. This value cannot be used with DATE_SHORTDATE or DATE_LONGDATE
DATE_USE_ALT_CALENDAR	Uses the alternate calendar (if present) to format the date string. If this flag is set, the function uses the default format for the alternate calendar, rather than any user overrides. The user overrides will be used only in the event that there is no default format for the specified alternate calendar
DATE_LTRREADING	Adds marks for left-to-right layout. This value cannot be used with DATE_RTLREADING
DATE_RTLREADING	Adds marks for right-to-left layout. This value cannot be used with DATE_LTRREADING

The AFormat parameter specifies the date format. If the AFormat parameter is set to an empty string, then the date format of the default locale is used. The following elements are used to construct the date format:

Value	Meaning
d	Day of month as digits without a leading zero for single-digit days
dd	Day of month as digits with leading zero for single-digit days
ddd	Day of week as a three-letter abbreviation
dddd	Day of week as its full name
M	Month as digits without a leading zero for single-digit months
MM	Month as digits with leading zero for single-digit months
MMM	Month as a three-letter abbreviation
MMMM	Month as its full name
y	Year as last two digits, but without a leading zero for years less than 10
yy	Year as last two digits, but with leading zero for years less than 10
yyy	Year represented by full four digits
gg	Period/era string. This element is ignored if the date to be formatted does not have an associated era or period string


DateToLongDateStr
DateToLongDateStr Function

Converts the ADate date into a string formatted as a long date.

Unit

cxDateUtils

function DateToLongDateStr(ADate: TDateTime): string;

Description

Use the DateToLongDateStr method to convert the ADate date into a string. The resulting string is formatted as a long date. For example, if the ADate parameter is set to 03/14/2005 and the long date format is dddd, MMMM dd, yyyy, then the resulting string will be ‘Monday, March 14, 2005’.

The ADate parameter specifies the date to be converted into a string.

Note: As for Windows NT/2000/XP the long date format of the default user locale is used (see the value in the registry subkey HKEY_CURRENT_USER\Control Panel\International\sLongDate). For other platforms the resulting string is formatted according to the long date format given by the Delphi LongDateFormat global variable.


TcxFirstWeekOfYear
TcxFirstWeekOfYear type

See Also

Enumerates the available options that specify which week should be considered the first week of a year.

Unit

cxDateUtils

type

  TcxFirstWeekOfYear = (fwySystem, fwyJan1, fwyFirstFullWeek, fwyFirstFourDays);

Description

All the possible values are described in the following table.

Value	Meaning
fwySystem	The day of the week specified in the host environment settings as the first day of the week.
fwyJan1	The first week of the year starts on January 1.
fwyFirstFullWeek	The first week with a complete set of working days in it.
fwyFirstFourDays	The first week with four working days in it.


GetWeekNumber
GetWeekNumber Function

See Also

Returns the week number in a year.

Unit

cxDateUtils

function GetWeekNumber(ADate: TDateTime; AStartOfWeek: TDay; AFirstWeekOfYear: TcxFirstWeekOfYear): Integer;

Description

Use the GetWeekNumber function to determine the week number in a year.

The ADate parameter specifies the date that the given week contains.

The AStartOfWeek parameter specifies the day, which will be treated as the first day in each week.

The AFirstWeekOfYear parameter specifies the week that should be considered as the first week of a year.


ChangeMonth
ChangeMonth Procedure

Changes the date by a specified number of months.

Unit

cxDateUtils

procedure ChangeMonth(var AYear, AMonth: Word; Delta: Integer);

Description

The AYear and AMonth parameters identify the date to be changed by a specified number of months.  The Delta parameter can be either a positive or a negative value.


CheckDay
CheckDay Function

Returns the valid day for a specific date.

Unit

cxDateUtils

function CheckDay(AYear, AMonth, ADay: Integer): Integer;

Description

The CheckDay function returns the valid day for the date defined by the AYear, AMonth and ADay parameters.  If the ADay parameter is less than 1, the function returns the first day of the month, i.e. 1.  If it is greater than the total number of days in a given month and year, CheckDay returns the last day of the month.  Otherwise, the ADay parameter is a valid day returned by the function.


DateOf
DateOf Function

Extracts the date from the TDateTime type.

Unit

cxDateUtils

function DateOf(ADateTime: TDateTime): Integer;

Description

Use the DateOf function to extract the date from the TDateTime type.  It retrieves the integer part of the ADateTime parameter and this determines the number of days elapsed since 12/30/1899.


DateTimeToText
DateTimeToText Function

Converts a TDateTime value to a human readable string.

Unit

cxDateUtils

function DateTimeToText(ADate: TDateTime): string;

Description

Use the DateTimeToText function to convert the TDateTime type data to a human readable string.  The ADate parameter represents the TDateTime type to convert.  The conversion manner depends on the TcxFormatController.UseDelphiDateTimeFormats property value.


DateTimeToTextEx
DateTimeToTextEx Function

Converts a TDateTime value to a string.

Unit

cxDateUtils

function DateTimeToTextEx(const ADate: TDateTime; AIsMasked: Boolean): string;

Description

The DateTimeToTextEx function converts a TDateTime value to a string.  If the AIsMasked parameter is False, the function simply calls DateTimeToText, passes the ADate parameter to it and returns its result.  If the AIsMasked parameter is True, the function performs the following steps:

1.	Gets the global variable’s ShortDateFormat value.

2.	Corrects it to use in masked editor mode.

3.	Makes up the date format based on the previous two steps.

4.	Formats the ADate parameter value according to the format made up.

5.	Returns the formatted human readable string containing a value of the ADate parameter.


DaysPerMonth
DaysPerMonth Function

Returns the number of days in a month.

Unit

cxDateUtils

function DaysPerMonth(AYear, AMonth: Integer): Integer;

Description

Use the DaysPerMonth function to determine the number of days in a specific month of a specific year.  The AYear and AMonth parameters specify the year and month respectively.


DecMonth
DecMonth Procedure

Decreases the specified date by one month.

Unit

cxDateUtils

procedure DecMonth(var AYear, AMonth: Word);

Description

Use the DecMonth procedure to decrease the date passed as the AMonth and AYear parameters by one month.


GetDateElement
GetDateElement Function

Extracts the day, month or year form the TDateTime type.

Unit

cxDateUtils

function GetDateElement(ADate: TDateTime; AElement: TcxDateElement): Integer;

Description

The GetDateElement function extracts the day, month or year portion from the TDateTime type. The result is an integer representing the year, the number of a month or the number of days in a month.  The ADateTime argument represents the date/time value from which to extract elements. The AElement argument determines the element to extract.

See the description of the TcxDateElement type for the list of available elements.


GetDateRegularExpession
GetDateRegularExpession Function

See Also

Returns a regular expression for editor internal date representation.

Unit

cxDateUtils

function GetDateRegularExpession(const ADateFormat: string; AUseSmartInput: Boolean): string;

Description

The GetDateEditMask function returns a mask for editor internal date representation. The result is a regular expression representing the current date format.


IncMonth
IncMonth Procedure

Increases the specified date by one month.

Unit

cxDateUtils

procedure IncMonth(var AYear, AMonth: Word);

Description

Use the IncMonth procedure to increase the date passed as the AMonth and AYear parameters by one month.


IsLeapYear
IsLeapYear Function

Determines whether the specified year is a leap year.

Unit

cxDateUtils

function IsLeapYear(AYear: Integer): Boolean;

Description

Use the IsLeapYear function to determine whether the year passed as an AYear parameter contains 365 or 366 days.


SmartTextToDate
SmartTextToDate Function

See Also

Converts a string to the TDateTime type format.

Unit

cxDateUtils

function SmartTextToDate(const AText: string; var ADate: TDateTime): Boolean;

Description

Use the SmartTextToDate function to convert a string to the TDateTime type format. If conversion succeeds, the function returns True; otherwise, False.  The strings that the SmartTextToDate function can recognize are declared as resource strings.  For instance, for the ‘tomorrow’ string the function retrieves the date of the present date.  All available smart input constants are listed below.

Constant	Value	Description
cxSDateToday	'today'	Represents the current date.
cxSDateYesterday	'yesterday'	Represents yesterday’s date.
cxSDateTomorrow	'tomorrow'	Represents tomorrow’s date.
cxSDateSunday	'Sunday'	Represents the next Sunday date. *
cxSDateMonday	'Monday’	Represents the next Monday date. *
cxSDateTuesday	'Tuesday'	Represents the next Tuesday date. *
cxSDateWednesday	'Wednesday'	Represents the next Wednesday date. *
cxSDateThursday	'Thursday'	Represents the next Thursday date. *
cxSDateFriday	'Friday'	Represents the next Friday’s date. *
cxSDateSaturday	'Saturday'	Represents the next Saturday’s date. *
cxSDateFirst	'first'	Represents the first day of the current week.
cxSDateSecond	'second'	Represents the second day of the current week.
cxSDateThird	'third'	Represents the third day of the current week.
cxSDateFourth	'fourth'	Represents the fourth day of the current week.
cxSDateFifth	'fifth'	Represents the fifth day of the current week.
cxSDateSixth	'sixth'	Represents the sixth day of the current week.
cxSDateSeventh	'seventh'	Represents the seventh day of the current week.
cxSDateBOM	'bom'	Represents the first day of the current month.
cxSDateEOM	'eom'	Represents the last day of the current month.
cxSDateNow	'now'	Represents the current date including the current time.
* If the constant coincides with the current day of the week, the SmartTextToDate function returns the current date.

Depending on your language you may want to use another strings to be recognized by the function.  For this purpose, you can use the global cxSetResourceString procedure which replaces the resource string for the given identifier.  A date editor gets a string, when it needs to display it, via the cxGetResourceString function.  The function retrieves a resource string for the given identifier taking into account whether the string was substituted by cxSetResourceString.

A date edit control allows a user to type specific strings instead of date values.  These strings are interpreted then as corresponding dates.  A date editor uses the SmartTextToDate function to convert the strings.  The next code shows how to substitute the ‘today’ and ‘tomorrow’ strings acceptable by a date edit control for the German equivalents:

// Delphi

  cxSetResourceString(@cxSDateToday, "Heute");

  cxSetResourceString(@cxSDateTomorrow, "Morgen");

  cxFormatController.GetFormats;

  cxFormatController.NotifyListeners;

// C++ Builder

  cxSetResourceString(&_cxSDateToday, "Heute");

  cxSetResourceString(&_cxSDateTomorrow, "Morgen");

  cxFormatController -> GetFormats();

  cxFormatController -> NotifyListeners();

Now a date edit recognizes ‘Heute’ and ‘Morgen’ strings as today and tomorrow respectively.  Calling to the SmartTextToDate function is performed by a date editor internally.  After setting resource strings, you need to rebuild masks used by date editors.  To do so, just call the GetFormats and NotifyListeners functions of the global format controller object.

You can implement your own parser function (SmartTextToDateFunc constant) and use it to parse input via the SmartTextToDate function.


StrToDateDef
StrToDateDef Function

Tries to convert a string to the TDateTime type.

Unit

cxDateUtils

function StrToDateDef(ADateStr: string; ADefDate: TDateTime): TDateTime;

Description

The StrToDateDef function tries to convert a string to the TDateTime type. In case of a failure, it returns the ADefTime argument.


TextToDateEx
TextToDateEx Function

Converts a string to the TDateTime type.

Unit

cxDateUtils

function TextToDateEx(AText: string; var ADate: TDateTime): Boolean;

Description

The TextToDateEx function first calls the SmartTextToDate function and passes the AText parameter to it.  If the SmartTextToDate function fails, the format dependant conversion of the AText parameter occurs.  If the conversion fails, the TextToDateEx function returns False.  Otherwise, the converted value is placed into the ADate parameter and the function returns True.


TimeOf
TimeOf Function

Extracts time from the TDateTime type.

Unit

cxDateUtils

function TimeOf(ADateTime: TDateTime): TDateTime;

Description

Use the TimeOf function to extract time from the TDateTime type.  The ADateTime argument represents the TDateTime type from which to extract time.


TcxDateElement
TcxDateElement type

Unit

cxDateUtils

type

  TcxDateElement = (deYear, deMonth, deDay);

Description

Determines the date element. This enumerator is used by the GetDateElement function.


TDay
TDay type

Unit

cxDateUtils

type

  TDay = (dSunday, dMonday, dTuesday, dWednesday, dThursday, dFriday, dSaturday);

Description

Enumerates days of the week.


TDays
TDays type

Unit

cxDateUtils

type

  TDays = set of TDay;

Description

Represents a set of days of the week.


NullDate constant
NullDate global constant

Unit

cxDateUtils

NullDate = -700000;

Description

Specifies the value for a date determined as not set.


SmartTextToDateFunc constant
SmartTextToDateFunc global constant

See Also

Unit

cxDateUtils

SmartTextToDateFunc: function(const AText: string; var ADate: TDateTime): Boolean = nil;

Description

Specifies the function handle for the SmartTextToDate function.


cxDBCheckComboBox Unit Overview
cxDBCheckComboBox Unit

Classes

TcxDBCheckComboBox


TcxDBCheckComboBox
 TcxDBCheckComboBox Object

Hierarchy          Properties          Methods          Events

Represents a data-aware version of the TcxCheckComboBox.

Unit

cxDBCheckComboBox

TcxDBCheckComboBox = class(TcxCustomCheckComboBox)

Description

The TcxDBCheckComboBox is a data-aware version of the cxCheckComboBox control. The cxCheckComboBox control represents a combo box that can display items with checkboxes within the dropdown window.  This can be useful when the end-user needs to select several options from the dropdown at once.  For instance, in a time-scheduling application, you can use a check combo box with names of week days so the end user can select one or more days.

A check combo box editor displays selected items in its edit box.  Once you check/uncheck a specific item, it is automatically added to/removed from the edit box.  These items are separated by the delimiter (see the Properties.Delimiter property).

The data-aware functionality of the TcxDBCheckComboBox is encapsulated by its DataBinding property.   This allows you to specify the DataSource and DataField to which the editor is bound.

The bound database field must contain integer values.  These field values are interpreted as the bitwise combination of flags, each of which corresponds to a specific item within the list box.  Note: the number of significant bits is equal to the number of items within the list box.


TcxDBCheckComboBox Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomComboBox

     |

TcxCustomCheckComboBox

     |


Properties for TcxDBCheckComboBox
TcxDBCheckComboBox Properties

TcxDBCheckComboBox          Legend

In TcxDBCheckComboBox

DataBinding

Derived from TcxCustomCheckComboBox

ActiveProperties

ItemIndex

Properties

States

Value

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxDBCheckComboBox
TcxDBCheckComboBox Methods

TcxDBCheckComboBox          Legend

Derived from TcxCustomCheckComboBox

SetItemState

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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxDBCheckComboBox
TcxDBCheckComboBox Events

TcxDBCheckComboBox          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxDBCheckComboBox.DataBinding

TcxDBCheckComboBox

Specifies a data source connection.

property DataBinding: TcxDBEditDataBinding;

Description

Use the DataBinding property to access a TcxDBEditDataBinding instance used to connect to a data source.  The DataBinding.DataSource property identifies the dataset and DataBinding.DataField it’s data source field bound by the check combo box control.


cxDBCheckListBox Unit Overview
cxDBCheckListBox Unit

Classes

TcxDBCheckListBox


TcxDBCheckListBox
 TcxDBCheckListBox Object

Hierarchy          Properties          Methods          Events

Represents the data-aware version of the TcxCheckListBox control.

Unit

cxDBCheckListBox

TcxDBCheckListBox = class(TcxCustomCheckListBox)

Description

TcxDBCheckListBox is the data-aware version of the cxCheckListBox control.  The behavior of TcxDBCheckListBox is similar to the cxCheckListBox control except that it allows editing the contents of dataset fields.

The TcxDBCheckListBox’s data-aware functionality is encapsulated by its DataBinding property.  It allows you to specify the DataSource and DataField to which the editor is bound.

This database field must contain integer values.  These field values are interpreted as the bitwise combination of flags, each of which corresponds to a specific item within the list box.  Note: the number of significant bits is equal to the number of items within the list box.


TcxDBCheckListBox Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomCheckListBox

     |


Properties for TcxDBCheckListBox
TcxDBCheckListBox Properties

TcxDBCheckListBox          Legend

In TcxDBCheckListBox

DataBinding

Derived from TcxCustomCheckListBox

AllowGrayed

AutoComplete

AutoCompleteDelay

Columns

Count

EditValue

Glyph

GlyphCount

ImageLayout

Images

IntegralHeight

ItemIndex

Items

ReadOnly

ScrollWidth

Selected

Sorted

TopIndex

Derived from TcxContainer

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName

Derived from TControl

Align


Methods for TcxDBCheckListBox
TcxDBCheckListBox Methods

TcxDBCheckListBox          Legend

Derived from TcxCustomCheckListBox

Clear

CopySelection

DeleteSelected

ItemAtPos

ItemRect

MoveSelection

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxDBCheckListBox
TcxDBCheckListBox Events

TcxDBCheckListBox          Legend

Derived from TcxCustomCheckListBox

OnClickCheck

OnDrawItem

OnMeasureItem


TcxDBCheckListBox.DataBinding

TcxDBCheckListBox

Specifies a data source connection.

property DataBinding: TcxCustomDataBinding;

Description

Use the DataBinding property to access the TcxDBEditDataBinding instance used to connect to a data source.  The DataBinding.DataSource property identifies the dataset to which to connect and the DataBinding.DataField property specifies the data source field bound to the check list box control.


cxDBColorComboBox Unit Overview
cxDBColorComboBox Unit

Classes

TcxDBColorComboBox


TcxDBColorComboBox
 TcxDBColorComboBox Object

Hierarchy          Properties          Methods          Events          See Also

Represents the data-aware version of the TcxColorComboBox.

Unit

cxDBColorComboBox

TcxDBColorComboBox = class(TcxCustomColorComboBox)

Description

The TcxDBColorComboBox is a data-aware combo box control intended to work with the colors and color groups available in the system.  Various control settings can be accessed by the Properties of the control.

TcxDBColorComboBox editor allows:

•	previewing, navigating and selecting colors,

•	loading predefined color groups,

•	maintaining MRU (most recently used) colors list,

•	replacing standard color-picker dialog with the user defined,

•	editing custom colors and maintaining them among standard colors.

The data-aware functionality of the TcxDBColorComboBox is encapsulated in the DataBinding property.   It allows you to specify DataSource and DataField to which the editor is bound.

This database field must contain integer values.  These field values are interpreted as the TColor values representing the currently selected color within the editor.


TcxDBColorComboBox Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomComboBox

     |

TcxCustomColorComboBox

     |


Properties for TcxDBColorComboBox
TcxDBColorComboBox Properties

TcxDBColorComboBox          Legend

In TcxDBColorComboBox

DataBinding

Derived from TcxCustomColorComboBox

ActiveProperties

ColorValue

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxDBColorComboBox
TcxDBColorComboBox Methods

TcxDBColorComboBox          Legend

Derived from TcxCustomColorComboBox

PrepareDelphiColorList

PrepareHTML4ColorList

PrepareX11ColorList

PrepareX11OrderedColorList

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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxDBColorComboBox
TcxDBColorComboBox Events

TcxDBColorComboBox          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxDBColorComboBox.DataBinding

TcxDBColorComboBox

Specifies a data source connection.

property DataBinding: TcxDBEditDataBinding;

Description

Use the DataBinding property to access a TcxDBEditDataBinding instance used to establish a connection to a data source.  The DataBinding.DataSource property identifies a dataset to which to connect.  The DataBinding.DataField property specifies the data source field whose value is to be edited by the color combo box.


cxDBEdit Unit Overview
cxDBEdit Unit

Classes

TcxDBBlobEdit

TcxDBButtonEdit

TcxDBCalcEdit

TcxDBCheckBox

TcxDBComboBox

TcxDBCurrencyEdit

TcxDBDateEdit

TcxDBEditDataBinding

TcxDBHyperLinkEdit

TcxDBImage

TcxDBImageComboBox

TcxDBMaskEdit

TcxDBMemo

TcxDBMRUEdit

TcxDBPopupEdit

TcxDBSpinEdit

TcxDBTextEdit

TcxDBTextEditDataBinding

TcxDBTimeEdit


TcxDBButtonEdit
 TcxDBButtonEdit Object

Hierarchy          Properties          Methods          Events          See Also

Represents a data-aware edit control with embedded buttons.

Unit

cxDBEdit

TcxDBButtonEdit = class(TcxCustomButtonEdit);

Description

The TcxDBButtonEdit control allows editing the contents of a text dataset field.  An editor provides a collection of buttons.  It is accessible via the Buttons member of the Properties object.  The following image demonstrates a button edit with two buttons (the custom and the ellipsis buttons) painted in the XP style:

When a user clicks a button or presses the ClickKey keystroke, the Properties object generates an OnButtonClick event.  You can implement editor behavior depending on your needs by handling this event.  Properties contains various attributes specific to button editors: text alignment, mask for entering values, the auto select feature and many others.  Use the Style, StyleDisabled, StyleFocused and StyleHot properties to adjust the look & feel of an editor in various control’s states.  Working with styles is discussed in the TcxCustomEditStyle class topic.

To connect a data-aware control to a dataset set the DataSource and DataField properties of the DataBinding object.


TcxDBButtonEdit Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomButtonEdit

     |


Properties for TcxDBButtonEdit
TcxDBButtonEdit Properties

TcxDBButtonEdit          Legend

In TcxDBButtonEdit

DataBinding

Derived from TcxCustomButtonEdit

ActiveProperties

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxDBButtonEdit
TcxDBButtonEdit Methods

TcxDBButtonEdit          Legend

Derived from TcxCustomMaskEdit

CutToClipboard

PasteFromClipboard

Derived from TcxCustomTextEdit

Clear

ClearSelection

CopyToClipboard

Create

SelectAll

SetSelection

Undo

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Create

CreateInnerEdit

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SetSize

ValidateEdit


Events for TcxDBButtonEdit
TcxDBButtonEdit Events

TcxDBButtonEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxDBButtonEdit.DataBinding

TcxDBButtonEdit

Specifies the dataset connection.

property DataBinding: TcxDBTextEditDataBinding;

Description

Use the DataBinding property to access a TcxDBTextEditDataBinding instance to establish a connection to a dataset.  You should use the DataSource and DataField properties of the DataBinding object to enable the TcxDBButtonEdit control to edit a specific field value from the dataset.


TcxDBCheckBox
 TcxDBCheckBox Object

Hierarchy          Properties          Methods          Events          See Also

Represents a data-aware control which supports "checked", "unchecked" and "grayed" states.

Unit

cxDBEdit

TcxDBCheckBox = class(TcxCustomCheckBox);

Description

Like TcxCheckBox, a TcxDBCheckBox control represents an option.  A user can set a check box to one of three states: checked, unchecked and grayed.  By default, only checked and unchecked states are available.  To enable a user to set a grayed state you should assign True to the AllowGrayed member of the Properties object.  A user can switch between states by clicking an editor with the mouse or pressing the keyboard space bar while the editor has focus.  The following image displays a check box editor painted using the Windows XP look & feel:

To connect a data-aware control to a dataset, set the DataSource and DataField properties of the DataBinding object.

You can associate specific values with every state via the ValueChecked, ValueUnchecked or ValueGrayed members of the Properties object.  These values will be posted to the dataset when a user sets a check box to the corresponding state.  Conversely, when your editor retrieves a dataset value, it is set to one of the three states:

•	the checked state if a field specifies the ValueChecked property value;

•	the unchecked state if a field specifies the ValueUnchecked property value;

•	the grayed state if a field identifies neither the ValueChecked nor the ValueUnchecked property value.

Use the Properties and style (Style, StyleDisabled, StyleFocused and StyleHot) members to specify the behavior and look & feel of an editor.  Working with styles is discussed in the TcxCustomEditStyle class topic.

To set the state programmatically, use either the Checked or the State property. The Checked property is of type Boolean and so can only identify only checked and unchecked states.  The State property is more flexible and allows you to select one of the three states.


TcxDBCheckBox Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomCheckBox

     |


Properties for TcxDBCheckBox
TcxDBCheckBox Properties

TcxDBCheckBox          Legend

In TcxDBCheckBox

DataBinding

Derived from TcxCustomCheckBox

ActiveProperties

Checked

Properties

State

Derived from TcxCustomEdit

ActiveProperties

AutoSize

DataBinding

EditModified

EditValue

InnerEdit

ModifiedAfterEnter

Properties

RepositoryItem

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TControl

Align

Caption


Methods for TcxDBCheckBox
TcxDBCheckBox Methods

TcxDBCheckBox          Legend

Derived from TcxCustomCheckBox

Toggle

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxDBCheckBox
TcxDBCheckBox Events

TcxDBCheckBox          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxDBCheckBox.DataBinding

TcxDBCheckBox

Specifies the connection to a dataset.

property DataBinding: TcxDBEditDataBinding;

Description

Use the DataBinding property to access a TcxDBEditDataBinding instance to establish a connection to a dataset.  You should set the DataSource and DataField properties of the DataBinding object to enable the TcxDBCheckBox control to edit a specific field value from the dataset.


TcxDBComboBox
 TcxDBComboBox Object

Hierarchy          Properties          Methods          Events          See Also

Represents a data-aware combo box editor.

Unit

cxDBEdit

TcxDBComboBox = class(TcxCustomComboBox);

Description

A data-aware combo box editor allows you to edit data from the associated field either by selecting the required value from the dropdown list or by typing text in the edit box part of your control.  The image below demonstrates a combo box editor painted in the XP style:

You can use the TcxDBMRUEdit control for the same purpose.  However, an MRU-editor stores values entered by a user into the associated dropdown list at runtime.

The TcxDBComboBox control’s functionality is similar to TcxComboBox, but it allows editing dataset values.  To connect a data-aware control to a dataset, it is necessary to set the DataSource and DataField properties of the DataBinding object.

Use the Items attribute of the Properties object to populate the list of strings displayed within the dropdown window.  When a user enters text into an editor, that text can be automatically completed to match a value from the editor dropdown.

A combo box editor can be used to display values from its dropdown without inputting text into the edit region of a control.  Set the DropDownListStyle member of the Properties object to the IsFixedList value to implement this type of combo box behavior.  A user can activate the popup by clicking the dropdown button or by pressing the Up Arrow and Down Arrow keys combined with the Alt key or by pressing the F4 key.

The Properties object provides various settings specific to combo box editors: text alignment, the type of dropdown list, the mask to enter values, the immediate dropdown feature and many others.

Use the Style, StyleDisabled, StyleFocused and StyleHot members to specify the look & feel of an editor and its dropdown window.  Working with styles is discussed in TcxCustomEditStyle topic.


TcxDBComboBox Hierarchy
Hierarchy

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomComboBox

     |


Properties for TcxDBComboBox
TcxDBComboBox Properties

TcxDBComboBox          Legend

In TcxDBComboBox

DataBinding

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxDBComboBox
TcxDBComboBox Methods

TcxDBComboBox          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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxDBComboBox
TcxDBComboBox Events

TcxDBComboBox          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxDBComboBox.DataBinding

TcxDBComboBox

Specifies the dataset connection.

property DataBinding: TcxDBTextEditDataBinding;

Description

Use the DataBinding property to access a TcxDBTextEditDataBinding instance to establish a connection to a dataset.  You should use the DataSource and DataField properties of the DataBinding object to enable the TcxDBComboBox control to edit a specific field value from the dataset.


TcxDBEditDataBinding
TcxDBEditDataBinding Object

Hierarchy          Properties          Methods

Represents an editor connection to a data storage.

Unit

cxDBEdit

TcxDBEditDataBinding = class(TcxEditDataBinding);

Description

The TcxDBEditDataBinding class encapsulates a dataset connection of a data-aware control.  Every data-aware control has the DataBinding property to establish a connection.  To link to a dataset you have to

1.	place a dataset (TTable, TQuery for instance) onto a form, adjust appropriate properties and set Active to True.

2.	place a data source component (TDataSource) onto a form and set its DataSet property to the dataset you placed in step 1.

3.	place the required data-aware editor onto a form.  Set the DataSource property of its DataBinding object to the data source you created in step 2.  Set the DataField property of the DataBinding object to the name of a dataset field or select it from the dropdown list in the Object Inspector.

For more information, refer to the Delphi (C++ Builder) documentation.


TcxDBEditDataBinding Hierarchy
Hierarchy

TPersistent

     |

TcxEditDataBinding

     |


Properties for TcxDBEditDataBinding
TcxDBEditDataBinding Properties

TcxDBEditDataBinding          Legend

In TcxDBEditDataBinding

DataField

DataSource

Field

Derived from TcxEditDataBinding

StoredValue


Methods for TcxDBEditDataBinding
TcxDBEditDataBinding Methods

TcxDBEditDataBinding          Legend

Derived from TcxEditDataBinding

SetEditMode


TcxDBEditDataBinding.DataField

TcxDBEditDataBinding          See Also

Specifies the database field from which a data-aware editor retrieves data.

property DataField: string;

Description

To begin using a dataset you have to set the DataSource and DataField properties.  The DataSource property defines dataset links.  It is like a conduit between data-aware controls and datasets.  To enable editing data from a dataset via an editor you have to:

1)	place the dataset and data source components onto a form. Set necessary properties for both components;

2)	assign the editor’s DataSource property to the data source component;

3)	set the editor’s DataField property to the dataset field name.


TcxDBEditDataBinding.DataSource

TcxDBEditDataBinding          See Also

Specifies the dataset link.

property DataSource: TDataSource;

Description

To begin working with a dataset you have to set the DataSource and DataField properties.  The DataSource property defines dataset links.  It is like a conduit between data-aware controls and datasets.  To enable editing data from a dataset via an editor you have to:

1)	place the dataset and data source components onto a form. Set necessary properties for both components;

2)	assign the editor’s DataSource property to the data source component;

3)	set the editor’s DataField property to the dataset field name.


TcxDBEditDataBinding.Field

TcxDBEditDataBinding

Gets the dataset field to which an editor is connected.

property Field: TField;

Description

You can use the Field property to get direct access to the contents and properties of a database field.  To connect an editor to a field, assign the DataField property.

ReadOnly Property


TcxDBMaskEdit
 TcxDBMaskEdit Object

Hierarchy          Properties          Methods          Events          See Also

Represents a masked editor that enables displaying and editing text fields within a dataset.

Unit

cxDBEdit

TcxDBMaskEdit = class(TcxCustomMaskEdit);

Description

A masked editor allows you to validate the text a user enters against a specific mask and to format this text.  The TcxDBMaskEdit control’s functionality is similar to TcxMaskEdit, but it provides editing dataset field values.

To connect a data-aware control to a dataset set the DataSource and DataField properties of the DataBinding object.

The Properties object provides various settings controlling the editor behavior.  The EditMask property is the main property defining a mask itself.  A mask formalizes user input and formats the display text.  It is possible to set a mask using the Input Mask Editor dialog activated via the Object Inspector.  A masked editor supports three types of masks: standard, regular expressions and extended regular expressions.  The standard mask is the same as the mask used in the standard TMaskEdit control.  Regular expressions provide more flexibility to specify the mask.  Extended regular expressions are like ordinary regular expressions but enable the auto completion feature.  The syntax of masks is described in the Using MaskEdit topic.

Use the Style, StyleDisabled, StyleFocused and StyleHot properties to determine the look & feel of mask editors.  Working with styles is discussed in the TcxCustomEditStyle class topic.


TcxDBMaskEdit Hierarchy
Hierarchy

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |


Properties for TcxDBMaskEdit
TcxDBMaskEdit Properties

TcxDBMaskEdit          Legend

In TcxDBMaskEdit

DataBinding

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxDBMaskEdit
TcxDBMaskEdit Methods

TcxDBMaskEdit          Legend

Derived from TcxCustomMaskEdit

CutToClipboard

PasteFromClipboard

Derived from TcxCustomTextEdit

Clear

ClearSelection

CopyToClipboard

Create

CutToClipboard

SelectAll

SetSelection

Undo

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxDBMaskEdit
TcxDBMaskEdit Events

TcxDBMaskEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxDBMaskEdit.DataBinding

TcxDBMaskEdit

Specifies the dataset connection.

property DataBinding: TcxDBTextEditDataBinding;

Description

Use the DataBinding property to access a TcxDBTextEditDataBinding instance to establish a connection to a dataset.  You should use the DataSource and DataField properties of the DataBinding object to enable the TcxDBMaskEdit control to edit a specific field value from the dataset.


TcxDBMemo
 TcxDBMemo Object

Hierarchy          Properties          Methods          Events          See Also

Represents a memo editor that enables editing dataset fields.

Unit

cxDBEdit

TcxDBMemo = class(TcxCustomMemo);

Description

The TcxDBMemo control enables editing lengthy textual data.  Data is displayed within the region of a multi-line editor.  By default, words are wrapped.  The behavior of TcxDBMemo is similar to the TcxMemo control except that it allows editing the contents of dataset fields.

To connect a data-aware control to a dataset, set the DataSource and DataField properties of the DataBinding object.

The Properties object provides various settings specific to memo editors: text alignment, maximum text length, read-only status and many others.

Use the Style, StyleDisabled, StyleFocused and StyleHot properties to adjust the look & feel of a memo editor in various control’s states.  Working with styles is discussed in the TcxCustomEditStyle class topic.


TcxDBMemo Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMemo

     |


Properties for TcxDBMemo
TcxDBMemo Properties

TcxDBMemo          Legend

In TcxDBMemo

DataBinding

Derived from TcxCustomMemo

ActiveProperties

Lines

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName

Derived from TControl

Align


Methods for TcxDBMemo
TcxDBMemo Methods

TcxDBMemo          Legend

Derived from TcxCustomTextEdit

Clear

ClearSelection

CopyToClipboard

Create

CutToClipboard

SelectAll

SetSelection

Undo

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

SetSize

ValidateEdit


Events for TcxDBMemo
TcxDBMemo Events

TcxDBMemo          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxDBMemo.DataBinding

TcxDBMemo

Specifies the dataset connection.

property DataBinding: TcxDBTextEditDataBinding;

Description

Use the DataBinding property to access a TcxDBTextEditDataBinding instance to establish a connection to a dataset.  You should use the DataSource and DataField properties of the DataBinding object to enable the TcxDBMemo control to edit a specific field value from the dataset.


TcxDBPopupEdit
 TcxDBPopupEdit Object

Hierarchy          Properties          Methods          Events          See Also

Represents a data-aware text editor with a popup window embedding a control.

Unit

cxDBEdit

TcxDBPopupEdit = class(TcxCustomPopupEdit);

Description

The TcxDBPopupEdit control allows editing text fields in a dataset.  The TcxDBPopupEdit editor has a popup window, which can embed another control in it.  The following image demonstrates a popup editor displaying the TPanel control within its popup window.  The panel contains three buttons and a memo component.  The popup window is painted in the XP style.

The DataBinding object determines a dataset connection.  Set the DataSource and DataField properties of the DataBinding object to make a data-aware control represent values from a dataset field.

To embed your control into the popup window use the PopupControl property of the Properties object.  At runtime, a user can work with the control placed onto the popup window in the same manner as with its standalone version.

To open or close the popup window you can use the DroppedDown property.  Set it to True to activate the popup window.  At runtime, a user can activate the popup by clicking the dropdown button or by pressing the Up Arrow and Down Arrow keys combined with the Alt key or by pressing the F4 key.

Use the Style, StyleDisabled, StyleFocused and StyleHot properties to control the look & feel of a memo editor.  Working with styles is discussed in the TcxCustomEditStyle class topic.


TcxDBPopupEdit Hierarchy
Hierarchy

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomPopupEdit

     |


Properties for TcxDBPopupEdit
TcxDBPopupEdit Properties

TcxDBPopupEdit          Legend

In TcxDBPopupEdit

DataBinding

Derived from TcxCustomPopupEdit

ActiveProperties

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxDBPopupEdit
TcxDBPopupEdit Methods

TcxDBPopupEdit          Legend

Derived from TcxCustomPopupEdit

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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxDBPopupEdit
TcxDBPopupEdit Events

TcxDBPopupEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxDBPopupEdit.DataBinding

TcxDBPopupEdit

Specifies the dataset connection.

property DataBinding: TcxDBTextEditDataBinding;

Description

Use the DataBinding property to access a TcxDBTextEditDataBinding instance to establish a connection to a dataset.  You should use the DataSource and DataField properties of the DataBinding object to enable the TcxDBPopupEdit control to edit a specific field value from the dataset.


TcxDBSpinEdit
 TcxDBSpinEdit Object

Hierarchy          Properties          Methods          Events          See Also

Represents a spin editor, which enables editing numerical dataset fields.

Unit

cxDBEdit

TcxDBSpinEdit = class(TcxCustomSpinEdit);

Description

A spin editor is a control that enables editing numerical values by clicking so-called "spin buttons" (up and down arrows displayed within an editor).  They allow incrementing and decrementing a number by some amount (integer or floating-point).  It is also possible to enter a value directly by typing it.  The following image demonstrates a spin editor painted using the UltraFlat style:

The DataBinding property allows you to connect an editor to a dataset.  To do this, you have to set the DataSource and DataField members of the DataBinding property.

TcxDBSpinEdit is similar to the TcxSpinEdit control except that it is designed to edit numerical (integer or floating point) dataset fields.  To access a value displayed by a spin editor, use the Value property.  It specifies the currently edited value.  When a user either exits the editor or presses the Enter key, this value is stored in the EditValue property.

The Properties object defines different settings specific to spin editors.  The Increment member defines the number by which a specific value is changed every time a user clicks spin buttons or presses the Up and Down keys (if the UseCtrlIncrement property is set to True, the Up and Down keys must be combined with the Ctrl key).  Use the MaxValue and MinValue properties to limit the numbers which a spin editor can represent.  They define the range of acceptable values.  A spin editor can represent either integer or double values.  The ValueType property controls the type of spin edit value and specifies the manner in which the increment number is interpreted.  It is possible to prohibit users from editing values directly.  Set the CanEdit property to False to restrict the user to change a value by clicking a spin button or by pressing the Up/Down keys (or the Ctrl-Up, Ctrl-Down keys).  The Properties object provides an OnChange event, which is generated every time the display value changes.

To adjust style attributes use the Style, StyleDisabled, StyleFocused and StyleHot properties.  Working with styles is discussed in the TcxCustomEditStyle class topic.


TcxDBSpinEdit Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomSpinEdit

     |


Properties for TcxDBSpinEdit
TcxDBSpinEdit Properties

TcxDBSpinEdit          Legend

In TcxDBSpinEdit

DataBinding

Derived from TcxCustomSpinEdit

ActiveProperties

Properties

Value

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxDBSpinEdit
TcxDBSpinEdit Methods

TcxDBSpinEdit          Legend

Derived from TcxCustomSpinEdit

GetIncrement

Derived from TcxCustomMaskEdit

CutToClipboard

PasteFromClipboard

Derived from TcxCustomTextEdit

Clear

ClearSelection

CopyToClipboard

Create

CutToClipboard

SelectAll

SetSelection

Undo

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxDBSpinEdit
TcxDBSpinEdit Events

TcxDBSpinEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxDBSpinEdit.DataBinding

TcxDBSpinEdit

Specifies the dataset connection.

property DataBinding: TcxDBEditDataBinding;

Description

Use the DataBinding property to access a TcxDBEditDataBinding instance to establish a connection to a dataset.  You should use the DataSource and DataField properties of the DataBinding object to enable the TcxDBSpinEdit control to edit a specific field value from the dataset.


TcxDBTextEdit
 TcxDBTextEdit Object

Hierarchy          Properties          Methods          Events          See Also

Represents a data-aware editor, which enables editing textual data.

Unit

cxDBEdit

TcxDBTextEdit = class(TcxCustomTextEdit);

Description

The TcxDBTextEdit control represents a single-line text editor.  It is similar to the TcxTextEdit control except for it is designed to work with dataset text or numerical fields.  A text editor provides methods and properties to select text, copy/paste etc.  It enables validation and the auto-completion feature.

To connect a data-aware control to a dataset, set the DataSource and DataField properties of the DataBinding object.

The Properties object provides many settings specific to text editors: text alignment, maximum text length, strings for the auto complete feature, the echo mode and others.

Use the Style, StyleDisabled, StyleFocused and StyleHot properties to adjust the look & feel of an editor.  Working with styles is discussed in the TcxCustomEditStyle class topic.


TcxDBTextEdit Hierarchy
Hierarchy

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |


Properties for TcxDBTextEdit
TcxDBTextEdit Properties

TcxDBTextEdit          Legend

In TcxDBTextEdit

DataBinding

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxDBTextEdit
TcxDBTextEdit Methods

TcxDBTextEdit          Legend

Derived from TcxCustomTextEdit

Clear

ClearSelection

CopyToClipboard

Create

CutToClipboard

SelectAll

SetSelection

Undo

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxDBTextEdit
TcxDBTextEdit Events

TcxDBTextEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxDBTextEdit.DataBinding

TcxDBTextEdit

Specifies the dataset connection.

property DataBinding: TcxDBTextEditDataBinding;

Description

Use the DataBinding property to access a TcxDBTextEditDataBinding instance to establish a connection to a dataset.  You should use the DataSource and DataField properties of the DataBinding object to enable the TcxDBTextEdit control to edit a specific field value from the dataset.


TcxDBTextEditDataBinding
TcxDBTextEditDataBinding Object

Hierarchy          Properties          Methods

Represents an editor connection to a data storage.

Unit

cxDBEdit

TcxDBTextEditDataBinding = class(TcxDBEditDataBinding);

Description

The TcxDBTextEditDataBinding class encapsulates a dataset connection of a data-aware control.  It overrides some TcxDBEditDataBinding methods for more convenient work with data-aware text editors.

Every data-aware control has a DataBinding property to establish a connection.  To connect to a dataset you have to:

1.	place your dataset (TTable, TQuery, for instance) onto a form, adjust its properties as necessary and set Active to True.

2.	place a data source component (TDataSource) onto a form and set its DataSet property to the dataset you placed in step 1.

3.	place the required data-aware editor onto a form.  Set the DataSource property of its DataBinding object to the data source you created in step 2.  Set the DataField property of the DataBinding object to the dataset field name or select it from the dropdown list in the Object Inspector.

For more information, refer to the Delphi (C++ Builder) documentation.


TcxDBTextEditDataBinding Hierarchy
Hierarchy

TPersistent

     |

TcxEditDataBinding

     |

TcxDBEditDataBinding

     |


Properties for TcxDBTextEditDataBinding
TcxDBTextEditDataBinding Properties

TcxDBTextEditDataBinding          Legend

Derived from TcxDBEditDataBinding

DataField

DataSource

Field

Derived from TcxEditDataBinding

StoredValue


Methods for TcxDBTextEditDataBinding
TcxDBTextEditDataBinding Methods

TcxDBTextEditDataBinding          Legend

Derived from TcxEditDataBinding

SetEditMode


TcxDBTimeEdit
 TcxDBTimeEdit Object

Hierarchy          Properties          Methods          Events          See Also

Represents a data-aware editor which enables editing time values.

Unit

cxDBEdit

TcxDBTimeEdit = class(TcxCustomTimeEdit)

Description

A time editor allows editing time values of the TDateTime type.  TDateTime represents a floating-point value.  The fractional part of a TDateTime value identifies the time portion (fraction of a 24 hour day that has elapsed).  TcxDBTimeEdit is similar to the TcxTimeEdit control except that it enables editing date-time dataset fields.  A user can edit a time value either by typing it or by changing it with the help of spin buttons.  Spin buttons allow incrementing and decrementing the selected time value portion: hours, minutes, seconds.  The following image demonstrates a time edit painted in the XP style:

To adjust settings specific to time editors, use the Properties object and this allows you to define the time format, value alignment, read-only status and many others.  Use the Style, StyleDisabled, StyleFocused and StyleHot properties to manage the look & feel of an editor.  Working with styles is discussed in the TcxCustomEditStyle class topic.

The DataBinding property defines a dataset connection.  To connect a data-aware editor, you need to set the DataSource and DataField properties of the DataBinding object.


TcxDBTimeEdit Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomSpinEdit

     |

TcxCustomTimeEdit

     |


Properties for TcxDBTimeEdit
TcxDBTimeEdit Properties

TcxDBTimeEdit          Legend

In TcxDBTimeEdit

DataBinding

Derived from TcxCustomTimeEdit

ActiveProperties

Properties

Time

Derived from TcxCustomSpinEdit

ActiveProperties

Properties

Value

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxDBTimeEdit
TcxDBTimeEdit Methods

TcxDBTimeEdit          Legend

Derived from TcxCustomSpinEdit

GetIncrement

Derived from TcxCustomMaskEdit

CutToClipboard

PasteFromClipboard

Derived from TcxCustomTextEdit

Clear

ClearSelection

CopyToClipboard

Create

CutToClipboard

SelectAll

SetSelection

Undo

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxDBTimeEdit
TcxDBTimeEdit Events

TcxDBTimeEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxDBTimeEdit.DataBinding

TcxDBTimeEdit

Specifies the dataset connection.

property DataBinding: TcxDBTextEditDataBinding;

Description

Use the DataBinding property to access a TcxDBTextEditDataBinding instance to establish a connection to a dataset.  You should use the DataSource and DataField properties of the DataBinding object to enable the TcxDBTimeEdit control to edit a specific field value from the dataset.


cxDBEditRepository Unit Overview
cxDBEditRepository Unit

See Also

Classes

TcxEditRepositoryLookupComboBoxItem


TcxEditRepositoryLookupComboBoxItem
TcxEditRepositoryLookupComboBoxItem Object

Hierarchy          Properties          Methods          See Also

Represents a repository item containing settings specific to a TcxLookupComboBox control.

Unit

cxDBEditRepository

TcxEditRepositoryLookupComboBoxItem = class(TcxEditRepositoryItem);

Description

TcxEditRepositoryLookupComboBoxItem stores properties specific to a TcxLookupComboBox control via a Properties object.  A repository object of the TcxEditRepository class maintains a collection of repository items.


TcxEditRepositoryLookupComboBoxItem Hierarchy
Hierarchy

TComponent

     |

TcxEditRepositoryItem

     |


Properties for TcxEditRepositoryLookupComboBoxItem
TcxEditRepositoryLookupComboBoxItem Properties

TcxEditRepositoryLookupComboBoxItem          Legend

In TcxEditRepositoryLookupComboBoxItem

Properties

Derived from TcxEditRepositoryItem

Properties

Repository


Methods for TcxEditRepositoryLookupComboBoxItem
TcxEditRepositoryLookupComboBoxItem Methods

TcxEditRepositoryLookupComboBoxItem          Legend

Derived from TcxEditRepositoryItem

 Create

 Destroy

 GetBaseName


TcxEditRepositoryLookupComboBoxItem.Properties

TcxEditRepositoryLookupComboBoxItem

Defines settings specific to a specific editor.

property Properties: TcxLookupComboBoxProperties;

Description

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


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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

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 an editor.

property ActiveProperties: TcxExtLookupComboBoxProperties;

Description

Use the ActiveProperties property to obtain the properties of the current editor that are currently in effect.  This property is especially useful when the 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 editor.  Otherwise, the inherent 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 an 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

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

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

In 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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


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.

To control any changes made to the editor’s DisplayFormat, EditFormat, MaxLength, MaxValue, MinValue and ReadOnly properties and reverse their values back to the default ones, use the AssignedValues property.


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

IncrementalSearch

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

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

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

Set the FocusPopup property to True to enable editing and filtering data within the dropdown view of the ExtLookupEditor.  When the dropdown window is opened, for instance, by clicking the dropdown button or by pressing the F4, Alt+Up arrow or Alt+Down arrow keys, the focus is moved to the view.  This view is specified by the View property.

If the FocusPopup property is set to 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:

•	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.


cxDBFontNameComboBox Unit Overview
cxDBFontNameComboBox Unit

Classes

TcxDBFontNameComboBox


TcxDBFontNameComboBox
 TcxDBFontNameComboBox Object

Hierarchy          Properties          Methods          Events          See Also

Represents data aware version of the TcxFontNameComboBox.

Unit

cxDBFontNameComboBox

TcxDBFontNameComboBox = class(TcxCustomFontNameComboBox)

Description

The TcxDBFontNameComboBox is a data-aware combo box control intended to work with the fonts (font names) currently installed in the system.  Various control settings can be accessed by the Properties of a control.

The main features of the cxDBFontNameComboBox include:

•	selecting and preview fonts and font groups,

•	building the MRU (most recently used) fonts list,

•	adjusting the selected font attributes (bold, italic, underline and strikeout).

The data-aware functionality of the TcxDBFontNameComboBox is encapsulated in the DataBinding property.   It allows you to specify DataSource and DataField to which the editor is bound.

This database field must contain string values (font names).


TcxDBFontNameComboBox Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomComboBox

     |

TcxCustomFontNameComboBox

     |


Properties for TcxDBFontNameComboBox
TcxDBFontNameComboBox Properties

TcxDBFontNameComboBox          Legend

In TcxDBFontNameComboBox

DataBinding

Derived from TcxCustomFontNameComboBox

ActiveProperties

ItemIndex

Properties

Derived from TcxCustomComboBox

ActiveProperties

ItemIndex

Properties

Derived from TcxCustomDropDownEdit

ActiveProperties

DroppedDown

PopupWindow

Properties

Derived from TcxCustomTextEdit

ActiveProperties

BeepOnEnter

CursorPos

EditingText

Properties

SelLength

SelStart

SelText

Text

Derived from TcxCustomEdit

ActiveProperties

AutoSize

EditModified

EditValue

InnerEdit

ModifiedAfterEnter

Properties

RepositoryItem

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxDBFontNameComboBox
TcxDBFontNameComboBox Methods

TcxDBFontNameComboBox          Legend

Derived from TcxCustomFontNameComboBox

AddMRUFontName

DelMRUFontName

Derived from TcxCustomComboBox

CanDropDown

Derived from TcxCustomDropDownEdit

CanDropDown

CloseUp

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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit


Events for TcxDBFontNameComboBox
TcxDBFontNameComboBox Events

TcxDBFontNameComboBox          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxDBFontNameComboBox.DataBinding

TcxDBFontNameComboBox

Specifies a data source connection.

property DataBinding: TcxDBEditDataBinding;

Description

Use the DataBinding property to access a TcxDBEditDataBinding instance used to establish a connection to a data source.  The DataBinding.DataSource property identifies a dataset to which to connect.  The DataBinding.DataField property specifies the data source field whose value is to be edited by the font name combo box.


cxDBLabel Unit Overview
cxDBLabel Unit

Classes

TcxDBLabel


TcxDBLabel
 TcxDBLabel Object

Hierarchy          Properties          Methods          Events          See Also

Represents data aware version of the TcxLabel.

Unit

cxDBLabel

TcxDBLabel = class(TcxCustomLabel)

Description

The TcxDBLabel represents the data-aware version of the label control intended to display a short block of information or explain the meaning of the other controls.  Modify the way in which it displays using its Properties property.

The TcxDBLabel’s data-aware functionality is provided by the DataBinding property.   It allows you to specify the DataSource and DataField to which the editor is bound.

Note:	The default value of the AutoSize property for the TcxDBLabel object is False.


TcxDBLabel Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomLabel

     |


Properties for TcxDBLabel
TcxDBLabel Properties

TcxDBLabel          Legend

In TcxDBLabel

DataBinding

Derived from TcxCustomLabel

ActiveProperties

AutoSize

Caption

Properties

Derived from TcxCustomEdit

ActiveProperties

AutoSize

DataBinding

EditModified

EditValue

InnerEdit

ModifiedAfterEnter

Properties

RepositoryItem

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName

Derived from TControl

Align


Methods for TcxDBLabel
TcxDBLabel Methods

TcxDBLabel          Legend

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit


Events for TcxDBLabel
TcxDBLabel Events

TcxDBLabel          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxDBLabel.DataBinding

TcxDBLabel

Specifies a data source connection.

property DataBinding: TcxDBEditDataBinding;

Description

Use the DataBinding property to access the TcxDBEditDataBinding instance used to establish the connection to a data source.  The DataBinding.DataSource property identifies the dataset to which to connect.  The DataBinding.DataField property specifies the data source field to be displayed by the label control.


TcxDBListBox
 TcxDBListBox Object

Hierarchy          Properties          Methods          Events

Represents the data-aware version of TcxListBox.

Unit

cxDBEdit

TcxDBListBox = class(TcxListBox)

Description

TcxDBListBox is the data-aware version of the cxListBox control.  This control uses the standard list box control (TListBox) to implement most of its functionality.  Thus, most properties, methods and events of the TcxListBox control are identical to those of the TListBox control.

The following basic features are available in the list box control:

•	Displaying, sorting, selecting items within the list;

•	Moving and copying items to another list control;

•	Arranging items into several columns;

•	Painting items in a custom manner and assigning custom height to individual items;

•	Working in virtual mode – item captions and data are supplied using event handlers.

The TcxDBListBox control is bound to a DataBinding.DataSource field specified by the DataBinding.DataField property.  In order to perform correct data source editing, the data-bound list box must be populated with DataBinding.DataField values.  When you navigate the data set, the list box item corresponding to the bound field value within the current record is highlighted.  If you select another list box item, then the corresponding field value changes.  If the current record’s field value has no corresponding items within the list, then no items are highlighted within the list box.


TcxDBListBox Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxListBox

     |


Properties for TcxDBListBox
TcxDBListBox Properties

TcxDBListBox          Legend

In TcxDBListBox

DataBinding

Derived from TcxListBox

AutoComplete

AutoCompleteDelay

Columns

Count

ExtendedSelect

IntegralHeight

ItemHeight

ItemIndex

ItemObject

Items

ListStyle

MultiSelect

ReadOnly

ScrollWidth

SelCount

Selected

Sorted

TopIndex

Derived from TcxContainer

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxDBListBox
TcxDBListBox Methods

TcxDBListBox          Legend

Derived from TcxListBox

AddItem

Clear

ClearSelection

CopySelection

Create

DeleteSelected

Destroy

ItemAtPos

ItemRect

MoveSelection

SelectAll

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxDBListBox
TcxDBListBox Events

TcxDBListBox          Legend

Derived from TcxListBox

OnData

OnDataFind

OnDataObject

OnDrawItem

OnMeasureItem


TcxDBListBox.DataBinding

TcxDBListBox          See Also

Specifies a data source connection.

property DataBinding: TcxDBDataBinding;

Description

Use the DataBinding property to access a TcxDBDataBinding instance to establish a connection to a dataset.  You should use the DataSource and DataField properties of the DataBinding object so the list box control can edit a specific field value from the dataset.


TcxCustomDBDataBinding
TcxCustomDBDataBinding Object

Hierarchy          Properties

Serves as the base for objects used to bind a control to a dataset field.

Unit

cxDB

TcxCustomDBDataBinding = class(TcxCustomDataBinding)

Description

Data-aware controls are bound to data by means of specially designed objects.  These objects manage the interchange of data between the control and the source.  The methods required by such objects are declared by the TcxCustomDataBinding class.  The TcxCustomDBDataBinding object overrides these methods to implement this binding.

The TcxCustomDBDataBinding class is the ancestor of the TcxDBDataBinding object.  The latter is used to bind the TcxDBListBox control to a dataset field.  It can be accessed via the DataBinding property of the list box.

The TcxCustomDBDataBinding class implements all the functionality required to perform data binding.  Its descendant simply publishes the DataSource and DataField properties.


TcxCustomDBDataBinding Hierarchy
Hierarchy

TPersistent

     |

TcxCustomDataBinding

     |


Properties for TcxCustomDBDataBinding
TcxCustomDBDataBinding Properties

TcxCustomDBDataBinding          Legend

In TcxCustomDBDataBinding

DataField

DataSource

Field


TcxCustomDBDataBinding.DataField

TcxCustomDBDataBinding          See Also

Specifies the database field from which a data-aware editor retrieves data.

property DataField: string;

Description

To begin using a dataset you have to set the DataSource and DataField properties.  The DataSource property defines dataset links.  It is like a conduit between data-aware controls and datasets.  To enable editing data from a dataset via an editor you have to:

1)	place the dataset and data source components onto a form. Set necessary properties for both components;

2)	assign the editor’s DataSource property to the data source component;

3)	set the editor’s DataField property to the dataset field name.


TcxCustomDBDataBinding.DataSource

TcxCustomDBDataBinding          See Also

Specifies the dataset link.

property DataSource: TDataSource;

Description

To begin working with a dataset you have to set the DataSource and DataField properties.  The DataSource property defines dataset links.  It is like a conduit between data-aware controls and datasets.  To enable editing data from a dataset via an editor you have to:

1)	place the dataset and data source components onto a form. Set necessary properties for both components;

2)	assign the editor’s DataSource property to the data source component;

3)	set the editor’s DataField property to the dataset field name.


TcxCustomDBDataBinding.Field

TcxCustomDBDataBinding          See Also

Gets the dataset field to which an editor is connected.

property Field: TField;

Description

You can use the Field property to get direct access to the contents and properties of a database field.  To connect an editor to a field, assign the DataField property.

ReadOnly Property


TcxDBDataBinding
TcxDBDataBinding Object

Hierarchy          Properties          See Also

Used to bind a data-aware control to a dataset field.

Unit

cxDB

TcxDBDataBinding = class(TcxCustomDBDataBinding)

Description

The TcxDBDataBinding object can be accessed via the DataBinding property of the TcxDBListBox control.  Properties of the object are used to bind the data-aware list box to a dataset field.  To do this, you must set the DataSource and DataField properties to appropriate values.

The TcxDBDataBinding object is derived from the TcxCustomDBDataBinding class.  It doesn’t introduce any new functionality but simply publishes the DataSource and DataField properties.


TcxDBDataBinding Hierarchy
Hierarchy

TPersistent

     |

TcxCustomDataBinding

     |

TcxCustomDBDataBinding

     |


Properties for TcxDBDataBinding
TcxDBDataBinding Properties

TcxDBDataBinding          Legend

Derived from TcxCustomDBDataBinding

DataField

DataSource

Field


TcxCustomDataBinding
TcxCustomDataBinding Object

Hierarchy

Serves as the base for objects that bind controls to data.

Unit

cxDataUtils

TcxCustomDataBinding = class(TPersistent)

Description

Data-aware controls can be bound to data by means of objects which provide a conduit between the source and the control.  The TcxCustomDataBinding class implements the basic functionality of such classes.  It declares methods that are overridden by its descendants in order to link data from data sources to controls.

The TcxCustomDataBinding class serves as the base for the TcxCustomDBDataBinding object.  The latter implements the binding of a control to a dataset field.


TcxCustomDataBinding Hierarchy
Hierarchy

TPersistent

     |


cxDBProgressBar Unit Overview
cxDBProgressBar Unit

Classes

TcxDBProgressBar


TcxDBProgressBar
 TcxDBProgressBar Object

Hierarchy          Properties          Methods          Events          See Also

Represents the data-aware version of the TcxProgressBar.

Unit

cxDBProgressBar

TcxDBProgressBar = class(TcxCustomProgressBar)

Description

The TcxDBProgressBar is a data-aware version of the advanced progress bar control. Almost every aspect of the control’s visualization can be controlled through the Properties of the control.

The main features of the advanced progress bar are listed below:

•	Vertical orientation support (see the Properties.Orientation and Properties.TextOrientation property);

•	Multiple bar filling styles support – solid, gradient, rectangles, bitmaps (see the Properties.BarStyle and Properties.ForegroundImage properties);

•	Overload bar support – the bar can be divided into two parts with different styles (see the Properties.ShowOverload property);

•	Peak value support – the progress bar is capable of displaying a peak value (see the Properties.ShowPeak property);

•	Two text styles support – the progress bar can display the current position or the percentage (see the Properties.ShowTextStyle property);

•	XP theme support (see the Style.LookAndFeel.NativeStyle property).

The data-aware functionality of the TcxDBProgressBar is encapsulated in the DataBinding property.   It allows you to specify DataSource and DataField to which the editor is bound.

This database field must contain integer values.  These field values are interpreted as the position of the progress bar indicator and they must not exceed the limits specified by the Properties.Max and Properties.Min properties.


TcxDBProgressBar Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomProgressBar

     |


Properties for TcxDBProgressBar
TcxDBProgressBar Properties

TcxDBProgressBar          Legend

In TcxDBProgressBar

DataBinding

Derived from TcxCustomProgressBar

ActiveProperties

Position

Properties

Derived from TcxCustomEdit

ActiveProperties

AutoSize

DataBinding

EditModified

EditValue

InnerEdit

ModifiedAfterEnter

Properties

RepositoryItem

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TControl

Align


Methods for TcxDBProgressBar
TcxDBProgressBar Methods

TcxDBProgressBar          Legend

Derived from TcxCustomProgressBar

Create

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit


Events for TcxDBProgressBar
TcxDBProgressBar Events

TcxDBProgressBar          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxDBProgressBar.DataBinding

TcxDBProgressBar

Specifies a data source connection.

property DataBinding: TcxDBEditDataBinding;

Description

Use the DataBinding property to access a TcxDBEditDataBinding instance used to establish a connection to a data source.  The DataBinding.DataSource property identifies a dataset to which to connect.  The DataBinding.DataField property specifies the data source field whose value is to be displayed by the progress bar control.


cxDBShellComboBox Unit Overview
cxDBShellComboBox Unit

Components

TcxDBShellComboBox


TcxDBShellComboBox
 TcxDBShellComboBox Object

Hierarchy          Properties          Methods          Events

Represents the data-aware version of the shell combo box control.

Unit

cxDBShellComboBox

TcxDBShellComboBox = class(TcxCustomShellComboBox)

Description

The TcxDBShellComboBox class represents the data-aware shell combo box control.  The shell combo box editors are capable of browsing the system Shell.  The required shell item can be located both by typing the path to an item within the edit region and by invoking the editor’s dropdown, representing the folders tree:

Various settings specific to shell combo box editors can be accessed via the Properties member.

The dataset field bound to the cxDBShellComboBox must contain string values.  These values represent the paths to the shell items.


TcxDBShellComboBox Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomPopupEdit

     |

TcxCustomShellComboBox

     |


Properties for TcxDBShellComboBox
TcxDBShellComboBox Properties

TcxDBShellComboBox          Legend

In TcxDBShellComboBox

DataBinding

Derived from TcxCustomShellComboBox

AbsolutePath

AbsolutePIDL

ActiveProperties

PopupShellTreeView

Properties

RelativePIDL

ShellListView

ShellTreeView

Derived from TcxCustomPopupEdit

ActiveProperties

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName

Derived from TControl

Align


Methods for TcxDBShellComboBox
TcxDBShellComboBox Methods

TcxDBShellComboBox          Legend

Derived from TcxCustomPopupEdit

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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxDBShellComboBox
TcxDBShellComboBox Events

TcxDBShellComboBox          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxDBShellComboBox.DataBinding

TcxDBShellComboBox

Specifies a data source connection.

property DataBinding: TcxDBTextEditDataBinding;

Description

Use the DataBinding property to access a TcxDBTextEditDataBinding instance used to establish a connection to a data source.  The DataBinding.DataSource property identifies a dataset to which to connect.  The DataBinding.DataField property specifies the data source field whose value is to be edited by the shell combo box.


cxDBTrackBar Unit Overview
cxDBTrackBar Unit

Classes

TcxDBTrackBar


TcxDBTrackBar
 TcxDBTrackBar Object

Hierarchy          Properties          Methods          Events          See Also

Represents the data-aware version of the TcxTrackBar.

Unit

cxDBTrackBar

TcxDBTrackBar = class(TcxCustomTrackBar)

Description

The TcxDBTrackBar is a data-aware version of the track bar control.  Almost every aspect of the control’s visualization can be controlled through the Properties of the control.

The main features of the advanced progress bar are listed below:

•	Vertical orientation support (see the Properties.Orientation and Properties.TextOrientation properties description for details);

•	Track bar thumb managing (see the Properties.AutoSize, Properties.ThumbColor, Properties.ThumbHeight, Properties.ThumbHighlightColor, Properties.ThumbWidth properties description for details);

•	Track bar ticks managing (see the Properties.TickColor, Properties.TickMarks, Properties.TickSize, Properties.TickType properties description for details).

The data-aware functionality of the TcxDBTrackBar is encapsulated in the DataBinding property.   It allows you to specify DataSource and DataField to which the editor is bound.

This database field must contain integer values.  These field values are interpreted as the position of the track bar thumb and they must not exceed the limits specified by the Properties.Max and Properties.Min properties.


TcxDBTrackBar Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTrackBar

     |


Properties for TcxDBTrackBar
TcxDBTrackBar Properties

TcxDBTrackBar          Legend

In TcxDBTrackBar

DataBinding

Derived from TcxCustomTrackBar

ActiveProperties

Position

Properties

Derived from TcxCustomEdit

ActiveProperties

AutoSize

DataBinding

EditModified

EditValue

InnerEdit

ModifiedAfterEnter

Properties

RepositoryItem

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TControl

Align


Methods for TcxDBTrackBar
TcxDBTrackBar Methods

TcxDBTrackBar          Legend

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxDBTrackBar
TcxDBTrackBar Events

TcxDBTrackBar          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxDBTrackBar.DataBinding

TcxDBTrackBar

Specifies a data source connection.

property DataBinding: TcxDBEditDataBinding;

Description

Use the DataBinding property to access a TcxDBEditDataBinding instance used to establish a connection to a data source.  The DataBinding.DataSource property identifies a dataset to which to connect.  The DataBinding.DataField property specifies the data source field whose value is to be edited by the track bar control.


TcxEditDataBinding
  TcxEditDataBinding Object

Hierarchy           Properties           Methods          See Also

Represents a connection of an editor to a data storage.

Unit

cxEdit

TcxEditDataBinding = class(TPersistent);

Description

The TcxEditDataBinding class binds the TcxCustomEdit editor to the appropriate data storage.  Editors can use the DataBinding property to read from or write to a dataset.  Data-aware editors work with datasets while simple (non data-aware) editors do not.  To write or read a value from a data storage write or read the value from the StoredValue property.

Note: You can create your own data-binding class which will supply data from a custom data storage.  The new class must be derived from TcxEditDataBinding.  To make an editor use a new data-binding object you have to override the GetDataBindingClass function declared in TcxCustomEdit.


TcxEditDataBinding Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxEditDataBinding
TcxEditDataBinding Properties

TcxEditDataBinding          Legend

In TcxEditDataBinding

 StoredValue


Methods for TcxEditDataBinding
TcxEditDataBinding Methods

TcxEditDataBinding          Legend

In TcxEditDataBinding

 SetEditMode


TcxEditDataBinding.StoredValue

TcxEditDataBinding           See Also

Specifies a specific field value for an edit control.

type

  TcxEditValue = Variant;

property StoredValue: TcxEditValue;

Description

The StoredValue property allows accessing a value in the data storage that corresponds to the edit control.  Use this property to read or write a value to the data storage.  Before the value can be written to the data storage, the edit mode must be set by the SetEditMode method.


TcxEditDataBinding.SetEditMode

TcxEditDataBinding           See Also

Sets the edit mode for a data storage.

function SetEditMode: Boolean; virtual;

Description

The SetEditMode method sets your data storage to the edit mode.  In this mode a value can be written to the data storage by assigning it to the StoredValue property.  If the SetEditMode function fails to set the edit mode, it returns False, otherwise, it returns True.


TcxCustomEditProperties
TcxCustomEditProperties Object

Hierarchy          Properties          Methods          Events         See also

Stores attributes specific to an editor.

Unit

cxEdit

TcxCustomEditProperties = class(TcxInterfacedPersistent);

Description

The TcxCustomEditProperties class represents a set of attributes that control the editor’s behavior.  The edit control’s properties are set via the Properties member of the corresponding editor.

The TcxCustomEditProperties class implements validations of the display value in a number of cases.  The ValidateDisplayValue method validates the text before converting the display value into an edit value.  This occurs when moving focus to another control or pressing the Enter key in the editor (the ValidateOnEnter property should be set to True).  The ValidateDisplayValue method generates the OnValidate event.

The IsDisplayValueValid method verifies text when programmatically assigning a value to the editor’s Text property, when pasting text from the clipboard, or cutting it to the clipboard.

Data-aware editors have default values for some properties (i.e. Alignment and ReadOnly) which are retrieved from the related TField object properties.  You can redefine them by setting other values or by restoring the default values by using the RestoreDefaults method.

To implement a set of attributes for custom editors, create a TcxCustomEditProperties descendant, and override its GetButtonsClass, GetContainerClass, GetStyleClass, and GetViewInfoClass functions to provide data specific to the editor type.  To associate the derived class with a custom editor, override the editor’s GetPropertiesClass function to return this class type.


TcxCustomEditProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |


Properties for TcxCustomEditProperties
TcxCustomEditProperties Properties

TcxCustomEditProperties          Legend

In TcxCustomEditProperties

Alignment

AssignedValues

AutoSelect

BeepOnError

Buttons

ButtonsViewStyle

ClearKey

ClickKey

ImmediatePost

ReadOnly

UseLeftAlignmentOnEditing

UseMouseWheel

ValidateOnEnter


Methods for TcxCustomEditProperties
TcxCustomEditProperties Methods

TcxCustomEditProperties          Legend

In TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue


Events for TcxCustomEditProperties
TcxCustomEditProperties Events

TcxCustomEditProperties          Legend

In TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomEditProperties.Alignment

TcxCustomEditProperties           See Also

Determines the alignment of the editor’s contents.

property Alignment: TcxEditAlignment;

Description

Use the Alignment property to align data within the editor horizontally and vertically.

Data-aware editors have the default horizontal alignment.  When the editor represents data from TDataSet, the default alignment is defined by the TField.Alignment property.  You can redefine the alignment for data-aware controls by setting it via the Alignment property.  To restore the default alignment, use the RestoreDefaults method.


TcxCustomEditProperties.AssignedValues

TcxCustomEditProperties

Contains the property flags that indicate which properties specific to an editor have been changed.

property AssignedValues: TcxCustomEditPropertiesValues;

Description

Use the AssignedValues property to track the changes made to an editor’s ReadOnly property and undo them.  Once the property being tracked is set to a value other than the default one, the changes are reflected in the AssignedValues property (its corresponding property flag is set to True).  To undo the changes made and reverse the property back to its default value, set the corresponding property flag to False or call the AssignedValues.RestoreDefaults method to reverse all these properties back to their default values and reset all the property flags.  Use the AssignedValues.BeginUpdate and AssignedValues.EndUpdate methods to control when the editor repaints and avoid any flickering when the property flags are modified.


TcxCustomEditProperties.AutoSelect

TcxCustomEditProperties

Determines whether the editor’s contents are automatically selected when the editor receives focus.

property AutoSelect: Boolean;

Description

Setting the AutoSelect property to True selects the editor’s contents when it receives focus.

The default value of the AutoSelect property is True.


TcxCustomEditProperties.BeepOnError

TcxCustomEditProperties

Specifies whether to play the system default sound on a validation error.

property BeepOnError: Boolean;

Description

Set the BeepOnError property to True to play the system default sound when validation of the editor text fails.  If BeepOnError is False no sound is played when a validation error occurs.

The default value of the BeepOnError property is False.


TcxCustomEditProperties.Buttons

TcxCustomEditProperties           See Also

Supports a collection of buttons displayed within the editor.

property Buttons: TcxEditButtons;

Description

Use the Buttons property to add and delete a button within the collection.  You can make a button invisible by setting its Visible property to False.

When a user clicks a button with the mouse the OnButtonClick event is generated.


TcxCustomEditProperties.ButtonsViewStyle

TcxCustomEditProperties           See Also

Specifies the view style for the editor text and buttons displayed within the editor.

type

  TcxEditButtonsViewStyle = (bvsNormal, bvsButtonsOnly, bvsButtonsAutoWidth);

property ButtonsViewStyle: TcxEditButtonsViewStyle;

Description

Use the ButtonsViewStyle property to designate the view style, the manner the editor text and buttons (if any) are displayed within the editor.  Refer to the TcxEditButtonsViewStyle type description for the list of available view styles.

The default value of the ButtonsViewStyle property is vsNormal.


TcxCustomEditProperties.ClearKey

TcxCustomEditProperties          See Also

Specifies the shortcut to clear an editor’s edit value.

property ClearKey: TShortCut;

Description

The ClearKey property represents a shortcut to set the editor’s EditValue property to NIL.  By default, ClearKey is not assigned.  You can specify ClearKey to enable the end-user to clear the edit value.

The ClearKey property is published only by lookup editors (TcxLookupComboBoxProperties and TcxExtLookupComboBoxProperties).

The following code creates a repository item of the TcxEditRepositoryExtLookupComboBoxItem class (a repository item containing properties for the ExtLookupEditor) and sets its ClearKey property to the ‘Alt+C’ key combination.  The repository item is created with the help of the existing TcxEditRepository component (cxEditRepository1).  See the repository and repository items section for more information.

//Delphi

var

  ARepositoryItem: TcxEditRepositoryLookupComboBoxItem;

//...

ARepositoryItem :=
  TcxEditRepositoryLookupComboBoxItem(cxEditRepository1.CreateItem(
  TcxEditRepositoryLookupComboBoxItem));

with ARepositoryItem.Properties do

begin

  //...

  ClearKey := TextToShortCut('Alt+C');

end;

//Assign the repository item to an existing LookupComboBox editor

cxLookupComboBox1.RepositoryItem := ARepositoryItem;

//...

//Delete the repository item when you finish working with it

ARepositoryItem.Free;

//C++ Builder

TcxEditRepositoryLookupComboBoxItem * ARepositoryItem;

//...

ARepositoryItem =
  (TcxEditRepositoryLookupComboBoxItem*)cxEditRepository1
  ->CreateItem(__classid(TcxEditRepositoryLookupComboBoxItem));

TcxLookupComboBoxProperties * AProperties =
  ARepositoryItem->Properties;

//...

AProperties->ClearKey = TextToShortCut("Alt+C");

//Assign the repository item to an existing LookupComboBox editor

cxLookupComboBox1->RepositoryItem = ARepositoryItem;

//...

//Delete the repository item when you finish working with it

delete cxLookupComboBox1->RepositoryItem;

The default value of the ClearKey property is 0.


TcxCustomEditProperties.ClickKey

TcxCustomEditProperties           See also

Specifies a key combination to generate the OnButtonClick click event for the default button.

property ClickKey: TShortCut;

Description

The OnButtonClick event is generated when a user clicks any button within an editor supported by the Buttons collection.  Every button has the TcxEditButton.Default property.  Setting it to True indicates that this button is the default.  Only one button can have the Default property set to True at a time.  When you press the key combination assigned to the ClickKey property the editor generates the OnButtonClick event for the default button.

The default value of the ClickKey property is Ctrl + Enter.


TcxCustomEditProperties.ImmediatePost

TcxCustomEditProperties

Indicates whether the edit value should be saved immediately after it has been modified.

property ImmediatePost: Boolean;

Description

The ImmediatePost property is in effect for data-aware editors that allow you to modify their values immediately.  For instance, this property can be used for a check editor, a combo box, etc.  If the property value is set to True, the editor automatically saves the edited value to the bound field’s Value property as soon as the value has been changed.  Otherwise, the edited value will be saved when the editor looses focus or in response to pressing the Enter key.

The ImmediatePost property is useful if there are a number of controls displaying data from the editor’s bound field.  If this property value is True, all bound controls will refresh themselves as soon as the editor’s value has been changed.

Note: you can save the edited value manually by calling the editor’s PostEditValue method.

The default value of the ImmediatePost property is False.


TcxCustomEditProperties.ReadOnly

TcxCustomEditProperties           See Also

Specifies the desired read-only status of an editor.

property ReadOnly: Boolean;

Description

For non data-aware editors, the ReadOnly property specifies the read-only status of an editor.  Setting it to True prevents a user from making data modifications.  The default value of the ReadOnly property for non data-aware editors is False.

There is one difference for data-aware editors.  If an editor is linked to a read-only field in a dataset, you still cannot edit the value even if the ReadOnly is set to False.  The default value of the ReadOnly property for data-aware editors is determined by the TField.CanModify attribute value.

Use the RestoreDefaults method to restore the default values of the ReadOnly property and other properties which are retrieved from the related TField object attributes.


TcxCustomEditProperties.UseLeftAlignmentOnEditing

TcxCustomEditProperties

Specifies whether to align text to the left in edit mode.

property UseLeftAlignmentOnEditing: Boolean;

Description

If the UseLeftAlignmentOnEditing property is set to True, the text is aligned to the left when editing regardless of the Alignment property value.  Otherwise, the Alignment property value determines the text placement both in edit and display modes.


TcxCustomEditProperties.UseMouseWheel

TcxCustomEditProperties

Specifies whether an in-place editor should respond to mouse wheel movements.

property UseMouseWheel: Boolean;

Description

Like standard editors which accept mouse wheel movements by default, in-place editors can also do the same if the UseMouseWheel property is set to True or alternatively, the Ctrl key is being held down.  Otherwise, they are ignored.

The default value of the UseMouseWheel property is True.


TcxCustomEditProperties.ValidateOnEnter

TcxCustomEditProperties           See Also

Specifies whether to call validation procedure when a user presses the Enter key.

property ValidateOnEnter: Boolean;

Description

Set the ValidateOnEnter property to True to invoke the validation procedure when a user presses the Enter key.  If the text is validated by this procedure, it is stored as the edit value.  The text validation is performed by the TcxCustomEdit.ValidateEdit method and this makes a call to the ValidateDisplayValue routine that generates the OnValidate event.

To handle validation errors the editor must support validation, i.e. the CanValidate function returns True.  Otherwise, it returns False.

The default value of the ValidateOnEnter property is False.


TcxCustomEditProperties.BeginUpdate

TcxCustomEditProperties           See Also

Prevents an editor from being repainted until the EndUpdate method is called.

procedure BeginUpdate;

Description

Enclose the statements that modify the properties of the TcxCustomEditProperties object with calls to the BeginUpdate and EndUpdate methods.  This gives a performance benefit and avoids any flickering when the property flags are modified.

Note:	Calls to BeginUpdate are cumulative; for every call to BeginUpdate there must be a corresponding call to EndUpdate.  The editor is repainted only after the same number of calls have been made to EndUpdate as BeginUpdate.  The editor receives notifications about property changes by subscribing to the protected OnPropertiesChanged event.


TcxCustomEditProperties.CanModify

TcxCustomEditProperties           See Also

Specifies whether the edit value can be modified.

function CanModify: Boolean;

Description

If the ReadOnly property is set to True, the CanModify method always returns False.

If ReadOnly is False, the return value depends on the editor type.  For non data-aware editors, CanModify returns True.  For data-aware editors the return value is defined by the read-only status of the linked field.


TcxCustomEditProperties.CanValidate

TcxCustomEditProperties           See Also

Identifies whether the editor supports validation.

function CanValidate: Boolean; virtual;

Description

When a user enters text and wants to store it as the edit value (the TcxCustomEdit.EditValue property), in some cases it is necessary to check whether it can be converted.  If the text cannot be converted to the edit value then an error occurs and the edit value is not changed.  This procedure is called validation.  To handle such situations the editor must support validation.  If the editor implements validation operations, the CanValidate function returns True.  Otherwise, it returns False.

Validation is performed by the TcxCustomEdit.ValidateEdit method.


TcxCustomEditProperties.EndUpdate

TcxCustomEditProperties           See Also

Enables repainting of an editor.

procedure EndUpdate;

Description

Enclose the statements that modify the properties of the TcxCustomEditProperties object with calls to the BeginUpdate and EndUpdate methods.  This improves performance and avoids any flickering when the property flags are modified.

Note:	Calls to BeginUpdate are cumulative; for every call to BeginUpdate there must be a corresponding call to EndUpdate.  The editor is repainted only after the same number of calls have been made to EndUpdate as BeginUpdate.  The editor receives notifications about property changes by subscribing to the protected OnPropertiesChanged event.


TcxCustomEditProperties.GetButtonsClass

TcxCustomEditProperties

Determines the type of the button collection accessible via the Buttons property.

type

  TcxEditButtonsClass = class of TcxEditButtons;

class function GetButtonClass: TcxEditButtonsClass; virtual;

Description

By default, this function returns TcxEditButtons.  Override this function to display custom buttons (for example, TcxEditButton descendants).


TcxCustomEditProperties.GetContainerClass

TcxCustomEditProperties

Determines the editor container type for the current TcxCustomEditProperties object.

type

  TcxContainerClass = class of TcxContainer;

class function GetContainerClass: TcxContainerClass; virtual;

Description

By default, this function returns TcxCustomEdit.  Override this function to return the desired class type when implementing custom editors.


TcxCustomEditProperties.GetStyleClass

TcxCustomEditProperties

Determines the style type that corresponds to the current TcxCustomEditProperties object.

type

  TcxCustomEditStyleClass = class of TcxCustomEditStyle;

class function GetStyleClass: TcxCustomEditStyleClass; virtual;

Description

By default, this function returns TcxEditStyle.  Override this function to return the desired class type when implementing styles for custom editors.


TcxCustomEditProperties.GetViewInfoClass

TcxCustomEditProperties           See Also

Determines the ViewInfo type that corresponds to the current TcxCustomEditProperties object.

type

  TcxContainerViewInfoClass = class of TcxContainerViewInfo;

class function GetViewInfoClass: TcxContainerViewInfoClass; virtual;

Description

By default, this function returns TcxCustomEditViewInfo.  Override this function to return the desired class type when implementing custom editors.


TcxCustomEditProperties.IsEditValueValid

TcxCustomEditProperties           See Also

Ascertains whether the specified edit value is valid.

type

  TcxEditValue = Variant;

function IsEditValueValid(var EditValue: TcxEditValue): Boolean; virtual;

Description

The IsEditValueValid function returns True if the specified edit value is valid for this editor instance.  Otherwise, it returns False.


TcxCustomEditProperties.RestoreDefaults

TcxCustomEditProperties           See also

Restores a set of properties, which are dependent on field settings for data-aware editors, to their default values.

procedure RestoreDefaults; virtual;

Description

Some editor properties can have default values.  Non data-aware editors specify default values for such properties themselves.  Data-aware editors retrieve default values for these properties from the associated field in the dataset.  These are properties such as Alignment and ReadOnly.  Descendants of TcxCustomEditProperties may introduce another properties whose values are determined by a dataset.  A user can override default values by assigning specific values explicitly.

For instance, data-aware editors have default values for the Alignment and ReadOnly properties.  Default values are determined by TField.Alignment and TField.CanModify respectively.

The RestoreDefaults method restores the default property values after they have been assigned.


TcxCustomEditProperties.ValidateDisplayValue

TcxCustomEditProperties           See Also

Validates the specified display value.

type

  TcxEditValue = Variant;

procedure ValidateDisplayValue(var DisplayValue: TcxEditValue; var ErrorText: TCaption; var Error: Boolean; AEdit: TcxCustomEdit); virtual;

Description

The ValidateDisplayValue method is called before converting the changed display value to the edit value in the following cases:

1) when moving focus to another control;

2) when pressing the Enter key, if the ValidateOnEnter property is set to True.

The method validates the specified DisplayValue parameter.  If the display value cannot be converted to the edit value, the ValidateDisplayValue method sets the Error parameter to True and assigns the ErrorText parameter as an error description.

If an editor specified by the AEdit parameter has the OnValidate event handler assigned, the ValidateDisplayValue method fires this event which allows a user to customize the result of the validation.  In this case the ValidateDisplayValue method passes the DisplayValue, ErrorText and Error parameters as the parameters to the OnValidate event.

If the Error flag is set to True as a result of the ValidateDisplayValue method and the OnValidate event, the display value is not converted to the edit value, the system sound is played (the BeepOnError property is set to True) and an exception is raised.


TcxCustomEditProperties.OnButtonClick

TcxCustomEditProperties           See also

Occurs when a user clicks a button within an editor.

type

  TcxEditButtonClickEvent = procedure(Sender: TObject; AButtonIndex: Integer) of object;

property OnButtonClick: TcxEditButtonClickEvent;

Description

Use the OnButtonClick event to perform specific actions when a user clicks a button within the editor.  The Sender parameter identifies the editor which contains the button.  The AButtonIndex parameter represents the index of the button within the button collection provided by the Buttons property.


TcxCustomEditProperties.OnChange

TcxCustomEditProperties           See Also

Occurs on changing the value within an editor.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnChange: TNotifyEvent;

Description

For text editors, the OnChange event occurs when changing the display value provided by the TcxCustomEdit.Text property and is fired by the TcxCustomEdit.DoOnChange virtual method.  Image editors generate this event when changing the image.  For check box controls, the event is generated when the state is changed.


TcxCustomEditProperties.OnEditValueChanged

TcxCustomEditProperties

Occurs after assigning a new value to the TcxCustomEdit.EditValue property.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnEditValueChanged: TNotifyEvent;

Description

The OnEditValueChanged event occurs after assigning a new value to the TcxCustomEdit.EditValue property and is fired by the TcxCustomEdit.DoOnEditValueChanged virtual method.  The Sender parameter identifies the editor (the TcxCustomEdit descendant) whose value has been changed.


TcxCustomEditProperties.OnPropertiesChanged

TcxCustomEditProperties

Occurs when any properties are changed.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnPropertiesChanged: TNotifyEvent;

Description

The OnPropertiesChanged event occurs when any properties are changed.  The TcxCustomEdit editor subscribes to this event to get notifications when the editor should be refreshed.


TcxCustomEditProperties.OnValidate

TcxCustomEditProperties           See Also

Occurs before converting the display value to the edit value.

type

  TcxEditValue = Variant;

  TcxEditValidateEvent = procedure(Sender: TObject; var DisplayValue: TcxEditValue; var ErrorText: TCaption; var Error: Boolean) of object;

property OnValidate: TcxEditValidateEvent;

Description

Use the OnValidate event to validate the specified display value before converting it to the edit value.  The OnValidate event is generated by the ValidateDisplayValue procedure if the editor supports validation (the CanValidate method must return True).  The ValidateDisplayValue method performs the primary validation.  If validation of the DisplayValue parameter value fails, this method sets the Error parameter to True and assigns the ErrorText parameter error description.  In an OnValidate event handler, you can redefine the validation results.

The event is generated:

1) when moving focus to another control;

2) when pressing the Enter key if the ValidateOnEnter property is set to True.


TcxEditSizeProperties

Describes the properties relevant to the editor size.

Unit

cxEdit

type

  TcxEditSizeProperties = record

    MaxLineCount: Integer;

    Width: Integer;

  end;

Description

The TcxEditSizeProperties type describes properties relevant to the editor size which such as:

Field	Meaning
MaxLineCount	Specifies the maximum number or lines in a multiline edit control.  If MaxLineCount is 0, the number of lines is not limited.
Width	Defines the width of an editor in pixels.  If Width is 0, the editor width is not limited.  If Width is –1, the default value specific to an editor will be used.


TcxCustomEditPropertiesValues
TcxCustomEditPropertiesValues Object

Hierarchy          Properties          Methods

Contains the property flags that indicate which editor-specific properties have been changed.

Unit

cxEdit

TcxCustomEditPropertiesValues = class(TPersistent);

Description

The TcxCustomEditPropertiesValues class represents the base class for all classes that track changes made to the editor-specific properties.  This class only tracks the changes made to the read-only state of an editor.  Once an editor’s ReadOnly property is set to a value other than the default one, the changes are reflected in the TcxCustomEditPropertiesValues class (its corresponding property flag is set to True).  To reset the changes made and reverse the ReadOnly property back to its default value, call the RestoreDefaults method or set the corresponding property flag to False.  The TcxCustomEditPropertiesValues class also provides the BeginUpdate and EndUpdate methods which are used to control when the editor repaints and avoid any flickering when the property flags are modified.


TcxCustomEditPropertiesValues Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxCustomEditPropertiesValues
TcxCustomEditPropertiesValues Properties

TcxCustomEditPropertiesValues          Legend

In TcxCustomEditPropertiesValues

ReadOnly


Methods for TcxCustomEditPropertiesValues
TcxCustomEditPropertiesValues Methods

TcxCustomEditPropertiesValues          Legend

In TcxCustomEditPropertiesValues

BeginUpdate

EndUpdate

RestoreDefaults


TcxCustomEditPropertiesValues.ReadOnly

TcxCustomEditPropertiesValues          See Also

Specifies whether an editor’s read-only state has been modified.

property ReadOnly: Boolean;

Description

Once an editor’s ReadOnly property is set to a value other than the default one, the ReadOnly property flag is set to True.  Otherwise, it’s set to False.  To undo the changes made to the editor’s ReadOnly property and reverse it back to its default value, call the RestoreDefaults method which resets all the property flags or set the ReadOnly property flag to False.


TcxCustomEditPropertiesValues.BeginUpdate

TcxCustomEditPropertiesValues          See Also

Prevents an editor from being repainted until the EndUpdate method is called.

procedure BeginUpdate;

Description

Enclose the statements that modify the properties of the TcxCustomEditPropertiesValues object with calls to the BeginUpdate and EndUpdate methods.  This gives a performance benefit and avoids any flickering when the property flags are modified.

Note:	Calls to BeginUpdate are cumulative; for every call to BeginUpdate there must be a corresponding call to EndUpdate.  The editor is repainted only after the same number of calls have been made to EndUpdate as BeginUpdate.  The editor receives notifications about property changes by subscribing to the protected OnPropertiesChanged event.


TcxCustomEditPropertiesValues.EndUpdate

TcxCustomEditPropertiesValues          See Also

Enables editor repainting.

procedure EndUpdate;

Description

Enclose the statements that modify the properties of the TcxCustomEditPropertiesValues object with calls to the BeginUpdate and EndUpdate methods.  This gives a performance benefit and avoids any flickering when the property flags are modified.

Note:	Calls to BeginUpdate are cumulative; for every call to BeginUpdate there must be a corresponding call to EndUpdate.  The editor is repainted only after the same number of calls have been made to EndUpdate as BeginUpdate.  The editor receives notifications about property changes by subscribing to the protected OnPropertiesChanged event.


TcxCustomEditPropertiesValues.RestoreDefaults

TcxCustomEditPropertiesValues

Reverses the values of the properties (changes to which are being tracked) back to their default values.

procedure RestoreDefaults; virtual;

Description

The RestoreDefaults method undoes any changes made to the properties and resets their values back to the default ones.  Calling this method sets the editor’s ReadOnly property to the default value and resets the corresponding ReadOnly property flag to False.  Setting the property flag of each property being tracked to False has the same result as calling the RestoreDefaults method.


TcxCustomEditViewInfo Object

Hierarchy

Stores all the information necessary for drawing an editor.

Unit

cxEdit

TcxCustomEditViewInfo = class(TcxContainerViewInfo);

Description

The TcxCustomEditViewInfo class stores data necessary for drawing an editor.  It describes the state of editor items.  The EditState property specifies whether the editor is active, disabled or highlighted.  The ButtonsInfo member provides information related to editor button drawing.  TcxCustomEditViewInfo contains many properties describing various style attributes which define the background color, border color, border style, popup border style, shadow and transparency states.

The Paint method calls the DrawCustomEdit procedure, which invokes a sequence of drawing operations.


Hierarchy

TcxContainerViewInfo

      |


TcxEditButton
TcxEditButton Object

Hierarchy          Properties         See also

Represents a button displayed within an editor.

Unit

cxEdit

TcxEditButton = class(TCollectionItem);

Description

The TcxEditButton class represents a single button within the button collection supported by the TcxCustomEditProperties.Buttons property.  The TcxCustomEditProperties class provides an OnButtonClick event which occurs when a user clicks a button.  This event is also generated for the default button (the Default property is set to True) when a user presses the key combination provided by the TcxCustomEditProperties.ClickKey property.


TcxEditButton Hierarchy
Hierarchy

TCollectionItem

     |


Properties for TcxEditButton
TcxEditButton Properties

TcxEditButton          Legend

In TcxEditButton

Caption

ContentAlignment

Default

Enabled

Glyph

Kind

LeftAlignment

Stretchable

Tag

Visible

Width


TcxEditButton.Caption

TcxEditButton

Specifies the custom text displayed on a button’s surface.

property Caption: TCaption;

Description

Use the Caption property to specify the text displayed on a button’s surface.  To display the text you must set the Kind property to bkText.  If the button's width is insufficient to display the entire text, then text clipping occurs.  The clipped portion of the text is replaced with an ellipsis.

Use the ContentAlignment property to align the text within the button.


TcxEditButton.ContentAlignment

TcxEditButton

Specifies a button’s text alignment.

type

  TAlignment = (taLeftJustify, taRightJustify, taCenter);

property ContentAlignment: TAlignment;

Description

Use this property to align the text specified by the Caption property within the button.  The ContentAlignment property is in effect when the button’s Kind property is set to bkText.

The default value of the ContentAlignment property is taCenter.


TcxEditButton.Default

TcxEditButton           See Also

Specifies whether a button is the default one.

property Default: Boolean;

Description

Use Default to assign a button the default status.  Only one button in the TcxEditButtons collection can have the Default property set to True.  If you set the Default property to True for one button, the Default attribute of other buttons in the collection is automatically set to False.

For the default button, the TcxCustomEditProperties.OnButtonClick event is generated both by clicking it and by pressing the key combination assigned to the TcxCustomEditProperties.ClickKey property.

The default value of the Default property is False.


TcxEditButton.Enabled

TcxEditButton

Specifies whether a button can be clicked.

property Enabled: Boolean;

Description

Use the Enabled property to determine whether a button can be clicked.  If you set the Enabled property to False, the button is disabled.  When a button is disabled, it is not highlighted and cannot be clicked in order to perform an action.

The default value of the Enabled property is True.


TcxEditButton.Glyph

TcxEditButton           See also

Specifies the custom image displayed on a button’s surface.

property Glyph: TBitmap;

Description

Use the Glyph property to specify the image displayed on a button’s surface.  To display an image you must set the Kind property to bkGlyph.


TcxEditButton.Kind

TcxEditButton           See Also

Specifies button type.

type

  TcxEditButtonKind = (bkEllipsis, bkDown, bkGlyph, bkText);

property Kind: TcxEditButtonKind;

Description

Use the Kind property to identify button type.  It defines the image displayed on a button’s surface.  You can display your custom image on a button by assigning bkGlyph to Kind and setting the image via the Glyph property.

The default value of the Kind property is bkDown.


TcxEditButton.LeftAlignment

TcxEditButton

Specifies button alignment.

property LeftAlignment: Boolean;

Description

The LeftAlignment property defines whether a button is aligned to the left.  By default, buttons appear at the right editor edge.  Set LeftAlignment to True to display your button at the left edge.

The default value of the LeftAlignment property is False.


TcxEditButton.Stretchable

TcxEditButton           See Also

Specifies whether a button’s width is adjusted if the editor’s width is changed.

property Stretchable: Boolean;

Description

When the Stretchable property is set to True and the editor control’s width is about to change, the button’s width is adjusted in such a manner as to preserve the ratio of its width with the new editor’s width.  If you set the Stretchable property to False, the button’s width is not modified in this way.

Note:	This property is effective for editor controls which display buttons only, i.e. have their Properties.ViewStyle set to vsButtonsOnly or vsButtonsAutoWidth.

The default value of the Stretchable property is True.


TcxEditButton.Tag

TcxEditButton

Stores a value associated with the button.

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 buttons or when you need to have an additional button identification mechanism.


TcxEditButton.Visible

TcxEditButton

Determines whether a button is visible.

property Visible: Boolean;

Description

Use the Visible property to manage button visibility.  Set this property to False to hide a button.

The default value of the Visible property is True.


TcxEditButton.Width

TcxEditButton

Specifies a button’s width.

property Width: Integer;

Description

Use the Width property to adjust a button’s width.  If Width is set to 0, an image is displayed with the default width.

The default value of the Width property is 0.


TcxEditButtons
TcxEditButtons Object

Hierarchy          Properties          Methods          See also

Represents a collection of buttons provided by an editor.

Unit

cxEdit

TcxEditButtons = class(TCollection);

Description

The TcxEditButtons class represents a collection of buttons for the TcxCustomEdit control.  Use the editor’s Properties.Buttons property to gain access to the buttons collection.

To add a button, call the Add function.  Use the Items property provides to access properties of a specific button by its index.  By default, every button is represented by a TcxEditButton object (as specified by the GetButtonClass function).  To display custom buttons within the editor, override this function to return the desired button type.

To provide a custom button collection (a TcxEditButtons descendant) for an editor, override the editor’s Properties.GetButtonsClass function to return this collection’s class type.


TcxEditButtons Hierarchy
Hierarchy

TCollection

     |


Properties for TcxEditButtons
TcxEditButtons Properties

TcxEditButtons          Legend

In TcxEditButtons

Items

VisibleCount


Methods for TcxEditButtons
TcxEditButtons Methods

TcxEditButtons          Legend

In TcxEditButtons

Add

GetButtonClass


TcxEditButtons.Items

TcxEditButtons

Provides access to individual buttons within the current collection.

property Items: TcxEditButton;

Description

Use the Items property to access an individual button by its index.  Every button is represented by a TcxEditButton instance. The total number of buttons is determined by the inherited Count property.


TcxEditButtons.VisibleCount

TcxEditButtons

Returns the number of visible buttons.

property VisibleCount: Integer;

Description

The VisibleCount property returns the number of buttons whose TcxEditButton.Visible property is set to True.

ReadOnly Property


TcxEditButtons.Add

TcxEditButtons          See Also

Adds a button to the current collection.

function Add: TcxEditButton;

Description

Call the Add function to add a new button to the current collection of buttons displayed within the editor.

Use the Buttons property of the editor’s Properties member to access the collection of buttons.


TcxEditButtons.GetButtonClass

TcxEditButtons          See Also

Determines the type of buttons contained within the current collection.

type

  TcxEditButtonClass = class of TcxEditButton;

class function GetButtonClass: TcxEditButtonClass; virtual;

Description

By default, this function returns TcxEditButton.  Override this function to return the desired class type when implementing custom buttons.


TcxEditStyleController
 TcxEditStyleController Object

Hierarchy          Properties          Events          See Also

Represents the style controller which defines the style properties common to several editors.

Unit

cxEdit

TcxEditStyleController = class(TcxStyleController);

Description

The TcxEditStyleController class describes the style attributes that can be applied to several editors.  Use the Style, StyleDisabled, StyleFocused, StyleHot members to specify style attributes for the normal, disabled, focused and highlighted (hot-tracked) editor state, respectively.  To set a style controller to an editor, you need to assign an instance of the TcxEditStyleController class to the TcxCustomEditStyle.StyleController property.

The style controller allows you to define the style attributes common to several editors.  But you can redefine individual style attributes by setting them explicitly via the editor’s TcxCustomEdit.Style, TcxCustomEdit.StyleDisabled, TcxCustomEdit.StyleFocused and TcxCustomEdit.StyleHot properties.   The editor and the style controller each have the AssignedValues property, which specify whether to obtain style attributes from the editor style or from the style controller.  It represents a set of flags that describe which style attributes were explicitly assigned in the editor style and the style controller, respectively.  Editor style attributes have a higher priority than attributes defined in the style controller.  If a specific style attribute is set both in the editor style and style controller, the editor will obtain the style attribute value from the editor style.

It is possible to connect one style controller to another style controller by setting the TcxEditStyleController.Style.StyleController property.  This gives you additional flexibility when controlling editor style attributes.  Attributes of the style controller have less priority than attributes of the controller to which it is connected.

Note:	a default style controller provides access to default style attributes’ values for all the editors and controls that have unassigned style attributes (set to their defaults) and have no style controller assigned, i.e. when a default style controller is present and an editor or a style controller has an unassigned style attribute and has no style controller connected to itself, the corresponding default style controller’s attribute can be set via the default style controller. Use the TcxDefaultEditStyleController component to customize the style attributes’ default values for all the controls that have no individual style control assigned.


TcxEditStyleController Hierarchy
Hierarchy

TComponent

     |

TcxStyleController

     |


Properties for TcxEditStyleController
TcxEditStyleController Properties

TcxEditStyleController          Legend

In TcxEditStyleController

 Style

 StyleDisabled

 StyleFocused

 StyleHot

Derived from TcxStyleController

 Styles


Events for TcxEditStyleController
TcxEditStyleController Events

TcxEditStyleController          Legend

In TcxEditStyleController

 OnStyleChanged


TcxEditStyleController.Style

TcxEditStyleController           See Also

Specifies the style attributes provided by the current style controller for editors in the normal state.

property Style: TcxEditStyle;

Description

Use the Style property to specify the normal state’s style attributes applied via the style controller to several editors.  To redefine individual style attributes you need to assign values to the corresponding properties via the TcxCustomEdit.Style property.


TcxEditStyleController.StyleDisabled

TcxEditStyleController           See Also

Specifies the style attributes provided by the current style controller for disabled editors.

property StyleDisabled: TcxEditStyleEx;

Description

Use the StyleDisabled property to specify the disabled state’s style attributes applied via the style controller to several editors.  To redefine individual style attributes you need to assign values to the corresponding properties via the TcxCustomEdit.StyleDisabled property.


TcxEditStyleController.StyleFocused

TcxEditStyleController           See Also

Specifies the style attributes provided by the current style controller for the focused editor.

property StyleFocused: TcxEditStyleEx;

Description

Use the StyleFocused property to specify the focused state’s style attributes applied via the style controller to several editors.  To redefine individual style attributes you need to assign values to the corresponding properties via the TcxCustomEdit.StyleFocused property.


TcxEditStyleController.StyleHot

TcxEditStyleController           See Also

Specifies the style attributes provided by the current style controller for the highlighted (hot-tracked) editor.

property StyleHot: TcxEditStyleEx;

Description

Use the StyleHot property to specify the highlighted state’s style attributes applied via the style controller to several editors.  To redefine individual style attributes you need to assign values to the corresponding properties via the TcxCustomEdit.StyleHot property.


TcxEditStyleController.OnStyleChanged

TcxEditStyleController           See Also

Occurs when the style attributes of the current TcxEditStyleController class have been changed.

type

  TcxStyleChangedEvent = procedure(Sender: TObject; AStyle: TcxContainerStyle) of object;

property OnStyleChanged: TcxStyleChangedEvent;

Description

The OnStyleChanged event occurs when any of the style attributes provided by the Style property has been changed.

The Sender parameter specifies the style controller.  The AStyle parameter represents the Style property value of this style controller.


cxEdit Unit Overview
cxEdit Unit

Classes

TcxCustomEdit

TcxCustomEditProperties

TcxCustomEditPropertiesValues

TcxCustomEditStyle

TcxCustomEditViewInfo

TcxDefaultEditStyleController

TcxEditAlignment

TcxEditButton

TcxEditButtons

TcxEditDataBinding

TcxEditRepository

TcxEditRepositoryItem

TcxEditStyle

TcxEditStyleController

TcxEditStyleEx

Other Types

TcxEditBorderStyle

TcxEditButtonKind

TcxEditButtonStyle

TcxEditButtonsViewStyle

TcxEditButtonTransparency

TcxEditCloseUpReason

TcxEditHorzAlignment

TcxEditPopupBorderStyle

TcxEditRepositoryItemClass

TcxEditSizeProperties

TcxEditStyleValue

TcxEditStyleValues

TcxEditValidateEvent

TcxEditValue

TcxEditVertAlignment


TcxEditAlignment
TcxEditAlignment Object

Hierarchy          Properties          See Also

Defines the horizontal and vertical alignments of an editor’s contents.

Unit

cxEdit

TcxEditAlignment = class(TPersistent);

Description

The TcxEditAlignment class represents the alignment of an editor’s contents, which is set via the TcxCustomEditProperties.Alignment property.  The Horz and Vert properties specify the horizontal and vertical alignments respectively.


TcxEditAlignment Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxEditAlignment
TcxEditAlignment Properties

TcxEditAlignment          Legend

In TcxEditAlignment

Horz

Vert


TcxEditAlignment.Horz

TcxEditAlignment           See Also

Identifies the horizontal alignment of an editor’s contents.

type

  TAlignment = (taLeftJustify, taRightJustify, taCenter);

  TcxEditHorzAlignment = TAlignment;

property Horz: TcxEditHorzAlignment;

Description

Use the Horz property to align an editor’s contents horizontally.  The TcxEditHorzAlignment type enumerates possible values.


TcxEditAlignment.Vert

TcxEditAlignment           See Also

Identifies the vertical alignment of an editor’s contents.

type

  TcxEditVertAlignment = (taTopJustify, taBottomJustify, taVCenter);

property Vert: TcxEditVertAlignment;

Description

Use the Vert property to align an editor’s contents vertically.  The TcxEditVertAlignment type enumerates possible values.


TcxEditBorderStyle
TcxEditBorderStyle type

Represents the border style of an edit control.

Unit

cxEdit

type

  TcxEditBorderStyle = (ebsNone, ebsSingle, ebsThick, ebsFlat, ebs3D, ebsUltraFlat, ebsOffice11);

Description

The TcxEditBorderStyle type enumerates border styles of an editor.  Use the TcxCustomEditStyle.BorderStyle property to set the border style.

Value	Meaning
ebsNone	Normally, no borders are drawn around the edit control.  However, when the mouse cursor is positioned over the editor or the editor has focus, editor borders are drawn flat. The following images demonstrate the TcxButtonEdit control with BorderStyle set to ebsNone and HotTrack set to True.
ebsSingle	The editor normally has thin borders.  When the mouse cursor is positioned over the editor or the editor has focus, the editor has thick borders. The following images demonstrate the TcxButtonEdit control with BorderStyle set to ebsSingle and HotTrack set to True.
ebsThick	Editor borders are always thick, i.e. the mouse position has no effect. The following image demonstrates the TcxButtonEdit control with BorderStyle set to ebsThick.
ebsFlat	Normally, editor borders are flat.  When the mouse cursor is positioned over the editor or the editor has focus, editor borders appear three-dimensional. The following images demonstrate the TcxButtonEdit control with BorderStyle set to ebsFlat and HotTrack set to True.
ebs3D	The editor appears three-dimensional and the mouse position has no effect. The following image demonstrates the TcxButtonEdit control with BorderStyle set to ebs3D.
ebsUltraFlat	Editor borders have an Office XP style.  Editor borders and buttons are highlighted when you move mouse cursor over the editor. The following images demonstrate the TcxButtonEdit control with BorderStyle set to ebsUltraFlat and HotTrack set to True.
ebsOffice11	Editor borders have an Office 2003 style.  Editor borders and buttons are highlighted when you move mouse cursor over the editor. The following images demonstrate the TcxButtonEdit control with BorderStyle set to ebsOffice11 and HotTrack set to True.


TcxEditButtonKind
TcxEditButtonKind type

Represents button type.

Unit

cxEdit

type

  TcxEditButtonKind = (bkEllipsis, bkDown, bkGlyph, bkText);

Description

The TcxEditButtonKind type enumerates the button types controlling the image displayed on a button’s surface.  Use the TcxEditButton.Kind property to specify the button type.

The images in the following table demonstrate the TcxButtonEdit control with the Kind property set to the corresponding value.  The first editor is drawn with the default style.  The second one is drawn with the Windows XP style enabled (the Style.LookAndFeel.NativeStyle property is set to True).

Value	Meaning
bkEllipsis	An Ellipsis symbol is drawn on a button's surface.
bkDown	A Down-arrow is drawn on a button's surface.
bkGlyph	A custom bitmap is drawn on a button's surface.  The bitmap is provided by the TcxEditButton.Glyph property.
bkText	A custom text is drawn on a button's surface.  The text is provided by the TcxEditButton.Caption property.  Use the TcxEditButton.ContentAlignment property to align the text within the button.


TcxEditButtonStyle
TcxEditButtonStyle type

Represents the button style of an edit control.

Unit

cxEdit

type

  TcxEditButtonStyle = (btsDefault, bts3D, btsFlat, btsSimple, btsHotFlat, btsUltraFlat, btsOffice11);

Description

The TcxEditButtonStyle type enumerates button styles set via the TcxCustomEditStyle.ButtonStyle property.

Value	Meaning
BtsDefault	The button style is determined by the border style of the editor which is set via the TcxCustomEditStyle.BorderStyle property.  Possible values for the border style are presented by the TcxEditBorderStyle enumerator.
bts3D	A button appears three-dimensional.  It is not highlighted when the mouse cursor is positioned over it. The following image demonstrates the TcxButtonEdit control with BorderStyle set to ebs3D and ButtonStyle set to bts3D.
btsFlat	A button appears flat with a slight three-dimensional effect.  It is not highlighted when the mouse cursor is positioned over it. The following image demonstrates the TcxButtonEdit control with BorderStyle set to ebs3D and ButtonStyle set to btsFlat.
btsSimple	A button normally appears without borders.  It is displayed with the btsFlat effect when the mouse cursor is positioned over it. The following images demonstrate the TcxButtonEdit control with BorderStyle set to ebs3D and ButtonStyle set to btsSimple.
BtsHotFlat	A button appears flat with a thin border.  It is highlighted when the mouse cursor is positioned over it. The following images demonstrate the TcxButtonEdit control with BorderStyle set to ebs3D and ButtonStyle set to btsHotFlat.
BtsUltraFlat	A button has an Office XP style.  It appears flat without borders and is highlighted when the mouse cursor is positioned over it. The following images demonstrate the TcxButtonEdit control with BorderStyle set to ebs3D and ButtonStyle set to btsUltraFlat.
btsOffice11	A button has an Office 2003 style.  It appears flat without borders and is highlighted when the mouse cursor is positioned over it. The following images demonstrate the TcxButtonEdit control with BorderStyle set to ebs3D and ButtonStyle set to btsOffice11.


TcxEditButtonTransparency

Represents the button transparency mode within an editor.

Unit

cxEdit

type

  TcxEditButtonTransparency = (ebtNone, ebtInactive, ebtAlways, ebtHideInactive, ebtHideUnselected);

Description

The TcxEditButtonTransparency type enumerates transparency modes of editor buttons.  The following table describes possible values:

Value	Meaning
ebtNone	A button is always displayed in a non-transparent fashion.
ebtInactive	A button is drawn when the editor has focus or when the mouse cursor is positioned over the button.  Otherwise, the button is transparent. The following images demonstrate the TcxButtonEdit control with BorderStyle set to ebs3D, ButtonStyle set to btsDefault and ButtonTransparency set to ebtInactive.
ebtAlways	A button is always transparent. The following image demonstrates the TcxButtonEdit control with BorderStyle set to ebs3D, ButtonStyle set to btsDefault and ButtonTransparency set to ebtAlways.
ebtHideInactive	A button is drawn only when the editor has focus.  Otherwise, the button is invisible. The following images demonstrate the TcxButtonEdit control with BorderStyle set to ebs3D, ButtonStyle set to btsDefault and ButtonTransparency set to ebtHideInactive.
ebtHideUnselected	A button is drawn when the editor has focus or when the mouse cursor is positioned over the editor region.  Otherwise, the button is invisible. The following images demonstrate the TcxButtonEdit control with BorderStyle set to ebs3D, ButtonStyle set to btsDefault and ButtonTransparency set to ebtHideUnselected.


TcxEditCloseUpReason
TcxEditCloseUpReason type

Represents the reason for the editor’s popup window closing.

Unit

cxEdit

type

  TcxEditCloseUpReason = (crUnknown, crTab, crClose, crCancel, crEnter);

Description

The TcxEditCloseUpReason type enumerates reasons for the editor’s popup window closing.

All the possible values are listed in the following table.

Value	Description
crTab	The popup window is closed when focus is moved from an editor by pressing the Tab key.
crClose	The popup window is closed by pressing the F4, Alt+↑ or Alt+↓ key.
crCancel	The popup window is closed and the selection within the popup window is discarded (for instance, by pressing the Esc key).
crEnter	The popup window is closed either by a press on the Enter key or by the item within the popup window being clicked.
crUnknown	None of the above reasons caused the popup window to close of (for instance, this kind of reason is used for internal purposes).


TcxEditHorzAlignment
TcxEditHorzAlignment type

Specifies the type of the horizontal alignment.

Unit

cxEdit

type

  TAlignment = (taLeftJustify, taRightJustify, taCenter);

  TcxEditHorzAlignment = TAlignment;

Description

The horizontal alignment of an editor’s contents is set via the Horz property of the TcxCustomEditProperties.Alignment object.  The TcxEditHorzAlignment type enumerates possible values of the horizontal alignment.

Value	Meaning
taLeftJustify	The editor value is left justified: all text lines begin at the left edge of the editor.
taCenter	The editor value is centered within the editor.
taRightJustify	The editor value is right justified: all text lines end at the right edge of the control.


TcxEditPopupBorderStyle
TcxEditPopupBorderStyle type

Enumerates the styles of popup window borders.

Unit

cxEdit

type

  TcxEditPopupBorderStyle = (epbsDefault, epbsSingle, epbsFrame3D, epbsFlat);

Description

The TcxEditPopupBorderStyle class enumerates the border styles of the popup window associated with an editor.  Use the TcxCustomEditStyle.PopupBorderStyle property to set the border style.

Value	Meaning
epbsDefault	Popup borders are drawn in the manner in which editor borders are currently painted.  That is determined by the TcxCustomEditStyle.BorderStyle and TcxCustomEditStyle.HotTrack properties of the editor with which the popup is associated.
epbsSingle	Popup borders are thin. The following image displays the popup window with PopupBorderStyle set to epbsSingle.
epbsFrame3D	Popup borders are three-dimensional. The following image displays the popup window with PopupBorderStyle set to epbsFrame3D.
epbsFlat	Popup-borders are flat with a slight three-dimensional effect. The following image displays the popup window with PopupBorderStyle set to epbsFlat.


TcxEditStyleValue
TcxEditStyleValue type

Enumerates flags describing which editor style attributes are assigned.

Unit

cxEdit

type

  TcxEditStyleValue = (svBorderColor, svBorderStyle, svButtonStyle, svButtonTransparency, svColor, svEdges, svFont, svHotTrack, svPopupBorderStyle, svShadow, svTransparentBorder);

Description

The TcxEditStyleValue type enumerates flags indicating which editor style attributes are assigned to the TcxCustomEditStyle object.  These flags are set via the TcxCustomEditStyle.AssignedValues property.

Value	Meaning
svBorderColor	Indicates that the TcxCustomEditStyle.BorderColor property is assigned a value.
svBorderStyle	Indicates that the TcxCustomEditStyle.BorderStyle property is assigned a value.
svButtonStyle	Indicates that the TcxCustomEditStyle.ButtonStyle property is assigned a value.
svButtonTransparency	Indicates that the TcxCustomEditStyle.ButtonTransparency property is assigned a value.
svColor	Indicates that the TcxCustomEditStyle.Color property is assigned a value.
svEdges	Indicates that the TcxCustomEditStyle.Edges property is assigned a value.
svFont	Indicates that the TcxCustomEditStyle.Font property is assigned a value.
svHotTrack	Indicates that the TcxCustomEditStyle.HotTrack property is assigned a value.
svPopupBorderStyle	Indicates that the TcxCustomEditStyle.PopupBorderStyle property is assigned a value.
svShadow	Indicates that the TcxCustomEditStyle.Shadow property is assigned a value.
svTransparentBorder	Indicates that the TcxCustomEditStyle.TransparentBorder property is assigned a value.


TcxEditButtonsViewStyle
TcxEditButtonsViewStyle type

Represents the view style of buttons in an edit control.

Unit

cxEdit

type

  TcxEditButtonsViewStyle = (bvsNormal, bvsButtonsOnly, bvsButtonsAutoWidth);

Description

The TcxEditButtonsViewStyle type enumerates button view styles which are set via the TcxCustomEditProperties.ButtonsViewStyle property.

Value	Meaning
bvsNormal	The edit control displays the editor text and buttons (if any).
bvsButtonsOnly	The edit control displays buttons only (if any).
bvsButtonsAutoWidth	The edit control displays buttons only (if any).  The width of the edit control is adjusted according to the buttons’ widths.

The width of a particular button is controlled by its Width and Stretchable properties.


TcxEditStyleValues
TcxEditStyleValues type

Represents the set of flags that indicate which editor style attributes are assigned.

Unit

cxEdit

type

  TcxEditStyleValue = (svBorderColor, svBorderStyle, svButtonStyle, svButtonTransparency, svColor, svEdges, svFont, svHotTrack, svPopupBorderStyle, svShadow, svTransparentBorder);

  TcxEditStyleValues = set of TcxEditStyleValue;

Description

Each editor provides a Style property, presenting editor style attributes.  The TcxCustomEditStyle.AssignedValues member of the TcxEditStyleValues type describes which style attributes are explicitly assigned to the TcxCustomEditStyle object.


TcxEditValidateEvent
TcxEditValidateEvent type

Represents the procedure which handles the OnValidate event.

Unit

cxEdit

type

  TcxEditValidateEvent = procedure(Sender: TObject; var DisplayValue: TcxEditValue; var ErrorText: TCaption; var Error: Boolean) of object;

Description

The OnValidate event is fired by the ValidateDisplayValue procedure if the editor supports validation (the CanValidate function must return True).  The ValidateDisplayValue performs primary validation.  If validation of the DisplayValue parameter value fails, the ValidateDisplayValue method sets the Error parameter to True and assigns ErrorText an error description.  You can redefine validation results in an OnValidate event handler.

The event is generated:

1) when moving focus to another control;

2) when pressing the Enter key if the ValidateOnEnter property is set to True.


TcxEditValue
TcxEditValue type

Represents the edit value type.

Unit

cxEdit

type

  TcxEditValue = Variant;

Description

The TcxEditValue type is used to store the edit value of the TcxCustomEdit editor.


TcxEditVertAlignment
TcxEditVertAlignment type

Enumerates types of vertical alignments for editor’s contents.

Unit

cxEdit

type

  TcxEditVertAlignment = (taTopJustify, taBottomJustify, taVCenter);

Description

The vertical alignment of editor’s contents is set via the Vert property of the TcxCustomEditProperties.Alignment object.  The TcxEditVertAlignment type enumerates possible values of the vertical alignment.

Value	Meaning
taTopJustify	The editor value is aligned to the top.
taBottomJustify	The editor value is aligned to the bottom.
taVCenter	The editor value is centered vertically.


cxEditRepositoryItems Unit Overview
cxEditRepositoryItems Unit

See Also

Classes

TcxEditRepositoryBlobItem

TcxEditRepositoryButtonItem

TcxEditRepositoryCalcItem

TcxEditRepositoryCheckBoxItem

TcxEditRepositoryComboBoxItem

TcxEditRepositoryCurrencyItem

TcxEditRepositoryDateItem

TcxEditRepositoryHyperLinkItem

TcxEditRepositoryImageComboBoxItem

TcxEditRepositoryImageItem

TcxEditRepositoryMaskItem

TcxEditRepositoryMemoItem

TcxEditRepositoryMRUItem

TcxEditRepositoryPopupItem

TcxEditRepositorySpinItem

TcxEditRepositoryTextItem

TcxEditRepositoryTimeItem


TcxEditRepository
 TcxEditRepository Object

Hierarchy          Properties          Methods          See Also

Represents a collection of repository items.

Unit

cxEdit

TcxEditRepository = class(TComponent);

Description

The repository represents a collection of repository items, each of which is a descendant of the TcxEditRepositoryItem class.  The ExpressEditorsLibrary provides a repository item for every editor it contains.  A repository item stores properties specific to a corresponding editor in the Properties object.

A repository item can be used to specify properties common to several editors.  See the RepositoryItem property to assign a repository item to the editor.  Properties of an editor assigned a repository item address the properties of the repository item.  Editor properties are preserved in this case and restored when clearing the RepositoryItem value.

Repository items are also used when assigning the column type in a grid control.  To make a grid control use the desired editor for a specific column, you should assign the corresponding repository item to the column.  When editing data in a grid, only one editor instance exists.  This editor is used to edit the current cell value.  For other column cells, editors are not created: cells are drawn with the help of the corresponding ViewInfo object, which knows how to render an editor on a canvas.  The ViewInfo object is retrieved via the virtual GetViewInfoClass function of the Properties attribute.

When an editor is to be created, the editor class required is determined from the Properties object of a repository item via the GetContainerClass function.  After the editor is instantiated, the Properties value of the repository item is assigned to the Properties member of the edit control, thus creating an editor with the required behavior.

The repository provides a convenient way to support a collection of repository items.  It is easy to add, delete repository items and customize their properties at design time via a repository dialog.


TcxEditRepository Hierarchy
Hierarchy

TComponent

     |


Properties for TcxEditRepository
TcxEditRepository Properties

TcxEditRepository          Legend

In TcxEditRepository

Count

Items


Methods for TcxEditRepository
TcxEditRepository Methods

TcxEditRepository          Legend

In TcxEditRepository

 Clear

 Create

 CreateItem

 CreateItemEx

 Destroy


TcxEditRepository.Count

TcxEditRepository          See Also

Returns the number of repository items in a repository object.

property Count: Integer;

Description

Use the Count property to return the number of repository items in the current repository.  You can access individual repository items via the indexed Items property.

ReadOnly Property


TcxEditRepository.Items

TcxEditRepository          See Also

Defines the collection of repository items.

property Items[Index: Integer]: TcxEditRepositoryItem;

Description

The Items property provides access to individual repository items in the repository.  Each repository item represents a descendant of the TcxEditRepositoryItem class.

ReadOnly Property


TcxEditRepository.Clear

TcxEditRepository          See Also

Clears the repository by destroying all repository items.

procedure Clear;

Description

The Clear method destroys all repository items stored in the repository.  If you need to remove a specific repository item, you can obtain a reference to it via the Items property and invoke its destructor.


TcxEditRepository.Create

TcxEditRepository

Creates an instance of the TcxEditRepository class.

constructor Create(AOwner: TComponent); override;

Description

The constructor creates a repository object and initializes the list to store repository items.  The AOwner parameter specifies the owner of the repository.  The owner disposes of the component when it is destroyed.


TcxEditRepository.CreateItem

TcxEditRepository          See Also

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

function CreateItem(ARepositoryItemClass: TcxEditRepositoryItemClass): TcxEditRepositoryItem; virtual;

Description

The CreateItem method creates a new instance of a repository item (whose class is determined by the ARepositoryItemClass parameter), adds this item to the Items collection and returns it as the function result.  The current TcxEditRepository object becomes the owner of the created repository item. The owner disposes of the repository item when it is destroyed.


TcxEditRepository.CreateItemEx

TcxEditRepository          See Also

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

function CreateItemEx(ARepositoryItemClass: TcxEditRepositoryItemClass; AOwner: TComponent): TcxEditRepositoryItem; virtual;

Description

The CreateItemEx method creates a new instance of a repository item (whose class is determined by the ARepositoryItemClass parameter), adds this item to the Items collection and returns it as the function result.  The AOwner parameter specifies the component, which becomes the owner of the created repository item.  The owner disposes of the repository item when it is destroyed.


TcxEditRepository.Destroy

TcxEditRepository

Destroys a TcxEditRepository instance.

destructor Destroy; override;

Description

The destructor destroys all repository items stored in the repository and frees all resources allocated by a TcxEditRepository object.


TcxEditRepositoryBlobItem
TcxEditRepositoryBlobItem Object

Hierarchy          Properties          Methods         See Also

Represents the repository item containing settings specific to a TcxBlobEdit control.

Unit

cxEditRepositoryItems

TcxEditRepositoryBlobItem = class(TcxEditRepositoryItem);

Description

TcxEditRepositoryBlobItem stores properties specific to a TcxBlobEdit control via the Properties object.  A repository object of the TcxEditRepository class maintains a collection of repository items.


TcxEditRepositoryBlobItem Hierarchy
Hierarchy

TComponent

     |

TcxEditRepositoryItem

     |


Properties for TcxEditRepositoryBlobItem
TcxEditRepositoryBlobItem Properties

TcxEditRepositoryBlobItem          Legend

In TcxEditRepositoryBlobItem

Properties

Derived from TcxEditRepositoryItem

Properties

Repository


Methods for TcxEditRepositoryBlobItem
TcxEditRepositoryBlobItem Methods

TcxEditRepositoryBlobItem          Legend

Derived from TcxEditRepositoryItem

 Create

 Destroy

 GetBaseName


TcxEditRepositoryBlobItem.Properties

TcxEditRepositoryBlobItem

Defines settings specific to an appropriate editor.

property Properties: TcxBlobEditProperties;

Description

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


TcxEditRepositoryButtonItem
TcxEditRepositoryButtonItem Object

Hierarchy          Properties          Methods          See Also

Represents the repository item containing settings specific to a TcxButtonEdit control.

Unit

cxEditRepositoryItems

TcxEditRepositoryButtonItem = class(TcxEditRepositoryItem);

Description

TcxEditRepositoryButtonItem stores properties specific to a TcxButtonEdit control via the Properties object.  A repository object of the TcxEditRepository class maintains a collection of repository items.


TcxEditRepositoryButtonItem Hierarchy
Hierarchy

TComponent

     |

TcxEditRepositoryItem

     |


Properties for TcxEditRepositoryButtonItem
TcxEditRepositoryButtonItem Properties

TcxEditRepositoryButtonItem          Legend

In TcxEditRepositoryButtonItem

Properties

Derived from TcxEditRepositoryItem

Properties

Repository


Methods for TcxEditRepositoryButtonItem
TcxEditRepositoryButtonItem Methods

TcxEditRepositoryButtonItem          Legend

Derived from TcxEditRepositoryItem

 Create

 Destroy

 GetBaseName


TcxEditRepositoryButtonItem.Properties

TcxEditRepositoryButtonItem

Defines settings specific to a specific editor.

property Properties: TcxButtonEditProperties;

Description

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


TcxEditRepositoryCalcItem
TcxEditRepositoryCalcItem Object

Hierarchy          Properties          Methods          See Also

Represents a repository item containing settings specific to a TcxCalcEdit control.

Unit

cxEditRepositoryItems

TcxEditRepositoryCalcItem = class(TcxEditRepositoryItem);

Description

TcxEditRepositoryCalcItem stores properties specific to a TcxCalcEdit control via the Properties object.  A repository object of the TcxEditRepository class maintains a collection of repository items.


TcxEditRepositoryCalcItem Hierarchy
Hierarchy

TComponent

     |

TcxEditRepositoryItem

     |


Properties for TcxEditRepositoryCalcItem
TcxEditRepositoryCalcItem Properties

TcxEditRepositoryCalcItem          Legend

In TcxEditRepositoryCalcItem

Properties

Derived from TcxEditRepositoryItem

Properties

Repository


Methods for TcxEditRepositoryCalcItem
TcxEditRepositoryCalcItem Methods

TcxEditRepositoryCalcItem          Legend

Derived from TcxEditRepositoryItem

 Create

 Destroy

 GetBaseName


TcxEditRepositoryCalcItem.Properties

TcxEditRepositoryCalcItem

Defines settings specific to a specific editor.

property Properties: TcxCalcEditProperties;

Description

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


TcxEditRepositoryCheckBoxItem
TcxEditRepositoryCheckBoxItem Object

Hierarchy          Properties          Methods          See Also

Represents a repository item containing settings specific to a TcxCheckBox control.

Unit

cxEditRepositoryItems

TcxEditRepositoryCheckBoxItem = class(TcxEditRepositoryItem);

Description

TcxEditRepositoryCheckBoxItem stores properties specific to a TcxCheckBox control via the Properties object.  A repository object of the TcxEditRepository class maintains a collection of repository items.


TcxEditRepositoryCheckBoxItem Hierarchy
Hierarchy

TComponent

     |

TcxEditRepositoryItem

     |


Properties for TcxEditRepositoryCheckBoxItem
TcxEditRepositoryCheckBoxItem Properties

TcxEditRepositoryCheckBoxItem          Legend

Derived from TcxEditRepositoryItem

Properties

Repository


Methods for TcxEditRepositoryCheckBoxItem
TcxEditRepositoryCheckBoxItem Methods

TcxEditRepositoryCheckBoxItem          Legend

Derived from TcxEditRepositoryItem

 Create

 Destroy

 GetBaseName


TcxEditRepositoryCheckBoxItem.Properties

TcxEditRepositoryCheckBoxItem

Defines settings specific to an appropriate editor.

property Properties: TcxCheckBoxProperties;

Description

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


TcxEditRepositoryComboBoxItem
TcxEditRepositoryComboBoxItem Object

Hierarchy          Properties          Methods          See Also

Represents a repository item containing settings specific to a TcxComboBox control.

Unit

cxEditRepositoryItems

TcxEditRepositoryComboBoxItem = class(TcxEditRepositoryItem);

Description

TcxEditRepositoryComboBoxItem stores properties specific to a TcxComboBox control via the Properties object.  A repository object of the TcxEditRepository class maintains a collection of repository items.


TcxEditRepositoryComboBoxItem Hierarchy
Hierarchy

TComponent

     |

TcxEditRepositoryItem

     |


Properties for TcxEditRepositoryComboBoxItem
TcxEditRepositoryComboBoxItem Properties

TcxEditRepositoryComboBoxItem          Legend

In TcxEditRepositoryComboBoxItem

Properties

Derived from TcxEditRepositoryItem

Properties

Repository


Methods for TcxEditRepositoryComboBoxItem
TcxEditRepositoryComboBoxItem Methods

TcxEditRepositoryComboBoxItem          Legend

Derived from TcxEditRepositoryItem

 Create

 Destroy

 GetBaseName


TcxEditRepositoryComboBoxItem.Properties

TcxEditRepositoryComboBoxItem

Defines settings specific to an appropriate editor.

property Properties: TcxComboBoxProperties;

Description

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


TcxEditRepositoryCurrencyItem
TcxEditRepositoryCurrencyItem Object

Hierarchy          Properties          Methods          See Also

Represents a repository item containing settings specific to a TcxCurrencyEdit control.

Unit

cxEditRepositoryItems

TcxEditRepositoryCurrencyItem = class(TcxEditRepositoryItem);

Description

TcxEditRepositoryCurrencyItem stores properties specific to a TcxCurrencyEdit control via the Properties object.  A repository object of the TcxEditRepository class maintains a collection of repository items.


TcxEditRepositoryCurrencyItem Hierarchy
Hierarchy

TComponent

     |

TcxEditRepositoryItem

     |


Properties for TcxEditRepositoryCurrencyItem
TcxEditRepositoryCurrencyItem Properties

TcxEditRepositoryCurrencyItem          Legend

In TcxEditRepositoryCurrencyItem

Properties

Derived from TcxEditRepositoryItem

Properties

Repository


Methods for TcxEditRepositoryCurrencyItem
TcxEditRepositoryCurrencyItem Methods

TcxEditRepositoryCurrencyItem          Legend

Derived from TcxEditRepositoryItem

 Create

 Destroy

 GetBaseName


TcxEditRepositoryCurrencyItem.Properties

TcxEditRepositoryCurrencyItem

Defines settings specific to an appropriate editor.

property Properties: TcxCurrencyEditProperties;

Description

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


TcxEditRepositoryDateItem
TcxEditRepositoryDateItem Object

Hierarchy          Properties          Methods          See Also

Represents a repository item containing settings specific to a TcxDateEdit control.

Unit

cxEditRepositoryItems

TcxEditRepositoryDateItem = class(TcxEditRepositoryItem);

Description

TcxEditRepositoryDateItem stores properties specific to a TcxDateEdit control via the Properties object.  A repository object of the TcxEditRepository class maintains a collection of repository items.


TcxEditRepositoryDateItem Hierarchy
Hierarchy

TComponent

     |

TcxEditRepositoryItem

     |


Properties for TcxEditRepositoryDateItem
TcxEditRepositoryDateItem Properties

TcxEditRepositoryDateItem          Legend

In TcxEditRepositoryDateItem

Properties

Derived from TcxEditRepositoryItem

Properties

Repository


Methods for TcxEditRepositoryDateItem
TcxEditRepositoryDateItem Methods

TcxEditRepositoryDateItem          Legend

Derived from TcxEditRepositoryItem

 Create

 Destroy

 GetBaseName


TcxEditRepositoryDateItem.Properties

TcxEditRepositoryDateItem

Defines settings specific to an appropriate editor.

property Properties: TcxDateEditProperties;

Description

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


TcxEditRepositoryHyperLinkItem
TcxEditRepositoryHyperLinkItem Object

Hierarchy          Properties          Methods          See Also

Represents a repository item containing settings specific to a TcxHyperLinkEdit control.

Unit

cxEditRepositoryItems

TcxEditRepositoryHyperLinkItem = class(TcxEditRepositoryItem);

Description

TcxEditRepositoryHyperLinkItem stores properties specific to a TcxHyperLinkEdit control via the Properties object.  A repository object of the TcxEditRepository class maintains a collection of repository items.


TcxEditRepositoryHyperLinkItem Hierarchy
Hierarchy

TComponent

     |

TcxEditRepositoryItem

     |


Properties for TcxEditRepositoryHyperLinkItem
TcxEditRepositoryHyperLinkItem Properties

TcxEditRepositoryHyperLinkItem          Legend

In TcxEditRepositoryHyperLinkItem

Properties

Derived from TcxEditRepositoryItem

Properties

Repository


Methods for TcxEditRepositoryHyperLinkItem
TcxEditRepositoryHyperLinkItem Methods

TcxEditRepositoryHyperLinkItem          Legend

Derived from TcxEditRepositoryItem

 Create

 Destroy

 GetBaseName


TcxEditRepositoryHyperLinkItem.Properties

TcxEditRepositoryHyperLinkItem

Defines settings specific to an appropriate editor.

property Properties: TcxHyperLinkEditProperties;

Description

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


TcxEditRepositoryImageComboBoxItem
TcxEditRepositoryImageComboBoxItem Object

Hierarchy          Properties          Methods         See Also

Represents a repository item containing settings specific to a TcxImageComboBox control.

Unit

cxEditRepositoryItems

TcxEditRepositoryImageComboBoxItem = class(TcxEditRepositoryItem);

Description

TcxEditRepositoryImageComboBoxItem stores properties specific to a TcxImageComboBox control via the Properties object.  A repository object of the TcxEditRepository class maintains a collection of repository items.


TcxEditRepositoryImageComboBoxItem Hierarchy
Hierarchy

TComponent

     |

TcxEditRepositoryItem

     |


Properties for TcxEditRepositoryImageComboBoxItem
TcxEditRepositoryImageComboBoxItem Properties

TcxEditRepositoryImageComboBoxItem          Legend

In TcxEditRepositoryImageComboBoxItem

Properties

Derived from TcxEditRepositoryItem

Properties

Repository


Methods for TcxEditRepositoryImageComboBoxItem
TcxEditRepositoryImageComboBoxItem Methods

TcxEditRepositoryImageComboBoxItem          Legend

Derived from TcxEditRepositoryItem

 Create

 Destroy

 GetBaseName


TcxEditRepositoryImageComboBoxItem.Properties

TcxEditRepositoryImageComboBoxItem

Defines settings specific to an appropriate editor.

property Properties: TcxImageComboBoxProperties;

Description

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


TcxEditRepositoryImageItem
TcxEditRepositoryImageItem Object

Hierarchy          Properties          Methods          See Also

Represents a repository item containing settings specific to a TcxImage control.

Unit

cxEditRepositoryItems

TcxEditRepositoryImageItem = class(TcxEditRepositoryItem);

Description

TcxEditRepositoryImageItem stores properties specific to a TcxImage control via the Properties object.  A repository object of the TcxEditRepository class maintains a collection of repository items.


TcxEditRepositoryImageItem Hierarchy
Hierarchy

TComponent

     |

TcxEditRepositoryItem

     |


Properties for TcxEditRepositoryImageItem
TcxEditRepositoryImageItem Properties

TcxEditRepositoryImageItem          Legend

In TcxEditRepositoryImageItem

Properties

Derived from TcxEditRepositoryItem

Properties

Repository


Methods for TcxEditRepositoryImageItem
TcxEditRepositoryImageItem Methods

TcxEditRepositoryImageItem          Legend

Derived from TcxEditRepositoryItem

 Create

 Destroy

 GetBaseName


TcxEditRepositoryImageItem.Properties

TcxEditRepositoryImageItem

Defines settings specific to an appropriate editor.

property Properties: TcxImageProperties;

Description

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


TcxEditRepositoryItem
TcxEditRepositoryItem Object

Hierarchy          Properties          Methods          See Also

Represents a repository item.

Unit

cxEdit

TcxEditRepositoryItem = class(TComponent);

Description

A repository item maintains information specific to an appropriate editor in the Properties object.  TcxEditRepositoryItem descendants redefine the Properties member allowing you to adjust attributes specific a corresponding edit control.  A repository object of the TcxEditRepository class maintains a collection of repository items.

A repository item can be used to specify properties common to several editors.  See the RepositoryItem property to assign a repository item to the editor.  Properties of an editor assigned a repository item address the properties of the repository item.  Editor properties are preserved in this case and restored when clearing the RepositoryItem value.

Repository items are also used when assigning a column type in a grid control.  To make a grid control use the desired editor for a specific column, you can assign the corresponding repository item to this column.  When editing data in your grid, only one instance of the editor exists.  This editor is used to edit the current cell value.  For other column cells editors are not created: cells are drawn with the help of the corresponding ViewInfo object, which knows how to render an editor on a canvas.  The ViewInfo object is retrieved via the virtual GetViewInfoClass function of the Properties attribute.

When an editor is to be created, the editor class is determined from the Properties object of a repository item via the GetContainerClass function.  After the editor is instantiated, the Properties value of the repository item is assigned to the Properties member of the edit control, thus creating an editor with the required behavior.


TcxEditRepositoryItem Hierarchy
Hierarchy

TComponent

     |


Properties for TcxEditRepositoryItem
TcxEditRepositoryItem Properties

TcxEditRepositoryItem          Legend

In TcxEditRepositoryItem

Properties

Repository


Methods for TcxEditRepositoryItem
TcxEditRepositoryItem Methods

TcxEditRepositoryItem          Legend

In TcxEditRepositoryItem

 Create

 Destroy

 GetBaseName


TcxEditRepositoryItem.Properties

TcxEditRepositoryItem

Defines settings specific to an appropriate editor.

property Properties: TcxCustomEditProperties;

Description

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


TcxEditRepositoryItem.Repository

TcxEditRepositoryItem

Specifies the repository object containing the current repository item.

property Repository: TcxEditRepository;

Description

The Repository property provides access to the repository object storing repository items.


TcxEditRepositoryItem.Create

TcxEditRepositoryItem

Creates a repository item.

constructor Create(AOwner: TComponent); override;

Description

The constructor creates a new instance of a repository item.  It creates the Properties object of a specific class object via which you define different settings specific to a corresponding editor.

The AOwner parameter specifies the owner of this repository item.  The owner disposes of the component when it is destroyed.


TcxEditRepositoryItem.Destroy

TcxEditRepositoryItem

Destroys an instance of the repository item.

destructor Destroy; override;

Description

The destructor removes a repository item from the repository and frees all resources allocated by it.


TcxEditRepositoryItem.GetBaseName

TcxEditRepositoryItem

Returns the name of the current repository item.

function GetBaseName: string; virtual;

Description

The GetBaseName function is called whenever the name of the repository item being created needs to be determined.  By default, this function uses the class name of the repository item to generate the return value.


TcxEditRepositoryMaskItem
TcxEditRepositoryMaskItem Object

Hierarchy          Properties          Methods          See Also

Represents a repository item containing settings specific to a TcxMaskEdit control.

Unit

cxEditRepositoryItems

TcxEditRepositoryMaskItem = class(TcxEditRepositoryItem);

Description

TcxEditRepositoryMaskItem stores properties specific to a TcxMaskEdit control via the Properties object.  A repository object of the TcxEditRepository class maintains a collection of repository items.


TcxEditRepositoryMaskItem Hierarchy
Hierarchy

TComponent

     |

TcxEditRepositoryItem

     |


Properties for TcxEditRepositoryMaskItem
TcxEditRepositoryMaskItem Properties

TcxEditRepositoryMaskItem          Legend

In TcxEditRepositoryMaskItem

Properties

Derived from TcxEditRepositoryItem

Properties

Repository


Methods for TcxEditRepositoryMaskItem
TcxEditRepositoryMaskItem Methods

TcxEditRepositoryMaskItem          Legend

Derived from TcxEditRepositoryItem

 Create

 Destroy

 GetBaseName


TcxEditRepositoryMaskItem.Properties

TcxEditRepositoryMaskItem

Defines settings specific to an appropriate editor.

property Properties: TcxMaskEditProperties;

Description

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


TcxEditRepositoryMemoItem
TcxEditRepositoryMemoItem Object

Hierarchy          Properties          Methods          See Also

Represents a repository item containing settings specific to a TcxMemo control.

Unit

cxEditRepositoryItems

TcxEditRepositoryMemoItem = class(TcxEditRepositoryItem);

Description

TcxEditRepositoryMemoItem stores properties specific to a TcxMemo control via the Properties object.  A repository object of the TcxEditRepository class maintains a collection of repository items.


TcxEditRepositoryMemoItem Hierarchy
Hierarchy

TComponent

     |

TcxEditRepositoryItem

     |


Properties for TcxEditRepositoryMemoItem
TcxEditRepositoryMemoItem Properties

TcxEditRepositoryMemoItem          Legend

In TcxEditRepositoryMemoItem

Properties

Derived from TcxEditRepositoryItem

Properties

Repository


Methods for TcxEditRepositoryMemoItem
TcxEditRepositoryMemoItem Methods

TcxEditRepositoryMemoItem          Legend

Derived from TcxEditRepositoryItem

 Create

 Destroy

 GetBaseName


TcxEditRepositoryMemoItem.Properties

TcxEditRepositoryMemoItem

Defines settings specific to an appropriate editor.

property Properties: TcxMemoProperties;

Description

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


TcxEditRepositoryMRUItem
TcxEditRepositoryMRUItem Object

Hierarchy          Properties          Methods          See Also

Represents a repository item containing settings specific to a TcxMRUEdit control.

Unit

cxEditRepositoryItems

TcxEditRepositoryMRUItem = class(TcxEditRepositoryItem);

Description

TcxEditRepositoryMRUItem stores properties specific to a TcxMRUEdit control via the Properties object.  A repository object of the TcxEditRepository class maintains a collection of repository items.


TcxEditRepositoryMRUItem Hierarchy
Hierarchy

TComponent

     |

TcxEditRepositoryItem

     |


Properties for TcxEditRepositoryMRUItem
TcxEditRepositoryMRUItem Properties

TcxEditRepositoryMRUItem          Legend

In TcxEditRepositoryMRUItem

Properties

Derived from TcxEditRepositoryItem

Properties

Repository


Methods for TcxEditRepositoryMRUItem
TcxEditRepositoryMRUItem Methods

TcxEditRepositoryMRUItem          Legend

Derived from TcxEditRepositoryItem

 Create

 Destroy

 GetBaseName


TcxEditRepositoryMRUItem.Properties

TcxEditRepositoryMRUItem

Defines settings specific to an appropriate editor.

property Properties: TcxMRUEditProperties;

Description

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


TcxEditRepositoryPopupItem
TcxEditRepositoryPopupItem Object

Hierarchy          Properties          Methods          See Also

Represents a repository item containing settings specific to a TcxPopupEdit control.

Unit

cxEditRepositoryItems

TcxEditRepositoryPopupItem = class(TcxEditRepositoryItem);

Description

TcxEditRepositoryPopupItem stores properties specific to a TcxPopupEdit control via the Properties object.  A repository object of the TcxEditRepository class maintains a collection of repository items.


TcxEditRepositoryPopupItem Hierarchy
Hierarchy

TComponent

     |

TcxEditRepositoryItem

     |


Properties for TcxEditRepositoryPopupItem
TcxEditRepositoryPopupItem Properties

TcxEditRepositoryPopupItem          Legend

In TcxEditRepositoryPopupItem

Properties

Derived from TcxEditRepositoryItem

Properties

Repository


Methods for TcxEditRepositoryPopupItem
TcxEditRepositoryPopupItem Methods

TcxEditRepositoryPopupItem          Legend

Derived from TcxEditRepositoryItem

 Create

 Destroy

 GetBaseName


TcxEditRepositoryPopupItem.Properties

TcxEditRepositoryPopupItem

Defines settings specific to an appropriate editor.

property Properties: TcxPopupEditProperties;

Description

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


TcxEditRepositorySpinItem
TcxEditRepositorySpinItem Object

Hierarchy          Properties          Methods          See Also

Represents a repository item containing settings specific to a TcxSpinEdit control.

Unit

cxEditRepositoryItems

TcxEditRepositorySpinItem = class(TcxEditRepositoryItem);

Description

TcxEditRepositorySpinItem stores properties specific to a TcxSpinEdit control via the Properties object.  A repository object of the TcxEditRepository class maintains a collection of repository items.


TcxEditRepositorySpinItem Hierarchy
Hierarchy

TComponent

     |

TcxEditRepositoryItem

     |


Properties for TcxEditRepositorySpinItem
TcxEditRepositorySpinItem Properties

TcxEditRepositorySpinItem          Legend

In TcxEditRepositorySpinItem

Properties

Derived from TcxEditRepositoryItem

Properties

Repository


Methods for TcxEditRepositorySpinItem
TcxEditRepositorySpinItem Methods

TcxEditRepositorySpinItem          Legend

Derived from TcxEditRepositoryItem

 Create

 Destroy

 GetBaseName


TcxEditRepositorySpinItem.Properties

TcxEditRepositorySpinItem

Defines settings specific to an appropriate editor.

property Properties: TcxSpinEditProperties;

Description

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


TcxEditRepositoryTextItem
TcxEditRepositoryTextItem Object

Hierarchy          Properties          Methods          See Also

Represents a repository item containing settings specific to a TcxTextEdit control.

Unit

cxEditRepositoryItems

TcxEditRepositoryTextItem = class(TcxEditRepositoryItem);

Description

TcxEditRepositoryTextItem stores properties specific to a TcxTextEdit control via the Properties object.  A repository object of the TcxEditRepository class maintains a collection of repository items.


TcxEditRepositoryTextItem Hierarchy
Hierarchy

TComponent

     |

TcxEditRepositoryItem

     |


Properties for TcxEditRepositoryTextItem
TcxEditRepositoryTextItem Properties

TcxEditRepositoryTextItem          Legend

In TcxEditRepositoryTextItem

Properties

Derived from TcxEditRepositoryItem

Properties

Repository


Methods for TcxEditRepositoryTextItem
TcxEditRepositoryTextItem Methods

TcxEditRepositoryTextItem          Legend

Derived from TcxEditRepositoryItem

 Create

 Destroy

 GetBaseName


TcxEditRepositoryTextItem.Properties

TcxEditRepositoryTextItem

Defines settings specific to an appropriate editor.

property Properties: TcxTextEditProperties;

Description

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


TcxEditRepositoryTimeItem
TcxEditRepositoryTimeItem Object

Hierarchy          Properties          Methods          See Also

Represents a repository item containing settings specific to a TcxTimeEdit control.

Unit

cxEditRepositoryItems

TcxEditRepositoryTimeItem = class(TcxEditRepositoryItem);

Description

TcxEditRepositoryTimeItem stores properties specific to a TcxTimeEdit control via the Properties object.  A repository object of the TcxEditRepository class maintains a collection of repository items.


TcxEditRepositoryTimeItem Hierarchy
Hierarchy

TComponent

     |

TcxEditRepositoryItem

     |


Properties for TcxEditRepositoryTimeItem
TcxEditRepositoryTimeItem Properties

TcxEditRepositoryTimeItem          Legend

In TcxEditRepositoryTimeItem

Properties

Derived from TcxEditRepositoryItem

Properties

Repository


Methods for TcxEditRepositoryTimeItem
TcxEditRepositoryTimeItem Methods

TcxEditRepositoryTimeItem          Legend

Derived from TcxEditRepositoryItem

 Create

 Destroy

 GetBaseName


TcxEditRepositoryTimeItem.Properties

TcxEditRepositoryTimeItem

Defines settings specific to an appropriate editor.

property Properties: TcxTimeEditProperties;

Description

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


TcxEditRepositoryItemClass
TcxEditRepositoryItemClass type

Represents a repository item class.

Unit

cxEdit

TcxEditRepositoryItemClass = class of TcxEditRepositoryItem;

Description

TcxEditRepositoryItemClass represents a meta-class used to create repository items within the repository via the TcxEditRepository.CreateItem and TcxEditRepository.CreateItemEx functions.


TcxEditRepositoryRadioGroupItem
TcxEditRepositoryRadioGroupItem Object

Hierarchy          Properties          Methods

Represents a repository item containing settings specific to a TcxRadioGroup control.

Unit

cxEditRepositoryItems

TcxEditRepositoryRadioGroupItem = class(TcxEditRepositoryItem)

Description

TcxEditRepositoryRadioGroupItem stores properties specific to a TcxRadioGroup control via the Properties object.  A repository object of the TcxEditRepository class maintains a collection of repository items.


TcxEditRepositoryRadioGroupItem Hierarchy
Hierarchy

TComponent

     |

TcxEditRepositoryItem

     |


Properties for TcxEditRepositoryRadioGroupItem
TcxEditRepositoryRadioGroupItem Properties

TcxEditRepositoryRadioGroupItem          Legend

In TcxEditRepositoryRadioGroupItem

Properties

Derived from TcxEditRepositoryItem

Properties

Repository


Methods for TcxEditRepositoryRadioGroupItem
TcxEditRepositoryRadioGroupItem Methods

TcxEditRepositoryRadioGroupItem          Legend

Derived from TcxEditRepositoryItem

 Create

 Destroy

 GetBaseName


TcxEditRepositoryRadioGroupItem.Properties

TcxEditRepositoryRadioGroupItem

Defines settings specific to an appropriate editor.

property Properties: TcxRadioGroupProperties;

Description

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


cxExtEditRepositoryItems Unit Overview
cxExtEditRepositoryItems Unit

Classes

TcxEditRepositoryCheckComboBox

TcxEditRepositoryColorComboBox

TcxEditRepositoryFontNameComboBox

TcxEditRepositoryLabel

TcxEditRepositoryProgressBar

TcxEditRepositoryRichItem

TcxEditRepositorySpinButton

TcxEditRepositoryTrackBar


TcxEditRepositoryCheckComboBox
TcxEditRepositoryCheckComboBox Object

Hierarchy          Properties          Methods

Represents a repository item containing settings specific to a combo box control.

Unit

cxExtEditRepositoryItems

TcxEditRepositoryCheckComboBox = class(TcxEditRepositoryItem)

Description

TcxEditRepositoryCheckComboBox stores properties specific to a TcxCheckComboBox control via the Properties object.  A repository object of the TcxEditRepository class maintains a collection of repository items.


TcxEditRepositoryCheckComboBox Hierarchy
Hierarchy

TComponent

     |

TcxEditRepositoryItem

     |


Properties for TcxEditRepositoryCheckComboBox
TcxEditRepositoryCheckComboBox Properties

TcxEditRepositoryCheckComboBox          Legend

In TcxEditRepositoryCheckComboBox

Properties

Derived from TcxEditRepositoryItem

Properties

Repository


Methods for TcxEditRepositoryCheckComboBox
TcxEditRepositoryCheckComboBox Methods

TcxEditRepositoryCheckComboBox          Legend

Derived from TcxEditRepositoryItem

Create

Destroy

GetBaseName


TcxEditRepositoryCheckComboBox.Properties

TcxEditRepositoryCheckComboBox

Defines settings specific to an appropriate editor.

property Properties: TcxCheckComboBoxProperties;

Description

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


TcxEditRepositoryColorComboBox
TcxEditRepositoryColorComboBox Object

Hierarchy          Properties          Methods

Represents a repository item containing settings specific to a TcxColorComboBox control.

Unit

cxExtEditRepositoryItems

TcxEditRepositoryColorComboBox = class(TcxEditRepositoryItem)

Description

The TcxEditRepositoryColorComboBox stores properties specific to a TcxColorComboBox control via the Properties object.  A repository object of the TcxEditRepository class maintains a collection of repository items.


TcxEditRepositoryColorComboBox Hierarchy
Hierarchy

TComponent

     |

TcxEditRepositoryItem

     |


Properties for TcxEditRepositoryColorComboBox
TcxEditRepositoryColorComboBox Properties

TcxEditRepositoryColorComboBox          Legend

In TcxEditRepositoryColorComboBox

Properties

Derived from TcxEditRepositoryItem

Properties

Repository


Methods for TcxEditRepositoryColorComboBox
TcxEditRepositoryColorComboBox Methods

TcxEditRepositoryColorComboBox          Legend

Derived from TcxEditRepositoryItem

Create

Destroy

GetBaseName


TcxEditRepositoryColorComboBox.Properties

TcxEditRepositoryColorComboBox

Defines settings specific to an appropriate editor.

property Properties: TcxColorComboBoxProperties;

Description

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


TcxEditRepositoryFontNameComboBox
TcxEditRepositoryFontNameComboBox Object

Hierarchy          Properties          Methods

Represents a repository item containing settings specific to a TcxFontNameComboBox control.

Unit

cxExtEditRepositoryItems

TcxEditRepositoryFontNameComboBox = class(TcxEditRepositoryItem)

Description

The TcxEditRepositoryFontNameComboBox stores properties specific to a TcxFontNameComboBox control via the Properties object.  A repository object of the TcxEditRepository class maintains a collection of repository items.


TcxEditRepositoryFontNameComboBox Hierarchy
Hierarchy

TComponent

     |

TcxEditRepositoryItem

     |


Properties for TcxEditRepositoryFontNameComboBox
TcxEditRepositoryFontNameComboBox Properties

TcxEditRepositoryFontNameComboBox          Legend

In TcxEditRepositoryFontNameComboBox

Properties

Derived from TcxEditRepositoryItem

Properties

Repository


Methods for TcxEditRepositoryFontNameComboBox
TcxEditRepositoryFontNameComboBox Methods

TcxEditRepositoryFontNameComboBox          Legend

Derived from TcxEditRepositoryItem

Create

Destroy

GetBaseName


TcxEditRepositoryFontNameComboBox.Properties

TcxEditRepositoryFontNameComboBox

Defines settings specific to an appropriate editor.

property Properties: TcxFontNameComboBoxProperties;

Description

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


TcxEditRepositoryLabel
TcxEditRepositoryLabel Object

Hierarchy          Properties          Methods

Represents a repository item containing settings specific to a TcxLabel control.

Unit

cxExtEditRepositoryItems

TcxEditRepositoryLabel = class(TcxEditRepositoryItem)

Description

The TcxEditRepositoryLabel stores properties specific to a TcxLabel control via the Properties object.  A repository object of the TcxEditRepository class maintains a collection of repository items.


TcxEditRepositoryLabel Hierarchy
Hierarchy

TComponent

     |

TcxEditRepositoryItem

     |


Properties for TcxEditRepositoryLabel
TcxEditRepositoryLabel Properties

TcxEditRepositoryLabel          Legend

In TcxEditRepositoryLabel

Properties

Derived from TcxEditRepositoryItem

Properties

Repository


Methods for TcxEditRepositoryLabel
TcxEditRepositoryLabel Methods

TcxEditRepositoryLabel          Legend

Derived from TcxEditRepositoryItem

Create

Destroy

GetBaseName


TcxEditRepositoryLabel.Properties

TcxEditRepositoryLabel

Defines settings specific to an appropriate editor.

property Properties: TcxLabelProperties;

Description

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


TcxEditRepositoryProgressBar
TcxEditRepositoryProgressBar Object

Hierarchy          Properties          Methods

Represents a repository item containing settings specific to a TcxProgressBar control.

Unit

cxExtEditRepositoryItems

TcxEditRepositoryProgressBar = class(TcxEditRepositoryItem)

Description

The TcxEditRepositoryProgressBar stores properties specific to a TcxProgressBar control via the Properties object.  A repository object of the TcxEditRepository class maintains a collection of repository items.


TcxEditRepositoryProgressBar Hierarchy
Hierarchy

TComponent

     |

TcxEditRepositoryItem

     |


Properties for TcxEditRepositoryProgressBar
TcxEditRepositoryProgressBar Properties

TcxEditRepositoryProgressBar          Legend

In TcxEditRepositoryProgressBar

Properties

Derived from TcxEditRepositoryItem

Properties

Repository


Methods for TcxEditRepositoryProgressBar
TcxEditRepositoryProgressBar Methods

TcxEditRepositoryProgressBar          Legend

Derived from TcxEditRepositoryItem

Create

Destroy

GetBaseName


TcxEditRepositoryProgressBar.Properties

TcxEditRepositoryProgressBar

Defines settings specific to an appropriate editor.

property Properties: TcxProgressBarProperties;

Description

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


TcxEditRepositoryTrackBar
TcxEditRepositoryTrackBar Object

Hierarchy          Properties          Methods

Represents a repository item containing settings specific to a TcxTrackBar control.

Unit

cxExtEditRepositoryItems

TcxEditRepositoryTrackBar = class(TcxEditRepositoryItem)

Description

The TcxEditRepositoryTrackBar stores properties specific to a TcxTrackBar control via the Properties object.  A repository object of the TcxEditRepository class maintains a collection of repository items.


TcxEditRepositoryTrackBar Hierarchy
Hierarchy

TComponent

     |

TcxEditRepositoryItem

     |


Properties for TcxEditRepositoryTrackBar
TcxEditRepositoryTrackBar Properties

TcxEditRepositoryTrackBar          Legend

In TcxEditRepositoryTrackBar

Properties

Derived from TcxEditRepositoryItem

Properties

Repository


Methods for TcxEditRepositoryTrackBar
TcxEditRepositoryTrackBar Methods

TcxEditRepositoryTrackBar          Legend

Derived from TcxEditRepositoryItem

Create

Destroy

GetBaseName


TcxEditRepositoryTrackBar.Properties

TcxEditRepositoryTrackBar

Defines settings specific to an appropriate editor.

property Properties: TcxTrackBarProperties;

Description

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


TcxEditRepositorySpinButton
TcxEditRepositorySpinButton Object

Hierarchy          Properties          Methods

Represents a repository item containing settings specific to a TcxSpinButton control.

Unit

cxExtEditRepositoryItems

TcxEditRepositorySpinButton = class(TcxEditRepositoryItem)

Description

The TcxEditRepositorySpinButton stores properties specific to a TcxSpinButton control via the Properties object.  A repository object of the TcxEditRepository class maintains a collection of repository items.


TcxEditRepositorySpinButton Hierarchy
Hierarchy

TComponent

     |

TcxEditRepositoryItem

     |


Properties for TcxEditRepositorySpinButton
TcxEditRepositorySpinButton Properties

TcxEditRepositorySpinButton          Legend

In TcxEditRepositorySpinButton

Properties

Derived from TcxEditRepositoryItem

Properties

Repository


Methods for TcxEditRepositorySpinButton
TcxEditRepositorySpinButton Methods

TcxEditRepositorySpinButton          Legend

Derived from TcxEditRepositoryItem

Create

Destroy

GetBaseName


TcxEditRepositorySpinButton.Properties

TcxEditRepositorySpinButton

Defines settings specific to an appropriate editor.

property Properties: TcxSpinButtonProperties;

Description

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


TcxEditRepositoryRichItem
TcxEditRepositoryRichItem Object

Hierarchy          Properties          Methods

Represents a repository item containing settings specific to a TcxSpinButton control.

Unit

cxExtEditRepositoryItems

TcxEditRepositoryRichItem = class(TcxEditRepositoryItem)

Description

The TcxEditRepositoryRichItem stores properties specific to a TcxRichEdit control via the Properties object.  A repository object of the TcxEditRepository class maintains a collection of repository items.


TcxEditRepositoryRichItem Hierarchy
Hierarchy

TComponent

     |

TcxEditRepositoryItem

     |


Properties for TcxEditRepositoryRichItem
TcxEditRepositoryRichItem Properties

TcxEditRepositoryRichItem          Legend

In TcxEditRepositoryRichItem

Properties

Derived from TcxEditRepositoryItem

Properties

Repository


Methods for TcxEditRepositoryRichItem
TcxEditRepositoryRichItem Methods

TcxEditRepositoryRichItem          Legend

Derived from TcxEditRepositoryItem

Create

Destroy

GetBaseName


TcxEditRepositoryRichItem.Properties

TcxEditRepositoryRichItem

Defines settings specific to an appropriate editor.

property Properties: TcxRichEditProperties;

Description

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


cxFontNameComboBox Unit Overview
cxFontNameComboBox Unit

Classes

TcxCustomFontNameComboBox

TcxCustomFontNameComboBoxProperties

TcxFontNameComboBox

TcxFontNameComboBoxProperties

TcxFontPreview

TcxMRUFontNameItem

TcxMRUFontNameItems

Other Types

TcxMRUFontNameAction


TcxCustomFontNameComboBox
TcxCustomFontNameComboBox Object

Hierarchy          Properties          Methods          Events          See Also

The base class for combo box controls that contain a list of fonts.

Unit

cxFontNameComboBox

TcxCustomFontNameComboBox = class(TcxCustomComboBox)

Description

The TcxCustomFontNameComboBox represents a combo box control capable of displaying fonts.  The font name combo box control supports a preview area, where the selected font is displayed.  The preview areas features are controlled by the TcxFontPreview class. The TcxFontPreview.Visible property is used to show and hide the preview area. The TcxFontPreview.ShowButtons property toggles the visibility of style-formatting buttons.

Another feature is the most recently used (MRU) font list.  This list is displayed within a special control area known as the hot-pick area.  The fonts displayed in this hot-pick area are controlled by the TcxMRUFontNameItems collection. Use the MaxMRUFonts property of the TcxFontNameComboBox to specify the maximum number of fonts displayed in this area. Various font name combo box settings can be accessed by the Properties member.

Do not create instances of the TcxCustomFontNameComboBox class in your applications.  If you need a font name combo box, use the TcxFontNameComboBox control.  The TcxCustomFontNameComboBox class, in turn, can be used to derive other font name combo box controls.


TcxCustomFontNameComboBox Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomComboBox

     |


Properties for TcxCustomFontNameComboBox
TcxCustomFontNameComboBox Properties

TcxCustomFontNameComboBox          Legend

In TcxCustomFontNameComboBox

ActiveProperties

ItemIndex

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxCustomFontNameComboBox
TcxCustomFontNameComboBox Methods

TcxCustomFontNameComboBox          Legend

In TcxCustomFontNameComboBox

AddMRUFontName

DelMRUFontName

Derived from TcxCustomComboBox

CanDropDown

Derived from TcxCustomDropDownEdit

CanDropDown

CloseUp

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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit


Events for TcxCustomFontNameComboBox
TcxCustomFontNameComboBox Events

TcxCustomFontNameComboBox          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCustomFontNameComboBox.ActiveProperties

TcxCustomFontNameComboBox          See Also

Obtains the properties that are currently applied to an editor.

property ActiveProperties: TcxCustomFontNameComboBoxProperties;

Description

Use the ActiveProperties property to obtain the properties of the current editor that are currently in effect.  This property is especially useful when the 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 editor.  Otherwise, the inherent editor’s properties are returned.

ReadOnly Property


TcxCustomFontNameComboBox.ItemIndex

TcxCustomFontNameComboBox          See Also

Specifies the index of the selected font within the font list.

property ItemIndex: Integer;

Description

Use the ItemIndex property to specify the zero-based index of the selected item within the font list which is accessible via the FontItems property.  You can change the ItemIndex value in order to navigate the font list. If the font name combo box contains the list of MRU fonts, then the index is assigned to the first item within the MRU list.


TcxCustomFontNameComboBox.Properties

TcxCustomFontNameComboBox

Provides access to the control’s base attributes.

property Properties: TcxCustomFontNameComboBoxProperties;

Description

Use Properties property to access the attributes specific to the font name combo box.  The Properties property provides:

•	enabling/disabling the FontPreview feature (see the Properties.FontPreview property description);

•	managing font types displayed within the list (see the Properties.FontTypes property description);

•	setting the position of font icons (see the Properties.ShowFontTypeIcon property description);

•	management of the MRU font list (see the Properties.MaxMRUFonts and Properties.MRUFontNames properties description).


TcxCustomFontNameComboBox.AddMRUFontName

TcxCustomFontNameComboBox          See Also

Adds a new entry in the MRU font list.

function AddMRUFontName(const AFontName: TFontName): TcxMRUFontNameAction;

Description

Use the AddMRUFontName method to add a new name of the font into the MRU font list. If successful, the new item appears at the top of the control’s MRU font list area.  If the Properties.MaxMRUFonts property value is 0 (there are no MRU fonts within the list), then this method does nothing.

The name of a font is added to the MRU font list when a user selects the font within the combo box.  If the font’s name already exists in the MRU list, then the selected name is placed at the top of the MRU list.  The same happens when the MRU list is populated completely (the number of fonts within it has reached the MaxMRUFonts property value) and a user selects another font within the combo box.

Parameter	Meaning
AFontName	The name of the font to add to the MRU font list.

The return value of this method is a TcxMRUFontNameAction enumerator value.  See the enumerator description for details.  Successful execution of this method raises the OnAddedMRUFont event.

The following code demonstrates adding Arial into the MRU list:

//Delphi

cxFontNameComboBox.AddMRUFontName('Arial');

Result of code execution is demonstrated below:

Before the AddMRUFontName method call	After the AddMRUFontName method call


TcxCustomFontNameComboBox.DelMRUFontName

TcxCustomFontNameComboBox          See Also

Removes an item from the MRU font list.

function DelMRUFontName(const AFontName: TFontName): TcxMRUFontNameAction;

Description

Use the DelMRUFontName method to remove the name of a font from the MRU font list. If successful, the font item disappears from the control’s MRU font list area.  If the Properties.MaxMRUFonts property value is 0 (there are no MRU fonts within the list), this method does nothing.

Parameter	Meaning
AFontName	The name of the font to remove.

The return value of this method is a TcxMRUFontNameAction enumerator value.  See the enumerator description for details.

Successful execution of this method raises the OnDeletedMRUFont event.


TcxCustomFontNameComboBoxProperties
TcxCustomFontNameComboBoxProperties Object

Hierarchy          Properties          Methods          Events

Contains attributes specific to the font name combo box.

Unit

cxFontNameComboBox

TcxCustomFontNameComboBoxProperties = class(TcxCustomComboBoxProperties)

Description

TcxCustomFontNameComboBoxProperties holds settings specific to the font name combo box.  These settings can be accessed using the Properties member and this provides:

•	enabling/disabling the FontPreview feature (see the Properties.FontPreview description);

•	managing the font types displayed within the list (see Properties.FontTypes);

•	setting up the position of font icons (see Properties.ShowFontTypeIcon);

•	managing the MRU font list (see Properties.MaxMRUFonts and Properties.MRUFontNames);

•	access to the names of the fonts loaded to the font name combo box (see Properties.FontItems).


TcxCustomFontNameComboBoxProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |

TcxCustomDropDownEditProperties

     |

TcxCustomComboBoxProperties

     |


Properties for TcxCustomFontNameComboBoxProperties
TcxCustomFontNameComboBoxProperties Properties

TcxCustomFontNameComboBoxProperties          Legend

In TcxCustomFontNameComboBoxProperties

LoadFontComplete

FontItems

FontPreview

FontTypes

MaxMRUFonts

MRUFontNames

ShowFontTypeIcon

UseOwnFont

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

IncrementalSearch

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 TcxCustomFontNameComboBoxProperties
TcxCustomFontNameComboBoxProperties Methods

TcxCustomFontNameComboBoxProperties          Legend

In TcxCustomFontNameComboBoxProperties

LoadFontNames

Derived from TcxCustomMaskEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults


Events for TcxCustomFontNameComboBoxProperties
TcxCustomFontNameComboBoxProperties Events

TcxCustomFontNameComboBoxProperties          Legend

In TcxCustomFontNameComboBoxProperties

OnAddedMRUFont

OnDeletedMRUFont

OnLoadFontComplete

OnMovedMRUFont

Derived from TcxCustomComboBoxProperties

OnDrawItem

OnMeasureItem

Derived from TcxCustomDropDownEditProperties

OnCloseQuery

OnCloseUp

OnInitPopup

OnPopup

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomFontNameComboBoxProperties.FontPreview

TcxCustomFontNameComboBoxProperties          See Also

Contains settings for the font preview.

property FontPreview: TcxFontPreview;

Description

The FontPreview property provides access to font preview settings.  The preview area displays the selected font automatically, thus helping the user to choose the most appropriate font.  The following image shows the preview section highlighted by a red border:

The Preview property allows:

•	enabling/disabling the font preview (see the TcxFontPreview.Visible description);

•	display of font style buttons and visibility of the end ellipsis (TcxFontPreview.ShowButtons and TcxFontPreview.ShowEndEllipsis);

•	alignment, color and style of the preview font (TcxFontPreview.Alignment, TcxFontPreview.Color and TcxFontPreview.FontStyle);

•	preview type and text (TcxFontPreview.PreviewType and TcxFontPreview.PreviewText).


TcxCustomFontNameComboBoxProperties.FontItems

TcxCustomFontNameComboBoxProperties          See Also

Provides access to the font list displayed within the font name combo box.

property FontItems: TStrings;

Description

Use the FontItems property to programmatically access the list of font names displayed within the font name combo box.  The list is updated every time the LoadFontNames procedure loads fonts into the TcxFontNameComboBox control.

ReadOnly Property


TcxCustomFontNameComboBoxProperties.FontTypes

TcxCustomFontNameComboBoxProperties

Specifies the types of font displayed within the font name combo box.

type

  TcxFontType = (cxftTTF, cxftRaster, cxftDevice, cxftFixed, cxftSymbol);

  TcxFontTypes = set of TcxFontType;

property FontTypes: TcxFontTypes;

Description

Use the FontTypes property if you wish to include/exclude specific types from displaying within the font name combo box.  By default, all font types are enabled, including TTF, raster, device, fixed and symbol.

The list of available values is given below:

Option	Effect
cxftTTF	Enables and disables True Type fonts (e.g. Arial, Times New Roman, Courier).
cxftFixed	Enables and disables fixed fonts (e.g. Terminal, FixedSys).
cxftSymbol	Enables and disables symbol fonts (e.g. WebDings, Windings, etc.).
cxftRaster	Enables and disables raster fonts (e.g. MS Sans Serif, Smallfonts, etc.).
cxftDevice	Enables and disables device dependant fonts (e.g. fonts, supplied with a peripheral device – printer, scanner, fax, etc.).

The example below shows how to force the control to display only names of True Type Fonts:

cxFontNameComboBox1.Properties.FontTypes := [cxftTTF];

If you wish, for example, to exclude raster fonts from the list, use following code:

cxFontNameComboBox1.Properties.FontTypes := cxFontNameComboBox1.Properties.FontTypes - [cxftRaster];

The default value of the FontTypes property is [cxftTTF, cxftRaster, cxftDevice, cxftFixed, cxftSymbol].


TcxCustomFontNameComboBoxProperties.LoadFontComplete

TcxCustomFontNameComboBoxProperties          See Also

Indicates whether the font names have finished loading.

property LoadFontComplete: Boolean;

Description

Use the LoadFontComplete property to determine whether the names of the fonts have finished loading.  Once loading has successfully completed, the FontItems property is populated with the names of the fonts, the LoadFontComplete property is set to True and the OnLoadFontComplete event is fired.  Otherwise, the OnLoadFontComplete event is not fired and the LoadFontComplete property’s value is set to False.

ReadOnly Property


TcxCustomFontNameComboBoxProperties.MaxMRUFonts

TcxCustomFontNameComboBoxProperties          See Also

Specifies the maximum number of fonts that can be displayed within the MRU font list.

property MaxMRUFonts: Byte;

Description

The cxFontNameComboBox control supports a most recently used (MRU) font list.  This list is displayed within a special control region known as the hot-pick area.  The fonts displayed in this hot-pick area are controlled by the TcxMRUFontNameItems collection. Use the MRUFontNames property of the TcxFontNameComboBox to access the MRU font list programmatically.

The MaxMRUFonts property specifies the maximum number of fonts that can be displayed within the MRU font list.  If you wish to disable the MRU area, assign 0 to the MaxMRUFonts property.

MaxMRUFonts is set to 3	MaxMRUFonts is set to 6

A font name is added to the MRU font list when a user selects a font within the combo box.  If this font name already exists in the MRU list, then the selected name is placed at the top of the MRU list.  The same happens when the MRU list is completely populated (the number of fonts within it has reached the MaxMRUFonts property value) and a user selects another font within the combo box.  You can use the AddMRUFont and DelMRUFont methods to manage the MRU font list programmatically.

The default value of the MaxMRUFonts property is 10.


TcxCustomFontNameComboBoxProperties.MRUFontNames

TcxCustomFontNameComboBoxProperties          See Also

Provides access to items in the MRU font list.

property MRUFontNames: TcxMRUFontNameItems;

Description

The MRUFontNames property provides access to the collection of fonts within the MRU font list.  The code below returns the name of the first font in the collection:

ASelectedFont := cxFontNameComboBox1.Properties.MRUFontNames.Items[0].FontName;

The MRU font list (or hot-pick area) is located at the top of the font name combo box but below the font preview (which may be disabled):

A font name is added to the MRU font list when a user selects a font within the combo box.  If the font name already exists in the MRU list, then the selected name is placed at the top of the MRU list.  The same happens when the MRU list is completely populated (the number of fonts within it has reached the MaxMRUFonts property value) and a user selects another font within the combo box.

Use the AddMRUFontName and DelMRUFontName methods to manage the MRU font list programmatically.  Handle the OnAddedMRUFont and OnDeletedMRUFont events as required when adding/removing MRU fonts.

ReadOnly Property


TcxCustomFontNameComboBoxProperties.ShowFontTypeIcon

TcxCustomFontNameComboBoxProperties

Specifies the location of font icons.

type

  TcxShowFontIconType = (ftiShowInCombo, ftiShowInList);

  TcxShowFontIconTypes = set of TcxShowFontIconType;

property ShowFontTypeIcon: TcxShowFontIconTypes;

Description

The cxFontNameComboBox supports various font types: True Type, raster, system, symbol and device-dependant fonts.  Each font type has a corresponding icon.  The ShowFontTypeIcon specifies the location of the font type icons.  These icons can be displayed in dropdown list and/or the selection area.

Property Value	Meaning	Effect
ftiShowInCombo = True ftiShowInList = True	The icons are displayed in the text area and the drop-down list.
ftiShowInCombo = False ftiShowInList = True	The icons are displayed in the drop-down list only.
ftiShowInCombo = True ftiShowInList = False	The icons are displayed within the text area only.
ftiShowInCombo = False ftiShowInList = False	No icons are displayed.

The default value of the ShowFontTypeIcon property is [ftiShowInCombo,ftiShowInList].


TcxCustomFontNameComboBoxProperties.UseOwnFont

TcxCustomFontNameComboBoxProperties

Determines whether dropdown list items are displayed using the font name they display.

property UseOwnFont: Boolean;

Description

By default, the fonts within the font name combo box are drawn using the Style.Font settings. Set the UseOwnFont property to True to enable drawing the fonts within the list using their own typeface.

Property Value	Effect
True
False

However, some fonts do not display standard text characters. Such fonts as Windings, Webdings, Symbol and others are shown in the list with their name displayed in the standard font followed by a font sample, as shown by the screenshot below:

The default value of the UseOwnFont property is False.


TcxCustomFontNameComboBoxProperties.LoadFontNames

TcxCustomFontNameComboBoxProperties          Example

Populates the control with font names.

procedure LoadFontNames; virtual;

Description

The LoadFontNames procedure loads font names into the TcxFontNameComboBox control.  Upon successful completing, this procedure populates the FontItems property with the names of the fonts, sets the LoadFontComplete property to True and fires the OnLoadFontComplete event.

You can override the LoadFontNames procedure to implement custom loading of fonts.  For example, you can implement functionality to load fonts from files, streams, XML objects and so on.  See the following example for details.


TcxCustomFontNameComboBoxProperties.OnAddedMRUFont

TcxCustomFontNameComboBoxProperties          See Also

Occurs after adding a font to the MRUFontNames collection.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnAddedMRUFont: TNotifyEvent;

Description

The OnAddedMRUFont event is fired when a font is added to the MRUFontNames collection.  Handle this event if you wish, for instance, to synchronize the MRU lists of two combo boxes (see the example below). This event does not occur if the selected font name is already added to the MRU list.

Use the AddMRUFontName and DelMRUFontName methods to manage the MRU font list programmatically.

The following code handles the OnAddedMRUFont event in order to synchronize the MRU lists of two font name combo boxes:

procedure TForm1.cxFontNameComboBox1PropertiesAddedMRUFont(Sender: TObject);

var

  FontNameComboBoxProperties: TcxFontNameComboBoxProperties;

begin

//obtaining the Properties object, containing the MRUFontNames collection

  FontNameComboBoxProperties := Sender as TcxFontNameComboBoxProperties;

//adding the first item from the MRU list of the major font name combo box

//to the MRU list of the dependant font name combo box

    cxFontNameComboBox2.AddMRUFontName(FontNameComboBoxProperties.MRUFontNames[0].FontName);

end;

After a specific font name is selected within the major font name combo box (the leftmost combo box), that font name appears within the MRU list of the rightmost combo box:

Also the selected font name appears within the MRU list of the dependant font name combo box:


TcxCustomFontNameComboBoxProperties.OnDeletedMRUFont

TcxCustomFontNameComboBoxProperties          See Also

Occurs once a font is removed from the MRUFontNames collection.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnDeletedMRUFont: TNotifyEvent;

Description

The OnDeletedMRUFont event is fired when a font is removed from the MRUFontNames collection.  Handle this event if you wish, for instance, to synchronize the MRU lists of two combo boxes.

Use the AddMRUFontName and DelMRUFontName methods to manage the MRU font list programmatically.


TcxCustomFontNameComboBoxProperties.OnLoadFontComplete

TcxCustomFontNameComboBoxProperties          See Also

Occurs after the font names have been successfully loaded.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnLoadFontComplete: TNotifyEvent;

Description

The OnLoadFontComplete event fires only when the TcxFontNameComboBox control has successfully finished loading the font names.  In this case, the LoadFontComplete property has a value of True, otherwise it has a value of False.

Call the LoadFontNames method to load fonts into the TcxFontNameComboBox control programmatically.


TcxCustomFontNameComboBoxProperties.OnMovedMRUFont

TcxCustomFontNameComboBoxProperties          See Also

Occurs when a font name moves within the MRU font list.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnMovedMRUFont: TNotifyEvent;

Description

The OnMovedMRUFont event fires when a font name moves within the MRU font list.  The MRU font list is populated when a user selects font names with the combo box.  If the selected font name already exists within the MRU font list, then this name is moved to the top of the list.  The OnMovedMRUFont event fires at this precise moment.

Use the AddMRUFontName and DelMRUFontName methods to manage the MRU font list programmatically.


TcxFontNameComboBox
 TcxFontNameComboBox Object

Hierarchy          Properties          Methods          Events

Represents a combo box control containing font names available for selection.

Unit

cxFontNameComboBox

TcxFontNameComboBox = class(TcxCustomFontNameComboBox)

Description

The TcxFontNameComboBox represents a combo box control capable of displaying the fonts available in the system.  TcxFontNameComboBox supports a preview area, where the selected font is displayed with different styles that can be applied to it.  The preview area’s features are controlled by the TcxFontPreview class. The TcxFontPreview.Visible property is used to show and hide the area. The TcxFontPreview.ShowButtons property toggles the visibility of style-formatting buttons.

Another feature available with this control is the most recently used (MRU) font list.  This list is displayed within a special control region known as the hot-pick area.  The fonts displayed in the hot-pick area are controlled by the TcxMRUFontNameItems collection. Use the MaxMRUFonts property of the TcxFontNameComboBox to specify the maximum number of fonts within the hot-pick area. Various font name combo box settings can be accessed by the Properties member.

The following screenshot shows the font name combo box:


TcxFontNameComboBox Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomComboBox

     |

TcxCustomFontNameComboBox

     |


Properties for TcxFontNameComboBox
TcxFontNameComboBox Properties

TcxFontNameComboBox          Legend

Derived from TcxCustomFontNameComboBox

ActiveProperties

ItemIndex

Properties

Derived from TcxCustomComboBox

ActiveProperties

ItemIndex

Properties

Derived from TcxCustomDropDownEdit

ActiveProperties

DroppedDown

PopupWindow

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxFontNameComboBox
TcxFontNameComboBox Methods

TcxFontNameComboBox          Legend

Derived from TcxCustomFontNameComboBox

AddMRUFontName

DelMRUFontName

Derived from TcxCustomComboBox

CanDropDown

Derived from TcxCustomDropDownEdit

CanDropDown

CloseUp

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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit


Events for TcxFontNameComboBox
TcxFontNameComboBox Events

TcxFontNameComboBox          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxFontNameComboBoxProperties
TcxFontNameComboBoxProperties Object

Hierarchy          Properties          Methods          Events

A class that holds TcxFontNameComboBox specific attributes.

Unit

cxFontNameComboBox

TcxFontNameComboBoxProperties = class(TcxCustomFontNameComboBoxProperties)

Description

TcxFontNameComboBoxProperties holds settings specific to the font name combo box and these are accessed by the Properties member providing:

•	enabling/disabling the FontPreview feature (see the Properties.FontPreview description);

•	managing the font types displayed within the list (Properties.FontTypes);

•	position of font icons (Properties.ShowFontTypeIcon);

•	managing the MRU font list (Properties.MaxMRUFonts and Properties.MRUFontNames).

To control any changes made to the editor’s DisplayFormat, EditFormat, MaxLength, MaxValue, MinValue and ReadOnly properties and reverse their values back to the default ones, use the AssignedValues property.


TcxFontNameComboBoxProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |

TcxCustomDropDownEditProperties

     |

TcxCustomComboBoxProperties

     |

TcxCustomFontNameComboBoxProperties

     |


Properties for TcxFontNameComboBoxProperties
TcxFontNameComboBoxProperties Properties

TcxFontNameComboBoxProperties          Legend

Derived from TcxCustomFontNameComboBoxProperties

LoadFontComplete

FontItems

FontPreview

FontTypes

MaxMRUFonts

MRUFontNames

ShowFontTypeIcon

UseOwnFont

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

IncrementalSearch

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 TcxFontNameComboBoxProperties
TcxFontNameComboBoxProperties Methods

TcxFontNameComboBoxProperties          Legend

Derived from TcxCustomFontNameComboBoxProperties

LoadFontNames

Derived from TcxCustomMaskEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults


Events for TcxFontNameComboBoxProperties
TcxFontNameComboBoxProperties Events

TcxFontNameComboBoxProperties          Legend

Derived from TcxCustomFontNameComboBoxProperties

OnAddedMRUFont

OnDeletedMRUFont

OnLoadFontComplete

OnMovedMRUFont

Derived from TcxCustomComboBoxProperties

OnDrawItem

OnMeasureItem

Derived from TcxCustomDropDownEditProperties

OnCloseQuery

OnCloseUp

OnInitPopup

OnPopup

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxFontPreview
TcxFontPreview Object

Hierarchy          Properties          Events

Contains the preview area’s settings.

Unit

cxFontNameComboBox

TcxFontPreview = class(TPersistent)

Description

The TcxFontPreview object represents the preview area, located at the top of the combo box drop-down list.  The preview area supports optional style buttons, allowing the user to apply bold, italic, underline or strikeout formatting to the selected font. Note: this is to help with selection only, since as its name suggests, the control is for selecting a font name, not a font.

Below is the screenshot of the font name combo box with the preview area highlighted using a red border:

The PreviewType property specifies the type of preview used.  The PreviewText specifies the custom preview string (if the PreviewType property is set to cxfpCustom).  Use the Color property to customize the background color of the preview box. The ShowButtons property can be used to show and hide style-formatting buttons. The TcxFontPreview.Alignment property can be used to specify the alignment of the sample text within the preview box area.


TcxFontPreview Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxFontPreview
TcxFontPreview Properties

TcxFontPreview          Legend

In TcxFontPreview

Alignment

Color

FontStyle

PreviewText

PreviewType

ShowButtons

ShowEndEllipses

Visible

WordWrap


Events for TcxFontPreview
TcxFontPreview Events

TcxFontPreview          Legend

In TcxFontPreview

OnButtonClick


TcxFontPreview.Alignment

TcxFontPreview

Defines the alignment of the preview text within the preview area.

property Alignment: TAlignment;

Description

The Alignment property specifies the alignment of the preview text displayed within the font name combo box.  You may display the text on the left, right or centered. The alignment property can be read and modified at design and at run-time.  The following code changes preview text alignment:

//...

with cxFontNameComboBox1.Properties.FontPreview do

begin

  if Alignment <> taCenter then

    Alignment := taCenter;

end;

//...

The following screenshots show different alignment settings:

Property’s Value	Meaning	Effect
taLeft	Preview text is left aligned.
taCenter	Preview text is centered.
taRight	Preview text is right aligned.

The default value of the Alignment property is taCenter.


TcxFontPreview.Color

TcxFontPreview

Specifies the background color of the preview area.

property Color: TColor;

Description

Use the Color property to change the background color of the control’s preview area.  The following image shows the Properties.Preview.Color property set to clTeal:

The default value of the Color property is clWindow.


TcxFontPreview.FontStyle

TcxFontPreview

Specifies the style of preview section text.

type

  TFontStyle = (fsBold, fsItalic, fsUnderline, fsStrikeOut);

  TFontStyles = set of TFontStyle;

property FontStyle: TFontStyles;

Description

There are four styles that can be applied to preview section text: Bold, Italic, Underline and StrikeOut.  These styles can be applied by pressing the required combination of the preview section buttons:

The FontStyle property allows you to specify the preview section’s text style programmatically.

The default value of the FontStyle property is [].


TcxFontPreview.PreviewText

TcxFontPreview          See Also

Specifies the preview text displayed within the font name combo box.

property PreviewText: TCaption;

Description

When enabled (see the TcxFontPreview.Visible property), the font preview is displayed at the top of the combo box’s dropdown window. The TcxFontPreview.PreviewType property allows you to select the contents of the text displayed within the preview area (full alphabet, font name or custom text, defined by the TcxFontPreview.PreviewText property).

The TcxFontPreview.Alignment property specifies the preview text’s alignment within the preview area.   You can access this property both at design and at run-time. Implement the code similar to the following to change the preview text programmatically:

//...

with cxFontNameComboBox1.Properties.FontPreview do

begin

  if PreviewText = '' then

    PreviewText := '1234567890';

end;

//...

The result of executing this code is shown below:


TcxFontPreview.PreviewType

TcxFontPreview          See Also

Specifies the contents of the font name combo box’s preview area.

type

  TcxFontPreviewType = (cxfpFontName, cxfpCustom, cxfpFullAlphabet);

property PreviewType: TcxFontPreviewType;

Description

The font preview is displayed when it is enabled (see the TcxFontPreview.Visible property). You can use the PreviewType property to select preview text contents.

The following options are supported:

Property’s Value	Meaning	Effect
cxfpFontName	The selected font name is used as the preview string.
cxfpFullAlphabet	The English alphabet is used as the preview string.
cxfpCustom	A custom string as defined by the TcxFontPreview.PreviewText property.

The default value of the PreviewType property is cxfpFontName.


TcxFontPreview.ShowButtons

TcxFontPreview

Determines the visibility of font formatting buttons.

property ShowButtons: Boolean;

Description

The style-formatting buttons, namely Bold, Italic, Underline and Strikeout, can be displayed within the preview area of the font name combo box.  These buttons can be hidden at design or runtime by setting the ShowButtons property to False. Note: font style buttons are used for preview purposes only.

The following screenshots show ShowButtons enabled and disabled:

Property’s Value	Effect
True
False

The default value of the ShowButtons property is True.


TcxFontPreview.ShowEndEllipsises
TcxFontPreview.ShowEndEllipsis

TcxFontPreview          See Also

Determines whether clipped preview text is replaced with an ellipsis.

property ShowEndEllipsis: Boolean;

Description

By default, the font preview text is displayed with the maximum font size, which is allowed by the font name combo box width.   If the combo box width is not enough to fit the entire region of the preview text, then this text is clipped.  Set ShowEndEllipsis to True to display an ellipsis instead of the clipped text.

ShowEndEllipsis is set to False	ShowEndEllipsis is set to True

You can also display long preview text by using the TcxFontPreview.WordWrap property.  Setting this property to True wraps the preview text so it fits within the preview area:

The default value of the ShowEndEllipses property is True.


TcxFontPreview.Visible

TcxFontPreview

Toggles the visibility of the font name combo box’s preview area.

property Visible: Boolean;

Description

The following screenshots show the font name combo box with and without a preview area:

Property’s Value	Effect
True
False

The default value of the Visible property is True.


TcxFontPreview.WordWrap

TcxFontPreview          See Also

Determines whether long text is wrapped within a font name combo box’s preview area.

property WordWrap: Boolean;

Description

When WordWrap is enabled, the preview text is wrapped to fit the preview area.  If the WordWrap property is set to False, then the preview text will be clipped if the font name combo box’s dropdown window width is not wide enough.  Set the TcxFontPreview.ShowEndEllipsis property to True to replace the clipped text with an ellipsis.

The following screenshots show the effect of WordWrap within the preview area:

Property’s Value	Effect
True
False

The default value of the WordWrap property is False.


TcxFontPreview.OnButtonClick

TcxFontPreview

Occurs when the font style button is pressed within the preview section.

type

  TcxFontButtonType = (cxfbtBold, cxfbtItalic, cxfbtUnderline, cxfbtStrikeOut);

  TcxFontButtonClickEvent = procedure(Sender: TObject; ButtonType: TcxFontButtonType) of object;

property OnButtonClick: TcxFontButtonClickEvent;

Description

The OnButtonClick event occurs each time a user presses font style buttons within the preview section.  The pressed button type can be obtained via the ButtonType parameter.


TcxMRUFontNameItem
TcxMRUFontNameItem Object

Hierarchy          Properties

Represents an item in the MRU font list.

Unit

cxFontNameComboBox

TcxMRUFontNameItem = class(TCollectionItem)

Description

The TcxMRUFontNameItem class represents items within the TcxMRUFontNameItems collection.  This collection contains MRU (Most Recently Used) font names.

You can use the MRUFontNames property to access the MRU font list programmatically.


TcxMRUFontNameItem Hierarchy
Hierarchy

TCollectionItem

     |


Properties for TcxMRUFontNameItem
TcxMRUFontNameItem Properties

TcxMRUFontNameItem          Legend

In TcxMRUFontNameItem

Tag


TcxMRUFontNameItem.Tag

TcxMRUFontNameItem

Stores a value associated with the item.

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 items or when you need to have an additional item identification mechanism.


TcxMRUFontNameItems
TcxMRUFontNameItems Object

Hierarchy          Properties          Methods

Represents the MRUFontNames collection.

Unit

cxFontNameComboBox

TcxMRUFontNameItems = class(TOwnedCollection)

Description

The controls based on the TcxCustomFontNameComboBox class contain a hot-pick area where the most recently used font names are displayed.   The MRU font list (or hot-pick area) is located at the top of the font name combo box but below the font preview (which might not be visible):

Use the Properties.MRUFontNames property to access the MRU font list programmatically.  The Properites.MaxMRUFonts specifies the maximum number of font names displayed within the MRU font list.  If this property value is 0, then the MRU list is not populated.

You can use the AddMRUFontName and DelMRUFontName methods to manage the MRU font list programmatically.  Handle the OnAddedMRUFont and OnDeletedMRUFont events to provide additional functionality when adding/removing MRU fonts.


TcxMRUFontNameItems Hierarchy
Hierarchy

TOwnedCollection

     |


Properties for TcxMRUFontNameItems
TcxMRUFontNameItems Properties

TcxMRUFontNameItems          Legend

In TcxMRUFontNameItems

Items


Methods for TcxMRUFontNameItems
TcxMRUFontNameItems Methods

TcxMRUFontNameItems          Legend

In TcxMRUFontNameItems

FindFontName


TcxMRUFontNameItems.Items

TcxMRUFontNameItems

Provides indexed access to MRU fonts.

property Items[Index: Integer]: TcxMRUFontNameItem;

Description

Use the Items property to access individual fonts within the list of MRU fonts.  Each font within this list is represented by a TcxMRUFontNameItem instance.

If the font name combo box contains an MRU font list (the Properties.MaxMRUFonts property value is not 0), then fonts within the combo box are enumerated from the first item within the MRU list.  That means, that if the ItemIndex property is assigned 1 and the MRU font list contains 3 items, the second item within the MRU list is selected, instead of the second combo box item.


TcxMRUFontNameItems.FindFontName

TcxMRUFontNameItems

Searches for the specified font in the TcxMRUFontNameItems collection.

function FindFontName(const AFontName: TFontName): TcxMRUFontNameItem; virtual;

Description

The FindFontName method locates a font with the specified name within the MRU font list of a font name combo box.

Parameter	Meaning
AFontName	The name of the required font.

If successful, then this method returns a TcxMRUFontNameItems collection item representing the required font. Otherwise, nil is returned.


TcxMRUFontNameAction
TcxMRUFontNameAction type

Contains values returned by methods that manage the MRU font list.

Unit

cxFontNameComboBox

type

  TcxMRUFontNameAction = (mfaInvalidFontName, mfaNone, mfaMoved, mfaAdded, mfaDeleted);

Description

The TcxMRUFontNameAction is the enumeration type providing return values for methods managing the MRU list (AddMRUFontName and DelMRUFontName). These methods require a font name parameter and the following return values relate to it:

Option	Meaning
mfaInvalidFontName	There is no font available with this name.  The AddMRUFontName and DelMRUFontName methods do nothing.
mfaNone	The font name is available but is not contained within the MRU list.
mfaMoved	The font name now occupies a different position within the MRU list.  This value is returned when the font name already exists within the MRU list or when the font name is added to a fully populated MRU list.
mfaAdded	The font name was added to the MRU list.  Represents the successful result of the AddMRUFontName method.
mfaDeleted	The font name was deleted from the MRU list.  Represents the successful result of the DelMRUFontName method.


Example: Overriding LoadFontNames procedure

This example demonstrates overriding the default behavior of the cxFontNameComboBox control. By default, it loads the names of all fonts available in the system.  You can implement custom font loading by overriding the LoadFontNames procedure.  The functionality of the cxFontNameComboBox is overridden in this example to so that fonts are loaded from a text file.

Two classes are created – TMyFontNameComboBox and TMyFontNameComboBoxProperties.  The TMyFontNameComboBoxProperties declares a FileName property, specifying the name of the file, containing the font names to load.  The properties class also contains an overridden LoadFontNames procedure.

If the file specified via the FileName property exists, then the font names from this file are loaded into the font name combo box.  Changing of the FileName property forces a call of the LoadFontNames method.  This behavior is implemented in the TMyFontNameComboBoxProperties.SetFileName private method.

The TMyFontNameComboBox class overrides the GetPropertiesClass class function in order to specify the required properties class (TMyFontNameComboBoxProperties).

//Delphi

type

//The TMyFontNameComboBoxProperties class contains the FileName property

//declaration and the overriden LoadFontNames procedure

  TMyFontNameComboBoxProperties = class(TcxFontNameComboBoxProperties)

  private

    FFileName: string;

    procedure SetFileName(Value: string);

  public

    property FileName: string read FFileName write SetFileName;

    procedure LoadFontNames; override;

  end;

//The TMyFontNameComboBox class contains the overridden GetPropertiesClass class function

  TMyFontNameComboBox = class(TcxFontNameComboBox)

  public

    class function GetPropertiesClass: TcxCustomEditPropertiesClass; override;

  end;

implementation

{ TMyFontNameComboBoxProperties }

//The following method loads the names of the fonts from a text file

procedure TMyFontNameComboBoxProperties.LoadFontNames;

begin

//removing existing items from the font name combo box

  Self.Items.Clear;

//if the FileName property specifies the name of an existing file, then this

//file’s contents are loaded into the Items property of the font name combo box

  if FileExists(FFileName) then

    Self.Items.LoadFromFile(FFileName)

  else Exit;

end;

//The following method changes the FileName property value

procedure TMyFontNameComboBoxProperties.SetFileName(Value: string);

begin

  if FFileName <> Value then

  begin

//the new value is assigned to the FileName property

    FFileName := Value;

//and the LoadFontNames method is called to reflect the changing of the font

//names source

    LoadFontNames;

  end;

end;

{ TMyFontNameComboBox }

//The following function returns the class of the properties object associated

//with the editor

class function TMyFontNameComboBox.GetPropertiesClass: TcxCustomEditPropertiesClass;

begin

//The Properties property of the TMyFontNameComboBox object is interpreted as an

//instance of the TMyFontNameComboBoxProperties class

  Result := TMyFontNameComboBoxProperties;

end;

//...

//...

var

  Form1: TForm1;

//MyFontNameCombo object represents the TMyFontNameComboBox object

  MyFontNameCombo: TMyFontNameComboBox;

//...

procedure TForm1.FormCreate(Sender: TObject);

begin

//creating TMyFontNameComboBox control

  MyFontNameCombo := TMyFontNameComboBox.Create(Self);

  MyFontNameCombo.Parent := Self;

//setting the FileName property of the created control. Fonts in the specified

//file are automatically loaded into the font name combo box

  TMyFontNameComboBoxProperties(MyFontNameCombo.Properties).FileName := 'c:\FontNames.ini';

end;

//...

The FontNames.txt file contains four font names: Arial, Courier, Times New Roman and MS Sans Serif.

The following screenshot demonstrates the generated MyFontNameComboBox object:


cxGroupBox Unit Overview
cxGroupBox Unit

Classes

TcxButtonGroupItem

TcxButtonGroupItems

TcxCustomButtonGroup

TcxCustomButtonGroupProperties

TcxCustomGroupBox

TcxGroupBox


TcxCustomGroupBox
TcxCustomGroupBox Object

Hierarchy          Properties          Methods          Events

Serves as the base for group box controls.

Unit

cxGroupBox

TcxCustomGroupBox = class(TcxControl)

Description

The TcxCustomGroupBox control implements the functionality required by group box controls.  Such controls are used to display related controls within logical groups and to give captions to these groups.

For example, with a form where users provide their personal details and credit card information, you may want to arrange the controls into two groups.  The first group will contain edit fields for personal information while the second contains credit card input fields.  The form can look as displayed below.

The Alignment property allows you to change the position of the group box’s caption.  You can position the caption string at any control edge and specify its alignment within this edge using this property.  Additionally, you can center the caption string within the control’s client area.  This allows you to use TcxCustomGroupBox descendants as panels.  The image below shows an example.

Using TcxCustomGroupBox descendants, you can also customize the background color, the caption style and the group box’s look and feel.  Use the Color, CaptionBkColor, Font and LookAndFeel properties for this purpose.  Note that you can enable XP painting of the control by setting the LookAndFeel.NativeStyle property to True.

Do not create instances of the TcxCustomGroupBox class in applications. Use this class to create custom group box controls.  If you want to add a group box to a form, use the TcxGroupBox control.  This control is derived from the TcxCustomGroupBox.  It doesn’t provide any new functionality but simply publishes properties.


TcxCustomGroupBox Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |


Properties for TcxCustomGroupBox
TcxCustomGroupBox Properties

TcxCustomGroupBox          Legend

In TcxCustomGroupBox

Alignment

CaptionBkColor

Derived from TcxCustomEdit

ActiveProperties

AutoSize

DataBinding

EditModified

EditValue

InnerEdit

ModifiedAfterEnter

Properties

RepositoryItem

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Transparent

Derived from TcxControl

BorderStyle

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxCustomGroupBox
TcxCustomGroupBox Methods

TcxCustomGroupBox          Legend

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCustomGroupBox
TcxCustomGroupBox Events

TcxCustomGroupBox          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCustomGroupBox.Alignment

TcxCustomGroupBox

Specifies the caption text position.

type

  TcxCaptionAlignment = (alTopLeft, alTopCenter, alTopRight, alBottomLeft, alBottomCenter, alBottomRight, alLeftTop, alLeftCenter, alLeftBottom, alRightTop, alRightCenter, alRightBottom, alCenterCenter);

property Alignment: TcxCaptionAlignment;

Description

Use the Alignment property to change the position of the group box’s caption text.  The caption can be placed on any border and aligned within it.  Additionally, the control’s caption can be placed in the center of its client area.  This allows you to use the group box as a substitute for a panel control.

If the group box is painted in XP style (the LookAndFeel.NativeStyle property is set to True), the caption text cannot be placed onto the right or left border and will be displayed on the top border instead.

The table below lists the values available for the Alignment property.

Value	Meaning	Example
alTopLeft	The caption text is placed on the top edge and left aligned.
alTopCenter	The caption text is placed on the top edge and centered.
alTopRight	The caption text is placed on the top edge and right aligned.
alBottomLeft	The caption text is placed on the bottom edge and left aligned.
alBottomCenter	The caption text is placed on the bottom edge and centered.
alBottomRight	The caption text is placed on the bottom edge and right aligned.
alLeftTop	The caption text is placed on the left edge and aligned to the top.
alLeftCenter	The caption text is placed on the left edge and centered.
alLeftBottom	The caption text is placed on the left edge and aligned to the bottom.
alRightTop	The caption text is placed on the right edge and aligned to the top.
alRightCenter	The caption text is aligned on the right edge and centered.
alRightBottom	The caption text is placed on the right edge and aligned to the bottom.
alCenterCenter	The caption text is centered within the client area of the control. Note that all borders now correspond to the edges of the control, thus making it suitable for use as a panel.

The default value of the Alignment property is alTopLeft.


TcxCustomGroupBox.CaptionBkColor

TcxCustomGroupBox

Specifies the background color of the caption text.

property CaptionBkColor: TColor;

Description

Use the CaptionBkColor property to change the background color of the caption text.  The color of the actual text is controlled by the Font.Color property. You can also change the color of the control’s client area using the Color property.  The image below shows an example of modifying these properties.

When the group box is painted in XP style (the LookAndFeel.NativeStyle property is set to True), you cannot change these settings, as the caption text colors are then controlled by the current XP theme.

The default value of the CaptionBkColor property is clBtnFace.


TcxGroupBox
TcxGroupBox Object

Hierarchy          Properties          Methods          Events

Represents the group box control.

Unit

cxGroupBox

TcxGroupBox = class(TcxCustomGroupBox)

Description

Use the TcxGroupBox control to place a group box onto the form.  The control provides features such as caption text position and alignment, background color and XP painting.  Note that you can also use this control as a panel.  To do this, center the caption within the control’s client area by setting the control’s Alignment property to alCenterCenter.

The TcxGroupBox control is a TcxCustomGroupBox descendant.  It doesn’t introduce any new functionality but simply publishes properties.  Please refer to the TcxCustomGroupBox class description for more details on the features provided by the group box.


TcxGroupBox Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomGroupBox

     |


Properties for TcxGroupBox
TcxGroupBox Properties

TcxGroupBox          Legend

Derived from TcxCustomGroupBox

Alignment

CaptionBkColor

Derived from TcxCustomEdit

ActiveProperties

AutoSize

DataBinding

EditModified

EditValue

InnerEdit

ModifiedAfterEnter

Properties

RepositoryItem

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Transparent

Derived from TcxControl

BorderStyle

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TControl

Align


Methods for TcxGroupBox
TcxGroupBox Methods

TcxGroupBox          Legend

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxGroupBox
TcxGroupBox Events

TcxGroupBox          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


cxHeader Unit Overview
cxHeader Unit

Classes

TcxCustomHeader

TcxHeader

TcxHeaderSection

TcxHeaderSections


TcxCustomHeader
TcxCustomHeader Object

Hierarchy          Properties          Methods          Events

Represents the base class for tabulated header descendants such as TcxHeader.

Unit

cxHeader

TcxCustomHeader = class(TcxControl)

Description

The TcxCustomHeader class represents the base class for controls providing tabulated headers. It implements the basic functionality of a header control.  Do not create instances of TcxCustomHeader. If you need an advanced tabulated header on your form, use the TcxHeader class, which is derived from TcxCustomHeader.


TcxCustomHeader Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |


Properties for TcxCustomHeader
TcxCustomHeader Properties

TcxCustomHeader          Legend

In TcxCustomHeader

AllowSort

DragReorder

Images

ResizeUpdate

Sections

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

Derived from TWinControl

BorderWidth

Derived from TControl

Align

Anchors

BiDiMode

Constraints

DragCursor

DragKind

DragMode

Enabled


Methods for TcxCustomHeader
TcxCustomHeader Methods

TcxCustomHeader          Legend

In TcxCustomHeader

FlipChildren

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCustomHeader
TcxCustomHeader Events

TcxCustomHeader          Legend

In TcxCustomHeader

OnDrawSection

OnSectionChange

OnSectionChangedSortOrder

OnSectionChangingSortOrder

OnSectionClick

OnSectionDrag

OnSectionEndDrag

OnSectionEndResize

OnSectionResize

OnSectionTrack


TcxCustomHeader.AllowSort

TcxCustomHeader          See Also

Specifies whether end-users can change the section’s sort order.

property AllowSort: Boolean;

Description

The TcxHeader control allows end-users to specify the sort order of the header’s sections.  If the AllowSort property is set to True, then an end-user can change the sort order of an individual section by clicking on it.  Otherwise, the sort order is left unchanged.  Setting the AllowSort property to False prevents the OnSectionChangingSortOrder and OnSectionChangedSortOrder events from being raised and also resets the sorting options for all the sections within the header (their SortOrder properties are set to soNone).

The default value of the AllowSort property is True.


TcxCustomHeader.DragReorder

TcxCustomHeader          See Also

Determines the ability to initiate drag-and-drop operations on the header.

property DragReorder: Boolean;

Description

The TcxHeader control allows the end-user to change the order of the header’s sections using drag-and-drop operations.  If the DragReorder property value is True, then an end-user may change section order by clicking a section and dragging it to the required position.

The default value of the DragReorder property is False.


TcxCustomHeader.Images

TcxCustomHeader          See also

Specifies the images list used to display small images within header sections.

property Images: TCustomImageList;

Description

The Images property specifies the TCustomImagesList object and this contains the images for display within the header’s sections.  To assign images to the sections, open the Sections editor and edit each item’s TcxHeaderSection.ImageIndex property.  If no image is required for a section, set the property value to –1 (the default).

The following screenshot shows the header control containing two sections displaying custom images:


TcxCustomHeader.ResizeUpdate

TcxCustomHeader          See Also

Specifies the behavior of the header when a section is being resized.

property ResizeStyle: Boolean;

Description

By default, end-users can resize a section by clicking and dragging its vertical edge unless the width of the section is determined automatically (when the AutoSize is set to True).  The header’s behavior as the edge is being dragged is controlled by the ResizeUpdate property’s value.  If True, the section is resized as its vertical edge is dragged.  Otherwise, the section is only resized when its vertical edge is dropped and a pattern bar marks its position until this occurs.

Note:	When the ResizeUpdate property is set to False the OnSectionTrack event is not raised and OnSectionEndResize event is fired once resizing is complete.  When the ResizeUpdate property is set to True, the OnSectionEndResize and the OnSectionTrack events are fired every time the section resizes.

The default value of the ResizeUpdate property is True.


TcxCustomHeader.Sections

TcxCustomHeader          See Also

Provides access to the header’s collection of sections.

property Sections: TcxHeaderSections;

Description

The Sections property provides access to the header’s sections collection. This collection is represented by the TcxHeaderSections object and each item within it is an instance of the TcxHeaderSection class.  The following code demonstrates adding a section to the header control and setting that section up:

//Delphi

with cxHeader.Sections.Add do

begin

  Text := 'First Section';

  SortOrder := soAscending;

  AllowClick := False;

end;


TcxCustomHeader.FlipChildren

TcxCustomHeader

Changes the order in which sections are displayed.

procedure FlipChildren(AllLevels: Boolean); override;

Description

Use the FlipChildren method to reverse the order of the sections. The following screenshots show the cxHeader control before and after FlipChildren execution:

Before FlipChildren execution	After FlipChildren execution


TcxCustomHeader.OnDrawSection

TcxCustomHeader

Occurs when it is necessary to draw/redraw a header section.

type

  TcxCustomDrawSectionEvent = procedure(HeaderControl: TcxCustomHeader; Section: TcxHeaderSection; const ARect: TRect; Pressed: Boolean) of object;

property OnDrawSection: TcxCustomDrawSectionEvent;

Description

The OnDrawSection event occurs before a section of the TcxHeader control is redrawn. Handle the OnDrawSection event if you wish to override the section’s default painting.

Parameter	Meaning
Sender	The header control which fired the event
Section	The header section to be painted
ARect	A rectangle object defining the position and the size of the section’s drawing rectangle
Pressed	True, if the section is being clicked, False – in other cases.

Example

This example implements custom painting of the cxHeader control by handling the OnDrawSection event. Note: the cxGraphics unit needs to be added to your uses clause.

//Delphi

procedure TForm1.cxHeader1DrawSection(HeaderControl: TcxCustomHeader;

  Section: TcxHeaderSection; const ARect: TRect; Pressed: Boolean);

begin

  if Pressed then

  begin

    HeaderControl.Canvas.Brush.Color := clBlue;

    HeaderControl.Canvas.Font.Color := clYellow;

    HeaderControl.Canvas.Font.Style := [fsBold];

  end else

  begin

    HeaderControl.Canvas.Brush.Color := clNavy;

    HeaderControl.Canvas.Font.Color := clWhite;

    HeaderControl.Canvas.Font.Style := [];

  end;

  HeaderControl.Canvas.FillRect(ARect);

  HeaderControl.Canvas.DrawTexT(Section.Text, ARect, cxAlignHCenter or cxAlignVCenter);

end;

The following images show the result of executing this code:

Header control is in normal state	First section of the header control is clicked


TcxCustomHeader.OnSectionChange

TcxCustomHeader

Occurs after changes to a specific header section have been applied.

type

  TNotifyEvent = procedure (Sender: TObject) of object;

property OnSectionChange: TNotifyEvent;

Description

The OnSectionChange event occurs after a user performs actions which affect the visualization of a specific header section.


TcxCustomHeader.OnSectionChangedSortOrder

TcxCustomHeader          See Also

Occurs after the sort order has been changed for a header section.

type

  TcxSectionChangedSortOrderEvent = procedure(Sender: TObject; const Section: TcxHeaderSection; const ASortOrder: TcxHeaderSortOrder) of object;

property OnSectionChangedSortOrder: TcxSectionChangedSortOrderEvent;

Description

The OnSectionChangedSortOrder event occurs after a user changes the sort order for one of the header control sections. A user can change sort order for a section by clicking it.  Handle this event if you wish to do something after the order has changed.

Parameter	Meaning
Sender	The header control which fired the event
Section	The section whose sort order has changed
ASortOrder	New sort order applied. Can take the following values: • soNone - no sort order is applied; • soAscending - ascending sort order is enabled; • soDescending - descending sort order is enabled.

If you need to do something before the sort order changes, see the OnSectionChangingSortOrder event.


TcxCustomHeader.OnSectionChangingSortOrder

TcxCustomHeader          See Also

Occurs before the sort order is changed.

type

  TcxSectionChangingSortOrderEvent = procedure(Sender: TObject; const Section: TcxHeaderSection; const AOldSortOrder: TcxHeaderSortOrder; var ANewSortOrder: TcxHeaderSortOrder; var AllowChange: Boolean) of object;

property OnSectionChangingSortOrder: TcxSectionChangingSortOrderEvent;

Description

The OnSectionChangedSortOrder event occurs before the user changes the sort order of the header control.  A user can change the sorting order for a section by clicking it.  Handle this event if you wish to reject the order change or need to do something before it changes. For example, you may wish to reject the currently applied sorting mode.

Parameter	Meaning
Sender	The header control, which fired the event.
Section	A section whose sort order has changed.
AOldSortOrder	Previous sort order. Can take the following values: • soNone - no sort order is applied; • soAscending - ascending sort order is enabled; • soDescending - descending sort order is enabled.
ANewSortOrder	New sort order applied. Can take the following values: • soNone - no sort order is applied; • soAscending - ascending sort order is enabled; • soDescending - descending sort order is enabled.
AllowChange	True if new sort order settings are accepted; False if you wish to revert to the previous sort order.
If you need to do something after the sort order has changed, see the OnSectionChangingSortOrder event.


TcxCustomHeader.OnSectionClick

TcxCustomHeader          See Also

Occurs when a user clicks on a header section area.

type

  TcxCustomSectionNotifyEvent = procedure(HeaderControl: TcxCustomHeader; Section: TcxHeaderSection) of object;

property OnSectionClick: TcxCustomSectionNotifyEvent;

Description

The OnSectionClick event occurs when the user clicks on the header control’s section area.  Handle this event if you wish to respond to user clicks.  The event’s parameters identify the HeaderControl and the header Section where clicking occurs.


TcxCustomHeader.OnSectionDrag

TcxCustomHeader          See Also

Occurs when a user drags a section.

type

  TcxSectionDragEvent = procedure(Sender: TObject; FromSection, ToSection: TcxHeaderSection; var AllowDrag: Boolean) of object;

property OnSectionDrag: TcxSectionDragEvent;

Description

The OnSectionDrag event occurs when the user drags a section of the cxHeader control.

Parameter	Meaning
Sender	A TcxHeader object that fired the event.
FromSection	A header control section involved in the drag-and-drop operation.
ToSection	A header control section representing the destination point of the drag-and-drop operation.
AllowDrag	True, if dragging is allowed; False, if dragging is disabled.  This parameter can be used to restrict drag-and-drop operations (see the example below).

If you want to react after the drag-and-drop operation was successfully completed, handle the OnSectionEndDrag event.

The following code shows an OnSectionDrag event handler preventing drag-and-drop when the destination is the header control section with an ID property value of 3:

//Delphi

procedure TForm1.cxHeader1SectionDrag(Sender: TObject; FromSection,

  ToSection: TcxHeaderSection; var AllowDrag: Boolean);

begin

  AllowDrag := ToSection.ID <> 3;

end;


TcxCustomHeader.OnSectionEndDrag

TcxCustomHeader          See Also

Occurs after successful completion of drag-and-drop operations within the header control.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnSectionEndDrag: TNotifyEvent;

Description

The OnSectionEndDrag event occurs after successful completion of drag-and-drop operations within a header control.  If the drag-and-drop operation was not completed, then this event is not fired.  The Sender parameter identifies a TcxHeader control that fired the event.

Handle the OnSectionDrag event to react to section dragging.


TcxCustomHeader.OnSectionResize

TcxCustomHeader          See Also

Occurs when a user resizes a section.

type

  TcxCustomSectionNotifyEvent = procedure(HeaderControl: TcxCustomHeader; Section: TcxHeaderSection) of object;

property OnSectionResize: TcxCustomSectionNotifyEvent;

Description

The OnSectionResize event occurs when a user resizes a header control section by clicking and dragging one of the section’s edges.  Maximum and minimum section width settings can be accessed by the TcxHeaderSection.MaxWidth and TcxHeaderSection.MinWidth properties.

Parameter	Meaning
HeaderControl	The header control, where section resizing occurs.
Section	The resized section.
If a specific section is resized, then the other sections are moved within the header control.  If you want to react during section resizing, handle the OnSectionTrack event.


TcxCustomHeader.OnSectionEndResize

TcxCustomHeader          See Also

Occurs after a header section had been resized.

type

  TcxCustomSectionNotifyEvent = procedure(HeaderControl: TcxCustomHeader; Section: TcxHeaderSection) of object;

property OnSectionEndResize: TcxCustomSectionNotifyEvent;

Description

The OnSectionEndResize event occurs after a section had been resized by clicking and dragging the section’s edge.  Maximum and minimum section width settings can be accessed by the TcxHeaderSection.MaxWidth and TcxHeaderSection.MinWidth properties.

Parameter	Meaning
HeaderControl	The header control, where section resizing occurs.
Section	The resized section.

If you want to react during section resizing, handle the OnSectionTrack event.


TcxCustomHeader.OnSectionTrack

TcxCustomHeader          See Also

Occurs when a user resizes a section with the mouse.

type

  TcxSectionTrackState = (tsTrackBegin, tsTrackMove, tsTrackEnd);

  TcxCustomSectionTrackEvent = procedure(HeaderControl: TcxCustomHeader; Section: TcxHeaderSection; Width: Integer; State: TcxSectionTrackState) of object;

property OnSectionTrack: TcxCustomSectionTrackEvent;

Description

The OnSectionTrack event occurs when a user resizes a section by dragging its edge.  Maximum and minimum section width settings can be accessed by the TcxHeaderSection.MaxWidth and TcxHeaderSection.MinWidth properties.

Parameter	Meaning
HeaderControl	The header control object where section resizing occurs.
Section	The section being resized or has been resized (depending on the State value passed).
Width	The new width of the section.
State	The state of the section. It may take one of the following values: • tsTrackBegin – a user has started dragging the section’s edge; • tsTrackMove – a user is dragging the section’s edge; • tsTrackEnd – a user has finished dragging the section’s edge.

If you want to do something after the section has been resized, handle the OnSectionResize event.


TcxHeader
TcxHeader Object

Hierarchy          Properties          Methods          Events          See Also

Represents a header control.

Unit

cxHeader

TcxHeader = class(TcxCustomHeader)

Description

TcxHeader represents a header object that supports several header sections with borders.  Users may resize the sections and specify the sorting mode for each individual section.  Sections within a header control can be accessed by the Sections property.

TcxHeader publishes various events for responding to header control changes:

•	sorting changes applied to a section;

•	changing the width of a section;

•	clicking on a section;

•	drag-and-drop involving header sections.

The following image shows the cxHeader control embedded within the cxMCListBox control:


TcxHeader Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxCustomHeader

     |


Properties for TcxHeader
TcxHeader Properties

TcxHeader          Legend

Derived from TcxCustomHeader

AllowSort

DragReorder

Images

ResizeUpdate

Sections

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

BorderWidth

Derived from TControl

Align

Anchors

BiDiMode

Color

Constraints

DragCursor

DragKind

DragMode

Enabled

Font

ShowHint

ParentBiDiMode

ParentFont

ParentShowHint

Visible


Methods for TcxHeader
TcxHeader Methods

TcxHeader          Legend

Derived from TcxCustomHeader

FlipChildren

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxHeader
TcxHeader Events

TcxHeader          Legend

Derived from TcxCustomHeader

OnDrawSection

OnSectionChange

OnSectionChangedSortOrder

OnSectionChangingSortOrder

OnSectionClick

OnSectionDrag

OnSectionEndDrag

OnSectionResize

OnSectionEndResize

OnSectionTrack

Derived from TcxControl

OnMouseEnter

OnMouseLeave

Derived from TControl

OnDragDrop

OnDragOver

OnEndDock

OnEndDrag

OnMouseDown

OnMouseMove

OnMouseUp

OnResize

OnStartDock

OnStartDrag


TcxHeaderSection
TcxHeaderSection Object

Hierarchy          Properties          See Also

Represents a single section of the TcxHeader control.

Unit

cxHeader

TcxHeaderSection = class(TCollectionItem)

Description

The TcxHeaderSection object represents a single section of the header control.  Its properties allow you to read and modify a header’s section width, change the text displayed within a section, customize the sort order , etc. Use the Sections property of a header control to access the collection of the header control’s sections.


TcxHeaderSection Hierarchy
Hierarchy

TCollectionItem

     |


Properties for TcxHeaderSection
TcxHeaderSection Properties

TcxHeaderSection          Legend

In TcxHeaderSection

Alignment

AllowClick

AutoSize

ImageIndex

MaxWidth

MinWidth

SortOrder

Text

Width


TcxHeaderSection.Alignment

TcxHeaderSection

Controls the horizontal placement of text within the section.

property Alignment: TAlignment;

Description

Set Alignment to specify how the text of a section is justified within the section. The Alignment property may take one of the following values (see the Status section in the images below):

Value	Meaning	Example
taCenter	Text is centered.
taLeftJustify	Text is aligned to the left side of the section.
taRightJustify	Text is aligned to the right side of the section.

The default value of the Alignment property is taLeftJustify.


TcxHeaderSection.AllowClick

TcxHeaderSection          See Also

Determines whether the section responds to mouse clicks.

property AllowClick: Boolean;

Description

Use the AllowClick property to enable/disable the clicking of header control sections.  If this property value is False, then the OnSectionClick event is not fired.

The default value of the AllowClick property is True.


TcxHeaderSection.AutoSize

TcxHeaderSection

Indicates whether a header section occupies the maximum possible width within the header control.

property AutoSize: Boolean;

Description

By default, header sections are created with default width settings (50 pixels).  If a section has its AutoSize property set to True, then it occupies the maximum available header area:

The First section’s AutoSize property is False	The First section’s AutoSize property is True

If the AutoSize property area is set to True for several sections, then all such sections share the available space.  The following screenshot shows a header control containing three sections.  The AutoSize property value for the First and Third sections is set to True:

Sections with AutoSize set to True are resized simultaneously. The default value of the AutoSize property is False.


TcxHeaderSection.ImageIndex

TcxHeaderSection

Specifies the index of the image associated with the section.

property ImageIndex: TImageIndex;

Description

The ImageIndex property enables you to display an image in the header section.  The TCustomImageList object, providing the images for the sections is identified by the cxHeader.Images property.  The default property value (-1) specifies that a section does not display an image.

The following screenshot shows a header control with an image displayed in its first section:

The default value of the ImageIndex property is -1.


TcxHeaderSection.MaxWidth

TcxHeaderSection          See Also

Specifies the section’s maximum width.

property MaxWidth: Integer;

Description

The MaxWidth property specifies the maximum width (in pixels) of the section.  You can handle the OnSectionResize and OnSectionTrack events to react to changes of header control section widths.

The default value of the MaxWidth property is 1000.


TcxHeaderSection.MinWidth

TcxHeaderSection          See Also

Specifies the section’s minimum width.

property MinWidth: Integer;

Description

The MinWidth property specifies the minimum width (in pixels) of the section.  You can handle the OnSectionResize and OnSectionTrack events to react to changes of header control section widths.

The default value of the MinWidth property is 0.


TcxHeaderSection.SortOrder

TcxHeaderSection          See Also          Example

Specifies the section’s sort order.

type

  TcxHeaderSortOrder = (soNone, soAscending, soDescending);

property SortOrder: TcxHeaderSortOrder;

Description

Use the SortOrder property to specify the sort order for a header control section. When you enable a sort order, a sorting arrow appears inside the TcxHeader control. The SortOrder property has no impact on the data that is displayed in the linked control. This means that you should implement your own sorting routine by handling the OnSectionChangingSortOrder or OnSectionChangedSortOrder events (see the example).

Set the AllowClick property to False to disable sorting for all sections within a header control.

The list of possible values is given below:

Value	Meaning	Example
soNone	No sort order is applied.
soAscending	Ascending sort order is enabled.
soDescending	Descending sort order is enabled.

The default value of the SortOrder property is soNone.


TcxHeaderSection.Text

TcxHeaderSection          See Also

Specifies the text that is displayed within the header’s section.

property Text: string;

Description

The Text property specifies the text label displayed inside a TcxHeader section. When no text is specified, the section is empty unless you specify an image (see the ImageIndex property for details).

Please note that the text displayed inside the header sections may be longer than the available space in the header. In this instance, it will be truncated and replaced with ellipsis.  If you want to prevent this truncation, set the AutoSize property of the header section(s) to True. Also, you may use the MaxWidth , MinWidth and Width properties to adjust section width settings.


TcxHeaderSection.Width

TcxHeaderSection          See Also

Specifies the width of the header section.

property Width: Integer;

Description

The Width property specifies the width of the header section, in pixels. Users may resize a header section causing its Width property to change. Thus you can read the Width property to detect the current width of the relevant header section. Also, Width may be changed when the AutoSize property is True and the section adjusts its size to display a long text label.

The Width property value is limited by the MinWidth and MaxWidth values. You can handle the OnSectionResize and OnSectionTrack events if you want to respond to section width changes.

The default value of the Width property is 50.


TcxHeaderSections
TcxHeaderSections Object

Hierarchy          Properties          Methods          See Also

Represents the header control’s sections collection.

Unit

cxHeader

TcxHeaderSections = class(TCollection)

Description

The TcxHeaderSections object represents the header control’s sections collection. Each item in this collection is an instance of the TcxHeaderSection class.  These class members allow you to specify the text displayed within the section, the section’s sort order and the section’s width limits etc.

Use the TcxHeader.Sections property to access this collection.


TcxHeaderSections Hierarchy
Hierarchy

TCollection

     |


Properties for TcxHeaderSections
TcxHeaderSections Properties

TcxHeaderSections          Legend

In TcxHeaderSections

Items


Methods for TcxHeaderSections
TcxHeaderSections Methods

TcxHeaderSections          Legend

In TcxHeaderSections

 Add

 Insert


TcxHeaderSections.Items

TcxHeaderSections          See Also

Provides indexed access to individual sections of the header control.

property Items[Index: Integer]: TcxHeaderSection;

Description

Use Items to access individual header control sections.  Each section is an instance of the TcxHeaderSection class.  These class members allow you to specify the text displayed within the section, the section’s sort order and the section’s width limits etc.


TcxHeaderSections.Add

TcxHeaderSections          See Also

Adds a new section to the collection.

function Add: TcxHeaderSection;

Description

Use the Add method to add a new section to the Sections collection at run-time. The section is added at the right end of the control with all properties set to default values (no text, sorting is disabled and the section width is 50).


TcxHeaderSections.Insert

TcxHeaderSections

Inserts a new section into the TcxHeaderSections collection.

function Insert(Index: Integer): TcxHeaderSection;

Description

The Insert method inserts a new section into the TcxHeaderSections collection. The items in this collection are displayed as separate sections within the TcxHeader control.  If successful, returns the item added.

Parameter	Meaning
Item	The item you add.
Index	Position of the inserted item.

The following code uses the Insert method:

//Delphi

var

  ASection: TcxHeaderSection;

begin

  ASection := cxHeader1.Sections.Insert(1);

  with ASection do

  begin

    Text := 'Inserted Section';

    ImageIndex := 3;

    AutoSize := True;

  end;

end;

Before inserting the new section	After inserting the new section


TcxHeaderSortOrder
TcxHeaderSortOrder type

Contains sorting modes.

Unit

cxHeader

type

  TcxHeaderSortOrder = (soNone, soAscending, soDescending);

Description

The TcxHeaderSortOrder type defines the sorting modes that can be applied to header control sections. Available values are listed below:

Value	Meaning	Example
soNone	No sort order is applied.
soAscending	Ascending sort order is enabled.
soDescending	Descending sort order is enabled.

Use the SortOrder property to specify the sort mode for a particular header section. Also, you can handle the TcxCustomHeader.OnSectionChangedSortOrder  and TcxCustomHeader.OnSectionChangingSortOrder events to implement advanced sorting.


Example: Sorting applied to the list box control

The following example demonstrates how to implement sorting within the ListBox control by handling TcxHeader control events.  The SortDesc determines the strings order for descending sorting.  AStringList is used to hold list box values.

function SortDesc(List: TStringList; Index1, Index2: Integer): Integer;

begin

  Result := -CompareText(List.Strings[Index1], List.Strings[Index2]);

end;

procedure TForm1.cxHeaderSectionChangedSortOrder(Sender: TObject; const Section: TcxHeaderSection; const ASortOrder: TcxHeaderSortOrder);

var

  AStringList: TStringList;

begin

//creating a TStringList object used to keep list box items from changing    AStringList := TStringList.Create();

  AStringList.Assign(ListBox1.Items);

//if ascending sort order is applied to the header control,

//default sorting algorithm is applied to the list box

  if ASortOrder = soAscending then

    AStringList.Sort

  else

//if descending sort order is applied to the header control,

//the sorting algorithm for the list box is defined by the SortDesc function    if ASortOrder = soDescending then

      AStringList.CustomSort(SortDesc);

//copying item from string list to the list box

  ListBox1.Items.Assign(AStringList);

  AStringLIst.Free;

end;


cxHint Unit Overview
cxHint Unit

Classes

TcxCustomHintStyle

TcxCustomHintStyleController

TcxHintStyleController


TcxCustomHintStyle
TcxCustomHintStyle Object

Hierarchy          Properties

Contains style settings for hints controlled by the TcxHintStyleController component.

Unit

cxHint

TcxCustomHintStyle = class(TPersistent)

Description

You can customize the style of hints controlled by the TcxHintStyleController component using its HintStyle property.  This property returns an object of the TcxCustomHintStyle type.

The TcxCustomHintStyle provides a set of properties that can be divided into several groups.  The first group specifies the shape of the hint.  These are the CallOutPosition, Rounded and RoundRadius properties.  See Animate for AnimationDelay properties which control hint animation effects.  You can also specify the icon to be displayed within hints and its size using the Icon, IconSize and IconType properties.  The CaptionFont and Font properties set the font used to display the hint text.  Finally, the Color and BorderColor properties specify the hint background and border colors.

The image below illustrates some of these settings.

Note: you can switch easily between the standard hint style and custom appearance using the Standard property.  Set it to True to ignore all the above settings and to display standard hints.  If this property value is False, all the properties listed above take effect.


TcxCustomHintStyle Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxCustomHintStyle
TcxCustomHintStyle Properties

TcxCustomHintStyle          Legend

In TcxCustomHintStyle

Animate

AnimationDelay

BorderColor

CallOutPosition

CaptionFont

Color

Font

Icon

IconSize

IconType

Rounded

RoundRadius

Standard


TcxCustomHintStyle.Animate

TcxCustomHintStyle          See Also

Specifies the animation effect used when displaying hints.

type

  TcxHintAnimate = (cxhaSlideLeft, cxhaSlideRight, cxhaSlideUp, cxhaSlideDown, cxhaCenter, cxhaHide, cxhaActivate, cxhaFadeIn, cxhaAuto, cxhaNone);

property Animate: TcxHintAnimate;

Description

The hint controller component provides animation effects. For example, the hint frame can slide from left to right, from top to bottom or fade in. Such effects can add a unique feel to your applications.  However, you may wish to make animation effects optional, since users may find them tiresome after a while.

The Animate property provides the following options:

Value	Meaning
cxhaSlideFromLeft	The hint window slides from left to right.
cxhaSlideFromRight	The hint window slides from right to left.
cxhaSlideDownward	The hint window slides from top to bottom.
cxhaSlideUpward	The hint window slides from bottom to top.
cxhaFromCenter	The hint window slides from the center to the edges.
cxhaHide	Reserved.
cxhaActivate	Reserved.
cxhaFadeIn	The hint window fades in.
cxhaAuto	Hint window appears using the default animation effect.
cxhaNone	No animation effect, the entire hint is displayed immediately.

The speed of animation effects can be controlled using the AnimationDelay property.

The default value of the Animate property is cxhaAuto.


TcxCustomHintStyle.AnimationDelay

TcxCustomHintStyle          See Also

Specifies the speed of animating hints.

type

  TcxHintAnimationDelay = 0..1000;

property AnimationDelay: TcxHintAnimationDelay;

Description

The TcxHintStyleController component lets you animate hints by setting the Animate property to an appropriate value.  The speed of animation is controlled by the AnimationDelay property.  This property specifies the time interval in milliseconds taken to display the hint fully.  Thus, setting the AnimationDelay to a greater value makes the animation slower and vice versa.

Note:	Setting the AnimationDelay property to 1 is equivalent to disabling animation (the same as setting the Animate property value to cxhaNone).  Setting the property to 0 is equivalent to setting it to 100.

The default value of the AnimationDelay property is 100.


TcxCustomHintStyle.BorderColor

TcxCustomHintStyle          See Also

Specifies hint border colors.

property BorderColor: TColor;

Description

Use the BorderColor property if you need to change the color of hint borders.  For instance, you may set the property to the same value as the Color property.  In this case, hints will have no border displayed.

Images below show examples of hints when the BorderColor property is set to clBlack, clGreen and to the same value as the background color.

Note: the BorderColor property is in effect only when the hint uses rounded borders (the Rounded property value is True).  Otherwise, the hint window is rectangular and uses raised borders (painted using system colors).  To use a particular border color with a rectangular hint, set its Rounded property to True and RoundRadius to 0.  The images below show a rectangular hint window using a standard and a custom colored border.

The default value of the BorderColor property is clWindowFrame.


TcxCustomHintStyle.CallOutPosition

TcxCustomHintStyle          See Also

Specifies the position of the hints’ callout.

type

  TcxCallOutPosition = (cxbpNone, cxbpAuto, cxbpLeftBottom, cxbpLeftTop, cxbpTopLeft, cxbpTopRight, cxbpRightBottom, cxbpRightTop, cxbpBottomRight, cxbpBottomLeft);

property CallOutPosition: TcxCallOutPosition;

Description

Use the CallOutPosition property to specify whether the callout area is displayed and its position.  Note that this property also affects where the hint will appear with respect to the mouse cursor position.  Values available for the CallOutPosition property are:

Value	Meaning	Example
cxbpNone	No callout beak is displayed.  The hint’s position, relative to the mouse pointer, is determined automatically.
cxbpAuto	The hint’s position, relative to the mouse cursor, is determined automatically.  The position of the callout beak is displayed in the most appropriate position.
cxbpLeftBottom	The callout beak is displayed at the bottom of the left hint edge.  The hint window appears to the right of the mouse cursor, if possible.
cxbpLeftTop	The callout beak is displayed at the top of the left hint edge.  The hint window appears to the right of the mouse cursor, if possible.
cxbpTopLeft	The callout beak is displayed at the left of the top hint edge.  The hint window appears below the mouse cursor, if possible.
cxbpTopRight	The callout beak is displayed at the right of the top hint edge. The hint window is displayed below the mouse cursor, if possible.
cxbpRightBottom	The callout beak is displayed at the bottom of the right hint edge.  The hint window is displayed to the left of the mouse cursor, if possible.
cxbpRightTop	The callout beak is displayed at the top of the right hint edge.  The hint window is displayed to the left of the mouse cursor, if possible.
cxbpBottomRight	The callout beak is displayed at the right of the bottom hint edge.  The hint window is displayed above the mouse cursor, if possible.
cxbpBottomLeft	The callout beak is displayed at the left of the bottom hint edge.  The hint window is displayed above the mouse cursor, if possible.
The default value of the CallOutPosition property is cxbpNone.


TcxCustomHintStyle.CaptionFont

TcxCustomHintStyle          See Also

Specifies the font of the caption text displayed within hints.

property CaptionFont: TFont;

Description

The TcxHintStyleController component allows you to invoke hints with captions using the ShowHint method.  If you specify any caption as this method’s parameter, the caption will be painted using the font settings specified by the controller’s CaptionFont property.

The font used to paint the hint caption is specified by the CaptionFont property, a standard TFont type and thus can be used to modify the size, color and other font attributes applied to the hint caption.

Images below display examples of specifying different fonts for the hint caption.


TcxCustomHintStyle.Color

TcxCustomHintStyle          See Also

Specifies the background color of the hint window.

property Color: TColor;

Description

Use the Color property if you need to change the background color of the hint window.  The color of the window’s border is specified by the BorderColor property.  Set the two properties to the same value to prevent a border from being displayed.

Images below show hint windows when the Color property is set to different values.


TcxCustomHintStyle.Font

TcxCustomHintStyle          See Also

Specifies the font of the hint’s body text.

property Font: TFont;

Description

Two text blocks can be displayed by hints controlled by the TcxHintStyleController component.  These are the caption text and body text.  The caption text can only be displayed within hints that are invoked using the hint controller’s ShowHint method.  The specified caption’s font settings are set using the CaptionFont property.  The font settings for the rest text (the hint body) are specified using the Font property.

Use the Font property to customize the font settings of hints’ body text.  This property is represented by the TFont object and thus enables you to customize the size, color and other attributes of the font.

The images below show hint windows with different body text fonts.


TcxCustomHintStyle.Icon

TcxCustomHintStyle          See Also

Specifies the icon displayed within hint windows.

property Icon: TIcon;

Description

The TcxHintStyleController component enables you to display icons within hints.  You can choose an icon from the predefined set using the IconType property.  If you need to use a custom icon, set the IconType property to cxhiCustom and specify the desired icon using the Icon property.  If the IconType property is set to any other value, the Icon property value is ignored.

You can also modify the size of displayed icons.  Use the IconSize property for this purpose.

If you don’t need to display icons within hints, set the IconType property to cxhiNone.


TcxCustomHintStyle.IconSize

TcxCustomHintStyle          See Also

Specifies the size of icons displayed within hints.

type

  TcxHintIconSize = (cxisDefault, cxisLarge, cxisSmall);

property IconSize: TcxHintIconSize;

Description

The IconType property enables you to specify the icon that will be displayed within hints.  You can choose one of the predefined icons or set the property to cxhiCustom so that hints use the custom icon specified by the Icon property.

The IconSize property can be used to adjust the size of icons.  The following values are available for this property.

Value	Meaning
cxisDefault	The icon is drawn at its original size.  If the IconType property specifies one of the predefined icons (such as the error or warning icon), 32x32 will be applied.  If the IconType property is set to cxhiCustom so that the icon is provided by the Icon property, the icon will be displayed at its original size.
cxisLarge	The icon is displayed at 32x32.  If an icon’s actual size is 16x16, the icon will be expanded.  Note that the system provides standard icons of both sizes.  Thus, when using system icons, you don’t need to worry about loss of quality.
cxisSmall	The icon is displayed at 16x16.  If an icon’s actual size is 32x32, the icon will be shrunk.

It is recommended that you use cxisDefault when using custom icons.  If one of the system icons is used, set the IconSize property to either cxisLarge or cxisSmall as required.

The images below show hints displaying the standard information icon when the IconSize property is set to cxisSmall and cxisLarge respectively.

The default value of the IconSize property is cxisDefault.


TcxCustomHintStyle.IconType

TcxCustomHintStyle          See Also

Specifies which icon is displayed within hints.

type

  TcxHintIconType = (cxhiNone, cxhiApplication, cxhiInformation, cxhiWarning, cxhiError, cxhiQuestion, cxhiWinLogo, cxhiCurrentApplication, cxhiCustom);

property IconType: TcxHintIconType;

Description

Use the IconType property to specify the icon to be displayed within hints.  The following values are available for this property:

Value	Meaning	Examples (for Windows XP)
cxhiNone	No icon is displayed.
cxhiApplication	The application icon is displayed.
cxhiInformation	The information icon is displayed.
cxhiWarning	The warning icon is displayed.
cxhiError	The error icon is displayed.
cxhiQuestion	The question icon is displayed.
cxhiWinLogo	The Windows logo icon is displayed.
cxhiCurrentApplication	The current application’s icon is displayed.
cxhiCustom	The displayed icon is specified by the Icon property.

The size of displayed icons can be changed using the IconSize property.

The default value of the IconType property is cxhiNone.


TcxCustomHintStyle.Rounded

TcxCustomHintStyle          See Also

Specifies whether hint windows use rounded corners.

property Rounded: Boolean;

Description

Hints controlled by the TcxHintStyleController component support rounded corners.  To enable this feature, you need to set the Rounded property to True and possibly set the RoundRadius property value as well.

The images below show the hint window when the Rounded property is set to False and True respectively.

Note:  When Rounded is set to True, you can change the hint’s border color using the BorderColor property.  Also, you can set the RoundRadius property to 0 to make the hint rectangular.  This allows you to use custom colored borders for rectangular hints.

The default value of the Rounded property is False.


TcxCustomHintStyle.RoundRadius

TcxCustomHintStyle          See Also

Specifies the radius of the rounded corners.

property RoundRadius: Integer;

Description

If the Rounded property value is True, hints controlled by the TcxHintStyleController component use rounded corners.  The radius of these corners is specified by the RoundRadius property.  If this property is set to 0, the hint window is rectangular.  Assigning greater values to this property makes corners smoother.

The images below show the same hint when the RoundRadius property is set to 0, 5 and 15.

Please take into account that increasing the RoundRadius property increases the actual size of the hint frame.

The default value of the RoundRadius property is 11.


TcxCustomHintStyle.Standard

TcxCustomHintStyle

Specifies whether visual effects provided by the TcxHintStyleController component should be used.

property Standard: Boolean;

Description

The TcxHintStyleController component provides a number of visual effects for hints.  You can display icons within hints, customize the background color and text font, change the shape of the hint window, etc. (Please refer to the TcxCustomHintStyle object description for the overall description of the visual effects provided).  The Standard property must be set to False to enable all the visual effects.  Setting this property to True disables all effects.

The Standard property is useful if you want to make visual effects optional.  It allows you to toggle the use of visual effects by a single line of code.  Also note that when effects are disabled and re-enabled, all previous settings are preserved.

The default value of the Standard property is False.


TcxCustomHintStyleController
TcxCustomHintStyleController Object

Hierarchy          Properties          Methods          Events

Serves as the base for components controlling the appearance and behavior of hints within the application.

Unit

cxHint

TcxCustomHintStyleController = class(TComponent)

Description

The TcxCustomHintStyleController class implements the functionality required by its descendant – the TcxHintStyleController component.  This descendant is used to control the appearance and behavior of hints in the application or form (the Global property value specifies what it controls).  Once the component is placed on a form, its properties affect all hints within the application or form.  Please refer to the TcxHintStyleController class description for details.

Do not create instances of TcxCustomHintStyleController class.  If you need a hint style controller in your application, place the TcxHintStyleController component on a form.  The TcxCustomHintStyleController can be used to derive other hint style controllers.


TcxCustomHintStyleController Hierarchy
Hierarchy

TComponent

     |


Properties for TcxCustomHintStyleController
TcxCustomHintStyleController Properties

TcxCustomHintStyleController          Legend

In TcxCustomHintStyleController

Global

HintHidePause

HintPause

HintShortPause

HintStyle

HintWindow


Methods for TcxCustomHintStyleController
TcxCustomHintStyleController Methods

TcxCustomHintStyleController          Legend

In TcxCustomHintStyleController

ShowHint

HideHint


Events for TcxCustomHintStyleController
TcxCustomHintStyleController Events

TcxCustomHintStyleController          Legend

In TcxCustomHintStyleController

OnHintStyleChanged

OnShowHint

OnShowHintEx


TcxCustomHintStyleController.Global

TcxCustomHintStyleController

Specifies whether the current hint controller’s style has a global effect within an application.

property Global: Boolean;

Description

Whenever an active hint style controller with the Global property set to True is present within an application, each control that shows its hints uses this hint style controller’s style unless another (which is called "local") hint style controller is defined within the form.  When neither a global hint style controller (within the application) or a local hint style controller (within the form) is present, the standard hint style is used.  Set the Global property to True to designate the current hint style controller as global.  Doing so also renders the existing (if any) global hint style controller as local.  There can be only one global hint style controller at a time.

Note:	The first hint style controller created automatically assumes the global role.


TcxCustomHintStyleController.HintHidePause

TcxCustomHintStyleController          See Also

Specifies the time interval during which the hint is displayed.

property HintHidePause: Integer;

Description

The HintHidePause property specifies the interval in milliseconds between the time when the hint appears and before it is hidden.  This assumes that the mouse pointer stays within the control displaying the hint.  If the mouse pointer leaves the control area, the hint is hidden immediately.

When you assign a value to the HintHidePause property, it is actually passed to the application’s HintHidePause property.

Please refer to the Hints Time Intervals topic for additional information.

The default value of the HintHidePause property is 2500.


TcxCustomHintStyleController.HintPause

TcxCustomHintStyleController          See Also

Specifies the time interval before the hint is displayed.

property HintPause: Integer;

Description

The HintPause property specifies the interval, in milliseconds, between the time when the mouse pointer enters the control’s area and when the hint is displayed.  If you need hints to be displayed immediately, set this property to 0.

Note that if the mouse pointer leaves the control’s area before this time has elapsed, the hint is not displayed at all.

When you assign a value to the HintPause property, it is actually passed to the application’s  HintPause property.

Please refer to the Hints Time Intervals topic for additional information.

The default value of the HintPause property is 500.


TcxCustomHintStyleController.HintShortPause

TcxCustomHintStyleController          See Also

Specifies the time period passed before a hint is displayed if another hint has already been shown.

property HintShortPause: Integer;

Description

Use the HintShortPause property to reduce the flicker when moving the mouse quickly over a set of buttons that all have help hints.  If flicker appears, assign a greater value to this property.  Values are set in milliseconds.

When you assign a value to the HintShortPause property, it is actually assigned to the application’s HintShortPause property.

Please refer to the Hints Time Intervals topic for additional information.

The default value of the HintShortPause property is 50.


TcxCustomHintStyleController.HintStyle

TcxCustomHintStyleController          See Also

Specifies the style of hints in the application.

property HintStyle: TcxCustomHintStyle;

Description

The HintStyle property provides access to the TcxCustomHintStyle object containing hint style settings.  You can apply animation effects to hints, specify their background and border colors, change the shape of the hint window and more.  Please refer to TcxCustomHintStyle class description for details on the settings provided.


TcxCustomHintStyleController.HintWindow

TcxCustomHintStyleController          See Also

Provides access to a hint window.

property HintWindow: TcxCustomHintWindow;

Description

Use the HintWindow.Caption property to modify a hint’s caption in a currently displayed hint window.

ReadOnly Property


TcxCustomHintStyleController.HideHint

TcxCustomHintStyleController

Hides the hint that was previously invoked using the ShowHint method.

procedure HideHint;

Description

Use the HideHint method to hide the hint invoked using the ShowHint method.  If no hint invoked using this method is currently active, the HideHint method does nothing.


TcxCustomHintStyleController.ShowHint

TcxCustomHintStyleController          See Also

Displays a hint at a specified position.

procedure ShowHint(X, Y: Integer; ACaption, AHint: string);

Description

Use the ShowHint method to display a hint on screen.  The X and Y parameters specify the hint’s top-left corner position.  They represent the horizontal and vertical screen coordinates respectively.  The ACaption and AHint parameters specify strings that will be displayed as the hint’s caption and body.  If you don’t need to display a caption, pass an empty string as the ACaption parameter.  To modify the caption of the displayed hint, use the HintWindow.Caption property.

Calling the ShowHint method hides the hint that was invoked previously.  If you need to hide the currently active hint, use the HideHint method.


TcxCustomHintStyleController.OnHintStyleChanged

TcxCustomHintStyleController

Fires when hint style settings have been changed.

type

  TcxHintStyleChangedEvent = procedure(Sender: TObject; AStyle: TcxCustomHintStyle) of object;

property OnHintStyleChanged: TcxHintStyleChangedEvent;

Description

Write a handler for the OnHintStyleChanged event if you need to do something after the hint controller’s style settings changed.  This event fires if any of attributes of the HintStyle property are modified.  Handling this event is useful if you allow end users to alter hint styles and want to provide a common response to property changes.  For instance, you may want to restrict some style attribute combinations.  In this case, you can handle the OnHintStyleChanged event to check whether the combination is allowed and modify the style settings as required.

The Sender parameter specifies the hint controller component that raised the event.  The AStyle parameter contains style settings of the hint controller (its HintStyle property value).


TcxCustomHintStyleController.OnShowHint

TcxCustomHintStyleController

Fires before a hint is displayed.

type

  TcxShowHintEvent = procedure(Sender: TObject; var HintStr: string; var CanShow: Boolean; var HintInfo: THintInfo) of object;

property OnShowHintEx: TcxShowHintEvent;

Description

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


TcxCustomHintStyleController.OnShowHintEx

TcxCustomHintStyleController

Fires before a hint is displayed.

type

  TcxShowHintExEvent = procedure(Sender: TObject; var Caption, HintStr: string; var CanShow: Boolean; var HintInfo: THintInfo) of object;

property OnShowHintEx: TcxShowHintExEvent;

Description

Handle the OnShowHintEx event to control the general appearance and customize the behavior and various appearance aspects of a hint window.

The Sender parameter specifies the hint controller component that raised the event.  To prohibit a hint from appearing, pass False as the CanShow parameter.  Otherwise, a hint will be displayed.  Use the Caption and HintStr parameters to specify the hint’s caption and body.  To customize the appearance and behavior of the hint window, use the HintInfo parameter.  Refer to the description of the THintInfo type for details.


TcxHintStyleController
TcxHintStyleController Object

Hierarchy          Properties          Methods          Events

A component which controls the appearance and behavior of hints in the application or form.

Unit

cxHint

TcxHintStyleController = class(TcxCustomHintStyleController)

Description

The TcxHintStyleController component allows you to provide centralized control over the appearance and behavior of hints in the application or form.  There are two main features provided:

•	The scope for the control is determined by the Global property value;

•	Centralized control over when the hints are shown and hidden (see the HintPause, HintHidePause and HintShortPause property descriptions);

•	Centralized control over the appearance of hints.  Using the component’s HintStyle property, you can apply various fonts to hint contents, change the background and border color of the hint window, display icons within hints, provide animation effects, etc.  Please refer to the TcxCustomHintStyle for a general overview of all the style settings available.

Once the TcxHintStyleController component is placed on a form, it affects all the hints displayed by controls (specified by their Hint property).  Note that the ShowHint property of controls must be set to True so that they display hints when the mouse pointer is over them.

The image below shows an example of a control’s hint when using the TcxHintStyleController component.

The TcxHintStyleController component is derived from the TcxCustomHintStyleController class.  It doesn’t introduce any functionality but simply publishes properties and an event.


TcxHintStyleController Hierarchy
Hierarchy

TComponent

     |

TcxCustomHintStyleController

     |


Properties for TcxHintStyleController
TcxHintStyleController Properties

TcxHintStyleController          Legend

Derived from TcxCustomHintStyleController

Global

HintHidePause

HintPause

HintShortPause

HintStyle

HintWindow


Methods for TcxHintStyleController
TcxHintStyleController Methods

TcxCustomHintStyleController          Legend

Derived from TcxCustomHintStyleController

ShowHint

HideHint


Events for TcxHintStyleController
TcxHintStyleController Events

TcxHintStyleController          Legend

Derived from TcxCustomHintStyleController

OnHintStyleChanged

OnShowHint

OnShowHintEx


Hints Time Intervals

See Also

The TcxHintStyleController component provides several properties that affect time aspects of displaying hints.  This topic covers the relation between these properties.

There are three time intervals of displaying hints whose duration can be customized:

•	The interval between the moment when the mouse pointer enters the control area and when the hint is invoked.  This interval is customized by the HintPause and HintShortPause properties of the TcxHintStyleController component.  The interval specified by the HintPause property is used if the mouse pointer enters the control when no hints are displayed.  The interval specified by the HintShortPause property is used if the mouse pointer enters the control while a hint is displayed for another control.

•	The interval between the hint animation starts and ends.  This interval is controlled by the HintStyle.AnimationDelay property of the component.  Note that if the HintStyle.Animate property is set to cxhaNone, no animation takes place.  The hint is displayed immediately after the previous time interval elapses, in this case.

•	The interval during which the hint is displayed.  It is specified by the HintHidePause property.  Note that if the mouse pointer leaves the control area the hint is hidden regardless of this property value.

The image below illustrates the relation between the properties mentioned.


cxHyperLinkEdit Unit Overview
cxHyperLinkEdit Unit

Classes

TcxCustomHyperLinkEdit

TcxCustomHyperLinkEditProperties

TcxHyperLinkEdit

TcxHyperLinkEditProperties


TcxCustomHyperLinkEdit
TcxCustomHyperLinkEdit Object

Hierarchy          Properties          Methods          Events

Represents the base class for the editors implementing hyperlink functionality.

Unit

cxHyperLinkEdit

TcxCustomHyperLinkEdit = class(TcxCustomTextEdit);

Description

A hyperlink editor allows you to edit textual data and represent it as a hyperlink.  Editor text is displayed underlined and resembles a hyperlink element which can activate the default web-browser on a user's system.  A hyperlink editor also enables you to execute a system command if it can be recognized.

The SingleClick member of the Properties object identifies the behavior of a hyperlink editor.  If SingleClick is True, a user can execute the command typed in the edit box by clicking it with the mouse.  If SingleClick is False, the command is activated when a user double-clicks in the edit box.  An alternative way to execute the command is to press the keystroke, defined by the StartKey member of the Properties object.

The Properties object specifies various settings specific to hyperlink editors.  You can specify the link color and populate the Properties.LookupItems list with values for the auto-completion feature.

Use the Style, StyleDisabled, StyleFocused and StyleHot properties to adjust the look & feel of an editor.  Working with styles is discussed in the TcxCustomEditStyle class topic.

Do not create instances of the TcxCustomHyperLinkEdit class.  Use its descendants such as TcxHyperLinkEdit and TcxDBHyperLinkEdit instead.


TcxCustomHyperLinkEdit Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |


Properties for TcxCustomHyperLinkEdit
TcxCustomHyperLinkEdit Properties

TcxCustomHyperLinkEdit          Legend

In TcxCustomHyperLinkEdit

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxCustomHyperLinkEdit
TcxCustomHyperLinkEdit Methods

TcxCustomHyperLinkEdit          Legend

Derived from TcxCustomTextEdit

Clear

ClearSelection

CopyToClipboard

Create

CutToClipboard

SelectAll

SetSelection

Undo

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

SetSize

ValidateEdit


Events for TcxCustomHyperLinkEdit
TcxCustomHyperLinkEdit Events

TcxCustomHyperLinkEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCustomHyperLinkEdit.ActiveProperties

TcxCustomHyperLinkEdit          See Also

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

property ActiveProperties: TcxCustomHyperLinkEditProperties;

Description

Use the ActiveProperties property to obtain the properties of the current hyperlink editor that are currently in effect.  This property is especially useful when the hyperlink 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 hyperlink editor.  Otherwise, the inherent hyperlink editor’s properties are returned.

ReadOnly Property


TcxCustomHyperLinkEdit.Properties

TcxCustomHyperLinkEdit

Contains settings specific to hyperlink editors.

property Properties: TcxCustomHyperLinkEditProperties;

Description

Use the Properties member to adjust settings specific to hyperlink editors.  It allows you to control the link color, the way a specific link is activated, the shortcut and many other properties.


TcxCustomHyperLinkEditProperties
TcxCustomHyperLinkEditProperties Object

Hierarchy          Properties          Methods          Events

Represents settings specific to hyperlink editors.

Unit

cxHyperLinkEdit

TcxCustomHyperLinkEditProperties = class(TcxCustomTextEditProperties);

Description

The TcxCustomHyperLinkEditProperties class extends the TcxCustomTextEditProperties class with a set of properties that define the link color, edit behavior and shortcut used to activate a hyperlink.

To set settings for hyperlink editors use the editor’s Properties property.

The TcxHyperLinkEditProperties class derives from TcxCustomHyperLinkProperties and publishes necessary properties to access from TcxCustomHyperLinkEdit descendants.


TcxCustomHyperLinkEditProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |


Properties for TcxCustomHyperLinkEditProperties
TcxCustomHyperLinkEditProperties Properties

TcxCustomHyperLinkEditProperties          Legend

In TcxCustomHyperLinkEditProperties

AutoComplete

AutoSelect

LinkColor

Prefix

SingleClick

StartKey

UsePrefix

Derived from TcxCustomTextEditProperties

AssignedValues

CharCase

DisplayFormat

EchoMode

EditFormat

HideCursor

HideSelection

ImeMode

ImeName

IncrementalSearch

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 TcxCustomHyperLinkEditProperties
TcxCustomHyperLinkEditProperties Methods

TcxCustomHyperLinkEditProperties          Legend

Derived from TcxCustomTextEditProperties

IsDisplayValueValid

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue


Events for TcxCustomHyperLinkEditProperties
TcxCustomHyperLinkEditProperties Events

TcxCustomHyperLinkEditProperties          Legend

In TcxCustomHyperLinkEditProperties

OnStartClick

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomHyperLinkEditProperties.AutoComplete

TcxCustomHyperLinkEditProperties

Determines whether the prefix is added to a hyperlink.

property AutoComplete: Boolean;

Description

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


TcxCustomHyperLinkEditProperties.AutoSelect

TcxCustomHyperLinkEditProperties

Determines whether the hyperlink’s text is automatically selected when the hyperlink editor receives focus.

property AutoSelect: Boolean;

Description

Setting the AutoSelect property to True selects the hyperlink’s text when the hyperlink receives focus.

The default value of the AutoSelect property is False.


TcxCustomHyperLinkEditProperties.LinkColor

TcxCustomHyperLinkEditProperties

Specifies the hyperlink’s text color within an editor.

property LinkColor: TColor;

Description

Use the LinkColor property to modify the color of a hyperlink.

The default value of the LinkColor property is clBlue.


TcxCustomHyperLinkEditProperties.Prefix

TcxCustomHyperLinkEditProperties           See Also

Specifies the prefix that precedes a hyperlink’s text value in an editor.

property Prefix: string;

Description

The string specified by the Prefix property is automatically added to the address string as specified by the UsePrefix property.  Naturally, the string represents the protocol name (for instance, ‘http://’) used to connect to the address.

The default value of the Prefix property is specified by the scxSHyperLinkPrefix constant in the resource strings used by ExpressEditors.


TcxCustomHyperLinkEditProperties.SingleClick

TcxCustomHyperLinkEditProperties

Specifies the manner in which a hyperlink is activated.

property SingleClick: Boolean;

Description

If the SingleClick property is set to True, a hyperlink is activated by a single click.  If the SingleClick property is set to False, the hyperlink is activated by a double click.  The StartKey property specifies the keystroke, which also activates the hyperlink command.  You can handle the OnStartClick event generated when a user starts the hyperlink command.  Handling this event prevents your editor from executing the default command.

The default value of the SingleClick property is False.


TcxCustomHyperLinkEditProperties.StartKey

TcxCustomHyperLinkEditProperties

Specifies the shortcut used to activate a hyperlink.

property StartKey: TShortCut;

Description

Use the StartKey property to define the shortcut used to activate a hyperlink.  Pressing this shortcut performs the same action as clicking a hyperlink within an editor.  You can handle the OnStartClick event generated when a user starts the hyperlink command.  Handling this event prevents your editor from executing the default command.

The default value of the StartKey property is Ctrl+Enter.


TcxCustomHyperLinkEditProperties.UsePrefix

TcxCustomHyperLinkEditProperties          See Also

Specifies the manner in which the prefix is added to a hyperlink.

type

  TcxHyperLinkEditUsePrefix = (upAlways, upOnlyOnExecute, upNever);

property UsePrefix: TcxHyperLinkEditUsePrefix;

Description

Use this property to specify when the prefix (the string specified by the Prefix property) is automatically added to the address string.  Naturally, this prefix represents the protocol name (for instance, ‘http://’) used to connect to the address.

All the possible values for the UsePrefix property are listed in the following table.

Value	Meaning
upAlways	The prefix is added when a hyperlink is activated (executed) or validated (when the hyperlink editor loses focus).
upOnlyOnExecute	The prefix is added only when a hyperlink is activated (executed).
upNever	The prefix is not added to a hyperlink.

The default value of the UsePrefix property is upAlways.


TcxCustomHyperLinkEditProperties.OnStartClick

TcxCustomHyperLinkEditProperties

Occurs on hyperlink execution.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnStartClick: TNotifyEvent;

Description

Use the OnStartClick event to associate an action with hyperlink execution.  The command represented by a hyperlink, is executed when clicking or double-clicking the edit box (depending on the SingleClick property) or when pressing the keystroke defined by the StartKey property.  Handling this event prevents your editor from executing the default command.


TcxDBHyperLinkEdit
 TcxDBHyperLinkEdit Object

Hierarchy          Properties          Methods          Events          See Also

Represents a data-aware text editor with the hyperlink functionality.

Unit

cxDBEdit

TcxDBHyperLinkEdit = class(TcxCustomHyperLinkEdit);

Description

The TcxDBHyperLinkEdit control represents a text editor presenting its contents as a hyperlink.  It is similar to the TcxHyperLinkEdit control but enables editing values from dataset fields.  A hyperlink editor allows you to edit textual data and represent it as a hyperlink.  Editor text is displayed underlined and resembles a hyperlink element which can activate the default web-browser on a user's system.  A hyperlink editor also enables you to execute a system command if it can be recognized.

The SingleClick member of the Properties object identifies the behavior of a hyperlink editor.  If SingleClick is True, a user can execute the command typed in the edit box by clicking it with the mouse.  If SingleClick is False, the command is activated when a user double-clicks in the edit box.  An alternative way to execute the command is to press the keystroke defined by the StartKey member of the Properties object

The Properties object specifies various settings specific to hyperlink editors.  You can specify the link color and populate the LookupItems list with values for the auto-completion feature.

Use the Style, StyleDisabled, StyleFocused and StyleHot properties to adjust the look & feel of an editor.  Working with styles is discussed in the TcxCustomEditStyle class topic.

To connect a data-aware control to a dataset set the DataSource and DataField properties of the DataBinding object.


TcxDBHyperLinkEdit Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomHyperLinkEdit

     |


Properties for TcxDBHyperLinkEdit
TcxDBHyperLinkEdit Properties

TcxDBHyperLinkEdit          Legend

In TcxDBHyperLinkEdit

DataBinding

Derived from TcxCustomHyperLinkEdit

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxDBHyperLinkEdit
TcxDBHyperLinkEdit Methods

TcxDBHyperLinkEdit          Legend

Derived from TcxCustomTextEdit

Clear

ClearSelection

CopyToClipboard

Create

CutToClipboard

SelectAll

SetSelection

Undo

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

SetSize

ValidateEdit


Events for TcxDBHyperLinkEdit
TcxDBHyperLinkEdit Events

TcxDBHyperLinkEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxDBHyperLinkEdit.DataBinding

TcxDBHyperLinkEdit

Specifies the connection to a dataset.

property DataBinding: TcxDBTextEditDataBinding;

Description

Use the DataBinding property to access a TcxDBTextEditDataBinding instance via which the connection to the dataset is established.  To allow a TcxDBHyperLinkEdit control to edit a specific field value from the dataset set the DataSource and DataField properties of the DataBinding object.


TcxHyperLinkEdit
 TcxHyperLinkEdit Object

Hierarchy          Properties          Methods          Events          See Also

Represents a text editor with hyperlink functionality.

Unit

cxHyperLinkEdit

TcxHyperLinkEdit = class(TcxCustomHyperLinkEdit);

Description

TcxHyperLinkEdit is an editor that presents its contents as a hyperlink.  A hyperlink editor allows you to edit textual data and represent it as a hyperlink.  Editor text is displayed underlined and resembles a hyperlink element, which can activate the default web-browser on a user's system.  A hyperlink editor also enables you to execute a system command if it can be recognized.  To access the hyperlink command use the Text property.

The SingleClick member of the Properties object identifies the behavior of a hyperlink editor.  If SingleClick is True, a user can execute the command typed in the edit box by clicking it with the mouse.  If SingleClick is False, the command is activated when a user double-clicks in the edit box.  An alternative way to execute the command is to press the keystroke defined by the StartKey member of the Properties object

The Properties object specifies various settings specific to hyperlink editors.  You can specify the link color and populate the LookupItems list with values for the auto-completion feature.

Use the Style, StyleDisabled, StyleFocused and StyleHot properties to adjust the look & feel of an editor.  Working with styles is discussed in the TcxCustomEditStyle class topic.


TcxHyperLinkEdit Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomHyperLinkEdit

     |


Properties for TcxHyperLinkEdit
TcxHyperLinkEdit Properties

TcxHyperLinkEdit          Legend

In TcxHyperLinkEdit

Text

Derived from TcxCustomHyperLinkEdit

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxHyperLinkEdit
TcxHyperLinkEdit Methods

TcxHyperLinkEdit          Legend

Derived from TcxCustomTextEdit

Clear

ClearSelection

CopyToClipboard

Create

CutToClipboard

SelectAll

SetSelection

Undo

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

SetSize

ValidateEdit


Events for TcxHyperLinkEdit
TcxHyperLinkEdit Events

TcxHyperLinkEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxHyperLinkEdit.Text

TcxHyperLinkEdit

Contains the currently displayed text string within an editor.

property Text;

Description

Read the Text property to obtain text within an editor or set it to specify a new string for it.


TcxHyperLinkEditProperties
TcxHyperLinkEditProperties Object

Hierarchy          Properties          Methods          Events

Contains settings specific to hyperlinks editors.

Unit

cxHyperLinkEdit

TcxHyperLinkEditProperties = class(TcxCustomHyperLinkEditProperties);

Description

The TcxHyperLinkEditProperties class does not provide any new functionality but publishes necessary properties and events specific to hyperlink editors (TcxHyperLinkEdit and TcxDBHyperLink controls).  To adjust editor properties use the Propertes member of the corresponding edit control.  To control any changes made to the editor’s DisplayFormat, EditFormat, MaxLength, MaxValue, MinValue and ReadOnly properties and reverse their values back to the default ones, use the AssignedValues property.

The main hyperlink property is SingleClick.  It defines the manner in which a user activates the hyperlink command.  If SingleClick is True, a user needs only a single mouse click to execute the command.  Otherwise, he/she can activate the command by double-clicking the edit box.  An alternative way is to press the shortcut defined by the StartKey property.  When a user activates the hyperlink command, it is recognized by the system and executed.  However, if you handle the OnStartClick event you can interpret user actions as your needs dictate.  In this case the command is not executed by the system.


TcxHyperLinkEditProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomHyperLinkEditProperties

     |


Properties for TcxHyperLinkEditProperties
TcxHyperLinkEditProperties Properties

TcxHyperLinkEditProperties          Legend

Derived from TcxCustomHyperLinkEditProperties

AutoComplete

AutoSelect

LinkColor

Prefix

SingleClick

StartKey

UsePrefix

Derived from TcxCustomTextEditProperties

AssignedValues

CharCase

DisplayFormat

EchoMode

EditFormat

HideCursor

HideSelection

ImeMode

ImeName

IncrementalSearch

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 TcxHyperLinkEditProperties
TcxHyperLinkEditProperties Methods

TcxHyperLinkEditProperties          Legend

Derived from TcxCustomTextEditProperties

IsDisplayValueValid

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue


Events for TcxHyperLinkEditProperties
TcxHyperLinkEditProperties Events

TcxHyperLinkEditProperties          Legend

Derived from TcxCustomHyperLinkEditProperties

OnStartClick

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


cxImage Unit Overview
cxImage Unit

Classes

TcxCustomImage

TcxCustomImageProperties

TcxImage

TcxImageProperties

TcxPopupMenuLayout

Routines

GetGraphicClassByName

GetRegisteredGraphicClasses

RegisterGraphicClass

UnRegisterGraphicClass


TcxCustomImage
TcxCustomImage Object

Hierarchy          Properties          Methods          Events

Represents the base class for the editors displaying images.

Unit

cxImage

TcxCustomImage = class(TcxCustomEdit);

Description

The TcxCustomImage object represents an editor used to display a single image.  The displayed image can be of the following types: JPEG image (.jpg and .jpeg), bitmap (.bmp), icon (.ico) and metafile (.emf and .wmf).

An image can be loaded into an image editor in several ways:

•	by assigning an instance of the TPicture class to the Picture property;

•	by the LoadFromFile method;

•	by the TPicture.LoadFromFile method;

•	by the PasteFromClipboard method;

•	by the image editor popup menu, which provides access to all methods listed above.

The TcxCustomImage class overrides methods for working with the clipboard and provides you with the ability to load & save graphical data to a file.  The Properties property provides access to a set of options which determine the look & feel of an image editor.


TcxCustomImage Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |


Properties for TcxCustomImage
TcxCustomImage Properties

TcxCustomImage          Legend

In TcxCustomImage

ActiveProperties

AutoSize

ClipboardFormat

Picture

Properties

Derived from TcxCustomEdit

ActiveProperties

AutoSize

DataBinding

EditModified

EditValue

InnerEdit

ModifiedAfterEnter

Properties

RepositoryItem

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxCustomImage
TcxCustomImage Methods

TcxCustomImage          Legend

In TcxCustomImage

LoadFromFile

SaveToFile

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCustomImage
TcxCustomImage Events

TcxCustomImage          Legend

In TcxCustomImage

OnGetGraphicClass

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCustomImage.ActiveProperties

TcxCustomImage          See Also

Obtains the properties that are currently applied to an image editor.

property ActiveProperties: TcxCustomImageProperties;

Description

Use the ActiveProperties property to obtain the properties of the current image editor that are currently in effect.  This property is especially useful when the image 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 image editor.  Otherwise, the inherent image editor’s properties are returned.

ReadOnly Property


TcxCustomImage.AutoSize

TcxCustomImage          See Also

Specifies whether an image editor is resized to display its contents entirely.

property AutoSize: Boolean;

Description

Set the AutoSize property to True to specify whether an image editor sizes itself automatically so as to accommodate the entire image.  Otherwise, the image editor is not resized.

The default value of the AutoSize property is False.


TcxCustomImage.Picture

TcxCustomImage

Specifies the image displayed within an image editor.

property Picture: TPicture;

Description

Use the Picture property to specify the image displayed within an image editor.  The TcxCustomImage object can store images of the following types: JPEG image (.jpg and .jpeg), bitmap (.bmp), icon (.ico) and metafile (.emf and .wmf).

An image can be loaded into an image editor in several ways:

•	by assigning an instance of the TPicture class to the Picture property;

•	by the LoadFromFile method;

•	by the TPicture.LoadFromFile method;

•	by the PasteFromClipboard method;

•	by the image editor popup menu.


TcxCustomImage.ClipboardFormat

TcxCustomImage          See Also

Specifies the format in which graphical data is stored within the clipboard.

property ClipboardFormat: {$IFDEF VCL}Word{$ELSE}string{$ENDIF};

Description

Prior to pasting graphical data which is stored in the clipboard to the image editor, its data format is compared with the format specified by the Properties.GraphicClass property.  Graphical data of a custom format (not a bitmap graphic, metafile graphic, icon, JPEG compressed image data) is associated with one of the predefined clipboard formats specified by the ClipboardFormat property.

Some of the possible values of the ClipboardFormat property are listed below.

Value	Meaning
CF_BITMAP	A Windows bitmap graphic.
CF_METAFILEPICT	A Windows metafile graphic.
CF_PICTURE	A TPicture type object.


TcxCustomImage.Properties

TcxCustomImage

Contains settings specific to image editors.

property Properties: TcxCustomImageProperties;

Description

Use the Properties property to specify a set of options specific to image editors.  These settings are stored in the TcxCustomImageEditProperties class.  They determine the image position and size, the popup menu settings, transparency settings etc.


TcxCustomImage.LoadFromFile

TcxCustomImage

Invokes the "Open" dialog.

procedure LoadFromFile;

Description

Use the LoadFromFile method to invoke the "Open" dialog allowing you to specify the image to display within an image editor.  This dialog allows you to load from images matching the file type filter specified via the CustomFilter property.  If this property value is an empty string, the "Open" dialog displays files of all allowed file types (bitmaps, icons and metafiles).


TcxCustomImage.SaveToFile

TcxCustomImage

Invokes the "Save As" dialog.

procedure SaveToFile;

Description

Use the SaveToFile method to invoke the "Save As" dialog, allowing you to save the image displayed within an image editor.  This dialog allows you to save the graphical data displayed within an image editor as an image matching the file type filter specified via the CustomFilter property.  If this property value is an empty string, the "Save As" dialog allows saving to any allowed file type (bitmaps, icons and metafiles).


TcxCustomImage.OnGetGraphicClass

TcxCustomImage

Occurs when the graphic class of the image assigned to an image editor is being determined.

type

  TcxImageEditGraphicClassEvent = procedure(Sender: TObject; APastingFromClipboard: Boolean; var AGraphicClass: TGraphicClass) of object;

property OnGetGraphicClass: TcxImageEditGraphicClassEvent;

Description

Handle the OnGetGraphicClass event to specify the graphic class which describes the graphical data that will be stored within the image editor.  The APastingFromClipboard parameter indicates the condition which the image is assigned for and is equal to True when the image is pasted from the clipboard, and False in all other cases.  The AGraphicClass parameter specifies the graphic class assigned to the image.  This can be a non-registered graphic class (not a bitmap graphic, metafile graphic, icon, JPEG compressed image data).


TcxCustomImageProperties
TcxCustomImageProperties Object

Hierarchy          Properties          Methods          Events

Contains settings specific to image editors.

Unit

cxImage

TcxCustomImageProperties = class(TcxCustomEditProperties);

Description

The TcxCustomImageProperties class represents a set of attributes controlling the behavior of image editors.  Editor properties are set via the Properties member of the corresponding editor.

The TcxCustomImageProperties members allow a user to define the image position and size within an editor, the transparency settings for the editor background, the popup menu configuration, etc.


TcxCustomImageProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |


Properties for TcxCustomImageProperties
TcxCustomImageProperties Properties

TcxCustomImageProperties          Legend

In TcxCustomImageProperties

Caption

Center

CustomFilter

GraphicClass

GraphicClassName

GraphicTransparency

PopupMenuLayout

ShowFocusRect

Stretch

Derived from TcxCustomEditProperties

Alignment

AssignedValues

AutoSelect

BeepOnError

Buttons

ButtonsViewStyle

ClearKey

ClickKey

ImmediatePost

ReadOnly

UseLeftAlignmentOnEditing

UseMouseWheel

ValidateOnEnter


Methods for TcxCustomImageProperties
TcxCustomImageProperties Methods

TcxCustomImageProperties          Legend

In TcxCustomImageProperties

GetGraphicClass

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue


Events for TcxCustomImageProperties
TcxCustomImageProperties Events

TcxCustomImageProperties          Legend

In TcxCustomImageProperties

OnAssignPicture

OnCustomClick

OnGetGraphicClass

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomImageProperties.Caption

TcxCustomImageProperties

Specifies the text displayed within an image editor.

property Caption: string;

Description

Use the Caption property to specify the text displayed within an image editor.  This text is visible only if the image editor contains no image (the Picture property has no assigned image).


TcxCustomImageProperties.Center

TcxCustomImageProperties

Determines whether an image is centered within an editor.

property Center: Boolean;

Description

Use the Center property to determine whether the displayed image is centered within an image editor.

The default value of the Center property is True.


TcxCustomImageProperties.CustomFilter

TcxCustomImageProperties

Specifies the file type filter for the Open and Save As dialogs.

property CustomFilter: string;

Description

Use the CustomFilter property to specify the file type filter applied to the "Open" and "Save As" picture dialogs of an image editor.  A filter string can contain wildcards.

If the CustomFilter property value is an empty string, the image editor dialog displays the files of all allowed types.


TcxCustomImageProperties.GraphicClass

TcxCustomImageProperties          See Also

Specifies the custom graphic class describing the graphical data stored within an editor.

property GraphicClass: TGraphicClass;

Description

Use the GraphicClass property to specify the graphic class describing graphical data stored within an editor. Unlike the GraphicClassName property, this property can be assigned to a non-registered graphic class.


TcxCustomImageProperties.GraphicClassName

TcxCustomImageProperties          See Also

Specifies the name of the custom graphic class describing the graphical data stored within an editor.

property GraphicClassName: string;

Description

Use the GraphicClassName property to specify the name of the custom graphic class describing data stored within an editor.  Unlike the GraphicClass property, this property must be assigned the name of a registered graphic class; Otherwise, it is not in effect.


TcxCustomImageProperties.GraphicTransparency

TcxCustomImageProperties

Specifies the background transparency for an image editor.

type

  TcxImageTransparency = (gtDefault, gtOpaque, gtTransparent);

property GraphicTransparency: TcxImageTransparency;

Description

Use the GraphicTransparency property to specify the background transparency settings for an image editor.

Value	Meaning
gtDefault	Background transparency settings are obtained from the image itself (transparent for metafiles and icons, opaque for bitmaps).
gtOpaque	Background transparency is set to opaque.
gtTransparent	Background transparency is set to transparent.

The default value of the GraphicTransparency property is gtDefault.


TcxCustomImageProperties.PopupMenuLayout

TcxCustomImageProperties

Specifies the popup menu layout.

property PopupMenuLayout: TcxPopupMenuLayout;

Description

The PopupMenuLayout property allows you to determine whether the standard popup menu items are displayed and to define a new custom item.  The custom item caption and glyph image representing that item within the popup menu are defined via the CustomMenuItemCaption and CustomMenuItemGlyph properties.  The custom menu item is displayed at the bottom of the popup menu and is segregated from the standard menu items via a separator line.


TcxCustomImageProperties.ShowFocusRect

TcxCustomImageProperties

Determines whether a focus rectangle is drawn around an image editor when it is focused.

property ShowFocusRect: Boolean;

Description

Use the ShowFocusRect property to determine whether a focus rectangle is drawn around the focused image editor.


TcxCustomImageProperties.Stretch

TcxCustomImageProperties

Determines whether the displayed image is stretched to match the size of an image editor.

property Stretch: Boolean;

Description

Use the Stretch property to determine whether the image displayed within an image editor is stretched or compressed to match the size of the editor’s window.  This property does not affect the size of the icons (.ICO) displayed within the editor.

The default value of the Stretch property is False.


TcxCustomImageProperties.GetGraphicClass

TcxCustomImageProperties

Determines the graphic class of the image assigned to the image editor which is used as the in-place editor.

function GetGraphicClass(AItem: TObject; ARecordIndex: Integer; APastingFromClipboard: Boolean = False): TGraphicClass; virtual;

Description

The GetGraphicClass function determines the graphic class of the graphical data assigned to the image editor which is used as the in-place editor (in a grid control, for example).  The ARecordIndex and AItem parameters represent the data record (its index) and the item in this record (a column or row) for which the image editor is displayed, respectively.  This lets you set a specific graphic class for each data record and item.

Basically, the GetGraphicClass function returns the Properties.GraphicClass property’s value as the result.  When this property is not set, the OnGetGraphicClass event is fired.  Its AGraphicClass parameter is pre-initialized using the APastingFromClipboard parameter’s value that indicates the condition which the image is assigned to the editor for and is equal to True when the image is pasted from the clipboard (in this case the graphic class assumed to be a bitmap graphic), and False in all other cases.

Note:	The resulting graphic class assigned to the image can be a non-registered graphic class (not a bitmap graphic, metafile graphic, icon or JPEG compressed image data).


TcxCustomImageProperties.OnAssignPicture

TcxCustomImageProperties

Occurs when changes are made to the editor contents and new data needs to be saved.

type

  TcxImageAssignPictureEvent = procedure(Sender: TObject; const Picture: TPicture) of object;

property OnAssignPicture: TcxImageAssignPictureEvent;

Description

Write an OnAssignPicture event handler to respond when a user changes the editor contents and new data needs to be saved.


TcxCustomImageProperties.OnCustomClick

TcxCustomImageProperties

Occurs when a user clicks an additional popup menu item.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnCustomClick: TNotifyEvent;

Description

Write an OnCustomClick event handler to respond when a user clicks an additional popup menu item.  This handler can perform custom actions specific to the image editor.


TcxCustomImageProperties.OnGetGraphicClass

TcxCustomImageProperties

Occurs when the graphic class of the image assigned to an image editor, which is used as the in-place editor, is being determined.

type

  TcxImageGraphicClassEvent = procedure(AItem: TObject; ARecordIndex: Integer; APastingFromClipboard: Boolean; var AGraphicClass: TGraphicClass) of object;

property OnGetGraphicClass: TcxImageGraphicClassEvent;

Description

This event is fired whenever the graphic class of the graphical data which is assigned to an image editor is determined, i.e. when the Properties.GraphicClass property's value is not set.  The OnGetGraphicClass event is useful when the editor is used as an in-place editor (in a grid control, for example) and should display graphical data of various types.  You can set a specific graphic class for each data record (represented by its index) and the item in this record (a column or row) for which the image editor is displayed, which are represented by the ARecordIndex and AItem parameters, correspondingly.  The APastingFromClipboard parameter indicates the condition which the image is assigned to the editor for and is equal to True when the image is pasted from the clipboard, and False in all other cases.  The AGraphicClass parameter specifies the graphic class assigned to the image.  This can be a non-registered graphic class (not a bitmap graphic, metafile graphic, icon, JPEG compressed image data).


TcxDBImage
 TcxDBImage Object

Hierarchy          Properties          Methods          Events          See Also

Represents a data-aware image editor.

Unit

cxDBEdit

TcxDBImage = class(TcxCustomImage);

Description

The TcxDBImage control is used to display the image obtained from a data source.  It inherits all its functionality from the TcxCustomImage class.  The TcxDBImage class publishes the DataBinding property providing the connection between your editor and the data source.  This property refers to an instance of the TcxDBEditDataBinding class, whose properties specify the data source to connect to and the data source field displayed within the editor.

The TcxDBImage class provides you with the ability to work with the clipboard and load & save graphical data to a file.  The Properties property provides access to a set of options determining the look & feel of an image editor.


TcxDBImage Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomImage

     |


Properties for TcxDBImage
TcxDBImage Properties

TcxDBImage          Legend

In TcxDBImage

DataBinding

Derived from TcxCustomImage

ActiveProperties

AutoSize

Picture

Properties

Derived from TcxCustomEdit

ActiveProperties

AutoSize

DataBinding

EditModified

EditValue

InnerEdit

ModifiedAfterEnter

Properties

RepositoryItem

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TControl

Align


Methods for TcxDBImage
TcxDBImage Methods

TcxDBImage          Legend

Derived from TcxCustomImage

LoadFromFile

SaveToFile

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxDBImage
TcxDBImage Events

TcxDBImage          Legend

Derived from TcxCustomImage

OnGetGraphicClass

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxDBImage.DataBinding

TcxDBImage

Specifies the object binding an editor to a data source.

property DataBinding: TcxDBEditDataBinding;

Description

Use the DataBinding property to access a TcxDBEditDataBinding instance establishing the connection between an image editor and a data source.  Use the TcxDBEditDataBinding.DataSource and TcxDBEditDataBinding.DataField properties to specify the data source and the data source field whose values are to be displayed within an image editor.

Note:	Make certain that the data source field connected with the image editor contains image data; otherwise, an error may occur.


TcxImage
 TcxImage Object

Hierarchy          Properties          Methods          Events          See Also

Represents an image editor.

Unit

cxImage

TcxImage = class(TcxCustomImage);

Description

The TcxImage object represents an editor used to display a single image.  The displayed image can be of the following types: JPEG image (.jpg and .jpeg), bitmap (.bmp), icon (.ico) and metafile (.emf and .wmf).

An image can be loaded into an image editor in several ways:

•	by assigning an instance of the TPicture class to the Picture property;

•	by the LoadFromFile method;

•	by the TPicture.LoadFromFile method;

•	by the PasteFromClipboard method;

•	by the image editor popup menu, which provides access to all the methods listed above.

The TcxImage class provides you with the ability to work with the clipboard and load & save graphical data to a file.  The Properties property provides access to a set of options determining the look & feel of an image editor.

The following image demonstrates the image editor containing an image:


TcxImage Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomImage

     |


Properties for TcxImage
TcxImage Properties

TcxImage          Legend

Derived from TcxCustomImage

ActiveProperties

AutoSize

Picture

Properties

Derived from TcxCustomEdit

ActiveProperties

AutoSize

DataBinding

EditModified

EditValue

InnerEdit

ModifiedAfterEnter

Properties

RepositoryItem

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TControl

Align


Methods for TcxImage
TcxImage Methods

TcxImage          Legend

Derived from TcxCustomImage

LoadFromFile

SaveToFile

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxImage
TcxImage Events

TcxImage          Legend

Derived from TcxCustomImage

OnGetGraphicClass

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxImageProperties
TcxImageProperties Object

Hierarchy          Properties          Methods          Events

Contains settings specific to image editors.

Unit

cxImage

TcxImageProperties = class(TcxCustomImageProperties);

Description

The TcxImageProperties class does not define any additional functionality other than that defined in the TcxCustomImagProperties class.  It only publishes TcxCustomImageProperties members responsible for the TcxImage functionality.

The TcxImageProperties members allow a user to define the image position and the size within an editor, the transparency settings for the editor background, the popup menu configuration, etc.  To control any changes made to the editor’s ReadOnly property and reverse its value back to the default one, use the AssignedValues property.


TcxImageProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomImageProperties

     |


Properties for TcxImageProperties
TcxImageProperties Properties

TcxImageProperties          Legend

Derived from TcxCustomImageProperties

Caption

Center

CustomFilter

GraphicClass

GraphicClassName

GraphicTransparency

PopupMenuLayout

ShowFocusRect

Stretch

Derived from TcxCustomEditProperties

Alignment

AssignedValues

AutoSelect

BeepOnError

Buttons

ButtonsViewStyle

ClearKey

ClickKey

ImmediatePost

ReadOnly

UseLeftAlignmentOnEditing

UseMouseWheel

ValidateOnEnter


Methods for TcxImageProperties
TcxImageProperties Methods

TcxImageProperties          Legend

Derived from TcxCustomImageProperties

GetGraphicClass

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue


Events for TcxImageProperties
TcxImageProperties Events

TcxImageProperties          Legend

Derived from TcxCustomImageProperties

OnAssignPicture

OnCustomClick

OnGetGraphicClass

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxPopupMenuLayout
TcxPopupMenuLayout Object

Hierarchy          Properties

Defines the popup menu layout settings.

Unit

cxImage

TcxPopupMenuLayout = class(TPersistent);

Description

The TcxPopupMenuLayout object contains the settings determining the popup menu layout.  It allows you to determine whether standard popup menu items are displayed and to define a new custom item.  The custom item caption and glyph image representing that item within the popup menu are defined via the CustomMenuItemCaption and CustomMenuItemGlyph properties.  The custom menu item is displayed at the bottom of the popup menu and is segregated from standard menu items via a separator line.


TcxPopupMenuLayout Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxPopupMenuLayout
TcxPopupMenuLayout Properties

TcxPopupMenuLayout          Legend

In TcxPopupMenuLayout

CustomMenuItemCaption

CustomMenuItemGlyph

MenuItems


TcxPopupMenuLayout.CustomMenuItemCaption

TcxPopupMenuLayout

Specifies the caption of an additional popup menu item.

property CustomMenuItemCaption: string;

Description

Use the CustomMenuItemCaption property to specify the caption of an additional popup menu item.  If this property value is not specified, the appropriate popup menu item is represented by the image defined via the CustomMenuItemGlyph property.


TcxPopupMenuLayout.CustomMenuItemGlyph

TcxPopupMenuLayout

Specifies the glyph image of an additional popup menu item.

property CustomMenuItemGlyph: TBitmap;

Description

Use the CustomMenuItemGlyph property to specify the glyph of an additional popup menu item.  If this property value is not specified, the appropriate popup menu item is represented by the text string defined via the CustomMenuItemCaption property.


TcxPopupMenuLayout.MenuItems

TcxPopupMenuLayout

Specifies which popup menu items are enabled.

type

  TcxPopupMenuItem = (pmiCut, pmiCopy, pmiPaste, pmiDelete, pmiLoad, pmiSave, pmiCustom);

  TcxPopupMenuItems = set of TcxPopupMenuItem;

property MenuItems: TcxPopupMenuItems;

Description

Use the MenuItems property to specify which popup menu items are enabled.  The default property value (see below) enables the standard popup menu items: Cut, Copy, Paste, Delete, Load and Save.  To enable an additional popup menu item set the pmiCustom enumeration member to True.  In this case the additional popup menu item is displayed at the bottom of the popup menu segregated from the other menu items via a separator line.

The default value of the MenuItems property is [pmiCut, pmiCopy, pmiPaste, pmiDelete, pmiLoad, pmiSave].


GetGraphicClassByName

Returns the registered graphic class by its name.

Unit

cxImage

function GetGraphicClassByName(const AClassName: string): TGraphicClass;

Description

Use the GetGraphicClassByName function to obtain the graphic class from the list of registered graphic classes by its class name which is specified by the AClassName parameter.


GetRegisteredGraphicClasses

Returns the list of registered graphic classes.

Unit

cxImage

function GetRegisteredGraphicClasses: TList;

Description

Use the GetRegisteredGraphicClasses function to obtain the list of registered graphic classes.  If a specific class describing graphical data interpretation is registered via the RegisterGraphicClass function, then it can be used by the ExpressQuantumEditors capable of displaying graphic data (BLOB and Image editors).

Use the GetGraphicClassByName to obtain a specific graphic class from the list of registered graphic classes, by its name.


RegisterGraphicClass

Registers a class describing custom graphic data for usage with the ExpressQuantumEditors.

Unit

cxImage

procedure RegisterGraphicClass(AGraphicClass: TGraphicClass);

Description

The ExpressQuantumEditors capable of displaying graphical data initially support the following graphic data formats: icons, bitmaps and windows meta-files.  The list of registered graphic classes is accessible via the GetRegisteredGraphicClasses function.  In order to register a new graphic class, call the RegisterGraphicClass function, which adds the graphic class passed via the AGraphicClass parameter to the list of registered graphic classes.  After a graphic class is registered, you can specify its name via the GraphicClassName or PictureGraphicClassName property value.


UnRegisterGraphicClass

Removes the specified class from the list of registered graphic data classes.

Unit

cxImage

procedure UnRegisterGraphicClass(AGraphicClass: TGraphicClass);

Description

The ExpressQuantumEditors capable of displaying graphical data initially support the following graphic data formats: icons, bitmaps and windows meta-files.  The list of registered graphic classes is accessible via the GetRegisteredGraphicClasses function.  In order to register a new graphic class, call the RegisterGraphicClass function, which adds the graphic class to the list of registered graphic classes.  After a graphic class is registered, you can specify its name as the GraphicClassName or PictureGraphicClassName property value.  The UnRegisterGraphicClass function removes a class specified via the AGraphicClass parameter from the list of registered graphic classes.


cxImageComboBox Unit Overview
cxImageComboBox Unit

Classes

TcxCustomImageComboBox

TcxCustomImageComboBoxProperties

TcxImageComboBox

TcxImageComboBoxItem

TcxImageComboBoxItems

TcxImageComboBoxProperties


TcxCustomImageComboBox
TcxCustomImageComboBox Object

Hierarchy          Properties          Methods          Events

Represents the base class for the editors displaying a list of images and text strings within a dropdown window.

Unit

cxImageComboBox

TcxCustomImageComboBox = class(TcxCustomComboBox);

Description

The TcxCustomImageComboBox class is the base class for the TcxImageComboBox class and for the user-defined classes representing the "image "editors.  These "image" editors contain a list of images with corresponding text descriptions within a dropdown window.  It provides properties and methods defining the basic functionality of image combo box editors.

An image combo box editor enables you to display a list of items within its dropdown window.  The list of items is accessible via the Items collection of the Properties object.  You should use the Items collection to assign every item a unique value via the item’s Value property.  The editor uses item values to distinguish items from each other.  If you do not assign the item’s Value property, the editor will not work properly.

Every item can be associated with an image and a text string displayed in the dropdown window and in the edit box of the control.  The item’s ImageIndex property determines the index of the image associated with the item in the image collections provided by the Properties.Images and Properties.LargeImages lists.  Thus you should populate image collections with images and then assign the required image index to the item’s ImageIndex property.  The item’s Description property specifies the text representing a specific item within an editor.

The EditValue property is related to the item’s Value property of the selected item.  When you select a specific item from the dropdown window, the EditValue property is automatically set to the value of the item’s Value property.  Conversely, by setting the EditValue property you select the corresponding item whose Value property’s value matches EditValue.


TcxCustomImageComboBox Hierarchy
Hierarchy

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomComboBox

     |


Properties for TcxCustomImageComboBox
TcxCustomImageComboBox Properties

TcxCustomImageComboBox          Legend

In TcxCustomImageComboBox

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxCustomImageComboBox
TcxCustomImageComboBox Methods

TcxCustomImageComboBox          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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCustomImageComboBox
TcxCustomImageComboBox Events

TcxCustomImageComboBox          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCustomImageComboBox.ActiveProperties

TcxCustomImageComboBox          See Also

Obtains the properties that are currently applied to an image combo box editor.

property ActiveProperties: TcxCustomImageComboBoxProperties;

Description

Use the ActiveProperties property to obtain the properties of the current image combo box editor that are currently in effect.  This property is especially useful when the image combo box 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 image combo box editor.  Otherwise, the inherent image combo box editor’s properties are returned.

ReadOnly Property


TcxCustomImageComboBox.Properties

TcxCustomImageComboBox

Contains settings specific to image combo box editors.

property Properties: TcxCustomImageComboBoxProperties;

Description

Use the Properties property to specify the ImageComboBox settings.  The Images and LargeImages properties specify the TCustomImageList instances storing the images displayed within the editor’s edit region and dropdown window.  The Image alignment within the editor’s dropdown window is defined via the ImageAlign property.  The MultiLineText property determines whether the text displayed within the editor dropdown is represented in a single or multi line manner.  The ShowDescriptions property indicates whether the text representation of image combo box items is displayed within the editor.


TcxCustomImageComboBoxProperties
TcxCustomImageComboBoxProperties Object

Hierarchy          Properties          Methods          Events

Contains settings specific to image combo box editors.

Unit

cxImageComboBox

TcxCustomImageComboBoxProperties = class(TcxCustomComboBoxProperties);

Description

The TcxCustomImageComboBoxProperties class represents a set of attributes controlling the ImageComboBox behavior.  Properties for an edit control are set via the Properties member of the corresponding editor.

The Images and LargeImages properties specify the TCustomImageList instances storing the images displayed within an editor and its dropdown window.  Images alignment within the editor dropdown is defined via the ImageAlign property.  The MultiLineText property determines whether the text displayed within the editor dropdown is represented in a single or multi line manner.  The ShowDescriptions property indicates whether the text representation of image combo box items is displayed within the editor.


TcxCustomImageComboBoxProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |

TcxCustomDropDownEditProperties

     |

TcxCustomComboBoxProperties

     |


Properties for TcxCustomImageComboBoxProperties
TcxCustomImageComboBoxProperties Properties

TcxCustomImageComboBoxProperties          Legend

In TcxCustomImageComboBoxProperties

DefaultDescription

DefaultImageIndex

ImageAlign

Images

Items

LargeImages

MultiLineText

ShowDescriptions

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

IncrementalSearch

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 TcxCustomImageComboBoxProperties
TcxCustomImageComboBoxProperties Methods

TcxCustomImageComboBoxProperties          Legend

In TcxCustomImageComboBoxProperties

FindItemByValue

Derived from TcxCustomMaskEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults


Events for TcxCustomImageComboBoxProperties
TcxCustomImageComboBoxProperties Events

TcxCustomImageComboBoxProperties          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


TcxCustomImageComboBoxProperties.DefaultDescription

TcxCustomImageComboBoxProperties

Specifies the text displayed within the image combo box when the edit value has no corresponding description within the list of associated items.

property DefaultDescription: string;

Description

Use the DefaultDescription property to specify the text displayed within the image combo box when the edit value has no corresponding description within the list of associated items.  This situation may occur when the image combo box’s EditValue is specified via code and is not represented via a specific item in the dropdown window of the image combo box.

To avoid this situation, ensure that the image combo box’s edit value is equal to the value of the Value property of one of the items within the image combo box.


TcxCustomImageComboBoxProperties.DefaultImageIndex

TcxCustomImageComboBoxProperties

Specifies the index of the default image displayed within the image combo box.

property DefaultImageIndex: TImageIndex;

Description

Use this property to specify the index of the default image displayed within the image combo box. It is used when the edit value has no corresponding image within its associated list of images.  This situation may occur when the image combo box’s EditValue is specified via code and is not represented by any item in the dropdown of the image combo box.

To avoid this situation, ensure that the image combo box’s edit value is equal to the value of the Value property of one of the items within the image combo box.

The default value of the DefaultImageIndex property is -1.


TcxCustomImageComboBoxProperties.ImageAlign

TcxCustomImageComboBoxProperties

Specifies images alignment within the dropdown window of an image combo box.

type

  TcxImageAlign = (iaLeft, iaRight);

property ImageAlign: TcxImageAlign;

Description

Use the ImageAlign property to specify images alignment within the dropdown window of an image combo box.

Value	Meaning
iaLeft	Images are displayed at the left side of the image combo box’s dropdown window.
iaRight	Images are displayed at the right side of the image combo box’s dropdown window.

The default value of the ImageAlign property is iaLeft.


TcxCustomImageComboBoxProperties.Images

TcxCustomImageComboBoxProperties

Specifies a TCustomImageList instance containing images to display within an image combo box.

property Images: TCustomImageList;

Description

Use the Images property to specify a TCustomImageList instance containing the images displayed within an image combo box.  Images from this image list are displayed within the editor’s edit region and, if the LargeImages property is not assigned, within the editor dropdown.


TcxCustomImageComboBoxProperties.Items

TcxCustomImageComboBoxProperties

Specifies the collection of items stored within an image combo box.

property Items: TcxImageComboBoxItems;

Description

Use the Items property to specify the collection of items stored within an image combo box.  Each item is a TcxImageComboBoxItem class instance.  The Description property of a TcxImageComboBoxItem instance specifies the text representing a specific item within an editor.  The ImageIndex property defines the index of the image representing a specific item within this editor.  The Value property specifies the image combo box’s EditValue represented by the image and the text defined by the Description and ImageIndex properties.

Note: Make certain that each image combo box item has a unique value for its Value property; otherwise, items with the same values will not be distinguished from each other.


TcxCustomImageComboBoxProperties.LargeImages

TcxCustomImageComboBoxProperties

Specifies the TCustomImageList instance containing images to display within the dropdown window of an image combo box.

property LargeImages: TCustomImageList;

Description

Use the LargeImages property to specify the TCustomImageList instance containing the images displayed within the dropdown window of an image combo box.  This image list may contain images which are larger than images from the image list specified by the Images property.


TcxCustomImageComboBoxProperties.MultiLineText

TcxCustomImageComboBoxProperties

Determines whether the description text is displayed in a single or multi line manner.

property MultiLineText: Boolean;

Description

Use the MultiLineText property to determine whether item descriptions of the image combo box are displayed in a single or multi line manner.  This property affects only the text displayed within the dropdown window of the image combo box.


TcxCustomImageComboBoxProperties.ShowDescriptions

TcxCustomImageComboBoxProperties

Determines whether item descriptions specified by its Description property are displayed beside the image representing a specific combo box item.

property ShowDescriptions: Boolean;

Description

Use the ShowDescription property to determine whether item descriptions are displayed within the image combo box when the combo box dropdown is closed.  If this property value is False, the image combo box displays only images when its dropdown window is closed.  This property does not affect the descriptions displayed within the dropdown window of the image combo box.

The default value of the ShowDescriptions property is True.


TcxCustomImageComboBoxProperties.FindItemByValue

TcxCustomImageComboBoxProperties

Locates an image combo box item based on the specified ImageComboBox EditValue.

function FindItemByValue(const AValue: Variant): TcxImageComboBoxItem;

Description

Use the FindItemByValue method to locate an image combo box item representing the EditValue property value specified via the AValue parameter.  This method returns a TcxImageComboBoxItem object instance whose Value property value is equal to the AValue parameter.  If such an item does not exist, the FindItemByValue method returns nil.


TcxDBImageComboBox
 TcxDBImageComboBox Object

Hierarchy          Properties          Methods          Events          See Also

Represents a data-aware control used to display a list of images with corresponding text strings.

Unit

cxDBEdit

TcxDBImageComboBox = class(TcxCustomImageComboBox);

Description

The TcxDBImageComboBox object represents a data-aware control displaying a list of images with corresponding text strings.  It inherits its main functionality from the TcxCustomImageComboBox class.

Each image combo box item represents a data source field value.  This value is assigned to the item’s Value property of a TcxImageComboBox class instance, which corresponds to a specific image combo box item.  Said differently, data source field values identify image combo box items.

Note:	Make certain that each image combo box item has a unique value for its Value property; otherwise, items with the same values will not be distinguished from each other.


TcxDBImageComboBox Hierarchy
Hierarchy

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomComboBox

     |

TcxCustomImageComboBox

     |


Properties for TcxDBImageComboBox
TcxDBImageComboBox Properties

TcxDBImageComboBox          Legend

In TcxDBImageComboBox

DataBinding

Derived from TcxCustomImageComboBox

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxDBImageComboBox
TcxDBImageComboBox Methods

TcxDBImageComboBox          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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxDBImageComboBox
TcxDBImageComboBox Events

TcxDBImageComboBox          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxDBImageComboBox.DataBinding

TcxDBImageComboBox

Specifies a data source connection.

property DataBinding: TcxDBEditDataBinding;

Description

Use the DataBinding property to specify the TcxDBEditDataBinding instance used to establish a connection to a data source.  The DataBinding.DataSource property specifies the data source to which to connect. The DataBinding.DataField property specifies the data source field, connected to your editor.  That field can be of any type since the data source field value is assigned to the item’s Value property whose type is Variant.


TcxImageComboBox
 TcxImageComboBox Object

Hierarchy          Properties          Methods          Events          See Also

Represents an editor displaying a list of images and text strings within a dropdown window.

Unit

cxImageComboBox

TcxImageComboBox = class(TcxCustomImageComboBox);

Description

The TcxImageComboBox class represents the editors containing a list of images with corresponding text descriptions within a dropdown window.

Image combo box editors are able to store images from the TCustomImageList object.  Each image from the image list assigned to the Properties.Images or Properties.LargeImages property corresponds to the item displayed within the dropdown window of an image combo box.  The Properties.Items property specifies the collection of items displayed within the image combo box’s editor.  Each item is a TcxImageComboBoxItem class instance.  The Description property of a TcxImageComboBoxItem instance specifies the text representing a specific editor item.  The ImageIndex property defines the index of the image representing a specific item within the editor.  The Value property specifies the image combo box’s EditValue represented by the image and text defined via the Description and ImageIndex properties.

The following image demonstrates the image combo box with the opened dropdown window:


TcxImageComboBox Hierarchy
Hierarchy

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomComboBox

     |

TcxCustomImageComboBox

     |


Properties for TcxImageComboBox
TcxImageComboBox Properties

TcxImageComboBox          Legend

Derived from TcxCustomImageComboBox

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxImageComboBox
TcxImageComboBox Methods

TcxImageComboBox          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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxImageComboBox
TcxImageComboBox Events

TcxImageComboBox          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxImageComboBoxItem
TcxImageComboBoxItem Object

Hierarchy          Properties

Represents an item displayed within the dropdown of an image combo box.

Unit

cxImageComboBox

TcxImageComboBoxItem = class(TCollectionItem);

Description

The TcxImageComboBoxItem object represents an item displayed within an image combo box.  Each image combo box item can be represented by the text and/or image, specified via the Description and ImageIndex properties respectively.   When a user navigates through image combo box items, the Value property values of the TcxImageComboBoxItem object (representing the currently selected item) are assigned to the editor's EditValue property.  If the EditValue property of the image combo box’s editor is assigned a value which has no corresponding image combo box item, the image and the text to display within the image combo box’s editor are specified by the Properties.DefaultImageIndex and Properties.DefaultDescription properties.

Note:	Make certain that each image combo box item has a unique value for its Value property; otherwise, items with the same values will not be distinguished from each other.


TcxImageComboBoxItem Hierarchy
Hierarchy

TCollectionItem

     |


Properties for TcxImageComboBoxItem
TcxImageComboBoxItem Properties

TcxImageComboBoxItem          Legend

In TcxImageComboBoxItem

Description

ImageIndex

Tag

Value


TcxImageComboBoxItem.Description

TcxImageComboBoxItem

Specifies the text representing a specific image combo box item.

property Description: TCaption;

Description

Use the Description property to specify the text used to represent a specific image combo box item.  This text is displayed within the editor dropdown and within the editor itself (if the Properties.ShowDescriptions property is True).


TcxImageComboBoxItem.ImageIndex

TcxImageComboBoxItem

Specifies the index of an image representing a specific image combo box item within an editor.

property ImageIndex: TImageIndex;

Description

Use the ImageIndex property to specify the index of the images, representing a specific image combo box item.  These images are stored within the Properties.Images and Properties.LargeImages image lists.  Two different image combo box items can be assigned the same ImageIndex property value.


TcxImageComboBoxItem.Tag

TcxImageComboBoxItem

Stores a value associated with the item.

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 items or when you need to have an additional item identification mechanism.


TcxImageComboBoxItem.Value

TcxImageComboBoxItem

Specifies the EditValue property value of an editor.

property Value: Variant;

Description

The Value property specifies the EditValue property value of the editor corresponding to the selected image combo box item.  Navigation through image combo box items is implemented by changing the editor’s EditValue property value.  If the EditValue property of the image combo box editor is assigned a value which has no corresponding image combo box item, the image and the text to display within the image combo box editor are specified by the Properties.DefaultImageIndex and Properties.DefaultDescription properties.


TcxImageComboBoxItems
TcxImageComboBoxItems Object

Hierarchy          Properties

Represents a collection of image combo box items.

Unit

cxImageComboBox

TcxImageComboBoxItems = class(TOwnedCollection);

Description

The TcxImageComboBoxItems object represents a collection of the TcxImageComboBoxItem objects corresponding to items of a specific image combo box.


TcxImageComboBoxItems Hierarchy
Hierarchy

TOwnedCollection

     |


Properties for TcxImageComboBoxItems
TcxImageComboBoxItems Properties

TcxImageComboBoxItems          Legend

In TcxImageComboBoxItems

Items


TcxImageComboBoxItems.Items

TcxImageComboBoxItems

Provides indexed access to image combo box items.

property Items[Index: Integer]: TcxImageComboBoxItem;

Description

Use the Items property to access individual items displayed within an image combo box.  The Index parameter value represents the item position within the TcxImageComboBoxItems collection.

This property provides an editor window for customizing the TcxImageComboBoxItems collection at design time.  You can specify the images associated with an item (which are displayed in the image combo box and the dropdown window of the image combo box), the item’s description, value and tag.

The ‘Image’ column in this window displays the image associated with an item (if any) by the item’s ImageIndex property.  The ‘ValueType’ column represents the string representation of the value type to which the string value specified in the ‘Value’ field is converted when the item’s Value property is assigned.  Other columns in this window correspond to the items’ properties and display their values.

The functions which are available within this window are listed in the following table:

Button	Function
Add	Adds a new item as the last item to the TcxImageComboBoxItems collection.  When the image combo box has an image list assigned via the Properties.Images and Properties.LargeImages lists, the image in the list is automatically associated with the new item.  The item’s ImageIndex in this case will correspond to the current item’s index within the collection.  For instance, the first item in the collection with an index of 0 will have its ImageIndex property assigned to 0 and thus the image with this index in the Properties.Images collection will be displayed in the ‘Image’ column.  Since the ImageIndex property's value is determined, sorting (if any) is applied to the items and affects the items’ actual position within the collection.
Insert	Unlike the Add function, this one inserts a new item into the TcxImageComboBoxItems collection at the position specified by the currently selected item, thus moving the selected item and the items that follow it down the collection.  Again, the inserted item’s ImageIndex corresponds to the current item’s index within the collection.  Since the ImageIndex property's value is determined, sorting (if any) is applied for items, which affects the actual items’ positions within the collection.
Delete	Deletes the currently selected item from the TcxImageComboBoxItems collection.
Select All	Selects all items within the TcxImageComboBoxItems collection.
Set ValueType	Use the dropdown list to select and set the value type for selected items.  The value type can be selected for a particular item in the collection by populating the list within the ‘ValueType’ field.
OK	Saves all the items and their properties within the editor window to the control’s item collection and closes the editor window.
Cancel	Discards all the TcxImageComboBoxItems collection’s items‘ modifications within the editor window and closes it.

You can sort items within the editor window by clicking the corresponding column captions.


TcxImageComboBoxProperties
TcxImageComboBoxProperties Object

Hierarchy          Properties          Methods          Events

Contains settings specific to image combo box editors.

Unit

cxImageComboBox

TcxImageComboBoxProperties = class(TcxCustomImageComboBoxProperties);

Description

The TcxImageComboBoxProperties class represents a set of attributes controlling the ImageComboBox behavior.  Properties for an edit control are set by the Properties member of the corresponding editor.  To control any changes made to the editor’s DisplayFormat, EditFormat, MaxLength, MaxValue, MinValue and ReadOnly properties and reverse their values back to the default ones, use the AssignedValues property.

The Images and LargeImages properties specify TCustomImageList instances storing images displayed within the editor and the editor dropdown window.  Image alignment within the editor dropdown window is defined by the ImageAlign property.  The MultiLineText property determines whether the text displayed within the editor dropdown is represented in a single or multi-line manner.  The ShowDescriptions property indicates whether the text representation of image combo box items is displayed within the editor.


TcxImageComboBoxProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |

TcxCustomDropDownEditProperties

     |

TcxCustomComboBoxProperties

     |

TcxCustomImageComboBoxProperties

     |


Properties for TcxImageComboBoxProperties
TcxImageComboBoxProperties Properties

TcxImageComboBoxProperties          Legend

Derived from TcxCustomImageComboBoxProperties

DefaultDescription

DefaultImageIndex

ImageAlign

Images

Items

LargeImages

MultiLineText

ShowDescriptions

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

IncrementalSearch

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 TcxImageComboBoxProperties
TcxImageComboBoxProperties Methods

TcxImageComboBoxProperties          Legend

Derived from TcxCustomImageComboBoxProperties

FindItemByValue

Derived from TcxCustomMaskEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults


Events for TcxImageComboBoxProperties
TcxImageComboBoxProperties Events

TcxImageComboBoxProperties          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


cxLabel Unit Overview
cxLabel Unit

Classes

TcxCustomLabel

TcxCustomLabelProperties

TcxLabel

TcxLabelProperties


TcxCustomLabel
TcxCustomLabel Object

Hierarchy          Properties          Methods          Events

Represents a base class for the TcxLabel and TcxDBLabel objects.

Unit

cxLabel

TcxCustomLabel = class(TcxCustomEdit)

Description

TcxCustomLabel is the base class for the TcxLabel and TcxDBLabel classes.  It implements the basic functionality for these label controls.  The Caption property specifies the text displayed within a label.  The Properties property contains various label settings: caption painting style, drawing effects, caption text rotation angle etc.

Do not create instances of TcxCustomLabel. Use TcxCustomLabel as the base class when declaring label controls. Properties and methods of TcxCustomLabel provide basic behavior that descendant classes inherit as well as behavior that components can override to customize their behavior.


TcxCustomLabel Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |


Properties for TcxCustomLabel
TcxCustomLabel Properties

TcxCustomLabel          Legend

In TcxCustomLabel

ActiveProperties

AutoSize

Caption

FocusControl

Properties

Derived from TcxCustomEdit

ActiveProperties

AutoSize

DataBinding

EditModified

EditValue

InnerEdit

ModifiedAfterEnter

Properties

RepositoryItem

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxCustomLabel
TcxCustomLabel Methods

TcxCustomLabel          Legend

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit


Events for TcxCustomLabel
TcxCustomLabel Events

TcxCustomLabel          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCustomLabel.ActiveProperties

TcxCustomLabel          See Also

Obtains the properties that are currently applied to a label.

property ActiveProperties: TcxCustomLabelProperties;

Description

Use the ActiveProperties property to obtain the properties of the current label that are currently in effect.  This property is especially useful when the label 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 label.  Otherwise, the inherent label’s properties are returned.

ReadOnly Property


TcxCustomLabel.AutoSize

TcxCustomLabel          See Also

Specifies whether a label is resized to display its caption entirely.

property AutoSize: Boolean;

Description

Set the AutoSize property to True to specify whether a label automatically changes its height and width so as to display its caption entirely.  Otherwise, the label is not resized.

The default value of the AutoSize property is True.


TcxCustomLabel.Caption

TcxCustomLabel

Specifies the text displayed within a label.

property Caption: TCaption;

Description

The Caption property specifies the text displayed within a label control.  You can specify a hot key for the label by supplying an ampersand before the desired character within the Caption.  If an end user presses the Alt + hot key combination, then focus goes to the control identified by the label’s FocusControl property.


TcxCustomLabel.FocusControl

TcxCustomLabel          See Also

Designates the windowed control associated with the label.

property FocusControl: TWinControl;

Description

Set FocusControl to the windowed control that should receive focus when an end user presses the accelerator key specified by the label’s Caption property. Specify an accelerator key by preceding a character in the label text with an ampersand (&) and setting the Properties.ShowAccelChar property to True.


TcxCustomLabel.Properties

TcxCustomLabel          See Also

Contains settings specific to label controls.

property Properties: TcxCustomLabelProperties;

Description

Use the Properties property to access the following label properties:

•	text painting effect (see Properties.LabelStyle and Properties.PenWidth for details);

•	3D shadow effect (see Properties.LabelEffect, Properties.Depth and Properties.Orientation);

•	a bitmap for painting the label’s text (see Properties.Glyph for details).

All these properties are declared in the TcxCustomLabelProperties class.


TcxCustomLabelProperties
TcxCustomLabelProperties Object

Hierarchy          Properties          Methods          Events          See Also

Represents settings specific to label controls.

Unit

cxLabel

TcxCustomLabelProperties = class(TcxCustomEditProperties)

Description

The TcxCustomLabelProperties class contains a set of attributes specific for label controls.  The label control’s properties are set via the Properties member.

The label attributes includes:

•	text painting effect (see Properties.LabelStyle and Properties.PenWidth for details);

•	3D shadow effect (see Properties.LabelEffect, Properties.Depth and Properties.Orientation);

•	a bitmap for painting the label’s text (see Properties.Glyph for details).


TcxCustomLabelProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |


Properties for TcxCustomLabelProperties
TcxCustomLabelProperties Properties

TcxCustomLabelProperties          Legend

In TcxCustomLabelProperties

Angle

Depth

Glyph

LabelEffect

LabelStyle

Orientation

PenWidth

ShadowedColor

ShowAccelChar

Transparent

WordWrap

Derived from TcxCustomEditProperties

Alignment

AssignedValues

AutoSelect

BeepOnError

Buttons

ButtonsViewStyle

ClearKey

ClickKey

ImmediatePost

ReadOnly

UseLeftAlignmentOnEditing

UseMouseWheel

ValidateOnEnter


Methods for TcxCustomLabelProperties
TcxCustomLabelProperties Methods

TcxCustomLabelProperties          Legend

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue


Events for TcxCustomLabelProperties
TcxCustomLabelProperties Events

TcxCustomLabelProperties          Legend

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomLabelProperties.Angle

TcxCustomLabelProperties

Specifies the label ‘s rotation angle.

property Angle: Integer;

Description

Use the Angle property to add a rotation effect to the label control. Angle specifies the angle (in degrees) used to rotate the label.  Positive Angle values rotate the label text counter-clockwise, while negative values rotate it clockwise.

Note: only True Type Fonts (TTF) support rotation. If you use other fonts for the label’s Caption, setting the Angle property has no effect.

The following images show different values for the Angle property (with a Glyph image applied to the label):

Value	Meaning	Picture
0 (default)	The label is not rotated.
45	The label is rotated by 45 degrees counter-clockwise.

Note: setting the Angle property to a non-default value removes the painting effect applied by the LabelEffect property.

The default value of the Angle property is 0.


TcxCustomLabelProperties.Depth

TcxCustomLabelProperties          See Also

Specifies the depth of the label’s text shadow.

property Depth: Word;

Description

Use the Depth property to specify the space between the label’s text and text shadow.  When the Depth value is 0, no shadow is visible.

Text shadow appearance is determined by the Properties.LabelEffect property.  Shadow position is provided by the Properties.Orientation property and the shadow color is specified by Properties.ShadowedColor.

The following images show different Depth property settings (Properties.LabelEffect is cxleCool):

Value	Meaning	Picture
0 (default)	No shadow is visible.
5	Shadow depth is 5 pixels.
10	Shadow depth is 10 pixels.

The default value of the Depth property is 0.


TcxCustomLabelProperties.Glyph

TcxCustomLabelProperties

Specifies the image used to draw the label’s Caption.

property Glyph: TBitmap;

Description

Use the Glyph property to specify the bitmap used to draw caption text. When selected, the Glyph image will be used as a texture for the caption text.

The following picture demonstrates a label with an assigned Glyph image:


TcxCustomLabelProperties.LabelEffect

TcxCustomLabelProperties          See Also

Specifies the type of 3D shadow effect applied to a label.

type

  TcxLabelEffect = (cxleNormal, cxleFun, cxleExtrude, cxleCool);

property LabelEffect: TcxLabelEffect;

Description

Use the LabelEffect property to define the type of 3D shadow effect used to draw a label.

Set the Properties.Depth property to a non-zero value to enable the text shadow and to define how deep its shadow will be.  Note that if LabelEffect is set to cxleNormal, the label’s text shadow is not visible.  The Properties.Orientation property controls the direction of the shadow and Properties.ShadowedColor specifies its color.

The list of possible LabelEffect values are as follows:

Value	Meaning	Picture
cxleNormal	No visual effects or shadow is applied.
cxleFun	The shadow has a gradient effect.
cxleExtrude	The shadow uses the ShadowedColor color.
cxleCool	The shadow is visible only at the Depth position.

The default value of the LabelEffect property is cxleNormal.


TcxCustomLabelProperties.LabelStyle

TcxCustomLabelProperties          See Also

Specifies the painting style of the label’s text.

type

  TcxLabelStyle = (cxlsNormal, cxlsRaised, cxlsLowered, cxlsOutLine);

property LabelStyle: TcxLabelStyle;

Description

Use the LabelStyle property to define the painting style of the label’s text.  The list of possible LabelStyle values are as follows:

Value	Meaning	Picture
cxlsNormal	The label is drawn as is without any special effects.
cxlsRaised	The label is drawn using a raised style.
cxlsLowered	The label is drawn in a lowered style.
cxlsOutLine	The label is painted with an outline with its width defined by the Properties.PenWidth property.

The default value of the LabelStyle property is cxlsNormal.


TcxCustomLabelProperties.Orientation

TcxCustomLabelProperties

Specifies the orientation of the label’s text shadow.

type

  TcxLabelOrientation = (cxoLeft, cxoRight, cxoTop, cxoBottom, cxoLeftTop, cxoLeftBottom, cxoRightTop, cxoRightBottom);

property Orientation: TcxLabelOrientation;

Description

Use the Orientation property to define the direction of the label’s shadow. The label’s text shadow is visible if the Properties.Depth property has a non-zero value or the Properties.LabelEffect is not set to cxleNormal.

The list of possible values are given below:

Value	Meaning	Picture
cxoLeft	Shadow is dropped to the left.
cxoRight	Shadow is dropped to the right.
cxoTop	Shadow is dropped to the top.
cxoBottom	Shadow is dropped to the bottom.
cxoLeftTop	Shadow is dropped to the left top corner.
cxoLeftBottom	Shadow is dropped to the left bottom corner.
cxoRightTop	Shadow is dropped to the right top corner.
cxoRightBottom	Shadow is dropped to the right bottom corner.

The default value of the Orientation property is cxoRightBottom.


TcxCustomLabelProperties.PenWidth

TcxCustomLabelProperties          See Also

Specifies the width of the label’s caption outline.

property PenWidth: Integer;

Description

The PenWidth property defines the width of the outline when the Properties.LabelStyle is set to cxlsOutline.

The following images show two different PenWidth settings:

Value	Meaning	Picture
0	No outline.
2	Outline width is 2.

The default value of the PenWidth property is 1.


TcxCustomLabelProperties.ShadowedColor

TcxCustomLabelProperties          See Also

Specifies the color of the label’s text shadow.

property ShadowedColor: TColor;

Description

Use the ShadowedColor property to specify the color of the label’s text shadow.  The following images show different ShadowedColor settings:

Value	Meaning	Picture
clBtnShadow	Default color.
clGreen	Shadow is green.
clRed	Shadow is red.

The default value of the ShadowedColor property is clBtnShadow.


TcxCustomLabelProperties.ShowAccelChar

TcxCustomLabelProperties          See Also

Determines how an ampersand in the label text is displayed.

property ShowAccelChar: Boolean;

Description

Set the ShowAccelChar property to True to allow the label to display an underlined accelerator key value.  In this case any character preceded by an ampersand (&) appears underlined.  If the FocusControl property is set, the windowed control specified by the FocusControl property receives input focus when the user types that underlined character while pressing the Alt key.  To display an ampersand when the ShowAccelChar is set to True, use two ampersands (&&) to stand for the single ampersand that is displayed.

Set the ShowAccelChar property to False to display the label's text with all ampersands appearing as ampersands.  In this case the value of the FocusControl property is not used.

The default value of the ShowAccelChar property is True.


TcxCustomLabelProperties.Transparent

TcxCustomLabelProperties

Determines whether the label background is transparent.

property Transparent: Boolean;

Description

Use the Transparent property to make the label background transparent.  The label caption appears opaque, regardless of the Transparent property value.

Note:	This property is obsolete.  To specify the transparency state of an editor’s background, use its Transparent property.


TcxCustomLabelProperties.WordWrap

TcxCustomLabelProperties

Determines whether the label caption is wrapped.

property WordWrap: Boolean;

Description

Use the WordWrap property to determine whether the label caption is wrapped.  Setting this property to True is useful when the label caption is too long to fit into the label rect.

WordWrap is False	WordWrap is True


TcxLabel
 TcxLabel Object

Hierarchy          Properties          Methods          Events

Represents the label control.

Unit

cxLabel

TcxLabel = class(TcxCustomLabel)

Description

The TcxLabel object provides an advanced label control that supports various visual effects.

The cxLabel attributes are accessed and managed by the Properties member.  These attributes include:

•	text painting effects (see Properties.LabelStyle and Properties.PenWidth for details);

•	the 3D shadow effect (see Properties.LabelEffect, Properties.Depth and Properties.Orientation);

•	a bitmap for painting the label text (see Properties.Glyph for details);

•	an accelerator char.

The following image shows a label control:


TcxLabel Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomLabel

     |


Properties for TcxLabel
TcxLabel Properties

TcxLabel          Legend

Derived from TcxCustomLabel

ActiveProperties

AutoSize

Caption

FocusControl

Properties

Derived from TcxCustomEdit

ActiveProperties

AutoSize

DataBinding

EditModified

EditValue

InnerEdit

ModifiedAfterEnter

Properties

RepositoryItem

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TControl

Align


Methods for TcxLabel
TcxLabel Methods

TcxLabel          Legend

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit


Events for TcxLabel
TcxLabel Events

TcxLabel          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxLabelProperties
TcxLabelProperties Object

Hierarchy          Properties          Methods          Events

Represents a set of attributes specific to label controls.

Unit

cxLabel

TcxLabelProperties = class(TcxCustomLabelProperties)

Description

The TcxLabelProperties class contains attributes specific to label controls.  The label control’s properties are set via the Properties member.

Label attributes include:

•	text painting effects (see Properties.LabelStyle and Properties.PenWidth for details);

•	the 3D shadow effect (see Properties.LabelEffect, Properties.Depth and Properties.Orientation);

•	a bitmap for painting label text (see Properties.Glyph for details).


TcxLabelProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomLabelProperties

     |


Properties for TcxLabelProperties
TcxLabelProperties Properties

TcxLabelProperties          Legend

Derived from TcxCustomLabelProperties

Angle

Depth

Glyph

LabelEffect

LabelStyle

Orientation

PenWidth

ShadowedColor

ShowAccelChar

Transparent

WordWrap

Derived from TcxCustomEditProperties

Alignment

AssignedValues

AutoSelect

BeepOnError

Buttons

ButtonsViewStyle

ClearKey

ClickKey

ImmediatePost

ReadOnly

UseLeftAlignmentOnEditing

UseMouseWheel

ValidateOnEnter


Methods for TcxLabelProperties
TcxLabelProperties Methods

TcxLabelProperties          Legend

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue


Events for TcxLabelProperties
TcxLabelProperties Events

TcxLabelProperties          Legend

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


cxListBox Unit Overview
cxListBox Unit

Classes

TcxListBox


TcxListBox
 TcxListBox Object

Hierarchy          Properties          Methods          Events

A list box style edit control.

Unit

cxListBox

TcxListBox = class(TcxContainer);

Description

The list box control represents a scrollable list of items (strings).  This control uses the standard list box control (TListBox) to implement most of its functionality.  Thus, most properties, methods and events of the TcxListBox control are identical to those of the TListBox control.

The following basic features are available in the list box control:

•	Displaying, sorting, selecting items within the list;

•	Moving and copying items to another list control;

•	Arranging items into several columns;

•	Painting items in a custom manner and assigning custom height to each individual item;

•	Working in virtual mode – item captions and data are supplied using event handlers.

The TcxListBox control also introduces the style properties (the Style, StyleDisabled, StyleFocused and StyleHot) that enables you to control the look & feel of the list box control in the same manner as other editors supplied with the ExpressQuantumGrid.


TcxListBox Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |


Properties for TcxListBox
TcxListBox Properties

TcxListBox          Legend

In TcxListBox

AutoComplete

AutoCompleteDelay

Columns

Count

ExtendedSelect

IntegralHeight

ItemHeight

ItemIndex

ItemObject

Items

ListStyle

MultiSelect

ReadOnly

ScrollWidth

SelCount

Selected

Sorted

TopIndex

Derived from TcxContainer

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName

Derived from TControl

Align


Methods for TcxListBox
TcxListBox Methods

TcxListBox          Legend

In TcxListBox

 AddItem

 Clear

 ClearSelection

 CopySelection

 Create

 DeleteSelected

 Destroy

 ItemAtPos

 ItemRect

 MoveSelection

 SelectAll

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxListBox
TcxListBox Events

TcxListBox          Legend

In TcxListBox

 OnData

 OnDataFind

 OnDataObject

 OnDrawItem

 OnMeasureItem


TcxListBox.AutoComplete

TcxListBox

Specifies whether end users can navigate through items by typing their captions.

property AutoComplete: Boolean;

Description

If the AutoComplete property is set to True the focus moves from item to item as a user types text.  The control locates the first item which matches the characters typed by the end user.  Use the AutoCompleteDelay property to specify the timing settings for the incremental search feature.


TcxListBox.AutoCompleteDelay

TcxListBox

Specifies the time interval (in milliseconds) during which any additional key presses that are made will be treated as an addition to the filter string used in the incremental search.

property AutoCompleteDelay: Cardinal;

Description

This property is in effect only when the incremental search feature is on (the AutoComplete property is set to True).  Any successive keystroke that are made within the time specified by the AutoCompleteDelay property will be treated as an addition to the filter string used in the incremental search.  When the number of milliseconds specified by the AutoCompleteDelay property has passed, the filter string is reset so that it consists only of the last key pressed.

The default value of this property is specified by the cxDefaultAutoCompleteDelay global constant.


TcxListBox.Columns

TcxListBox

Specifies the number of columns visible within the list box.

property Columns: Integer;

Description

By default, values in the list box control are arranged into a single column.  If values don’t fit into the control’s area, the vertical scroll bar is displayed.  This takes place when the Columns property value is 0.  The image below displays an example.

If the Columns property is set to a value greater than 0, strings are arranged into columns so that the vertical scroll bar is not required.  You can see the content of each column using the horizontal scroll bar in this case.  The Columns property value specifies the number of columns displayed within the control simultaneously.  The images below display the same list box control with its Columns property set to 2 and 3.


TcxListBox.Count

TcxListBox          See Also

Specifies the number of items within the list box control.

property Count: Integer;

Description

Commonly you will need the Count property to determine the number of items within the list box.  Assigning values to this property makes sense only when the list box is virtual.

Setting the ListStyle property to lbVirtual or lbVirtualOwnerDraw makes the list box virtual.  This means that you intend to supply data to the list box by handling the OnData event.  The event fires the number of times specified by the Count property value.  Each time it fires, you can provide data for a single list box item.

Note: when the list box control is virtual, you will also need to handle the OnDataFind and OnDataObject events.


TcxListBox.ExtendedSelect

TcxListBox          See Also

Specifies whether end users can select sequential ranges of items within the list box.

property ExtendedSelect: Boolean;

Description

The ExtendedSelect property is in effect only when the MultiSelect property is set to True.  If both these properties are set to True, the list box control has the following behavior:

•	Clicking an item selects it and deselects all other items.

•	Clicking an item holding the SHIFT key selects the range of items from the previously clicked to the current one.  All other items become deselected.

•	Clicking an item holding the CTRL key selects the item preserving the selected state of all other items.

If the ExtendedSelect property is set to False, clicking an item changes its selected state.  The state of other items is preserved.  Thus, end users can select multiple items, but have no ability to select ranges of items using a single click.


TcxListBox.IntegralHeight

TcxListBox          See Also

Specifies whether the list box control can display partial items.

property IntegralHeight: Boolean;

Description

If the IntegralHeight property value is False, the list box control can display partial items if they don’t completely fit into the control’s height.  The image below displays an example of displaying items partially (the bottom item doesn’t fit into the control’s area completely).

If the IntegralHeight property is set to True, the height of the control is modified so that partial items are not displayed.  The control’s client area height is the multiple of the ItemHeight property value in this case.  The image below displays the same control with the IntegralHeight property set to True.

Note:	If the ListStyle property is set to lbOwnerDrawVariable, the height of items is calculated by handling the OnMeasureItem event.  Setting the IntegralHeight property to True has no effect in this case.


TcxListBox.ItemHeight

TcxListBox          See Also

Specifies the height of items in pixels.

property ItemHeight: Integer;

Description

If the ListStyle property is set to lbStandard, the height of items in the list box is determined by the font applied to them.  (Use the Style property to access the style settings of the control.)  If the ListStyle property value is lbOwnerDrawVariable, the height of items is specified via handling the OnMeasureItem event.

In all cases except listed above, the ItemHeight property specifies the height of items within the list box control.  The image below displays list box controls with a ListStyle property lbOwnerDrawFixed and the ItemHeight property 16 and 30 respectively.


TcxListBox.ItemIndex

TcxListBox          See Also

Specifies the selected item index.

property ItemIndex: Integer;

Description

If the MultiSelect property value is False (a single item can be selected at a time), the ItemIndex property specifies the index of the selected item.  Otherwise, the ItemIndex property can be used to determine the focused item (the last one which was selected or deselected).  Assigning a value to the ItemIndex property when the MultiSelect property value is True has no visual effect.


TcxListBox.ItemObject

TcxCheckListBoxItem          See Also

Specifies the object associated with the selected item.

property ItemObject: TObject;

Description

Setting the ItemObject property locates the item which is associated with the specified object.  If found, the located item is selected within the list box (the ItemIndex property is changed correspondingly.)  Otherwise, the selection is cleared (the ItemIndex property is set to –1.)  Note that assigning a value to the ItemIndex property when the MultiSelect property’s value is equal to True has no visual effect.

Use the ItemObject property to access the object associated with the selected item.

Note:	Use the Items.Objects property to associate an item with a specific object and also to access all the objects which are associated with the items within the list box.  You have to provide complete management for the objects that you want to associate with items in a list box.


TcxListBox.Items

TcxListBox          See Also

Specifies the list of strings that represent item captions.

property Items: TStrings;

Description

The list box control can operate in two modes: standard and virtual.  This is specified by the ListStyle property value.  If working in standard mode, the number of strings in the Items property exactly specifies the number of items in the list box.  These strings represent the captions of items.

When the list box control is switched to virtual mode, the Items string list is cleared.  The number of items in the list is specified by the Count property in this case.   Captions are supplied to items by handling the OnData event.


TcxListBox.ListStyle

TcxListBox

Specifies whether the list box is standard or virtual and whether it is owner-drawn.

type

  TListBoxStyle = (lbStandard, lbOwnerDrawFixed, lbOwnerDrawVariable, lbVirtual, lbVirtualOwnerDraw);

property ListStyle: TListBoxStyle;

Description

The list box can work either in standard or virtual modes.  When in standard mode, the number of items and their captions are specified by the Items property.  In virtual mode the Count property is used to specify the number of items and their captions which are supplied in the OnData event handler.

You can also specify whether items of the list box are painted in the default or a custom manner.  In the second case, you need to write code for the OnDrawItem event handler to implement your painting logic.

The current mode, in which the list box control operates, is specified by the ListStyle property.  The following values are available for it:

Value	Description
lbStandard	The list box operates in the standard mode.  Items are painted in the default manner.
lbOwnerDrawFixed	The list box operates in the standard mode.  The OnDrawItem event fires for each item.  You can handle it to provide your own painting logic.  The height of items is specified by the ItemHeight property.
lbOwnerDrawVariable	The list box operates in the standard mode.  The OnDrawItem event fires for each item.  You can handle it to provide your own painting logic.  The height of each individual item can be set separately via handling the OnMeasureItem event.
lbVirtual	The list box operates in virtual mode.  Items are painted in the default manner.
lbVirtualOwnerDraw	The list box operates in virtual mode.  The OnDrawItem event fires for each item.  You can handle it to provide your own painting logic.  The height of items is specified by the ItemHeight property.


TcxListBox.MultiSelect

TcxListBox          See Also

Specifies whether multiple items can be selected by end users.

property MultiSelect: Boolean;

Description

If the MultiSelect property value is False, end users can select a single item at a time.  In other words, clicking an item selects it and deselects the previously selected item.  When the MultiSelect property is set to True, multiple items can be selected at the same time.  The exact behavior of the list box control depends on the ExtendedSelect property in this case.


TcxListBox.ReadOnly

TcxListBox

Specifies whether end users can change the current selection.

property ReadOnly: Boolean;

Description

Set the ReadOnly property to True to restrict end users from changing the current selection thus preventing items from having their selection state toggled within the control.  Otherwise, end users are able to change the current selection by toggling the selection state of the items in a standard manner.

Note:	When multiselect is enabled (the MultiSelect property is set to True), setting the ReadOnly property to True prevents changing the focused item and toggling its selection state.

The default value of the ReadOnly property is False.


TcxListBox.ScrollWidth

TcxListBox

Specifies the width of the list box’s client area in pixels.

property ScrollWidth: Integer;

Description

Use the ScrollWidth to enlarge the client area of the list box control.  If this property is set to a value greater than the visible client width, the logical width of the list box is enlarged.  As the result, the horizontal scroll bar is displayed.  If the ScrollWidth property value is less or equal to the visible client width, the horizontal scroll bar disappears.


TcxListBox.SelCount

TcxListBox          See Also

Gets the number of selected items when multiple selection is allowed.

property SelCount: Integer;

Description

When the MultiSelect property is set to True, end users can select multiple items within the list box.  In this case, you can use the SelCount property to determine the number of currently selected items.  When multiple selection is prohibited, this property always returns -1.

Note:	You can determine whether a specific item is selected using the Selected property.

ReadOnly Property


TcxListBox.Selected

TcxListBox          See Also

Specifies whether a specific item is selected.

property Selected[Index: Integer]: Boolean;

Description

Use the Selected property to determine whether the specified item is selected.  The item is specified by its zero-based index via the Index property.  If the specified index is negative or exceeds the maximum available item index, an exception is raised.

You can also select and deselect items using the Selected property.  For this purpose, specify the desired item index and assign True or False respectively.


TcxListBox.Sorted

TcxListBox

Specifies whether list items are alphabetically sorted.

property Sorted: Boolean;

Description

Use the Sorted property to sort items in the alphabetical order.  Set this property to True and items will be rearranged in alphabetical order within the list.  When adding items, they are automatically inserted into appropriate positions to preserve the sort order.

Setting the Sorted property to False does not revert the order however added items will not be automatically placed into positions that preserve the sort order.

Note: the Sorted property is not in effect when the list box control operates in virtual mode.  The current operation mode is specified by the ListStyle property.


TcxListBox.Style

TcxListBox

Contains style settings applied to the list box control.

property Style: TcxCustomContainerStyle;

Description

The Style property provides access to the TcxCustomContainerStyle object that contains style settings applied to the control.  You can use its properties to specify the border color, border style, font settings, etc.  Moreover, it enables you to control the look & feel of the list box using the LookAndFeel property.  This property gives you the ability to use the native style defined by the operating system or choose one the three predefined painting styles.  Please refer to the LookAndFeel property description for more details.


TcxListBox.TopIndex

TcxListBox

Specifies the index of the top visible item.

property TopIndex: Integer;

Description

When items are arranged into a single column and don’t fit into the control’s area, the vertical scroll bar is displayed.  You can use the TopIndex property to determine the item which is currently displayed at the top.  Assign a value to this property to scroll the list to the specified item.

The list box control enables you to arrange items in several columns.  In this case, the horizontal scroll bar appears when item don’t fit into the control’s area.  In this case, the TopIndex property returns the index of the first item within the leftmost visible column.  Assigning an item’s index to this property results in scrolling to the column that contains this item.


TcxListBox.AddItem

TcxListBox          See Also

Adds a new item to the list box control.

procedure AddItem(AItem: string; AObject: TObject);

Description

Use the AddItem method to add a new item to the list.  The AItem parameter represents the caption of the added item.  The AObject parameter can contain any data associated with it.

If the list is not sorted (the Sorted property value is False), the item is added to the end of the collection.  Otherwise, it is inserted to the appropriate place that preserves the sort order.

Note: this method is not in effect when the list box is in virtual mode.  The current mode is specified by the ListStyle property.


TcxListBox.Clear

TcxListBox          See Also

Removes all items from the list box.

procedure Clear;

Description

Use the Clear method if you want to delete all the items from the Items collection.

Note: this method is not in effect when the list box is in virtual mode.  The current mode is specified by the ListStyle property.


TcxListBox.ClearSelection

TcxListBox          See Also

Deselects all selected items.

procedure ClearSelection;

Description

Use the ClearSelection method to deselect all items currently selected.  After calling this method, the last selected item receives focus.  Note that the item is focused but not selected.


TcxListBox.CopySelection

TcxListBox          See Also

Copies the selected items to the specified list control.

procedure CopySelection(ADestination: TCustomListControl);

Description

Use the CopySelection method to copy the selected items into the specified TCustomListControl descendant.  This can be either a list box, combo box or a list view control.  This control is set via the ADestination parameter.

If items of the destination control are not sorted, the copied items are added to the end of the list.


TcxListBox.Create

TcxListBox          See Also

Creates a new list box control.

procedure Create(AOwner: TComponent); override;

Description

Use the constructor to create a new list box control at runtime.  The AOwner parameter specifies the owner of the control (typically, the form).  Remember to specify in your code the Parent property otherwise the list box will not be displayed.


TcxListBox.DeleteSelected

TcxListBox          See Also

Removes selected items from the list.

procedure DeleteSelected;

Description

Use the DeleteSeleciton method to delete selected items from the Items list.  After calling this method, the ItemIndex method returns the index of the item that followed the focused one.


TcxListBox.Destroy

TcxListBox          See Also

Destroys the list box control.

procedure Destroy; override;

Description

The destructor is used to dispose the list box control and free any allocated memory.

Do not call the Destroy method directly.  Call the Free method instead, which will check that the list box reference is not nil before calling Destroy.


TcxListBox.ItemAtPos

TcxListBox          See Also

Returns the index of the item located at the specified point.

function ItemAtPos(const APos: TPoint; AExisting: Boolean): Integer;

Description

You can use the ItemAtPos method to determine the item located under the specified point.  The point is specified relatively to the top-left corner of the control via the APos parameter.  The AExisting parameter specifies the return value if the specified point is below the last item.  If this parameter value is True, the method returns –1.  Otherwise, the ItemAtPos method returns the index of the last available item incremented by one.


TcxListBox.ItemRect

TcxListBox          See Also

Gets the bounds of the specified item.

function ItemRect(Index: Integer): TRect;

Description

Use the ItemRect method to determine the bounding rectangle of the specified item.  The item is specified by its zero-based index via the Index parameter.  If the parameter value is negative or exceeds the last available item index, an empty rectangle is returned (all coordinates are zeros).


TcxListBox.MoveSelection

TcxListBox          See Also

Moves the selected items to the specified list control.

procedure MoveSelection(ADestination: TCustomListControl);

Description

Use the MoveSelection method to copy the selected items into the specified TCustomListControl descendant.  This can be either a list box, combo box or a list view control.  This control is set via the ADestination parameter.

If items of the destination control are not sorted, the moved items are added to the end of the list.


TcxListBox.SelectAll

TcxListBox          See Also

Selects all items within the list box control.

procedure SelectAll;

Description

Use the SelectAll method to select all items within the list box control.  Calling this method is only in effect when the multiple selections are allowed.  Thus, the MultiSelect property must be set to True.


TcxListBox.OnData

TcxListBox          See Also

Enables you to supply captions of items when working in virtual mode.

type

  TLBGetDataEvent = procedure(Control: TWinControl; Index: Integer; var Data: string) of object;

property OnData: TLBGetDataEvent;

Description

The list box control can operate in virtual mode, where you supply item captions not via the Items property but by handling the OnData event handler.  To set the list box into this mode the ListStyle property must be set to lbVirtual or lbVirtualOwnerDraw.  Note, that handling the OnData event also results in populating the Items list, but in a different manner.

The Control parameter identifies the list box control.  The Index parameter specifies the index of the item whose caption needs to be supplied.  The caption must be assigned to the Data parameter.

Note, that when working in the virtual mode, you need to set the Count property value to a positive integer.  This property specifies the number of items, and thus the number of times the OnData event fires.


TcxListBox.OnDataFind

TcxListBox          See Also

Occurs when the list box control needs to determine the index of the item by its caption.

type

  TLBFindDataEvent = function(Control: TWinControl; FindString: string) : Integer of object;

property OnDataFind: TLBFindDataEvent;

Description

The OnDataFind event fires when the control operates in virtual mode and it is needed to find an item by its caption.  The item to be found is specified by its caption via the FindString parameter.  The event must return the index of the requested item.  The Control parameter is the list box whose item needs to be found.

The ListStyle property must be set to lbVirtual or lbVirtualOwnerDraw value to switch the control to virtual mode.


TcxListBox.OnDataObject

TcxListBox          See Also

Fires when the list box object needs to obtain the object associated with an item.

type

  TLBGetDataObjectEvent = procedure(Control: TWinControl; Index: Integer; var DataObject: TObject) of object;

property OnDataObject: TLBGetDataObjectEvent;

Description

The OnDataObject event is similar to the OnData event.  The only difference is that the OnData event supplies captions for items, while the OnDataObject event supplies associated objects.  In other words these events are needed to fill the Strings and Objects collections of the items list represented by the Items property.

The Control parameter is the list box control for whose item the object is supplied.  The Index parameter identifies the currently processed item by its zero-based index.  The object associated with the item must be assigned to the DataObject parameter.

Note: as well as the OnData event, this event only fires when the control is in virtual mode.  The ListStyle property must be set to lbVirtual or lbVirtualOwnerDraw value for this purpose.


TcxListBox.OnDrawItem

TcxListBox          See Also

Enables you to paint items in a custom manner.

type

  TDrawItemEvent = procedure(AControl: TcxListBox; ACanvas: TcxCanvas; AIndex: Integer; ARect: TRect; AState: TOwnerDrawState) of object;

property OnDrawItem: TDrawItemEvent;

Description

The list box control enables you to paint items in a custom manner.  For this purpose, you must set the ListStyle property to lbOwnerDrawFixed, lbOwnerDrawVariable or lbVirtualOwnerDraw.  In this case, the OnDrawItem event fires for each individual item when it needs to be painted.  Note that if the ListStyle property is set to one of the listed values and the OnDrawItem event is not handled, the control is painted in its usual way.

The AControl parameter specifies the list box control whose item is to be painted on the ACanvas’s surface.  ACanvas provides methods to draw shapes, write text, render graphic images, etc.

The AIndex parameter identifies the processed item by its zero-based index.  The bounding rectangle of the item is specified by the ARect parameter.  The AState parameter provides information on whether the current item is selected, focused, etc.

Note that you can assign a custom height to each individual item.  For this purpose, you need to set the ListStyle property to lbOwnerDrawVariable and handle the OnMeasureItem event.  Otherwise, the height of items is specified by the ItemHeight property.

The following example shows how to implement different painting of odd and even items for a listbox control.  If an item is selected (the AState parameter contains the odSelected flag), it is painted in a soft yellow color.

//Delphi

procedure TForm1.cxListBox1DrawItem(AControl: TcxListBox;

  ACanvas: TcxCanvas; AIndex: Integer; ARect: TRect;

  AState: TOwnerDrawState);

var

  AText: string;

  ABkGColor, ATextColor: TColor;

  ATextRect: TRect;

begin

  if odSelected in AState then

  begin

    ABkGColor := $008DEFF1;

    ATextColor := $005079BE;

  end

  else

    if Odd(AIndex) then

    begin

      ABkGColor := $00E8C5A8;

      ATextColor := clBlue;

    end

    else

      begin

        ABkGColor := $00F19F3A;

        ATextColor := clWhite;

      end;

  ACanvas.Brush.Color := ABkGColor;

  ACanvas.Font.Color := ATextColor;

  ACanvas.FillRect(ARect);

  AText := AControl.Items[AIndex];

  ATextRect := ARect;

  ATextRect.Left := ATextRect.Left + 3;

  ACanvas.DrawTexT(AText, ATextRect, 0);

end;

//C++ Builder

void __fastcall TForm1::cxListBox1DrawItem(TcxListBox *AControl,

      TcxCanvas *ACanvas, int AIndex, TRect &ARect, TOwnerDrawState AState)

{

  TColor ABkGColor, ATextColor;

  if (AState.Contains(odSelected)) {

    ABkGColor = 0x008DEFF1;

    ATextColor = 0x005079BE;

  }

  else

    if (AIndex % 2) {

      ABkGColor = 0x00E8C5A8;

      ATextColor = clBlue;

    }

    else {

      ABkGColor = 0x00F19F3A;

      ATextColor = clWhite;

    }

  ACanvas->Brush->Color = ABkGColor;

  ACanvas->Font->Color = ATextColor;

  ACanvas->FillRect(ARect);

  String AText = AControl->Items->Strings[AIndex];

  TRect ATextRect = ARect;

  ATextRect.Left = ATextRect.Left + 3;

  ACanvas->DrawTexT(AText, ATextRect, 0);

}

The result of the customization is displayed in the following image:


TcxListBox.OnMeasureItem

TcxListBox          See Also

Enables you to assign a custom height to each individual item.

type

  TMeasureItemEvent = procedure(AControl: TcxListBox; AIndex: Integer; var Height: Integer) of object;

property OnMeasureItem: TMeasureItemEvent;

Description

The OnMeasureItem event fires if the ListStyle property is set to lbOwnerDrawVariable.  This event enables you to change the height of each individual item within the list box.  The currently processed item is identified by its index via the AIndex parameter.  The height in pixels must be assigned to the Height parameter.  The AControl parameter represents the list box control whose item’s height is to be calculated.

Note:	if the OnDrawItem event is not handled, items will have assigned heights but will be painted in the default manner.


cxLookupDBGrid Unit Overview
cxLookupDBGrid Unit

Classes

TcxLookupDBGridColumn

TcxLookupDBGridColumns


TcxLookupDBGridColumn
TcxLookupDBGridColumn Object

Hierarchy          Properties

Represents a column within the dropdown list of a lookup combo box.

Unit

cxLookupDBGrid

TcxLookupDBGridColumn = class(TcxLookupGridColumn);

Description

The TcxLookupDBGridColumn object represents a column within the dropdown list of a lookup combo box.  Columns provide a convenient data representation and allow the performing of different actions (sorting, for instance).  All columns are stored within the LookupComboBox.Properties.ListColumns collection.  Each column corresponds to a LookupComboBox.Properties.ListSource field.  The names of all fields to display within the dropdown list are specified via the LookupComboBox.Properties.ListFieldNames property.

A user can create or remove dropdown columns either by using the LookupComboBox.Properties.ListColumns collection editor or by adding or removing names of the required LookupComboBox.Properties.ListSource fields to the LookupComboBox.Properties.ListFieldNames property value.


TcxLookupDBGridColumn Hierarchy
Hierarchy

TCollectionItem

     |

TcxLookupGridColumn

     |


Properties for TcxLookupDBGridColumn
TcxLookupDBGridColumn Properties

TcxLookupDBGridColumn          Legend

In TcxLookupDBGridColumn

FieldName

Derived from TcxLookupGridColumn

Caption

Fixed

HeaderAlignment

MinWidth

RepositoryItem

Sorting

SortOrder

Width


TcxLookupDBGridColumn.FieldName

TcxLookupDBGridColumn

Specifies the name of the data source field whose values are displayed within a column.

property FieldName: string;

Description

Use the FieldName property to specify the name of the data source field whose values are displayed within a column.  If a user supplies the FieldName property value for a specific column, the Caption property value of that column is copied from the FieldName value by default.  If this property value is not assigned for a specific column, that column appears empty within the dropdown list.

Note: The FieldName property may contain only the name of the existing data source field, otherwise, an error message is displayed and the FieldName property value is cleared.


TcxLookupDBGridColumns
TcxLookupDBGridColumns Object

Hierarchy          Properties          See Also

Represents a collection of columns located within the dropdown list of a lookup combo box.

Unit

cxLookupDBGrid

TcxLookupDBGridColumns = class(TcxLookupGridColumns);

Description

The TcxLookupDBGridColumns collection contains columns displayed within the dropdown list of a lookup combo box.  Columns provide a convenient data representation within the dropdown list and they allow the performing of different actions (sorting, for instance).

Columns can be added to or removed from the collection both at design time and via code.  At design time, a user can work with the ListColumns collection editor to add or remove columns from the collection, specify the data source field for each column or change a specific column’s settings, such as width and sorting, etc.  Another way of editing the ListColumns collection is to use the LookupComboBox.Properties.ListFieldNames property.  A user can add a column to the collection by adding a new data source’s field name to the LookupComboBox.Properties.ListFieldNames property value.  A column can be removed if the name of the corresponding data source field is removed from the LookupComboBox.Properties.ListFieldNames property value.


TcxLookupDBGridColumns Hierarchy
Hierarchy

TCollection

     |

TcxLookupGridColumns

     |


Properties for TcxLookupDBGridColumns
TcxLookupDBGridColumns Properties

TcxLookupDBGridColumns          Legend

Derived from TcxLookupGridColumns

Items


cxLookupGrid Unit Overview
cxLookupGrid Unit

Classes

TcxLookupGridColumn

TcxLookupGridColumns

TcxLookupGridOptions


TcxLookupGridColumn
TcxLookupGridColumn Object

Hierarchy          Properties

Represents the base class for the TcxLookupDBGridColumn object.

Unit

cxLookupGrid

TcxLookupGridColumn = class(TCollectionItem, IcxEditRepositoryItemListener, IUnknown);

Description

The TcxLookupGridColumn object represents the base class for the TcxLookupDBGridColumn object (a column within the dropdown list of a lookup combo box).  Columns of the dropdown list are stored within the LookupComboBox.Properties.ListColumns collection.  They can be used to apply sorting to the dropdown list.  The width of columns can be adjusted in order to entirely display field values of a data source.


TcxLookupGridColumn Hierarchy
Hierarchy

TCollectionItem

     |


Properties for TcxLookupGridColumn
TcxLookupGridColumn Properties

TcxLookupGridColumn          Legend

In TcxLookupGridColumn

Caption

Fixed

HeaderAlignment

MinWidth

RepositoryItem

Sorting

SortOrder

Width


TcxLookupGridColumn.Caption

TcxLookupGridColumn

Specifies the text string representing a column within the dropdown list of a lookup combo box.

property Caption: string;

Description

Use the Caption property to specify the text string representing a column within the dropdown list of a lookup combo box.


TcxLookupGridColumn.Fixed

TcxLookupGridColumn

Determines whether the width of a column depends on other column settings.

property Fixed: Boolean;

Description

Use the Fixed property to determine whether the width of a column depends on other column settings.  If Fixed is True, the width of a column can be only changed directly via the Width property.

The default value of the Fixed property is False.


TcxLookupGridColumn.HeaderAlignment

TcxLookupGridColumn

Specifies column caption text alignment within a column header.

type

  TAlignment = (taLeftJustify, taRightJustify, taCenter);

property HeaderAlignment: TAlignment;

Description

Use the HeaderAlignment property to specify the alignment of column header text.

The default value of the HeaderAlignment property is taLeftJustify.


TcxLookupGridColumn.MinWidth

TcxLookupGridColumn

Specifies the minimum width of a specific column.

property MinWidth: Integer;

Description

Use the MinWidth property to specify the minimum width of a specific column in a dropdown list.

The default value of the MinWidth property is cxLookupGridColumnDefaultMinWidth.


TcxLookupGridColumn.RepositoryItem

TcxLookupGridColumn

Specifies the repository item used as an editor for a specific column’s content.

property RepositoryItem: TcxEditRepositoryItem;

Description

Use the RepositoryItem property to specify a specific repository item to use as an editor for a specific column’s contents.  For instance, a user can assign a TcxCheckBox control to represent values of the column displaying the ListSource field containing Boolean data.


TcxLookupGridColumn.Sorting

TcxLookupGridColumn

Determines whether dropdown data of a lookup combo box can be sorted based on values of a specific column.

property Sorting: Boolean;

Description

Use the Sorting property to determine whether dropdown data of the lookup combo box can be sorted, at runtime, based on values of a specific column.  If this property value is False, sorting can still be applied to a lookup combo box dropdown by setting the SortOrder property to any value (except for soNone).

Sorting can be applied to a column at runtime by clicking the required column header.  To apply sorting across several columns, click the appropriate column headers with the Shift key pressed.

The default value of the Sorting property is True.


TcxLookupGridColumn.SortOrder

TcxLookupGridColumn

Specifies the sort order for a column.

type

  TcxDataSortOrder = (soNone, soAscending, soDescending);

property SortOrder: TcxDataSortOrder;

Description

Use the SortOrder property to specify the order in which the lookup grid dropdown list is sorted based on the current column’s values.

Value	Meaning
soAscending	The lookup grid dropdown list is sorted in ascending order.
soDescending	The lookup grid dropdown list is sorted in descending order.
soNone	The lookup grid dropdown list is not sorted.

SortOrder can be applied to a column even when the Sorting property value is False.

The default value of the SortOrder property is soNone.


TcxLookupGridColumn.Width

TcxLookupGridColumn

Specifies column width.

property Width: Integer;

Description

Use the Width property to specify column width.  Using this property is the only way of changing the width of a column if the Fixed property value is True.


TcxLookupGridColumns
TcxLookupGridColumns Object

Hierarchy          Properties          Methods          See Also

Represents a collection of columns located within the dropdown list of a lookup combo box.

Unit

cxLookupGrid

TcxLookupGridColumns = class(TCollection);

Description

The TcxLookupGridColumns collection contains columns displayed within the dropdown list of a lookup combo box.  Columns provide a convenient data representation within the dropdown list and allow the performing of different actions (sorting, for instance).

Columns can be added to or removed from the collection both at design time and via code.  At design time, a user can work with the ListColumns collection editor or specify the LookupComboBox.Properties.ListFieldNames property value.


TcxLookupGridColumns Hierarchy
Hierarchy

TCollection

     |


Properties for TcxLookupGridColumns
TcxLookupGridColumns Properties

TcxLookupGridColumns          Legend

In TcxLookupGridColumns

Items


Methods for TcxLookupGridColumns
TcxLookupGridColumns Methods

TcxLookupGridColumns          Legend

In TcxLookupGridColumns

 Add


TcxLookupGridColumns.Items

TcxLookupGridColumns

Provides indexed access to columns in the columns collection of the dropdown list.

property Items[Index: Integer]: TcxLookupGridColumn;

Description

Use the Items property to access individual columns within a collection.  The Index parameter value represents the position of an item within the collection.


TcxLookupGridColumns.Add

TcxLookupGridColumns

Creates a new lookup combo box column and adds it to a collection.

function Add: TcxLookupGridColumn;

Description

Use the Add method to create a column in a collection.  A new column is placed at the end of the Items array.  The return value of this method is the newly created collection item.


TcxLookupGridOptions
TcxLookupGridOptions Object

Hierarchy          Properties          See Also

Contains settings determining the look & feel of the dropdown list of a lookup combo box.

Unit

cxLookupGrid

TcxLookupGridOptions = class(TPersistent);

Description

TcxLookupGridOptions contains settings determining the look & feel of the dropdown list of an editor.   These settings determine the visual representation of the dropdown list (GridLines and ShowHeader) and the row selection within it (RowSelect).  They also define whether the list can be sorted (ColumnSorting).  Sorting is implemented using Windows locale settings for sorting rows (AnsiSort).  The characters case information can be ignored during sorting (CaseInsensitive).


TcxLookupGridOptions Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxLookupGridOptions
TcxLookupGridOptions Properties

TcxLookupGridOptions          Legend

In TcxLookupGridOptions

AnsiSort

CaseInsensitive

ColumnSorting

FocusRowOnMouseMove

GridLines

RowSelect

ShowHeader


TcxLookupGridOptions.AnsiSort

TcxLookupGridOptions

Indicates whether the dropdown list uses Windows locale settings to sort rows.

property AnsiSort: Boolean;

Description

Use the AnsiSort property to determine whether the dropdown list uses Windows locale settings to sort rows. This option is useful when the dropdown list contains native language text.

The default value of the AnsiSort property is False.


TcxLookupGridOptions.CaseInsensitive

TcxLookupGridOptions

Indicates whether character case is ignored during sorting.

property CaseInsensitive: Boolean;

Description

Use the CaseInsensitive property to determine whether character case is ignored when sorting the dropdown list of a lookup combo box.

The default value of the CaseInsensitive property is False.


TcxLookupGridOptions.ColumnSorting

TcxLookupGridOptions

Indicates whether sorting can be applied to the dropdown list of a lookup combo box.

property ColumnSorting: Boolean;

Description

Use the column sorting property to determine whether the dropdown list of a lookup combo box can be sorted at runtime.  If this property value is False, the dropdown list can still be sorted using the SortOrder property of the required column.

The default value of the ColumnSorting property is True.


TcxLookupGridOptions.FocusRowOnMouseMove

TcxLookupGridOptions

Indicates whether moving the mouse in the dropdown list of a lookup combo box focuses the row under the mouse pointer.

property FocusRowOnMouseMove: Boolean;

Description

Set this property to True to enable focusing the row under the mouse pointer during mouse navigation within the dropdown list of a lookup combo box.  Otherwise, the focus doesn’t move from the currently focused row (which corresponds to the editor’s value) when the mouse hovers over rows in the dropdown list.

The default value of the FocusRowOnMouseMove property is True.


TcxLookupGridOptions.GridLines

TcxLookupGridOptions

Specifies which grid lines are displayed within the dropdown list of a lookup combo box.

type

  TcxGridLines = (glBoth, glNone, glVertical, glHorizontal);

property GridLines: TcxGridLines;

Description

Use the GridLines property to determine which grid lines are displayed within the dropdown list of a lookup combo box.

Value	Meaning
glBoth	Both horizontal and vertical grid lines are displayed.
glHorizontal	Only horizontal grid lines are displayed.
glNone	No grid lines are displayed.
glVertical	Only vertical grid lines are displayed.

The default value of the GridLines property is glBoth.


TcxLookupGridOptions.RowSelect

TcxLookupGridOptions

Indicates whether entire rows can be selected when navigating through a dropdown list.

property RowSelect: Boolean;

Description

Use the RowSelect property to determine whether entire rows are selected when navigating through a dropdown list.  The images illustrating the difference between RowSelect set to True or False are demonstrated below:

The RowSelect value is True	The RowSelect value is False

The default value of the RowSelect property is True.


TcxLookupGridOptions.ShowHeader

TcxLookupGridOptions

Indicates whether column headers are displayed within the dropdown list of a lookup combo box.

property ShowHeader: Boolean;

Description

Use the ShowHeader property to determine whether column headers are displayed within the dropdown list of a lookup combo box.  If this property value is False, there are no column headers within the dropdown list.  That means that sorting cannot be applied to the dropdown list by clicking column headers.  In this case, the dropdown list can be sorted by changing the SortOrder property value of the required column.

The default value of the ShowHeader property is True.


cxMaskEdit Unit Overview
cxMaskEdit Unit

Classes

TcxCustomMaskEdit

TcxCustomMaskEditProperties

TcxMaskEdit

TcxMaskEditProperties

Other Types

TcxEditMask

TcxEditMaskKind


TcxCustomMaskEdit
TcxCustomMaskEdit Object

Hierarchy          Properties          Methods           Events

TcxCustomMaskEdit is the base type for those edit controls which provide a mask for checking the validity of text typed into a control.

Unit

cxMaskEdit

TcxCustomMaskEdit = class(TcxCustomTextEdit);

Description

The TcxCustomMaskEdit component introduces new properties and methods to expand the capabilities of TcxCustomTextEdit for validity checking using the edit mask.  Use the TcxMaskEdit object to create an edit control that utilizes TcxCustomMaskEdit mask capabilities.  To create an edit control that does not validate input, use the TcxCustomTextEdit object instead.

Do not create instances of TcxCustomMaskEdit.  Use TcxCustomMaskEdit as the base class when declaring the control objects implementing a masked edit control.  Properties and methods of TcxCustomMaskEdit provide the base behavior inherited by descendant classes, as well as the behavior components can override to customize their behavior.


TcxCustomMaskEdit Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |


Properties for TcxCustomMaskEdit
TcxCustomMaskEdit Properties

TcxCustomMaskEdit          Legend

In 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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxCustomMaskEdit
TcxCustomMaskEdit Methods

TcxCustomMaskEdit          Legend

In TcxCustomMaskEdit

CutToClipboard

PasteFromClipboard

Derived from TcxCustomTextEdit

Clear

ClearSelection

CopyToClipboard

Create

CutToClipboard

SelectAll

SetSelection

Undo

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCustomMaskEdit
TcxCustomMaskEdit Events

TcxCustomMaskEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCustomMaskEdit.ActiveProperties

TcxCustomMaskEdit           See Also

Obtains the properties that are currently applied to an editor.

property ActiveProperties: TcxCustomMaskEditProperties;

Description

Use the ActiveProperties property to obtain the properties of the current editor that are currently in effect.  This property is especially useful when the 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 editor.  Otherwise, the inherent editor’s properties are returned.

ReadOnly Property


TcxCustomMaskEdit.Properties

TcxCustomMaskEdit

Identifies the main attributes specific to an editor.

property Properties: TcxCustomMaskEditProperties;

Description

Use Properties to set specific attributes which control the editor behavior.  They define the alignment of an editor’s contents, the collection of buttons that can be displayed within this editor, the read-only status, etc.  Properties specific to text editors are stored in the TcxCustomMaskEditProperties class.


TcxCustomMaskEdit.CutToClipboard

TcxCustomMaskEdit

Copies the selected text to the Clipboard and deletes the selection.

procedure CutToClipboard; override;

Description

Use the CutToClipboard method to replace the Clipboard contents with the selected text while clearing this text within a control.  If no text is selected, CutToClipboard performs no actions.

The TcxCustomMaskEdit component re-implements the CutToClipboard method to support mask handling.


TcxCustomMaskEdit.PasteFromClipboard

TcxCustomMaskEdit

Pastes the contents of the Clipboard to a mask control replacing the current selection.

procedure PasteFromClipboard; override;

Description

Use the PasteFromClipboard method to replace the selected text with the contents of the Clipboard, or, if no text is selected, to insert the contents of the Clipboard at the cursor.  If the Clipboard is empty, the PasteFromClipboard method performs no action.


TcxCustomMaskEditProperties
  TcxCustomMaskEditProperties Object

Hierarchy          Properties          Methods          Events

Contains settings specific to mask editors.

Unit

cxMaskEdit

TcxCustomMaskEditProperties = class(TcxCustomTextEditProperties);

Description

The TcxCustomMaskEditProperties class represents a set of attributes controlling the MaskEdit behavior.  Properties for an edit control are set via the Properties member of the corresponding editor.


TcxCustomMaskEditProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |


Properties for TcxCustomMaskEditProperties
TcxCustomMaskEditProperties Properties

TcxCustomMaskEditProperties          Legend

In TcxCustomMaskEditProperties

AlwaysShowBlanksAndLiterals

CaseInsensitive

EditMask

IgnoreMaskBlank

IsMasked

MaskKind

Derived from TcxCustomTextEditProperties

AssignedValues

CharCase

DisplayFormat

EchoMode

EditFormat

HideCursor

HideSelection

ImeMode

ImeName

IncrementalSearch

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 TcxCustomMaskEditProperties
TcxCustomMaskEditProperties Methods

TcxCustomMaskEditProperties          Legend

In TcxCustomMaskEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomTextEditProperties

IsDisplayValueValid

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue


Events for TcxCustomMaskEditProperties
TcxCustomMaskEditProperties Events

TcxCustomMaskEditProperties          Legend

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomMaskEditProperties.AlwaysShowBlanksAndLiterals

TcxCustomMaskEditProperties           See Also

Specifies whether the editor’s display value includes blank and literal characters when the editor is not focused.

property AlwaysShowBlanksAndLiterals: Boolean;

Description

When an editor uses a standard mask, you can use the AlwaysShowBlanksAndLiterals property to specify whether blank and literal characters should be displayed when the editor is not focused.  Blank characters are placeholders for character input.  Literal characters are included into the mask into fixed positions to enhance input convenience and value readability.  An example of literal characters is the day, month and year delimiter in a date mask.

Note that literal characters included into the mask can be included into the editor’s value.  This takes place if the mask includes the 1 flag separated from the mask pattern by a semicolon (at design-time, you can switch this flag using the Save literal characters check box within the mask editor).  If this flag is set, literal characters are not hidden regardless of the AlwaysShowBlanksAndLiterals property value.

Note that setting the AlwaysShowBlanksAndLiterals property value to True is useful for in-place editors that are bound to fields whose values are edited using masks but literal characters are not stored.  The image below shows an example for a column displaying phones.  The AlwaysShowBlanksAndLiterals property is set to False and True respectively.

The default value of the AlwaysShowBlanksAndLiterals property is False.


TcxCustomMaskEditProperties.CaseInsensitive

TcxCustomMaskEditProperties

Specifies whether the mask is case sensitive.

property CaseInsensitive: Boolean;

Description

If the CaseInsensitive property is set to True, the mask does not distinguish input between capital and small letters.

For more information see Using MaskEdit.


TcxCustomMaskEditProperties.EditMask

TcxCustomMaskEditProperties           See Also

Specifies the mask representing valid text for a masked edit control.

type

  TcxEditMask = type string;

property EditMask: TcxEditMask;

Description

Use the EditMask property to restrict the number of characters a user can enter into a masked edit control to validate characters and formats.  If the user attempts to enter an invalid character, the edit control will not accept it.

Setting the EditMask property to an empty string removes the mask.

The default value of the EditMask property for a data-aware editor is determined by the EditMask attribute of the dataset field to which this editor is connected.

You can use the RestoreDefaults method to revert to the default values of the EditMask property and some other properties retrieved from the related TField object attributes.

For more information on masks see Using MaskEdit.


TcxCustomMaskEditProperties.IgnoreMaskBlank

TcxCustomMaskEditProperties

Determines the manner in which a mask editor reacts to an input validation error.

property IgnoreMaskBlank: Boolean;

Description

If the IgnoreMaskBlank property is set to False, a user cannot leave the mask editor until input is validated successfully.  If validation fails, a user receives the following message box:

If the IgnoreMaskBlank property is set to True, a user can leave the mask editor only if the text is completely entered or is not entered at all.  If a part of the required text is entered a user cannot leave the editor.   This is applied for standard mask only.  When working with regular expressions a user can leave the editor at any moment without input validation.

The default value of the IgnoreMaskBlank property is False.


TcxCustomMaskEditProperties.IsMasked

TcxCustomMaskEditProperties

Indicates whether the mask exists for a mask editor.

property IsMasked: Boolean;

Description

Read the IsMasked property to determine whether the EditMask property has been set.  If the IsMasked property is True, the control has a mask, and input is validated at runtime.  If the IsMasked property is False, the control does not restrict editing at runtime.

ReadOnly Property


TcxCustomMaskEditProperties.MaskKind

TcxCustomMaskEditProperties

Determines the mask type of a mask editor.

type

  TcxEditMaskKind = (emkStandard, emkRegExpr, emkRegExprEx);

property MaskKind: TcxEditMaskKind;

Description

Read the MaskKind property to get the current input mask type.  Write this property to specify the input mask type.

For more information see Using MaskEdit.


TcxCustomMaskEditProperties.GetEmptyString

TcxMaskEditProperties

Returns an empty text based on the EditMask property, if set.

function GetEmptyString: string;

Description

The GetEmptyString method returns an empty text based on the EditMask property, if set.  For instance, if the EditMask property value is !\(999\)000-0000;1;_, the GetEmptyString method will return (___)___-____.


TcxCustomMaskEditProperties.ValidateDisplayValue

TcxCustomMaskEditProperties

Validates a string against the current mask.

type

  TcxEditValue = Variant;

procedure ValidateDisplayValue(var ADisplayValue: TcxEditValue; var AErrorText: TCaption; var Error: Boolean); override;

Description

Use the ValidateDisplayValue method to validate a string against the current mask.  The ADisplayValue parameter contains the string to validate.  The AErrorText parameter contains an error message if a validation error occurs.  The Error parameter indicates whether the validation error has occurred.  It is False if validation is successful; otherwise, False.


TcxMaskEdit
 TcxMaskEdit Object

Hierarchy          Properties          Methods          Events           See Also

TcxMaskEdit implements a generic masked edit control.

Unit

cxMaskEdit

TcxMaskEdit = class(TcxCustomMaskEdit);

Description

Use the TcxMaskEdit object to place a masked edit control onto your form.  Masked edit controls validate text a user enters against the mask and this limits the valid forms the text can take.  The mask can also format the text displayed for a user.

The TcxMaskEdit control implements the generic behavior introduced in TcxCustomMaskEdit.  TcxMaskEdit publishes many of the properties and methods inherited from TcxCustomMaskEdit, but does not introduce any new behavior.

Use the Properties and style (the Style, StyleDisabled, StyleFocused and StyleHot) properties to specify the behavior and appearance of a combo box editor.  Working with styles is discussed in the TcxCustomEditStyle class topic.


TcxMaskEdit Hierarchy
Hierarchy

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |


Properties for TcxMaskEdit
TcxMaskEdit Properties

TcxMaskEdit          Legend

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

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxMaskEdit
TcxMaskEdit Methods

Derived from TcxCustomMaskEdit

CutToClipboard

PasteFromClipboard

Derived from TcxCustomTextEdit

Clear

ClearSelection

CopyToClipboard

Create

CutToClipboard

SelectAll

SetSelection

Undo

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxMaskEdit
TcxMaskEdit Events

TcxCustomMaskEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxMaskEditProperties
  TcxMaskEditProperties Object

Hierarchy          Properties          Methods          Events

Publishes members of the TcxCustomMaskEditProperties object.

Unit

cxMaskEdit

TcxMaskEditProperties = class(TcxCustomMaskEditProperties);

Description

The TcxMaskEditProperties class represents a set of attributes that control the behavior of mask edit editors.  Properties for an editor are set via the Properties member of the corresponding editor.  To control any changes made to the editor’s DisplayFormat, EditFormat, MaxLength, MaxValue, MinValue and ReadOnly properties and reverse their values back to the default ones, use the AssignedValues property.

This class inherits the functionality defined in the TcxCustomMaskEditProperties class.  It also publishes the EditMask property, which allows the implementation of an input mask.


TcxMaskEditProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |


Properties for TcxMaskEditProperties
TcxMaskEditProperties Properties

TcxMaskEditProperties          Legend

In TcxMaskEditProperties

MaxLength

Derived from TcxCustomMaskEditProperties

AlwaysShowBlanksAndLiterals

CaseInsensitive

EditMask

IgnoreMaskBlank

IsMasked

MaskKind

Derived from TcxCustomTextEditProperties

AssignedValues

CharCase

DisplayFormat

EchoMode

EditFormat

HideCursor

HideSelection

ImeMode

ImeName

IncrementalSearch

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 TcxMaskEditProperties
TcxMaskEditProperties Methods

Derived from TcxCustomMaskEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomTextEditProperties

IsDisplayValueValid

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue


Events for TcxMaskEditProperties
TcxMaskEditProperties Events

TcxMaskEditProperties          Legend

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxMaskEditProperties.MaxLength

TcxMaskEditProperties

Specifies the maximum number of characters which can appear within a mask editor.

property MaxLength: Integer;

Description

The MaxLength property specifies the length of the Text property value.  Set the MaxLength property to limit the number of characters that can appear within an edit control, when there is no EditMask.  If there is an EditMask, MaxLength is implied by the mask itself and cannot be changed.  The Text property has sufficient blank characters added at the end or beginning of every optional section, so that it remains constant in length.


TcxEditMask
TcxEditMask type

See Also

Represents a mask that validates and formats user input.

Unit

cxMaskEdit

type

  TcxEditMask = type string;

Description

For more information on the input mask see Using Mask Edit.


TcxEditMaskKind
TcxEditMaskKind type

Determines the mask type of a mask editor.

Unit

cxMaskEdit

type

  TcxEditMaskKind = (emkStandard, emkRegExpr, emkRegExprEx);

Description

A mask editor supports three mask types.

Kind	Description
emkStandard	Simple mask.  Same as the Delphi Native MaskEdit.
emkRegExpr	Mask based on regular expressions.
emkRegExprEx	Same as emkRegExpr, but has the auto-completion feature.

The default value of the MaskKind property is emkStandard.

For more information see Using MaskEdit.


cxMCListBox Unit Overview
cxMCListBox Unit

Classes

TcxMCListBox


TcxMCListBox
 TcxMCListBox Object

Hierarchy          Properties          Methods

Represents a multi column list box control.

Unit

cxMCListBox

TcxMCListBox = class(TcxContainer);

Description

The TcxMCListBox control represents a list box that is capable of displaying data across several columns.  Visually, it consists of a header panel where column headers reside and the data columns.  The rightmost edges of column headers can be dragged to resize columns at runtime.  Additionally, you can enable column header click events to allow end users to sort the list by column values in ascending and/or descending order.

The images below display possible appearance options of our multi column list box control.

The TcxMCListBox control offers the following features:

•	Displaying data across multiple columns with the ability to display large values across several columns.  Please refer to the Populating a Multi Column ListBox with Items topic for details;

•	Selecting multiple items.  Please refer to the Working with Selections topic for details;

•	Copying and moving selections to any list control with a single method call.  Please see the CopySelection and MoveSelection property description for more information;

•	Displaying multi-line items.  See the MultiLines property description for details;

•	Sorting the list by column values.  Please refer to the Sorted property description for details.


TcxMCListBox Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |


Properties for TcxMCListBox
TcxMCListBox Properties

TcxMCListBox          Legend

In TcxMCListBox

AutoComplete

AutoCompleteDelay

ColumnLineColor

Delimiter

ExtendedSelect

HeaderDragReorder

HeaderSections

IntegralHeight

ItemHeight

ItemIndex

Items

MultiLines

MultiSelect

OverflowEmptyColumn

SelCount

Selected

ShowColumnLines

ShowEndEllipsis

ShowHeader

Sorted

TopIndex

Derived from TcxContainer

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName

Derived from TControl

Align


Methods for TcxMCListBox
TcxMCListBox Methods

TcxMCListBox          Legend

In TcxMCListBox

 AddItem

 Clear

 ClearSelection

 CopySelection

 DeleteSelected

 ItemAtPos

 ItemRect

 MoveSelection

 SelectAll

Derived from TcxControl

 Create

 Destroy

 InvalidateRect


TcxMCListBox.AutoComplete

TcxMCListBox

Specifies whether end users can navigate through items by typing their captions.

property AutoComplete: Boolean;

Description

If the AutoComplete property is set to True the focus moves from item to item as a user types text.  The control locates the first item which matches the characters typed by the end user.  Use the AutoCompleteDelay property to specify the timing settings for the incremental search feature.


TcxMCListBox.AutoCompleteDelay

TcxMCListBox

Specifies the time interval (in milliseconds) during which any additional key presses that are made will be treated as an addition to the filter string used in the incremental search.

property AutoCompleteDelay: Cardinal;

Description

This property is in effect only when the incremental search feature is on (the AutoComplete property is set to True).  Any successive keystroke that are made within the time specified by the AutoCompleteDelay property will be treated as an addition to the filter string used in the incremental search.  When the number of milliseconds specified by the AutoCompleteDelay property has passed, the filter string is reset so that it consists only of the last key pressed.

The default value of this property is specified by the cxDefaultAutoCompleteDelay global constant.


TcxMCListBox.ColumnLineColor

TcxMCListBox          See Also

Specifies the color of column lines.

property ColumnLineColor: TColor;

Description

Use the ColumnLineColor property to change column color lines.  Note that these lines are only visible if the ShowColumnLines property value is True.

Images below show the same control when the ColumnLineColor property is set to clRed and clGreen.

The default value of the ColumnLineColor property is clBtnShadow.


TcxMCListBox.Delimiter

TcxMCListBox          See Also

Specifies the character separating column values from one another in strings specified by the Items property.

property Delimiter: Char;

Description

Data displayed by the multi column list box is specified by the Items property.  Each text line stored in this property corresponds to a row of values in the control.  Column values are separated from one another using the character specified by the Delimiter property.

By default, the Delimiter property value is the semicolon character.  You may need to change it if the list box must display semicolons in column values.  So the common rule for setting the Delimiter property is to specify a character that is not used for any column value.

Please refer to the Populating a Multi Column ListBox with Items topic for details on using the Delimiter and related properties.

The default value of the Delimiter property is #9 (the semicolon character).


TcxMCListBox.ExtendedSelect

TcxMCListBox          See Also

Specifies the manner in which end users can select multiple items.

property ExtendedSelect: Boolean;

Description

End users are allowed to select multiple items when the MultiSelect property is set to True.  The way items can be selected is specified by the ExtendedSelect property.  The table below describes the values available for this property.

Value	Meaning
True	Clicking an item holding the CTRL key pressed toggles the selected state of the item.  Clicking an item holding the SHIFT key pressed selects the range of items from the currently selected to the clicked item.  All other items become deselected.  Finally, clicking an item without holding the CTRL or SHIFT key pressed selects the items deselecting all other items.
False	Clicking an item toggles its selected state.  Any keys pressed along with the click are ignored.

See the Working with Selections topic for information on how items can be selected via code and what built in operations across selections are available.

The default value of the ExtendedSelect property is True.


TcxMCListBox.HeaderDragReorder

TcxMCListBox          See Also

Specifies whether end users can change the order of columns by dragging their headers.

property HeaderDragReorder: Boolean;

Description

Use the HeaderDragReorder property to specify whether headers can be dragged to reorder columns.  If set to True, such drag and drop operations are allowed.  Otherwise, attempts to drag column headers have no effect.  Note that changing the order of columns at runtime doesn’t affect the data they display.  The contents of the Items property remains the same after such operations.

Note:	You can customize the appearance and behavior of column headers using the HeaderSections property.  This property holds a collection of TcxHeaderSection objects that contain settings for individual columns headers.  You can expose one more feature to end users using properties of these objects.  Set the AllowClick property to True to allow end users to sort the list box by column values using a click on the column header.

The default value of the HeaderDragReorder property is False.


TcxMCListBox.HeaderSections

TcxMCListBox          See Also

Specifies the number of column displayed by the control and provides access to column header settings.

property HeaderSections: TcxHeaderSections;

Description

The HeaderSections property provides access to the collection of column headers displayed by the multi column list box.  To manage elements of this collection at design-time, click the ellipsis button corresponding to the property.   The standard collection editing dialog will be displayed.  You can use its buttons to add, delete and move column headers.  Select items corresponding to the desired column headers to access their properties via the Object Inspector.  The image below shows an example.

Note that the number of columns displayed by the multi column list box is specified by the number of items within the HeaderSections collection.

Each element in the collection is represented by the TcxHeaderSection class.  Please refer to this class description for details on settings it provides.  Note however, that the multi column list box control uses headers not only for display purposes.  If a header’s AllowClick property is set to True, end users are allowed to click headers to toggle sorting by values of the corresponding column.  The sort order can also be specified by the SortOrder property either at design or runtime.

Please refer to the  Populating a Multi Column ListBox with Items topic for additional information on the HeaderSections property and related members.


TcxMCListBox.IntegralHeight

TcxMCListBox          See Also

Specifies whether the multi column list box control can display partial items.

property IntegralHeight: Boolean;

Description

If the IntegralHeight property value is False, the list box control can display partial items if they don’t completely fit into the control’s height.  The image below demonstrates an example of items partially displayed within MCListBox (the bottom item doesn’t fit into the control’s area completely).

If the IntegralHeight property is set to True, the height of the control is modified so that partial items are not displayed.  The control’s client area height is the multiple of the ItemHeight property value in this instance.  The image below displays the same control with the IntegralHeight property set to True.

The default value of the IntegralHeight property is False.


TcxMCListBox.ItemHeight

TcxMCListBox          See Also

Specifies the height of items in pixels.

property ItemHeight: Integer;

Description

The ItemHeight property specifies the height of the items within the multi column list box control.  The font applied to the items in the multi column list box also affects the item’s height and increases it automatically whenever it is necessary for display purposes.  (Use the Style property to access the style settings of the control in the normal state.)

The images below display list box controls with the ItemHeight property set to 16 and 32 pixels, respectively.

The default value of the ItemHeight property is 16.


TcxMCListBox.ItemIndex

TcxMCListBox          See Also

Specifies the index of the currently selected item.

property ItemIndex: Integer;

Description

If multiple item selection is prohibited (the MultiSelect property is set to False), the ItemIndex property specifies the index of the currently selected item.  Read this property to determine the selected item by its index.  If no item is currently selected, the ItemIndex property returns –1.  Assign the index of an item to this property to select the item (the previously selected item becomes deselected in this case).  Note that assigning –1 to this property clears the selection.  Assigning negative values or values that exceed the index of the last available item has no effect.  The index of the last available item can be obtained using the Items.Count property.

If the multiple item selection feature is enabled (the MultiSelect property value is True), the ItemIndex property returns the index of the item whose selected state was last changed.  Assigning values to this property produces no effect.

When multiple item selection is allowed, use the Selected property to change the selected state of items.

Please refer to the Working with Selections topic for more information regarding selections.


TcxMCListBox.Items

TcxMCListBox          See Also

Specifies data displayed by the multi column list box control.

property Items: TStrings;

Description

Use the Items property to supply data for the multi column list box control.  This property is represented by a TStrings object which is the collection of text lines.  Each text line corresponds to a row in the control.  Column values are separated from one another using the character specified by the Delimiter property.

Please refer to the Populating a Multi Column ListBox with Items topic for more information about populating the control with data.


TcxMCListBox.MultiLines

TcxMCListBox          See Also

Specifies whether column values can be word wrapped.

property MultiLines: Boolean;

Description

Use the MultiLines property to specify whether column values must be word wrapped if they don’t fit into columns.  Set this property to True to allow word wrapping.  In this instance, if a column values doesn’t fit into the column, the value occupies several lines so that it is displayed completely.  Note that the there can be situations wherein the MultiLines property value is True, but the column value is partially visible.  This occurs if column width is so small that individual words cannot be displayed completely.

If the MultiLines property value is False, column values are displayed in a single line independant of whether they are displayed completely.  In this instance, you can specify how the text should be truncated using the ShowEndEllipsis property.

Images below show the same multi column list box control when the MultiLines property is set to False and True respectively.  Odd items are selected in the second screenshot so you can see which items occupy multiple lines.

The default value of the MultiLines property is False.


TcxMCListBox.MultiSelect

TcxMCListBox          See Also

Specifies whether several items can be selected at the same time.

property MultiSelect: Boolean;

Description

Set the MultiSelect property to True to enable the multiple item selection feature.  In this instance, you can control the selected state of each individual item independently using the Selected property.  End users are also allowed to perform multiple selections.  Please refer to the ExtendedSelect property description for details on how they can perform this.

If the MultiSelect property value is False, only a single item can be selected at a time.  This implies that selecting an item deselects the previously selected item.

See the Working with Selections topic for additional information on members related to item selection.

The default value of the MultiSelect property is False.


TcxMCListBox.OverflowEmptyColumn

TcxMCListBox          See Also

Specifies the behavior of the control when all column values are not supplied for a row.

property OverflowEmptyColumn: Boolean;

Description

Data is supplied for the multi column list box control using the Items property.  This property holds a collection of text lines – one line per each data row.  Column values are separated from each other using a character specified by the Delimiter property.

You may at times want to display a string across a number of columns.  For this purpose, you can specify a single value within a data row and set the OverflowEmptyColumn property to True.  In this instance, the next column will not truncate the specified value.  Also, you can specify values for several of the first columns.  In this instance, the value of the last column will be displayed throughout the remaining columns.

The image below shows an example of the Items property.

The next image shows the control’s appearance when the OverflowEmptyColumn property is set to False and True respectively.  Note that the last line is truncated in the former.

Please refer to the Populating a Multi Column ListBox with Items topic for more details on supplying data for the multi column list box control.

The default value of the OverflowEmptyColumn is True.


TcxMCListBox.SelCount

TcxMCListBox          See Also

Returns the number of selected items.

property SelCount: Integer;

Description

Use the SelCount property to obtain the number of currently selected items.  Note that this property returns a valid number only when the MultiSelect property is set to True (multiple item selection feature is enabled).  Otherwise, the SelCount property always returns –1.

If you need to determine whether any item is selected when multiple item selection is prohibited, use the ItemIndex property.  If this property’s return value is –1, none of the items is selected.  Otherwise, the ItemIndex property value is the index of the selected item.

The SelCount property value is useful, for instance, when you need to copy text of selected items into an array.  It enables you to set the array’s dimensions before it is filled with data.  Also, it can be used to determine whether at least one item is selected before performing actions on the selection.

The following sample code inverts the selection within the multi column list box control.  First it checks whether there are any items selected using the SelCount property.  If no item is selected, the SelectAll method is called.  Otherwise, the selected state of each item is toggled using the Selected property.

// Delphi

procedure InvertSelection(MCListBox: TcxMCListBox);

var I: Integer;

begin

  if MCListBox.SelCount = 0 then

    MCListBox.SelectAll

  else

  begin

    for I := 0 to MCListBox.Items.Count - 1 do

      MCListBox.Selected[I] := not MCListBox.Selected[I];

  end;

end;

Note:	The SelCount property cannot be used to traverse through selected items, since the control doesn’t store these items in a separate collection.  To visit each selected item, you need to traverse through all the items and check whether the Selected property returns True for the corresponding item index.  Please refer to the Selected property description for details.

Please refer to the Working with Selections topic for additional information on selections.

ReadOnly property


TcxMCListBox.Selected

TcxMCListBox          See Also

Defines the selected state of the specified item.

property Selected[Index: Integer]: Boolean;

Description

Use the Selected property to set or obtain the selected state of the specified item.  The item is specified by its index via the Index parameter.  Note that item indexes are zero based.  The index of the last item is the Items.Count property value decremented by one.  If the specified index is negative or exceeds the last available index, an exception is raised.

When the multiple item selection feature is enabled, the Selected property can be used to change the selected state of each item independently.  However, if it is disabled, selecting an item using the Selected property deselects the previously selected item.  To enable the multi selection feature, set the MultiSelect property to True.

The following procedure can be used to invert the selection within the specified multi column list box.  It first checks whether any item is selected by comparing the SelCount property to 0.  If no item is selected, the SelectAll method is called.  Otherwise, the procedure toggles the selected state of all items.

// Delphi

procedure InvertSelection(MCListBox: TcxMCListBox);

var I: Integer;

begin

  if MCListBox.SelCount = 0 then

    MCListBox.SelectAll

  else

  begin

    for I := 0 to MCListBox.Items.Count - 1 do

      MCListBox.Selected[I] := not MCListBox.Selected[I];

  end;

end;

Please refer to the Working with Selections topic for details on selecting items when the multi selection feature is enabled and disabled.


TcxMCListBox.ShowColumnLines

TcxMCListBox          See Also

Specifies whether column lines are visible.

property ShowColumnLines: Boolean;

Description

Use the ShowColumnLines property to specify the visibility of column lines.  If set to True, column lines are displayed.  Otherwise, they are hidden.  Note that you can use the ColumnLineColor property to change the color of column lines.

Images below show the same multi column list box control when the ShowColumnLines property is set to True and False respectively.

The default value of the ShowColumnLines property is True.


TcxMCListBox.ShowHeader

TcxMCListBox

Indicates whether column headers are displayed within the list box control.

property ShowHeader: Boolean;

Description

Use the ShowHeader property to determine whether column headers are displayed within the list box control.  If this property value is False, there are no column headers within the control.  This means that sorting cannot be applied to the dropdown list by clicking column headers.  In this case, the dropdown list can be sorted by changing the SortOrder property value of the required column.

The default value of the ShowHeader property is True.


TcxMCListBox.ShowEndEllipsis

TcxMCListBox          See Also

Specifies whether ellipses are displayed at the end of values that don’t fit into columns.

property ShowEndEllipsis: Boolean;

Description

If values don’t fit into columns you can force them to be word wrapped by setting the MultiLines property to True.  Otherwise, such values are displayed in a single line.  In this case, you can specify whether ellipses must be displayed at the end of values that don’t fit into columns.  To display them set the ShowEndEllipsis property to True.  Otherwise, values are simply truncated by the column border.

Images below show the same multi column list box when the ShowEndEllipsis property is set to True and False respectively.  (The MultiLines property is set to False.)

The default value of the ShowEndEllipsis property is True.


TcxMCListBox.Sorted

TcxMCListBox

Specifies whether items of the list box are alphabetically sorted.

property Sorted: Boolean;

Description

Set the Sorted property to True to sort items of the list box alphabetically.  Note that items are sorted in ascending order.  Changing item contents or adding new items to the list forces the control to resort items.  Note that entire strings stored within the Items property are compared to implement sorting.  So, if the first column contains the same values, the order of these items is determined by the contents of the following columns.  Also note, that setting the Sorted property to True changes the order of items within the Items collection.

If the Sorted property is False, items are not sorted.  New items can be added to any position within the collection.  Note however, that setting the Sorted property to False after it was set to True doesn’t change the order of items to the initial state.

Also note, that when the Sorted property value is False, you can allow end users to sort items by any column value.  To implement this, you must set the AllowClick property of TcxHeaderSection objects representing header sections to True.  These objects can be accessed via the HeaderSections property.  If this has been performed, end users can click column headers to sort items against values of the column.  The first click applies sorting in ascending order.  Following clicks toggle sort order.  When sorted, column headers display special images identifying current sort order.  See the image below for clarification.

Sorting the list box by clicking column headers also changes the order of items in the Items collection.

The default value of the Sorted property is False.


TcxMCListBox.TopIndex

TcxMCListBox

Specifies the index of the item that is displayed at the top of the control.

property TopIndex: Integer;

Description

If all items don’t fit into the control vertically, the control displays a vertical scroll bar so that end users can access all items.  You can use the TopIndex property to determine the index of the item currently displayed at the top of the list (the position where end users have scrolled).  Also, the TopIndex property can be used to scroll through the list programmatically.  Set this property to the index of the desired record to scroll the view so that the record becomes the first in the visible list.

Note that indexes of items are zero based.  Thus, the TopIndex property can accept values between zero and the last available item index.  The index of the last item is the Items.Count property value decremented by one.  Setting the TopIndex property to a value outside of this range has no effect.

Note also, that the control cannot be scrolled downward so that it is partially empty.  (The last item cannot be displayed higher than the bottom of the control.  This is only possible when the number of items is small, so that the control height exceeds their total height.)


TcxMCListBox.AddItem

TcxMCListBox          See Also

Adds the specified item to the multi column list box.

procedure AddItem(AItem: string; AObject: TObject);

Description

The AddItem method enables you to add a new item to the end of the list box.  The AItem parameter specifies the text of the item.  The text must contain column values separated by the character specified by the Delimiter property.  The AObject parameter specifies the object associated with an item.  Such objects can be accessed via the Items.Objects property of the control.

In fact, calling the AddItem method of the control is equivalent to calling the AddObject method of the TStrings object representing the Items property value.  This method is introduced for your convenience only.  Please refer to the TStrings class documentation for more information on methods that allow you to manage an items collection.

See the Populating a Multi Column ListBox with Items topic for additional information about supplying data for the multi column list box.


TcxMCListBox.Clear

TcxMCListBox          See Also

Removes all items from the multi column list box control.

procedure Clear;

Description

Call the Clear method to remove all items from the list box.  Note that calling this method is equivalent to calling the Clear method of the TStrings object representing the Items property.

Please refer to the Items property and TStrings object descriptions for more information on managing the collection of items displayed within the list box.


TcxMCListBox.ClearSelection

TcxMCListBox          See Also

Deselects all items in the multi column list box control.

procedure ClearSelection;

Description

Call the ClearSelection method to deselect all currently selected items.  After this method is called, the Selected property returns False for all items.  Note also, that calling this method is equivalent to assigning –1 to the ItemIndex property when the multi selection feature is disabled (the MultiSelect property value is False).

If you need to select all items at once, call the SelectAll method.  If the selected state of individual items needs to be controlled, use the Selected property.

Please refer to the Working with Selections topic for additional information.


TcxMCListBox.CopySelection

TcxMCListBox          See Also

Copies selected items to the specified list control.

procedure CopySelection(ADestination: TCustomListControl);

Description

Use the CopySelection method to copy the currently selected items (the corresponding strings from the Items property) to the specified list control.  The target control is specified by the ADestination parameter.  This parameter is of the TCustomListControl type.  Thus, you can pass any descendant control to this method.  Descendants of the TCustomListControl class are list boxes, combo boxes and list views.

The sample line of code below copies the selection to a combo box control.

// Delphi

cxMCListBox1.CopySelection(ComboBox1);

The image below shows the result of executing the code listed above.

The next line of code can be used to copy the selection from one multi column list box to another.

// Delphi

cxMCListBox1.CopySelection(cxMCListBox2.InnerListBox);

Visually, it may seem that only values of two first columns have been copied to the destination list box.  However, strings from the Items property are copied completely.  If one more column is added to the target control, birth year values will also be displayed.

Note also, that source and target list boxes must have the same value for the Delimiter property.  Otherwise, controls will break strings into column values in different ways.

If you need to delete the selection or move it to another list control, use the DeleteSelected and MoveSelection methods respectively.

See the Working with Selections topic for information on selecting items in the multi column list box.


TcxMCListBox.DeleteSelected

TcxMCListBox          See Also

Removes the currently selected items.

procedure DeleteSelected;

Description

Use the DeleteSelected method to remove selected items from the multi column list box control.  Refer to the Working with Selections topic for details on how to select items.

If you need to delete individual items from the list box, use the Delete method of the TStrings object representing the Items property value.


TcxMCListBox.ItemAtPos

TcxMCListBox

Returns the index of the item located under the specified point.

function ItemAtPos(const APos: TPoint; AExisting: Boolean): Integer;

Description

Use the ItemAtPos method to determine the item located under the specified point.  The test point is specified by the APos parameter.  This parameter must specify the point in the control’s client coordinates (relatively to its top-left corner).  If you have screen coordinates, use the ScreenToClient method of the control to obtain the control’s client coordinates.

The AExisting parameter value affects the return value of the ItemAtPos method.  If True, the method will return –1 if the specified point is within the control but below the last item.  Otherwise, the method will return the index of the last item in such cases.

Most commonly, the ItemAtPos method is used to determine the item located under the mouse cursor.  The following sample code shows how this can be used.  It handles the OnMouseDown event to select the right-clicked item and invoke the popup menu.  The popup menu must contain a single item that removes selected items from the control.  Below are the handlers of the menu item’s OnClick and list box’s OnMouseDown events.

// Delphi

procedure TForm1.Delete1Click(Sender: TObject);

begin

  cxMCListBox1.DeleteSelected;

end;

procedure TForm1.cxMCListBox1MouseDown(Sender: TObject;

  Button: TMouseButton; Shift: TShiftState; X, Y: Integer);

var

  ClickedItemIndex: Integer;

  PopupMenuOrigin: TPoint;

begin

  if Button <> mbRight then Exit;

  ClickedItemIndex := cxMCListBox1.ItemAtPos(Point(X, Y - 16), True);

  if ClickedItemIndex <> -1 then

  begin

    cxMCListBox1.ClearSelection;

    cxMCListBox1.Selected[ClickedItemIndex] := True;

    PopupMenuOrigin := cxMCListBox1.ClientToScreen(Point(X, Y));

    PopupMenu1.Popup(PopupMenuOrigin.X, PopupMenuOrigin.Y);

  end;

end;

The result of handling events in such a manner is illustrated in the image below.


TcxMCListBox.ItemRect

TcxMCListBox

Gets the bounding rectangle of the specified item.

function ItemRect(Index: Integer): TRect;

Description

The ItemRect method is used to obtain the bounding rectangle of the specified item.   The item is specified by its index via the Index parameter.  Note that items are zero-based indexed.  The index of the last available item is the Items.Count property value decremented by one.  If a value outside the allowed range is specified as the Index parameter, an empty rectangle (with all dimensions set to zero) is returned.

Most commonly, you will have no need to use the ItemRect method in applications.  To determine the item located at the specified point, use the ItemAtPos method.


TcxMCListBox.SelectAll

TcxMCListBox          See Also

Selects all items in the multi column list box.

procedure SelectAll;

Description

Use the SelectAll method to select all items in the list box.  Note that this method is only in effect when the multiple item selection feature is enabled (the MultiSelect property value is True).  Otherwise, calling this method has no effect.

If you need to deselect all the items, call the ClearSelection method.  The selected state of individual items can be controlled using the Selected property.  Refer to the Working with Selections topic for additional information.


TcxMCListBox.MoveSelection

TcxMCListBox          See Also

Moves the currently selected items to the specified list control.

procedure MoveSelection(ADestination: TCustomListControl);

Description

The MoveSelection method moves items selected within the caller control to the specified list control.  The target control is specified by the ADestination parameter which is of the TCustomListControl type.  This type implies that any list control (TCustomListControl descendant) can be passed to the MoveSelection method as the parameter.  List controls are list boxes, combo boxes and list views.

The MoveSelection method works just as the CopySelection method.  The only difference is that the MoveSelection method deletes the copied items.  Please refer to the CopySelection method description for examples of using these methods.

See the Working with Selections topic for additional information about selecting items in the multi column list box control.


Populating a Multi Column ListBox with Items

See Also

The TcxMCListBox control enables you to display information arranged into a number of columns.  This topic describes how to specify the number of columns to be displayed and how to fill the control with data.

When you place a TcxMCListBox control onto the form, it displays a single column.  To access settings of this column and add other columns to the control, click the ellipsis button corresponding to the HeaderSections property.  The columns collection editor will appear.  Use its buttons to add, delete and move columns.  Select individual items to display the properties of corresponding columns within the Object Inspector.

Note that the HeaderSections property is represented by the TcxHeaderSections class.  Each individual item of the collection is a TcxHeaderSection object.  Please refer to the corresponding reference topics for details on managing the collection via code and information about settings of each individual header item.

Rename the first header section to First Name.  Add two more sections and set their captions to Second Name and Birth Year.  The image below shows the appearance of the collection editor, the Object Inspector and the control itself.

Now it is time to fill the columns with data.  For this purpose, click the ellipsis button corresponding to the Items property of the control.  The standard String List Editor dialog will appear.  Type in data – one string per each row.  Values of each column must be delimited from one another using the semicolon (;) character.  The image below shows a sample of data input and the resulting control.

Note that you can change the character that separates column values.  Use the Delimiter property for this purpose.  For instance, if this property is set to ‘#’, the string list must look as follows:

Finally, the TcxMCListBox control enables you to display strings across individual columns.  This means that you can provide values for first column and have the value appear across all columns.  If the OverflowEmptyColumn property is set to True, the text in the last column will overflow into the remaining columns.  See the example below.  The last string sets text only for two columns.  Thus, the second column’s text is displayed throughout the third column.


Working with Selections

See Also

By default, the TcxMCListBox control allows end users to select a single item at a time.  The selected item is specified by its index using the ItemIndex property.  You can use this property to obtain the index of the currently selected item or to move selection to another item.

The multi column list box control also allows you to enable the multi selection feature.  This is performed by setting the MultiSelect property to True.  If enabled, you can specify the selected state for each individual item using the Selected property.  The number of currently selected items can be obtained via the SelCount property.

When the multi selection feature is enabled, end users can select items in two ways, depending on the ExtendedSelect property value:

•	If set to True, end users can click items holding the CTRL key pressed to toggle their selection state.  They can also click items holding the SHIFT key pressed to select continuous item ranges.

•	If set to False, end users can toggle selected state of items using simple clicks.  Continuous selections are not allowed in this instance.

The multi column list box control also provides a number of methods useful when working with multiple selections.  Most of them are in effect independently of whether the multi selection feature is enabled.  These methods are:

Method	Description
ClearSelection	Clears the selection.  None of the items are selected after this method call.
CopySelection	Copies selected items from the caller to the specified list control.  The copied items are added to the end of the destination control’s items collection.
DeleteSelected	Deletes selected items.
MoveSelection	Moves the selected items from the caller to the specified list control.  The moved items are added to the end of the destination control’s items collection.
SelectAll	Select all items within the multi column list box.  This method is in effect only when the multi selection feature is enabled.


cxMemo Unit Overview
cxMemo Unit

Classes

TcxCustomMemo

TcxCustomMemoProperties

TcxMemo

TcxMemoProperties


TcxCustomMemo
TcxCustomMemo Object

Hierarchy          Properties          Methods          Events          See Also

Represents the base class for multi-line editors.

Unit

cxMemo

TcxCustomMemo = class(TcxCustomTextEdit);

Description

The TcxCustomMemo control allows displaying multi-line text.  It provides the Lines property, which defines the list of strings displayed by a memo editor.

The Properties member defines a number of settings specific to editors.  They define the text alignment, the maximum text length, read-only status and many others.  The behavior of a memo control is similar to a standard TMemo component.

Use the Style, StyleDisabled, StyleFocused and StyleHot properties to adjust the look & feel of an editor.  Working with styles is discussed in the TcxCustomEditStyle class topic.

Do not create instances of TcxCustomMemo.  Use its descendants such as TcxMemo or TcxDBMemo instead.


TcxCustomMemo Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |


Properties for TcxCustomMemo
TcxCustomMemo Properties

TcxCustomMemo          Legend

In TcxCustomMemo

ActiveProperties

CaretPos

Lines

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxCustomMemo
TcxCustomMemo Methods

TcxCustomMemo          Legend

Derived from TcxCustomTextEdit

Clear

ClearSelection

CopyToClipboard

Create

CutToClipboard

SelectAll

SetSelection

Undo

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

SetSize

ValidateEdit


Events for TcxCustomMemo
TcxCustomMemo Events

TcxCustomMemo          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCustomMemo.ActiveProperties

TcxCustomMemo         See Also

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

property ActiveProperties: TcxCustomMemoProperties;

Description

Use the ActiveProperties property to obtain the properties of the current memo editor that are currently in effect.  This property is especially useful when the memo 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 memo editor.  Otherwise, the inherent memo editor’s properties are returned.

ReadOnly Property


TcxCustomMemo.CaretPos

TcxCustomMemo

Determines the caret's position within a memo editor.

property CaretPos: TPoint;

Description

Use CaretPos to get and set the position of the caret in terms of the characters of text.  The X and Y fields of the TPoint class specify the column and line (row) at which the caret is located within a memo editor.


TcxCustomMemo.Lines

TcxCustomMemo

Represents a list of strings displayed by a memo editor.

property Lines: TStrings;

Description

Use Lines to manipulate text within a memo control.  Using methods and properties of the TStrings class, you can add, delete or access a specific line of text.  The Text property is inherited from the TControl class and it allows you to work with all the text at once.


TcxCustomMemo.Properties

TcxCustomMemo          See Also

Defines settings specific to memo editors.

property Properties: TcxCustomMemoProperties;

Description

The Properties object specifies various settings for memo editors.  Use the ScrollBars member of a Properties instance to display scrollbars (vertical and/or horizontal).  Other properties adjust alignment and maximum length of text, char case and many other attributes.


TcxCustomMemoProperties
TcxCustomMemoProperties Object

Hierarchy          Properties          Methods          Events          See Also

Contains settings specific to memo controls.

Unit

cxMemo

TcxCustomMemoProperties = class(TcxCustomTextEditProperties);

Description

The TcxCustomMemoProperties class extends the TcxCustomTextEditProperties functionality and provides additional properties specific to memo controls.  To set memo properties, use the Properties member of a corresponding editor class.  The TcxMemoProperties class derives from TcxCustomMemoProperties and publishes the necessary members to access from the TcxCustomMemo editors.

Different settings for memo controls include Alignment, ScrollBars, VisibleLineCount, WantReturns, WantTabs and WordWrap.  Most of these are similar to those of the TMemo component.


TcxCustomMemoProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |


Properties for TcxCustomMemoProperties
TcxCustomMemoProperties Properties

TcxCustomMemoProperties          Legend

In TcxCustomMemoProperties

Alignment

AutoSelect

ScrollBars

VisibleLineCount

WantReturns

WantTabs

WordWrap

Derived from TcxCustomTextEditProperties

AssignedValues

CharCase

DisplayFormat

EchoMode

EditFormat

HideCursor

HideSelection

ImeMode

ImeName

IncrementalSearch

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 TcxCustomMemoProperties
TcxCustomMemoProperties Methods

TcxCustomMemoProperties          Legend

Derived from TcxCustomTextEditProperties

IsDisplayValueValid

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue


Events for TcxCustomMemoProperties
TcxCustomMemoProperties Events

TcxCustomMemoProperties          Legend

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomMemoProperties.Alignment

TcxCustomMemoProperties

Defines the horizontal alignment of text displayed by a memo control.

type

  TAlignment = (taLeftJustify, taRightJustify, taCenter);

property Alignment: TAlignment;

Description

Use the Alignment property to set text alignment.  The following table lists possible alignment formats:

Value	Meaning
taLeftJustify	Text is aligned to the left side of a control.
taCenter	Text is centered horizontally.
taRightJustify	Text is aligned to the right side of a control.

Data-aware editors have horizontal alignment by default.  When an editor represents data from a TDataSet, the default alignment is defined by the TField.Alignment property.  You can redefine the alignment for data-aware controls by setting it via the Alignment property.  To restore the default alignment, use the RestoreDefaults method.


TcxCustomMemoProperties.AutoSelect

TcxCustomMemoProperties

Determines whether the memo control’s contents are automatically selected when the memo control receives focus.

property AutoSelect: Boolean;

Description

Setting the AutoSelect property to True selects the memo control’s contents when it receives focus.

The default value of the AutoSelect property is False.


TcxCustomMemoProperties.ScrollBars

TcxCustomMemoProperties

Determines whether a memo editor has scroll bars.

type

  TScrollStyle = (ssNone, ssHorizontal, ssVertical, ssBoth, ssAutoHorizontal, ssAutoVertical, ssBoth);

property ScrollBars: TScrollStyle;

Description

Use the ScrollBars property to provide a memo editor with horizontal and/or vertical scroll bars.  The following table lists all the relevant values for the ScrollBars property:

Value	Meaning
ssNone	A memo control does not have any scroll bars.
ssHorizontal	A horizontal scroll bar is displayed at the bottom of a control.
ssVertical	A vertical scroll bar is displayed at the right side of a control.
ssBoth	A memo has vertical and horizontal scrollbars.

The default value of the ScrollBars property is ssNone.


TcxCustomMemoProperties.VisibleLineCount

TcxCustomMemoProperties

Specifies the height (in text lines) of a memo editor.

property VisibleLineCount: Integer;

Description

Use the VisibleLineCount property to specify the height of a memo editor in text lines.  When the VisibleLineCount property is set to a value greater than 0 the control’s height is adjusted so as to display exactly the specified number of text lines.  The height of the editor cannot be modified in this case by setting the control’s Height property.

Setting the VisibleLineCount property to 0 indicates that the VisibleLineCount property’s value does not control the height of the memo editor, instead use the control’s Height to specify the height of the control in pixels.

The default value of the VisibleLineCount property is 0.


TcxCustomMemoProperties.WantReturns

TcxCustomMemoProperties

Specifies whether a user can insert return characters into text.

property WantReturns: Boolean;

Description

Set the WantReturns property to True to allow a user to insert return characters into text.  Otherwise, return characters are processed by a form.  If WantReturns is False, users can still enter return characters into text by pressing the Ctrl+Enter combination.

The default value of the WantReturns property is True.


TcxCustomMemoProperties.WantTabs

TcxCustomMemoProperties

Specifies whether a user can insert tab characters into text.

property WantTabs: Boolean;

Description

Set the WantTabs property to True to allow a user to insert tab characters into text.  Otherwise, pressing a tab character selects another control on a form.  If WantTabs is True, users can tab into an edit control, but they cannot tab out.

The default value of the WantTabs property is False.


TcxCustomMemoProperties.WordWrap

TcxCustomMemoProperties

Determines whether long strings are wrapped within a memo editor.

property WordWrap: Boolean;

Description

If WordWrap is True and there is no horizontal scroll bar, long strings are wrapped at the right edge of a memo control.  Otherwise, a long string that does not contain return characters is displayed in a single line.

The default value of the WordWrap property is True.


TcxMemo
 TcxMemo Object

Hierarchy          Properties          Methods          Events          See Also

Represents an edit control that allows editing memo data.

Unit

cxMemo

TcxMemo = class(TcxCustomMemo);

Description

The TcxMemo control represents an editor, which allows displaying multi-line text.  It provides the Lines property defining the list of strings displayed by a memo editor.

The Properties member defines a number of settings specific to editors.  They define text alignment, the maximum text length, read-only status and many others.  The behavior of a memo control is similar to a standard TMemo component.

Use the Style, StyleDisabled, StyleFocused and StyleHot properties to adjust the look & feel of an editor.  Working with styles is discussed in the TcxCustomEditStyle class topic.


TcxMemo Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMemo

     |


Properties for TcxMemo
TcxMemo Properties

TcxMemo          Legend

Derived from TcxCustomMemo

ActiveProperties

Lines

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName

Derived from TControl

Align


Methods for TcxMemo
TcxMemo Methods

TcxMemo          Legend

Derived from TcxCustomTextEdit

Clear

ClearSelection

CopyToClipboard

Create

CutToClipboard

SelectAll

SetSelection

Undo

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

SetSize

ValidateEdit


Events for TcxMemo
TcxMemo Events

TcxMemo          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxMemoProperties
TcxMemoProperties Object

Hierarchy          Properties          Methods          Events          See Also

Represents settings specific to memo editors.

Unit

cxMemo

TcxMemoProperties = class(TcxCustomMemoProperties);

Description

The TcxMemoProperties class provides various settings specific to memo editors.  Memo editors are presented by the TcxCustomMemo class descendants, such as TcxMemo and TcxDBMemo.  TcxMemoProperties does not introduce any new functionality, but publishes necessary properties and events inherited from base classes.  To set properties of memo editors, use the Properties member of a corresponding editor class.  To control any changes made to the editor’s DisplayFormat, EditFormat, MaxLength, MaxValue, MinValue and ReadOnly properties and reverse their values back to the default ones, use the AssignedValues property.

Different settings for memo controls include Alignment, ScrollBars, VisibleLineCount, WantReturns, WantTabs and WordWrap.  Most of these are similar to those of the TMemo component.


TcxMemoProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMemoProperties

     |


Properties for TcxMemoProperties
TcxMemoProperties Properties

TcxMemoProperties          Legend

Derived from TcxCustomMemoProperties

Alignment

AutoSelect

ScrollBars

VisibleLineCount

WantReturns

WantTabs

WordWrap

Derived from TcxCustomTextEditProperties

AssignedValues

CharCase

DisplayFormat

EchoMode

EditFormat

HideCursor

HideSelection

ImeMode

ImeName

IncrementalSearch

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 TcxMemoProperties
TcxMemoProperties Methods

TcxMemoProperties          Legend

Derived from TcxCustomTextEditProperties

IsDisplayValueValid

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue


Events for TcxMemoProperties
TcxMemoProperties Events

TcxMemoProperties          Legend

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


cxMRUEdit Unit Overview
cxMRUEdit Unit

Classes

TcxCustomMRUEdit

TcxCustomMRUEditProperties

TcxMRUEdit

TcxMRUEditProperties


TcxCustomMRUEdit
TcxCustomMRUEdit Object

Hierarchy          Properties          Methods          Events          See Also

Represents the base class for the text editors displaying the list of most recently used items (MRU) within a dropdown window.

Unit

cxMRUEdit

TcxCustomMRUEdit = class(TcxCustomComboBox);

Description

The TcxCustomMRUEdit class extends the TcxCustomComboBox functionality introducing the ability to display a list of items within a dropdown window.  TcxCustomMRUEdit maintains recently inputted text items at the top of the dropdown list.  When a new item is added, it is placed at the top of the list.  When an existing list item is accessed, it is also moved to the first position.  Use the AddItem method to add a new item or shift an existing item to the top of the list.  At runtime a new item is added when the editor loses focus.  An MRU editor supports the auto-completion feature, which enables a user to select an item from the list by typing its initial characters.

The Properties object controls various settings specific to MRU editors.  The LookupItems member allows you to access the list of items.  The number of items an MRU editor maintains can be limited by the MaxItemCount property.  By default, an MRU editor displays the ellipsis (…) button, which does not provide any functionality, except that it generates the OnButtonClick event.  To hide the ellipsis button set the ShowEllipsis property to False.

Use the Style, StyleDisabled, StyleFocused and StyleHot properties to adjust the look & feel of an editor.  Working with styles is discussed in the TcxCustomEditStyle class topic.

Do not create instances of TcxCustomMRUEdit.  Use its descendants such as TcxMRUEdit or TcxDBMRUEdit instead.


TcxCustomMRUEdit Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomComboBox

     |


Properties for TcxCustomMRUEdit
TcxCustomMRUEdit Properties

TcxCustomMRUEdit          Legend

In TcxCustomMRUEdit

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxCustomMRUEdit
TcxCustomMRUEdit Methods

TcxCustomMRUEdit          Legend

In TcxCustomMRUEdit

AddItem

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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCustomMRUEdit
TcxCustomMRUEdit Events

TcxCustomMRUEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCustomMRUEdit.ActiveProperties

TcxCustomMRUEdit          See Also

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

property ActiveProperties: TcxCustomMRUEditProperties;

Description

Use the ActiveProperties property to obtain the properties of the current MRU editor that are currently in effect.  This property is especially useful when the MRU 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 MRU editor.  Otherwise, the inherent MRU editor’s properties are returned.

ReadOnly Property


TcxCustomMRUEdit.Properties

TcxCustomMRUEdit          See Also

Specifies settings specific to MRU editors.

property Properties: TcxCustomMRUEditProperties;

Description

Use the Properties member to adjust various settings specific to MRU editors.  The Properties object maintains the list of most recently used items, defines the number of items to display and provides events to implement specific behavior as your needs dictate.


TcxCustomMRUEdit.AddItem

TcxCustomMRUEdit          See Also

Adds a new item or moves the existing one to the top of the dropdown list.

procedure AddItem(const Value: string); virtual;

Description

The AddItem method places the item passed as a Value parameter to the top of the dropdown list.  If the specified item already exists in the list, it is moved to the first position.  Thus, the AddItem method places most recently used items to the top of the list.  Use the Properties.LookupItems property to access this list.

Note:	When the Properties.MaxItemCount property is assigned a value greater than 0 and a new item is added to the list, which already contains Properties.MaxItemCount items the last item is removed from the list.  You can handle the Properties.OnDeleteLookupItem event to implement your own custom logic before the last item is removed.


TcxCustomMRUEditProperties
TcxCustomMRUEditProperties Object

Hierarchy          Properties          Methods          Events          See Also

Represents settings specific to MRU editors.

Unit

cxMRUEdit

TcxCustomMRUEditProperties = class(TcxCustomComboBoxProperties);

Description

An MRU editor maintains a list of Most Recently Used items within a dropdown window.  Various settings for editors are set via the Properties member of a corresponding editor class (for instance, TcxCustomMRUEdit.Properties).

TcxCustomMRUEditProperties extends functionality of the TcxCustomComboBoxProperties class, which introduces the settings controlling the dropdown list behavior.  The MaxItemCount property specifies the maximum number of items displayed by the list.  When this property is assigned a value greater than 0, you can handle the OnDeleteLookupItem event to implement your own custom logic before an MRU editor removes the last item from the dropdown list.  Use the LookupItems property to access this list.

By default, an MRU editor contains two buttons: a down-arrow button and an ellipsis (…) button.  The down-arrow button allows a user to open the dropdown list.  The ellipsis button does not provide any built-in functionality.  When a user clicks this button, the OnButtonClick event is generated.  Handle the OnButtonClick event to implement the required behavior as your needs dictate.  It is possible to hide the ellipsis button by setting the ShowEllipsis property to False.


TcxCustomMRUEditProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |

TcxCustomDropDownEditProperties

     |

TcxCustomComboBoxProperties

     |


Properties for TcxCustomMRUEditProperties
TcxCustomMRUEditProperties Properties

TcxCustomMRUEditProperties          Legend

In TcxCustomMRUEditProperties

MaxItemCount

ShowEllipsis

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

IncrementalSearch

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 TcxCustomMRUEditProperties
TcxCustomMRUEditProperties Methods

TcxCustomMRUEditProperties          Legend

Derived from TcxCustomMaskEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults


Events for TcxCustomMRUEditProperties
TcxCustomMRUEditProperties Events

TcxCustomMRUEditProperties          Legend

In TcxCustomMRUEditProperties

OnButtonClick

OnDeleteLookupItem

Derived from TcxCustomComboBoxProperties

OnDrawItem

OnMeasureItem

Derived from TcxCustomDropDownEditProperties

OnCloseQuery

OnCloseUp

OnInitPopup

OnPopup

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomMRUEditProperties.MaxItemCount

TcxCustomMRUEditProperties          See Also

Defines the maximum number of items displayed in the dropdown list.

property MaxItemCount: Integer;

Description

Use the MaxItemCount property to define the maximum number of items which a MRU editor can represent.  To access a list of items read the LookupItems property.  If MaxItemCount is set to 0, the number of items is unlimited.  A new value is stored as a new item within the dropdown list when input is confirmed.  A most recently used item is placed at the top of the list by replacing existing items or shifting them down.

The default value of the MaxItemCount property is 0.


TcxCustomMRUEditProperties.ShowEllipsis

TcxCustomMRUEditProperties          See Also

Specifies whether to display the ellipsis (…) button within an MRU editor.

property ShowEllipsis: Boolean;

Description

Set the ShowEllipsis property to False to hide the ellipsis button within an MRU editor.  If the ShowEllipsis property is True, it is possible to provide an additional functionality to the editor by handling the OnButtonClick event.

The default value of the ShowEllipsis property is True.


TcxCustomMRUEditProperties.OnButtonClick

TcxCustomMRUEditProperties          See Also

Occurs when a user clicks the ellipsis (…) button within an MRU editor.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnButtonClick: TNotifyEvent;

Description

The OnButtonClick event allows you to implement specific behavior for an MRU editor when a user clicks the ellipsis button.  It is possible to hide the ellipsis button by setting the ShowEllipsis property to False.  In this instance, the event is not generated.  To handle the situation when a user presses the down-arrow button use the OnPopup event.


TcxCustomMRUEditProperties.OnDeleteLookupItem

TcxCustomMRUEditProperties          See Also

Occurs before an MRU editor removes the last item from the dropdown list.

type

  TcxMRUEditDeleteLookupItemEvent = procedure(AProperties: TcxCustomMRUEditProperties; AItemIndex: Integer) of object;

property OnDeleteLookupItem: TcxMRUEditDeleteLookupItemEvent;

Description

This event is fired provided that the MaxItemCount property is assigned a value greater than 0 and a new item is added to the LookupItems list, which already contains MaxItemCount items.  In this instance, the last item is removed from the list.  The index of the item being removed is passed as the event’s AItemIndex parameter.  The AProperties parameter allows you to access the properties of the MRU editor.


TcxMRUEdit
 TcxMRUEdit Object

Hierarchy          Properties          Methods          Events          See Also

Represents a text editor displaying the list of most recently used items (MRU) within a dropdown window.

Unit

cxMRUEdit

TcxMRUEdit = class(TcxCustomMRUEdit);

Description

A TcxMRUEdit control represents a text editor that stores the most recently inputted strings in the associated dropdown list.  The most recently accessed are placed at the top of the list.  When a new string is added, it is placed at the top of the list.  When an existing item is accessed, it is shifted to the first position.

The next image demonstrates the MRU editor painted in the XP style:

The TcxMRUEdit class does not provide any new functionality but publishes the properties declared in base classes.  The Properties object controls various settings specific to MRU editors.


TcxMRUEdit Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomComboBox

     |

TcxCustomMRUEdit

     |


Properties for TcxMRUEdit
TcxMRUEdit Properties

TcxMRUEdit          Legend

Derived from TcxCustomMRUEdit

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxMRUEdit
TcxMRUEdit Methods

TcxMRUEdit          Legend

Derived from TcxCustomMRUEdit

AddItem

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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxMRUEdit
TcxMRUEdit Events

TcxMRUEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxMRUEditProperties
TcxMRUEditProperties Object

Hierarchy          Properties          Methods          Events          See Also

Represents settings specific to MRU editors.

Unit

cxMRUEdit

TcxMRUEditProperties = class(TcxCustomMRUEditProperties);

Description

The TcxMRUEditProperties class provides properties specific to MRU editors.  An MRU editor maintains a list of Most Recently Used items within a dropdown window.  Various options for editors are set via the Properties member of a corresponding editor class.  To control any changes made to the editor’s DisplayFormat, EditFormat, MaxLength, MaxValue, MinValue and ReadOnly properties and reverse their values back to the default ones, use the AssignedValues property.

TcxMRUEditProperties does not provide any new functionality but publishes the properties declared in base classes.  Properties specific to MRU editors are introduced by the TcxCustomMRUEditProperties class.


TcxMRUEditProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |

TcxCustomDropDownEditProperties

     |

TcxCustomComboBoxProperties

     |

TcxCustomMRUEditProperties

     |


Properties for TcxMRUEditProperties
TcxMRUEditProperties Properties

TcxMRUEditProperties          Legend

Derived from TcxCustomMRUEditProperties

MaxItemCount

ShowEllipsis

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

IncrementalSearch

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 TcxMRUEditProperties
TcxMRUEditProperties Methods

TcxMRUEditProperties          Legend

Derived from TcxCustomMaskEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults


Events for TcxMRUEditProperties
TcxMRUEditProperties Events

TcxMRUEditProperties          Legend

Derived from TcxCustomMRUEditProperties

OnButtonClick

OnDeleteLookupItem

Derived from TcxCustomComboBoxProperties

OnDrawItem

OnMeasureItem

Derived from TcxCustomDropDownEditProperties

OnCloseQuery

OnCloseUp

OnInitPopup

OnPopup

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxDBMRUEdit
 TcxDBMRUEdit Object

Hierarchy          Properties          Methods          Events          See Also

Represents a data-aware text editor that stores the list of most recently used items and allows the selection of a value from this list.

Unit

cxDBEdit

TcxDBMRUEdit = class(TcxCustomMRUEdit);

Description

A TcxDBMRUEdit control allows the editing of the contents of a text dataset field. This control represents a text editor that stores the most recently inputted strings in the associated dropdown list.  The most recently accessed are placed at the top of the list.  When a new string is added, it is placed at the top of the list.  When an existing item is accessed, it is shifted to the first position.

The next image demonstrates the MRU editor painted in the XP style:

The TcxDBMRUEdit class introduces the DataBinding property which allows you to connect a control to a dataset via the DataBinding.DataSource and DataBinding.DataField properties.

The Properties object controls various settings specific to MRU editors.


TcxDBMRUEdit Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomComboBox

     |

TcxCustomMRUEdit

     |


Properties for TcxDBMRUEdit
TcxDBMRUEdit Properties

TcxDBMRUEdit          Legend

In TcxDBMRUEdit

DataBinding

Derived from TcxCustomMRUEdit

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxDBMRUEdit
TcxDBMRUEdit Methods

TcxDBMRUEdit          Legend

Derived from TcxCustomMRUEdit

AddItem

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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxDBMRUEdit
TcxDBMRUEdit Events

TcxDBMRUEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxDBMRUEdit.DataBinding

TcxDBMRUEdit

Specifies the connection to a dataset.

property DataBinding: TcxDBTextEditDataBinding;

Description

Use the DataBinding property to access a TcxDBTextEditDataBinding instance via which the connection with a dataset is established.  To allow the TcxDBMRUEdit control to edit a specific field value from the dataset set the DataSource and DataField properties of the DataBinding object.


cxProgressBar Unit Overview
cxProgressBar Unit

Classes

TcxCustomProgressBar

TcxCustomProgressBarProperties

TcxProgressBar

TcxProgressBarProperties


TcxCustomProgressBar
TcxCustomProgressBar Object

Hierarchy          Properties          Methods          Events

Serves as the base for progress bar controls.

Unit

cxProgressBar

TcxCustomProgressBar = class(TcxCustomEdit)

Description

The TcxCustomProgressBar class is the ancestor of the TcxProgressBar which represents a progress bar control.  It implements all the functionality needed by its descendant.  The TcxProgressBar class simply publishes some of these properties.

The primary features implemented by the TcxCustomProgressBar class are listed below:

•	Vertical orientation support (see the Properties.Orientation and Properties.TextOrientation property);

•	Multiple fill styles support – solid, gradient, rectangles, bitmaps (see the Properties.BarStyle and Properties.ForegroundImage properties);

•	Overload bar support – the bar can be divided into two parts with different styles (see the Properties.ShowOverload property);

•	Peak value support – the progress bar is capable of displaying a peak value (see the Properties.ShowPeak property);

•	Two text styles support – the progress bar can display the current position or a percentage (see the Properties.ShowTextStyle property);

•	XP theme support (see the Style.LookAndFeel.NativeStyle property).

The images below show possible appearances of the progress bar control derived from the TcxCustomProgressBar class.

Do not create instances of the TcxCustomProgressBar class in your applications.  If you need a progress bar, use the TcxProgressBar control.  The TcxCustomProgressBar class should be used to derive other progress bar controls.


TcxCustomProgressBar Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |


Properties for TcxCustomProgressBar
TcxCustomProgressBar Properties

TcxCustomProgressBar          Legend

In TcxCustomProgressBar

ActiveProperties

Position

Properties

Derived from TcxCustomEdit

ActiveProperties

AutoSize

DataBinding

EditModified

EditValue

InnerEdit

ModifiedAfterEnter

Properties

RepositoryItem

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxCustomProgressBar
TcxCustomProgressBar Methods

TcxCustomProgressBar          Legend

In TcxCustomProgressBar

Create

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit


Events for TcxCustomProgressBar
TcxCustomProgressBar Events

TcxCustomProgressBar          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCustomProgressBar.ActiveProperties

TcxCustomProgressBar          See Also

Obtains the properties that are currently applied to a progress bar.

property ActiveProperties: TcxCustomProgressBarProperties;

Description

Use the ActiveProperties property to obtain the properties of the current progress bar that are currently in effect.  This property is especially useful when the progress bar 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 progress bar.  Otherwise, the inherent progress bar’s properties are returned.

ReadOnly Property


TcxCustomProgressBar.Position

TcxCustomProgressBar          See Also

Specifies the position of the progress bar.

property Position: Double;

Description

Use the Position property to specify the current position of the progress bar.  The position can vary within the range specified by the Properties.Min and Properties.Max properties.  If the Position property’s value is the same as the Properties.Min property, no bar is displayed.  If it is the same as the Properties.Max property value, the bar fills the entire control.  Note that the Position property cannot be set to a value outside of these bounds.

If the Properties.ShowText property is set to True, the progress bar control displays textual information about the current position of the bar.  The way in which this information is presented is controlled by the Properties.ShowTextStyle property.  If this property’s value is cxtsPosition, the Position property value is displayed.  If it is cxtsPercent, the progress percentage is shown.

The table below shows examples of different Position property values.  Assume that Properties.Min is –10 and Properties.Max is 20.

Position	ShowTextStyle = cxtsPosition	ShowTextStyle = cxtsPercent
-10
0
10

When the Properties.ShowOverload property is set to True, the overload bar is displayed.  In this case, the Position property sets the total progress.  The value where the overload bar starts is set using the Properties.OverloadValue property.  Review the image below for more information.

The default value of the Position property is 0.


TcxCustomProgressBar.Properties

TcxCustomProgressBar          See Also

Provides access to specific settings of the progress bar control.

property Properties: TcxCustomProgressBarProperties;

Description

Use the Properties property to access the TcxCustomProgressBarProperties object that holds attributes specific to the progress bar control.  The attributes available allow you to customize the appearance and behavior of the progress bar.  Please refer to the description of the TcxCustomProgressBarProperties object’s properties for details.


TcxCustomProgressBar.Create

TcxCustomProgressBar

Constructor for the TcxCustomProgressBar class.

procedure Create(AOwner: TComponent); override;

Description

If you need to create a progress bar control at runtime, use the constructor of the TcxProgressBar class instead.

You may want to override the constructor in descendants of the TcxCustomProgressBar class if designing your own progress bar control.  This will allow you to perform additional initialization.


TcxCustomProgressBarProperties
TcxCustomProgressBarProperties Object

Hierarchy          Properties          Methods          Events

Holds properties specific to progress bar controls.

Unit

cxProgressBar

TcxCustomProgressBarProperties = class(TcxCustomEditProperties)

Description

The TcxCustomProgressBarProperties class serves as the base for the TcxProgressBarProperties object.  This object can be accessed via the Properties property of the TcxProgressBar control.  It holds settings specific to the progress bar.

The TcxCustomProgressBarProperties class implements all the functionality needed by its descendant.  The TcxProgressBarProperties class simply publishes some of the properties.


TcxCustomProgressBarProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |


Properties for TcxCustomProgressBarProperties
TcxCustomProgressBarProperties Properties

TcxCustomProgressBarProperties          Legend

In TcxCustomProgressBarProperties

BarBevelOuter

BarStyle

BeginColor

BorderWidth

EndColor

ForegroundImage

Max

Min

Orientation

OverloadBeginColor

OverloadEndColor

OverloadValue

PeakColor

PeakSize

PeakValue

ShowOverload

ShowPeak

ShowText

ShowTextStyle

SolidTextColor

TextOrientation

Transparent

TransparentImage

Derived from TcxCustomEditProperties

Alignment

AssignedValues

AutoSelect

BeepOnError

Buttons

ButtonsViewStyle

ClearKey

ClickKey

ImmediatePost

ReadOnly

UseLeftAlignmentOnEditing

UseMouseWheel

ValidateOnEnter


Methods for TcxCustomProgressBarProperties
TcxCustomProgressBarProperties Methods

TcxCustomProgressBarProperties          Legend

In TcxCustomProgressBarProperties

Assign

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue


Events for TcxCustomProgressBarProperties
TcxCustomProgressBarProperties Events

TcxCustomProgressBarProperties          Legend

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomProgressBarProperties.BarBevelOuter

TcxCustomProgressBarProperties          See Also

Specifies whether the progress bar is raised, lowered or flat.

type

  TcxProgressBarBevelOuter = (cxbvNone, cxbvLowered, cxbvRaised);

property BarBevelOuter: TcxProgressBarBevelOuter;

Description

Use the BarBevelOuter property to change the bevel style of the progress bar.  The table below illustrates how different values of this property affect the bar’s appearance.

Value	Description	Sample
cxbvNone	The progress bar is flat.
cxbvLowered	The progress bar is lowered.
cxbvRaised	The progress bar is raised.
Note:	The BarBevelOuter property is not in effect when images are displayed instead of the progress bar (the BarStyle property is set to cxbsBitmap or cxbsBitmapLEDs).  It also doesn’t affect the control’s appearance when XP painting is used (the Style.LookAndFeel.NativeStyle property is set to True).

The default value of the BarBevelOuter property is pbbvNone.


TcxCustomProgressBarProperties.BarStyle

TcxCustomProgressBarProperties          See Also

Specifies the style of the progress bar.

type

  TcxProgressBarBarStyle = (cxbsSolid, cxbsLEDs, cxbsGradient, cxbsGradientLEDs, cxbsBitmap, cxbsBitmapLEDs);

property BarStyle: TcxProgressBarBarStyle;

Description

Use the BarStyle property to change the appearance of the progress bar.  Note that if the ShowOverload property is set to True, the overload bar is displayed from the position set by the OverloadValue property to the position specified by the Position property.  The overload bar is also affected by the BarStyle property.

The table below describes the values available for the BarStyle property and shows their effect when XP painting is disabled and enabled. Note that the overload bar cannot be displayed using XP style (as it doesn’t support gradient filling).

Value	Meaning	XP Style Disabled	XP Style Enabled
cxbsSolid	The progress bar is represented by a solid rectangle.  The bar’s color is set by the BeginColor property.  The color of the overload bar (if shown) is specified by the OverloadBeginColor property.
cxbsLEDs	The progress bar is a set of rectangles.  The color of rectangles is set by the BeginColor property.  The color of rectangles corresponding to the overload bar (if shown) is set using the OverloadBeginColor property.
cxbsGradient	The progress bar is represented by a rectangle with gradient filling.  The starting and ending colors of the gradient are set using the BeginColor and EndColor properties.  The starting and ending colors of the overload bar’s area are specified by the OverloadBeginColor and OverloadEndColor properties.
cxbsGradientLEDs	The progress bar is a set of rectangles filled using a gradient.  The starting and ending colors of the gradient are set using the BeginColor and EndColor properties.  The starting and ending colors of the overload bar’s area are specified by the OverloadBeginColor and OverloadEndColor properties.
cxbsBitmap	The progress bar is filled with a custom bitmap.  The bitmap is specified by the ForegroundImage property.  If the specified image is smaller than the control’s client area, it is tiled.
cxbsBitmapLEDs	The progress bar is filled with a custom bitmap that is broken into a set of rectangles.  The bitmap is specified by the ForegroundImage property.  If the specified image is smaller than the control’s client area, it is tiled.
Note: you can specify whether XP painting is enabled or disabled using the Style.LookAndFeel.NativeStyle property.

The default value of the BarStyle property is pbbsSolid.


TcxCustomProgressBarProperties.BeginColor

TcxCustomProgressBarProperties          See Also

Specifies the color of the progress bar.

property BeginColor: TColor;

Description

The style of the progress bar is specified by the BarStyle property.  When this property is set to cxbsSolid or cxbsLEDs the progress bar’s color is set using the BeginColor property.  If the BarStyle property value is either cxbsGradient or cxbsGradientLEDs, the progress bar is filled using a gradient.  The starting and ending colors of the gradient are specified by the BeginColor and EndColor properties.

Note that if the ShowOverload property value is True, the control displays the overload bar between the positions specified by the OverloadValue and Position properties.  The style of this bar can be customized separately using the OverloadBeginColor and OverloadEndColor properties.

The table below shows how different values for the BeginColor property affect the appearance of the progress bar.  It assumes that the EndColor property is set to clWhite and the ShowOverload property value is False.

Value	Sample (BarStyle = cxbsLEDs)	Sample (BarStyle = cxbsGradientLEDs)
clNavy
clRed
clGreen
Note: the BeginColor property is not in effect when using XP painting.  Use the Style.LookAndFeel.NativeStyle property to specify whether XP painting is used.

The default value of the BeginColor property is clNavy.


TcxCustomProgressBarProperties.BorderWidth

TcxCustomProgressBarProperties

Specifies the offset between the control’s borders and the progress bar in pixels.

property BorderWidth: Integer;

Description

Use the BorderWidth property to change the distance between borders of the control and the progress bar.  If this property is set to 0, the bar has no offset from the control’s borders.  The BorderWidth property cannot be set to negative values.

The table below shows how different values of the BorderWidth property affect the progress bar’s appearance.

Value	Sample
0
2
5

The default value of the BorderWidth property is 0.


TcxCustomProgressBarProperties.EndColor

TcxCustomProgressBarProperties          See Also

Specifies the ending color of the gradient if gradient filling is used.

property EndColor: TColor;

Description

The progress bar is filled using a gradient only when the BarStyle property is set either to cxbsGradient or cxbsGradientLEDs.  In such an instance, the BeginColor and EndColor properties specify the starting and ending colors of the gradient respectively.  If these two properties are set to the same value, the progress bar has a solid fill.  The progress bar is also solid when the BarStyle property value is cxbsSolid or cxbsLEDs.  The color of the bar is specified by the BeginColor property.

Note that you can display an overload bar within the progress bar control.  Set the ShowOverload property to True for this purpose.  The overload bar is displayed in the range specified by the OverloadValue and Position properties.  Its style can be customized using the OverloadBeginColor and OverloadEndColor properties.  The image below shows the relationship between the relevant properties.

The table below illustrates various values of the EndColor property.  It assumes that the BarStyle property value is cxbsGradient, the BeginColor property is set to clNavy and the overload bar is disabled.

Value	Sample
clWhite
clFuchsia
clBlue
Note:	The BeginColor and EndColor properties have no influence on the control’s appearance when the control is painted using XP style.  The progress bar’s color is specified by the currently used XP theme.  Use the Style.LookAndFeel.NativeStyle property to specify whether XP painting is used.

The default value of the EndColor property is clWhite.


TcxCustomProgressBarProperties.ForegroundImage

TcxCustomProgressBarProperties          See Also

Specifies the image used to fill the progress bar.

property ForegroundImage: TBitmap;

Description

The ForegroundImage property specifies the bitmap image used to fill the progress bar. The bitmap is used only when the BarStyle property is set to cxbsBitmap or cxbsBitmapLEDs.  When set to cxbsBitmap, the image is displayed as is.  If it exceeds the size of the progress bar, it is truncated.  If the image is smaller than the progress bar’s client area, it is tiled.  The image below displays an example of using a small image to fill the progress bar.

When the BarStyle property is set to cxbsBitmapLEDs, the specified image is cut into rectangles.  This mode is more likely to be used when you specify an image that fits or exceeds the control’s area (or a texture bitmap).  The image below shows an example.

Note:	If the BarStyle property is set either to cxbsBitmap or cxbsBitmapLEDs and the ForegroundImage property is not set, the progress bar displays nothing regardless of the Position property value.


TcxCustomProgressBarProperties.Max

TcxCustomProgressBarProperties          See Also

Specifies the maximum value that can be displayed by the progress bar.

property Max: Double;

Description

The value displayed by the progress bar control is specified by its Position property.  This property can be set to a value within the range specified by the Min and Max properties.  Note that the Max property cannot be set to a value less than the Min property value, and vice versa.

When the Position property value is equal to the Max value, the progress bar completely occupies the client area of the control.  If the ShowText property is True and the ShowTextStyle property value is cxtsPercent the control will display ‘100%’.

The default value of the Max property is 100.


TcxCustomProgressBarProperties.Min

TcxCustomProgressBarProperties          See Also

Specifies the minimum value that can be displayed by the progress bar control.

property Min: Double;

Description

The range of values that can be displayed by the progress bar control is specified by the Min and Max properties.  This means that the Position property can be set to a value that falls between these property values.  Note that the Min property cannot be set to a value greater than the Max property value and vice versa.

If the Position and Min properties are set to the same value, the control is empty (no progress bar is displayed).  If the ShowText property is True and the ShowTextStyle property value is cxtsPercent the control will display ‘0%’.

The default value of the Min property is 0.


TcxCustomProgressBarProperties.Orientation

TcxCustomProgressBarProperties          See Also

Specifies the orientation of the progress bar within the control.

type

  TcxProgressBarOrientation = (cxorHorizontal, cxorVertical);

property Orientation: TcxProgressBarOrientation;

Description

Use the Orientation property to specify whether the progress bar fills the control from right to left or from bottom to top.  The table below lists values available for this property:

Value	Meaning	Samples
cxorHorizontal	The progress bar fills the control from left to right.
cxorVertical	The progress bar fills the control from bottom to top.

Note that you need to set the AutoSize property of the TcxProgressBar control to False to resize it vertically.

If the ShowText property is set to True, the progress bar displays text indicating the current progress bar position.  You can change the orientation of this text using the TextOrientation property.  You will most likely want to have the same orientation as for the progress bar itself, otherwise the text may not fit into the control’s client area.

The default value of the Orientation property is pborHorizontal.


TcxCustomProgressBarProperties.OverloadBeginColor

TcxCustomProgressBarProperties          See Also

Specifies the color of the overload bar.

property OverloadBeginColor: TColor;

Description

If the ShowOverload property value is True, the control displays the overload bar in the range specified by the OverloadValue and Position properties.  The overload bar (as well as the rest of the progress bar) can either use solid or gradient filling.  If the BarStyle property is set to cxbsSolid or cxbsLEDs, the overload bar is filled with a solid color specified by the OverloadBeginColor property.  If the BarStyle property value is either cxbsGradient or cxbsGradientLEDs, the overload bar is filled with the gradient whose starting and ending colors are specified by the OverloadBeginColor and OverloadEndColor properties.

The filling of the rest of the bar is specified by the BeginColor and EndColor properties.  The image below shows the relationship between the relevant properties.

The table below shows examples of changing the OverloadBeginColor property value.  Assume that the BarStyle property value is cxbsGradient and the OverloadEndColor property is set to clWhite.

Value	Sample
clRed
clGreen
clFuchsia

Note:	The overload bar cannot be displayed when the control is painted using XP style.  Use the Style.LookAndFeel.NativeStyle property to control whether XP painting is used.

The default value of the OverloadBeginColor property is $008080FF.


TcxCustomProgressBarProperties.OverloadEndColor

TcxCustomProgressBarProperties          See Also

Specifies the ending color of the overload bar if it is filled using a gradient.

property OverloadEndColor: TColor;

Description

Use the OverloadEndColor property value when the overload bar is displayed and gradient filling of the progress bar is used.  This property sets the ending color of the gradient used to fill the overload bar in this case.  Please refer to the OverloadBeginColor property description for details.

The table below shows examples of changing the OverloadEndColor property value.  Assume that the BarStyle property value is cxbsGradient and the OverloadBeginColor property is set to clWhite.

Value	Sample
clRed
clGreen
clFuchsia

Note:	The overload bar cannot be displayed when the control is painted using XP style.  Use the Style.LookAndFeel.NativeStyle property to control whether XP painting is used.

The default value of the OverloadEndColor property is clFuchsia.


TcxCustomProgressBarProperties.OverloadValue

TcxCustomProgressBarProperties          See Also

Specifies the starting position of the overload bar.

property OverloadValue: Integer;

Description

The progress bar control displays the overload bar if its ShowOverload property is set to True.  The bar fills the range specified by the OverloadValue and Position properties.  Note that the OverloadValue property cannot be set to a value less than the Min property or greater than the Position property.

The table below shows how changing the OverloadValue property affects the appearance of the control.  Assume that the Min, Max and Position properties are set to 0, 100 and 75 respectively.

Value	Sample
25
50

The overload bar is used when you need to illustrate two values using the same progress bar control.  For instance, if the application compresses files you can illustrate the number of bytes currently processed and the current size of the compressed file.  The size of the compressed file will correspond to the OverloadValue property value in this case.  The total number of bytes processed will correspond to the Position property.

Note:	The overload bar cannot be displayed when the control is painted using XP style.  Use the Style.LookAndFeel.NativeStyle property to control whether XP painting is used.

The default value of the OverloadValue property is 80.


TcxCustomProgressBarProperties.PeakColor

TcxCustomProgressBarProperties          See Also

Specifies the color used to fill the peak area.

property PeakColor: TColor;

Description

If the ShowPeak property value is True, the control displays a peak area to indicate a critical position.  The position and width of the peak area are specified by the PeakValue and PeakSize properties respectively.  Its color is set using the PeakColor property.

The table below shows how changing the PeakColor property value affects the control’s appearance.

Value	Sample
clRed
clBlue

The default value of the PeakColor property is clRed.


TcxCustomProgressBarProperties.PeakSize

TcxCustomProgressBarProperties          See Also

Specifies the width of the peak area in pixels.

type

  TcxNaturalNumber = 1..High(Integer);

property PeakSize: TcxNaturalNumber;

Description

The progress bar enables you to display a peak area within it.  This area identifies a critical value (progress can go further than this value).  You need to set the ShowPeak property to True to display the peak area.

The position of this critical value is specified by the PeakValue property.  The peak area is painted starting from this position.  Its width is specified by the PeakSize property.  The table below shows how this property affects the control’s appearance.

Value	Sample
2
5

The default value of the PeakSize property is 2.


TcxCustomProgressBarProperties.PeakValue

TcxCustomProgressBarProperties          See Also

Specifies the position of the peak area.

property PeakValue: Integer;

Description

When the ShowPeak property is set to True, the control displays the peak area at the position specified by the PeakValue property.  The width and color of the peak area are set by the PeakSize and PeakColor properties respectively.

The PeakValue property can be set to a value in the range specified by the Position and Max properties.  If the Position is increased so that it is greater than the peak position, the PeakValue property is set to the Position property value.

The default value of the PeakValue property is 0.


TcxCustomProgressBarProperties.ShowOverload

TcxCustomProgressBarProperties          See Also

Specifies whether an overload bar is displayed.

property ShowOverload: Boolean;

Description

The progress bar control enables you to display an overload bar – a part of the progress bar with different style settings.  This bar is displayed in the range specified by the OverloadValue and Position properties.  The style of the bar is controlled by the OverloadBeginColor and OverloadEndColor properties.  Please refer to these property descriptions for details.

Note:	The overload bar cannot be displayed when the control is painted using XP style.  Use the Style.LookAndFeel.NativeStyle property to control whether XP painting is used.

The default value of the ShowOverload property is False.


TcxCustomProgressBarProperties.ShowPeak

TcxCustomProgressBarProperties          See Also

Specifies whether the peak area is displayed.

property ShowPeak: Boolean;

Description

The control allows you to display a peak area, enabling a critical value to be displayed.  Set the ShowPeak property to True to make that area visible.  The position of the peak area is set by the PeakValue property.  Its appearance can be customized using the PeakSize and PeakColor properties.  Please refer to these property descriptions for details.

The default value of the ShowPeak property is False.


TcxCustomProgressBarProperties.ShowText

TcxCustomProgressBarProperties          See Also

Specifies whether the progress bar control displays text identifying its current position.

property ShowText: Boolean;

Description

The progress bar is capable of displaying a text label that identifies its current position.  This text label can display either the Position property value or the percentage of progress (as specified by the ShowTextStyle property).  When the ShowText property value is True, text is displayed.

Setting the ShowText property to False hides the text label.

You can change the orientation of the label using the TextOrientation property.  Its font settings can be customized using the Style.Font property.  You can also force the label to use colors inverse to its background (thus ensuring that it is always visible).  See the SolidTextColor property description for details.

The default value of the ShowText property is True.


TcxCustomProgressBarProperties.ShowTextStyle

TcxCustomProgressBarProperties          See Also

Specifies whether the progress bar’s text label displays the current position or the percentage of completion.

type

  TcxProgressBarTextStyle = (cxtsPercent, cxtsPosition);

property ShowTextStyle: TcxProgressBarTextStyle;

Description

If the ShowTextStyle property is set to cxtsPercent, the progress bar’s text label displays the percentage of completion.  If current Position equals the Min property value, the label will display ‘0%’.  If it equals the Max property value, the label will display ‘100%’.

When the ShowTextStyle property is set to cxtsPosition, the progress bar’s text label displays the current Position property value.

The images below show the appearance of the control when different values of the ShowTextStyle property are used.  It is assumed that the Min, Max and Position property values are set to –10, 10 and 5 respectively.

Value	Sample
cxtsPercent
cxtsPosition
Note:	The text label is displayed within the progress bar control only when the ShowText property is set to True.

The default value of the ShowTextStyle property is pbtsPercent.


TcxCustomProgressBarProperties.SolidTextColor

TcxCustomProgressBarProperties

Specifies whether the text label is painted using a single color or whether the color depends on its background.

property SolidTextColor: Boolean;

Description

If the SolidTextColor property is set to True, the text label is painted using the color specified by the Style.Font.Color property of the control.  For some combinations (as illustrated on the leftmost image below), this can result in part of the text being invisible. When the property is set to False, the label is painted in a different color to the background.  The table below shows examples.  The font color is set to clNavy.

SolidTextColor is True	SolidTextColor is False
Note:	The label text is displayed only when the ShowText property is set to True.

The default value of the SolidTextColor property is False.


TcxCustomProgressBarProperties.TextOrientation

TcxCustomProgressBarProperties          See Also

Specifies the orientation of the text indicating current position.

type

  TcxProgressBarOrientation = (cxorHorizontal, cxorVertical);

property TextOrientation: TcxProgressBarOrientation;

Description

If the ShowText property is set to True, the progress bar control displays a text label indicating its current position.  The orientation of the displayed text is set by the TextOrientation property.  Note that the orientation of the progress bar can also be changed using the Orientation property.  You will probably want to change these properties together, otherwise the text may not fit into the control’s area.

The table below shows examples of changing the TextOrientation and Orientation properties together.

Value	Sample
cxorHorizontal
cxorVertical

The default value of the TextOrientation property is cxorHorizontal.


TcxCustomProgressBarProperties.Transparent

TcxCustomProgressBarProperties

Determines whether the progress bar background is transparent.

property Transparent: Boolean;

Description

Use the Transparent property to determine whether the progress bar background is transparent.  This has no effect if the progress bar is filled with an image. To make the progress bar foreground image transparent, set the Properties.TransparentImage to True.

The default value of the Transparent property is False.

Note:	This property is obsolete.  To specify the transparency state of an editor’s background, use its Transparent property.


TcxCustomProgressBarProperties.TrasparentImage
TcxCustomProgressBarProperties.TransparentImage

TcxCustomProgressBarProperties

Specifies whether to add transparency to the image used to fill the progress bar.

property TransparentImage: Boolean;

Description

If the BarStyle property is set to cxbsBitmap or cxbsBitmapLEDs, the progress bar is filled with the image specified by the ForegroundImage property.  Set the TransparentImage property to True to add transparency to the image.  The transparent color is obtained from the left-bottom pixel of the loaded image.

Suppose that the image specified by the ForegroundImage property is the following.

The images below show the appearance of the control when the TransparentImage property is set to False and True respectively (the BarStyle property is set to cxbsBitmap).

Note:	The background color of the progress bar is specified by the Style.Color property.  This color is displayed behind the transparent color.

The default value of the TransparentImage property is True.


TcxCustomProgressBarProperties.Assign

TcxCustomProgressBarProperties

Assigns the contents of one TcxCustomProgressBarProperties object to another.

procedure Assign(Source: TPersistent); override;

Description

Use the Assign method if you need to create several progress bars with slightly different or similar settings.  This allows you to customize a single progress bar and then copy its settings to others.

The Source parameter represents the source object.  The caller is the destination object.  Note that if the Source parameter value is not a TcxCustomProgressBarProperties object (or descendant), the Assign method does nothing.


TcxProgressBar
 TcxProgressBar Object

Hierarchy          Properties          Methods          Events

Represents an advanced progress bar control.

Unit

cxProgressBar

TcxProgressBar = class(TcxCustomProgressBar)

Description

TcxProgressBar displays a bar that can gradually fill the control from left to right or from bottom to top (depending on the control’s orientation).  The orientation of the bar and the text displaying the current position can be changed using the Properties.Orientation and Properties.TextOrientation properties.  The bar style is set using the Properties.BarStyle and Properties.ForegroundImage properties.

When the control is oriented horizontally, it is likely to be used to display the progress of a specific operation.  Vertically oriented progress bars can be used to show an operation’s execution rate.  In either case, the progress bar can display values in the range specified by the Properties.Min and Properties.Max properties.  The current position of the bar is set via the Position property.

Using the TcxProgressBar control you can also display an overload bar.  In this instance, the total progress bar displayed by the control will be split into two.  Each part can have different styles.  This can be used for instance, when using the progress bar to illustrate a compression procedure.  The total bar will display how much of the file has been processed.  The first part of the bar will show the size of the compressed file at a given point in time.  Please refer to the Properties.ShowOverload property description for details.

Another feature provided by the TcxProgressBar control is the display of a peak or critical value.  Refer to the Properties.ShowPeak property description for more information.

Note that like the other editors, the progress bar supports XP painting.  (However, the overload bar feature cannot be used in this case).  The image below shows an example.

All functionality of the progress bar control is implemented by its ancestor – the TcxCustomProgressBar class.  The TcxProgressBar object simply publishes properties.


TcxProgressBar Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomProgressBar

     |


Properties for TcxProgressBar
TcxProgressBar Properties

TcxProgressBar          Legend

Derived from TcxCustomProgressBar

ActiveProperties

Position

Properties

Derived from TcxCustomEdit

ActiveProperties

AutoSize

DataBinding

EditModified

EditValue

InnerEdit

ModifiedAfterEnter

Properties

RepositoryItem

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TControl

Align


Methods for TcxProgressBar
TcxProgressBar Methods

TcxProgressBar          Legend

Derived from TcxCustomProgressBar

Create

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit


Events for TcxProgressBar
TcxProgressBar Events

TcxProgressBar          Legend

Derived from TcxCustomEdit

 OnEditing

OnFocusChanged


TcxProgressBarProperties
TcxProgressBarProperties Object

Hierarchy          Properties          Methods          Events

Holds specific settings of the progress bar control.

Unit

cxProgressBar

TcxProgressBarProperties = class(TcxCustomProgressBarProperties)

Description

The TcxProgressBarProperties object holds settings specific to the TcxProgressBar control.  You can access this object via the Properties property of the control.

All the functionality of the TcxProgressBarProperties class is implemented by its ancestor – the TcxCustomProgressBarProperties object.  The descendant simply publishes properties.


TcxProgressBarProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomProgressBarProperties

     |


Properties for TcxProgressBarProperties
TcxProgressBarProperties Properties

TcxProgressBarProperties          Legend

Derived from TcxCustomProgressBarProperties

BarBevelOuter

BarStyle

BeginColor

BorderWidth

EndColor

ForegroundImage

Max

Min

Orientation

OverloadBeginColor

OverloadEndColor

OverloadValue

PeakColor

PeakSize

PeakValue

ShowOverload

ShowPeak

ShowText

ShowTextStyle

SolidTextColor

TextOrientation

Transparent

TransparentImage

Derived from TcxCustomEditProperties

Alignment

AssignedValues

AutoSelect

BeepOnError

Buttons

ButtonsViewStyle

ClearKey

ClickKey

ImmediatePost

ReadOnly

UseLeftAlignmentOnEditing

UseMouseWheel

ValidateOnEnter


Methods for TcxProgressBarProperties
TcxProgressBarProperties Methods

TcxProgressBarProperties          Legend

Derived from TcxCustomProgressBarProperties

Assign

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue


Events for TcxProgressBarProperties
TcxProgressBarProperties Events

TcxProgressBarProperties          Legend

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


cxShellBrowserDialog Unit Overview
cxShellBrowserDialog Unit

Components

TcxShellBrowserDialog

Classes

TcxCustomShellBrowserDialog


TcxCustomShellBrowserDialog
TcxCustomShellBrowserDialog Object

Hierarchy          Properties          Methods

Represents the base class for the cxShellBrowserDialog control.

Unit

cxShellBrowserDialog

TcxCustomShellBrowserDialog = class(TComponent);

Description

The TcxCustomShellBrowserDialog class is the base class for the cxShellBrowserDialog control.

It defines the basic functionality for the shell browser dialog controls:

•	the Path property, specifying the path to the current folder;

•	the Root property, containing the starting folder settings;

•	the Options property, providing access to the behavior options of the shell browser dialog;

•	the ShowButtons, ShowInfoTips, ShowLines and ShowRoot properties affecting the appearance of the shell browser dialog folder tree;

•	the Execute method, invoking the shell browser dialog.


TcxCustomShellBrowserDialog Hierarchy
Hierarchy

TComponent

     |


Properties for TcxCustomShellBrowserDialog
 TcxCustomShellBrowserDialog Properties

TcxCustomShellBrowserDialog          Legend

In TcxCustomShellBrowserDialog

FolderLabelCaption

LookAndFeel

Options

Path

Root

ShowButtons

ShowInfoTips

ShowLines

ShowRoot

Title


Methods for TcxCustomShellBrowserDialog
TcxCustomShellBrowserDialog Methods

TcxCustomShellBrowserDialog          Legend

In TcxCustomShellBrowserDialog

Execute


TcxCustomShellBrowserDialog.FolderLabelCaption

TcxCustomShellBrowserDialog

Specifies the Caption of the label containing the current folder name.

property FolderLabelCaption: string;

Description

Use the FolderLabelCaption property to specify the Caption for the label displaying the current folder name.


TcxCustomShellBrowserDialog.LookAndFeel

TcxCustomShellBrowserDialog

Specifies the default look and feel of a grid control.

property LookAndFeel: TcxLookAndFeel;

Description

LookAndFeel controls the default look and feel of a shell browser dialog and the style behavior in response to user actions.

The NativeStyle attribute determines whether the control’s elements (borders, buttons and 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.  The styles enumerated by the TcxLookAndFeel type determine the manner in which the browser dialog is painted and how it responds to mouse events.


TcxCustomShellBrowserDialog.Options

TcxCustomShellBrowserDialog

Contains the shell browser dialog options.

property Options: TcxDlgShellOptions;

Description

Use the Options property to access the set of options affecting the appearance and functionality of the shell browser dialog.  These options determine:

•	whether the shell browser dialog displays only folder or non folder shell items (see the Options.ShowFolders and Options.ShowNonFolders property descriptions);

•	whether the shell browser dialog displays hidden shell items and shell context menus (see the Options.ShowHidden and Options.ContextMenus property descriptions);

•	whether the shell browser dialog reflects all changes, occurring among shell items (see the Options.TrackShellChanges property description);

•	whether shell items tool tips are displayed when the mouse pointer is positioned over items (see the Options.ShowToolTip property description).


TcxCustomShellBrowserDialog.Path

TcxCustomShellBrowserDialog

Specifies the path to the current shell item.

property Path: string;

Description

Use the Path property to specify the path to the current shell item.  Folder path can be specified in two ways:

•	as a full path, including all sequence of folders, required for accessing the required shell item from the shell root.

Example:

cxShellBrowserDialog1.Path := 'C:\Documents and Settings\Administrator\My Documents\My Pictures';

•	as a relative path, providing access to shell items within the current folder.

Example:

cxShellBrowserDialog1.Path := 'My Pictures';

The Path property allows a user to access virtual shell items, which have no analog on the hard disk.  You need to specify one of the virtual shell item path prefixes before the virtual shell item name.  The cxShellObjectInternalAbsoluteVirtualPathPrefix constant allows accessing the required shell item from any current folder.  The cxShellObjectInternalRelativeVirtualPathPrefix constant allows accessing the required shell item from the Root folder.  Examples of virtual shell items include:

•	Network printers;

•	Other networked computers;

•	Control Panel applications;

•	Recycle Bin.

Example of accessing the Recycle Bin shell item via the absolute and relative virtual path prefix:

cxShellBrowserDialog1.Path := cxShellObjectInternalAbsoluteVirtualPathPrefix + '\Recycle Bin';

cxShellBrowserDialog1.Path := cxShellObjectInternalRelativeVirtualPathPrefix + '\Recycle Bin';

During navigation through the folders, the AbsolutePath property stores the path to the currently accessed shell item.

Note: the Path property must contain folder names only.  Specifying the file name within the Path property causes unpredictable results.


TcxCustomShellBrowserDialog.Root

TcxCustomShellBrowserDialog

Contains starting folder options.

property Root: TcxDlgShellRoot;

Description

Use the Root property to access shell browser dialog starting folder options.  The Root.BrowseFolder property specifies the folder that is opened when the shell browser dialog is displayed.  If this property is set to bfCustomPath, then the starting folder path is defined by the Root.CustomPath property.

The path to the currently accessed shell item is specified via the Path property.


TcxCustomShellBrowserDialog.ShowButtons

TcxCustomShellBrowserDialog

Specifies whether the expand buttons are displayed within the shell browser dialog.

property ShowButtons: Boolean;

Description

Set the ShowButtons property to False to hide expand buttons displayed within the shell browser dialog.  The images below show you the shell browser dialog when the ShowButtons property is set to True and False respectively.

If expand buttons are not displayed, end users can use the following methods to expand and collapse parent nodes:

•	Pressing the right and left arrow keys when the desired parent node is selected;

•	Double-clicking the desired parent node.

Note: you can hide expand buttons only on the root level of the tree.  Set the ShowRoot property to False for this purpose.

The default value of the ShowButtons property is True.


TcxCustomShellBrowserDialog.ShowInfoTips

TcxCustomShellBrowserDialog

Specifies whether tool tips are displayed for shell items.

property ShowInfoTips: Boolean;

Description

Set the ShowInfoTips property to True to display tool tips for shell items.  These tool tips contain display information specific to the shell item type:

•	a short description for virtual shell items;

•	the total size and a list of the contained folders and files for folders.

The default value of the ShowInfoTips property is True.


TcxCustomShellBrowserDialog.ShowLines

TcxCustomShellBrowserDialog

Specifies whether the tree lines are displayed within the shell browser dialog.

property ShowLines: Boolean;

Description

Set the ShowLines property to False to hide tree lines.  If it is set to True, tree lines are displayed.  The images below illustrate both values for this property.

The default value of the ShowLines property is True.


TcxCustomShellBrowserDialog.ShowRoot

TcxCustomShellBrowserDialog

Specifies the visibility of tree lines and expand buttons at the root level of the tree.

property ShowRoot: Boolean;

Description

Set the ShowRoot property to False to hide tree lines and expand buttons at the root level of the shell tree.  If they are hidden, contents of root nodes are displayed at the left edge of the control without any indent.

The images below show sample shell browser dialogs when the ShowRoot property is set to True and False respectively.

The default value of the ShowRoot property is True.


TcxCustomShellBrowserDialog.Title

TcxCustomShellBrowserDialog

Specifies the shell browse dialog caption.

property Title: string;

Description

Use the Title property to specify the shell browser dialog caption.


TcxCustomShellBrowserDialog.Execute

TcxCustomShellBrowserDialog

Invokes the shell browser dialog.

function Execute: Boolean; override;

Description

The Execute method invokes the shell browser dialog and returns the boolean value representing the dialog execution result (True if the OK button had been pressed).  When the dialog executes successefully the Path property stores the path to the current folder.  Otherwise the Path property stores the path to the folder accessed last.


TcxShellBrowserDialog
TcxShellBrowserDialog Component

Hierarchy          Properties          Methods

Represents the shell browser dialog control.

Unit

cxShellBrowserDialog

TcxShellBrowserDialog = class(TcxCustomShellBrowserDialog)

Description

The TcxShellBrowserDialog class represents the shell browser dialog control which can be customized, tested at design time and invoked later in code.  It inherits its basic functionality from its ancestor (the TcxCustomShellBrowserDialog class):

•	the Path property, specifiying the path to the current folder;

•	the Root property, containing the starting folder settings;

•	the Options property, providing access to the behavior options of the shell browser dialog;

•	the ShowButtons, ShowInfoTips, ShowLines and ShowRoot properties affecting the appearance of the shell browser dialog folder tree;

•	the Execute method, invoking the shell browser dialog.


TcxShellBrowserDialog Hierarchy
Hierarchy

TComponent

     |

TcxCustomShellBrowserDialog

     |


Properties for TcxShellBrowserDialog
TcxShellBrowserDialog Properties

TcxShellBrowserDialog          Legend

Derived from TcxCustomShellBrowserDialog

FolderLabelCaption

LookAndFeel

Options

Path

Root

ShowButtons

ShowInfoTips

ShowLines

ShowRoot

Title


Methods for TcxShellBrowserDialog
TcxShellBrowserDialog Methods

TcxShellBrowserDialog          Legend

Derived from TcxCustomShellBrowserDialog

Execute


cxShellComboBox Unit Overview
cxShellComboBox Unit

Components

TcxShellComboBox

Classes

TcxCustomShellComboBox

TcxCustomShellComboBoxProperties

TcxPopupShellTreeView

TcxShellComboBoxProperties

TcxShellComboBoxRoot


TcxCustomShellComboBox
TcxCustomShellComboBox Object

Hierarchy          Properties          Methods          Events

Represents the base class for the TcxShellComboBox editor.

Unit

cxShellComboBox

TcxCustomShellComboBox = class(TcxCustomPopupEdit)

Description

The TcxCustomShellComboBox class is the base class for the TcxShellComboBox object.  It defines the basic functionality for the shell combo box editor.  Do not instantiate the TcxCustomShellComboBox class.  Use its descendant, the TcxShellComboBox class, which publishes the necessary properties.

The shell combo box editors are capable of browsing the system Shell.  You can specify the path to the required shell item via the EditValue or AbsolutePath properties.  If you need to process the items’ PIDLs directly, use the AbsolutePIDL and RelativePIDL properties.

Various settings specific to shell combo box editors can be accessed via the Properties member.


TcxCustomShellComboBox Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomPopupEdit

     |


Properties for TcxCustomShellComboBox
TcxCustomShellComboBox Properties

TcxCustomShellComboBox          Legend

In TcxCustomShellComboBox

AbsolutePath

AbsolutePIDL

ActiveProperties

PopupShellTreeView

Properties

RelativePIDL

ShellListView

ShellTreeView

Derived from TcxCustomPopupEdit

ActiveProperties

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxCustomShellComboBox
TcxCustomShellComboBox Methods

TcxCustomShellComboBox          Legend

Derived from TcxCustomPopupEdit

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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCustomShellComboBox
TcxCustomShellComboBox Events

TcxCustomShellComboBox          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCustomShellComboBox.ActiveProperties

TcxCustomShellComboBox          See Also

Obtains the properties that are currently applied to a shell combo box.

property ActiveProperties: TcxCustomShellComboBoxProperties;

Description

Use the ActiveProperties property to obtain the properties of the current shell combo box that are currently in effect.  This property is especially useful when the shell combo box 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 shell combo box.  Otherwise, the inherent shell combo box’s properties are returned.

ReadOnly Property


TcxCustomShellComboBox.AbsolutePath

TcxCustomShellComboBox          See Also

Specifies the path to a shell item being accessed.

property AbsolutePath: string;

Description

Use the AbsolutePath property to specify the path to the shell item being accessed.  Folder path can be specified in two ways:

•	as a full path, including all sequence of folders, required for accessing the required shell item from the shell root.

Example:

cxShellComboBox1.AbsolutePath := 'C:\Documents and Settings\Administrator\My Documents\My Pictures';

•	as a relative path, providing access to shell items within the current folder.

Example:

cxShellComboBox1.AbsolutePath := 'My Pictures';

The AbsolutePath property allows a user to access both virtual and standard shell items.  Note that virtual shell items have no analog on the hard disk.  You need to specify one of the virtual shell item path prefixes before the virtual shell item’s name.  The cxShellObjectInternalAbsoluteVirtualPathPrefix constant allows accessing the required shell item from any current folder.  The cxShellObjectInternalRelativeVirtualPathPrefix constant allows accessing the required shell item from the Properties.Root folder.  Examples of virtual shell items include:

•	Network printers;

•	Other networked computers;

•	Control Panel applications;

•	Recycle Bin.

Example of accessing the Recycle Bin shell item via the absolute and relative virtual path prefix:

cxShellComboBox1.AbsolutePath := cxShellObjectInternalAbsoluteVirtualPathPrefix + 'Recycle Bin';

cxShellComboBox1.AbsolutePath := cxShellObjectInternalRelativeVirtualPathPrefix + 'Recycle Bin';

During navigation through the folders, the AbsolutePath property stores the path to the currently accessed shell item.

Note:	The AbsolutePath property must contain folder names only.  Specifying the file name within the AbsolutePath property causes unpredictable results.


TcxCustomShellComboBox.AbsolutePIDL

TcxCustomShellComboBox          See Also

Specifies the identifier of the shell item being accessed.

property AbsolutePIDL: PItemIDList;

Description

Set the AbsolutePIDL property to specify the identifier of the shell item being accessed.  Both virtual and standard shell items can be accessed using identifiers.  Note that virtual shell items have no physical analogs – files or folders on hard drives.

Using this property is similar to specifying the AbsolutePath property with the cxShellObjectInternalAbsoluteVirtualPathPrefix constant.

Use the AbsolutePIDL property when working with Shell API directly.

You can obtain the text representation of the item’s identifier by calling the GetPidlName function.


TcxCustomShellComboBox.PopupShellTreeView

TcxCustomShellComboBox

Provides access to the shell tree view that is displayed within the popup window.

property PopupShellTreeView: TcxPopupShellTreeView;

Description

Use the PopupShellTreeView to access the shell tree view that is displayed within the popup window and its properties (such as nodes, corresponding shell items, etc.).

ReadOnly Property


TcxCustomShellComboBox.Properties

TcxCustomShellComboBox

Contains settings specific to shell combo box.

property Properties: TcxCustomShellComboBoxProperties;

Description

Use the Properties to adjust settings specific to shell combo box.  These settings specify whether the incremental searching is enabled, determine the manner in which the EditValue saves the specified path, the shell combo box display and dropdown options.


TcxCustomShellComboBox.RelativePIDL

TcxCustomShellComboBox          See Also

Specifies the relative identifier for the shell item being accessed.

property RelativePIDL: PItemIDList;

Description

Set the RelativePIDL property to specify the relative identifier for the shell item being accessed.  Both virtual and standard shell items can be accessed using identifiers.  Note that virtual shell items have no physical analogs – files or folders on hard drives.

Using this property is similar to specifying the AbsolutePath property with the cxShellObjectInternalRelativeVirtualPathPrefix constant.

Use the AbsolutePIDL property when working with Shell API directly.


TcxCustomShellComboBox.ShellListView

TcxCustomShellComboBox          See Also

Specifies the TcxShellListView control associated with the current shell combo box.

property ShellListView: TcxCustomShellListView;

Description

Use the ShellListView property to associate a shell list view control with the current shell combo box.  The cxShellListView specified via this property is synchronized with the current shell combo box.

When a specific shell item (folder) is selected within the shell combo box, this item (folder) contents are displayed within the associated shell list view.


TcxCustomShellComboBox.ShellTreeView

TcxCustomShellComboBox          See Also

Specifies the TcxShellTreeView control associated with the current shell combo box.

property ShellTreeView: TcxCustomShellTreeView;

Description

Use the ShellTreeView property to associate a shell tree view control with the current shell combo box.  The cxShellTreeView specified via this property is synchronized with the current shell combo box.

When a specific shell item (folder) is selected within the shell combo box, this selected item (folder) parent contents are displayed within the associated shell tree view.


TcxCustomShellComboBoxProperties
TcxCustomShellComboBoxProperties Object

Hierarchy          Properties          Methods          Events

Contains settings specific to the shell combo box editors.

Unit

cxShellComboBox

TcxCustomShellComboBoxProperties = class(TcxCustomPopupEditProperties)

Description

The TcxCustomShellComboBoxProperties class represents the set of attributes that control behavior of the TcxShellComboBox editor.  Properties of an editor are set via the Properties member.


TcxCustomShellComboBoxProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |

TcxCustomDropDownEditProperties

     |

TcxCustomPopupEditProperties

     |


Properties for TcxCustomShellComboBoxProperties
TcxCustomShellComboBoxProperties Properties

TcxCustomShellComboBoxProperties          Legend

In TcxCustomShellComboBoxProperties

DropDownSizeable

DropDownWidth

FastSearch

IncrementalSearch

Root

ShowFullPath

StoreRelativePath

TreeViewOptions

ViewOptions

Derived from TcxCustomPopupEditProperties

PopupControl

PopupSizeable

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

IncrementalSearch

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 TcxCustomShellComboBoxProperties
TcxCustomShellComboBoxProperties Methods

TcxCustomShellComboBoxProperties          Legend

Derived from TcxCustomMaskEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults


Events for TcxCustomShellComboBoxProperties
TcxCustomShellComboBoxProperties Events

TcxCustomShellComboBoxProperties          Legend

In TcxCustomShellComboBoxProperties

OnAddFolder

Derived from TcxCustomDropDownEditProperties

OnCloseQuery

OnCloseUp

OnInitPopup

OnPopup

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomShellComboBoxProperties.DropDownSizeable

TcxCustomShellComboBoxProperties

Determines whether the shell combo box dropdown is sizeable.

property DropDownSizeable: Boolean;

Description

Set the DropDownSizeable property to True to allow a user to change the size of the popup window using the mouse.  If DropDownSizeable is set to False, the user cannot resize the popup.

Use the DropDownWidth property to change the shell combo box dropdown width when the DropDownSizeable is False.

The default value of the DropDownSizeable property is True.


TcxCustomShellComboBoxProperties.DropDownWidth

TcxCustomShellComboBoxProperties

Specifies the shell combo box dropdown width.

property DropDownWidth: Integer;

Description

The DropDownWidth property specifies the width of the shell combo box dropdown.   If runtime resizing of the dropdown is disabled by setting the DropDownSizeable to False, then use the DropDownWidth to change the shell combo box dropdown width.

The default value of the DropDownWidth property is 0.


TcxCustomShellComboBoxProperties.FastSearch

TcxCustomShellComboBoxProperties

Determines whether the fast searching for the shell items is enabled.

property FastSearch: Boolean;

Description

When a shell combo box functions as an in-place editor its EditValue accepts a string and the editor attempts to locate the corresponding shell item.  If the FastSearch option is active, then the shell combo box activity differs according to the shell item type.  If the specified EditValue refers to a virtual shell item, then full search for that item is performed.  If the EditValue refers to a non-virtual shell item, then the search is not performed and the EditValue stores the string portion after the last slash symbol.  For instance: if the EditValue is assigned "C:\Documents and Settings\UserName\My Documents\My Pictures\" value, then the stored value is "My Pictures" string.

The default value of the FastSearch property is False.


TcxCustomShellComboBoxProperties.IncrementalSearch

TcxCustomShellComboBoxProperties

Determines whether the incremental search feature is enabled.

property IncrementalSearch: Boolean;

Description

Use the IncrementalSearch property to enable or disable the incremental search within the shell combo box dropdown.  If this property value is True, then an end-user may type the required shell item name to locate the closest match within the shell combo box dropdown.  The located item becomes selected within the dropdown.

The default value of the IncrementalSearch property is False.


TcxCustomShellComboBoxProperties.Root

TcxCustomShellComboBoxProperties

Contains starting folder options.

property Root: TcxShellComboBoxRoot;

Description

Use the Root property to access shell combo box view starting folder options.  The Root.BrowseFolder property specifies the folder that is opened when the shell combo box view is created.  If this property is set to bfCustomPath, then the starting folder path is defined by the Root.CustomPath property.

The current path to the currently opened shell item is specified via the AbsolutePath property.  If the current starting folder is virtual (for instance, Recycle Bin), then the folder’s identifier can be accessed via the AbsolutePIDL property.


TcxCustomShellComboBoxProperties.ShowFullPath

TcxCustomShellComboBoxProperties          See Also

Specifies the manner in which the full path to the current shell item is displayed within the edit region.

type

  TcxShellComboBoxShowFullPath = (sfpNever, sfpAlways, sfpNotFocused);

property ShowFullPath: TcxShellComboBoxShowFullPath;

Description

Use the ShowFullPath property to specify the manner in which the full path to the current shell item is displayed within the edit region.

All the possible values for this property are listed in the following table.

Value	Meaning
sfpNever	The edit region of the shell combo box contains only the display name of the current shell item within its parent folder.
sfpAlways	The edit region displays the absolute path to the current shell item (from the Shell root) even when the edit region of the shell combo box is focused.
sfpNotFocused	The edit region displays the absolute path to the current shell item (from the Shell root) only when the edit region of the shell combo box is not focused.

The default value of the ShowFullPath property is sfpNever.


TcxCustomShellComboBoxProperties.StoreRelativePath

TcxCustomShellComboBoxProperties

Determines whether the EditValue stores full or relative path.

property StoreRelativePath: Boolean;

Description

Use the StoreRelativePath property to specify the manner in which the current path is stored within the EditValue.  If the StoreRelativePath is False, then the EditValue stores absolute path to the current shell item (see the AbsolutePath property description for details).  Otherwise, the EditValue saves path relative to the shell combo box Root.

The default value of the StoreRelativePath property is True.


TcxCustomShellComboBoxProperties.TreeViewOptions

TcxCustomShellComboBoxProperties

Specifies the shell combo box dropdown options.

type

  TcxPopupShellTreeViewOption = (tvoContextMenus, tvoHotTrack, tvoShowButtons,

    tvoShowLines, tvoShowRoot, tvoRightClickSelect);

  TcxPopupShellTreeViewOptions = set of TcxPopupShellTreeViewOption;

property TreeViewOptions: TcxPopupShellTreeViewOptions;

Description

Use the TreeViewOptions property to specify the shell combo box dropdown options.

All the possible values for this property are listed in the following table.

Value	Meaning
tvoContextMenus	Determines whether the shell context menus are displayed.
tvoHotTrack	Specifies whether the shell combo box dropdown items are hot-tracked when the mouse hovers over them.
tvoShowButtons	Specifies whether the expand buttons are displayed next to the parent dropdown items. If this option is deactivated, then the parent items can be expanded by double-clicking on them.
tvoShowLines	Specifies whether the tree lines are displayed within the shell combo box dropdown.
tvoShowRoot	Determines whether the expand buttons and the tree lines are displayed at the root level of the shell combo box dropdown.
tvoRightClickSelect	Specifies whether the property returns the right-clicked node when the control’s popup menu is invoked.

The default value of the TreeViewOptions property is [tvoContextMenus,tvoHotTrack,tvoShowButtons,tvoShowLines,tvoShowRoot].


TcxCustomShellComboBoxProperties.ViewOptions

TcxCustomShellComboBoxProperties

Specifies the display options for the shell combo box.

type

  TcxShellComboBoxViewOption = (scvoShowFiles, scvoShowHidden);

  TcxShellComboBoxViewOptions = set of TcxShellComboBoxViewOption;

property ViewOptions: TcxShellComboBoxViewOptions;

Description

Use the ViewOptions property to specify the display options for the shell combo box dropdown.

All the possible values for this property are listed in the following table.

Value	Meaning
scvoShowFiles	Determines whether the folders only or both folders and files are displayed within the shell combo box dropdown.
scvoShowHidden	Specifies whether the hidden shell items (files and folders) are displayed within the shell combo box dropdown.

The default value of the ViewOptions property is [].


TcxCustomShellComboBoxProperties.OnAddFolder

TcxCustomShellComboBoxProperties          See Also

Occurs when a shell item is added to the shell tree view that is displayed within a popup window.

type

  TcxShellAddFolderEvent = procedure(Sender: TObject; AFolder: TcxShellFolder; var ACanAdd: Boolean) of object;

property OnAddFolder: TcxShellAddFolderEvent;

Description

The OnAddFolder event occurs when a shell item is added to the shell tree view that is displayed within a popup window.  The AFolder parameter specifies the shell item being added.  The ACanAdd parameter indicates whether the item will be added to the shell tree view and is initially equal to True.  Once added, the shell item can be accessed via the Folders property.  Set the ACanAdd parameter to False to prevent the shell item from being displayed within the shell tree view.


TcxShellComboBox
 TcxShellComboBox Component

Hierarchy          Properties          Methods          Events

Represents the shell combo box editor.

Unit

cxShellComboBox

TcxShellComboBox = class(TcxCustomShellComboBox)

Description

The TcxShellComboBox class represents the shell combo box editor.  The shell combo box editors are capable of browsing the system Shell.

The required shell item can be located both by typing the path to an item within the edit region and by invoking the editor’s dropdown, representing the folders tree:

You can specify the path to the required shell item via the EditValue or AbsolutePath properties.  If you need to process the items’ PIDLs directly, use the AbsolutePIDL and RelativePIDL properties.

Various settings specific to shell combo box editors can be accessed via the Properties member.


TcxShellComboBox Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomPopupEdit

     |

TcxCustomShellComboBox

     |


Properties for TcxShellComboBox
TcxShellComboBox Properties

TcxShellComboBox          Legend

Derived from TcxCustomShellComboBox

AbsolutePath

AbsolutePIDL

ActiveProperties

PopupShellTreeView

Properties

RelativePIDL

ShellListView

ShellTreeView

Derived from TcxCustomPopupEdit

ActiveProperties

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName

Derived from TControl

Align


Methods for TcxShellComboBox
TcxShellComboBox Methods

TcxShellComboBox          Legend

Derived from TcxCustomPopupEdit

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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxShellComboBox
TcxShellComboBox Events

TcxShellComboBox          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxShellComboBoxProperties
TcxShellComboBoxProperties Object

Hierarchy          Properties          Methods          Events

Contains settings specific to shell combo box editors.

Unit

cxShellComboBox

TcxShellComboBoxProperties = class(TcxCustomShellComboBoxProperties)

Description

The TcxShellComboBoxProperties class represents the set of attributes specific to shell combo box editors.  These settings can be accessed via the Properties member of an editor.  To control any changes made to the combo box editor’s DisplayFormat, EditFormat, MaxLength, MaxValue, MinValue and ReadOnly properties and reverse their values back to the default ones, use the AssignedValues property.

The properties of a shell combo box editor specify: starting folder options, the possibility of implementing incremental search, the manner in which the path to the current shell item is stored, the display options and shell combo box dropdown options.


TcxShellComboBoxProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |

TcxCustomDropDownEditProperties

     |

TcxCustomPopupEditProperties

     |

TcxCustomShellComboBoxProperties

     |


Properties for TcxShellComboBoxProperties
TcxShellComboBoxProperties Properties

TcxShellComboBoxProperties          Legend

Derived from TcxCustomShellComboBoxProperties

DropDownSizeable

DropDownWidth

FastSearch

IncrementalSearch

Root

ShowFullPath

StoreRelativePath

TreeViewOptions

ViewOptions

Derived from TcxCustomPopupEditProperties

PopupControl

PopupSizeable

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

IncrementalSearch

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 TcxShellComboBoxProperties
TcxShellComboBoxProperties Methods

TcxShellComboBoxProperties          Legend

Derived from TcxCustomMaskEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults


Events for TcxShellComboBoxProperties
TcxShellComboBoxProperties Events

TcxShellComboBoxProperties          Legend

Derived from TcxCustomShellComboBoxProperties

OnAddFolder

Derived from TcxCustomDropDownEditProperties

OnCloseQuery

OnCloseUp

OnInitPopup

OnPopup

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxPopupShellTreeView
TcxPopupShellTreeView Object

Hierarchy          Properties          Methods          Events

Contains the starting folder options for the shell combo box editors.

Unit

cxShellComboBox

TcxPopupShellTreeView = class(TcxShellTreeView)

Description

The TcxShellComboBoxRoot class represents the starting folder options for the shell combo box editors.  It inherits all functionality from its ancestor and publishes several properties.


TcxPopupShellTreeView Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomShellTreeView

     |

TcxShellTreeView

     |


Properties for TcxPopupShellTreeView
TcxPopupShellTreeView Properties

TcxShellTreeView          Legend

Derived from TcxCustomShellTreeView

AbsolutePath

AbsolutePIDL

AutoExpand

ChangeDelay

DragDropSettings

HideSelection

Indent

InnerTreeView

Options

RightClickSelect

Root

ShellListView

ShowButtons

ShowInfoTips

ShowLines

ShowRoot

StateImages

TreeHotTrack

Derived from TcxContainer

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TControl

Align


Methods for TcxPopupShellTreeView
TcxPopupShellTreeView Methods

TcxShellTreeView          Legend

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxPopupShellTreeView
TcxPopupShellTreeView Events

TcxShellTreeView          Legend

Derived from TcxCustomShellTreeView

OnChange

OnChanging

OnCollapsed

OnCollapsing

OnEdited

OnEditing

OnExpanded

OnExpanding


TcxShellComboBoxRoot
TcxShellComboBoxRoot Object

Hierarchy          Properties

Contains the starting folder options for the shell combo box editors.

Unit

cxShellComboBox

TcxShellComboBoxRoot = class(TcxCustomShellRoot)

Description

The TcxShellComboBoxRoot class represents the starting folder options for the shell combo box editors.  It inherits all functionality from its ancestor and publishes several properties.


TcxShellComboBoxRoot Hierarchy
Hierarchy

TPersistent

     |

TcxCustomShellRoot

     |


Properties for TcxShellComboBoxRoot
TcxShellComboBoxRoot Properties

TcxShellComboBoxRoot          Legend

Derived from TcxCustomShellRoot

BrowseFolder

CustomPath

Pidl

ShellFolder


cxShellDlgs Unit Overview
cxShellDlgs Unit

Classes

TcxDlgShellOptions

TcxDlgShellRoot


TcxDlgShellOptions
TcxDlgShellOptions Object

Hierarchy          Properties

Contains settings common to all shell objects.

Unit

cxShellDlgs

TcxDlgShellOptions = class(TPersistent)

Description

The TcxDlgShellOptions class contains options affecting the functionality of the shell browser dialog controls.

These options affect the visibility of the shell items of different types (files or folders), the availability of the context menus to end-users, etc.

You can access the set of options using the Options property of a shell browser dialog.


TcxDlgShellOptions Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxDlgShellOptions
TcxDlgShellOptions Properties

TcxDlgShellOptions          Legend

In TcxDlgShellOptions

 	ContextMenus

ShowFolders

ShowHidden

ShowNonFolders

ShowToolTip

TrackShellChanges


TcxDlgShellOptions.ContextMenus

TcxDlgShellOptions

Determines whether the popup menu is displayed for the right-clicked shell items.

property ContextMenus: Boolean;

Description

Use the ContextMenus property to enable displaying the context menus for the right-clicked shell items.  This menu provides access to many actions specific to the shell items.

The default value of the ContextMenus property is True.


TcxDlgShellOptions.ShowFolders

TcxDlgShellOptions

Determines whether folder shell items are displayed.

property ShowFolders: Boolean;

Description

Use the ShowFolders property to enable displaying folder shell items.  In general, this option enables displaying of the shell items that have sub-items.

If the ShowFolders and ShowNonFolders options are deactivated, then the shell control displays nothing.

The default value of the ShowFolders property is True.


TcxDlgShellOptions.ShowHidden

TcxDlgShellOptions

Determines whether the hidden shell items are displayed.

property ShowHidden: Boolean;

Description

Use the ShowHidden property to enable displaying of the hidden shell items.  This property is in effect only if either the ShowFolders or ShowNonFolders option is activated.

The default value of the ShowHidden property is False.


TcxDlgShellOptions.ShowNonFolders

TcxDlgShellOptions

Determines whether the file shell items are displayed.

property ShowNonFolders: Boolean;

Description

Use the ShowNonFolders property to enable displaying only file shell items.  In general, this option enables displaying of the shell items that have no sub-items.

If the ShowFolders and ShowNonFolders options are deactivated, then the shell control displays nothing.

The default value of the ShowNonFolders property is False.


TcxDlgShellOptions.ShowToolTip

TcxDlgShellOptions

Determines whether the tooltips are displayed for the shell items.

property ShowToolTip: Boolean;

Description

Use the ShowToolTip property to enable displaying of the tooltips for the shell items.  The item tooltip is displayed when the mouse pointer hovers over an item.

Note:	Enabling tooltips results in application slowdown.

The default value of the ShowToolTip property is False.


TcxDlgShellOptions.TrackShellChanges

TcxDlgShellOptions

Determines whether the shell changes are tracked via a shell control.

property TrackShellChanges: Boolean;

Description

Use the TrackShellChanges to specify whether the shell changes are tracked via a shell control.  If this property value is True, then the changes applied to the shell outside of a shell control (for instance, via the Windows Explorer) are instantly reflected by a shell control.

The default value of the TrackShellChanges property is True.


TcxDlgShellRoot
TcxDlgShellRoot Object

Hierarchy          Properties

Represents an object specifying the starting folder options for the shell browser dialog control.

Unit

cxShellDlgs

TcxDlgShellRoot = class(TPersistent);

Description

The TcxDlgShellRoot class represents an object containing the starting folder options for the shell browser dialog control.  The BrowseFolder property allows setting the starting location to any of the common folders: Desktop, Favorites, Program Files, My Computer, etc.  When BrowseFolder is set to bfCutomPath, then the CustomPath property specifies the path to the starting location.


TcxDlgShellRoot Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxDlgShellRoot
TcxDlgShellRoot Properties

TcxDlgShellRoot          Legend

In TcxDlgShellRoot

BrowseFolder

CustomPath


TcxDlgShellRoot.BrowseFolder

TcxDlgShellRoot

Specifies one of the common folders as the starting location.

type

  TcxBrowseFolder = (bfCustomPath, bfAltStartup, bfBitBucket, bfCommonDesktopDirectory, bfCommonDocuments, bfCommonFavorites, bfCommonPrograms, bfCommonStartMenu, bfCommonStartup, bfCommonTemplates, bfControls, bfDesktop, bfDesktopDirectory, bfDrives, bfPrinters, bfFavorites, bfFonts, bfHistory, bfMyMusic, bfMyPictures, bfNetHood, bfProfile, bfProgramFiles, bfPrograms, bfRecent, bfStartMenu, bfStartUp, bfTemplates);

property BrowseFolder: TcxBrowseFolder;

Description

Use the BrowseFolder to select one of the common folders as the starting location for a shell browser dialog control.  Common folders include: My Computer, Desktop, Program Files, Favorites, etc.  If this property is set to the bfCustomPath, then the CustomPath property specifies the starting location.

The default value of the BrowseFolder property is bfDesktop.


TcxDlgShellRoot.CustomPath

TcxDlgShellRoot

Specifies the custom path as the starting location.

property CustomPath: string;

Description

Use the CustomPath property to specify the custom starting location for a shell browser dialog control.  This property value is in effect only if the BrowseFolder property is set to bfCustomPath.  Otherwise, the starting location is defined via the BrowseFolder property.


cxShellListView Unit Overview
cxShellListView Unit

Classes

TcxCustomShellListView

TcxInnerShellListView

TcxShellListView

Global Constants

cxShellObjectInternalAbsoluteVirtualPathPrefix

cxShellObjectInternalRelativeVirtualPathPrefix


TcxCustomShellListView
TcxCustomShellListView Object

Hierarchy          Properties          Methods          Events          See Also

Represents the base class for the TcxShellListView control.

Unit

cxShellListView

TcxCustomShellListView = class(TcxContainer)

Description

The TcxCustomShellListView class implements the basic functionality of shell list view controls.  Shell list view controls are used to display shell items in list view format.  The Shell namespace is the more comprehensive version of the file system and incorporates both file and folder objects residing on the hard disk along with virtual objects, which have no physical analog.  Examples of virtual shell objects are: network printers, networked computers, Control Panel applications, Recycle Bin, and My Computer.

The Shell namespace provides unique identifiers for each included object and stores these identifiers in a tree structure.  Shell item identifiers can be of two types:

•	fully qualified identifiers containing the entire identifier sequence required for reaching a specific shell item;

•	relative identifier, which designates the path to a specific item within its parent folder.

The shell list view control supports two ways of accessing a specific shell item:

•	by specifying the physical path to a shell item via the AbsolutePath property;

•	by specifying the required item’s identifier via the AbsolutePIDL property.

You can handle the OnCurrentFolderChanged event in order to respond to changing the active shell item.

To access the items that are displayed within the shell list view and the corresponding shell items, use the InnerListView.Items and Folders properties, respectively.

To customize the order in which the items will be displayed within the shell list view, handle the OnCompare event.

The TcxCustomShellListView class provides properties which affect the control’s look and feel.  These properties specify:

•	drag-and-drop functionality of the shell list view (see the DragDropSettings property description);

•	shell options, including the ability to access shell items via the keyboard and mouse, displaying folder, non-folder and hidden items, etc.(see the Options property description);

•	starting folder options (see the Root property description);

•	display style for the control (see the ViewStyle property description).


TcxCustomShellListView Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |


Properties for TcxCustomShellListView
TcxCustomShellListView Properties

TcxCustomShellListView          Legend

In TcxCustomShellListView

AbsolutePath

AbsolutePIDL

DragDropSettings

FolderCount

Folders

IconOptions

InnerListView

ListHotTrack

MultiSelect

Options

Root

ViewStyle

Derived from TcxContainer

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxCustomShellListView
TcxCustomShellListView Methods

TcxCustomShellListView          Legend

In TcxCustomShellListView

BrowseParent

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCustomShellListView
TcxCustomShellListView Events

TcxCustomShellListView          Legend

In TcxCustomShellListView

OnAddFolder

OnBeforeNavigation

OnChange

OnCompare

OnCurrentFolderChanged

OnSelectItem

OnShellChange


TcxCustomShellListView.AbsolutePath

TcxCustomShellListView          See Also

Specifies the path to a shell item being accessed.

property AbsolutePath: string;

Description

Use the AbsolutePath property to specify the path to the required shell item.  Folder path can be specified in two ways:

•	as a full path, including all sequence of folders, required for accessing the required shell item from the shell root.

Example:

cxShellListView1.AbsolutePath := 'C:\Documents and Settings\Administrator\My Documents\My Pictures';

•	as a relative path, providing access to shell items within the current folder.

Example:

cxShellListView1.AbsolutePath := 'My Pictures';

The AbsolutePath property allows a user to access both virtual and standard shell items.  Note that virtual shell items have no analog on the hard disk.  You need to specify one of the virtual shell item path prefixes before the virtual shell item’s name.  The cxShellObjectInternalAbsoluteVirtualPathPrefix constant allows accessing the required shell item from any current folder.  The cxShellObjectInternalRelativeVirtualPathPrefix constant allows accessing the required shell item from the Root folder.  Examples of virtual shell items include:

•	Network printers;

•	Other networked computers;

•	Control Panel applications;

•	Recycle Bin.

Example of accessing the Recycle Bin shell item via the absolute and relative virtual path prefix:

cxShellListView1.AbsolutePath := cxShellObjectInternalAbsoluteVirtualPathPrefix + '\Recycle Bin';

cxShellListView1.AbsolutePath := cxShellObjectInternalRelativeVirtualPathPrefix + '\Recycle Bin';

During navigation through the folders, the AbsolutePath property stores the path to the currently accessed shell item.

Note: the AbsolutePath property must contain folder names only.  Specifying the file name within the AbsolutePath property causes unpredictable results.


TcxCustomShellListView.AbsolutePIDL

TcxCustomShellListView          See Also

Specifies the identifier of the shell item being accessed.

property AbsolutePIDL: PItemIDList;

Description

Set the AbsolutePIDL property to specify the identifier of the shell item being accessed.  Both virtual and standard shell items can be accessed using identifiers.  Note that virtual shell items have no physical analogs – files or folders on hard drives.

Using this property is similar to specifying the AbsolutePath property with the cxShellObjectInternalAbsoluteVirtualPathPrefix constant.

Use the AbsolutePIDL property when working with Shell API directly.

You can obtain the text representation of the item’s identifier by calling the GetPidlName function.


TcxCustomShellListView.DragDropSettings

TcxCustomShellListView

Contains drag-and-drop settings for a shell list view.

property DragDropSettings: TcxDragDropSettings;

Description

Use the DragDropSettings property to access settings affecting drag-and-drop functionality of a shell list view.  These settings define:

•	whether drag-and-drop functionality is enabled within the shell list view (see the DragDropSettings.AllowDragObjects property description);

•	visual effects, displayed during scrolling (see the DragDropSettings.DefaultDropEffect and DragDropSettings.DropEffect property descriptions).

Note: not all shell items can be involved in drag-and-drop operations.  You cannot drag-and-drop, for instance, disk drives, Control Panel, My Computer and other special system shell items.


TcxCustomShellListView.FolderCount

TcxCustomShellListView

Returns the total number of shell items that are displayed within a shell list view.

property FolderCount: Integer;

Description

Use the FolderCount property to obtain the total number of shell items (folder objects and file objects) that are displayed within a shell list view.  Use the Folders property to access a particular shell item.

ReadOnly Property


TcxCustomShellListView.Folders

TcxCustomShellListView          See Also

Provides access to shell items that are displayed within a shell list view.

property Folders[AIndex: Integer]: TcxShellFolder;

Description

Use the Folders property to access shell items (folder objects and file objects) that are displayed within a shell list view.  Each shell item is represented by an instance of the TcxShellFolder class.

The shell items within the Folders property correspond to the items within the InnerListView.Items property, i.e. these items have the same indexes by which they can be addressed.

When the current folder changes, the Folders property provides access to the shell items within the current folder.  Every time a shell item is added to the shell list view, the OnAddFolder event is raised.

Use the FolderCount property to obtain the total number of shell items that are displayed within a shell list view.

ReadOnly Property


TcxCustomShellListView.IconOptions

TcxCustomShellListView          See Also

Contains icon options for a shell list view.

property IconOptions: TIconOptions;

Description

The IconOptions property contains various options affecting icons within a shell list view. The IconOptions.Arrangement property defines the manner in which icons are aligned within a shell list view:

Value	Meaning
iaTop	Items are aligned left to right in rows at the top of the view control
iaLeft	Items are aligned in columns top to bottom at the left of the view control

IconOptions.AutoArrange property defines whether list view icons are automatically rearranged when icons are added, moved or deleted within a list view.  If this property value is False, then icons are rearranged only after the call to the Arrange method.  IconOptions.WrapText property determines whether the text within the icon’s label is wrapped.

Note:	IconOptions settings are in effect only if the ViewStyle is set to vsIcon or vsSmallIcon.


TcxCustomShellListView.InnerListView

TcxCustomShellListView

Provides access to the instance of the object which implements the inner functionality of the TcxShellListView control.

property InnerListView: TcxInnerShellListView;

Description

Use the InnerListView property to access the instance of the object which implements the inner functionality of the TcxShellListView control.


TcxCustomShellListView.ListHotTrack

TcxCustomShellListView

Determines whether the shell list view items can be hot-tracked.

property ListHotTrack: Boolean;

Description

Use the ListHotTrack property to enable item hot-tracking within a shell list view.  When the mouse pointer hovers over shell list view items and the HotTrack property is set to True, items are hot-tracked.

The default value of the ListHotTrack property is False.


TcxCustomShellListView.MultiSelect

TcxCustomShellListView

Determines whether multiple items can be selected.

property MultiSelect: Boolean;

Description

Use the MultiSelect property to determine whether multiple items can be selected within a shell list view.  If this property value is True, then a user can select several items within the shell list view.  This applies to keyboard and mouse navigation.  The Shift key is used to select a range of items, and the Ctrl key is used to select non-contiguous items.

The default value of the MultiSelect property is False.


TcxCustomShellListView.Options

TcxCustomShellListView

Contains shell list view options.

property Options: TcxShellListViewOptions;

Description

Use the Options property to access a set of appearance and functionality options specific to the shell list view.  These options determine:

•	whether the shell list view displays only folder or non folder shell items (see the Options.ShowFolders and Options.ShowNonFolders property descriptions).  Regardless of the state of these options, you can access the required shell item via the AbsolutePath or AbsolutePIDL properties;

•	whether the shell list view displays hidden shell items and shell context menus (see the Options.ShowHidden and Options.ContextMenus property descriptions);

•	whether a user can access folders and open files by pressing the Enter key or by double-clicking the mouse (see the Options.AutoNavigate property description).  If this option is deactivated, you can still access the required shell item via the AbsolutePath or AbsolutePIDL properties;

•	whether the shell list view reflects all changes, occurring among shell items (see the Options.TrackShellChanges property description);

•	whether shell items tool tips are displayed when the mouse pointer is positioned over items (see the Options.ShowToolTip property description).


TcxCustomShellListView.Root

TcxCustomShellListView

Contains starting folder options.

property Root: TcxShellListRoot;

Description

Use the Root property to access shell list view starting folder options.  The Root.BrowseFolder property specifies the folder that is opened when the shell list view is created.  If this property is set to bfCustomPath, then the starting folder path is defined by the Root.CustomPath property.

The current path to the currently opened shell item is specified via the AbsolutePath property.  If the current starting folder is virtual (for instance, Recycle Bin), then the folder’s identifier can be accessed via the AbsolutePIDL property.


TcxCustomShellListView.ViewStyle

TcxCustomShellListView

Defines the manner in which shell list view items are displayed.

type

  TViewStyle = (vsIcon, vsSmallIcon, vsList, vsReport);

property ViewStyle: TViewStyle;

Description

The ViewStyle property specifies the style used to display shell list view items. The following view styles are supported:

Property’s Value	Meaning	Effect
vsIcon	Shell items are displayed as large icons with the item name next to each.
vsSmallIcons	Shell items are displayed as small icons with the item name next to each.
vsList	Shell items are arranged into columns.
vsReport	Shell items are arranged into columns.  Columns contain information based upon shell item type.  In general, additional information on the shell item includes: shell item type, item size and modification date.

The default value of the ViewStyle property is vsIcon.


TcxCustomShellListView.BrowseParent

TcxCustomShellListView          See Also

Navigates to the parent shell item of the currently selected shell item.

procedure BrowseParent;

Description

Use the BrowseParent method to navigate to the parent shell item of the currently selected shell item.  If the shell root (desktop) is currently selected, then this method is not in effect.


TcxCustomShellListView.OnAddFolder

TcxCustomShellListView          See Also

Occurs when a shell item is added to the shell list view.

type

  TcxShellAddFolderEvent = procedure(Sender: TObject; AFolder: TcxShellFolder; var ACanAdd: Boolean) of object;

property OnAddFolder: TcxShellAddFolderEvent;

Description

The OnAddFolder event occurs when a shell item is added to the shell list view control.  The AFolder parameter specifies the shell item being added.  The ACanAdd parameter indicates whether the item will be added to the shell list view and is initially equal to True.  Once added, the shell item can be accessed via the Folders property.  Set the ACanAdd parameter to False to prevent the shell item from being displayed within the shell list view.


TcxCustomShellListView.OnBeforeNavigation

TcxCustomShellListView          See Also

Occurs before navigating to a new shell item.

type

  TcxBeforeNavigationEvent = procedure(Sender: TcxCustomShellListView; ANewAbsolutePIDL: PItemIDList) of object;

property OnBeforeNavigation: TcxBeforeNavigationEvent;

Description

The OnBeforeNavigation event occurs before navigating to a new shell item.  The new shell item is identified by the ANewAbsolutePIDL parameter.  This parameter is a PItemIDList value, representing a new shell item.  In order to convert this value to a readable string, use the GetPIDLName function.

The following code example prints the path to the accessed shell item within a status bar:

//Delphi

procedure TForm1.cxShellListView1BeforeNavigation(Sender: TcxCustomShellListView; ANewAbsolutePIDL: PItemIDList);

begin

  StatusBar1.SimpleText := GetPidlName(ANewAbsolutePIDL);

end;


TcxCustomShellListView.OnChange

TcxCustomShellListView

Occurs after an item was changed.

type

  TItemChange = (ctText, ctImage, ctState);

  TLVChangeEvent = procedure(Sender: TObject; Item: TListItem; Change: TItemChange) of object;

property OnChange: TLVChangeEvent;

Description

The OnChange event occurs when a shell item changes.  The item that has been changed and the type of changes that occurred are specified via the Item and Change parameters, respectively.

The following table lists all the possible types of changes (values of the Change parameter).

Value	Meaning
ctText	The item’s Caption property has been changed.
ctImage	The item’s ImageIndex property or the appropriate image list in the shell list view have been changed.
ctState	The item’s Cut, Focused or Selected properties have been changed.


TcxCustomShellListView.OnCompare

TcxCustomShellListView

Occurs when two items are compared when sorting the shell list view.

type

  TcxShellCompareEvent = procedure(Sender: TObject; AItem1, AItem2: TcxShellFolder; out ACompare: Integer) of object;

property OnChange: TcxShellCompareEvent;

Description

By default, items within the shell list view are sorted so that the corresponding folder objects precede file objects.  Then both folder objects and file objects are sorted independently in alphabetical order.  The OnCompare event is fired each time two shell items are compared to determine their relative position within the list.

Handle the OnCompare event to customize the order in which the items will be displayed in the shell list view.  The shell items being compared are passed as the AItem1 and AItem2 parameters.  Set the ACompare parameter to specify the order in which these shell items will be displayed.

All the possible values of the ACompare parameter are listed in the following table.

Value	Meaning
0	The shell items are the same.
A negative value	AItem1 precedes AItem2.
A positive value	AItem2 precedes AItem1.

The following code snippet demonstrates how to revert the default order of shell items within the shell list view.

//Delphi

procedure TForm1.cxShellListView1Compare(Sender: TObject; AItem1,

  AItem2: TcxShellFolder; out ACompare: Integer);

begin

  if AItem1.IsFolder = AItem2.IsFolder then

    ACompare := -CompareStr(AItem1.DisplayName, AItem2.DisplayName)

  else

    if AItem1.IsFolder then

      ACompare := 1

    else

      ACompare := -1;

    exit;

end;


TcxCustomShellListView.OnCurrentFolderChanged

TcxCustomShellListView

Occurs after the current folder changes within the cxShellListView control.

type

  TcxCurrentFolderChangedEvent = procedure(Sender: TcxCustomShellListView) of object;

property OnCurrentFolderChanged: TcxCurrentFolderChangedEvent;

Description

The OnCurrentFolderChanged event occurs after the current folder within the shell list view changes.  You can use the AbsolutePath property to get or set the current path.


TcxCustomShellListView.OnSelectItem

TcxCustomShellListView

Occurs when a shell item is selected or unselected.

type

  TLVSelectItemEvent = procedure(Sender: TObject; Item: TListItem; Selected: Boolean) of object;

property OnSelectItem: TLVSelectItemEvent;

Description

The OnSelectItem event occurs when a shell item is selected or unselected.  The Item parameter specifies the processed shell item.  The Selected parameter is True when an item is selected and False otherwise.


TcxCustomShellListView.OnShellChange

TcxCustomShellListView          See Also

Occurs when performing an event that may change the Shell namespace.

type

  TcxShellChangeEvent = procedure(Sender: TObject; AEventID: DWORD; APIDL1, APIDL2: PItemIDList) of object;

property OnShellChange: TcxShellChangeEvent;

Description

The AEventID parameter specifies the event that has occurred.  The APIDL1 and APIDL2 parameters represent event-dependent item identifiers.  Refer to the description of the IShellChangeNotify.OnChange method in the Windows SDK help system for details on the values of the AEventID, APIDL1, and APIDL2 parameters.

Note:	The OnShellChange event is not raised when the shell list view’s Options.TrackShellChanges property is set to False.


TcxInnerShellListView
TcxInnerShellListView Object

Hierarchy          Properties

Represents an object implementing the inner list view functionality of the TcxShellListView.

Unit

cxShellListView

TcxInnerShellListView = class(TcxCustomInnerShellListView);

Description

The TcxInnerShellListView class implements the inner functionality of the TcxShellListView control.  An instance of this class can be accessed via the editor’s InnerListView property.  It provides the Items property allowing to access the currently displayed shell items.


TcxInnerShellListView Hierarchy
Hierarchy

TCustomListView

     |

TcxCustomInnerShellListView

     |


Properties for TcxInnerShellListView
TcxInnerShellListView Properties

TcxInnerShellListView          Legend

In TcxInnerShellListView

Items

Derived from TControl

Align


TcxInnerShellListView.Items

TcxInnerShellListView          See Also

Provides indexed access to the items, displayed within the shell list view.

property Items;

Description

Use the Items property to access the list of items displayed within the shell list view.  The item with zero index among the Items is displayed in the top-left corner within the shell list view.  When the current folder changes, the Items property gives access to the shell items within the current folder.


TcxShellListView
TcxShellListView Object

Hierarchy          Properties          Methods          Events         See Also

Represents a shell list view control.

Unit

cxShellListView

TcxShellListView = class(TcxCustomShellListView)

Description

The TcxShellListView class represents a shell list view control.  Shell list view controls are used to display shell items in list format.  The Shell namespace provides a unique identifier for each included object and stores these identifiers in a tree structure.  Shell item identifiers can be of two types: fully qualified identifier, containing the entire identifier sequence, required for reaching a specific shell item, and relative identifier, which designates the path to a specific item within its parent folder.

The shell list view control supports two manners of accessing a specific shell item:

•	by specifying the physical path to a shell item via the AbsolutePath property

•	by specifying the required item’s identifier via the AbsolutePIDL property.

You can handle the OnCurrentFolderChanged event in order to respond to changing the active shell item.

To access the items that are displayed within the shell list view and the corresponding shell items, use the InnerListView.Items and Folders properties, respectively.

The TcxShellListView class provides properties, affecting the control’s look and feel.  These properties specify:

•	Drag-and-drop functionality of the shell list view (see the DragDropSettings property description);

•	Shell options, including the ability to access shell items via the keyboard and mouse, displaying folder, non-folder and hidden items, etc.(see the Options property description);

•	Starting folder options (see the Root property description);

•	Display style for the control (see the Root property description).

The following screenshot demonstrates a shell list view control, displaying the Control Panel shell item contents:


TcxShellListView Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomShellListView

     |


Properties for TcxShellListView
TcxShellListView Properties

TcxShellListView          Legend

Derived from TcxCustomShellListView

AbsolutePath

AbsolutePIDL

DragDropSettings

FolderCount

Folders

IconOptions

InnerListView

ListHotTrack

MultiSelect

Options

Root

ViewStyle

Derived from TcxContainer

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

Derived from TControl

Align


Methods for TcxShellListView
TcxShellListView Methods

TcxShellListView          Legend

Derived from TcxCustomShellListView

BrowseParent

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxShellListView
TcxShellListView Events

TcxShellListView          Legend

Derived from TcxCustomShellListView

OnAddFolder

OnBeforeNavigation

OnChange

OnCompare

OnCurrentFolderChanged

OnSelectItem

OnShellChange


cxShellObjectInternalAbsoluteVirtualPathPrefix constant
cxShellObjectInternalAbsoluteVirtualPathPrefix global constant

Represents the absolute virtual path prefix.

Unit

cxShellListView

cxShellObjectInternalAbsoluteVirtualPathPrefix = '::{9C211B58-E6F1-456A-9F22-7B3B418A7BB1}';

Description

Use the cxShellObjectInternalAbsoluteVirtualPathPrefix constant to access a virtual shell item.  Virtual shell items have no physical analogs.  Examples of virtual shell objects are: network printers, networked computers, Control Panel applications, Recycle Bin, and My Computer.

The cxShellObjectInternalAbsoluteVirtualPathPrefix constant provides absolute access to virtual shell items regardless of the current folder opened within a shell control.

The following code example demonstrates how to access the Control Panel shell item:

//Delphi

cxShellListView1.AbsolutePath := cxShellObjectInternalAbsoluteVirtualPathPrefix + '\My Computer\Control Panel';


cxShellObjectInternalRelativeVirtualPathPrefix constant
cxShellObjectInternalRelativeVirtualPathPrefix global constant

Provides the relative virtual path prefix.

Unit

cxShellListView

cxShellObjectInternalRelativeVirtualPathPrefix = '::{63BE9ADB-E4B5-4623-96AA-57440B4EF5A8}';

Description

Use the cxShellObjectInternalRelativeVirtualPathPrefix constant to access a virtual shell item.  Virtual shell items have no physical analogs.  Examples of virtual shell objects are: network printers, networked computers, Control Panel applications, Recycle Bin, and My Computer.

The cxShellObjectInternalRelativeVirtualPathPrefix constant provides access to virtual shell items relative to the currently opened shell item.

The following example demonstrates how to access the Control Panel shell item from the My Computer "folder":

//Delphi

cxShellListView1.AbsolutePath := cxShellObjectInternalAbsoluteVirtualPathPrefix + '\Control Panel';


cxShellTreeView Unit Overview
cxShellTreeView Unit

Classes

TcxCustomShellTreeView

TcxInnerShellTreeView

TcxShellTreeView


TcxCustomShellTreeView
TcxCustomShellTreeView Object

Hierarchy          Properties          Methods          Events

Represents the base class for the TcxShellTreeView control.

Unit

cxShellTreeView

TcxCustomShellTreeView = class(TcxContainer)

Description

The TcxCustomShellTreeView class implements the basic functionality of shell tree view controls.  Shell tree view controls are used to display shell items in a tree-like manner.  The Shell namespace is the more comprehensive version of the file system and incorporates both file and folder objects residing on the hard disk along with virtual objects, which have no physical analog.  Examples of virtual shell objects are: network printers, networked computers, Control Panel applications, Recycle Bin, and My Computer.

The Shell namespace provides unique identifiers for each included object and stores these identifiers in a tree structure.  Shell item identifiers can be of two types: fully qualified identifiers containing the entire identifier sequence required for reaching a specific shell item, and relative identifier, which designates the path to a specific item within its parent folder.

The shell tree view control supports two ways of accessing a specific shell item:

•	by specifying the physical path to a shell item via the AbsolutePath property;

•	by specifying the required item’s identifier via the AbsolutePIDL property.

To access the nodes that are displayed within the shell tree view and the corresponding shell items, use the InnerTreeView.Items and Folders properties, respectively.

The TcxCustomShellTreeView class provides properties, affecting the control’s look and feel.  These properties specify:

•	drag-and-drop functionality of the shell list view (see the DragDropSettings property description);

•	shell options, including the ability to access shell items via the keyboard and mouse, displaying folder, non-folder and hidden items, etc.(see the Options property description);

•	starting folder options (see the Root property description).


TcxCustomShellTreeView Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |


Properties for TcxCustomShellTreeView
TcxCustomShellTreeView Properties

TcxCustomShellTreeView          Legend

In TcxCustomShellTreeView

AbsolutePath

AbsolutePIDL

AutoExpand

ChangeDelay

DragDropSettings

FolderCount

Folders

HideSelection

Indent

InnerTreeView

Options

RightClickSelect

Root

ShellListView

ShowButtons

ShowInfoTips

ShowLines

ShowRoot

StateImages

TreeHotTrack

Derived from TcxContainer

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxCustomShellTreeView
TcxCustomShellTreeView Methods

TcxCustomShellTreeView          Legend

In TcxCustomShellTreeView

GetNodeAbsolutePIDL

UpdateContent

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCustomShellTreeView
TcxCustomShellTreeView Events

TcxCustomShellTreeView          Legend

In TcxCustomShellTreeView

OnAddFolder

OnChange

OnChanging

OnCollapsed

OnCollapsing

OnEdited

OnEditing

OnExpanded

OnExpanding

OnShellChange


TcxCustomShellTreeView.AbsolutePath

TcxCustomShellTreeView          See Also

Specifies the path to the shell item being accessed via the starting folder.

property AbsolutePath: string;

Description

Use the AbsolutePath property to specify the path to the required shell node.  Folder path can be specified in two ways:

•	as a full path, including all sequence of folders, required for accessing the required shell node from the shell root.

Example:

cxShellTreeView1.AbsolutePath := 'C:\Documents and Settings\Administrator\My Documents\My Pictures';

•	as a relative path, providing access to shell nodes within the current folder.

Example:

cxShellTreeView1.AbsolutePath := 'My Pictures';

The AbsolutePath property allows a user to access both virtual and standard shell items.  Note that virtual shell items have no analog on the hard disk.  You need to specify one of the virtual shell item path prefixes before the virtual shell item name.  The cxShellObjectInternalAbsoluteVirtualPathPrefix constant allows accessing the required shell item from any current folder.  The cxShellObjectInternalRelativeVirtualPathPrefix constant allows accessing the required shell item from the Root folder.  Examples of virtual shell items include:

•	Network printers;

•	Other networked computers;

•	Control Panel applications;

•	Recycle Bin.

Example of accessing the Recycle Bin shell item via the absolute and relative virtual path prefix:

cxShellTreeView1.AbsolutePath := cxShellObjectInternalAbsoluteVirtualPathPrefix + '\Recycle Bin';

cxShellTreeView1.AbsolutePath := cxShellObjectInternalRelativeVirtualPathPrefix + '\Recycle Bin';

During navigation through the folders, the AbsolutePath property stores the path to the currently accessed shell node.

Note: the AbsolutePath property must contain folder names only.  Specifying the file name within the AbsolutePath property causes unpredictable results.


TcxCustomShellTreeView.AbsolutePIDL

TcxCustomShellTreeView          See Also

Specifies the identifier of the shell item being accessed via the starting folder.

property AbsolutePIDL: PItemIDList;

Description

Set the AbsolutePIDL property to specify the identifier of the shell item being accessed via the starting folder.  Both virtual and standard shell items can be accessed using identifiers.  Note that virtual shell items have no physical analogs – files or folders on hard drives.

Using this property is similar to specifying the AbsolutePath property with the cxShellObjectInternalAbsoluteVirtualPathPrefix constant.

Use the AbsolutePIDL property when working with the Shell API directly.

You can obtain the node’s identifier and its text representation by calling the GetNodeAbsolutePIDL and GetPidlName function, respectively.


TcxCustomShellTreeView.AutoExpand

TcxCustomShellTreeView

Specifies whether parent nodes are automatically expanded and collapsed when clicked.

property AutoExpand: Boolean;

Description

Set the AutoExpand property to True to enable automatic node expansion and collapse.  If enabled, parent nodes are automatically expanded when selected using the mouse (other expanded nodes are collapsed in this instance).  If you click an expanded node, it is collapsed.

You can change the expanded state of nodes by using the keyboard, expand buttons and via code independently of the AutoExpand property.

If the AutoExpand property is set to False, clicking a node merely results in selecting it.  If you need to change the expanded state of nodes, you need to double-click them.

The default value of the AutoExpand property is False.


TcxCustomShellTreeView.ChangeDelay

TcxCustomShellTreeView          See Also

Specifies the time interval (in milliseconds) that passes between selecting a node and the OnChange event being raised.

property ChangeDelay: Integer;

Description

You can respond to nodes being selected in the shell tree view control by handling the OnChange event.  This can for instance, be used to update the contents of a form with respect to the currently selected item (or perform other time-consuming operations).  In such cases, you may want to specify a delay between an item being selected and the desired actions being performed.  This is helpful in two cases.  If the user clicks the wrong node, he has time to correct his choice before any time-consuming operation begins.  This is also useful when performing navigation using the keyboard.

To specify the delay before responding to node selection, use the ChangeDelay property.  This property value is set in milliseconds.  Thus, if you need a half second delay, set this property to 500.  If you need the shell tree view to respond to selection changes immediately, set this property to 0.

Note:	setting this property to a negative value has the same effect as setting it to 0.

The default value of the ChangeDelay property is 0.


TcxCustomShellTreeView.DragDropSettings

TcxCustomShellTreeView

Contains drag-and-drop settings for a shell tree view.

property DragDropSettings: TcxDragDropSettings;

Description

Use the DragDropSettings property to access settings affecting drag-and-drop functionality of a shell tree view.  These settings define:

•	whether drag-and-drop functionality is enabled within the shell tree view (see the DragDropSettings.AllowDragObjects property description);

•	visual effects, displayed during scrolling (see the DragDropSettings.DefaultDropEffect and DragDropSettings.DropEffect property descriptions).

Note: not all shell nodes can be involved in drag-and-drop operations.  You cannot drag-and-drop, for instance, disk drives, Control Panel, My Computer and other special system shell nodes.


TcxCustomShellTreeView.FolderCount

TcxCustomShellTreeView

Returns the total number of shell items that are displayed within a shell tree view.

property FolderCount: Integer;

Description

Use the FolderCount property to obtain the total number of shell items (folder objects and file objects) that are displayed within a shell tree view.  Use the Folders property to access a particular shell item.

ReadOnly Property


TcxCustomShellTreeView.Folders

TcxCustomShellTreeView          See Also

Provides access to shell items that are displayed within a shell tree view.

property Folders[AIndex: Integer]: TcxShellFolder;

Description

Use the Folders property to access shell items (folder objects and file objects) that are displayed within a shell tree view.  Each shell item is represented by an instance of the TcxShellFolder class.

The shell items within the Folders property correspond to the nodes within the InnerTreeView.Items property, i.e. nodes and shell items have the same indexes by which they can be addressed.  Every time a shell item is added to the shell tree view, the OnAddFolder event is raised.

Expanding a specific parent node increases the number of Folders by the number of child nodes.

Use the FolderCount property to obtain the total number of shell items that are displayed within a shell tree view.

ReadOnly Property


TcxCustomShellTreeView.HideSelection

TcxCustomShellTreeView

Specifies whether selection is hidden when the shell tree view looses focus.

property HideSelection: Boolean;

Description

The image below shows a sample tree view control with some of its nodes selected.  The control is focused.

The next screenshots illustrate the appearance of the control when it is not focused.  The HideSelection property is set to True and False respectively.

The default value of the HideSelection property is True.


TcxCustomShellTreeView.Indent

TcxCustomShellTreeView

Specifies the horizontal indent between parent and child nodes.

property Indent: Integer;

Description

Use the Indent property to change the indent between parent nodes and their children.  The indent is set in pixels.  Note that changing the Indent property also affects the position of first level nodes.

The images below show the same tree view control with the Indent property set to 19 and 30.  Note the change of the horizontal offset between nodes at different levels.

The Indent property cannot be set to a value less than 19.

Note:	If the ShowRoot property is set to False (expand buttons and tree lines are not displayed for root nodes), the Indent property doesn’t affect the offset of root level nodes from the left edge of the control.  The contents of root level nodes are always aligned to left in this instance.


TcxCustomShellTreeView.InnerTreeView

TcxCustomShellTreeView

Provides access to the instance of the object which implements the inner functionality of the TcxShellTreeView control.

property InnerTreeView: TcxInnerShellTreeView;

Description

Use the InnerTreeView property to access the instance of the object which implements the inner functionality of the TcxShellTreeView control.


TcxCustomShellTreeView.Options

TcxCustomShellTreeView

Contains shell tree view options.

property Options: TcxShellOptions;

Description

Use the Options property to access a set of appearance and functionality options specific to the shell tree view.  These options determine:

•	whether the shell list view displays only folder or non folder shell nodes (see the Options.ShowFolders and Options.ShowNonFolders property descriptions).  Regardless of the state of these options, you can access the required shell node via the AbsolutePath or AbsolutePIDL properties;

•	whether the shell list view displays hidden shell nodes and shell context menus (see the Options.ShowHidden and Options.ContextMenus property descriptions);

•	whether the shell list view reflects all changes, occurring among shell nodes (see the Options.TrackShellChanges property description);

•	whether shell nodes tool tips are displayed when the mouse pointer is positioned over nodes (see the Options.ShowToolTip property description).


TcxCustomShellTreeView.RightClickSelect

TcxCustomShellTreeView

Specifies whether the InnerTreeView.Selected property returns the right-clicked node when the control’s popup menu is invoked.

property RightClickSelect: Boolean;

Description

The RightClickSelect property is useful if you need to have a context menu associated with the shell tree view to perform specific actions on nodes.  In this instance, you need to bind a TPopupMenu component to the tree view control using the control’s PopupMenu property.  If such binding has been performed, right-clicking the shell tree view control will result in invoking the popup menu.  The easiest way to determine the node for which the menu has been invoked is to read the InnerTreeView.Selected property value when handling the OnPopup event of the menu.  This property will return the right-clicked node if the RightClickSelect property is set to True.  Otherwise, the node that was last left-clicked will be returned.

The default value of the RightClickSelect property is False.


TcxCustomShellTreeView.Root

TcxCustomShellTreeView

Contains starting folder options.

property Root: TcxShellTreeRoot;

Description

Use the Root property to access shell tree view starting folder options.  The Root.BrowseFolder property specifies the folder that is opened when the shell tree view is created.  If this property is set to bfCustomPath, then the starting folder path is defined by the Root.CustomPath property.

The current path to the currently opened shell node is specified via the AbsolutePath property.  If the current starting folder is virtual (for instance, Recycle Bin), then the folder’s identifier can be accessed via the AbsolutePIDL property.


TcxCustomShellTreeView.ShellListView

TcxCustomShellTreeView

Specifies the TcxShellListView control associated with the current shell tree view.

property ShellListView: TcxCustomShellListView;

Description

Use the ShellListView property to associate a shell list view control with the current shell tree view.  The cxShellTreeView specified via this property is synchronized with the current shell tree view.

When a specific shell item is selected within the shell tree view, this item contents are displayed within the associated shell list view.  If the currently selected shell tree view node represents a file, then the associated shell list view displays the contents of the last selected folder.


TcxCustomShellTreeView.ShowButtons

TcxCustomShellTreeView

Specifies whether expand buttons are displayed within nodes that have children.

property ShowButtons: Boolean;

Description

Set the ShowButtons property to False to hide expand buttons displayed within parent nodes.  The images below show you the tree view control when the ShowButtons property is set to True and False respectively.

If expand buttons are not displayed, end users can use the following methods to expand and collapse parent nodes:

•	Pressing the right and left arrow keys when the desired parent node is selected;

•	Double-clicking the desired parent node if the AutoExpand property value is False;

•	Single-clicking the desired parent node if the AutoExpand property value is True.

Note:	You can hide expand buttons only on the root level of the tree.  Set the ShowRoot property to False for this purpose.

The default value of the ShowButtons property is True.


TcxCustomShellTreeView.ShowInfoTips

TcxCustomShellTreeView

Specifies whether tool tips are displayed for shell items.

property ShowInfoTips: Boolean;

Description

Set the ShowInfoTips property to True to display tool tips for shell items.  These tool tips contain display information specific to the shell item type:

•	a short description for virtual shell items;

•	the total size and a list of the contained folders and files for folders.

The default value of the ShowInfoTips property is True.


TcxCustomShellTreeView.ShowLines

TcxCustomShellTreeView

Specifies whether tree lines are visible.

property ShowLines: Boolean;

Description

Set the ShowLines property to False to hide tree lines.  If it is set to True, tree lines are displayed.  The images below illustrate both values for this property.

The default value of the ShowLines property is True.


TcxCustomShellTreeView.ShowRoot

TcxCustomShellTreeView

Specifies the visibility of tree lines and expand buttons at the root level of the tree.

property ShowRoot: Boolean;

Description

Set the ShowRoot property to False to hide tree lines and expand buttons at the root level of the tree.  If they are hidden, contents of root nodes are displayed at the left edge of the control without any indent independently of the Indent property value.  The Indent property affects only the offset of child nodes relative to their parents.

The images below show sample shell tree view controls when the ShowRoot property is set to True and False respectively.

You can also hide all tree lines and all expand buttons within the control.  Use the ShowLines and ShowButtons properties for this purpose.

The default value of the ShowRoot property is True.


TcxCustomShellTreeView.StateImages

TcxCustomShellTreeView

Provides state images to be displayed within tree nodes.

property StateImages: TCustomImageList;

Description

Use the StateImages property to assign the TImageList component storing the desired images.  You can then choose an image from the list to be displayed within the node by setting the node’s StateIndex property.


TcxCustomShellTreeView.TreeHotTrack

TcxCustomShellTreeView

Determines whether the shell tree view nodes can be hot-tracked.

property TreeHotTrack: Boolean;

Description

Use the ListHotTrack property to enable node hot-tracking within a shell tree view.  When the mouse pointer hovers over shell tree view nodes and the HotTrack property is set to True, nodes are hot-tracked.

The default value of the TreeHotTrack property is False.


TcxCustomShellTreeView.GetNodeAbsolutePIDL

TcxCustomShellTreeView

Returns the identifier for a specific shell node.

function GetNodeAbsolutePIDL(ANode: TTreeNode): PItemIDList;

Description

Use the GetNodeAbsolutePIDL function to obtain the identifier for the shell item specified by the ANode parameter.  Use the GetNodeAbsolutePIDL function when working with the Shell API directly.

To obtain the text representation of the node’s identifier call the GetPidlName function.


TcxCustomShellTreeView.UpdateContent

TcxCustomShellTreeView

Refreshes the contents of the shell tree view control.

procedure UpdateContent;

Description

Use the UpdateContent method to explicitly update the contents of the shell tree view control so as to get the latest up-to-date information on the file system (for instance, when changes to the shell were made programmatically or outside of the control and the changes are not tracked by the control, i.e. the Options.TrackShellChanges property is set to False).


TcxCustomShellTreeView.OnAddFolder

TcxCustomShellTreeView          See Also

Occurs when a shell item is added to the shell tree view.

type

  TcxShellAddFolderEvent = procedure(Sender: TObject; AFolder: TcxShellFolder; var ACanAdd: Boolean) of object;

property OnAddFolder: TcxShellAddFolderEvent;

Description

The OnAddFolder event occurs when a shell item is added to the shell tree view.  The AFolder parameter specifies the shell item being added.  The ACanAdd parameter indicates whether the item will be added to the shell tree view and is initially equal to True.  Once added, the shell item can be accessed via the Folders property.  Set the ACanAdd parameter to False to prevent the shell item from being displayed within the shell tree view.


TcxCustomShellTreeView.OnChange

TcxCustomShellTreeView          See Also

Occurs when selection changes within the shell tree view.

type

  TTVChangedEvent = procedure(Sender: TObject; Node: TTreeNode) of object;

property OnChange: TTVChangedEvent;

Description

Write an OnChange event handler to take specific action when the selected node changes. The Sender parameter is the shell tree view whose selected node changes, and the Node parameter is the newly selected node.

Note:	The OnChange event does not occur for nodes selected using the right mouse button when RightClickSelect is True.  To respond to changes in the value of the InnerTreeView.Selected property when RightClickSelect is True, use the OnMouseUp event.


TcxCustomShellTreeView.OnChanging

TcxCustomShellTreeView          See Also

Occurs when the selection is about to change from one node to another.

type

  TTVChangingEvent = procedure(Sender: TObject; Node: TTreeNode; var AllowChange: Boolean) of object;

property OnChanging: TTVChangingEvent;

Description

Write an OnChanging event handler to selectively prevent selection from moving to specific nodes.

Set the AllowChange parameter to False, to prevent selection from moving to a new node. The Node parameter specifies the node that is about to be selected.


TcxCustomShellTreeView.OnCollapsed

TcxCustomShellTreeView          See Also

Occurs after the shell tree view node is collapsed.

type

  TTVExpandedEvent = procedure(Sender: TObject; Node: TTreeNode) of object;

property OnCollapsed: TTVExpandedEvent;

Description

Write an OnCollapsed event handler to perform specific actions after a specific node collapses.  The Node parameter specifies the collapsed node.

You can handle the OnCollapsing event to prevent a node from collapsing.  Handle the OnExpanded and OnExpanding events to respond to the nodes’ expanding.


TcxCustomShellTreeView.OnCollapsing

TcxCustomShellTreeView          See Also

Occurs when the shell tree view node is being collapsed.

type

  TTVCollapsingEvent = procedure(Sender: TObject; Node: TTreeNode; var AllowCollapse: Boolean) of object;

property OnCollapsing: TTVCollapsingEvent;

Description

Write an OnCollapsing event handler to prevent node collapsing.  The Node parameter returns the node, being collapsed.  Setting the AllowCollapse parameter to False prevents the node from collapsing.


TcxCustomShellTreeView.OnEdited

TcxCustomShellTreeView          See Also

Occurs after the Text property of a node changes.

type

  TTVEditedEvent = procedure(Sender: TObject; Node: TTreeNode; var S: string) of object;

property OnEdited: TTVEditedEvent;

Description

Write an OnEdited event handler to respond to changes the user makes to the node labels. The Node parameter is the node whose label was edited. The S parameter is the new value of the node’s Text property. The node’s label can be changed in an OnEdited event handler before the user’s edits are committed. This event can occur only if ReadOnly is set to False.


TcxCustomShellTreeView.OnEditing

TcxCustomShellTreeView          See Also

Occurs when an end-user starts editing of the node’s Text.

type

  TTVEditingEvent = procedure(Sender: TObject; Node: TTreeNode; var AllowEdit: Boolean) of object;

property OnEditing: TTVEditingEvent;

Description

Write an OnEditing event handler to prevent an end-user from editing the node’s Text property.  The Node parameter identifies a node, whose Text is being changed.  Setting the AllowEdit parameter to False prevents the node’s Text from changing.

You can write an OnEdited event handler to change the node’s text after it has been changed.


TcxCustomShellTreeView.OnExpanded

TcxCustomShellTreeView          See Also

Occurs after a specific node expands.

type

  TTVExpandedEvent = procedure(Sender: TObject; Node: TTreeNode) of object;

property OnExpanded: TTVExpandedEvent;

Description

Write an OnExpanded event handler to respond after the node has been expanded.  The Node parameter identifies the expanded node.

You can handle the OnExpanding event to prevent a node from expanding.  Handle the OnCollapsed and OnCollapsing events to respond to the nodes’ collapsing.


TcxCustomShellTreeView.OnExpanding

TcxCustomShellTreeView          See Also

Occurs when the shell tree view node is expanding.

type

  TTVExpandingEvent = procedure(Sender: TObject; Node: TTreeNode; var AllowExpansion: Boolean) of object;

property OnExpanding: TTVExpandingEvent;

Description

Write an OnExpanding event handler to prevent nodes from expanding.  The Node parameter identifies the node being expanded.  Setting the AllowExpansion parameter to False restricts expanding of the specified node.


TcxCustomShellTreeView.OnShellChange

TcxCustomShellListView

Occurs when performing an event that may change the Shell namespace.

type

  TcxShellChangeEvent = procedure(Sender: TObject; AEventID: DWORD; APIDL1, APIDL2: PItemIDList) of object;

property OnShellChange: TcxShellChangeEvent;

Description

The AEventID parameter specifies the event that has occurred.  The APIDL1 and APIDL2 parameters represent event-dependent item identifiers.  Refer to the description of the IShellChangeNotify.OnChange method in the Windows SDK help system for details on the values of the AEventID, APIDL1, and APIDL2 parameters.

Note:	The OnShellChange event is not raised when the shell list view’s Options.TrackShellChanges property is set to False.


TcxInnerShellTreeView
TcxInnerShellTreeView Object

Hierarchy          Properties

Represents an object implementing the inner tree view functionality of the TcxShellTreeView.

Unit

cxShellTreeView

TcxInnerShellTreeView = class(TcxCustomInnerShellTreeView, IcxContainerInnerControl)

Description

The TcxInnerShellTreeView class implements the inner tree view functionality of the TcxShellTreeView control.  An instance of this class can be accessed via the editor’s InnerTreeView property.  It provides the Items property allowing to access the currently displayed nodes.


TcxInnerShellTreeView Hierarchy
Hierarchy

TWinControl

     |

TCustomTreeView

     |

TcxCustomInnerShellTreeView

     |


Properties for TcxInnerShellTreeView
TcxInnerShellTreeView Properties

TcxInnerShellTreeView          Legend

In TcxInnerShellTreeView

Items

Derived from TControl

Align


TcxInnerShellTreeView.Items

TcxInnerShellTreeView          See Also

Provides indexed access to the nodes displayed within the shell tree view.

property Items;

Description

Use the Items property to access the nodes displayed within the shell tree view via their indexes.  Expanding a specific parent node increases the number of Items by the number of the child nodes.


TcxShellTreeView
TcxShellTreeView Object

Hierarchy          Properties          Methods          Events

Represents a shell tree view control.

Unit

cxShellTreeView

TcxShellTreeView = class(TcxCustomShellTreeView)

Description

The TcxShellTreeView class implements the basic functionality of shell tree view controls.  Shell tree view controls are used to display shell items in a tree-like manner.  The Shell namespace is the more comprehensive version of the file system and incorporates both file and folder objects residing on the hard disk along with virtual objects, which have no physical analog.  Examples of virtual shell objects are: network printers, networked computers, Control Panel applications, Recycle Bin, and My Computer.

The Shell namespace provides unique identifiers for each included object and stores these identifiers in a tree structure.  Shell item identifiers can be of two types: fully qualified identifiers containing the entire identifier sequence required for reaching a specific shell item, and relative identifier, which designates the path to a specific item within its parent folder.

The shell tree view control supports two ways of accessing a specific shell item:

•	by specifying the physical path to a shell item via the AbsolutePath property

•	by specifying the required item’s identifier via the AbsolutePIDL property.

To access the nodes that are displayed within the shell tree view and the corresponding shell items, use the InnerTreeView.Items and Folders properties, respectively.

The TcxShellTreeView class provides properties, affecting the control’s look and feel.  These properties specify:

•	drag-and-drop functionality of the shell list view (see the DragDropSettings property description);

•	shell options, including the ability to access shell items via the keyboard and mouse, displaying folder, non-folder and hidden items, etc.(see the Options property description);

•	starting folder options (see the Root property description).

The following screenshot demonstrates a shell tree view control, displaying the Desktop contents:


TcxShellTreeView Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomShellTreeView

     |


Properties for TcxShellTreeView
TcxShellTreeView Properties

TcxShellTreeView          Legend

Derived from TcxCustomShellTreeView

AbsolutePath

AbsolutePIDL

AutoExpand

ChangeDelay

DragDropSettings

FolderCount

Folders

HideSelection

Indent

InnerTreeView

Options

RightClickSelect

Root

ShellListView

ShowButtons

ShowInfoTips

ShowLines

ShowRoot

StateImages

TreeHotTrack

Derived from TcxContainer

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TControl

Align


Methods for TcxShellTreeView
TcxShellTreeView Methods

TcxShellTreeView          Legend

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxShellTreeView
TcxShellTreeView Events

TcxShellTreeView          Legend

Derived from TcxCustomShellTreeView

OnChange

OnChanging

OnCollapsed

OnCollapsing

OnEdited

OnEditing

OnExpanded

OnExpanding

OnShellChange


cxSpinButton Unit Overview
cxSpinButton Unit

Classes

TcxCustomSpinButton

TcxCustomSpinButtonProperties

TcxSpinButton

TcxSpinButtonProperties


TcxCustomSpinButton
TcxCustomSpinButton Object

Hierarchy          Properties          Methods          Example

Serves as the base class for spin button controls.

Unit

cxSpinButton

TcxCustomSpinButton = class(TcxCustomSpinEdit)

Description

The TcxCustomSpinButton class represents the base class for the spin button controls.  A spin button can be connected to a TWinControl to enable editing of the control’s value or for navigation using the keyboard or the spin buttons.  Use the Associate property to bind a spin button to a control.

If a spin button is associated with an edit control, then the latter’s value is obtained from the spin button’s Value property (0 by default).  When the edit control has focus, then the associated spin button handles pressing the Up, Down, PageUp and PageDown keys.  Pressing the Up key or the right/up spin button increases the edit control value while pressing the Down key or the left/down spin button decreases it (increment/decrement is specified by the Properties.Increment property).

The spin button also allows fast navigation through the edit control’s values.  Fast navigation occurs when the user presses the fast buttons or the PageUp/PageDown keys.  In order to enable fast buttons, set the Properties.SpinButtons.ShowFastButtons property to True.  During fast navigation, the edit control’s value is increased/decreased by the Properties.LargeIncrement property value.

Note:	You should connect a spin button to edit controls in order to obtain full functionality.  If you bind a spin button to another type of control, then you need to handle changes to its Value manually (by using the Properties.OnEditValueChanged event handler).

Note that the most obvious application of the spin button control is to bind it to a text editor.  This will allow end users to edit the value directly or by pressing the increment/decrement and fast navigation buttons.  However, this functionality is already better implemented by the TcxSpinEdit control.  Use the spin button control when you want to associate it with something different from a basic text editor.

The TcxCustomSpinButton class implements all the functionality required by spin buttons. The derived TcxSpinButton control simply publishes the inherited properties and events.

Do not create instances of the TcxCustomSpinButton class in applications.  Use the TcxSpinButton control to add a spin button to forms.


TcxCustomSpinButton Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomSpinEdit

     |


Properties for TcxCustomSpinButton
TcxCustomSpinButton Properties

TcxCustomSpinButton          Legend

In TcxCustomSpinButton

ActiveProperties

Associate

Properties

Derived from TcxCustomSpinEdit

ActiveProperties

Properties

Value

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxCustomSpinButton
TcxCustomSpinButton Methods

TcxCustomSpinButton          Legend

Derived from TcxCustomMaskEdit

CutToClipboard

PasteFromClipboard

Derived from TcxCustomTextEdit

Clear

ClearSelection

CopyToClipboard

Create

CutToClipboard

SelectAll

SetSelection

Undo

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


TcxCustomSpinButton.ActiveProperties

TcxCustomSpinButton          See Also

Obtains the properties that are currently applied to a spin button.

property ActiveProperties: TcxCustomSpinButtonProperties;

Description

Use the ActiveProperties property to obtain the properties of the current spin button that are currently in effect.  This property is especially useful when the spin button 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 spin button.  Otherwise, the inherent spin button’s properties are returned.

ReadOnly Property


TcxCustomSpinButton.Associate

TcxCustomSpinButton          Example

Specifies a TWinControl descendant associated with the current spin button.

property Associate: TWinControl;

Description

Use the Associate property to link a TWinControl descendant to the spin button.

If a spin button is associated with an edit control, then the edit control’s value is obtained from the spin button’s Value property (0 by default).  When the edit control has focus, then the associated spin button handles pressing the Up, Down, PageUp and PageDown keys.  Pressing the Up key or the right/up spin button increases the edit control value while pressing the Down key or the left/down spin button decreases it (increment/decrement is specified by the Properties.Increment property).

After a spin button has been associated with a control, it is positioned at the right edge of this control:

Spin buttons also provide fast navigation through the edit control’s values.  Fast navigation is performed when a user presses fast buttons or the PageUp/PageDown keys.  In order to enable fast buttons, set the Properties.SpinButtons.ShowFastButtons property to True.  During fast navigation, the edit control value is increased/decreased by the Properties.LargeIncrement property value.

Note:	You should connect a spin button to edit controls in order to obtain full functionality.  If you bind a spin button to another type of control, then you need to handle changes to its Value manually (by using the Properties.OnEditValueChanged event handler).


TcxCustomSpinButton.Properties

TcxCustomSpinButton

Contains settings specific to spin buttons.

property Properties: TcxCustomSpinButtonProperties;

Description

Use the Properties property to access attributes specific to spin buttons.

The Properties.Increment property specifies the value by which the spin button’s EditValue is increased/decreased.  The Properties.LargeIncrement property specifies the step while performing fast navigation.  The Properties.SpinButtons property manages the spin buttons’ position and visibility of the fast buttons.  The SpinButtons.ShowFastButtons property specifies the visibility of the fast navigation buttons.  The SpinButtons.Position property specifies the position of the spin edit buttons.

The following screenshot demonstrates a spin button bound to a cxComboBox control.  The Properties.SpinButtons.ShowFastButtons property value is True and the Properties.SpinButtons.Position property is set to sbpHorzRight:

The limits for the spin button’s EditValue are determined by the Properties.MaxValue and Properties.MinValue properties.


TcxCustomSpinButtonProperties
TcxCustomSpinButtonProperties Object

Hierarchy          Properties          Methods          Events

Represents settings specific to spin buttons.

Unit

cxSpinButton

TcxCustomSpinButtonProperties = class(TcxCustomSpinEditProperties)

Description

The TcxCustomSpinButtonProperties class contains settings specific to spin buttons.  Use the Properties property to access these attributes.

The Properties.Increment property specifies the value by which the spin button’s EditValue is increased/decreased.  The Properties.LargeIncrement property specifies the step while performing fast navigation.  The Properties.SpinButtons property manages the spin button’s position and visibility of the fast buttons.  The SpinButtons.ShowFastButtons property specifies the visibility of the fast navigation buttons.  The SpinButtons.Position property specifies the position of the spin edit buttons.  The spin button’s EditValue limits are determined by the Properties.MaxValue and Properties.MinValue properties.


TcxCustomSpinButtonProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |

TcxCustomSpinEditProperties

     |


Properties for TcxCustomSpinButtonProperties
TcxCustomSpinButtonProperties Properties

TcxCustomSpinButtonProperties          Legend

Derived from TcxCustomSpinEditProperties

AssignedValues

CanEdit

Circular

ExceptionOnInvalidInput

Increment

LargeIncrement

SpinButtons

UseCtrlIncrement

ValueType

Derived from TcxCustomMaskEditProperties

AlwaysShowBlanksAndLiterals

CaseInsensitive

EditMask

IgnoreMaskBlank

IsMasked

MaskKind

Derived from TcxCustomTextEditProperties

AssignedValues

CharCase

DisplayFormat

EchoMode

EditFormat

HideCursor

HideSelection

ImeMode

ImeName

IncrementalSearch

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 TcxCustomSpinButtonProperties
TcxCustomSpinButtonProperties Methods

TcxCustomSpinButtonProperties          Legend

Derived from TcxCustomMaskEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomTextEditProperties

IsDisplayValueValid

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue


Events for TcxCustomSpinButtonProperties
TcxCustomSpinButtonProperties Events

TcxCustomSpinButtonProperties          Legend

Derived from TcxCustomSpinEditProperties

OnGetValue

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxSpinButton
TcxSpinButton Object

Hierarchy          Properties          Example

Represents the spin button.

Unit

cxSpinButton

TcxSpinButton = class(TcxCustomSpinButton)

Description

The TcxSpinButton class represents the spin button control.  A spin button can be connected to a TWinControl to enable editing of the control’s value and for performing navigation using the keyboard or the spin buttons.  Use the Associate property to bind a spin button to a control.  The spin button is located at the right edge of the associated control (see the image below).

If a spin button is associated with an edit control, then the edit control’s value is obtained from the spin button’s Value property (0 by default).  When the edit control has focus, the associated spin button handles pressing the Up, Down, PageUp and PageDown keys.  Pressing the Up key or the right/up spin button increases the edit control’s value while pressing the Down key or the left/down spin button decreases it (increment/decrement is specified by the Properties.Increment property).

Spin buttons also provide fast navigation through the edit control’s values.  Fast navigation is performed when a user presses a fast button or a PageUp/PageDown key.  In order to enable fast buttons, set the Properties.SpinButtons.ShowFastButtons property to True.  During fast navigation, the edit control value is increased/decreased by the Properties.LargeIncrement property value.

The following screenshot shows a spin button bound to a cxComboBox control.  The Properties.SpinButtons.ShowFastButtons property value is True and the Properties.SpinButtons.Position property is set to sbpHorzRight:

Note that the most obvious application of the spin button control is to bind it to a text editor.  This will allow end users to edit the value directly or by pressing the increment/decrement and fast navigation buttons.  However, this functionality is already better implemented by the TcxSpinEdit control.  Use the spin button control for associating with other controls, not the basic text editor.

Also, you should connect a spin button to edit controls in order to obtain full functionality.  If you bind a spin button to another type of control, then you need to handle changes to its Value manually (by using the Properties.OnEditValueChanged event handler).


TcxSpinButton Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomSpinEdit

     |

TcxCustomSpinButton

     |


Properties for TcxSpinButton
TcxSpinButton Properties

TcxSpinButton          Legend

Derived from TcxCustomSpinButton

ActiveProperties

Associate

Properties

Derived from TcxCustomSpinEdit

ActiveProperties

Properties

Value

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


TcxSpinButtonProperties
TcxSpinButtonProperties Object

Hierarchy          Properties          Methods          Events

Represents the set of attributes specific to spin buttons.

Unit

cxSpinButton

TcxSpinButtonProperties = class(TcxCustomSpinButtonProperties)

Description

The TcxSpinButtonProperties class does not define any new functionality.  It simply publishes the properties declared in the TcxCustomSpinButtonProperties class.  Use the Properties property to access these attributes.  To control any changes made to a spin button’s DisplayFormat, EditFormat, MaxLength, MaxValue, MinValue, ReadOnly and ValueType properties and reverse their values back to the default ones, use the AssignedValues property.

The Properties.Increment property specifies the value by which the spin button’s EditValue is increased/decreased.  The Properties.LargeIncrement property specifies the step while performing fast navigation.  The Properties.SpinButtons property manages the spin buttons’ position and visibility of the fast buttons.  The SpinButtons.ShowFastButtons property specifies the visibility of the fast navigation buttons.  The SpinButtons.Position property specifies the position of the spin edit buttons.

The following screenshot shows a spin button bound to a cxComboBox control.  The Properties.SpinButtons.ShowFastButtons property value is True and the Properties.SpinButtons.Position property is set to sbpHorzRight:

The spin button’s EditValue limits are determined by the Properties.MaxValue and Properties.MinValue properties.


TcxSpinButtonProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |

TcxCustomSpinEditProperties

     |

TcxCustomSpinButtonProperties

     |


Properties for TcxSpinButtonProperties
TcxSpinButtonProperties Properties

TcxSpinButtonProperties          Legend

In TcxSpinButtonProperties

ValueType

Derived from TcxCustomSpinEditProperties

AssignedValues

CanEdit

Circular

ExceptionOnInvalidInput

Increment

LargeIncrement

SpinButtons

UseCtrlIncrement

ValueType

Derived from TcxCustomMaskEditProperties

AlwaysShowBlanksAndLiterals

CaseInsensitive

EditMask

IgnoreMaskBlank

IsMasked

MaskKind

Derived from TcxCustomTextEditProperties

AssignedValues

CharCase

DisplayFormat

EchoMode

EditFormat

HideCursor

HideSelection

ImeMode

ImeName

IncrementalSearch

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 TcxSpinButtonProperties
TcxSpinButtonProperties Methods

TcxSpinButtonProperties          Legend

Derived from TcxCustomMaskEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomTextEditProperties

IsDisplayValueValid

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue


Events for TcxSpinButtonProperties
TcxSpinButtonProperties Events

TcxSpinButtonProperties          Legend

Derived from TcxCustomSpinEditProperties

OnGetValue

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxSpinButtonProperties.ValueType

TcxSpinButtonProperties          See Also

Specifies the type of the spin edit value.

type

  TcxSpinEditValueType = (vtInt, vtFloat);

property ValueType: TcxSpinEditValueType;

Description

The ValueType property determines the type of value which a spin editor contains.  Two types are valid: integer and double.  Setting the ValueType property to one of these types automatically changes the type of the variant Value property.  This property specifies a value which the spin editor contains.

The ValueType affects the incrementing procedure when a user clicks the spin buttons or presses the Up and Down keys (a user must press Ctrl-Up and Ctrl-Down keys if the UseCtrlIncrement property is set to True).  The spin edit value is incremented or decremented by the amount defined by the Increment property.  If ValueType is set to vtInt, then the increment value is rounded to the nearest integer number first and then added to/subtracted from Value.

The default value of the ValueType property is vtInt.


Example: Using cxSpinButton in combination with cxComboBox

See Also

This example demonstrates using a cxSpinButton in combination with a cxComboBox editor.

The combo box is filled with values that differ from each other by 10.  Thus you can choose 10, 20, 30, etc. The associated spin button control is used to provide more precision for value editing.  It enables end users to increment of decrement the edited value by 1 by pressing the increment/decrement buttons. For instance, if you need to set the edited value to 22 you will need to choose the 20 item from the combo and then click the increment button of the spin button control twice.  The fast navigation buttons will be used to change the edited value by 5.

Follow the steps below:

•	Place a cxComboBox control onto the form.  Its properties will be displayed within the Object Inspector window.  Click the ellipsis button corresponding to the Properties.Items property.  Enter values as shown in the image below.  Click the OK button to save changes and exit the item collection editor.

•	Place a cxSpinButton control on the form.  Assign the combo box to its Associate property.  The spin button will automatically be positioned at the left of the combo box.  This also makes the spin button control the edit value of the combo box.

•	Set the Properties.SpinButtons.ShowFastButtons to True to make the fast navigation buttons visible.  The Properties.Increment and Properties.LargeIncrement properties must be set to 1 and 5 respectively.  With such settings, clicking the up and down buttons will change the value of the associated combo box by 1.  The fast navigation buttons will increment and decrement the value by 5.

•	Run the application.

The images below illustrate how this combination of combo box and spin button works. First, select 20 from the combo box dropdown:

Pressing the up button will change the value by 1:

Fast navigation buttons change the edited value by 5:


cxSpinEdit Unit Overview
cxSpinEdit Unit

Classes

TcxCustomSpinEdit

TcxCustomSpinEditProperties

TcxSpinEdit

TcxSpinEditButtons

TcxSpinEditProperties

TcxSpinEditPropertiesValues

Other Types

TcxSpinEditValueType


TcxCustomSpinEdit
TcxCustomSpinEdit Object

Hierarchy          Properties          Methods          Events          See Also

Represents a base class for spin editors.

Unit

cxSpinEdit

TcxCustomSpinEdit = class(TcxCustomMaskEdit);

Description

A spin editor is a control that enables editing numerical values by clicking so-called "spin buttons" (up and down arrows displayed within an editor).  They allow incrementing and decrementing a number by some amount (integer or floating-point).  It is also possible to enter a value directly by typing it.

TcxCustomSpinEdit is a base class for spin editors which are presented by TcxSpinEdit, TcxDBSpinEdit and TcxCustomTimeEdit controls.  To access a value displayed by a spin editor, use the Value property.  It specifies the currently edited value.  When a user either exits an editor or presses the Enter key, this value is stored in the EditValue property.

The Properties object defines different settings specific to spin editors.  The Increment member defines the number by which the value is changed every time a user clicks the spin buttons or presses Up and Down keys (if the UseCtrlIncrement property is set to True then Up and Down keys must be combined with the Ctrl key).  To limit numbers which a spin editor can represent, you can use the MaxValue and MinValue properties.  They define the range of acceptable values.

A spin editor can represent either integer or double values.  The ValueType property controls the type of the spin edit value and specifies the way in which the increment number is interpreted.  It is possible to prohibit users from editing the value directly.  Set the CanEdit property to False to restrict a user to change the value only by clicking the spin buttons or pressing Up/Down keys (or Ctrl-Up, Ctrl-Down keys).

The Properties object provides two events to handle any changes made within the spin editor, these are the OnChange event which is fired every time the displayed value is changed and the OnGetValue event which is raised before the displayed value is converted to the edit value.

Use the Style, StyleDisabled, StyleFocused and StyleHot properties to adjust the look & feel of an editor.  Working with styles is discussed in the TcxCustomEditStyle class topic.


TcxCustomSpinEdit Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |


Properties for TcxCustomSpinEdit
TcxCustomSpinEdit Properties

TcxCustomSpinEdit          Legend

In TcxCustomSpinEdit

ActiveProperties

Properties

Value

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxCustomSpinEdit
TcxCustomSpinEdit Methods

TcxCustomSpinEdit          Legend

In TcxCustomSpinEdit

GetIncrement

Derived from TcxCustomMaskEdit

CutToClipboard

PasteFromClipboard

Derived from TcxCustomTextEdit

Clear

ClearSelection

CopyToClipboard

Create

CutToClipboard

SelectAll

SetSelection

Undo

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCustomSpinEdit
TcxCustomSpinEdit Events

TcxCustomSpinEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCustomSpinEdit.ActiveProperties

TcxCustomSpinEdit          See Also

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

property ActiveProperties: TcxCustomSpinEditProperties;

Description

Use the ActiveProperties property to obtain the properties of the current spin editor that are currently in effect.  This property is especially useful when the spin 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 spin editor.  Otherwise, the inherent spin editor’s properties are returned.

ReadOnly Property


TcxCustomSpinEdit.Properties

TcxCustomSpinEdit          See Also

Defines settings specific to spin editors.

property Properties: TcxCustomSpinEditProperties;

Description

The Properties object defines different settings specific to spin editors.  The Increment member defines the number by which the value is changed every time a user clicks the spin buttons or presses Up and Down keys (if the UseCtrlIncrement property is set to True, then Up and Down keys must be combined with the Ctrl key).  To limit numbers which a spin editor can represent, you can use the MaxValue and MinValue properties.  They define the range of acceptable values.

A spin editor can represent either integer or double values.  The ValueType property controls the type of the spin edit value and specifies the way in which the increment number is interpreted.  It is possible to prohibit users from editing the value directly.  Set the CanEdit property to False to restrict a user to change the value only by clicking the spin buttons or pressing Up/Down keys (or Ctrl-Up, Ctrl-Down keys).

The TcxCustomSpinEditProperties class provides two events to handle any changes made within the spin editor, these are the OnChange event which is fired every time the displayed value is changed and the OnGetValue event which is raised before the displayed value is converted to the edit value.


TcxCustomSpinEdit.Value

TcxCustomSpinEdit          See Also

Contains a value displayed by a spin editor.

property Value: Variant;

Description

The Value property defines a value which is currently displayed by a spin editor.  When a user edits the value, it is not stored in the EditValue property.  It will be stored in EditValue after a user presses the Enter key or sets focus to another control.

A user can press the up and down keyboard keys to increment and decrement the edit value.  If the UseCtrlIncrement member of the Properties object is set to True, then up and down arrows keys must be combined with the Ctrl key to produce the same effect.


TcxCustomSpinEdit.GetIncrement

TcxCustomSpinEdit          See Also

Returns the increment value for a spin editor.

function GetIncrement: Double; virtual;

Description

The GetIncrement method returns the increment value by which the current spin edit value is increased or decreased.  The increment value is set via the Increment member of the Properties object.  Use the GetIncrement method in TcxCustomSpinEdit descendants to change the default behavior of incrementing operation.


TcxCustomSpinEditProperties
TcxCustomSpinEditProperties Object

Hierarchy          Properties          Methods          Events           See Also

Represents settings specific to spin editors.

Unit

cxSpinEdit

TcxCustomSpinEditProperties = class(TcxCustomMaskEditProperties);

Description

The TcxCustomSpinEditProperties class introduces new properties specific to spin editors.  Use the Properties member of a specific editor to set its various settings.  TcxSpinEditProperties publishes attributes provided by the TcxCustomSpinEditProperties class.

The Increment member defines the number by which the value is changed every time a user clicks the spin buttons or presses the Up and Down keys (if the UseCtrlIncrement property is set to True then Up and Down keys must be combined with the Ctrl key).  The ValueType property controls the type of the spin edit value and specifies the way in which the increment number is interpreted.  Use the CanEdit property to disable direct editing of the spin value.


TcxCustomSpinEditProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |


Properties for TcxCustomSpinEditProperties
TcxCustomSpinEditProperties Properties

TcxCustomSpinEditProperties          Legend

In TcxCustomSpinEditProperties

AssignedValues

CanEdit

Circular

ExceptionOnInvalidInput

Increment

LargeIncrement

SpinButtons

UseCtrlIncrement

ValueType

Derived from TcxCustomMaskEditProperties

AlwaysShowBlanksAndLiterals

CaseInsensitive

EditMask

IgnoreMaskBlank

IsMasked

MaskKind

Derived from TcxCustomTextEditProperties

AssignedValues

CharCase

DisplayFormat

EchoMode

EditFormat

HideCursor

HideSelection

ImeMode

ImeName

IncrementalSearch

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 TcxCustomSpinEditProperties
TcxCustomSpinEditProperties Methods

TcxCustomSpinEditProperties          Legend

Derived from TcxCustomMaskEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomTextEditProperties

IsDisplayValueValid

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue


Events for TcxCustomSpinEditProperties
TcxCustomSpinEditProperties Events

TcxCustomSpinEditProperties          Legend

In TcxCustomSpinEditProperties

OnGetValue

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomSpinEditProperties.AssignedValues

TcxCustomSpinEditProperties

Contains the property flags that indicate which properties specific to a spin editor have been changed.

property AssignedValues: TcxSpinEditPropertiesValues;

Description

Use the AssignedValues property to track the changes made to a spin editor’s DisplayFormat, EditFormat, MaxLength, MaxValue, MinValue, ReadOnly and ValueType properties and undo them.  Once the property being tracked is set to a value other than the default one, the changes are reflected in the AssignedValues property (its corresponding property flag is set to True).  To undo the changes made and reverse the property back to its default value, set the corresponding property flag to False or call the AssignedValues.RestoreDefaults method to reverse all these properties back to their default values and reset all the property flags.  Use the AssignedValues.BeginUpdate and AssignedValues.EndUpdate methods to control when the editor repaints and avoid any flickering when the property flags are modified.


TcxCustomSpinEditProperties.CanEdit

TcxCustomSpinEditProperties          See Also

Determines whether the direct editing is enabled.

property CanEdit: Boolean;

Description

If the CanEdit property is set to True then a user can edit the value by typing a number directly within the spin editor.  Otherwise, a user can only change the value by clicking the spin buttons or by pressing the Up and Down keys (if the UseCtrlIncrement property is set to True, the Up and Down keys must be combined with the Ctrl key).

The default value of the CanEdit property is True.


TcxCustomSpinEditProperties.Circular

TcxCustomSpinEditProperties          See Also

Determines whether the increment/decrement action has a "circular" effect.

property Circular: Boolean;

Description

When the Circular property is set to True and an end user exceeds the upper/lower bounds (which are specified by the MaxValue and MinValue properties) by incrementing/decrementing the spin editor’s value, then its value is set to the opposite bound value, the MinValue or MaxValue correspondingly.

The default value of the Circular property is False.


TcxCustomSpinEditProperties.ExceptionOnInvalidInput

TcxCustomSpinEditProperties          See Also

Indicates whether an exception should be raised when validation of the input value fails.

property ExceptionOnInvalidInput: Boolean;

Description

Set the ExceptionOnInvalidInput property to True to specify that an exception should be raised whenever the input value fails validation.  Otherwise, set this property to False.


TcxCustomSpinEditProperties.Increment

TcxCustomSpinEditProperties          See Also

Specifies the increment value for a spin editor.

property Increment: Double;

Description

When a user clicks the spin buttons (up and down arrows), the current spin value is increased or decreased by the amount specified by the Increment property.  The same effect can be achieved by pressing the up and down arrow keys (they must be combined with the Ctrl key if the UseCtrlincrement property is set to True).

The ValueType property controls whether the Increment value is converted to the integer type before incrementing or not.  If the ValueType is set to vtInt, then the value specified by the Increment property is rounded to the nearest integer number first.


TcxCustomSpinEditProperties.LargeIncrement

TcxCustomSpinEditProperties          See Also

Specifies the fast increment value for the spin editor.

property LargeIncrement: Double;

Description

A user can perform fast navigation through spin edit values.  There are two methods of implementing fast navigation:

•	pressing the fast buttons within the spin editor (the visibility of these buttons is determined by the Properties.SpinButtons.ShowFastButtons property);

•	pressing the PageDown/PageUp keys (combined with the Ctrl key if the Properties.UseCtrlIncrement property value is True).

During fast navigation, the EditValue of a spin editor is increased/decreased by the LargeIncrement property value.


TcxCustomSpinEditProperties.SpinButtons

TcxCustomSpinEditProperties          See Also

Contains the spin editor’s buttons settings.

property SpinButtons: TcxSpinEditButtons;

Description

Use the SpinButtons property to access the spin editor buttons settings.  Thee settings include:

•	the editor buttons position (see the Position property description for details);

•	the fast editor buttons visibility (see the FastButtons and Properties.LargeIncrement properties description for details).


TcxCustomSpinEditProperties.UseCtrlIncrement

TcxCustomSpinEditProperties

Determines whether to use Ctrl-Up and Ctrl-Down keys to increment/decrement the spin edit value.

property UseCtrlIncrement: Boolean;

Description

To increment or decrement the spin edit value a user can click the spin buttons or press the Up and Down keys.  If the UseCtrlIncrement property is set to True, then it is necessary to hold the Ctrl key while pressing Up and Down keys.

The default value of the UseCtrlIncrement property is False.


TcxCustomSpinEditProperties.ValueType

TcxCustomSpinEditProperties          See Also

Specifies the type of the spin edit value.

type

  TcxSpinEditValueType = (vtInt, vtFloat);

property ValueType: TcxSpinEditValueType;

Description

The ValueType property determines the type of value which a spin editor displays.  Two types are valid: integer and double.  Setting the ValueType property to one of these types automatically changes the type of the variant Value property.  This property specifies a value which the spin editor displays.

The ValueType affects the incrementing procedure when a user clicks the spin buttons or presses the Up and Down keys (a user must press Ctrl-Up and Ctrl-Down keys if the UseCtrlIncrement property is set to True).  The spin edit value is incremented or decremented by the amount defined by the Increment property.  If ValueType is set to vtInt, then the increment value is rounded to the nearest integer number first and then added to/subtracted from Value.

If you do not set the ValueType property then the default type is used.  For non data-aware spin editors (TcxSpinEdit controls), the default type is vtInt.  For data-aware spin editors (TcxDBSpinEdit controls), the default value type is determined based upon the associated field from the dataset.  A value type which is set explicitly via the ValueType property overrides the default type.

To restore ValueType and other properties to their default values, use the RestoreDefaults method.


TcxCustomSpinEditProperties.OnGetValue

TcxCustomSpinEditProperties          See Also

Occurs before the displayed value is converted to the edit value of the numeric type.

type

  TcxSpinEditGetValueEvent = procedure(Sender: TObject; const AText: TCaption; out AValue: Variant; var ErrorText: TCaption; var Error: Boolean) of object;

property OnGetValue: TcxSpinEditGetValueEvent;

Description

Handle the OnGetValue event to implement a custom mechanism which converts the editor’s displayed value to its edit value.  The Sender parameter specifies the spin editor which fired the event.  If a plain conversion of the AText parameter value to the edit value of the numeric type fails, the default value of the Error parameter is set to True and the ErrorText parameter is assigned an empty string as an error description.  The result of the conversion can be returned via the AValue parameter, which is equal to 0 by default.  In an OnGetValue event handler, you can apply the conversion mechanism and redefine the conversion results as needed, i.e. pass the resulting edit value to the AValue parameter, set the Error flag to indicate a successful conversion and assign a description of the error (if any) to the ErrorText parameter.

The OnGetValue event is fired in the following cases:

•	when moving focus to another control;

•	when pressing the Enter key, if the ValidateOnEnter property is set to True.


TcxSpinEditPropertiesValues
TcxSpinEditPropertiesValues Object

Hierarchy          Properties          Methods

Contains the property flags that indicate which properties specific to a spin editor have been changed.

Unit

cxSpinEdit

TcxSpinEditPropertiesValues = class(TcxTextEditPropertiesValues);

Description

The TcxSpinEditPropertiesValues class tracks the changes made to a spin editor’s DisplayFormat, EditFormat, MaxLength, MaxValue, MinValue, ReadOnly and ValueType properties.  Once one of these properties is set to a value other than the default one, the changes are reflected in the TcxSpinEditPropertiesValues class (its corresponding property flag is set to True).  To undo the changes made and reverse the property back to its default value, set the corresponding property flag to False or call the RestoreDefaults method to reverse all these properties back to their default values and reset all the property flags.  Use the BeginUpdate and EndUpdate methods to control when the spin editor repaints and avoid any flickering when the property flags are modified.


TcxSpinEditPropertiesValues Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditPropertiesValues

     |

TcxTextEditPropertiesValues

     |


Properties for TcxSpinEditPropertiesValues
TcxSpinEditPropertiesValues Properties

TcxSpinEditPropertiesValues          Legend

In TcxSpinEditPropertiesValues

ValueType

Derived from TcxTextEditPropertiesValues

DisplayFormat

EditFormat

MaxLength

MaxValue

MinValue

Derived from TcxCustomEditPropertiesValues

ReadOnly


Methods for TcxSpinEditPropertiesValues
TcxSpinEditPropertiesValues Methods

TcxSpinEditPropertiesValues          Legend

In TcxSpinEditPropertiesValues

RestoreDefaults

Derived from TcxCustomEditPropertiesValues

BeginUpdate

EndUpdate


TcxSpinEditPropertiesValues.ValueType

TcxSpinEditPropertiesValues          See Also

Specifies whether the type of the spin edit value have been changed.

property ValueType; Boolean;

Description

Once a spin editor’s ValueType property is set to a value other than the default one, the ValueType property flag is set to True.  Otherwise, it’s set to False.  To undo the changes made to the spin editor’s ValueType property and reverse it back to its default value, call the RestoreDefaults method which resets all the property flags or set the ValueType property flag to False.


TcxSpinEditPropertiesValues.RestoreDefaults

TcxSpinEditPropertiesValues          See Also

Reverses the values of the properties (changes to which are being tracked) back to their default values.

procedure RestoreDefaults; override;

Description

The RestoreDefaults method undoes any changes made to the properties and resets their values back to the default ones.  Calling this method sets the spin editor’s properties being tracked (DisplayFormat, EditFormat, MaxLength, MaxValue, MinValue, ReadOnly and ValueType) to the default values and resets the corresponding property flags to False.  Setting the property flag of each property being tracked to False has the same result as calling the RestoreDefaults method.


TcxSpinEdit
 TcxSpinEdit Object

Hierarchy          Properties          Methods          Events          See Also

Represents a spin editor.

Unit

cxSpinEdit

TcxSpinEdit = class(TcxCustomSpinEdit);

Description

A spin editor is a control that enables editing numerical values by clicking so-called "spin buttons" (up and down arrows displayed within an editor).  They allow incrementing and decrementing a number by some amount (integer or real).  It is also possible to enter a value directly by typing it.  The next image demonstrates a spin editor painted in UltraFlat style.

TcxSpinEdit publishes properties and events inherited from base classes.

TcxCustomSpinEdit is a base class for spin editors.  To access a value displayed by a spin editor use the Value property.  It specifies a currently edited value.  When a user either exits an editor or presses the Enter key, this value is stored in the EditValue property.

The Properties object defines different settings specific to spin editors.  The Increment member defines the number by which the value is changed every time a user clicks the spin buttons or presses the Up and Down keys (if the UseCtrlIncrement property is set to True then Up and Down keys must be combined with the Ctrl key).  To limit the numbers which a spin editor can represent, you can use the MaxValue and MinValue properties.  They define the range of acceptable values.  A spin editor can represent either integer or double values.  The ValueType property controls the type of the spin edit value and affects the way the increment number is interpreted.  To prohibit users from editing the value directly, set the CanEdit property to False to allow users only to change the value by clicking the spin buttons or pressing Up/Down keys (or Ctrl-Up, Ctrl-Down keys).

The Properties object provides two events to handle any changes made within the spin editor, these are the OnChange event which is fired every time the displayed value is changed and the OnGetValue event which is raised before the displayed value is converted to the edit value.

Use the Style, StyleDisabled, StyleFocused and StyleHot properties to adjust the look & feel of an editor.  Working with styles is discussed in the TcxCustomEditStyle class topic.


TcxSpinEdit Hierarchy
Hierarchy

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomSpinEdit

     |


Properties for TcxSpinEdit
TcxSpinEdit Properties

TcxSpinEdit          Legend

Derived from TcxCustomSpinEdit

ActiveProperties

Properties

Value

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxSpinEdit
TcxSpinEdit Methods

TcxSpinEdit          Legend

Derived from TcxCustomSpinEdit

GetIncrement

Derived from TcxCustomMaskEdit

CutToClipboard

PasteFromClipboard

Derived from TcxCustomTextEdit

Clear

ClearSelection

CopyToClipboard

Create

CutToClipboard

SelectAll

SetSelection

Undo

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxSpinEdit
TcxSpinEdit Events

TcxSpinEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxSpinEditButtons
TcxSpinEditButtons Object

Hierarchy          Properties

Specifies the location and visibility of spin buttons.

Unit

cxSpinEdit

TcxSpinEditButtons = class(TPersistent)

Description

The TcxSpinEditButtons class introduces properties that allow you to:

•	specify the location of spin buttons within an editor (Position);

•	control the general appearance of additional buttons ("fast buttons") that allow you to increase/decrease the editor’s value faster (ShowFastButtons);

•	control the general appearance of both standard and fast spin buttons (Visible).

Use a spin editor’s Properties.SpinButtons property to access these settings.


TcxSpinEditButtons Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxSpinEditButtons
TcxSpinEditButtons Properties

TcxSpinEditButtons          Legend

In TcxSpinEditButtons

 	Position

 	ShowFastButtons

 	Visible


TcxSpinEditButtons.Position

TcxSpinEditButtons          See Also

Specifies the position of spin editor buttons.

type

  TcxSpinEditButtonsPosition = (sbpHorzLeftRight, sbpHorzRight, sbpVert);

property Position: TcxSpinEditButtonsPosition;

Description

Spin editors are capable of displaying four buttons to affect the edited value.  Two are used to increment and decrement the edited value by the Increment property value.  The other two modify the edited value by the LargeIncrement property value but they are only visible if the ShowFastButtons property is set to True.  How these buttons are oriented and positioned within the editor is controlled by the Position property.

All the possible values for the Position property are listed in the following table.

Value	Meaning
sbpHorzLeftRight
sbpHorzRight
sbpVert

The default value of the Position property is sbpVert.


TcxSpinEditButtons.ShowFastButtons

TcxSpinEditButtons         See Also

Determines whether fast buttons are visible within an editor.

property ShowFastButtons: Boolean;

Description

Press fast buttons to increase/decrease the EditValue of an editor by the LargeIncrement property value.

All the possible values for the ShowFastButtons property are listed in the following table.

ShowFastButton is set to False	ShowFastButton is set to True

Note that the general appearance of both standard and fast spin buttons is controlled by the Visible property.

The default value of the ShowFastButtons property is False.


TcxSpinEditButtons.Visible

TcxSpinEditButtons

Specifies whether both standard and fast buttons are visible within an editor.

property Visible: Boolean;

Description

Set this property to False to hide both standard and fast buttons within an editor.  Otherwise, these buttons are displayed based upon the settings of the Position and ShowFastButtons properties.

The default value of the Visible property is True.


TcxSpinEditProperties
TcxSpinEditProperties Object

Hierarchy          Properties          Methods          Events          See also

Represents settings specific to spin editors.

Unit

cxSpinEdit

TcxSpinEditProperties = class(TcxCustomSpinEditProperties);

Description

The TcxSpinEditProperties class does not introduce any new behavior but publishes properties and events inherited from base classes.  To set settings for TcxCustomSpinEdit control, use its Properties member.  To control any changes made to a spin editor’s DisplayFormat, EditFormat, MaxLength, MaxValue, MinValue, ReadOnly and ValueType properties and reverse their values back to the default ones, use the AssignedValues property.

The main properties specific to spin editors are discussed below.  The Increment member defines the number by which the value is changed every time a user clicks the spin buttons or presses the Up and Down keys (if the UseCtrlIncrement property is set to True then Up and Down keys must be combined with the Ctrl key).  To limit possible values of a spin editor you can use the MaxValue and MinValue properties.  They define the range of acceptable values.  A spin editor can represent either integer or double values.  The ValueType property controls the type of the spin edit value and affects the way the increment number is interpreted.

The Properties object provides two events to handle any changes made within the spin editor, these are the OnChange event which is fired every time the displayed value is changed and the OnGetValue event which is raised before the displayed value is converted to the edit value.


TcxSpinEditProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |

TcxCustomSpinEditProperties

     |


Properties for TcxSpinEditProperties
TcxSpinEditProperties Properties

TcxSpinEditProperties          Legend

Derived from TcxCustomSpinEditProperties

AssignedValues

CanEdit

Circular

ExceptionOnInvalidInput

Increment

LargeIncrement

SpinButtons

UseCtrlIncrement

ValueType

Derived from TcxCustomMaskEditProperties

AlwaysShowBlanksAndLiterals

CaseInsensitive

EditMask

IgnoreMaskBlank

IsMasked

MaskKind

Derived from TcxCustomTextEditProperties

AssignedValues

CharCase

DisplayFormat

EchoMode

EditFormat

HideCursor

HideSelection

ImeMode

ImeName

IncrementalSearch

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 TcxSpinEditProperties
TcxSpinEditProperties Methods

TcxSpinEditProperties          Legend

Derived from TcxCustomMaskEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomTextEditProperties

IsDisplayValueValid

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue


Events for TcxSpinEditProperties
TcxSpinEditProperties Events

TcxSpinEditProperties          Legend

Derived from TcxCustomSpinEditProperties

OnGetValue

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxSpinEditValueType
TcxSpinEditValueType type

Represents the type of a value for spin editors.

Unit

cxSpinEdit

type

  TcxSpinEditValueType = (vtInt, vtFloat);

Description

TcxSpinEditValueType enumerates the types of value which a TcxCustomSpinEdit control can display.  A spin editor can represent either integer or double values.  To set the value type, use the ValueType member of the editor’s Properties object.

The following table lists all the possible types:

Value	Meaning
vtInt	A spin editor represents integer values.
vtFloat	A spin editor represents floating-point values.


cxSplitter Unit Overview
cxSplitter Unit

Classes

TcxCustomSplitter

TcxHotZoneStyle

TcxMediaPlayer8Style

TcxMediaPlayer9Style

TcxSimpleStyle

TcxSplitter

TcxXPTaskBarStyle


TcxCustomSplitter
TcxCustomSplitter Object

Hierarchy          Properties          Methods          Events

Serves as a base class for splitter controls.

Unit

cxSplitter

TcxCustomSplitter = class(TcxControl);

Description

Splitter controls enable you to create panes which can be resized easily by end users.  A common practice is to divide the form using several panel controls separated by splitters.  In this case, end users can resize panels by dragging the splitter and expand/collapse them by a single click on the splitter’s hot zone.  So, if you have groups of controls that are used less often, you can place them onto resizable panels.  In this case, end users can hide these control groups and make them visible again as and when needed.

The image below shows an example of a form using splitters to create resizable panes.  Please refer to the Using TcxSplitter topic for information on how to create such a form structure.

The TcxCustomSplitter class implements all the functionality required by splitters.  Among other features, it provides four types of hot zone (the central element used to collapse/expand controls at one side by a single click).  Use the HotZone property to choose the hot zone type that suits your needs.  This property can reference any TcxHotZoneStyle descendant.  Thus, you can create your own hot zone appearance by deriving from this class and assigning the inherited object to the HotZone property.  Please refer to the Creating Custom Hot Zones for Splitters topic for details.

Do not create instances of the TcxCustomSplitter class in applications.  Use this class to create custom splitter controls.  If you need to place a splitter control on a form, use the TcxSplitter control.  It is derived from the TcxCustomSplitter and publishes its properties and events.


TcxCustomSplitter Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |


Properties for TcxCustomSplitter
TcxCustomSplitter Properties

TcxCustomSplitter          Legend

In TcxCustomSplitter

AlignSplitter

AllowHotZoneDrag

AutoPosition

AutoSnap

Control

HotZone

HotZoneStyleClass

InvertDirection

MinSize

PositionAfterOpen

ResizeUpdate

State

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxCustomSplitter
TcxCustomSplitter Methods

TcxCustomSplitter          Legend

In TcxCustomSplitter

 CloseSplitter

 Create

 IsCursorInHotZone

 IsCursorInSplitter

 OpenSplitter

Derived from TcxControl

 Create

 Destroy

 InvalidateRect


Events for TcxCustomSplitter
TcxCustomSplitter Events

TcxCustomSplitter          Legend

In TcxCustomSplitter

 OnAfterClose

 OnAfterOpen

 OnBeforeClose

 OnBeforeOpen

 OnCanResize

 OnMoved

Derived from TcxControl

OnMouseEnter

OnMouseLeave


TcxCustomSplitter.AlignSplitter

TcxCustomSplitter          See Also

Specifies the alignment of the splitter within its container.

type

  TcxSplitterAlign = (salBottom, salLeft, salRight, salTop);

property AlignSplitter: TcxSplitterAlign;

Description

Use the AlignSplitter property to specify how the splitter is aligned within its container.  The most common practice is to align the splitter to the same edge to which its bound control is aligned.

Suppose you want to have a resizable panel at the left of the form.  In this case, the first thing to do is to place a panel onto the form and set its Align property to alLeft.  Next, add a splitter control to the form and set its AlignSplitter property to salLeft so that the splitter is aligned to the panel.  Set the splitter’s Control property to the panel.  Now you can run the application and resize the panel by dragging the splitter.

Note that in the simple example above, controls residing on the form will not be moved when the panel is resized.  The usual practice to overcome this is to place another panel on the form and set its Align property to alClient so it occupies the remainder of the form’s client area.  In this case, the new panel will be resized along with the first one.

Please refer to the Using TcxSplitter document for details on aligning splitters.

The table below lists all values available for the AlignSplitter property.  (Images in the table assume that there are four panels on the form aligned to its left, top, right and bottom edges.  Thus, changing the AlignSplitter property will position the splitter next to one of these panels.)

Property’s Value	Description	Example
salBottom	The splitter is aligned to the bottom of its container.  This alignment is used to resize controls that are aligned to the container’s bottom edge.
salLeft	The splitter is aligned to the left of its container.  This alignment is used to resize controls that are aligned to the container’s left edge.
salRight	The splitter is aligned to the right of its container.  This alignment is used to resize controls that are aligned to the container’s right edge.
salTop	The splitter is aligned to the top of its container.  This alignment is used to resize controls that are aligned to the container’s top edge.

The default value of the AlignSplitter property is salLeft.


TcxCustomSplitter.AllowHotZoneDrag

TcxCustomSplitter          See Also

Specifies whether end users can drag the splitter using its hot zone.

property AllowHotZoneDrag: Boolean;

Description

When a splitter is created it has no hot zone by default.  End users can only drag the splitter in order to resize the bound control.  However, you can enable the hot zone by setting the HotZone property to an appropriate value.  In this case, end users can click the hot zone to show/hide the bound control.

By default, the AllowHotZoneDrag property value is True, which means that end users can drag the splitter by its hot zone (i.e. use any part of the splitter’s area for dragging).  However, you can disable this by setting the property to False.  In this case, attempts to drag the splitter by the hot zone will have no effect.

Set the AllowHotZoneDrag property to False to provide standard button behavior for the hot zone.  This standard behavior means that pressing the button will only have an effect if the button is released within the splitter’s client area. If the AllowHotZoneDrag property is True, such an action will result in moving the splitter.

Note: You can also handle the OnCanResize event to prohibit splitter dragging for particular conditions.

The default value of the AllowHotZoneDrag property is True.


TcxCustomSplitter.AutoPosition

TcxCustomSplitter          See Also

Specifies whether expansion of the collapsed splitter moves it to its previous position or to the position specified by the PositionAfterOpen property.

property AutoPosition: Boolean;

Description

End users can hide the splitter’s bound control using two methods.  First by clicking on the hot zone, if it is enabled.  The second is to drag the splitter to the corresponding edge of its container.  You can also hide the control using code by changing the splitter’s State property value or by calling the CloseSplitter method.  Note that the splitter’s position before movement is stored regardless of the method used.

After the splitter’s bound control has been hidden, it can be shown again in a number of ways.  If  done by dragging the splitter away from the container’s edge, its new position will be the place where it is dropped.  Other methods of showing the bound control are to click the splitter’s hot zone (if enabled), to use the State property or the OpenSplitter method.  If one of these is used, the splitter will be moved either to its previous position or to the position specified by the PositionAfterOpen property, depending on the AutoPosition property value.

If the splitter’s bound control (a panel, for instance) does not have resizable contents, it is best to set the AutoPosition property to False.  In this case, opening the splitter will set its position to the fixed value specified by the PositionAfterOpen property.  If the contents are resizable (e.g. containing a grid  or memo) you will want to set the AutoPosition property to True.  In this case, end users can move the splitter as needed and its original position will be restored after closing and opening again.

The table below shows examples when the AutoPosition property is set to True and False.

AutoPosition is True	AutoPosition is False
1. The original position of the elements.	1. The original position of the elements.
2. Splitter is closed.	2. Splitter is closed.
3. Splitter is reopened.	3. Splitter is reopened (width of the left panel equals the PositionAfterOpen property value).
Note:	You can also control whether the splitter can move by handling the OnCanResize event.

The default value of the AutoPosition property is True.


TcxCustomSplitter.AutoSnap

TcxCustomSplitter          See Also

Specifies whether the splitter is automatically closed when its position reaches the MinSize property value.

property AutoSnap: Boolean;

Description

End users can drag the splitter to change the size of the bound control.  The AutoSnap property enables you to control how the bound control’s size changes when dragging the splitter to a position less than the MinSize property value.  If the AutoSnap property value is True, the control is automatically hidden in such cases (its width or height becomes zero).  Otherwise the control is always resized to the position where the splitter is dragged.

You can use the AutoSnap property to prevent users from making bound panels too small.  This property can also be set to True to help end users to close the splitter when the hot zone is disabled (see the HotZone property).

The default value of the AutoSnap property is False.


TcxCustomSplitter.Control

TcxCustomSplitter          See Also

Specifies the control whose size is affected by the splitter.

property Control: TControl;

Description

The Control property specifies the control (any TControl descendant) that is resized when the user drags the splitter or clicks the hot zone.  If this property is not set to any control, no operations performed on the splitter have any effect.

Please refer to the Using TcxSplitter topic for details on using the Control property.


TcxCustomSplitter.HotZone

TcxCustomSplitter          See Also

Specifies the type of the hot zone and provides access to properties affecting its appearance.

property HotZone: TcxHotZoneStyle;

Description

When the splitter control is created, the HotZone property value is nil.  This means that the control doesn’t display a hot zone and end users can only drag the splitter to resize the bound control.

To display a hot zone within the splitter, you need to set the HotZone property to a TcxHotZoneStyle descendant.  Each descendant can define a hot zone appearance and customized. Please refer to the TcxHotZoneStyle class description for details.

The splitter control is shipped with four TcxHotZoneStyle descendants available to the HotZone property.  They imitate the appearance of the most popularly used splitters and provide facilities for their customization.  Note that at design-time, the HotZone property value is initialized by a string.  The table below lists the strings corresponding to the predefined hot zone styles and their corresponding classes.

Property’s Value (Setting at design time)	Property’s Value (Setting at runtime)	Sample Appearance
Simple	An instance of the TcxSimpleStyle class.
XPTaskBar	An instance of the TcxXPTaskBarStyle class.
MediaPlayer8	An instance of the TcxMediaPlayer8Style class.
MediaPlayer9	An instance of the TcxMediaPlayer9Style class.


TcxCustomSplitter.HotZoneStyleClass

TcxCustomSplitter          See Also

Specifies the type of the hot zone.

type

  TcxHotZoneStyleClass = class of TcxHotZoneStyle;

property HotZoneStyleClass: TcxHotZoneStyleClass;

Description

Use the HotZoneStyleClass property to change the type of the hot zone at runtime by assigning one of the predefined classes to this property.  These classes are the TcxSimpleStyle, TcxXPTaskBarStyle, TcxMediaPlayer8Style and TcxMediaPlayer9Style.  Assign nil to the HotZoneStyleClass property to remove the hot zone.

At design-time, you need to use the HotZone property to change the hot zone type.  This property should also be used to access properties controlling the appearance and behavior of the hot zone.  Please refer to this property description for details on the types of hot zones available.


TcxCustomSplitter.InvertDirection

TcxCustomSplitter          See Also

Specifies the hot zone orientation.

property InvertDirection: Boolean;

Description

The splitter control is capable of displaying hot zones that can be clicked to expand or collapse the bound control.  You must set the HotZone property to an appropriate value to display the hot zone.

Most of the available hot zones display arrows that point to the direction in which the control will be resized if the hot zone is clicked.  However, you can force these arrows to point in the opposite direction.  This is useful, if you create a popout control.  For this, the splitter control resides at a form edge and when the hot zone is clicked, the form is enlarged to accommodate the splitter’s bound control.  The splitter remains at its original position in this case.  To implement such behavior, you need to handle the splitter’s OnAfterOpen and OnAfterClose events.  The code below shows an example.

// Delphi

procedure TForm1.FormCreate(Sender: TObject);

begin

  cxSplitter1.CloseSplitter;

  cxSplitter1.AutoPosition := False;

  cxSplitter1.PositionAfterOpen := 100;

  cxSplitter1.InvertDirection := True;

end;

procedure TForm1.cxSplitter1AfterOpen(Sender: TObject);

begin

  SetBounds(Left - 100, Top, Width + 100, Height);

end;

procedure TForm1.cxSplitter1AfterClose(Sender: TObject);

begin

  SetBounds(Left + 100, Top, Width - 100, Height);

end;

The form can look as shown below.  Note that the hot zone’s arrow points to where the popout control will appear.  This is achieved by setting the InvertDirection property to True at form creation.

The default value of the InvertDirection property is False.


TcxCustomSplitter.MinSize

TcxCustomSplitter          See Also

Specifies the bound control’s minimum size.

property MinSize: TcxNaturalNumber;

Description

There are two ways end users can change the size of the splitter’s bound control – dragging the splitter and clicking the hot zone, if enabled.  Dragging the splitter results in moving an edge of the bound control and, thus, changing its size.  If the AutoSnap property is set to True, end users cannot change the size of the bound control to a value less than MinSize by dragging the splitter.  Attempts to do so will result in collapsing the splitter (setting the bound control’s size to 0).  This can be used to prevent end users from making the bound control too small or to help when collapsing the splitter if the hot zone is disabled (see the HotZone property).

If the AutoSnap property is set to False, the splitter cannot be dragged to positions less than the MinSize property value.  Use this to prevent users from making the bound control too small if you don’t want to collapse the splitter.

You can allow resizing the bound control to any value by changing the MinSize property value to 0.

The default value of the MinSize property is 30.


TcxCustomSplitter.PositionAfterOpen

TcxCustomSplitter          See Also

Specifies the position to which the splitter is expanded if the AutoPosition property value is False.

type

  TcxPositionAfterOpen = 2..High(Integer);

property PositionAfterOpen: TcxPositionAfterOpen;

Description

If the hot zone is enabled (see the HotZone property), end users can click it to show/hide the bound control.  You can also collapse and expand the splitter programmatically.  The State property and the OpenSplitter and CloseSplitter methods can be used for this purpose.

When expanding the splitter, its behavior depends on the AutoPosition property value.  If it is True, the splitter is moved to the position it had before collapsing.  Otherwise, it is moved to the position specified by the PositionAfterOpen property.  See the AutoPosition property description for details and examples.

The default value of the PositionAfterOpen property is 30.


TcxCustomSplitter.ResizeUpdate

TcxCustomSplitter          See Also

Specifies the splitter’s behavior while it is being dragged.

property ResizeStyle: Boolean;

Description

By default, end users are allowed to move the splitter by dragging it with the mouse.  You can prohibit dragging the splitter by its hot zone using the AllowHotZoneDrag property.  Additionally, you can handle the OnCanResize event to restrict moving the splitter when particular conditions are met.

The splitter’s drag behavior is controlled by the ResizeUpdate property value.  If True, the bound control is resized as the splitter is dragged.  Otherwise, the bound control is only resized when the splitter is dropped and a pattern bar marks its position until this occurs.

The default value of the ResizeUpdate property is False.


TcxCustomSplitter.State

TcxCustomSplitter          See Also

Specifies whether the splitter is expanded or collapsed.

type

  TcxSplitterState = (ssOpened, ssClosed);

property State: TcxSplitterState;

Description

Use the State property to determine whether the splitter’s bound control has its minimum available size.  If so, the splitter is considered collapsed and the State property returns the ssClosed value.  Otherwise, the splitter is expanded and the ssOpened value is returned.

Setting the State property to the ssClosed value is equivalent to calling the CloseSplitter method.  This assigns the minimum possible size to the splitter’s bound control.  Setting the ssOpened value is equivalent to calling the OpenSplitter method.  There are several possible consequences of performing this.  If the splitter is not collapsed, nothing is done.  If it is collapsed, the result depends on the AutoPosition property value.  If it is True, the splitter is moved to its position before it had been collapsed.  Otherwise, it is moved to the position specified by the MinSize property.


TcxCustomSplitter.CloseSplitter

TcxCustomSplitter          See Also

Changes the size of the bound control to its minimum possible value.

procedure CloseSplitter;

Description

Use the CloseSplitter method to collapse the splitter programmatically.  Collapsing the splitter implies setting the size of the bound control to its minimum possible value.  Most commonly, the minimum possible width or height of a control is 0.  In this case, collapsing the splitter results in hiding the bound control.  However, some controls may not allow their height or width to be set to 0.  For instance, you may use the Constraints property of a control to specify the minimum possible control dimensions.  In this case, part of the bound control will remain visible even after the CloseSplitter method call.

Note that calling the CloseSplitter method is equivalent to clicking the hot zone when the splitter is expanded.  If the splitter is collapsed, clicking it results in increasing the size of the bound control.  To handle this action via code, use the OpenSplitter method.

Moving the splitter at runtime is useful for dynamically showing and hiding the bound control.  For instance, you may want to display a panel when a mouse cursor is over a predefined area and hide it when the mouse leaves it.


TcxCustomSplitter.Create

TcxCustomSplitter

Creates an instance of the TcxCustomSplitter class.

procedure Create(AOwner: TComponent); override;

Description

The Create method is called by TcxCustomSplitter descendants.  Thus, you have no need to use this constructor in applications.  If you need to create a splitter control at runtime, instantiate a TcxSplitter object or other TcxCustomSplitter descendant.


TcxCustomSplitter.IsCursorInHotZone

TcxCustomSplitter          See Also

Returns a value indicating whether the specified point is within the hot zone.

function IsCursorInHotZone(const X, Y: Integer): Boolean;

Description

Use the IsCursorInHotZone method to determine whether a specific point is within the hot zone’s bounding rectangle.  The point is specified by its horizontal and vertical coordinates via the X and Y parameters respectively.  Note that the point must be set using the splitter’s client coordinates (relative to its top-left corner).  If the point tested is within the hot zone, the method returns True.  If the point is outside the hot zone or the hot zone is not displayed, False is returned.  (See the HotZone property description for details on how to show and hide it.)

Usually, you will provide the mouse pointer’s coordinates for the method’s parameters.  Use this to display information within the status bar when the mouse enters the hot zone, for instance.  To do this, you need to track mouse movements and to change the status bar’s text appropriate to the IsCursorInHotZone method’s return value.

You can also see whether a point is within the splitter’s bounding rectangle by using the IsCursorInSplitter method.


TcxCustomSplitter.IsCursorInSplitter

TcxCustomSplitter          See Also

Returns a value indicating whether the specified point is within the splitter.

function IsCursorInSplitter(const X, Y: Integer): Boolean;

Description

The IsCursorInSplitter method is used to see if the point specified by the X and Y parameters is within the splitter’s client rectangle.  The parameters specify the horizontal and vertical coordinates of the test point respectively.  Note that they must specify the splitter’s client coordinates (the offset from its top-left corner).  If the test point is within the control’s client rectangle, the method returns True.  Otherwise, False is returned.

A common method of using IsCursorInSplitter is to provide mouse cursor coordinates as its parameters.  This can be used, for instance, to display information when the mouse is over the splitter.  In this case, you will need to handle mouse movements.

You can also see if a point is within the hot zone’s bounding rectangle bu using the IsCursorInHotZone method.


TcxCustomSplitter.OpenSplitter

TcxCustomSplitter          See Also

Opens the splitter.

procedure OpenSplitter;

Description

Use the OpenSplitter method to expand a closed splitter.  If the splitter is not closed, the method does nothing.  Otherwise, its behavior depends on the AutoPosition property value.  If this property is set to True, the splitter is moved to the position it had before closing.  Otherwise, it is moved to the position specified by the PositionAfterOpen property value.

The splitter can be programmatically closed using the CloseSplitter method.  To determine the current state of the splitter, use the State property.

The OpenSplitter and CloseSplitter methods provide the same functionality as when the user clicks on the hot zone.  Thus, these methods are useful if you don’t want to display the hot zone, but still want to provide the collapse/expand functionality to end users.  Please refer to the HotZone and HotZoneStyleClass property descriptions for details on how to show or hide the hot zone.


TcxCustomSplitter.OnAfterClose

TcxCustomSplitter          See Also

Fires after the splitter was closed  (i.e. the bound control was minimized).

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnAfterClose: TNotifyEvent;

Description

Write an OnAfterClose event handler to do something after closing the splitter.  End users can close the splitter by clicking the hot zone, if it is enabled, or by dragging it to the minimum possible position.  You can also close it programmatically using the CloseSplitter method or the State property.

The Sender parameter holds the splitter control that has been closed.

The OnAfterClose event is useful if you need to update the layout of controls when changing the splitter’s state.  You can also handle it for display purposes.  For instance, you may want to change the style of the splitter when it is closed.  If you need to discard the changes made in the OnAfterClose event handler when the splitter is opened again, handle the OnAfterOpen event.


TcxCustomSplitter.OnAfterOpen

TcxCustomSplitter          See Also

Fires immediately after the splitter is opened either by end users or via code.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnAfterOpen: TNotifyEvent;

Description

Write an OnAfterOpen event handler to do something after the splitter has been opened (i.e. when the bound control has been expanded).  End users can opened a closed splitter by clicking the hot zone, if it is enabled.  You can also perform the same via code.  Use the OpenSplitter method or the State property for this purpose.

The Sender parameter holds the splitter control that has been opened.

The OnAfterOpen event can be used to discard changes made in the OnAfterClose event handler.  This can be used, for instance, to recalculate the layout of controls on your form for display purposes.


TcxCustomSplitter.OnBeforeClose

TcxCustomSplitter          See Also

Enables you to stop the splitter from being closed.

type

  TBeforeCloseHotZoneEvent = procedure(Sender: TObject; var AllowClose: Boolean) of object;

property OnBeforeClose: TBeforeCloseHotZoneEvent;

Description

The OnBeforeClose event fires when the splitter is about to be closed.  It can be invoked as the result of clicking the hot zone or of closing the splitter programmatically (using the CloseSplitter method or the State property).  Handle this event to prohibit closing the splitter when particular conditions are met.  If you need to restrict splitter closing, set the AllowClose parameter to False.

The Sender parameter specifies the splitter control to be closed.


TcxCustomSplitter.OnBeforeOpen

TcxCustomSplitter          See Also

Enables you to stop the splitter from being opened.

type

  TBeforeOpenHotZoneEvent = procedure(Sender: TObject; var NewSize: Integer; var AllowOpen: Boolean) of object;

property OnBeforeOpen: TBeforeOpenHotZoneEvent;

Description

Closed splitters can be opened either by end users or via code.  End users need to click the hot zone to do this.  Open the splitter programmatically by using the OpenSplitter method or the State property.  All these actions raise the OnBeforeOpen event before the splitter is actually opened.  Handle this event to prevent the splitter expanding depending on your conditions.  If splitter opening should not occur, set the AllowOpen parameter to False.  This parameter’s value is True by default.

You can specify a new size for the control whose size is affected by the splitter.  To modify the control’s Height or Width property, set the NewSize parameter to a new value.  The splitter's type (vertical or horizontal, determined by the AlignSplitter property value) determines which property is changed.  The default value of the NewSize parameter indicates the control’s size value at the moment the OnBeforeOpen event is fired.

The Sender parameter specifies the splitter control to be opened.


TcxCustomSplitter.OnCanResize

TcxCustomSplitter          See Also

Enables you to prevent splitter movements.

type

  TCanResizeEvent = procedure(Sender: TObject; var NewSize: Integer; var Accept: Boolean) of object;

property OnCanResize: TCanResizeEvent;

Description

When users attempt to drag the splitter, the OnCanResize event is raised before the splitter’s position is changed.  The potential position of the splitter (i.e. new size of the bound control) can be determined by reading the NewSize parameter value.  If you want to stop the splitter moving to this position, set the Accept parameter to False.

The Sender parameter references the splitter control whose position is to be changed.

You can use the OnCanResize event to restrict the movement of the splitter to a predefined range.  Also, you may need to disable splitter dragging totally.  In this case, the event handler just needs to set the Accept parameter to False.

If you need to do something each time the splitter has changed its position, handle the OnMoved event.

Note: Altering the size of the splitter’s bound control changes its position.  In this case, the OnCanResize event is not raised.


TcxCustomSplitter.OnMoved

TcxCustomSplitter          See Also

Fires immediately after the splitter’s position has changed.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnMoved: TNotifyEvent;

Description

You may need to update controls residing on your form when the splitter’s position changes.  For instance, you may want to hide controls that are only partially visible and show them again when there is enough room.  In such cases, you need to handle the OnMoved event.  It is raised each time the splitter is moved by dragging it.

The Sender parameter holds the splitter control that moved.

To prohibit splitter movements or to restrict dragging depending on particular conditions, handle the OnCanResize event instead.

Note: Altering the size of the splitter’s bound control changes its position.  In this case, the OnMoved event is not raised.


TcxHotZoneStyle
TcxHotZoneStyle Object

Hierarchy          Properties          Methods          See Also

Serves as the base for objects representing hot zones within splitter controls.

Unit

cxSplitter

TcxHotZoneStyle = class(TPersistent)

Description

Splitter controls (TcxCustomSplitter descendants) are capable of displaying hot zones.  A hot zone is an area within the splitter that can be clicked by end users to close and open the splitter (i.e. set the size of the bound control to the minimum and back).

The hot zone used by the splitter control is specified by its HotZone property.  This property can accept any TcxHotZoneStyle descendant.  There are four descendants provided – the TcxSimpleStyle, TcxXPTaskBarStyle, TcxMediaPlayer8Style and TcxMediaPlayer9Style classes.  You can also create a custom descendant if you need to provide your own hot zone appearance.  Please refer to the Creating Custom Hot Zones for Splitters topic for details.


TcxHotZoneStyle Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxHotZoneStyle
TcxHotZoneStyle Properties

TcxHotZoneStyle          Legend

In TcxHotZoneStyle

HotZoneRect

Owner

SizePercent

Visible


Methods for TcxHotZoneStyle
TcxHotZoneStyle Methods

TcxHotZoneStyle          Legend

In TcxHotZoneStyle

 Assign

 CalculateHotZoneRect

 Changed

 Create

 DrawBackground

 DrawHotZone

 SplitterDirection


TcxHotZoneStyle.HotZoneRect

TcxHotZoneStyle

Represents the bounding rectangle of the hot zone.

property HotZoneRect: TRect;

Description

The HotZoneRect property represents the bounding rectangle of the hot zone and its value is updated every time the CalculateHotZoneRect function is called.


TcxHotZoneStyle.Owner

TcxHotZoneStyle          See Also

Gets the splitter control owning this hot zone.

property Owner: TcxCustomSplitter;

Description

The Owner property value is initialized in the constructor.  You can use this property for several purposes when designing your own hot zone.  You can provide different appearances for the hot zone depending on the splitter’s settings.  Also, you may wish to notify the owning splitter control of changes when updating is required.  For instance, you may invalidate the control each time a property affecting the hot zone’s appearance is changed.

ReadOnly Property


TcxHotZoneStyle.SizePercent

TcxHotZoneStyle          See Also

Specifies the fraction of the splitter’s area occupied by the hot zone.

type

  TcxNaturalNumber = 1..High(Integer);

property SizePercent: TcxNaturalNumber;

Description

Use the SizePercent property to change the size of the hot zone.  It specifies the fraction of the splitter’s size occupied by the hot zone as a percentage.  Thus, if you need a hot zone to occupy the whole splitter, set the SizePercent property to 100.

The table below provides examples of setting the SizePercent property to different values.

Property’s Value	Meaning	Effect
30	The hot zone occupies 30% of the splitter’s area.
50	The hot zone occupies the half of the splitter’s area.
100	The hot zone occupies the entire splitter.

Descendants of the TcxHotZoneStyle class can publish the SizePercent property.  However, you may want to create a custom hot zone with a fixed size, in which case you would leave the SizePercent property protected.

The default value of the SizePercent property is 30.


TcxHotZoneStyle.Visible

TcxHotZoneStyle

Specifies whether the hot zone is displayed.

property Visible: Boolean;

Description

Use the Visible property to show or hide the hot zone.  If this property value is True, the owner splitter control calls the hot zone object’s painting methods when needed.  Otherwise, the methods are not called.  Thus, when creating a custom hot zone object, you don’t need to track the state of the Visible property yourself.

Use the Visible property if you need to change the hot zone’s visibility at runtime.  If never want to display the hot zone, do not initialize the HotZone property value of the splitter control.

The default value of the Visible property is True.


TcxHotZoneStyle.Assign

TcxHotZoneStyle

Copies settings of one hot zone object to another.

procedure Assign(Source: TPersistent); override;

Description

Use the Assign method to create a copy of a hot zone object.  The Source parameter represents the source object (whose settings are copied).  The caller is the destination object.

Each descendant of the TcxHotZoneStyle object overrides the Assign method so that settings specific to the hot zone type are successfully copied.

The Assign method is useful if you need to create several splitters that have the same or similar hot zone settings.  In this case you can customize a single object and then assign its settings to the others.  Thus, you will not have to perform the same customization several times.


TcxHotZoneStyle.CalculateHotZoneRect

TcxHotZoneStyle          See Also

Calculates the bounding rectangle of the hot zone.

function CalculateHotZoneRect(const ABounds: TRect): TRect; virtual;

Description

The CalculateHotZoneRect method calculates the bounding rectangle (accessible via the HotZoneRect property) in which the hot zone will be painted.

The ABounds parameter specifies the bounding rectangle of the owning splitter control.  As implemented in the TcxHotZoneStyle class, this parameter is used to calculate the method’s return value depending on the SizePercent property value.  However, you may still want to override this method in descendant classes.  For instance, you may want your custom hot zone to occupy the whole splitter without regard to the SizePercent property value.  To implement this, you need to return the value of the ABounds parameter.

Another reason to override the CalculateHotZoneRect method is to perform additional calculations when the hot zone contains several elements.

Note that, when calculating the hot zone’s bounding rectangle, you must take into account the SplitterDirection property value.  This property returns the direction of the splitter.  Thus, you can determine whether to modify the width or the height of the hot zone’s rectangle.

Please refer to the Creating a Custom Hot Zone Style topic for an example of overriding this method.


TcxHotZoneStyle.Changed

TcxHotZoneStyle          See Also

Notifies the owning control to update the hot zone.

procedure Changed; virtual;

Description

The Changed method is called by the TcxHotZoneStyle class and its descendants whenever a property affecting the hot zone’s appearance changes.  The method notifies the owning control to repaint the hot zone, so that changes take effect immediately.

If you are creating a custom hot zone, call the Changed method when changing properties that affect the look of the hot zone.  Otherwise, the control will not be updated.


TcxHotZoneStyle.Create

TcxHotZoneStyle          See Also

Creates an instance of the TcxHotZoneStyle class.

procedure Create(AOwner: TcxCustomSplitter); virtual;

Description

The Create method is called by descendants of the TcxHotZoneStyle class to initialize their inherited settings.  The AOwner parameter specifies the control owning the hot zone.  The value of this parameter is assigned to the Owner property.  This is required to update the control correctly when the Changed method is called.  Also, you may need to access settings of the owner control when creating custom hot zones.

Descendants of the TcxHotZoneStyle class override the constructor to initialize their specific settings.


TcxHotZoneStyle.DrawBackground

TcxHotZoneStyle          See Also

Paints the background for the hot zone.

procedure DrawBackground(ACanvas: TcxCanvas; const ARect: TRect; const AHighlighted, AClicked: Boolean); virtual;

Description

The hot zone’s DrawBackground method is called by the DrawHotZone method whenever the hot zone needs to be repainted.  As implemented in the TcxHotZoneStyle class, this method does nothing.  Descendants override it to implement custom painting of hot zones.  Thus, if you are designing a custom hot zone, you may need to override this method to paint the hot zone’s background.

The ACanvas parameter specifies the TcxCanvas object which provides the painting surface.  Use the methods and properties of this object to implement painting of primitives.  The ARect parameter specifies the bounding rectangle of the hot zone which is determined by the CalculateHotZoneRect function.  The hot zone’s background must be painted within these boundaries.  The AHighlighted and AClicked parameters specify whether the hot zone is hot-tracked or pressed.  You may provide a painting routine which allows for these parameter values so that the hot zone has various appearances in different states.  Use the SplitterDirection property to determine the orientation of the hot zone when painting.

Please refer to the Creating a Custom Hot Zone Style topic for an example of overriding this method.


TcxHotZoneStyle.DrawHotZone

TcxHotZoneStyle          See Also

Paints the hot zone.

procedure DrawHotZone(ACanvas: TcxCanvas; const ARect: TRect; const AHighlighted, AClicked: Boolean); virtual;

Description

The hot zone’s DrawHotZone method is called by its owner control when the hot zone needs to be repainted.  As implemented in the TcxHotZoneStyle class, this method does nothing.  Descendants override it to implement painting of hot zones.  Thus, if you are designing a custom hot zone, you must to override this method to paint the hot zone.

The ACanvas parameter specifies the TcxCanvas object which provides the painting surface.  Use the methods and properties of this object to implement painting of primitives.  The ARect parameter specifies the bounding rectangle of the owner control (for instance, a splitter).  The hot zone must be painted within these boundaries.  The AHighlighted and AClicked parameters specify whether the hot zone is hot-tracked or pressed.  You may provide a painting routine which allows for these parameter values so that the hot zone has various appearances in different states.

Most probably, you will need to know the orientation of the hot zone when painting.  Use the SplitterDirection property to determine it.

Note:	The ARect parameter value is used to calculate the bounding rectangle of the hot zone.  The calculated value is returned by the CalculateHotZoneRect function.

Please refer to the Creating a Custom Hot Zone Style topic for an example of overriding this method.


TcxHotZoneStyle.SplitterDirection

TcxHotZoneStyle          See Also

Returns the orientation of the hot zone and the arrows within it.

type

  TcxSplitterDirection = (cxsdLeftToRight, cxsdRightToLeft, cxsdTopToBottom, cxsdBottomToTop);

function SplitterDirection: TcxSplitterDirection; virtual;

Description

The SplitterDirection function is useful when overriding the CalculateHotZoneRect and DrawHotZone methods.  If overriding the CalculateHotZoneRect method, you may need to determine whether the hot zone (together with the owning splitter control) is oriented vertically or horizontally.  When implementing hot zone painting by overriding the DrawHotZone method, you will need the same information plus the orientation of hot zone’s arrows (if you intend to paint them).

The table below provides the relationship between the SplitterDirection method’s return values and the orientation of the hot zone and arrows within it.

Return Value	Description
cxsdLeftToRight	The hot zone is horizontally oriented.  Arrows are directed to the right.
cxsdRightToLeft	The hot zone is horizontally oriented.  Arrows are directed to the left.
cxsdTopToBottom	The hot zone is vertically oriented.  Arrows are directed to the bottom.
cxsdBottomToTop	The hot zone is vertically oriented.  Arrows are directed to the top.


TcxMediaPlayer8Style
TcxMediaPlayer8Style Object

Hierarchy          Properties          Methods          See Also

Provides a hot zone with a look similar to the Microsoft Windows Media Player 8 application.

Unit

cxSplitter

TcxMediaPlayer8Style = class(TcxHotZoneStyle)

Description

The TcxMediaPlayer8Style class is a descendant of the TcxHotZoneStyle (the common ancestor for objects representing hot zones within splitters).  It introduces properties allowing you to customize the appearance of the hot zone it represents.

If you want to use this type of hot zone within a splitter, assign the MediaPlayer8 string to the HotZone property of a splitter control at design-time.  To set this type of hot zone at runtime, assign the TcxMediaPlayer8Style class to the HotZoneStyleClass property.

The image below displays the default hot zone provided by the TcxMediaPlayer8Style class.


TcxMediaPlayer8Style Hierarchy
Hierarchy

TPersistent

     |

TcxHotZoneStyle

     |


Properties for TcxMediaPlayer8Style
TcxMediaPlayer8Style Properties

TcxMediaPlayer8Style          Legend

In TcxMediaPlayer8Style

ArrowColor

ArrowHighlightColor

LightColor

ShadowColor

Derived from TcxHotZoneStyle

HotZoneRect

Owner

SizePercent

Visible


Methods for TcxMediaPlayer8Style
TcxMediaPlayer8Style Methods

TcxMediaPlayer8Style          Legend

Derived from TcxHotZoneStyle

 Assign

 CalculateHotZoneRect

 Changed

 Create

 DrawBackground

 DrawHotZone

 SplitterDirection


TcxMediaPlayer8Style.ArrowColor

TcxMediaPlayer8Style          See Also

Specifies the default color of the arrow displayed within a hot zone (i.e. when it is not hot-tracked).

property ArrowColor: TColor;

Description

Use the ArrowColor property to change the color of the arrow displayed within the hot zone.  You can also change the its color when the hot zone is hot-tracked by using the ArrowHighlightColor property.

The table below shows how changing the ArrowColor property affects the appearance of the hot zone.  The property is set to clBlack and clRed respectively.

The default value of the ArrowColor property is clWindowText.


TcxMediaPlayer8Style.ArrowHighlightColor

TcxMediaPlayer8Style          See Also

Specifies the hot-tracked color of the arrow displayed within the hot zone.

property ArrowHighlightColor: TColor;

Description

The ArrowHighlightColor property defines the color used to paint the hot zone arrow when the mouse is over the hot zone. The arrow’s color when the mouse pointer is outside the hot zone is set using the ArrowColor property.

If you do not wish to use highlighting, set the ArrowHighlightColor and ArrowColor properties to the same value.

The default value of the ArrowHighlightColor property is clWindow.


TcxMediaPlayer8Style.LightColor

TcxMediaPlayer8Style          See Also

Specifies the light color used to paint the hot zone.

property LightColor: TColor;

Description

The hot zone provided by the TcxMediaPlayer8Style object is painted using two colors to simulate a 3D effect.  These colors are specified by the LightColor and ShadowColor properties.  They are likely to be set to shades of the same color and the ShadowColor is normally a darker shade.

The image below shows the default appearance of the Media Player 8 hot zone.

Setting the LightColor and ShadowColor properties to light and dark shades of blue, results in the following appearance.

The default value of the LightColor property is clWindow.


TcxMediaPlayer8Style.ShadowColor

TcxMediaPlayer8Style          See Also

Specifies the color used to paint the shadow within the hot zone.

property ShadowColor: TColor;

Description

The Media Player 8 hot zone is painted using two colors.  These colors are specified by the LightColor and ShadowColor properties.  The ShadowColor property sets the color used to paint the border and shadows.

Please refer to the LightColor property description for details on using these two properties.

The default value of the ShadowColor property is clBtnShadow.


TcxMediaPlayer9Style
TcxMediaPlayer9Style Object

Hierarchy          Properties          Methods          See Also

Provides a hot zone that looks similar to the Microsoft Windows Media Player 9 application.

Unit

cxSplitter

TcxMediaPlayer9Style = class(TcxHotZoneStyle)

Description

The TcxMediaPlayer9Style class represents one of four predefined hot zone styles for splitter controls (TcxCustomSplitter descendants) and it is derived from the TcxHotZoneStyle class.  In addition to the inherited settings, it introduces its own properties to customize the hot zone’s look and feel.

There are two ways to assign this hot zone type to a splitter control.  At design-time, you need to set the HotZone property of a splitter control to the MediaPlayer9 string.  If you need to apply this hot zone style at runtime, assign the TcxMediaPlayer9Style class to the HotZoneStyleClass property.

The image below displays the default appearance of the Media Player 9 hot zone.


TcxMediaPlayer9Style Hierarchy
Hierarchy

TPersistent

     |

TcxHotZoneStyle

     |


Properties for TcxMediaPlayer9Style
TcxMediaPlayer9Style Properties

TcxMediaPlayer9Style          Legend

In TcxMediaPlayer9Style

ArrowColor

ArrowHighlightColor

BorderColor

LightColor

ShadowHighlightStartColor

ShadowStartColor

Derived from TcxHotZoneStyle

HotZoneRect

Owner

SizePercent

Visible


Methods for TcxMediaPlayer9Style
TcxMediaPlayer9Style Methods

TcxMediaPlayer9Style          Legend

Derived from TcxHotZoneStyle

 Assign

 CalculateHotZoneRect

 Changed

 Create

 DrawBackground

 DrawHotZone

 SplitterDirection


TcxMediaPlayer9Style.ArrowColor

TcxMediaPlayer9Style          See Also

Specifies the default color of the arrow displayed within a hot zone (i.e. when it is not hot-tracked).

property ArrowColor: TColor;

Description

The color of the arrow displayed within the Media Player 9 hot zone can be customized using the ArrowColor and ArrowHighlightColor properties.  They specify the normal arrow color and the color when hot-tracked by the mouse.  Provide identical values for these properties if you do not want the arrow to change its color when pointing to the hot zone with the mouse.

The table below displays the result of setting the ArrowColor property to clBlack and clRed respectively.

The default value of the ArrowColor property is clWindowText.


TcxMediaPlayer9Style.ArrowHighlightColor

TcxMediaPlayer9Style          See Also

Specifies the color of the arrow displayed within the hot zone when the mouse cursor points to it.

property ArrowHighlightColor: TColor;

Description

The Media Player 9 hot zone style, like other hot zone styles using arrows, allows you to customize the color of the arrow displayed.  This can be done using the ArrowColor and ArrowHighlightColor properties.  These properties set the normal arrow color and while hot-tracked, respectively.  Please refer to the ArrowColor property description for details and for an example of customizing the arrow color.

The default value of the ArrowHighlightColor property is clBlue.


TcxMediaPlayer9Style.BorderColor

TcxMediaPlayer9Style          See Also

Specifies the color of the border painted around the hot zone.

property BorderColor: TColor;

Description

When changing the hot zone’s color scheme via the LightColor, ShadowStartColor and ShadowHighlightStartColor properties, you may wish to change the BorderColor property as well.  Also, a BorderColor property change may be required if the style of other controls on the form are changed, thus providing a common look and feel to all the controls in your application.

The image below displays the default appearance of the Media Player 9 hot zone.

Changing the BorderColor property value to a dark red color results in the following appearance.

Changing the LightColor and ShadowStartColor properties values to shades of the red color makes the hot zone look more natural.

The default value of the BorderColor property is clBtnShadow.


TcxMediaPlayer9Style.LightColor

TcxMediaPlayer9Style          See Also

Specifies the color used to fill the light area of the hot zone.

property LightColor: TColor;

Description

The Media Player 9 hot zone consists of light and dark areas.  The light area is filled with a solid brush controlled by the LightColor property.  The dark part is filled with a gradient brush.  The gradient’s start color is provided by the ShadowStartColor (when the hot zone is in normal state).  If the mouse pointer is over the hot zone, the start color is set by the ShadowHighlightStartColor property instead.  The gradient’s end color is automatically set to a darker shade of the start color.

The image below displays an example of the Media Player 9 hot zone.  The zoomed image shows you where the colors specified by the above properties are applied.

Usually, you will set the LightColor, ShadowStartColor and ShadowHighlightStartColor properties to shades of the same color to imitate a shadow effect.  In this case, colors corresponding to the shadow area must be set to a slightly darker shade than the LightColor property value.  The images below display examples of such customization.  Note that the BorderColor property value is changed also to provide a common style for the entire hot zone.

Another common example of a customized hot zone is when the LightColor property value is set to white.  In this case, the ShadowStartColor and ShadowHighlightStartColor properties can be set to a light shade of any color to provide a nice looking hot zone.  The image below provides examples.

Note:	Set the ShadowStartColor and ShadowHighlightStartColor properties to the same value if you don’t want the hot zone to change its appearance when the mouse cursor hovers over it.

The default value of the LightColor property is clWindow.


TcxMediaPlayer9Style.ShadowHighlightStartColor

TcxMediaPlayer9Style          See Also

Specifies the starting color of the gradient used to fill the dark area of the hot zone while in hot-tracked state.

property ShadowHightlightStartColor: TColor;

Description

The Media Player 9 hot zone is comprised of light and dark areas.  The dark area is filled with a gradient brush whose start color can be specified for both normal and hot-tracked states of the hot zone.  Use the ShadowStartColor and ShadowHighlightStartColor properties to set this color when the mouse pointer is outside and within the hot zone respectively.  The gradient’s end color is set automatically to a darker shade of the start color.

The color of the hot zone’s light area is specified by the LightColor property.  Please refer to this property description for details on customizing the appearance of the Media Player 9 hot zone.

The default value of the ShadowHightlightStartColor property is $00AFF5C3.


TcxMediaPlayer9Style.ShadowStartColor

TcxMediaPlayer9Style          See Also

Specifies the starting color of the gradient used to fill the dark area of the hot zone while not hot-tracked.

property ShadowStartColor: TColor;

Description

The background style of the Media Player 9 hot zone can be customized using the LightColor, ShadowStartColor and ShadowHighlightStartColor properties.  These properties allow you to provide a 3D look to the hot zone by painting the shadow using a gradient.  Additionally, you can use the properties to set different shadow styles for the hot zone’s normal and hot-tracked states.  Please refer to the LightColor property description for details on using these properties.

The default value of the ShadowStartColor property is $00F5E6CD.


TcxSimpleStyle
TcxSimpleStyle Object

Hierarchy          Properties          Methods          See Also

Represents a simple hot zone for splitter controls.

Unit

cxSplitter

TcxSimpleStyle = class(TcxHotZoneStyle)

Description

A Splitter control is capable of displaying a hot zone.  Clicking a hot zone will reduce the size of the splitter’s bound control to a minimum and back.  Use the HotZone property of a splitter control to access its hot zone object.

The TcxSimpleStyle class provides a very simple hot zone.  Assign this class to the HotZoneStyleClass property of a splitter to apply this hot zone style at runtime.  If you need to apply it at design-time, assign the Simple string to the HotZone property.

Like other objects representing hot zones, the TcxSimpleStyle object is derived from the TcxHotZoneStyle class.  As well as inheriting common members, this object introduces several new properties thus allowing you to customize the look and feel of the hot zone.

The image below displays a sample of the simple hot zone.


TcxSimpleStyle Hierarchy
Hierarchy

TPersistent

     |

TcxHotZoneStyle

     |


Properties for TcxSimpleStyle
TcxSimpleStyle Properties

TcxSimpleStyle          Legend

In TcxSimpleStyle

ArrowColor

ArrowHighlightColor

DotsColor

DotsShadowColor

LightColor

ShadowColor

Derived from TcxHotZoneStyle

HotZoneRect

Owner

SizePercent

Visible


Methods for TcxSimpleStyle
TcxSimpleStyle Methods

TcxSimpleStyle          Legend

Derived from TcxHotZoneStyle

 Assign

 CalculateHotZoneRect

 Changed

 Create

 DrawBackground

 DrawHotZone

 SplitterDirection


TcxSimpleStyle.ArrowColor

TcxSimpleStyle          See Also

Specifies the default color of the arrow displayed within a hot zone (i.e. when it is not hot-tracked).

property ArrowColor: TColor;

Description

Simple hot zones display two arrows within their area.  The normal color of these arrows (when the hot zone is not hot-tracked) is specified by the ArrowColor property.  When the mouse pointer enters the hot zone’s area, the color of arrows is provided by the ArrowHighlightColor property instead.

The image below illustrates how changing the ArrowColor property value affects the appearance of the hot zone.  The property is set to clBlack and clRed respectively.

The default value of the ArrowColor property is clWindowText.


TcxSimpleStyle.ArrowHighlightColor

TcxSimpleStyle          See Also

Specifies the color of arrows displayed within the hot zone when it is hot-tracked.

property ArrowHighlightColor: TColor;

Description

Use the ArrowHighlightColor property to specify the color that will be used to paint a hot zone’s arrows when the mouse pointer is over it.  If the mouse cursor is outside the hot zone’s area, the arrows are painted according to the ArrowColor property instead.

If you do not want to use highlighting, assign the same values to the ArrowColor and ArrowHighlightColor properties.

The default value of the ArrowHighlightColor property is clWindow.


TcxSimpleStyle.DotsColor

TcxSimpleStyle          See Also

Specifies the color of the dots displayed within the hot zone.

property DotsColor: TColor;

Description

Simple hot zones display a set of points between arrows.  The color of these points is specified by the DotsColor and DotsShadowColor properties.  The use of these properties in combination allows you to simulate a 3D effect.  If the DotsColor property is set to a lighter shade than the DotsShadowColor property the dots appear to be lowered.  The image below shows the simple hot zone when the DotsColor and DotsShadowColor properties are set to clWhite and clBlack respectively.

Otherwise (if the DotsColor property specifies a darker shade), the dots will look raised.  The image below shows the same hot zone but with swapped DotsColor and DotsShadowColor property values.

Note: the background color of the simple hot zone is the same as the background color of the owning splitter control.  Use the control’s Color property to change it.  If you don’t need to display shadows for dots, set the DotsShadowColor property to the same color as the owning control’s background.  If you don’t need points to be displayed at all, set both the DotsColor and DotsShadowColor properties to this value.

Use the LightColor and ShadowColor properties for other changes to the hot zone’s appearance.

The default value of the DotsColor property is clHighlight.


TcxSimpleStyle.DotsShadowColor

TcxSimpleStyle          See Also

Specifies the color of the shadow displayed for dots.

property DotsShadowColor: TColor;

Description

The color of points displayed by the simple hot zone can be customized using the DotsColor and DotsShadowColor properties.  Please refer to the DotsColor property description for details.

For other changes to the simple hot zone’s appearance, see the LightColor and ShadowColor properties.

The default value of the DotsShadowColor property is clWindow.


TcxSimpleStyle.LightColor

TcxSimpleStyle          See Also

Specifies the color of left and top edges of the hot zone.

property LightColor: TColor;

Description

The background color of the hot zone using the simple style is specified by the owning control’s background color.  It can be set using the Color property of the control.  You can also specify the color of the border painted around the hot zone by using the ShadowColor property.  In addition, the TcxSimpleStyle object provides the LightColor property and this sets the color of the hot zone’s left and top borders.  If this property is set to a light color, the hot zone looks raised, as in the image below.

Also, you can set LightColor to the owning control’s Color property value to make the hot zone flat, as shown by the next image.

Note that you can also control the style of the dots displayed within the hot zone.  Use the DotsColor and DotsShadowColor properties for this purpose.

The default value of the LightColor property is clWindow.


TcxSimpleStyle.ShadowColor

TcxSimpleStyle          See Also

Specifies the color of the border painted around the hot zone.

property ShadowColor: TColor;

Description

Use the ShadowColor property to change the color of the border painted around the hot zone.  Changing this property is useful when you change the hot zone’s background color.  Thus, you can provide shades of the same color to all elements of the hot zone.  The image below shows hot zones with different background colors and corresponding border colors.

The next image illustrates changing the ShadowColor property value when the background color of the hot zone is unchanged.

Note: change the hot zone’s background color by changing the splitter’s Color property.

The default value of the ShadowColor property is clBtnShadow.


TcxSplitter
TcxSplitter Object

Hierarchy          Properties          Methods          Events

Represents an advanced splitter control.

Unit

cxSplitter

TcxSplitter = class(TcxCustomSplitter)

Description

Use the TcxSplitter control to add a splitter control to the form.  This control enables end users to resize controls at runtime using drag and drop operations or by using the hot zone.  The hot zone is an element of the splitter control that can be clicked to change the size of the bound control to the minimum possible and back.  There are four hot zone styles provided.  Additionally, you can create a custom hot zone style by deriving from the TcxHotZoneStyle class.

The TcxSplitter control’s functionality is implemented by its ancestor – the TcxCustomSplitter class.  The TcxSplitter class simply publishes properties and events.  Please refer to the ancestor description for details on the features provided.

If you are new to using the TcxSplitter control, please refer to the Using TcxSplitter topic.  It contains the basic information you need for using the control.


TcxSplitter Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxCustomSplitter

     |


Properties for TcxSplitter
TcxSplitter Properties

TcxSplitter          Legend

Derived from TcxCustomSplitter

AlignSplitter

AllowHotZoneDrag

AutoPosition

AutoSnap

Control

HotZone

HotZoneStyleClass

InvertDirection

MinSize

PositionAfterOpen

ResizeUpdate

State

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxSplitter
TcxSplitter Methods

TcxSplitter          Legend

Derived from TcxCustomSplitter

 CloseSplitter

 Create

 IsCursorInHotZone

 IsCursorInSplitter

 OpenSplitter

Derived from TcxControl

 Create

 Destroy

 InvalidateRect


Events for TcxSplitter
TcxSplitter Events

TcxSplitter          Legend

Derived from TcxCustomSplitter

 OnAfterClose

 OnAfterOpen

 OnBeforeClose

 OnBeforeOpen

 OnCanResize

 OnMoved


TcxXPTaskBarStyle
TcxXPTaskBarStyle Object

Hierarchy          Properties          Methods          See Also

Provides a hot zone that looks like the splitter in the Windows XP task bar.

Unit

cxSplitter

TcxXPTaskBarStyle = class(TcxHotZoneStyle)

Description

The TcxXPTaskBarStyle object provides a hot zone like Windows XP task bar splitters for TcxCustomSplitter descendant controls.  To use, assign the XPTaskBar string to the HotZone property of the splitter control at design-time.  If you need to apply this hot zone style at runtime, assign the TcxXPTaskBarStyle class to the HotZoneStyleClass property.

The TcxXPTaskBarStyle object is derived from the TcxHotZoneStyle class – the common ancestor of all objects representing hot zones.  In addition to publishing inherited members, it introduces properties allowing you to customize its appearance.

The image below displays an example of the XP task bar hot zone style.


TcxXPTaskBarStyle Hierarchy
Hierarchy

TPersistent

     |

TcxHotZoneStyle

     |


Properties for TcxXPTaskBarStyle
TcxXPTaskBarStyle Properties

TcxXPTaskBarStyle          Legend

In TcxXPTaskBarStyle

LightColor

ShadowColor

Derived from TcxHotZoneStyle

HotZoneRect

Owner

SizePercent

Visible


Methods for TcxXPTaskBarStyle
TcxXPTaskBarStyle Methods

TcxXPTaskBarStyle          Legend

Derived from TcxHotZoneStyle

 Assign

 CalculateHotZoneRect

 Changed

 Create

 DrawBackground

 DrawHotZone

 SplitterDirection


TcxXPTaskBarStyle.LightColor

TcxXPTaskBarStyle          See Also

Specifies the color of the dots displayed within the hot zone.

property LightColor: TColor;

Description

The XP task bar hot zone is represented by a set of dots each with its own shadow.  The color of dots is specified by the LightColor property and the shadow color using ShadowColor.  Additionally, you can change the background color of the hot zone by specifying the background color of the owning splitter control.  Use the Color property of the control to change it.

Usually, you will want to assign shades of a single color to the LightColor, ShadowColor and the control’s Color property.  For instance, if you need dots to look lowered, you need to assign a light shade to the LightColor and a dark shade to the ShadowColor properties.  Note that the best appearance is achieved when the background color is lighter than the ShadowColor and darker than the LightColor.  The image below displays an example.  Properties are set to shades of green, blue and red.

If LightColor is set to a shade darker than the ShadowColor (and the control’s Color property is between them), the hot zone will display raised dots.  See the example below.

Note that setting the LightColor and ShadowColor properties to shades of grey works for any background color.  Images below show examples.

The default value of the LightColor property is clWindow.


TcxXPTaskBarStyle.ShadowColor

TcxXPTaskBarStyle          See Also

Specifies the color of shadows painted for dots within the hot zone.

property ShadowColor: TColor;

Description

The XP task bar hot zone’s style can be customized using the LightColor and ShadowColor properties plus the Color property of the owning splitter control. Please refer to the LightColor property description for details on how to use them.

The default value of the ShadowColor property is clBtnShadow.


Using TcxSplitter
Using the TcxSplitter

See Also

This topic covers the basics of using the TcxSplitter control that lets you to create forms with containing easily resizable areas.  The example in this topic shows how to create the structure shown in the image below.

Follow the steps below to create such an application:

•	Create a new application.

•	Place a panel on the form and assign the pnlSkyBlue string to its Name property. Set its Caption property to an empty string and its Color to clSkyBlue.  Set the Align property to alLeft so that the panel is docked to the left edge of the form.

•	Place a TcxSplitter control onto the form.  Its AlignSplitter property value is salLeft by default, which means that it is aligned to the left edge of the container.  Thus, it becomes aligned to the panel.  Set the splitter’s Control property to the panel (pnlSkyBlue) and its HotZone property to MediaPlayer8.

•	Place another panel on the form and set its Align property to alClient.  The panel will fill the remainder of the form’s client area.

At this point, you may run the application to see how the splitter works.  Drag it with the mouse to resize the blue panel.  When it is resized, the second panel will also change its size, since it occupies the remaining space available.

•	Place another panel control on the right panel.  Set its name to pnlMoneyGreen.  The Caption and Color properties should be set to an empty string and clMoneyGreen respectively.  The Align property should be set to alBottom, so that the panel added is docked to the bottom edge of its container.

•	Place another TcxSplitter control on the right panel.  Set its AlignSplitter property to salBottom to align it to the green panel.  This panel must be assigned to the Control property of the splitter.  The HotZone property should be set to MediaPlayer9.

•	The last step is to place one more panel on the right panel.  Set its Caption property to an empty string and Color to clSilver.  Its Align property should be set to alClient so that the new panel occupies all the space available.

Run the application and test the behavior of splitters now.


Creating a Custom Hot Zone Style

See Also

A Splitter control (a TcxCustomSplitter descendant) provides a hot zone facility.  Hot zones are control elements that can be clicked to collapse the splitter (set its bound control to the minimum size) and subsequently re-open it.

The style of the hot zone used is specified by the HotZone property of TcxCustomSplitter descendants.  This property can hold a TcxHotZoneStyle descendant object representing the hot zone style.  There are four descendants shipped – TcxSimpleStyle, TcxMediaPlayer8Style, TcxMediaPlayer9Style and TcxXPTaskBarStyle.  However, you can also create your own descendant if you need a custom hot zone style.  This topic describes how to perform this.

If you need to create a custom hot zone style, derive an object from the TcxHotZoneStyle.  The table below lists the members that need to be overridden or must be used when implementing your object’s functionality.

Member	Description
Changed	This method tells the owning splitter control to invalidate its hot zone.  Call this method whenever changing settings which affect the hot zone’s appearance.
SplitterDirection	Gets a value indicating the orientation of the splitter.  Use this method to determine whether the splitter is oriented vertically or horizontally.
CalculateHotZoneRect	This method is called whenever the bounding rectangle of the hot zone needs to be obtained (for instance, when passing the bounding rectangle of the hot zone to the DrawHotZone method).  As implemented in the TcxHotZoneStyle class, this method calculates the bounding rectangle according to the SizePercent property value.  Override this method if you need to correct the hot zone’s bounding rectangle.
DrawHotZone	This method is called whenever the hot zone needs to be repainted.  Override it to paint the hot zone as desired.

The following code declares a descendant of the TcxHotZoneStyle class.  This descendant paints the hot zone as a button.  The button is flat in normal state.  If it is hot-tracked or pressed, it is painted raised and lowered respectively.  The descendant created provides a ButtonColor property to specify the color of the button.  When the property value changes, the Changed method is called to invalidate the hot zone.

The descendant also overrides the CalculateHotZoneRect method.  This is used to decrease the width of the hot zone if it is vertically oriented.  If the hot zone is horizontally oriented, the height is decreased.  The SplitterDirection method is used to determine the hot zone orientation.

TcxCustomButtonHotZoneStyle = class(TcxHotZoneStyle)

private

  FButtonColor: TColor;

  procedure SetButtonColor(Value: TColor);

protected

  function CalculateHotZoneRect(const ABounds: TRect): TRect; override;

  function DrawHotZone(ACanvas: TcxCanvas; const ARect: TRect; const AHighlighted, AClicked: Boolean): TRect; override;

  procedure DrawBackground(ACanvas: TcxCanvas; const ARect: TRect; const AHighlighted, AClicked: Boolean); override;

public

  constructor Create(AOwner: TcxCustomSplitter); override;

published

  property ButtonColor: TColor read FButtonColor write SetButtonColor;

  property SizePercent;

end;

// ...

procedure TcxCustomButtonHotZoneStyle.SetButtonColor(Value: TColor);

begin

  if Value = FButtonColor then Exit;

  FButtonColor := Value;

  Changed;

end;

constructor TcxCustomButtonHotZoneStyle.Create(AOwner: TcxCustomSplitter);

begin

  inherited Create(AOwner);

  FButtonColor := clBtnFace;

end;

function TcxCustomButtonHotZoneStyle.CalculateHotZoneRect(const ABounds: TRect): TRect;

begin

  // obtaining the default bounding rectangle of the hot zone

  Result := inherited CalculateHotZoneRect(ABounds);

  if (SplitterDirection = cxsdLeftToRight) or (SplitterDirection = cxsdRightToLeft) then

  begin

    // splitter is vertically oriented, its width is decreased

    Inc(Result.Left);

    Dec(Result.Right);

  end

  else

    // splitter is horizontally oriented, its height is decreased

    Inc(Result.Top);

    Dec(Result.Bottom);

  begin

  end;

end;

function TcxCustomButtonHotZoneStyle.DrawHotZone(ACanvas: TcxCanvas; const ARect: TRect; const AHighlighted, AClicked: Boolean): TRect;

var

  ATopLeftBorderColor, ABottomRightBorderColor: TColor;

  ABounds: TRect;

begin

  // specifying button's border colors

  if AHighlighted then

  begin

    ATopLeftBorderColor := clBtnHighlight;

    ABottomRightBorderColor := clBtnShadow;

  end;

  if AClicked then

  begin

    ATopLeftBorderColor := clBtnShadow;

    ABottomRightBorderColor := clBtnHighlight;

  end;

  if not (AHighlighted or AClicked) then

  begin

    ATopLeftBorderColor := clBtnShadow;

    ABottomRightBorderColor := clBtnShadow;

  end;

  ABounds := CalculateHotZoneRect(ARect);

  // painting the borders

  ACanvas.FrameRect(ABounds, ATopLeftBorderColor, 1, [bLeft, bTop]);

  ACanvas.FrameRect(ABounds, ABottomRightBorderColor, 1, [bBottom, bRight]);

  // filling the button's client area

  ACanvas.Brush.Color := FButtonColor;

  ACanvas.Brush.Style := bsSolid;

  ABounds.TopLeft := Point(ABounds.Left + 1, ABounds.Top + 1);

  ABounds.BottomRight := Point(ABounds.Right - 1, ABounds.Bottom - 1);

  ACanvas.FillRect(ABounds);

end;

procedure TcxCustomButtonHotZoneStyle.DrawBackground(ACanvas: TcxCanvas; const ARect: TRect; const AHighlighted, AClicked: Boolean);

begin

  ACanvas.Brush.Color := clYellow;

  ACanvas.FillRect(ARect);

end;

After the code is written, you can assign this hot zone style to a splitter control using the following code lines.

cxSplitter1.HotZoneStyleClass := TcxCustomButtonHotZoneStyle;

(cxSplitter1.HotZone as TcxCustomButtonHotZoneStyle).ButtonColor := clMoneyGreen;

The image below shows the appearance the hot zone will have in the normal, highlighted and clicked states, respectively.

Note that you can also make use of the new hot zone style at design time.  To implement this, perform the following steps:

•	Move the TcxCustomButtonHotZoneStyle class declaration to the cxSplitter.pas unit.

•	Add the following line to the initialization section of the unit:

GetRegisteredHotZoneStyles.Register(TcxCustomButtonHotZoneStyle, 'Button');

•	Add the following line to the finalization section of the unit:

GetRegisteredHotZoneStyles.UnRegister(TcxCustomButtonHotZoneStyle);

•	Recompile the package containing the unit.

After doing this, you can choose the Button hot zone style from the HotZone combo box at design time.

If the Button style is selected, you can expand the HotZone property to access the published properties of the TcxCustomButtonHotZoneStyle class.  These are the ButtonColor and SizePercent properties.  You can change them to change the color of the button and its size relative to the splitter control.


cxTimeEdit Unit Overview
cxTimeEdit Unit

Classes

TcxCustomTimeEdit

TcxCustomTimeEditProperties

TcxTimeEdit

TcxTimeEditProperties

Other Types

TcxTimeEditTimeFormat


TcxCustomTimeEdit
TcxCustomTimeEdit Object

Hierarchy          Properties          Methods          Events          See Also

Represents the base class for editors displaying time.

Unit

cxTimeEdit

TcxCustomTimeEdit = class(TcxCustomSpinEdit);

Description

The TcxCustomTimeEdit class provides the base functionality for time editors (such as TcxTimeEdit).  It is inherited from the TcxCustomSpinEdit class, which introduces the capability of editing values via spin buttons.  The TcxCustomTimeEdit class declares a Time property, of type TTime, containing time values.  A user can edit a time value either by typing it or by changing it with the help of spin buttons.  Spin buttons allow the incrementing and decrementing of a selected time value portion: hours, minutes or seconds.

To adjust settings specific to time editors, use the Properties object.  The Properties property allows you to define the time format, value alignment, read-only status and many others.  Use the Style, StyleDisabled, StyleFocused and StyleHot properties to adjust the look & feel of an editor.

Do not create instances of TcxCustomTimeEdit. Use its descendants such as TcxTimeEdit or TcxDBTimeEdit instead.


TcxCustomTimeEdit Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomSpinEdit

     |


Properties for TcxCustomTimeEdit
TcxCustomTimeEdit Properties

TcxCustomTimeEdit          Legend

In TcxCustomTimeEdit

ActiveProperties

Properties

Time

Derived from TcxCustomSpinEdit

ActiveProperties

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxCustomTimeEdit
TcxCustomTimeEdit Methods

TcxCustomTimeEdit          Legend

Derived from TcxCustomSpinEdit

GetIncrement

Derived from TcxCustomMaskEdit

CutToClipboard

PasteFromClipboard

Derived from TcxCustomTextEdit

Clear

ClearSelection

CopyToClipboard

Create

CutToClipboard

SelectAll

SetSelection

Undo

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCustomTimeEdit
TcxCustomTimeEdit Events

TcxCustomTimeEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCustomTimeEdit.ActiveProperties

TcxCustomTimeEdit          See Also

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

property ActiveProperties: TcxCustomTimeEditProperties;

Description

Use the ActiveProperties property to obtain the properties of the current time editor that are currently in effect.  This property is especially useful when the time 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 time editor.  Otherwise, the inherent time editor’s properties are returned.

ReadOnly Property


TcxCustomTimeEdit.Properties

TcxCustomTimeEdit          See Also

Contains settings specific to time editors.

property Properties: TcxCustomTimeEditProperties;

Description

Use the Properties member to adjust settings specific to time editors.  It allows you to control the time format, value alignment, read-only status and many others.


TcxCustomTimeEdit.Time

TcxCustomTimeEdit          See Also

Specifies the currently edited time value.

type

  TTime = type TDateTime;

property Time: TTime;

Description

Use the Time property to get and set a time value for an editor.  The Time property specifies the value currently edited by a user.  The TimeFormat member of the Properties object defines what portions of the time value are presented by the editor.

The Time and EditValue properties refer to the same date/time value.  The difference is that EditValue maintains both the date and time parts of a date/time value, while the Time property maintains only the time part.  When you set a value via the Time property, only the time portion is assigned (the date part of the stored date/time value is preserved); when you read the Time property, only the time part is retrieved.  If EditValue is assigned or read, the date part is not discarded.


TcxCustomTimeEditProperties
TcxCustomTimeEditProperties Object

Hierarchy          Properties          Methods          Events          See Also

Represents settings specific to time editors.

Unit

cxTimeEdit

TcxCustomTimeEditProperties = class(TcxCustomSpinEditProperties);

Description

The TcxCustomTimeEditProperties class extends the TcxCustomSpinEditProperties functionality by providing the TimeFormat, ShowDate, Use24HourFormat and UseTimeFormatWhenUnfocused properties.  The TimeFormat property defines which portions of a time value (hours, minutes and seconds) are presented by the editor.  The ShowDate property specifies whether to display the date along with time and the UseTimeFormatWhenUnfocused property specifies the display format of the value when the editor does not have focus.  The Use24HourFormat property provides a choice between 24- and 12-hour formats.  Use the AutoCorrectHours property to specify how the time editor handles incorrect values for the hour part of its time value.

To set settings for time editors, use the Properties member.  For instance, to adjust settings for TcxCustomTimeEdit controls, use the TcxCustomTimeEdit.Properties member.

The TcxTimeEditProperties class derives from TcxCustomTimeEditProperties and publishes the necessary properties for TcxCustomTimeEdit descendants.


TcxCustomTimeEditProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |

TcxCustomSpinEditProperties

     |


Properties for TcxCustomTimeEditProperties
TcxCustomTimeEditProperties Properties

TcxCustomTimeEditProperties          Legend

In TcxCustomTimeEditProperties

AutoCorrectHours

ShowDate

TimeFormat

Use24HourFormat

UseTimeFormatWhenUnfocused

Derived from TcxCustomSpinEditProperties

AssignedValues

CanEdit

Circular

ExceptionOnInvalidInput

Increment

LargeIncrement

SpinButtons

UseCtrlIncrement

ValueType

Derived from TcxCustomMaskEditProperties

AlwaysShowBlanksAndLiterals

CaseInsensitive

EditMask

IgnoreMaskBlank

IsMasked

MaskKind

Derived from TcxCustomTextEditProperties

AssignedValues

CharCase

DisplayFormat

EchoMode

EditFormat

HideCursor

HideSelection

ImeMode

ImeName

IncrementalSearch

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 TcxCustomTimeEditProperties
TcxCustomTimeEditProperties Methods

TcxCustomTimeEditProperties          Legend

Derived from TcxCustomMaskEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomTextEditProperties

IsDisplayValueValid

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue


Events for TcxCustomTimeEditProperties
TcxCustomTimeEditProperties Events

TcxCustomTimeEditProperties          Legend

Derived from TcxCustomSpinEditProperties

OnGetValue

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomTimeEditProperties.AutoCorrectHours

TcxCustomTimeEditProperties          See Also

Indicates whether incorrect entries for the hour part of the edit value's time value are corrected automatically.

property AutoCorrectHours: Boolean;

Description

The time editor prevents users from entering incorrect values for the hour part of the time value.  A value outside of the hour portion’s value range (0 to 23 or 12 for a time editor which uses 24- or 12-hour format, respectively) is treated as an incorrect value.  Use the AutoCorrectHours property to explicitly specify exactly how the time editor handles an incorrect value which is entered into the time portion of its edit value.

Set the AutoCorrectHours property to True to specify that incorrect values have to be replaced with the maximum value possible for the current hour portion’s value range.  Otherwise, the keystroke (which would cause an incorrect value to be entered) is ignored.

The default value of the AutoCorrectHours property is True.


TcxCustomTimeEditProperties.ShowDate

TcxCustomTimeEditProperties

Defines whether to display the date portion as well as the time portion of a value.

property ShowDate: Boolean;

Description

If the ShowDate property is set to True, both the date and time portions of a value are displayed when the time editor does not have focus.  When it is focused, only the time portion is displayed and can be edited.  You can use the EditValue property to set the date/time value for your editor.  If ShowDate is False, only time is displayed.

The default value of the ShowDate property is True.


TcxCustomTimeEditProperties.TimeFormat

TcxCustomTimeEditProperties          See Also

Identifies the format of the value displayed by a time editor.

type

  TcxTimeEditTimeFormat = (tfHourMinSec, tfHourMin, tfHour);

property TimeFormat: TcxTimeEditTimeFormat;

Description

Use the TimeFormat property to specify the format of the time value for time editors.  This property determines which portions of the time value are presented by an editor.  The value itself is stored in the editor’s Time property.

The default value of the TimeFormat property is tfHourMinSec.


TcxCustomTimeEditProperties.Use24HourFormat

TcxCustomTimeEditProperties          See Also

Indicates whether the time editor uses 24- or 12-hour format in edit mode.

property Use24HourFormat: Boolean;

Description

The Use24HourFormat allows you to choose between 24- and 12-hour formats when editing time values.

When Use24HourFormat is True, the time value is represented using the hh:mm:ss format where hh denotes the hours portion varying from 00 to 23, mm – minutes, ss – seconds.

If Use24HourFormat is False, the time format is hh:mm:ss ts.  The hh portion defines hours varying from 1 to 12.  The ts portion identifies a time suffix (the AM or PM strings in the English locale).

You can specify what portions of a time value to display via the TimeFormat property.

The default value of the Use24HourFormat property is True.


TcxCustomTimeEditProperties.UseTimeFormatWhenUnfocused

TcxCustomTimeEditProperties          See Also

Specifies the time format which the time editor uses in display mode.

property UseTimeFormatWhenUnfocused: Boolean;

Description

When the editor control does not have focus and the UseTimeFormatWhenUnfocused property is set to True, the editor uses the time format specified by the TimeFormat property to display the editor value.  Otherwise, time representation is controlled by the regional options defined in the system.

The default value of the UseTimeFormatWhenUnfocused property is True.


TcxTimeEdit
 TcxTimeEdit Object

Hierarchy          Properties          Methods          Events          See also

Represents an editor displaying time values.

Unit

cxTimeEdit

TcxTimeEdit = class(TcxCustomTimeEdit);

Description

The TcxTimeEdit class represents an editor which allows editing time values by typing directly or via spin buttons (up and down arrows).  Spin buttons increment or decrement the time value portion (hours, minutes or seconds) a user indicates with the cursor.  The following image demonstrates the time edit painted in the XP style:

To set/get a time value, use the Time property of type TTime.

The Properties object defines settings specific to time editors and this allows you to define the time format, value alignment, read-only status and many others.  Use the Style, StyleDisabled, StyleFocused and StyleHot properties to adjust the look & feel of an editor.  Working with styles is discussed in the TcxCustomEditStyle class topic.


TcxTimeEdit Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomSpinEdit

     |

TcxCustomTimeEdit

     |


Properties for TcxTimeEdit
TcxTimeEdit Properties

TcxTimeEdit          Legend

Derived from TcxCustomTimeEdit

ActiveProperties

Properties

Time

Derived from TcxCustomSpinEdit

ActiveProperties

Properties

Value

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxTimeEdit
TcxTimeEdit Methods

TcxTimeEdit          Legend

Derived from TcxCustomSpinEdit

GetIncrement

Derived from TcxCustomMaskEdit

CutToClipboard

PasteFromClipboard

Derived from TcxCustomTextEdit

Clear

ClearSelection

CopyToClipboard

Create

CutToClipboard

SelectAll

SetSelection

Undo

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxTimeEdit
TcxTimeEdit Events

TcxTimeEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxTimeEditProperties
TcxTimeEditProperties Object

Hierarchy          Properties          Methods          Events          See Also

Represents settings specific to time editors.

Unit

cxTimeEdit

TcxTimeEditProperties = class(TcxCustomTimeEditProperties);

Description

TcxTimeEditProperties contains settings specific to time editors.  It does not introduce any new functionality but just publishes properties inherited from base classes.  The TcxCustomTimeEdit control represents the base class for time editors.  The Properties member of the TcxCustomTimeEdit control allows adjusting of various settings.  To control any changes made to the editor’s DisplayFormat, EditFormat, MaxLength, MaxValue, MinValue, ReadOnly and ValueType properties and reverse their values back to the default ones, use the AssignedValues property.


TcxTimeEditProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |

TcxCustomSpinEditProperties

     |

TcxCustomTimeEditProperties

     |


Properties for TcxTimeEditProperties
TcxTimeEditProperties Properties

TcxTimeEditProperties          Legend

Derived from TcxCustomTimeEditProperties

AutoCorrectHours

ShowDate

TimeFormat

Use24HourFormat

UseTimeFormatWhenUnfocused

Derived from TcxCustomSpinEditProperties

AssignedValues

CanEdit

Circular

ExceptionOnInvalidInput

Increment

LargeIncrement

SpinButtons

UseCtrlIncrement

ValueType

Derived from TcxCustomMaskEditProperties

AlwaysShowBlanksAndLiterals

CaseInsensitive

EditMask

IgnoreMaskBlank

IsMasked

MaskKind

Derived from TcxCustomTextEditProperties

AssignedValues

CharCase

DisplayFormat

EchoMode

EditFormat

HideCursor

HideSelection

ImeMode

ImeName

IncrementalSearch

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 TcxTimeEditProperties
TcxTimeEditProperties Methods

TcxTimeEditProperties          Legend

Derived from TcxCustomMaskEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomTextEditProperties

IsDisplayValueValid

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue


Events for TcxTimeEditProperties
TcxTimeEditProperties Events

TcxTimeEditProperties          Legend

Derived from TcxCustomSpinEditProperties

OnGetValue

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxTimeEditTimeFormat
TcxTimeEditTimeFormat type

Describes the formats of time editor values.

Unit

cxTimeEdit

type

  TcxTimeEditTimeFormat = (tfHourMinSec, tfHourMin, tfHour);

Description

The TcxTimeEditFormat type enumerates possible format types for displaying time values.  The format for time values is set via the TimeFormat member of the TcxCustomTimeEdit.Properties object.

The following table lists time formats.

Value	Meaning
tfHourMinSec	Hours, minutes and seconds are displayed within the time editor.
tfHourMin	Hours and minutes are displayed within the time editor.
tfHour	Hours are displayed within the time editor.


cxTreeView Unit Overview
cxTreeView Unit

Classes

TcxCustomTreeView

TcxTreeView


TcxCustomTreeView
TcxCustomTreeView Object

Hierarchy          Properties          Methods          Events

Serves as the base for tree view controls.

Unit

cxTreeView

TcxCustomTreeView = class(TcxContainer);

Description

The TcxCustomTreeView class implements the basic functionality of tree view controls.  These controls display a set of items arranged as a tree.  This implies that each item in the control can have children.  Parent items can be expanded and collapsed to show and hide children.

Please refer to the Items property for details on how to create a tree-like structure.  The item structure can be loaded from a text file or a stream.  Refer to the LoadFromFile and LoadFromStream methods for details.  You can also save the item structure by using the SaveToFile and SaveToStream methods.

Items of TcxCustomTreeView descendant controls are represented by TTreeNode objects.  Visually, items are comprised of text labels and images.  If this visual representation does not suit your application’s needs, you can paint items manually by handling the OnCustomDrawItem and OnAdvancedCustomDrawItem events.  Additionally you can create your own TTreeNode class descendant to represent nodes within the control.  You must handle the OnCreateNodeClass event to perform the replacement.

In addition to painting individual items, you can paint the entire tree view control manually.  This can be performed by handling the OnCustomDraw and OnAdvancedCustomDraw events.

Two more significant features implemented by the TcxCustomTreeView class are multi selection of items and item sorting.  Please refer to the MultiSelect and SortType property descriptions for details.

Note that the TcxCustomTreeView control uses the underlying TCustomTreeView object to perform most of its tasks.  Many settings are very similar to those of the standard tree view.  The primary difference is that the TcxCustomTreeView, like all of the controls within the ExpressEditors library, fully supports our style technology.  Please refer to the Style, StyleDisabled, StyleFocused and StyleHot properties for details.

Do not create instances of the TcxCustomTreeView class.  Use the derived TcxTreeView control if you need to use a tree view within your application.  The TcxCustomTreeView class can be used as the base when creating your own controls that require tree view functionality.


TcxCustomTreeView Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |


Properties for TcxCustomTreeView
TcxCustomTreeView Properties

TcxCustomTreeView          Legend

In TcxCustomTreeView

AutoExpand

ChangeDelay

DropTarget

HideSelection

HotTrack

Images

Indent

ItemHeight

Items

MultiSelect

MultiSelectStyle

RightClickSelect

RowSelect

Selected

SelectionCount

Selections

ShowButtons

ShowLines

ShowRoot

SortType

StateImages

ToolTips

TopItem

Derived from TcxContainer

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxCustomTreeView
TcxCustomTreeView Methods

TcxCustomTreeView          Legend

In TcxCustomTreeView

 ClearSelection

 CustomSort

 Deselect

 FindNextToSelect

 FullCollapse

 FullExpand

 GetHitTestInfoAt

 GetNodeAt

 IsEditing

 LoadFromFile

 LoadFromStream

 SaveToFile

 SaveToStream

 Select

 Subselect

Derived from TcxControl

 Create

 Destroy

 InvalidateRect


Events for TcxCustomTreeView
TcxCustomTreeView Events

TcxCustomTreeView          Legend

In TcxCustomTreeView

 OnAddition

 OnAdvancedCustomDraw

 OnAdvancedCustomDrawItem

 OnCancelEdit

 OnChange

 OnChanging

 OnCollapsed

 OnCollapsing

 OnCompare

 OnCreateNodeClass

 OnCustomDraw

 OnCustomDrawItem

 OnDeletion

 OnEdited

 OnEditing

 OnExpanded

 OnExpanding

 OnGetImageIndex

 OnGetSelectedIndex


TcxCustomTreeView.AutoExpand

TcxCustomTreeView

Specifies whether parent items are automatically expanded and collapsed when clicked.

property AutoExpand: Boolean;

Description

Set the AutoExpand property to True to enable automatic item expansion and collapse.  If enabled, parent items are automatically expanded when selected using the mouse (other expanded items are collapsed in this instance).  If you click an expanded item, it is collapsed.

You can change the expanded state of items by using the keyboard, expand buttons and via code independently of the AutoExpand property.  Please refer to the Expanding and Collapsing Tree View Nodes topic for a complete list of ways to expand and collapse items.

If the AutoExpand property is set to False, clicking an item merely results in selecting it.  To change the expanded state of items, double-click them or use the expand buttons.

The default value of the AutoExpand property is False.


TcxCustomTreeView.ChangeDelay

TcxCustomTreeView          See Also

Specifies the time interval (in milliseconds) that passes between selecting a node and the OnChange event being raised.

property ChangeDelay: Integer;

Description

You can respond to nodes being selected in the tree view control by handling the OnChange event.  This can for instance, be used to update the contents of a form with respect to the currently selected item (or perform other time-consuming operations).  In such cases, you may want to specify a delay between an item being selected and the desired actions being performed.  This is helpful in two cases.  If the user clicks the wrong node, he has time to correct his choice before any time-consuming operation begins.  This is also useful when performing navigation using the keyboard.

To specify the delay before responding to node selection, use the ChangeDelay property. This property value is set in milliseconds.  Thus, if you need a half second delay, set this property to 500.  If you need the tree view to respond to selection changes immediately, set this property to 0.

Note:	setting this property to a negative value has the same effect as setting it to 0.

The default value of the ChangeDelay property is 0.


TcxCustomTreeView.DropTarget

TcxCustomTreeView

Specifies which item in the tree view appears as the target of a drag and drop operation.

property DropTarget: TTreeNode;

Description

Read the DropTarget property to determine whether a node in the tree view is drawn as the target of a drag and drop operation. Set the DropTarget property to specify a particular node in the tree view as the drop target of a dragged item.

Note: When DropTarget is set, the application must still handle the actual logic of accepting the dragged object by the indicated node.


TcxCustomTreeView.HideSelection

TcxCustomTreeView

Specifies whether selection is hidden when the tree view looses focus.

property HideSelection: Boolean;

Description

The image below shows a sample tree view control with some of its items selected.  The control is focused.

The next screenshots illustrate the appearance of the control when it is not focused.  The HideSelection property is set to True and False, respectively.

Please refer to the Selecting Tree View Nodes topic for information on selecting nodes and responding to selection changes.

The default value of the HideSelection property is True.


TcxCustomTreeView.HotTrack

TcxCustomTreeView          See Also

Specifies whether tree view nodes are hot-tracked.

property HotTrack: Boolean;

Description

When the HotTrack property is set to True, nodes are highlighted when the mouse cursor rests over them.  Otherwise, they don’t respond to movements.

The images below show the appearance of the tree view control when the HotTrack property is set to True and False, respectively.

The default value of the HotTrack property is False.


TcxCustomTreeView.Images

TcxCustomTreeView           See Also

Provides images to be displayed within tree nodes.

property Images: TCustomImageList;

Description

The tree view control enables you to display images within nodes.  To perform this, you must place a TImageList component onto the form, fill it with images to be displayed and assign it to the Images property of the tree view.  To assign a specific image to a node, set the ImageIndex property of the node to the index of the desired image within the image list.  The image displayed within the node when it is selected is set using the node’s SelectedIndex property.  Set the ImageIndex and SelectedIndex properties to the same value if you need to display the same image for the normal and selected states of the node.

Please refer to the Displaying Images within Tree View Nodes topic for a complete list of ways to assign images to nodes.


TcxCustomTreeView.Indent

TcxCustomTreeView          See Also

Specifies the horizontal indent between parent and child nodes.

property Indent: Integer;

Description

Use the Indent property to change the indent between parent nodes and their children.  The indent is set in pixels.  Note that changing the Indent property also affects the position of first level nodes.

The images below show the same tree view control with the Indent property set to 19 and 30.  Note the change of the horizontal offset between items at different levels.

The Indent property cannot be set to a value less than 19.

Note:	if the ShowRoot property is set to False (expand buttons and tree lines are not displayed for root items), the Indent property doesn’t affect the offset of root level items from the left edge of the control.  The contents of root level items are always aligned to left in this instance.

Tip:	the Indent property is useful if you want to paint custom expand buttons that are wider than the default.  A single click on the expand button and anywhere before the node’s image/caption results in the expansion or collapse of the node.  Please refer to the OnCustomDrawItem and OnAdvancedCustomDrawItem event descriptions for details on painting tree view nodes manually.

The default value of the Indent property is 19.


TcxCustomTreeView.ItemHeight

TcxCustomTreeView          See Also

Specifies the height of items (in pixels) in the tree view.

property ItemHeight: Integer;

Description

A value of –1 indicates that the height is determined automatically based upon font settings.

The images below show the same tree view control with the ItemHeight property set to -1 and 22.  Note how this affects the vertical offset between items at different levels.

The default value of the ItemHeight property is –1.


TcxCustomTreeView.Items

TcxCustomTreeView

Provides access to nodes of the tree view.

property Items: TTreeNodes;

Description

The Items property contains elements displayed within the tree view control.  At design-time, this property can be used to create the hierarchical structure of nodes using the visual tree designer.  This designer can be invoked by clicking the ellipsis button corresponding to the Items property.

The left pane of the dialog enables you to create a tree structure.  The right pane is used to modify the properties of the currently selected node.

The Items property is represented by a TTreeNodes object.  This object stores a collection of all nodes within the tree.  The first item corresponds to the topmost node within the tree.  If the topmost node has children, the second item of the collection corresponds to the first child or the top node, etc.  Each node is represented by the TTreeNode object that provides access to its own children via the Item property.

At runtime, you can use the Items property either to create the structure of the tree or to access individual nodes.  Tree creation can be performed using methods of the TTreeNodes class.  The most commonly used methods are the Add and AddChild.  Please refer to the TTreeNodes method list for more information.  Individual items can be accessed to modify their settings.  For instance, you can change the expanded state of a node, its caption text, etc.  See the TTreeNode class description for a complete list of available settings.

A common task you might encounter when using a tree view control is to traverse through all nodes.  This can be performed using the following procedure.

// Delphi

var ACurrentNode: TTreeNode;

begin

  ACurrentNode := cxTreeView1.Items[0];

  while ACurrentNode <> nil do

  begin

    // perform the desired operations on the current node here

    // ...

    ACurrentNode := ACurrentNode.GetNext;

  end;

end;

The code uses the GetNext method of the TTreeNode class to obtain the next node within the tree (child nodes are also visited).  Please refer to the TTreeNode class description for details on methods used to navigate through nodes.


TcxCustomTreeView.MultiSelect

TcxCustomTreeView          See Also

Specifies whether multiple nodes can be selected.

property MultiSelect: Boolean;

Description

Set the MultiSelect property to True to enable multiple node selection.  In this instance, the MultiSelectStyle property specifies the keys that can be used along with mouse clicks to select several nodes.  Note that if the MultiSelectStyle property value indicates that no keys can be used, the multi selection feature is not available to end users.  However, you can still select multiple nodes in code.

If the MultiSelect property is set to False, multiple nodes cannot be selected either by end users or in code. Please refer to Selecting Tree View Nodes topic for details on selecting nodes in code.

The default value of the MultiSelect property is False.


TcxCustomTreeView.MultiSelectStyle

TcxCustomTreeView          See Also

Contains multi selection options for the tree view.

type

  TMultiSelectStyles = (msControlSelect, msShiftSelect, msVisibleOnly, msSiblingOnly);

  TMultiSelectStyle = set of TMultiSelectStyles;

property MultiSelectStyle: TMultiSelectStyle;

Description

Multi select operations in the tree view are enabled when the MultiSelect property is set to True.  The MultiSelectStyle property contains a set of options affecting the multi selection feature.  Available options include:

Value	Meaning
msControlSelect	Clicking on any node with the CTRL key pressed toggles the selection of that node.
msShiftSelect	Clicking on any node with the SHIFT key press selects that node, the last node selected, and all nodes in between. All other nodes are deselected.
msVisibleOnly	Multiple selections with the SHIFT key do not include child nodes of collapsed nodes.
msSiblingOnly	Selected nodes are restricted to a single set of siblings.

Note that if the msControlSelect and msShiftSelect options are both disabled, end users are not allowed to select multiple nodes even if the MultiSelect property is set to True.  However, you can still select multiple nodes in code using the Select method.  This means you can allow end users to select nodes by other means.  For instance, you can toggle the selected state of nodes when they are right-clicked.

If the MultiSelect property is set to False, multiple node selection cannot be performed either by end users or in code.

Please refer to the Selecting Tree View Nodes topic for more information on node selecting.


TcxCustomTreeView.ReadOnly

TcxCustomTreeView          See Also

Specifies whether end users can edit item captions.

property ReadOnly: Boolean;

Description

If the ReadOnly property value is False, the tree view control enables end users to edit item captions.  To perform this, end users must select the desired item and then click it.  The image below shows how item caption can be edited.

Note that if the ReadOnly property is set to False (editing is allowed) the OnEditing event fires each time the node caption is about to be edited.  You can use this event to prohibit caption editing for specific nodes.

After the item’s caption has been edited, the OnEdited event is raised.  Use it to provide a proper response to changes in the item’s caption.

Tip:	Sometimes you may need to start node caption editing in response to specific actions.  For instance, a common practice is to allow end users to start editing by pressing the F2 key.  The code below handles the OnKeyDown event to perform this.

// Delphi

procedure TForm1.cxTreeView1KeyDown(Sender: TObject; var Key: Word; Shift: TShiftState);

begin

  if Key <> VK_F2 then Exit;

  with TcxTreeView(Sender).Selected do

    TreeView_EditLabel(Handle, ItemId);

end;

Please refer to the Tree-View Label Editing, TreeView_EditLabel and TreeView_EndEditLabelNow topics of the Windows SDK help system for details on editing node captions at runtime.  Also, see the IsEditing topic for another example of invoking node editing.

The default value of the ReadOnly property is False.


TcxCustomTreeView.RightClickSelect

TcxCustomTreeView

Specifies whether the Selected property returns the right-clicked node when the control’s popup menu is invoked.

property RightClickSelect: Boolean;

Description

The RightClickSelect property is useful if you need to have a context menu associated with the tree view to perform specific actions on nodes.  In this instance, you need to bind a TPopupMenu component to the tree view control using the control’s PopupMenu property.  If such binding has been performed, right-clicking the tree view control will result in invoking the popup menu.  The easiest way to determine the node for which the menu has been invoked is to read the Selected property value when handling the OnPopup event of the menu.  This property will return the right-clicked node if the RightClickSelect property is set to True.  Otherwise, the node that was last left-clicked will be returned.

Consider an example of using the context menu to perform actions on nodes.  To use the code below, you need a tree view control on the form and a popup menu.  The popup menu should have a single item named ‘Delete’.  Clicking this item will delete the node that has been right-clicked when invoking the context menu.  Note that the code below succeeds if the menu is assigned to the PopupMenu property of the tree view and the tree view’s RightClickSelect property value is set to True.

// Delphi

var

  CurrentNode: TTreeNode;

// the menu item’s click handler

procedure TForm1.Delete1Click(Sender: TObject);

begin

  if CurrentNode <> nil then

    CurrentNode.Delete;

end;

// the menu’s popup handler

procedure TForm1.PopupMenu1Popup(Sender: TObject);

begin

  CurrentNode := cxTreeView1.Selected;

end;

The image below shows an example of using the popup menu to delete a node.

If you do not wish to use the technique described above, it is necessary to handle the OnMouseDown event of the tree view, determine the clicked node by mouse pointer coordinates and invoke the popup menu manually.  This is, of course, a more complicated way, but you may find a need to use it at some stage. The reason is that when a popup menu is assigned to the PopupMenu property of the control, it is invoked when end users right-click anywhere within the control’s client area.  Thus, you cannot use this if you need to display the menu only when node captions are clicked.


TcxCustomTreeView.RowSelect

TcxCustomTreeView          See Also

Specifies how node selection is painted.

property RowSelect: Boolean;

Description

If the tree view control doesn’t display tree lines (the ShowLines property is set to True), you can choose the selection painting style.  If the RowSelect property is set to True, entire rows are highlighted when nodes are selected.  Otherwise, only node captions are highlighted.  The images below show the tree view control when the RowSelect property is set to False and True respectively.

Please refer to the Selecting Tree View Nodes topic for information on selecting nodes.

The default value of the RowSelect property is False.


TcxCustomTreeView.Selected

TcxCustomTreeView          See Also

Specifies the currently selected node.

property Selected: TTreeNode;

Description

Read the Selected property value to obtain the currently selected node.  Note that when multiple node selection is enabled (the MultiSelect property value is True), the Selected property returns the last selected node.  To obtain all the selected nodes, use the Selections property.

Determining the currently selected node is most commonly used when you provide a response to changing the selection.  You must handle the OnChange event for this purpose.

The Selected property can also be used to change the selected node.  Assign the desired node to this property to accomplish this.  Use the Items property to obtain nodes.

When multiple node selection is used, assigning a node to the Selected property makes the node selected and deselects all other nodes.  However, if the last selected node is assigned to the Selected property, nothing happens.  The reason is that the Selected property value is not changed in this case.  Note also, that when using multiple node selection, the Selected property can return a deselected node.  This takes place when deselecting a node by clicking it holding the CTRL key pressed.  The focus rectangle is painted around the caption of that node but it is not selected.

If nil is assigned to the Selected property, all nodes are deselected.  This can also be performed by calling the ClearSelection method.

Please refer to the Selecting Tree View Nodes topic for more information on selecting nodes.


TcxCustomTreeView.SelectionCount

TcxCustomTreeView          See Also

Returns the number of currently selected items.

property SelectionCount: Cardinal;

Description

Use the SelectionCount property to obtain the number of nodes that are currently selected.  For instance, this can be useful if you need to obtain all the selected nodes.  In this case, you must traverse through the Selections collection.  The index of the first item within the collection is 0.  The index of the last item is the SelectionCount property decremented by one.

The SelectionCount property always returns 1 if multiple node selection is disabled (the MultiSelect property value is False).  In this case you can access the selected node directly using the Selected property.

Please refer to the Selecting Tree View Nodes topic for additional information about node selection.

ReadOnly Property


TcxCustomTreeView.Selections

TcxCustomTreeView          See Also

Provides access to selected nodes.

property Selections[Index: Integer]: TTreeNode;

Description

Use the Selections property to access currently selected nodes.  The Index parameter specifies the index of the node within the selected nodes list.  The first available index is zero.  The node obtained by this index is the first selected node.  The index of the last available node is the SelectionCount property value decremented by one.  This node is the last selected node.

The Selections and SelectionCount properties can be used in combination to traverse through selected nodes.  This is needed when you need to perform specific actions on each selected node (or on objects associated with selected nodes).  The code below shows the general approach to performing this.

// Delphi

var

  I: Integer;

  ANode: TTreeNode;

begin

  for I := 0 to cxTreeView1.SelectionCount - 1 do

  begin

    ANode := cxTreeView1.Selections[I];

    // perform the desired operations on the currently processed node here

  end;

end;

At times, you may need to delete all the selected nodes from the tree view.  This operation has two unique issues associated with it.  The first is when deleting nodes, they are removed from the Selections collection and thus the SelectionCount property value is decremented.  The second is that when deleting the last selected node, the control automatically selects its neighboring node (or the parent, if there are no nodes at the same level).  Thus, to perform node deletion you must first copy selected nodes to a different list and then remove them.  The code below shows how to perform this.

// Delphi

var

  I: Integer;

  ANodes: TList;

begin

  ANodes := TList.Create;

  for I := 0 to cxTreeView1.SelectionCount - 1 do

    ANodes.Add(cxTreeView1.Selections[I]);

  for I := 0 to ANodes.Count - 1 do

    TTreeNode(ANodes.Items[I]).Delete;

  ANodes.Free;

end;

You may also want to perform specific actions on nodes when the selection changes.  Handle the OnChange event for this purpose. Please refer to the Selecting Tree View Nodes topic for more information regarding node selection.

ReadOnly Property


TcxCustomTreeView.ShowButtons

TcxCustomTreeView          See Also

Specifies whether expand buttons are displayed within nodes that have children.

property ShowButtons: Boolean;

Description

Set the ShowButtons property to False to hide expand buttons displayed within parent nodes.  The images below show you the tree view control when the ShowButtons property is set to True and False respectively.

If expand buttons are not displayed, end users can use the following methods to expand and collapse parent nodes:

•	Pressing the right and left arrow keys when the desired parent node is selected;

•	Double-clicking the desired parent node if the AutoExpand property value is False;

•	Single-clicking the desired parent node if the AutoExpand property value is True.

See the Expanding and Collapsing Tree View Nodes topic for more information on expanding and collapsing nodes.

Note:	You can hide expand buttons only on the root level of the tree.  Set the ShowRoot property to False for this purpose.

The default value of the ShowButtons property is True.


TcxCustomTreeView.ShowLines

TcxCustomTreeView          See Also

Specifies whether tree lines are visible.

property ShowLines: Boolean;

Description

Set the ShowLines property to False to hide tree lines.  If it is set to True, tree lines are displayed.  The images below illustrate both values for this property.

Note that when the ShowLines property value is False you can change node selection style.  Please refer to the RowSelect property description for details.

The default value of the ShowLines property is True.


TcxCustomTreeView.ShowRoot

TcxCustomTreeView          See Also

Specifies the visibility of tree lines and expand buttons at the root level of the tree.

property ShowRoot: Boolean;

Description

Set the ShowRoot property to False to hide tree lines and expand buttons at the root level of the tree.  If they are hidden, contents of root nodes are displayed at the left edge of the control without any indent independently of the Indent property value.  The Indent property affects only the offset of child items relative to their parents.

The images below show sample tree view controls when the ShowRoot property is set to True and False respectively.

As an example, change the Indent property to 29.  This will increase the indent between parent nodes and their children by 10 pixels.  Note that when the ShowRoot property is True, the indent of root nodes changes.  If the ShowRoot property is False, the contents of root nodes remain aligned to the left edge of the control.

You can also hide all tree lines and all expand buttons within the control.  Use the ShowLines and ShowButtons properties for this purpose.

Note that hiding expand buttons may confuse end users since they will probably not be able to determine whether nodes have children.

The default value of the ShowRoot property if True.


TcxCustomTreeView.SortType

TcxCustomTreeView          See Also

Specifies the type of sorting applied to tree view control nodes

type

  TSortType = (stNone, stData, stText, stBoth);

property SortType: TSortType;

Description

Use the SortType property to sort tree view control nodes and specify when they need to be resorted.  The following values are available for this property.

Value	Meaning
stNone	Specifies that sorting is not applied tree view nodes.  This means that the control will not automatically resort nodes until the SortType property is set to another value.  However, nodes can still be sorted programmatically by calling the AlphaSort or CustomSort method. Changing the SortType property to stNone when nodes are already sorted will not restore the original order of items.  If you need to restore original node order, the best is to save the node layout at application startup using the SaveToFile or SaveToStream methods.  Then, nodes can be reloaded using the LoadFromFile and LoadFromStream method when needed.
stText	Specifies that tree view nodes are sorted by their captions in ascending order.  Each time the caption of a node is changed, nodes are resorted.  To toggle sort order, call the AlphaSort method. You can implement custom sorting logic by handling the OnCompare event.  In this instance, the stText value merely implies that nodes need to be resorted each time a node caption changes.  Thus you must use this value if the sorting logic only uses node captions (the Text property) to perform node comparison.  The resulting sort order depends upon the implementation of the OnCompare event handler.
stData	Setting the SortType property doesn’t apply any predefined sort order to nodes.  This value merely implies that node resorting must be invoked each time the value of a node’s Data property is changed.  The sorting logic must be implemented by handling the OnCompare event. Set the SortType property to stData if you implement sorting that is based on the Data property value of nodes and does not depend on its Text property value.  If the sorting algorithm uses both properties, set the SortType property to stBoth.
stBoth	This value implies that node sorting takes place each time the Text or Data property of a node is changed.  The sorting logic must be implemented in the OnCompare event handler.  Use the stBoth value if your sorting algorithm uses both the Text and Data properties of nodes to perform node comparison.  If only the Text or Data property is used, set the SortType property to stText or stData respectively.

You may need to use a sorting procedure that uses custom node settings (other than the Text or Data property) to perform sorting.  In this instance, you must leave the SortType property set to stNone to disable automatic node restoration when changing the mentioned properties.  When settings used in your sorting algorithm are changed or nodes are added to the tree view, you must manually call the AlphaSort method.  Use the OnAddition method to provide a response to node addition.

Please refer to the OnCompare method description for an example of performing custom node sorting.

Warning:	When nodes are sorted, their indexes within the tree view are changed.  Thus accessing nodes by indexes after sorting may lead to errors.

The default value of the SortType property is stNone.


TcxCustomTreeView.StateImages

TcxCustomTreeView          See Also

Provides state images to be displayed within tree nodes.

property StateImages: TCustomImageList;

Description

cxTreeView enables you to display up to two images within each node.  By default, no images are displayed.

If you need additional images to be displayed within nodes, assign the TImageList component storing the desired images to the StateImages property.  You can then choose an image from the list to be displayed within the node by setting the node’s StateIndex property.

The following is a handler for the form’s OnCreate event.  It is used to create an image list, add two images corresponding to checked and unchecked states and assign the unchecked image to every item.

// Delphi

procedure TForm1.FormCreate(Sender: TObject);

var

  ImageList: TImageList;

  Image: TBitmap;

  I: Integer;

begin

  ImageList := TImageList.Create(Self);

  ImageList.AddMasked(nil, $000000);

  Image := TBitmap.Create;

  Image.LoadFromFile('c:\Images\checked.bmp');

  ImageList.AddMasked(Image, $FF00FF);

  Image.LoadFromFile('c:\Images\unchecked.bmp');

  ImageList.AddMasked(Image, $FF00FF);

  cxTreeView1.StateImages := ImageList;

  for I := 0 to cxTreeView1.Items.Count - 1 do

    cxTreeView1.Items[I].StateIndex := 2;

end;

The OnClick event of the tree view control must be handled in the following manner to perform image toggling.

// Delphi

procedure TForm1.cxTreeView1Click(Sender: TObject);

var

  MousePos: TPoint;

  Node: TTreeNode;

begin

  MousePos := Mouse.CursorPos;

  MousePos := cxTreeView1.ScreenToClient(MousePos);

  Node := cxTreeView1.GetNodeAt(MousePos.X, MousePos.Y);

  if Node <> nil then

    if htOnStateIcon in cxTreeView1.GetHitTestInfoAt(MousePos.X, MousePos.Y) then

    begin

      if Node.StateIndex = 2 then

        Node.StateIndex := 1

      else

        Node.StateIndex := 2;

    end;

end;

The image below shows the appearance of the control.

Please refer to the Displaying Images within Tree View Nodes topic for a complete list of ways in which to assign images to nodes.


TcxCustomTreeView.ToolTips

TcxCustomTreeView

Specifies whether tool tips are displayed for nodes whose contents don’t fit into the control’s area.

property ToolTips: Boolean;

Description

The image below shows an example of a tool tip.

Tip:	If you need to display node hints, you need to handle the OnHint event of the application object.  The event handler must determine the hovered node using the GetNodeAt method of the tree view and assign the appropriate hint to the control’s Hint property.  Note that the tree view’s ShowHint property must be set to True and a non-empty string must be assigned to the Hint property so that the OnHint event can be raised.

The code below is an example of assigning hints to nodes of a tree view.  Hints will display the list of child nodes.  The OnMouseMove event is handled in the following manner:

// Delphi

procedure TForm1.cxTreeView1MouseMove(Sender: TObject; Shift: TShiftState;

  X, Y: Integer);

var

  Node: TTreeNode;

  I: Integer;

begin

  Node := cxTreeView1.GetNodeAt(X, Y);

  if (Node = nil) or (Node = PrevNode) then Exit;

  PrevNode := Node;

  cxTreeView1.Hint := 'Children list:';

  for I := 0 to Node.Count - 1 do

    cxTreeView1.Hint := cxTreeView1.Hint + #13#10 + '- ' + Node.Item[I].Text;

  if not Node.HasChildren then cxTreeView1.Hint := 'No children';

  Application.ActivateHint(cxTreeView1.ClientToScreen(Point(X, Y)));

end;

Here, PrevNode is the global variable that is assigned nil in the form’s OnCreate event handler.

// Delphi

var

  PrevNode: TTreeNode;

procedure TForm1.FormCreate(Sender: TObject);

begin

  PrevNode := nil;

end;

Upon execution, the result is as follows:

The default value of the ToolTips property is False.


TcxCustomTreeView.TopItem

TcxCustomTreeView

Specifies the topmost visible tree node.

property TopItem: TTreeNode;

Description

When there are too many items displayed to fit into the control vertically, a vertical scroll bar is displayed.  This enables end users to scroll through the tree.  If you need to determine the node which is currently the topmost visible, read the TopItem property value.  This property also enables you to specify the topmost visible node programmatically.  Thus you can scroll the tree view control vertically via code.

Here is an example of using the TopItem property.  By default, when expanding a node, the control tries to scroll the view so that all child nodes are visible.  You can avoid this effect by storing the top visible node when the node is about to be expanded and restoring it after the operation has been completed.  The OnExpanding and OnExpanded events are used for this purpose.

// Delphi

var

  CurrentNode: TTreeNode;

procedure TForm1.cxTreeView1Expanding(Sender: TObject; Node: TTreeNode;

  var AllowExpansion: Boolean);

begin

  CurrentNode := cxTreeView1.TopItem;

end;

procedure TForm1.cxTreeView1Expanded(Sender: TObject; Node: TTreeNode);

begin

  cxTreeView1.TopItem := CurrentNode;

end;


TcxCustomTreeView.AlphaSort

TcxCustomTreeView          See Also

Sorts tree nodes.

function AlphaSort(ARecursive: Boolean = True): Boolean;

Description

Call the AlphaSort method to sort nodes within the tree view control.  By default, the method sorts nodes by their captions.  If nodes are not currently sorted, ascending sort order is applied.  If the nodes are already sorted, AlphaSort toggles sort order.

The ARecursive parameter specifies whether nodes at all nesting levels must be sorted.  Specify False as its value to sort only root level nodes.  Note that this parameter is optional and is True by default.

If an OnCompare event handler has been written, it is used to compare nodes when sorting using the AlphaSort method.  This enables you to implement custom algorithms of node sorting.

Note that calling the AlphaSort method is equivalent to calling the CustomSort method with the first parameter set to nil.  AlphaSort simply calls this method to perform sorting.  You can also sort nodes within the tree view by calling the AlphaSort method of the TTreeNodes object standing for the Items property of the control.  If you need to sort an individual branch within the tree, call the AlphaSort method of the TTreeNode object representing the desired parent node.

The AlphaSort method is used when the control performs automatic node sorting.  This takes place when the SortType property of the control is set to a value different than stNone.  If the SortType property is set to stText, the AlphaSort method is automatically called each time the Text property of any node at the root level changes.  If changing node text located at other nesting levels, the AlphaSort method of the TTreeNode object representing this node’s parent is called.  If the SortType property is set to stData, these methods are called each time the Data node property is changed.  Finally, setting the SortType property to stBoth forces the control to call these methods when either the Text or Data property of nodes are changed.


TcxCustomTreeView.ClearSelection

TcxCustomTreeView          See Also

Clears the selection.

procedure ClearSelection(KeepPrimary: Boolean = False); virtual;

Description

Use the ClearSelection method to remove selection from all selected nodes.  The KeepPrimary parameter specifies whether the last selected node must be deselected together with others.  This parameter is optional and is False by default.  Note that if a single node is currently selected, calling the ClearSelection method with True as the parameter performs nothing.

If you need to deselect an individual node, use the Deselect method.  When a single node is selected, it can be deselected by setting the Selected property of the control to nil.

Please refer to the Selecting Tree View Nodes topic for additional information on selecting and deselecting nodes.


TcxCustomTreeView.CustomSort

TcxCustomTreeView          See Also

Sorts nodes using the specified node comparison routine.

{$IFNDEF CLR}

type

  TTVCompare = function(lParam1, lParam2, lParamSort: Longint): Integer stdcall;

function TcxCustomTreeView.CustomSort(SortProc: TTVCompare; Data: Longint; ARecurse: Boolean = True): Boolean;

{$ELSE}

type

  TTVCompareProc = function(lParam1, lParam2: TTreeNode; lParamSort: TTag): Integer;

function TcxCustomTreeView.CustomSort(SortProc: TTVCompareProc; Data: TTag; ARecurse: Boolean = True): Boolean;

{$ENDIF}

Description

The CustomSort method is used to perform node sorting using the comparison routine specified by the SortProc parameter.  If nil is passed as the SortProc parameter, the method behaves like the AlphaSort method.  Please refer to the TCustomTreeView.CustomSort method description for details on using the CustomSort method.

It is not recommended that you use the CustomSort method.  Instead, call the AlphaSort method and handle the OnCompare event to specify the appropriate node comparison logic.  If the OnCompare event is not handled, the AlphaSort method compares nodes by their captions (the Text property of TTreeNode objects representing nodes).


TcxCustomTreeView.Deselect

TcxCustomTreeView          See Also

Removes selection from the specified node.

procedure Deselect(Node: TTreeNode); virtual;

Description

When a single node is selected, you can deselect it by setting the Selected property to nil.  You can, however, enable multiple node selection by setting the MultiSelect property to True.  In this instance, use the Deselect method to remove selection from specific nodes.  Its Node parameter specifies the node to be deselected.  If nil is passed as this parameter, the method performs nothing.

When multiple node selection is applied, setting the Selected property to nil clears the selection.  This can also be achieved by calling the ClearSelection method.

See the Selecting Tree View Nodes topic for the complete list of ways to select and deselect nodes.


TcxCustomTreeView.FindNextToSelect

TcxCustomTreeView

Returns the next selectable node.

function FindNextToSelect: TTreeNode; virtual;

Description

Starting with the node specified by the Selected property, the FindNextToSelect method searches for a deselected node, with preference given to subsequent siblings. If the node returned by the Selected property and all its siblings are selected, the search proceeds to the parent node and its siblings, and so on up the tree. If the top level is reached without finding a deselected node, nil is returned.

Note that the Selected property can refer to a deselected node when MultiSelect is True. In this instance, the FindNextToSelect method returns that node.


TcxCustomTreeView.FullCollapse

TcxCustomTreeView          See Also

Collapses all parent nodes.

procedure FullCollapse;

Description

Use the FullCollapse method to collapse all parent nodes within the tree.  After calling this method, only root level nodes are visible.  Note that if a child node was selected before calling the FullCollapse method, selection moves to its parent at the top level.  If several nodes were selected, selection moves to the parent of the last selected node.

If you need to expand all the nodes within the tree, call the FullExpand method.  To expand and collapse an individual node, use the Expanded property of the TTreeNode object representing the desired node.

When the FullCollapse method is execute, the OnCollapsing and OnCollapsed events fire for each collapsed node.  If the OnCollapsing event sets its AllowCollapse parameter to False for certain nodes, these nodes are not collapsed.

The following sample code shows how to prevent collapsing parents of the selected node when calling the FullCollapse method.  Before calling the method, a global variable is set to True indicating that the full collapsing procedure is in progress.  The OnCollapsing event checks this variable and prohibits the parents of the selected node from being collapsed, if it’s set to True.  Otherwise, all nodes can be collapsed.

// Delphi

var

  FullCollapseInProgress: Boolean;

// ...

FullCollapseInProgress := True;

cxTreeView1.FullCollapse;

FullCollapseInProgress := False;

// ...

procedure TForm1.cxTreeView1Collapsing(Sender: TObject; Node: TTreeNode;

  var AllowCollapse: Boolean);

begin

  if not FullCollapseInProgress then Exit;

  if cxTreeView1.Selected = nil then Exit;

  if cxTreeView1.Selected.HasAsParent(Node) then

    AllowCollapse := False;

end;

Here is the result:

Please refer to the Expanding and Collapsing Tree View Nodes topic for details.


TcxCustomTreeView.FullExpand

TcxCustomTreeView          See Also

Expands all parent nodes within the tree.

procedure FullExpand;

Description

Use the FullExpand method to expand all parent nodes within the tree view control.  After the method is executed, all nodes become visible.  This is useful, if you have a small number of items within the tree and want end users to see them all at once.  For instance, if the tree view control is used for navigation purposes, you can call the FullExpand method on form creation and prohibit node collapse by handling the OnCollapsing event.  In this instance, end users will see all nodes and will not be able to collapse parents.  The code below shows how to perform this.  The OnCreate event of the form and the OnCollapsing event of the tree view are handled.

// Delphi

procedure TForm1.FormCreate(Sender: TObject);

begin

  // hiding expand buttons

  cxTreeView1.ShowButtons := False;

  // hiding tree lines at the root level

  cxTreeView1.ShowRoot := False;

  cxTreeView1.FullExpand;

end;

procedure TForm1.cxTreeView1Collapsing(Sender: TObject; Node: TTreeNode;

  var AllowCollapse: Boolean);

begin

  AllowCollapse := False;

end;

The result is as follows:

If you need to collapse all the nodes within the tree, call the FullCollapse method.  To change the expanded state of an individual node, use the Expanded property of the TTreeNode object representing the desired node.

When the FullExpand method is executed, the OnExpanding and OnExpanded events fire for each expanded node.  If the OnExpanding event handler sets the AllowExpansion parameter to False, the processed node is not expanded.  This can be used to perform partial expansion using the FullExpand method.

The example below demonstrates how to use the FullExpand method to expand all nodes up to the specified nesting level.  For this purpose, a global variable specifying whether the FullExpand method is in progress is used.  If set to True, the OnExpanding event handler prohibits expansion of nodes that don’t reside at the root level.

// Delphi

var

  FullExpandInProgress: Boolean;

// ...

FullExpandInProgress := True;

cxTreeView1.FullExpand;

FullExpandInProgress := False;

// ...

procedure TForm1.cxTreeView1Expanding(Sender: TObject; Node: TTreeNode;

  var AllowExpansion: Boolean);

begin

  if not FullExpandInProgress then Exit;

  if Node.Level > 0 then

    AllowExpansion := False;

end;

The result is as follows:

Please refer to the Expanding and Collapsing Tree View Nodes topic for more information on expanding and collapsing nodes.


TcxCustomTreeView.GetHitTestInfoAt

TcxCustomTreeView          See Also

Determines the elements of the control located under a specified point.

type

  THitTest = (htAbove, htBelow, htNowhere, htOnItem, htOnButton, htOnIcon, htOnIndent, htOnLabel, htOnRight, htOnStateIcon, htToLeft, htToRight);

  THitTests = set of THitTest;

function GetHitTestInfoAt(X, Y: Integer): THitTests;

Description

Use the GetHitTestInfoAt method to determine the element of the control located under a specified point.  The point is specified by its horizontal and vertical coordinates using X and Y method parameters.  Note that coordinates must be set in the control’s client coordinates.  Thus, if you have screen coordinates of the point, use the control’s ScreenToClient method to obtain client coordinates.

Generally, the GetHitTestInfoAt method is used to determine the element located under the mouse pointer.  For instance, you may need to display information about the element located under the pointer within the status bar.  Another example can be invoking the context menu when end users click node captions.  Note that the GetHitTestInfoAt method is most commonly used in conjunction with the GetNodeAt method.  The latter returns the node located under the specified point.

The sample code below handles the OnClick event of the tree view control.   If the clicked element is a node image, then an overlay image is painted.  The overlay image represents a red X.  It is applied by setting the OverlayIndex property of the node to a value different from -1.  The code uses the GetHitTestInfoAt method to determine whether the mouse pointer is over a node image.  The node is obtained using the GetNodeAt method call.

// Delphi

procedure TForm1.cxTreeView1Click(Sender: TObject);

var

  MousePos: TPoint;

  Node: TTreeNode;

begin

  MousePos := Mouse.CursorPos;

  MousePos := cxTreeView1.ScreenToClient(MousePos);

  Node := cxTreeView1.GetNodeAt(MousePos.X, MousePos.Y);

  if Node <> nil then

    if htOnIcon in cxTreeView1.GetHitTestInfoAt(MousePos.X, MousePos.Y) then

    begin

      if Node.OverlayIndex = -1 then

        Node.OverlayIndex := 0

      else

        Node.OverlayIndex := -1;

    end;

end;

If this handler for the OnClick event is used, end users can click node images to show and hide the red X.  The result is as follows:

See the ToolTips topic for another example of using the GetHitTestInfoAt method.


TcxCustomTreeView.GetNodeAt

TcxCustomTreeView          See Also

Gets the node located under the specified point.

function GetNodeAt(X, Y: Integer): TTreeNode;

Description

Use the GetNodeAt method to obtain the TTreeNode object representing the node located under the specified point.  The point is specified by its horizontal and vertical coordinates via X and Y parameters respectively.  Note that the control’s client coordinates must be specified.  If you have screen coordinates, you should use the ScreenToClient method of the control to obtain client coordinates.

The GetNodeAt method is most commonly used to obtain the node located under the mouse pointer.  This can be used, for instance, to display additional information about nodes within the status bar when pointing to nodes with the mouse pointer.  If you need to determine which element of the node is under the mouse pointer, use the GetHitTestInfoAt method.

The following sample code handles the OnMouseMove event of the tree view control.  This is used to display node captions within the status bar when the mouse pointer points to them.  Note that you need a status bar with at least one section created on your form to use the code below.

// Delphi

procedure TForm1.cxTreeView1MouseMove(Sender: TObject; Shift: TShiftState;

  X, Y: Integer);

var

  Node: TTreeNode;

begin

  Node := cxTreeView1.GetNodeAt(X, Y);

  if Node = nil then

    StatusBar1.Panels[0].Text := ''

  else

    StatusBar1.Panels[0].Text := Node.Text;

end;

Here is the result of code execution:

See the ToolTips and GetHitTestInfoAt topics for other examples of using the GetNodeAt method.


TcxCustomTreeView.IsEditing

TcxCustomTreeView          See Also

Indicates whether the user is currently editing a node caption.

function IsEditing: Boolean;

Description

Use the IsEditing method to determine whether the user is currently editing a node caption.  If so, the method returns True.  Otherwise, False.  Note that node editing is only allowed if the ReadOnly property of the tree view is set to False.

The sample code below shows how to toggle the editing mode for the currently selected node in response to pressing specific keys.  The F2 key toggles the editing mode for the currently selected node.  The ESC key stops node caption editing without saving changes made.  The OnKeyDown event of the tree view control is handled to respond to key press events.

// Delphi

procedure TForm1.cxTreeView1KeyDown(Sender: TObject; var Key: Word;

  Shift: TShiftState);

var SelectedNode: TTreeNode;

begin

  SelectedNode := cxTreeView1.Selected;

  if SelectedNode = nil then Exit;

  if Key = VK_F2 then

  begin

    if cxTreeView1.IsEditing then

      TreeView_EndEditLabelNow(SelectedNode.Handle, False)

    else

      TreeView_EditLabel(SelectedNode.Handle, SelectedNode.ItemId);

  end;

  if (Key = VK_ESCAPE) and cxTreeView1.IsEditing then

    TreeView_EndEditLabelNow(SelectedNode.Handle, True);

end;

Please refer to the Tree-View Label Editing, TreeView_EditLabel and TreeView_EndEditLabelNow topics of the Windows SDK help system for details on editing node captions at runtime.


TcxCustomTreeView.LoadFromFile

TcxCustomTreeView          See Also

Loads nodes from a specified text file.

procedure LoadFromFile(const FileName: string);

Description

Use the LoadFromFile method to load nodes into the tree view from a file previously created using the SaveToFile method.  The source file is specified by the FileName parameter.  If the specified file doesn’t exist, or cannot be opened for some other reason, an exception is raised.

Please refer to the Saving and Restoring Tree Nodes Structure for more information and examples of using the LoadFromFile and related methods.


TcxCustomTreeView.LoadFromStream

TcxCustomTreeView          See Also

Loads nodes from the specified stream.

procedure LoadFromStream(Stream: TStream);

Description

Use the LoadFromStream method to load nodes into the tree view from the specified stream.  The source stream is specified by the Stream parameter.  It must be previously populated with data using the SaveToStream method.

Note:	When loading your node structure using the LoadFromStream method, ensure that the Position property of the source stream points to the same position as it was before calling the SaveToStream method to fill the stream.

Please refer to the Saving and Restoring Tree Nodes Structure topic for additional information and examples of saving and restoring the nodes structure.


TcxCustomTreeView.SaveToFile

TcxCustomTreeView          See Also

Saves the node structure to a specified text file.

procedure SaveToFile(const FileName: string);

Description

Use the SaveToFile method to save the structure of nodes into a specified text file.  The file is specified by the FileName parameter.  This is a string comprised of the path to the file and its name.  If the file with the specified name cannot be created, an exception is raised.  If such a file already exists, it is overwritten without any warnings.

After the nodes structure has been saved to a file, you can restore it using the LoadFromFile method.  If storing data in a text file doesn’t suit your needs, consider using the SaveToStream and LoadFromStream method pair.

See the Saving and Restoring Tree Nodes Structure topic for more information.


TcxCustomTreeView.SaveToStream

TcxCustomTreeView          See Also

Saves the node structure to a specified stream.

procedure SaveToStream(Stream: TStream);

Description

Use the SaveToStream method to save the node structure into a stream specified by the Stream parameter.  The parameter must be represented by any TStream descendant object.  Note that using a TFileStream object as the parameter produces the same output file as if using the SaveToFile method.

After saving the node structure to a stream, it can be restored using the LoadFromStream method call.  If using streams to save and restore nodes doesn’t suit your needs, consider using the SaveToFile and LoadFromFile method pair.

Please refer to the Saving and Restoring Tree Nodes Structure topic for additional information and examples of using the mentioned methods.


TcxCustomTreeView.Select

TcxCustomTreeView          See Also

Selects the specified nodes.

Overloaded Variants

procedure Select(Node: TTreeNode; ShiftState: TShiftState = []);

procedure Select(const Nodes: array of TTreeNode);

procedure Select(Nodes: TList);

Description

The Select method is used to select nodes when the multiple node selection feature is enabled (the MultiSelect property value is True).  Note that it can also be used when only a single node can be selected, but in such a case, it is best to use the Selected property of the control.

The Select method provides three overloads so you can choose one that is most appropriate for your needs.

The first overload of the Select method imitates the behavior of the tree view when clicking a node.  The Node parameter specifies the node which is clicked.  The ShiftState parameter specifies the keys pressed when clicking.  This parameter is optional.  If omitted, it is assumed that no keys are pressed when clicking.

If the MultiSelect property is set to False, the first overload merely moves selection to the specified node.  If the specified node is already selected, it performs nothing.  If the MultiSelect property value is True, the behavior of the method depends on the ShiftState parameter value and the MultiSelectStyle property value.  If the ShiftState parameter specifies an empty set or omitted the Select method clears the current selection and selects the specified node.  If the ShiftState parameter includes ssShift and the msShiftSelect flag is included into the MultiSelectStyle property value, the method select all nodes starting from the last selected to that specified.  If the ShiftState parameter includes ssCtrl and the msControlSelect flag is included into the MultiSelectStyle property value, the method toggles the selection state of the specified node.  Remaining selections are unchanged in this instance. If both ssShift and ssCtrl are included into the ShiftState parameter value, ssCtrl is ignored.

Note that the msVisibleOnly and msSiblingOnly flags of the MultiSelectStyle property are also taken into account by the first overload of the Select method.

The following sample code toggles the selected state of the first node within the control.  The first line of code enables the msControlSelect flag of the MultiSelectStyle property to ensure that selecting nodes using the CTRL key is allowed.

// Delphi

cxTreeView1.MultiSelectStyle := cxTreeView1.MultiSelectStyle + [msControlSelect];

cxTreeView1.Select(cxTreeView1.Items[0], [ssCtrl]);

The second overload of the Select method selects all nodes passed as an array represented by the Nodes parameter.  Note that if the MultiSelect property value is False, the method merely moves the selection to the first node in the array.  If the MultiSelect property value is True, the behavior of the method depends on the msVisibleOnly and msSiblingOnly flags of the MultiSelectStyle property.  The first node within the array, however, is selected independently of these flags.  Note also, that the previous selection is removed from the control when calling this overload of the Select method.

The following sample code shows how the Select method can be used.  It selects all nodes residing at the second nesting level while preserving the previous selection.  To preserve the selection, all selected items are first added to the array of nodes.  They are obtained using the Selections property.

// Delphi

var

  Nodes: array of TTreeNode;

  I: Integer;

// ...

  // obtaining the previously selected nodes

  SetLength(Nodes, cxTreeView1.SelectionCount);

  for I := 0 to cxTreeView1.SelectionCount - 1 do

    Nodes[I] := cxTreeView1.Selections[I];

  // obtaining nodes residing on the second nesting level

  for I := 0 to cxTreeView1.Items.Count - 1 do

  begin

    if cxTreeView1.Items[i].Level = 1 then

    begin

      SetLength(Nodes, Length(Nodes) + 1);

      Nodes[High(Nodes)] := cxTreeView1.Items[I];

    end;

  end;

  // selecting obtained nodes

  cxTreeView1.Select(Nodes);

The third overload of the Select method is equivalent to the second but with a difference.  The accepted parameter is a TList object instead of a nodes array.  Choose the method that suits your needs more appropriately.

Please refer to the Selecting Tree View Nodes topic for more information regarding node selection.


TcxCustomTreeView.Subselect

TcxCustomTreeView          See Also

Selects the specified node.

procedure Subselect(Node: TTreeNode; Validate: Boolean = False); virtual;

Description

Use the Subselect method to select the node specified by the Node parameter.  The Validate parameter specifies whether the method must check the validity of the resulting selection.  Checking selection validity implies determining whether the selection is allowed by the msVisibleOnly and msSiblingOnly flags of the MultiSelectStyle property.  If the Validate parameter is set to True and selecting the specified node is not valid, the Subselect method performs nothing.  Otherwise the specified node is selected independently of the MultiSelectStyle property value.

See the Selecting Tree View Nodes topic for additional information about selecting nodes within the tree view control.


TcxCustomTreeView.OnAddition

TcxCustomTreeView

Fires in response to adding a node to the tree view control.

type

  TTVExpandedEvent = procedure(Sender: TObject; Node: TTreeNode) of object;

property OnAddition: TTVExpandedEvent;

Description

Handle the OnAddition event to perform specific actions each time a node is added to the tree view control.  The Sender parameter specifies the tree view control to which the node has been added.  The Node parameter represents the added node.

Handling the OnAddition event is useful, for instance, if you allow end users to add nodes to the tree view control and want to correct node settings on insert.

Note that you can load the node structure from a stream or a file.  This can be performed using the LoadFromStream and LoadFromFile methods respectively.  If using these methods, the OnAddition event fires for each loaded node.  Thus, you can handle the event to correct node settings.  This is useful since the mentioned methods allow you to load only the structure of nodes and their captions.  The OnAddition event enables you to specify any other data associated with the loaded nodes (for instance, image indexes).

Note:	Individual nodes can be added to the tree view control using methods of the TTreeNodes object available via the Items property of the control.

The sample code below handles the OnAddition event to add indexes to node captions.

// Delphi

procedure TForm1.cxTreeView4Addition(Sender: TObject; Node: TTreeNode);

var

  ParentNode: TTreeNode;

  Number: string;

begin

  ParentNode := Node;

  Number := IntToStr(Node.Index + 1);

  while ParentNode.Parent <> nil do

  begin

    ParentNode := ParentNode.Parent;

    Number := IntToStr(ParentNode.Index + 1) + '.' + Number;

  end;

  Node.Text := Number + ' - ' + Node.Text;

end;

Here is the result of code execution. Note the composite indexes of nodes:

If you need to handle node deletion, use the OnDeletion event.


TcxCustomTreeView.OnAdvancedCustomDraw

TcxCustomTreeView          See Also

Enables you to paint the tree view control (or a part of it) before or after default painting takes place.

type

  TTVAdvancedCustomDrawEvent = procedure(Sender: TCustomTreeView; const ARect: TRect; Stage: TCustomDrawStage; var DefaultDraw: Boolean) of object;

property OnAdvancedCustomDraw: TTVAdvancedCustomDrawEvent;

Description

The OnAdvancedCustomDraw event fires at different stages of control painting.  First, it fires before any default painting is performed.  Then it fires after all painting is finished.  Use the Stage parameter to determine the stage of painting.  It returns cdPrePaint if the event fires before any other painting.  If the cdPostPaint value is returned, all painting procedures have already been finished.  Note that the Stage parameter cannot return any other value listed by the TCustomDrawState enumeration.

The DefaultDraw parameter specifies whether default painting must proceed after the OnAdvancedCustomDraw event is executed.  If handling the event when the Stage parameter is cdPrePaint, setting the DefaultDraw parameter to True prohibits all further painting.  This means that control items will not be painted.  You cannot paint them manually either, since the OnCustomDrawItem and OnAdvancedCustomDrawItem events will not fire.  Thus, you need to set the DefaultDraw parameter to True only when all the desired painting is performed in the OnAdvancedCustomDraw event and no further painting is needed.

When the Stage parameter returns cdPostPaint, the DefaultDraw parameter should not be used.  No painting will take place.

Note:	Handle the OnCustomDraw event to perform only background painting (when the Stage parameter value is cdPrePaint).

The Sender parameter of the event provides access to the underlying tree view control.  Use the Canvas property of the object representing this parameter to obtain the canvas used to paint.  The bounding rectangle of the control can be obtained using the ARect parameter.

The following sample code shows how to perform painting when all default painting routines are finished.  The code handles the OnAdvancedCustomDraw event to paint a red X over the control’s client area.

// Delphi

procedure TForm1.cxTreeView1AdvancedCustomDraw(Sender: TCustomTreeView;

  const ARect: TRect; Stage: TCustomDrawStage; var DefaultDraw: Boolean);

begin

  if Stage = cdPostPaint then

  begin

    with Sender.Canvas do

    begin

      Pen.Color := clRed;

      Pen.Style := psSolid;

      Pen.Width := 3;

      MoveTo(ARect.Left, ARect.Top);

      LineTo(ARect.Right, ARect.Bottom);

      MoveTo(ARect.Left, ARect.Bottom);

      LineTo(ARect.Right, ARect.Top);

    end;

  end

end;

The result of code execution is as follows:

Important note: Use the OnAdvancedCustomDraw event to paint the foreground of the control very carefully.  When performing scrolling, the tree view control simply copies its canvas content and moves it up or down.  After movement, the OnAdvancedCustomDraw event is raised again.  If considering the example above, this can result in several red X’s painted one under another.   Note that the same effect takes place if collapsing or expanding nodes.  Other nodes can be moved as the result of the operation.  Node movement is implemented in a similar manner – the portion of the canvas’ content is copied and moved to another position.  Thus, if performing foreground painting, you need to be sure that end users are not allowed to scroll the control and expand/collapse items.


TcxCustomTreeView.OnAdvancedCustomDrawItem

TcxCustomTreeView

Enables you to paint tree view nodes before or after default painting takes place.

type

  TTVAdvancedCustomDrawItemEvent = procedure(Sender: TCustomTreeView; Node: TTreeNode; State, Stage: TCustomDrawState; TCustomDrawStage; var PaintImages, DefaultDraw: Boolean) of object;

property OnAdvancedCustomDrawItem: TTVAdvancedCustomDrawItemEvent;

Description

The OnAdvancedCustomDrawItem event fires for each individual node of the control before and after its default painting takes place.  The Stage parameter enables you to identify whether node painting is about to be performed or has been completed.

If the Stage parameter returns cdPrePaint, node painting has not been performed yet.  In this instance, you may perform your own painting of the processed node and set the DefaultDraw parameter to False.  This value for the DefaultDraw parameter implies that default painting of the processed node will not be performed.  Note that if you only need to perform painting before the default drawing routine is executed, you should handle the OnCustomDrawItem event instead.

If the Stage parameter returns cdPostPaint, node painting has already been completed.  At this time, you may perform any additional painting.  For instance, you can paint a stop sign over the node’s image.  Note that the DefaultDraw parameter is not in effect when the Stage parameter value is cdPostPaint.  The reason is that no other painting will take place.

The Sender parameter of the event specifies the control whose item is being painted.  Use the Canvas property of the object representing this parameter to obtain the canvas used to paint.  The Node parameter enables you to determine the currently processed node.  Use it to obtain the bounding rectangle of the node (the DisplayRect method) and other information needed when painting (caption text, image indexes, etc).  The State parameter can be used to determine the state of the painted node.  cdsSelected cdsHot included into this parameter’s value indicate that the node is selected or hot-tracked respectively.  (Note that node hot-tracking is only available when the HotTrack property is set to True).  And finally, the PaintImages parameter specifies whether node images should be painted by the default painting procedure.  This parameter value is not in effect if the DefaultDraw parameter is set to False, since no default painting is performed in this instance.

The code below shows you how to use the OnAdvancedCustomDrawItem event for additional painting after the default procedure has been completed.  The handler will strike out node captions residing at the third nesting level.  Note that the color of the strike line will be different for selected and unselected nodes.

// Delphi

procedure TForm1.cxTreeView4AdvancedCustomDrawItem(Sender: TCustomTreeView;

  Node: TTreeNode; State: TCustomDrawState; Stage: TCustomDrawStage;

  var PaintImages, DefaultDraw: Boolean);

var ARect: TRect;

begin

  if (Stage = cdPostPaint) and (Node.Level = 2) then

  begin

    ARect := Node.DisplayRect(True);

    with Sender.Canvas do

    begin

      Pen.Color := clRed;

      if cdsSelected in State then

        Pen.Color := clWhite;

      Pen.Style := psSolid;

      Pen.Width := 2;

      MoveTo(ARect.Left, ARect.Top + (ARect.Bottom - ARect.Top) div 2);

      LineTo(ARect.Right, ARect.Top + (ARect.Bottom - ARect.Top) div 2);

    end;

  end;

end;

Here is the result of code execution:

If you need to paint the background or foreground of the control, use the OnCustomDraw and OnAdvancedCustomDraw events.


TcxCustomTreeView.OnCancelEdit

TcxCustomTreeView          See Also

Fires when node caption editing is cancelled.

type

  TTVChangedEvent = procedure(Sender: TObject; Node: TTreeNode) of object;

property OnCancelEdit: TTVChangedEvent;

Description

Handle the OnCancelEdit event to perform specific actions each time node caption editing is finished without saving the changes made.  The Sender parameter specifies the control whose node has been edited.  The Node parameter allows you to obtain the node.

Note that the OnCancelEdit event fires after editing is finished.  Thus, you cannot obtain the text that the user entered before canceling changes.

Please refer to the Allowing End Users to Edit Tree Node Captions topic for more information on how to invoke, finish and cancel node editing.  The topic also contains an example of handling the OnCancelEdit event.


TcxCustomTreeView.OnChange

TcxCustomTreeView          See Also

Fires after a tree view node has been selected.

type

  TTVChangedEvent = procedure(Sender: TObject; Node: TTreeNode) of object;

property OnChange: TTVChangedEvent;

Description

Write an OnChange event handler to perform specific actions after a node has been selected.  The Sender parameter identifies the control whose node has been selected.  The Node parameter returns the node.

Please refer to the Selecting Tree View Nodes topic for details on selecting nodes and handling the appropriate events.


TcxCustomTreeView.OnChanging

TcxCustomTreeView          See Also

Allows you to prohibit node selection.

type

  TTVChangingEvent = procedure(Sender: TObject; Node: TTreeNode; var AllowChange: Boolean) of object;

property OnChanging: TTVChangingEvent;

Description

The OnChanging event fires each time an attempt to select a node takes place.  The Sender parameter identifies the tree view control whose node is about to be selected.  The Node parameter represents the node.  The AllowChange parameter specifies whether node selection is allowed.  Set this parameter to False to prohibit node selection.

Handle the OnChanging event to specify a condition for selecting nodes.  Note that if the OnChanging event handler prohibits specific node selection, you cannot navigate to that node using the keyboard.

Please refer to the Selecting Tree View Nodes topic for more information on selecting nodes.


TcxCustomTreeView.OnCollapsed

TcxCustomTreeView          See Also

Fires immediately after a tree node has been collapsed.

type

  TTVExpandedEvent = procedure(Sender: TObject; Node: TTreeNode) of object;

property OnCollapsed: TTVExpandedEvent;

Description

The OnCollapsed event fires in response to collapsing nodes.  The Sender parameter identifies the control whose node has been collapsed.  The Node parameter returns the collapsed node.

You can also handle the OnCollapsing event to specify whether nodes can be collapsed.  If you need to control node expansion, handle the OnExpanding and OnExpanded events.

The following sample code is used to change the node icon when the node is expanded or collapsed.  When the node is collapsed, a closed folder image is displayed within it.  Otherwise, the opened folder image is displayed.  Note that the desired images must reside within the image list specified by the Images property of the control to make this possible.  Please refer to the Displaying Images within Tree Nodes topic for details on specifying node images.

// Delphi

procedure TForm1.cxTreeView1Collapsed(Sender: TObject; Node: TTreeNode);

begin

  if Node.ImageIndex = 1 then

    Node.ImageIndex := 6

  else

    Node.ImageIndex := 1;

end;

Note: the handler above must also be assigned to both the OnCollapsed and OnExpanded events.

The image below shows the possible appearance of the tree view if handling the OnCollapsed and OnExpanded events in this manner.  Note that opened folder images are displayed only within expanded nodes.

Please refer to the Expanding and Collapsing Tree View Nodes topic for more information about expanding and collapsing nodes.


TcxCustomTreeView.OnCollapsing

TcxCustomTreeView          See Also

Enables you to prohibit node collapse.

type

  TTVCollapsingEvent = procedure(Sender: TObject; Node: TTreeNode; var AllowCollapse: Boolean) of object;

property OnCollapsing: TTVCollapsingEvent;

Description

The OnCollapsing event is raised each time an attempt to collapse a node is made.  The Sender parameter returns the tree view control whose node is about to be collapsed.  The Node parameter identifies the node.  The AllowCollapse parameter specifies whether the node can be collapsed.  Set this parameter to False to prohibit node collapse.  This parameter is True by default.  If it is left unchanged, the node is collapsed.

If you simply need to perform specific actions each time a node is collapsed, handle the OnCollapsed event.  To control node expansion, the OnExpanding and OnExpanded events should be used.

The following sample code demonstrates a simple handler for the OnCollapsing event.  This handler sets the AllowCollapse property to True to prohibit collapse of all nodes.  This can be used if you want to make all nodes visible and prevent the end user from collapsing parents.

// Delphi

procedure TForm1.cxTreeView1Collapsing(Sender: TObject; Node: TTreeNode;

  var AllowCollapse: Boolean);

begin

  AllowCollapse := False;

end;

Please refer to the Expanding and Collapsing Tree View Nodes topic for more information on collapsing and expanding nodes.


TcxCustomTreeView.OnCompare

TcxCustomTreeView          See Also

Fires when the sorting process compares two nodes.

type

  TTVCompareEvent = procedure(Sender: TObject; Node1, Node2: TTreeNode; Data: Integer; var Compare: Integer) of object;

property OnCompare: TTVCompareEvent;

Description

You can force node sorting by calling the AlphaSort method of the control.  You can also force the control to resort the tree automatically each time the Text or Data property of a node is changed.  Set the SortType property to the appropriate value for this purpose.

By default, the control sorts nodes alphabetically by their captions.  However, if a handler for the OnCompare event is written, the control uses the handler to compare nodes.  Thus, you may implement any required sorting logic.

The Sender parameter of the event is the control whose nodes are sorted.  The Node1 and Node2 parameters identify the nodes to be compared.  Use their properties to determine which of them should reside first within the sorted list.  The comparison result must to specified using the Compare parameter.  The table below explains what values must be assigned to it.

Value	Meaning
Negative	Node1 is less than Node2.  This means that the node specified by the Node1 parameter will reside above the node specified by the Node2 parameter.
0	Node1 is equal to Node2.
Positive	Node1 is greater than Node2.  This means that the node specified by the Node1 parameter will reside below the node specified by the Node2 parameter.

The sample code below handles the OnCompare event to custom sort nodes.  Nodes are sorted by captions in alphabetical order but nodes that have children are placed to the top of the list.

// Delphi

procedure TForm1.cxTreeView1Compare(Sender: TObject; Node1,

  Node2: TTreeNode; Data: Integer; var Compare: Integer);

begin

  if Node1.HasChildren = Node2.HasChildren then

    Compare := CompareStr(Node1.Text, Node2.Text)

  else

  begin

    if Node1.HasChildren then

      Compare := -1

    else

      Compare := 1;

  end;

end;


TcxCustomTreeView.OnCreateNodeClass

TcxCustomTreeView

Enables you to supply custom node types to the tree view control.

type

  TTVCreateNodeClassEvent = procedure(Sender: TCustomTreeView; var NodeClass: TTreeNodeClass) of object;

property OnCreateNodeClass: TTVCreateNodeClassEvent;

Description

The OnCreateNodeClass event fires before a node is added to the control.  It is raised when calling the Add method of the TTreeNodes class representing the control’s Items property.  You can handle this event to specify the type of the that will represent the added node.  The type must be a TTreeNode descendant.

The Sender parameter of the event specifies the control to which a node is about to be added.  The node class to be added must be assigned to the NodeClass parameter of the event.

Handle the OnCreateNodeClass event if you need additional node settings as compared to the TTreeNode class.  For instance, you may want to specify different font style for each node and use them when handling the OnCustomDrawItem event.


TcxCustomTreeView.OnCustomDraw

TcxCustomTreeView          See Also

Allows you to custom pain a tree view control.

type

  TTVCustomDrawEvent = procedure(Sender: TCustomTreeView; const ARect: TRect; var DefaultDraw: Boolean) of object;

property OnCustomDraw: TTVCustomDrawEvent;

Description

The OnCustomDraw event occurs each time the control needs to be repainted, but before the default painting is made.  The Sender parameter specifies the control that is painted.  Use the Canvas property of the object representing it to obtain the canvas used to paint.  The ARect parameter returns the bounding rectangle of the control so that you know where to paint.

The DefaultDraw parameter of the event specifies whether further painting must be performed by the control.  Set this parameter to False if all desired painting is performed within the OnCustomDraw event handler.  In this instance, the control will not paint nodes.  The OnCustomDrawItem and OnAdvancedCustomDrawItem events will not be raised either.  If you only need to custom paint the control’s background, set the DefaultDraw parameter to True.

Note that you can also custom paint the control’s foreground.  Please refer to the OnAdvancedCustomDraw event description for details on how to achieve this.

The following sample code handles the OnCustomDraw event to fill the background of the tree view with a texture.  The DefaultDraw parameter is not set to False to allow node painting.

// Delphi

procedure TForm1.cxTreeView1CustomDraw(Sender: TCustomTreeView;

  const ARect: TRect; var DefaultDraw: Boolean);

var

  TextureBrush: HBRUSH;

  Bitmap: TBitmap;

begin

  Bitmap := TBitmap.Create;

  Bitmap.LoadFromFile('c:\texture.bmp');

  TextureBrush := CreatePatternBrush(Bitmap.Handle);

  FillRect(Sender.Canvas.Handle, ARect, TextureBrush);

  SetBkMode(Sender.Canvas.Handle, TRANSPARENT);

end;

Here is the result of code execution.


TcxCustomTreeView.OnCustomDrawItem

TcxCustomTreeView

Enables you to custom paint nodes.

type

  TTVCustomDrawItemEvent = procedure(Sender: TCustomTreeView; Node: TTreeNode; State: TCustomDrawState; var DefaultDraw: Boolean) of object;

property OnCustomDrawItem: TTVCustomDrawItemEvent;

Description

The OnCustomDrawItem event fires each time a node is about to be painted.  You can handle this event to perform your own tree node painting.  If the desired painting has been performed, set the DefaultDraw parameter to False to indicate that default painting is not needed for the processed node.

The Sender parameter specifies the control whose node is presently painted.  Use the object’s Canvas property representing this parameter value to obtain the canvas used to paint.  The Node parameter identifies the node being processed.  Use the DisplayRect method of the TTreeNode object representing this parameter value to obtain the bounding rectangle of the node.  The State parameter enables you to determine the painted node’s current state.  cdsSelected and cdsHot values included into this parameter’s value indicate that the node is selected or hot-tracked respectively.  (Note that node hot-tracking is only available when the HotTrack property is set to True).

You can also use the OnAdvancedCustomDrawItem event to perform custom tree node painting.  This event should be used in the following instances:

•	You need to perform painting after the default painting has been performed;

•	You want to suppress only painting of node images.  The event provides a specially designed parameter for this purpose.

The following sample code provides an example of handling the OnCustomDrawItem event.  Opened and closed book images are painted within expanded and collapsed nodes respectively (they are painted in the place of expand buttons and have the same functionality).  The caption of the selected node is painted red.  Other nodes are painted using black.

// Delphi

procedure TForm1.cxTreeView1CustomDrawItem(Sender: TCustomTreeView;

  Node: TTreeNode; State: TCustomDrawState; var DefaultDraw: Boolean);

var

  ImageRect: TRect;

  RealImageWidth: Integer;

  NodeImage: TBitmap;

begin

  if cdsSelected in State then

    Sender.Canvas.Font.Color := clRed

  else

    Sender.Canvas.Font.Color := clBlack;

  SetBkMode(Sender.Canvas.Handle, TRANSPARENT);

  Sender.Canvas.TextOut(Node.DisplayRect(True).Left, Node.DisplayRect(True).Top, Node.Text);

  if Node.HasChildren then

  begin

    ImageRect := Node.DisplayRect(False);

    ImageRect.Right := Node.DisplayRect(True).Left;

    RealImageWidth := (ImageRect.Right - ImageRect.Left) div (Node.Level + 1);

    ImageRect.Left := ImageRect.Right - RealImageWidth;

    NodeImage := TBitmap.Create;

    if Node.Expanded then

      NodeImage.LoadFromFile('c:\expanded.bmp')

    else

      NodeImage.LoadFromFile('c:\collapsed.bmp');

    Sender.Canvas.Draw(ImageRect.Left, ImageRect.Top, NodeImage);

  end;

  DefaultDraw := False;

end;

The following is the result of code execution.


TcxCustomTreeView.OnDeletion

TcxCustomTreeView          See Also

Fires when a tree node is about to be deleted.

type

  TTVExpandedEvent = procedure(Sender: TObject; Node: TTreeNode) of object;

property OnDeletion: TTVExpandedEvent;

Description

Write a handler for the OnDeletion event to perform specific actions each time a node is deleted from the tree view.  The Sender parameter specifies the control whose node is about to be deleted.  The node can be obtained via the Node parameter.

If you need to respond to tree view node addition, handle the OnAddition event.

Nodes can be added or removed from the tree view using TTreeNodes object methods representing the Items property.


TcxCustomTreeView.OnEdited

TcxCustomTreeView          See Also

Enables you to correct node caption after it has been edited by an end-user.

type

  TTVEditedEvent = procedure(Sender: TObject; Node: TTreeNode; var S: string) of object;

property OnEdited: TTVEditedEvent;

Description

The OnEdited event fires immediately after the user has finished node caption editing.  The Sender parameter identifies the control whose node caption has been modified.  The node can be obtained via the Node parameter.  The S parameter returns the new node caption.  You can assign a new value to this parameter if you need to correct the value entered by end users.  For instance, you may want to prohibit specifying empty strings as node captions.

If you need to respond to the start or cancellation of node caption editing, handle the OnEditing and OnCancelEdit events respectively.

Please refer to the Allowing End Users to Edit Tree Node Captions topic for details on how to invoke, finish and cancel node caption editing.  The topic also contains an example of handling the OnEdited event.


TcxCustomTreeView.OnEditing

TcxCustomTreeView          See Also

Enables you to cancel node caption editing.

type

  TTVEditingEvent = procedure(Sender: TObject; Node: TTreeNode; var AllowEdit: Boolean) of object;

property OnEditing: TTVEditingEvent;

Description

The OnEditing event fires each time a node is switched to editing mode.  The Sender parameter identifies the control whose node is about to be edited.  The Node parameter returns the node.  The AllowEdit parameter specifies whether the operation is allowed.  Set this parameter to False to prohibit node editing.  This parameter’s value is True by default and if left unchanged, node editing starts after the event handler has been executed.

Use the OnEditing event if you need prohibit specific node editing.  This event can also be handled if you need to perform specific actions each time node editing begins - for instance, you may display an explanatory message within the status bar.

To respond to the completion or cancellation of node caption editing, handle the OnEdited and OnCancelEdit events respectively.

For more information on how to start, finish and cancel node caption editing, please refer to the Allowing End Users to Edit Tree Node Captions topic.  This topic also contains an example of handling the OnEditing event.


TcxCustomTreeView.OnExpanded

TcxCustomTreeView          See Also

Fires immediately after a tree node has been expanded.

type

  TTVExpandedEvent = procedure(Sender: TObject; Node: TTreeNode) of object;

property OnExpanded: TTVExpandedEvent;

Description

Write an OnExpanded event handler to perform specific actions each time a node has been expanded.  The Sender parameter identifies the control whose node has been affected.  The node is returned by the Node parameter.

You can also handle the OnExpanding event to specify whether each individual node can be expanded.  To respond to node collapse, handle the OnCollapsing and OnCollapsed events.

Please refer to the Expanding and Collapsing Tree View Nodes topic for information on how nodes can be expanded and collapsed either by end users or via code.


TcxCustomTreeView.OnExpanding

TcxCustomTreeView          See Also

Enables you to prohibit node expansion.

type

  TTVExpandingEvent = procedure(Sender: TObject; Node: TTreeNode; var AllowExpansion: Boolean) of object;

property OnExpanding: TTVExpandingEvent;

Description

The OnExpanding event fires each time a node is about to be expanded.  You can identify the node and its owning control via the Node and Sender parameters.  The AllowExpansion parameter specifies whether expansion is allowed.  If it is set to True, the processed node is expanded immediately after event handler execution has been finished.  Set the parameter to False, to prohibit node expansion.

See the Expanding and Collapsing Tree View Nodes topic for more information about expanding and collapsing tree nodes.


TcxCustomTreeView.OnGetImageIndex

TcxCustomTreeView          See Also

Enables you to assign images to tree view nodes.

type

  TTVExpandedEvent = procedure(Sender: TObject; Node: TTreeNode) of object;

property OnGetImageIndex: TTVExpandedEvent;

Description

The OnGetImageIndex event fires to obtain the image displayed within an unselected node.  The image must be assigned to the ImageIndex property of the TTreeNode object passed as the Node parameter.  The Sender parameter identifies the control whose node is being processed.

The OnGetImageIndex event fires for each node at application startup so that you can specify appropriate images for your nodes.  Also, the event fires when the expanded state of nodes is changed.

The sample code below is an example of handling the OnGetImageIndex event.  The handler assigns opened folder images to expanded nodes and closed folder images to collapsed ones.  Note that this code will work only if opened and closed folder images are loaded to the image list specified by the Images property of the control.  These images must reside at 0 and 1 positions within the list.

// Delphi

procedure TForm1.TreeView1GetImageIndex(Sender: TObject; Node: TTreeNode);

begin

  if not Node.HasChildren then

    Node.ImageIndex := -1

  else

    if Node.Expanded then

      Node.ImageIndex := 1

    else

      Node.ImageIndex := 0;

end;

Here is the result of code execution:

Note:	The OnGetImageIndex event doesn’t fire for nodes that have an ImageIndex property set to a value different than –1.

Please refer to the Displaying Images within Tree View Nodes topic for details on specifying images displayed within nodes.


TcxCustomTreeView.OnGetSelectedIndex

TcxCustomTreeView

Enables you to specify the image for the currently selected node.

type

  TTVExpandedEvent = procedure(Sender: TObject; Node: TTreeNode) of object;

property OnGetSelectedIndex: TTVExpandedEvent;

Description

The OnGetSelectedIndex event fires to obtain the image to be displayed within selected nodes.  The image to display must be assigned to the SelectedIndex property of the TTreeNode object passed as the Node parameter.  The control whose node is processed can be obtained using the Sender parameter.

Handling the OnGetSelectedIndex event is similar to handling the OnGetImageIndex event.  Please refer to the description of the latter for an example of its usage.  Also, see the Displaying Images within Tree View Nodes topic for more information about assigning images to nodes.


TcxTreeView
TcxTreeView Object

Hierarchy          Properties          Methods          Events

Represents the tree view control.

Unit

cxTreeView

TcxTreeView = class(TcxCustomTreeView)

Description

Tree view controls are used to display information arranged in hierarchical structures.  Data is displayed by means of nodes that can be represented by text labels together with images.  Each node can have a set of child nodes, which can have their own children, etc.  This forms the tree structure.

The primary features introduced by cxTreeView are:

Changing the expanded state of nodes to show or hide their children.  See the Expanding and Collapsing Tree View Nodes topic for details;

Selecting individual or multiple nodes.  Refer to the Selecting Tree View Nodes topic for more information on this feature;

Allowing end users to edit node captions at runtime.  This feature is covered in the Allowing End Users to Edit Tree Node Captions topic;

Custom painting nodes or the entire control.  Please refer to the OnCustomDraw and OnCustomDrawItem event descriptions for details;

In addition, what differentiates the TcxTreeView control from the standard TTreeView control is advanced style support (the same style support provided by the ExpressQuantumGrid and Editors Library).  It is implemented via the Style, StyleDisabled, StyleFocused and StyleHot properties of the control.  Using this property, you can customize the style applied to elements of the control, change its look and feel and apply XP theme painting, if supported.

All the functionality provided by the TcxTreeView control is implemented by its ancestor – the TcxCustomTreeView class.  The TcxTreeView class simply publishes certain properties and events.


TcxTreeView Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomTreeView

     |


Properties for TcxTreeView
TcxTreeView Properties

TcxTreeView          Legend

Derived from TcxCustomTreeView

AutoExpand

ChangeDelay

DropTarget

HideSelection

HotTrack

Images

Indent

Items

ItemHeight

MultiSelect

MultiSelectStyle

ReadOnly

RightClickSelect

RowSelect

Selected

SelectionCount

Selections

ShowButtons

ShowLines

ShowRoot

SortType

StateImages

ToolTips

TopItem

Derived from TcxContainer

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

Derived from TControl

Align


Methods for TcxTreeView
TcxTreeView Methods

TcxTreeView          Legend

Derived from TcxCustomTreeView

 ClearSelection

 CustomSort

 Deselect

 FindNextToSelect

 FullCollapse

 FullExpand

 GetHitTestInfoAt

 GetNodeAt

 IsEditing

 LoadFromFile

 LoadFromStream

 SaveToFile

 SaveToStream

 Select

 Subselect

Derived from TcxControl

 Create

 Destroy

 InvalidateRect


Events for TcxTreeView
TcxTreeView Events

TcxTreeView          Legend

Derived from TcxCustomTreeView

 OnAddition

 OnAdvancedCustomDraw

 OnAdvancedCustomDrawItem

 OnCancelEdit

 OnChange

 OnChanging

 OnCollapsed

 OnCollapsing

 OnCompare

 OnCustomDraw

 OnCustomDrawItem

 OnDeletion

 OnEdited

 OnEditing

 OnExpanded

 OnExpanding


Expanding and Collapsing Tree View Nodes

There are numerous ways of expanding and collapsing nodes in the tree view.  The following tables summarize them and explain the methods which you can use to control each of them:

	Functionality
	Expand a single node	Expand a node and its subnodes (all child nodes).	Expand all parent nodes within a tree view
How to implement it in code	1) Set the specified node’s Expanded property to True. 2) Call the Expand procedure for the specified node with the Recurse parameter set to False.	Call the Expand procedure for the specified node with the Recurse parameter set to True.	Call the tree view’s FullExpand procedure.
Availability for an end user	An end user can expand a collapsed node by double clicking it, clicking the associated expand button or pressing the right arrow key.  The latter requires the node to be selected.
Methods used to control functionality	at design time	Hide all the expand/minus buttons by setting the ShowButtons property to False.
	at run time	1) Hide all the expand/minus buttons by setting the ShowButtons property to False. 2) Set the AllowExpansion parameter of the OnExpanding event handler to False. 3) Handle the OnExpanded event to collapse the expanded node.
	Functionality
	Collapse a single node	Collapse a node and its subnodes (all child nodes).	Collapse all parent nodes within a tree view
How to implement it in code	1) Set the specified node’s Expanded property to False. 2) Call the Collapse procedure for the specified node with the Recurse parameter set to False.	Call the Collapse procedure for the specified node with the Recurse parameter set to True.	Call the tree view’s FullCollapse procedure.
Availability for an end user	An end user can collapse an expanded node by double clicking it, clicking the minus button or pressing the left arrow key.  The latter requires the node to be selected.
Methods used to control functionality	at design time	Hide all the expand/minus buttons by setting the ShowButtons property to False.
	at run time	1) Hide all the expand/minus buttons by setting the ShowButtons property to False. 2) Set the AllowCollapse parameter of the OnCollapsing event handler to False. 3) Handle the OnCollapsed event to expand the collapsed node.


Selecting Tree View Nodes


Displaying Images within Tree View Nodes

By default (if the tree view is not custom painted) two images can be displayed within each node.

If you need a single image to be displayed within nodes, you first need to create the image source and then assign them to nodes in the desired manner.  The image source is specified by the Images property of the tree view control.  Assign an image list (the TImageList component) containing the desired images to this property.  Images can be associated with nodes using the nodes’ ImageIndex and SelectedIndex properties.  These properties specify images that will be displayed within the node when it is in its normal state and selected respectively.  Note that images are specified by indexes in the source collection.

There are three methods to specify values of the ImageIndex and SelectedIndex properties.  The first is to use the TreeView Items Editor dialog.  This dialog can be invoked by clicking the ellipsis button corresponding to the Items property of the control.

Use the edit boxes corresponding to the Image Index and Selected Index properties to specify image indexes.  The edit box corresponding to the State Index property is used to assign a second image to a node (discussed below).

At runtime, you can choose two ways of specifying images.  The first is to assign desired values to the ImageIndex and SelectedIndex properties directly.  If, however, you have a common logic for node image assignment, it is most appropriate to use the OnGetImageIndex and OnGetSelectedIndex events.  These events fire each time an image must be obtained for the node (when the application starts, when the expanded state of a node is changed and when a node is selected).

Note that you can also use overlay images.  These are the images displayed over the ones specified by methods described above.  Displaying such images is useful, for instance, if you need a red X over node images that are no longer available.  Use the OverlayIndex node property to specify its overlay image.

You can also display additional images within nodes.  The source of these images is specified by the StateImages property of the control.  Images are associated with nodes using the nodes’ StateIndex property.  Please refer to the StateImages property description for an example of using additional images within nodes to imitate check boxes.

Note that you can custom paint nodes or the entire tree view.  In this instance, you are free to display anything you like within nodes.  Please refer to the OnCustomDraw, OnAdvancedCustomDraw, OnCustomDrawItem and OnAdvancedCustomDrawItem event descriptions for details.


Saving and Restoring Tree Nodes Structure

The TcxTreeView control offers you two pairs of methods that can be used to save and restore node structures.  These are the SaveToFile, LoadFromFile, SaveToStream and LoadFromStream methods.

The SaveToFile and LoadFromFile methods are used to save node structures to a text file and restore it when necessary.  This can be used to store node structures between application runs or to load data saved by an external application to the tree view control.

The files produced by the SaveToFile method (and that can be accepted by the LoadFromFile method) contain node captions one per line.  Child items are indented using either spaces or tabs (an extra space or tab increases the level of the node by one).  The images below show samples of files produced by the SaveToFile method and the appearance of the corresponding control.

Note:	If the structure of the source text file cannot be recognized by the LoadFromFile method, an exception is raised.

Note that text files produced by the SaveToFile method contain only node captions.  If you need to specify additional information for nodes loaded from a file, you need to handle specific events.  For instance, the OnAddition event fires for each individual node when loading data using the LoadFromFile method.  Thus, you can handle the event to initialize all required node properties.  You can also access nodes directly via the Items property immediately after a LoadFromFile method call.

The sample code below describes how to load nodes into the tree view at form loading and save them into the same file when the form is closed.  The OnCreate and OnClose events of the form are handled for this purpose.

// Delphi

procedure TForm1.FormCreate(Sender: TObject);

begin

    cxTreeView1.LoadFromFile('c:\TreeView.txt');

end;

procedure TForm1.FormClose(Sender: TObject; var Action: TCloseAction);

begin

  cxTreeView1.SaveToFile('c:\TreeView.txt');

end;

For an example of using the OnAddition event when loading data from a file, see the event’s description.

The SaveToStream and LoadFromStream methods can be used to save node structures to a stream and restore it when needed.  This method pair is likely to be used when you don’t need to use the saved data between application runs.  However, you can achieve the same effect as when using the SaveToFile and LoadFromFile methods if using a TFileStream object as the parameter of the SaveToStream and LoadFromStream methods.

Note:	Descriptions of the SaveToFile and LoadFromFile methods also apply to the SaveToStream and LoadFromStream methods.

The following sample code describes how to use the SaveToStream and LoadFromStream methods.  The first is used to store the structure of nodes at application startup.  The latter is called when it is needed to restore the original structure of the tree view.  As implemented in the example, it is called from a button click handler.

// Delphi

var

  Nodes: TMemoryStream;

procedure TForm1.FormCreate(Sender: TObject);

begin

  Nodes := TMemoryStream.Create;

  cxTreeView1.SaveToStream(Nodes);

end;

procedure TForm1.btnRestoreClick(Sender: TObject);

begin

  // restoring the initial position of the stream

  Nodes.Position := 0;

  cxTreeView1.LoadFromStream(Nodes);

end;


Allowing End Users to Edit Tree Node Captions

If the ReadOnly property is set to False, end users are allowed to edit node captions.  By default, they can initiate node caption editing by clicking the selected node.  Editing can be stopped by pressing the ENTER key or clicking outside of the edited label.

You can also start and finish label editing via code.  The TreeView_EditLabel and TreeView_EndEditLabelNow procedures can be used for this purpose.  Note that if the second parameter of the TreeView_EndEditLabelNow procedure is True, editing is completed without saving changes made.  Please refer to the Windows SDK help system for details on these procedures.

The above mentioned procedures can be used to allow end users to start and finish editing by other means than the default.  For instance, the IsEditing method description contains an example of using these methods to start, finish and cancel editing using the F2 and ESC keys.  The IsEditing method itself enables you to identify whether a node caption is being edited at present moment.

The TcxTreeView control provides three events that enable you to control node caption editing.  The OnEditing event fires each time a node’s caption is about to be edited.  You can handle this event to prohibit caption editing for specific nodes.  The OnEdited event fires when node editing is finished and changes are saved.  You can handle it to correct the newly entered value.  Finally, the control provides an OnCancelEdit event that fires if editing has been finished without saving changes.

The sample code below provides an example of handling the mentioned events.  The OnEditing event prohibits caption editing of root level nodes.  If editing is allowed, it displays an explanatory message within the status bar.  The OnEdited event removes the message from the status bar and changes the node caption to ‘none’ if an empty string has been entered.  Finally, the OnCancelEdit event is handled to clear the status bar.  (Note that you need a status bar with at least one panel created for this sample code to work.)

// Delphi

procedure TForm1.cxTreeView1Editing(Sender: TObject; Node: TTreeNode;

  var AllowEdit: Boolean);

begin

  if Node.Level = 0 then

    AllowEdit := False

  else

    StatusBar1.Panels[0].Text := 'Type in the new node caption';

end;

procedure TForm1.cxTreeView1Edited(Sender: TObject; Node: TTreeNode;

  var S: String);

begin

  if S = '' then S := 'none';

  StatusBar1.Panels[0].Text := '';

end;

procedure TForm1.cxTreeView1CancelEdit(Sender: TObject; Node: TTreeNode);

begin

  StatusBar1.Panels[0].Text := '';

end;


Resource Strings

Strings displayed in various message boxes, dialogs and control elements of Express products are stored as resources.  This allows you to easily substitute them with custom strings depending on your needs (for instance, for localization purposes).

To replace the default value of a specific resource string during program execution, use the cxSetResourceString procedure.  This procedure works together with the cxGetResourceString function used by Express Controls.  When controls need a specific string to display, they call the cxGetResourceString function, which returns either the overridden string or the default one (if the string was not overridden).

Resource strings are declared in separate files for individual Express Products.  Use the link below to get information on resource strings available for the ExpressEditors library.  These sections provide resource string identifiers (required by cxSetResourceString) and default values:

Express Editors: Resource Strings

Example

A date editor displays the Clear button in its dropdown.  The button’s string is addressed by the cxSDatePopupClear identifier.  The following code substitutes the caption of the button with its German equivalent:

//Delphi

cxSetResourceString(@cxSDatePopupClear, 'Löschen');

//C++ Builder

cxSetResourceString(&_cxSDatePopupClear, "Löschen");

This code changes the caption of the Clear button for all date editors in the current application.


Express Editors: Resource Strings

See Also

This section describes the resource strings used by the ExpressEditors in message boxes and control elements.  Refer to the Resource Strings topic for general information on these strings.  It shows how to override the default values of resource strings at runtime.

The resource strings used by the ExpressEditors are declared in the cxEditConsts unit.

Resource identifier	Value	Description
cxSBlobButtonCancel	'&Cancel'	The caption of the button to discard changes and close the dropdown window of a BLOB editor. This caption is used when the editor’s Properties.ReadOnly property is False.
cxSBlobButtonClose	'&Close'	The caption of the button to close the dropdown window of a BLOB editor. This caption is used when the editor’s Properties.ReadOnly property is True.
cxSBlobButtonOK	'&OK'	The caption of the Ok button displayed within the dropdown window of a BLOB editor.
cxSBlobMemo	'(MEMO)'	The text displayed in the edit box of a non-empty BLOB editor if its Properties.BlobEditKind property is set to bekMemo and Properties.BlobPaintStyle is set to bpsDefault.
cxSBlobMemoEmpty	'(memo)'	The text displayed in the edit box of an empty BLOB editor if its Properties.BlobEditKind property is set to bekMemo and Properties.BlobPaintStyle is set to bpsDefault.
cxSBlobPicture	'(PICTURE)'	The text displayed in the edit box of a non-empty BLOB editor if its Properties.BlobEditKind property is set to bekPict and Properties.BlobPaintStyle is set to bpsDefault.
cxSBlobPictureEmpty	'(picture)'	The text displayed in the edit box of an empty BLOB editor if its Properties.BlobEditKind property is set to bekPict and Properties.BlobPaintStyle is set to bpsDefault.
cxSDateBOM	'bom'	An acronym for ‘Begin Of Month’. Allows you to quickly enter the date corresponding to the first day of the current month by typing this string in a date editor.  The string is recognized by the date editor if its Properties.InputKind is set to ikStandard or ikRegExpr. See the Using the SmartTextToDate Function topic for more information.
cxSDateEOM	'eom'	An acronym for ‘End Of Month’. Allows you to quickly enter the date corresponding to the last day of the current month by typing this string in a date editor.  The string is recognized by the date editor if its Properties.InputKind is set to ikStandard or ikRegExpr. See the Using the SmartTextToDate Function topic for more information.
cxSDateError	'Invalid Date'	Represents a string displayed in the message box when a display text cannot be converted to a date value.
cxSDateFifth	'fifth'	Allows you to quickly enter the fifth day of the current week using a date editor. The date editor recognizes the string if its Properties.InputKind is set to ikStandard or ikRegExpr. See the Using the SmartTextToDate Function topic for more information.
cxSDateFirst	'first'	Allows you to quickly enter the first day of the current week using a date editor. The date editor recognizes the string if its Properties.InputKind is set to ikStandard or ikRegExpr. See the Using the SmartTextToDate Function topic for more information.
cxSDateFourth	'fourth'	Allows you to quickly enter the fourth day of the current week using a date editor. The date editor recognizes the string if its Properties.InputKind is set to ikStandard or ikRegExpr. See the Using the SmartTextToDate Function topic for more information.
cxSDateFriday	'Friday'	Applied to date editors. The string allows you to quickly enter the date corresponding to next Friday. A date editor recognizes the string if its Properties.InputKind is set to ikStandard or ikRegExpr. See the Using the SmartTextToDate Function topic for more information.
cxSDateMonday	'Monday'	Applied to date editors. The string allows you to quickly enter the date corresponding to next Monday. A date editor recognizes the string if its Properties.InputKind is set to ikStandard or ikRegExpr. See the Using the SmartTextToDate Function topic for more information.
cxSDateNow	'now'	Applied to date editors. The string allows you to quickly enter the current date including the current time. A date editor recognizes the string if its Properties.InputKind is set to ikStandard or ikRegExpr. See the Using the SmartTextToDate Function topic for more information.
cxSDatePopupClear	'Clear'	The caption of the Clear button in the dropdown of a date editor.  See the date editor’s Properties.DateButtons property to determine visibility of the button.
cxSDatePopupToday	'Today'	The caption of the Today button in the dropdown of a date editor.  See the date editor’s Properties.DateButtons property to determine the button’s visibility.
cxSDateSaturday	'Saturday'	Applied to date editors. The string allows you to quickly enter the date corresponding to next Saturday. A date editor recognizes the string if its Properties.InputKind is set to ikStandard or ikRegExpr. See the Using the SmartTextToDate Function topic for more information.
cxSDateSecond	'second'	Allows you to quickly enter the second day of the current week using a date editor. The date editor recognizes the string if its Properties.InputKind is set to ikStandard or ikRegExpr. See the Using the SmartTextToDate Function topic for more information.
cxSDateSeventh	'seventh'	Allows you to quickly enter the seventh day of the current week using a date editor. The date editor recognizes the string if its Properties.InputKind is set to ikStandard or ikRegExpr. See the Using the SmartTextToDate Function topic for more information.
cxSDateSixth	'sixth'	Allows you to quickly enter the sixth day of the current week using a date editor. The date editor recognizes the string if its Properties.InputKind is set to ikStandard or ikRegExpr. See the Using the SmartTextToDate Function topic for more information.
cxSDateSunday	'Sunday'	Applied to date editors. The string allows you to quickly enter the date corresponding to next Sunday. A date editor recognizes the string if its Properties.InputKind is set to ikStandard or ikRegExpr. See the Using the SmartTextToDate Function topic for more information.
cxSDateThird	'third'	Allows you to quickly enter the third day of the current week using a date editor. The date editor recognizes the string if its Properties.InputKind is set to ikStandard or ikRegExpr. See the Using the SmartTextToDate Function topic for more information.
cxSDateThursday	'Thursday'	Applied to date editors. The string allows you to quickly enter the date corresponding to next Thursday. A date editor recognizes the string if its Properties.InputKind is set to ikStandard or ikRegExpr. See the Using the SmartTextToDate Function topic for more information.
cxSDateToday	'today'	Applied to date editors. The string allows you to quickly enter the current date. A date editor recognizes the string if its Properties.InputKind is set to ikStandard or ikRegExpr. See the Using the SmartTextToDate Function topic for more information.
cxSDateTomorrow	'tomorrow'	Applied to date editors. The string allows you to quickly enter the tomorrow’s date. A date editor recognizes the string if its Properties.InputKind is set to ikStandard or ikRegExpr. See the Using the SmartTextToDate Function topic for more information.
cxSDateTuesday	'Tuesday'	Applied to date editors. The string allows you to quickly enter the date corresponding to next Tuesday. A date editor recognizes the string if its Properties.InputKind is set to ikStandard or ikRegExpr. See the Using the SmartTextToDate Function topic for more information.
cxSDateWednesday	'Wednesday'	Applied to date editors. The string allows you to quickly enter the date corresponding to next Wednesday. A date editor recognizes the string if its Properties.InputKind is set to ikStandard or ikRegExpr. See the Using the SmartTextToDate Function topic for more information.
cxSDateYesterday	'yesterday'	Applied to date editors. The string allows you to quickly enter the yesterday’s date. A date editor recognizes the string if its Properties.InputKind is set to ikStandard or ikRegExpr. See the Using the SmartTextToDate Function topic for more information.
cxSEditCheckBoxChecked	'True'	The default value for the Properties.DisplayChecked property of a check box.  See its description for more information.
cxSEditCheckBoxGrayed	''	The default value for the Properties.DisplayGrayed property of a check box.  See its description for more information.
cxSEditCheckBoxUnchecked	'False'	The default value for the Properties.DisplayUnchecked property of a check box.  See its description for more information.
cxSEditInvalidRepositoryItem	'The repository item is not acceptable'	Specifies the exception message raised when an editor is assigned an invalid repository item via the RepositoryItem property. For every editor, Express Library provides a corresponding repository item.  If NIL or an inappropriate repository item is assigned, this exception is fired.
cxSEditNumericValueConvert Error	'Could not convert to numeric value'	Applied to spin editors (TcxSpinEdit). You can use the editor’s Properties.PrepareDisplayValue method to test whether a specific variant value can be displayed within it.  When you pass a non-string value as a parameter that cannot be converted to a number, an exception with the cxSEditNumericValueConvertError text is raised.
cxSEditPopupCircularReferen cingError	'Circular referencing is not allowed'	Applied to popup editors (TcxPopupEdit). The exception message is raised when trying to open the popup window embedding an invalid control (the control which recursively owns the current editor). See the Properties.PopupControl property to link an external control to the popup editor.
cxSEditTimeConvertError	'Could not convert to time'	Applied to TcxTimeEdit controls. You can use the editor’s Properties.PrepareDisplayValue method to test whether a specific variant value can be displayed within it.  When you pass a value as a parameter that cannot be converted to a date/time value, an exception with the cxSEditTimeConvertError text is raised. For numerical, date/time and string values, this exception is not raised.
cxSEditValidateErrorText	'Invalid input value. Use escape key to abandon changes'	Specifies the exception message, which is raised when the display text cannot be converted to an edit value.
cxSEditValueOutOfBounds	'Value out of bounds'	Currency and spin editors allow you to define the range of acceptable numbers via the Properties.MaxValue and Properties.MinValue members.  When posting a value beyond this range, an exception with the cxSEditValueOutOfBounds message is raised.
cxSMenuItemCaptionCopy	'&Copy'	Applied to image editors (TcxImage and TcxBlobEdit are customized to display images). The string represents the caption of the menu item to copy the contents of an editor.
cxSMenuItemCaptionCut	'Cu&t'	Applied to image editors (TcxImage and TcxBlobEdit are customized to display images). The string represents the caption of the menu item to copy and delete the contents of an editor.
cxSMenuItemCaptionDelete	'&Delete'	Applied to image editors (TcxImage and TcxBlobEdit customized to display images). The string represents the caption of the menu item to delete the contents of an editor.
cxSMenuItemCaptionLoad	'&Load...'	Applied to image editors (TcxImage and TcxBlobEdit are customized to display images). The string represents the caption of the menu item to load an image from an external file.
cxSMenuItemCaptionPaste	'&Paste'	Applied to image editors (TcxImage and TcxBlobEdit are customized to display images). The string represents the caption of the menu item to replace the contents of an editor with an image from the clipboard.
cxSMenuItemCaptionSave	'Save &As...'	Applied to image editors (TcxImage and TcxBlobEdit are customized to display images). The string represents the caption of the menu item to save an editor’s image to an external file.
cxSRadioGroupDefaultCaption	''	The default value for the radio group’s Properties.DefaultCaption property.
scxMaskEditEmptyMaskColle ctionFile	'The mask collection file is empty'	A mask editor enables you to load masks from an external file (.def or .dxm).  Then you can apply one of the loaded masks to the editor. The string represents an exception message when the file with masks is empty. To load a file, select the editor’s Properties.EditMask property in the Object Inspector, click the ellipsis(…) button and then click the Masks… button within the opened dialog.
scxMaskEditIllegalFileFormat	'Illegal file format'	A mask editor enables you to load masks from an external file (.def or .dxm).  Then you can apply one of the loaded masks to the editor. The string represents an exception message when masks in the file cannot be parsed properly. To load a file, select the editor’s Properties.EditMask property in the Object Inspector, click the ellipsis(…) button and then click the Masks… button within the opened dialog.
scxMaskEditInvalidEditValue	'The edit value is invalid'	Specifies the exception message raised when the display text does not fully correspond to the mask and therefore cannot be converted to an edit value.
scxMaskEditMaskCollectionFi les	'Mask collection files'	A mask editor enables you to load masks from an external file (.def or .dxm).  You can apply one of the loaded masks to the editor. To load a file, select the editor’s Properties.EditMask property in the Object Inspector, click the ellipsis(…) button and then click the Masks… button within the opened dialog.  This will activate the Open dialog. The scxMaskEditMaskCollectionFiles constant defines the string displayed in the Files of type box of this dialog.
scxMaskEditNoMask	'None'	Represents an empty mask in the Masked Text Editor dialog. To open this dialog, select the editor’s Text property in the Object Inspector and click the ellipsis (…) button.
scxMaskEditRegExprError	'Regular expression errors:'	The caption of the error message displayed when specifying an invalid regular expression for a mask editor.  This string is followed by detail information on the error.
scxRegExprCantCreateEmpty Alt	'The alternative should not be empty'	This error message can occur when parsing a regular expression, containing an empty alternative, for a mask editor. For instance: abc||.
scxRegExprCantCreateEmpty Block	'The block should not be empty'	The error message can occur when parsing a regular expression, containing an empty grouping block, for a mask editor. For instance: abc().
scxRegExprCantCreateEmpty Enum	'Can''t create empty enumeration'	The error message can occur when parsing a regular expression, containing an empty enumeration block, for a mask editor. For instance: abc[] or abc[^].
scxRegExprCantUsePlusQua ntifier	'The ''+'' quantifier cannot be applied here'	The error message can occur when parsing a regular expression for a mask editor. This error occurs when the ‘+’ quantifier is inappropriate.  For instance, the following expressions generate this error: a?+ a*+
scxRegExprCantUseStarQuan tifier	'The ''*'' quantifier cannot be applied here'	The error message can occur when parsing a regular expression for a mask editor. This error occurs when the ‘ * ’ quantifier cannot be used in its current position.  For instance, the following expression generates this error: a?*
scxRegExprChar	'Char'	Used to build an error message which can occur when parsing a regular expression for a mask editor. The scxRegExprChar string is followed by the position of the character, which has generated the error.
scxRegExprEmptySourceStre am	'The source stream is empty'	You can use the IsTextValid or IsTextFullValid method declared in the cxRegExpr unit to test whether custom text corresponds to a specific regular expression.  If the regular expression is empty (contains only spaces and tab characters), the scxRegExprEmptySourceStream error occurs. The IsTextValid method returns True if all text corresponds to a part of the mask. The IsTextFullValid returns True if all text corresponds to the entire mask.
scxRegExprHexNumberExpec ted	'Hexadecimal number expected but ''%s'' found'	The error message can occur when parsing a regular expression for a mask editor. This error occurs when an illegal character was found instead of a hexadecimal symbol (0-9, A-F). For instance, the following expression is invalid: \xk
scxRegExprHexNumberExpec ted0	'Hexadecimal number expected'	The error message can occur when parsing a regular expression for a mask editor. The error occurs if the \x meta-character is not followed by any symbol or followed only by one valid hexadecimal number (0-9, A-F): \x \xA
scxRegExprIllegalQuantifier	'Illegal quantifier ''%s'''	The error message can occur when parsing a regular expression for a mask editor. This error occurs when a quantifier cannot be used in its current position.  For instance, the space character cannot precede the quantifiers (*, +, ?).
scxRegExprIllegalSymbol	'Illegal ''%s'''	The error message can occur when parsing a regular expression for a mask editor. Occurs if the specified character cannot be used in its current position.
scxRegExprIncorrectSpace	'The space character is not allowed after ''\'''	The error message can occur when parsing a regular expression for a mask editor. Occurs if the space character follows the backslash.
scxRegExprLine	'Line'	Used to build an error message which can occur when parsing a regular expression for a mask editor. The scxRegExprLine string is followed by the line position where the error occurred. A parser has the potential to process multi-line regular expressions.  However, in the current version, you are able to specify a single-line regular expression only for a mask editor.  Therefore, the line position is always 1.
scxRegExprMissing	'Missing ''%s'''	The error message can occur when parsing a regular expression for a mask editor. This error occurs if the specified character is expected but not found.
scxRegExprNotSupportQuant ifier	'The parameter quantifiers are not supported'	The error message which can occur when parsing a regular expression for a mask editor. In the current version, parameter quantifiers are not supported.  This error occurs if the regular expression contains braces { }.
scxRegExprSubrangeOrder	'The starting character of the subrange must be less than the finishing one'	The error message can occur when parsing a regular expression for a mask editor. The first character of a sub range in an enumeration block must be less than the last one.  If not, the parser generates an error with the scxRegExprSubrangeOrder order.  For instance, the following expression is illegal: [F-A]
scxRegExprTooBigReference Number	'Too big reference number'	The error message can occur when parsing a regular expression for a mask editor. The parser cannot find parenthesis corresponding to the current back reference.  For instance, the following expression contains only two opening brackets, while the back reference refers to the third one: (\d)(abc)\3
scxRegExprUnnecessary	'Unnecessary ''%s'''	The error message which can occur when parsing a regular expression for a mask editor. The error occurs if the specified character is found, but is not needed.  For instance, the following expression contains unnecessary closing brace: (999))
scxSHyperLinkPrefix	'http://'	The default prefix string for hyperlinks.
scxSCalcError	'Error'	The string displayed in the edit box of the TcxCalcEdit control if an expression cannot be evaluated.


cxTrackBar Unit Overview
cxTrackBar Unit

Classes

TcxCustomTrackBar

TcxCustomTrackBarProperties

TcxTrackBar

TcxTrackBarProperties


TcxCustomTrackBar
TcxCustomTrackBar Object

Hierarchy          Properties          Methods          Events

Serves as the base for track bar controls.

Unit

cxTrackBar

TcxCustomTrackBar = class(TcxCustomEdit)

Description

Track bar controls enable you to edit values using a slider.  The edit value can be changed by dragging the slider with the mouse, by clicking the slider at the required position or by pressing the arrow keys or PAGE UP and PAGE DOWN keys when the control is focused.  Track bars can also display a scale showing the range of edited values, marking each possible slider position by a number or by simple marks.  The appearance of all elements can be changed using a set of properties affecting the control’s style.

The image below displays examples of the track bar control’s appearance.

The TcxCustomTrackBar class implements all the functionality required by track bars.  The derived TcxTrackBar control simply publishes the inherited properties and event.

Do not create instances of the TcxCustomTrackBar class in applications.  Use the TcxTrackBar control to add a track bar to forms.  The TcxCustomTrackBar class can be used as the base if you need to create custom track bar controls.


TcxCustomTrackBar Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |


Properties for TcxCustomTrackBar
TcxCustomTrackBar Properties

TcxCustomTrackBar          Legend

In TcxCustomTrackBar

ActiveProperties

Position

Properties

Derived from TcxCustomEdit

ActiveProperties

AutoSize

DataBinding

EditModified

EditValue

InnerEdit

ModifiedAfterEnter

Properties

RepositoryItem

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxCustomTrackBar
TcxCustomTrackBar Methods

TcxCustomTrackBar          Legend

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCustomTrackBar
TcxCustomTrackBar Events

TcxCustomTrackBar          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCustomTrackBar.ActiveProperties

TcxCustomTrackBar          See Also

Obtains the properties that are currently applied to a track bar.

property ActiveProperties: TcxCustomTrackBarProperties;

Description

Use the ActiveProperties property to obtain the properties of the current track bar that are currently in effect.  This property is especially useful when the track bar 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 track bar.  Otherwise, the inherent track bar’s properties are returned.

ReadOnly Property


TcxCustomTrackBar.Position

TcxCustomTrackBar          See Also

Specifies the current position of the track bar’s slider.

property Position: Integer;

Description

End-users can change the position of the track bar’s slider (and thus its edit value) in three ways:

•	drag the slider using the mouse;

•	click the slider in the position where you want it to be moved to;

•	click either arrow keys or the Page Down and Page Up keys when the control is focused.

When any of these methods are used, the Properties.OnChange event is raised.  Thus, you can provide a proper response to changing the edited value.  To do so, you will need to obtain the current position of the track bar’s slider and this is available via the Position property.

You can also use the Position property to change the edited value programmatically.  Note that this property value is restricted to the range specified by the Properties.Min and Properties.Max property values.  Trying to assign a value below the allowed range will result in setting the Position to the Properties.Min property value.  Similarly, assigning a value beyond the range will assign it to the Properties.Max property value.

Setting the Position property programmatically is useful, for instance, when you want to synchronize the track bar with another control.  An example can be using the track bar together with a text editor.  In this case, the track bar can be used for rough value modifications while the text editor allows precise value changes.  This assumes that the text editor’s value changes are handled and the Position property of the track bar is modified as needed.  The Properties.OnChange event of the track bar must also be handled to update the bound control in this case.

Note that changing the Position property value programmatically also results in raising the Properties.OnChange event.

The default value of the Position property is 0.


TcxCustomTrackBar.Properties

TcxCustomTrackBar          See Also

Provides access to properties specific to the track bar editor.

property Properties: TcxCustomTrackBarProperties;

Description

Use the Properties property to access the TcxCustomTrackBarProperties object holding attributes specific to the track bar editor.  The attributes available allow you to change the appearance of the control’s elements and its behavior.  Please refer to the TcxCustomTrackBarProperties class description for details.


TcxCustomTrackBarProperties
TcxCustomTrackBarProperties Object

Hierarchy          Properties          Methods          Events

Holds the track bar’s specific properties.

Unit

cxTrackBar

TcxCustomTrackBarProperties = class(TcxCustomEditProperties)

Description

The TcxCustomTrackBarProperties class is the base class for the TcxTrackBarProperties class.  The latter can be accessed via the Properties property of the TcxTrackBar control.  It holds settings specific to the track bar editor.  These properties control the appearance and behavior of the control.  They allow you to set the maximum and minimum allowed values, the colors of elements within the control, the layout of the scale, etc.  It also provides the OnChange event and this can be handled in response to edit value changes.

The TcxCustomTrackBarProperties class implements all the functionality needed by its descendant.  The derived TcxTrackBarProperties class simply publishes some properties and the one event.


TcxCustomTrackBarProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |


Properties for TcxCustomTrackBarProperties
TcxCustomTrackBarProperties Properties

TcxCustomTrackBarProperties          Legend

In TcxCustomTrackBarProperties

AutoSize

BorderWidth

Frequency

Max

Min

Orientation

PageSize

SelectionColor

SelectionEnd

SelectionStart

ShowTicks

ShowTrack

TextOrientation

ThumbColor

ThumbHeight

ThumbHighlightColor

ThumbStep

ThumbType

ThumbWidth

TickColor

TickMarks

TickSize

TickType

TrackColor

TrackSize

Derived from TcxCustomEditProperties

Alignment

AssignedValues

AutoSelect

BeepOnError

Buttons

ButtonsViewStyle

ClearKey

ClickKey

ImmediatePost

ReadOnly

UseLeftAlignmentOnEditing

UseMouseWheel

ValidateOnEnter


Methods for TcxCustomTrackBarProperties
TcxCustomTrackBarProperties Methods

TcxCustomTrackBarProperties          Legend

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue


Events for TcxCustomTrackBarProperties
TcxCustomTrackBarProperties Events

TcxCustomTrackBarProperties          Legend

In TcxCustomTrackBarProperties

OnChange

OnDrawThumb

OnGetThumbRect

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomTrackBarProperties.AutoSize

TcxCustomTrackBarProperties          See Also

Specifies whether the size of track bar’s elements is calculated automatically.

property AutoSize: Boolean;

Description

By default, the size of the track and slider are calculated automatically by the control.  However, you may set the AutoSize property to False to specify the size of these elements manually.  The ThumbHeight, ThumbWidth and TrackSize properties should be used for this purpose.

The default value of the AutoSize property is True.


TcxCustomTrackBarProperties.BorderWidth

TcxCustomTrackBarProperties          See Also

Specifies the additional offset of the track bar’s elements from its borders.

property BorderWidth: Integer;

Description

By default, the track bar’s elements have a predefined offset from the edges of the control.  You can increase this offset by changing the BorderWidth property value.  Note that when the AutoSize property value is True, the BorderWidth changes the horizontal offset only.  Otherwise, the indent is changed in all directions.  The image below shows two track bars with BorderWidth properties set to 0 and 20.  The AutoSize property is set to True.

The default value of the BorderWidth property is 2.


TcxCustomTrackBarProperties.Frequency

TcxCustomTrackBarProperties          See Also

Specifies the distance between the ticks displayed.

type

  TcxPositiveNumber = 0..High(Integer);

property Frequency: TcxPositiveNumber;

Description

Use the Frequency property to set the offset between neighboring ticks.  This property value specifies the amount by which the Position property must be changed so that the track bar’s thumb moves to the next or previous tick.  Note that ticks are only displayed if the ShowTicks property value is True.  The TickType property can be used to specify whether ticks are displayed as lines or as numbers.

When you alter the offset between neighboring ticks, the number of ticks displayed also changes.  The table below shows screenshots of the same track bar control when the Frequency property is set to 2, 3 and 5.

Value	Effect
2
3
5

The Frequency property can be used for two reasons:

•	when the range of edited values is too large for all ticks to fit within the track bar.  Increase the Frequency to decrease the number of ticks in this case.

•	to restrict the end users to specific values only.

The default value of the Frequency property is 1.


TcxCustomTrackBarProperties.Max

TcxCustomTrackBarProperties          See Also

Specifies the maximum value that can be represented by the track bar control.

property Max: Integer;

Description

The Min and Max properties specify the lower and upper bounds of values that can be displayed by the track bar control.  For instance, if you want to use track bars to modify the red, green and blue channels of a color, you need to set the Min and Max properties of the controls to 0 and 255 respectively.  Note that the Max property cannot be set to a value less than the Min property value, and vice versa.  Attempts to do so will have no effect.

The current position of the track bar’s thumb is specified by the Position property of the TcxTrackBar control.  This property can be set only to values that fall within the range specified by the Min and Max properties.

The default value of the Max property is 10.


TcxCustomTrackBarProperties.Min

TcxCustomTrackBarProperties          See Also

Specifies the minimum values that can be represented by the track bar control.

property Min: Integer;

Description

The TcxTrackBar control displays values in the range specified by the Min and Max properties.  For instance, if you want to edit percent values, you need to set these properties to 0 and 100 respectively.  Note that you cannot set the Min property to a value greater than the Max property value and vice versa.  If such an assignment takes place, it will have no effect.

The Position property of the TcxTrackBar control specifies the current slider’s position.  This property cannot be set to a value that exceeds the bounds of the allowed range of values.  In other words it cannot be set to a value less than Min or greater than Max.

The default value of the Min property is 0.


TcxCustomTrackBarProperties.Orientation

TcxCustomTrackBarProperties          See Also

Specifies whether the track bar is oriented horizontally or vertically.

type

  TcxTrackBarOrientation = (tboHorizontal, tboVertical);

property Orientation: TcxTrackBarOrientation;

Description

Use the Orientation property if you need to change the track bar’s orientation.  The following values are available for this property:

Value	Meaning	Example
tboHorizontal	The track bar is horizontally oriented.  Values are displayed from left to right.
tboVertical	The track bar is vertically oriented.  Values are displayed from top to bottom.

Note that up arrow, left arrow and PAGE UP keys move the track bar’s thumb to smaller values.  The down arrow, right arrow and PAGE DOWN keys move it to larger values.  This doesn’t depend on the track bar’s orientation.

You can also change the orientation of the text representing the ticks by changing the TextOrientation property value (and use the TickType property to specify whether ticks must be displayed as numbers or lines).

The default value of the Orientation property is tboHorizontal.


TcxCustomTrackBarProperties.PageSize

TcxCustomTrackBarProperties          See Also

Specifies the amount by which the slider’s position is changed when pressing the PAGE UP or PAGE DOWN key or by clicking the track bar.

type

  TcxNaturalNumber = 1..High(Integer);

property PageSize: TcxNaturalNumber;

Description

When the track bar is oriented horizontally (Orientation is tboHorizontal), pressing the PAGE UP key is equivalent to clicking the bar to the right of the slider, resulting in an increased Position property value.  Pressing the PAGE DOWN key, in this case, results in the same as clicking the bar to the left of the slider.  This decreases the Position.  If the track bar is vertically oriented pressing the PAGE UP and PAGE DOWN keys is equivalent to clicking the bar above and below the slider, respectively.  In all cases, the Position property is changed by the amount specified by the PageSize property.

Tip:	The range of values edited by the track bar is specified by the Min and Max properties.  You can assign this range (or a greater value) to the PageSize property.  In this case, pressing the PAGE UP key will result in moving the track bar’s thumb to the minimum available value independently of the current slider’s position.  Pressing the PAGE DOWN key will result in moving the track bar’s thumb to the maximum value available.

Pressing the arrow keys always results in changing the Position property value by 1.

The default value of the PageSize property is 1.


TcxCustomTrackBarProperties.SelectionColor

TcxCustomTrackBarProperties          See Also

Specifies the color of the selection bar.

property SelectionColor: TColor;

Description

The track bar control enables you to display a selection bar within the track.  The portion of the track occupied by the selection bar is specified by the SelectionStart and SelectionEnd properties.  Note also that the track can be hidden by setting the ShowTrack property to False, which will also hide the selection bar.

Use the SelectionColor property to specify the color of the selection bar.  The image below shows the appearance of the track bar when this property is set to clNavy and clMoneyGreen.

The default value of the SelectionColor property is clHighlight.


TcxCustomTrackBarProperties.SelectionEnd

TcxCustomTrackBarProperties          See Also

Specifies the position where the selection bar ends.

property SelectionEnd: Integer;

Description

If the track is displayed within the track bar control (the ShowTrack property value is True), you can display a selection bar within it.  The range occupied by the selection bar is specified by the SelectionStart and SelectionEnd properties.  Note that the selection bar is displayed only when the following conditions are satisfied:

•	The SelectionStart property value is less than the SelectionEnd property value.  This means that you can hide the selection bar by setting these properties to the same value;

•	The SelectionStart property value is less than the Max property value;

•	The SelectionEnd property value is greater than the Min property value.

Note that if the SelectionStart property value equals the Min property value and SelectionEnd equals Max, the selection bar occupies the entire track.

The image below shows the relation between the SelectionStart, SelectionEnd, Min and Max property values.

Note:	The color of the selection bar is controlled by the SelectionColor property.

Tip:	You can imitate a progress bar control by hiding the track bar’s thumb and operating with the selection only.  The ThumbType property must be set to cxttNone for this purpose.

The default value of the SelectionEnd property is 0.


TcxCustomTrackBarProperties.SelectionStart

TcxCustomTrackBarProperties          See Also

Specifies the position where the selection bar starts.

property SelectionStart: Integer;

Description

If you need to highlight a portion of the track with a different color, set the SelectionStart and SelectionEnd properties to values specifying the starting and ending positions of the highlighted bar.  This can be used, for instance, if you want to display critical ranges of values.  The image below shows an example of displaying the selection bar.  It also illustrates the relation between the Min, Max, SelectionStart and SelectionEnd properties.

Please refer to the SelectionEnd property description for details on customizing the selection bar.

The default value of the SelectionStart property is 0.


TcxCustomTrackBarProperties.ShowTicks

TcxCustomTrackBarProperties          See Also

Specifies whether ticks are displayed.

property ShowTicks: Boolean;

Description

If the ShowTicks property is True, the control displays ticks along the bar.  The ticks can be represented by lines, numbers showing the Position property value at their location or the combination of both types.  This can be specified using the TickType property.  Moreover, you can use the Frequency property to control the distance between ticks.

Setting the ShowTicks property to False hides the ticks.  You might want to do this if end users get feedback about the edited value by other means than the track bar itself.  For instance, the edited value can be displayed in a synchronized text editor.

Note that you can control the position of ticks relative to the track bar using the TickMarks property.  This property also affects the slider’s appearance.  When hiding ticks, you might like to set the TickMarks property to cxtmBoth, thus preventing the slider from pointing to either side of the track bar.

The table below shows you examples of using the ShowTicks and TickMarks properties.

Values	Description	Example
ShowTicks = True TickMarks = cxtmBottomRight	Ticks are displayed at the bottom of the track bar (or at the right, if it is vertically oriented). The track bar’s thumb points to the ticks.
ShowTicks = False TickMarks = cxtmBoth	Ticks are hidden.  The track bar’s thumb doesn’t point anywhere.
Note:	You can also hide the track bar (i.e. by displaying the slider and ticks only) by setting the ShowTrack property to False.

The default value of the ShowTicks property is True.


TcxCustomTrackBarProperties.ShowTrack

TcxCustomTrackBarProperties          See Also

Specifies whether the track bar is displayed.

property ShowTrack: Boolean;

Description

If the ShowTrack property value is True, the track bar’s thumb is moved along the track bar.  Otherwise, the track bar is not displayed.  The table below illustrates the ShowTrack property’s values.

Value	Example
True
False

Note that you can also hide the ticks displayed along the track bar by setting the ShowTicks property to False.

The default value of the ShowTrack property is True.


TcxCustomTrackBarProperties.TextOrientation

TcxCustomTrackBarProperties          See Also

Specifies the orientation of the text representing the ticks.

type

  TcxTrackBarTextOrientation = (tbtoHorizontal, tbtoVertical);

property TextOrientation: TcxTrackBarTextOrientation;

Description

If the ShowTicks property is set to True, the control displays ticks along the track bar.  You can represent all ticks by text labels by setting the TickType property to tbttNumbers. Note: if this property is set to tbttValueNumber, the text will be displayed for the current thumb value only.  These labels display the Position property value corresponding to their location.

The TextOrientation property allows you to change the orientation of text within the labels.  You can use this, for instance, to avoid values overlapping.  The images below show an example.

Value	Meaning	Example
tbtoHorizontal	The text is horizontally oriented within tick labels.
tbtoVertical	The text is vertically oriented within tick labels.
Note:	You can also change the orientation of the track bar itself.  Use the Orientation property for this purpose.

The default value of the TextOrientation property is tbtoHorizontal.


TcxCustomTrackBarProperties.ThumbColor

TcxCustomTrackBarProperties          See Also

Specifies the color of the track bar’s thumb.

property ThumbColor: TColor;

Description

The ThumbColor property sets the color used to paint the track bar’s thumb.  This property is only in effect when the editor doesn’t use XP styles.  You can control whether the editor is painted in XP styles using the Style.LookAndFeel.NativeStyle property.

The images below show examples of setting the ThumbColor property to different values.

Value	Example
clBlue
clFuchsia
You can also change the color used to paint the slider when the mouse pointer hovers over it.  Use the ThumbHighlightColor property for this purpose.  The color of ticks and the track bar can be modified using the TickColor and TrackColor properties.

The default value of the ThumbColor property is clBtnFace.


TcxCustomTrackBarProperties.ThumbHeight

TcxCustomTrackBarProperties          See Also

Specifies the height of the track bar’s thumb in pixels.

property ThumbHeight: Integer;

Description

There are two ways to control the size of the track bar’s thumb:

•	Set the AutoSize property to True.  In this case, dimensions of the slider will be calculated automatically with respect to the track bar width (the TrackSize property).  Values of the ThumbWidth and ThumbHeight properties will be ignored in this case

•	Set the AutoSize property to False and specify the slider’s dimensions manually using the ThumbHeight and ThumbWidth properties.

Note that you cannot assign values less than 10 to the ThumbHeight property.

Images below show examples of changing the ThumbHeight property value.

Value	Example (horizontal orientation)	Example (vertical orientation)
20
30

The default value of the ThumbHeight property is 18.


TcxCustomTrackBarProperties.ThumbHighlightColor

TcxCustomTrackBarProperties          See Also

Specifies the color of the track bar’s thumb when the mouse pointer hovers over it.

property ThumbHighlightColor: TColor;

Description

Use ThumbHighLightColor to specify the color used to paint the track bar’s thumb when it is hot-tracked.  Note that the specified color is only used if the editor is not using XP styles.  You should use the Style.LookAndFeel.NativeStyle property to specify whether XP styles are used.

The color used to paint the slider in normal state is set using the ThumbColor property.  You can also specify custom colors for ticks and the track bar.  This can be performed using the TickColor and TrackColor properties.

The default value of the ThumbHighlightColor property is clSilver.


TcxCustomTrackBarProperties.ThumbStep

TcxCustomTrackBarProperties          See Also

Specifies the manner in which the track bar’s thumb is moved when the track bar is clicked.

type

  TcxTrackBarThumbStep = (cxtsNormal, cxtsJump);

property ThumbStep: TcxTrackBarThumbStep;

Description

End users can change the position of the track bar’s slider by clicking it at the position in which they want the track bar’s thumb to be moved to.  Use the ThumbStep property to specify the manner in which the slider will be moved.  The following values are available for this property.

Value	Meaning
cxtsNormal	The slider moves by a single tick to the specified position.
cxtsJump	The slider moves (jumps) exactly to the specified position (actually, the nearest tick to this position).

The default value of the ThumbStep property is cxtsNormal.


TcxCustomTrackBarProperties.ThumbType

TcxCustomTrackBarProperties          See Also

Specifies whether the track bar’s thumb is visible and whether it must be custom painted.

type

  TcxTrackBarThumbType = (cxttNone, cxttRegular, cxttCustom);

property ThumbType: TcxTrackBarThumbType;

Description

Use the ThumbType property to specify whether the track bar’s thumb must be displayed and in what manner.  The following values are available for this property.

Value	Meaning
cxttNone	The slider is not displayed.  This can be used if you want to display information using the selection bar only.  Please refer to the SelectionColor, SelectionStart and SelectionEnd properties for information on how to display and customize the selection bar.
cxttRegular	The control’s Style.LookAndFeel.Kind and Style.LookAndFeel.NativeStyle properties specify the appearance of the slider.  The size of the track bar’s thumb is specified by the ThumbHeight and ThumbWidth properties unless the AutoSize property value is True when the slider’s size is then calculated automatically.
cxttCustom	The track bar’s thumb must be painted manually by handling the OnDrawThumb event.  Specify the slider’s bounding rectangle by handling the OnGetThumbRect event.

The default value of the ThumbType property is cxttRegular.


TcxCustomTrackBarProperties.ThumbWidth

TcxCustomTrackBarProperties          See Also

Specifies the width of the track bar’s thumb in pixels.

property ThumbWidth: Integer;

Description

The track bar control gives you the ability to set the height and width of the track bar’s thumb manually using the ThumbWidth and ThumbHeight properties.  Note however, that this can be done only if the AutoSize property value is False.  Otherwise the dimensions of the track bar’s thumb are calculated automatically with respect to the track bar width (the TrackSize property).

Note that you cannot assign values less than 4 to the ThumbWidth property.

Images below show examples of the ThumbWidth property settings.

Value	Example (horizontal orientation)	Example (vertical orientation)
10
15

The default value of the ThumbWidth property is 7.


TcxCustomTrackBarProperties.TickColor

TcxCustomTrackBarProperties          See Also

Specifies the color of ticks.

property TickColor: TColor;

Description

Ticks are displayed along the track bar if the ShowTicks property is set to True and the TickType property value is not tbttValues.  The color of ticks can be specified using the TickColor property.

If the TickType property value is tbttValues the track bar displays text labels instead of ticks.  When this property is set to tbttValueNumber, both tick and a text label are displayed.  The color of text labels can be specified using the Style.Font property.

The images below show examples of the TickColor property settings.

Value	Example
clBlue
clRed

You can also change the slider’s color in normal and hot-tracked states and the color of the track bar.  For this purpose, use the ThumbColor, ThumbHighlightColor and TrackColor properties respectively.

The default value of the TickColor property is clWindowText.


TcxCustomTrackBarProperties.TickMarks

TcxCustomTrackBarProperties          See Also

Specifies the position of tick marks and the appearance of the track bar’s thumb.

type

  TcxTrackBarTickMarks = (cxtmBoth, cxtmTopLeft, cxtmBottomRight);

property TickMarks: TcxTrackBarTickMarks;

Description

Use the TickMarks property to specify whether tick marks must be painted on a single or both sides of the track bar. Note that this affects the appearance of the track bar’s thumb.  If tick marks are located at a single side of the track bar, the slider points to them.  When ticks are painted at both sides, the slider doesn’t point to either side.

The table below shows how changing the TickMarks property value affects the control when the track bar is oriented horizontally or vertically.

Value	Meaning	Example (horizontal orientation)	Example (vertical orientation)
cxtmBottomRight	If the track bar is horizontally oriented, tick marks are located at the bottom.  Otherwise they are located to the right of the track bar.  The track bar’s thumb points to tick marks.
cxtmTopLeft	If the track bar is vertically oriented, tick marks are located at the top.  Otherwise they are located to the left of the track bar.  The track bar’s thumb points to tick marks.
cxtmBoth	The tick marks are located at both sides of the track bar.  The track bar’s thumb doesn’t point anywhere.

You can hide tick marks by setting the ShowTicks property to False.  In this case, you might like to set the TickMarks property to cxtmBoth so that the track bar’s thumb doesn’t point anywhere.

Tick marks can be represented by lines, numbers or a combination of both.  Please refer to the TickType property description for details.

The default value of the TickMarks property is cxtmBottomRight.


TcxCustomTrackBarProperties.TickSize

TcxCustomTrackBarProperties          See Also

Specifies the size of tick marks in pixels.

type

  TcxNaturalNumber = 1..High(Integer);

property TickSize: TcxNaturalNumber;

Description

If the ShowTicks property is set to True, tick marks are displayed along the track bar.  Tick marks can be displayed as lines, numbers or a combination of both, as specified by the TickType property.  You can change the length of tick mark lines using the TickSize property.  This property sets the length of all tick lines except for the first and last and these are 1.5 times the size of the others.

The table below shows the same control with different TickSize property values.

Value	Meaning	Example
1	All tick marks are represented by points
4	Middle ticks are 4 pixels, so the first and last ticks occupy 6 pixels.
8	Middle ticks occupy 8 pixels and end ticks take 12 pixels.
You can also change the color of the tick marks using the TickColor property.

The default value of the TickSize property is 4.


TcxCustomTrackBarProperties.TickType

TcxCustomTrackBarProperties          See Also

Specifies whether tick marks are shown using lines, numbers or a combination of both.

type

  TcxTrackBarTickType = (tbttTicks, tbttNumbers, tbttValueNumber);

property TickType: TcxTrackBarTickType;

Description

The track bar control is capable of displaying tick values along the track bar. The main properties that affect the appearance and visibility of these values are:

•	ShowTicks – specifies whether ticks are displayed

•	Frequency – specifies the interval between neighboring tick values

•	TickMarks – specifies the location of tick values

•	TickType – specifies the appearance of tick values

The options available for the TickType property are listed and illustrated in the table below.

Value	Meaning	Example
tbttTicks	All tick values are shown by lines.
tbttValueNumber	The tick value at the track bar’s thumb is displayed as a number. Other ticks are shown by lines.
tbttNumbers	All tick signs are displayed as numbers.

A number displayed as a tick value represents the value that the Position property will return if the slider points to it.

The default value of the TickType property is tbttTicks.


TcxCustomTrackBarProperties.TrackColor

TcxCustomTrackBarProperties          See Also

Specifies the color of the track bar.

property TrackColor: TColor;

Description

The track bar is displayed if the ShowTrack property is set to True.  Its color can be changed using the TrackColor property.  Note that this property is in effect only if the editor doesn’t use XP styles.  You should use the Style.LookAndFeel.NativeStyle property to specify whether XP styles are used.

The table below shows examples of setting the TrackColor property to different values.

Value	Example
clMoneyGreen
clSkyBlue
Tip: you can use the TrackColor property to change the track bar’s color dynamically.  For instance you can handle the OnChange event to assign shades of blue to it.  The minimum value can display in white and the maximum value in deep blue.

You can also customize the color of the track bar’s thumb in normal and hot-tracked states and the color of tick marks.  For this, use the ThumbColor, ThumbHighlightColor and TickColor properties respectively.

The default value of the TrackColor property is clWindow.


TcxCustomTrackBarProperties.TrackSize

TcxCustomTrackBarProperties          See Also

Specifies the width of the track bar in pixels.

property TrackSize: Integer;

Description

Use the TrackSize property to change the width of the track bar.  If the AutoSize property is set to True, the track bar’s thumb will be automatically resized when changing the track bar’s size.  Otherwise, you can set the slider’s dimensions manually using the ThumbHeight and ThumbWidth properties.

The table below shows how changing the TrackSize property value affect the control’s appearance.

Value	Example (horizontal orientation)	Example (vertical orientation)
10
4
Note:	You need to use the Orientation property to change the orientation of the track bar.

The default value of the TrackSize property is 10.


TcxCustomTrackBarProperties.OnChange

TcxCustomTrackBarProperties          See Also

Fires when the slider’s position is changed either by end users or via code.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnChange: TNotifyEvent;

Description

Handle the OnChange event to provide a proper response to changing the slider’s position (the Position property value).  For instance, if track bars are used to specify color channel values, you need to update the control displaying the resulting color in the event handler.

The Sender parameter of the event specifies the TcxTrackBar control whose Position property value has been changed.


TcxCustomTrackBarProperties.OnDrawThumb

TcxCustomTrackBarProperties          See Also

Enables you to paint the track bar’s thumb in a custom manner.

type

  TcxDrawThumbEvent = procedure(Sender: TObject; ACanvas: TcxCanvas; const ARect: TRect) of object;

property OnDrawThumb: TcxDrawThumbEvent;

Description

You can paint the track bar’s thumb in any manner you like.  Set the ThumbType property to cxttCustom for this purpose.  In this case, the OnDrawThumb event will fire each time the slider needs to be repainted.

The Sender parameter specifies the control whose slider is painted.  The ACanvas parameter allows you to obtain the canvas where you need to paint.  The bounding rectangle of the track bar’s thumb is obtained via the ARect parameter.  Note that the width and height of this rectangle (the size of the slider) must be specified by handling the OnGetThumbRect event.

The sample code below handles the OnDrawThumb and OnGetThumbRect events to paint an image instead of the track bar’s thumb.

// Delphi

procedure TForm1.cxTrackBar1PropertiesGetThumbRect(Sender: TObject; var ARect: TRect);

var Bitmap: TBitmap;

begin

  Bitmap := TBitmap.Create;

  Bitmap.LoadFromFile('c:\ThumbImage.bmp');

  ARect := Rect(0, 0, Bitmap.Width, Bitmap.Height);

end;

procedure TForm1.cxTrackBar1PropertiesDrawThumb(Sender: TObject; ACanvas: TcxCanvas; const ARect: TRect);

var

  Bitmap: TBitmap;

begin

  Bitmap := TBitmap.Create;

  Bitmap.LoadFromFile('c:\ThumbImage.bmp');

  ACanvas.Draw(ARect.Left, ARect.Top, Bitmap);

end;

The result of handling these events is shown in the image below.


TcxCustomTrackBarProperties.OnGetThumbRect

TcxCustomTrackBarProperties          See Also

Specifies the size of the custom painted track bar’s thumb.

type

  TcxGetThumbRectEvent = procedure(Sender: TObject; var ARect: TRect) of object;

property OnGetThumbRect: TcxGetThumbRectEvent;

Description

You may customize the slider’s appearance.  Set the ThumbType property to cxttCustom for this purpose and handle the OnDrawThumb to perform slider painting.  However, if the OnGetThumbRect event is not handled, the OnDrawThumb event handler will get the default bounding rectangle of the track bar’s thumb as its ARect parameter.  This is likely to give undesirable results (the slider will be painted at a wrong position, stretched, etc).  Thus, you need to handle the OnGetThumbRect event to specify the size of the custom track bar’s thumb.

Specify the size of the slider by assigning an appropriate value to the ARect parameter.  The width and height of this rectangle provide the width and height of the custom track bar’s thumb.

The Sender parameter of the event can be used to determine the control whose slider is being painted.

Please refer to the OnDrawThumb event description for details on custom track bar’s thumb painting.  The description also provides an example of handling both the OnDrawThumb and OnGetThumbRect events.


TcxTrackBar
 TcxTrackBar Object

Hierarchy          Properties          Methods          Events

Represents the track bar control that is used to edit values using a slider.

Unit

cxTrackBar

TcxTrackBar = class(TcxCustomTrackBar)

Description

Use TcxTrackBar to put a track bar with advanced features on a form. The control displays a slider that can be dragged by end users in order to modify the edit value.  When the control is focused, the track bar’s thumb can also be moved by pressing the arrow keys or the PAGE UP and PAGE DOWN keys.  You must handle the Properties.OnChange event to provide response for changing the slider’s position.  The current position can be determined by reading the Position property value.

The control is also capable of displaying tick marks along the track bar.  There are a number of properties that can be used to control the visibility and appearance of these marks.  They can be displayed as lines, as numbers or as a combination of both.  The control also enables you to specify the side of the track bar where the ticks are displayed.  This changes the appearance of the track bar’s thumb – it points to the side where the tick marks are. Please refer to the Properties.TickMarks, Properties.TickType, Properties.Frequency and Properties.ShowTicks properties descriptions for details on customizing tick marks.

You can also change the appearance of the control’s elements.  First, you can modify the size and style of each element of the control.  Second, the control can be painted using XP themes or one of three predefined painting styles (as for all editors in the Express Editors library).

The image below shows how the TcxTrackBar control may look in your application:


TcxTrackBar Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTrackBar

     |


Properties for TcxTrackBar
TcxTrackBar Properties

TcxTrackBar          Legend

Derived from TcxCustomTrackBar

ActiveProperties

Position

Properties

Derived from TcxCustomEdit

ActiveProperties

AutoSize

DataBinding

EditModified

EditValue

InnerEdit

ModifiedAfterEnter

Properties

RepositoryItem

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TControl

Align


Methods for TcxTrackBar
TcxTrackBar Methods

TcxTrackBar          Legend

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxTrackBar
TcxTrackBar Events

TcxTrackBar          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxTrackBarProperties
TcxTrackBarProperties Object

Hierarchy          Properties          Methods          Events

Represents the class containing track bar control specific settings.

Unit

cxTrackBar

TcxTrackBarProperties = class(TcxCustomTrackBarProperties)

Description

The TcxTrackBarProperties object can be accessed using the Properties property of the TcxTrackBar control.  This object declares the properties representing settings specific to track bar controls.  These settings allow you to customize the styles of the elements comprising the control, its orientation, the layout of tick marks, etc.  Also, it provides access to the OnChange event used to respond to changes in the slider’s position.

All the TcxTrackBarProperties object’s functionality is implemented by its ancestor – the TcxCustomTrackBarProperties class.  The descendant simply publishes some properties and the one event.


TcxTrackBarProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTrackBarProperties

     |


Properties for TcxTrackBarProperties
TcxTrackBarProperties Properties

TcxTrackBarProperties          Legend

Derived from TcxCustomTrackBarProperties

AutoSize

BorderWidth

Frequency

Max

Min

Orientation

PageSize

SelectionColor

SelectionEnd

SelectionStart

ShowTicks

ShowTrack

TextOrientation

ThumbColor

ThumbHeight

ThumbHighlightColor

ThumbStep

ThumbType

ThumbWidth

TickColor

TickMarks

TickSize

TickType

TrackColor

TrackSize

Derived from TcxCustomEditProperties

Alignment

AssignedValues

AutoSelect

BeepOnError

Buttons

ButtonsViewStyle

ClearKey

ClickKey

ImmediatePost

ReadOnly

UseLeftAlignmentOnEditing

UseMouseWheel

ValidateOnEnter


Methods for TcxTrackBarProperties
TcxTrackBarProperties Methods

TcxTrackBarProperties          Legend

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue


Events for TcxTrackBarProperties
TcxTrackBarProperties Events

TcxTrackBarProperties          Legend

Derived from TcxCustomTrackBarProperties

OnChange

OnDrawThumb

OnGetThumbRect

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


cxCalendar Unit Overview
cxCalendar Unit

Classes

TcxCustomDateEdit

TcxCustomDateEditProperties

TcxDateEdit

TcxDateEditProperties

Global Constants

scxGridDatePopupClear

scxGridDatePopupToday


TcxCustomDateEdit
TcxCustomDateEdit Object

Hierarchy          Properties          Methods          Events          See Also

TcxCustomDateEdit is the base type for those edit controls which provide convenient date editing.

Unit

cxCalendar

TcxCustomDateEdit = class(TcxCustomPopupEdit, IcxFormatContollerListener)

Description

The TcxCustomDateEdit component introduces new properties and methods in additions to the capabilities of the TcxCustomPopupEdit in order to edit date data in a convenient way.  To create an edit control to take advantage of the mask capabilities of TcxCustomDateEdit, use the TcxDateEdit or TcxDBDateEdit object.

In addition to entering dates via the dropdown calendar, a date editor allows a user to enter dates within an edit box in a number of ways depending on the Properties.InputKind property.  The following table lists some of the possible formats recognized by a date editor in a system with default English (United States) regional settings.

InputKind value	Examples of dates
ikStandard	01/31 01/31/2002 9-Aug August/09/2002 Smart input strings: today; tomorrow; Sunday; now; bom today–7; now+3
ikMask	01/31/2002
ikRegExpr	01/31/2002 Aug/09/2002 Smart input strings: today; tomorrow; Sunday; now; bom today–7; now+3

If the year is omitted in the ikStandard mode, the current year is assumed.  The syntax in the ikRegExpr mode supports the auto-completion function.  Also validation is performed and this restricts the user input.

Smart input strings are discussed in the SmartTextToDate topic.  See the Using SmartTextToDate Function section to know how to expand possible constants.

Do not create instances of TcxCustomDateEdit.  Use TcxCustomDateEdit as a base class when declaring controls that implement the date editing.  Properties and methods of TcxCustomDateEdit provide basic behavior that descendant classes inherit as well as behavior that components can override to customize the functionality.


TcxCustomDateEdit Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomPopupEdit

     |


Properties for TcxCustomDateEdit
TcxCustomDateEdit Properties

TcxCustomDateEdit          Legend

In TcxCustomDateEdit

ActiveProperties

CurrentDate

Date

Properties

Derived from TcxCustomPopupEdit

ActiveProperties

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxCustomDateEdit
TcxCustomDateEdit Methods

TcxCustomDateEdit          Legend

Derived from TcxCustomPopupEdit

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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCustomDateEdit
TcxCustomDateEdit Events

TcxCustomDateEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCustomDateEdit.ActiveProperties

TcxCustomDateEdit          See Also

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

property ActiveProperties: TcxCustomDateEditProperties;

Description

Use the ActiveProperties property to obtain the properties of the current date editor that are currently in effect.  This property is especially useful when the date 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 date editor.  Otherwise, the inherent date editor’s properties are returned.

ReadOnly Property


TcxCustomDateEdit.CurrentDate

TcxCustomDateEdit          See Also

Determines the date value from the string currently displayed in an editor.

property CurrentDate: TDateTime;

Description

Unlike the Date property, the CurrentDate property does not return the data stored by an editor.  Instead, the CurrentDate property converts the string currently displayed in an editor to a date value.  If the date vale cannot be obtained from the string, the CurrentDate property returns the NullDate constant value.

ReadOnly Property


TcxCustomDateEdit.Date

TcxCustomDateEdit          See Also

Determines the currently displayed date value.

property Date: TDateTime;

Description

Use the Date property to get and set the floating-point data stored by an editor.  The EditValue property and Date refer to the same data as the Date property is an EditValue wrapper.  EditValue is of type Variant and can store NULL values.  If EditValue specifies NULL, the Date property returns the NullDate constant value.

After a user presses the Enter key or sets focus to another control, the edit text is validated and converted to the EditValue property.

Note:	Use the CurrentDate property to obtain the date value directly from the string currently displayed in an editor.


TcxCustomDateEdit.Properties

TcxCustomDateEdit

Defines settings specific to date editors.

property Properties: TcxCustomDateEditProperties;

Description

The Properties object defines different settings specific to date editors.  The DateButtons member defines the buttons displayed within a dropdown calendar of the date editor.

The image below displays a date editor with the calendar dropdown (buttons are marked with red border.)

The DateOnError member determines the editor behavior when user input validation fails.  The SaveTime member determines whether time is also stored along with the date.


TcxCustomDateEditProperties
TcxCustomDateEditProperties Object

Hierarchy          Properties          Methods          Events          See Also

Defines settings specific to date editors.

Unit

cxCalendar

TcxCustomDateEditProperties = class(TcxCustomPopupEditProperties);

Description

The TcxCustomDateEditProperties class introduces new properties specific to date editors.  Use the Properties member of a specific editor to set its various settings.  TcxDateEditProperties publishes attributes provided by the TcxCustomDateEditProperties class.

The DateButtons member defines the buttons displayed within a dropdown calendar of the date editor.  The image below displays a date editor with the calendar dropdown (the buttons are marked with red border.)

The DateOnError member determines the edit value when user input validation fails.  The SaveTime member determines whether time is also stored along with the date.


TcxCustomDateEditProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |

TcxCustomDropDownEditProperties

     |

TcxCustomPopupEditProperties

     |


Properties for TcxCustomDateEditProperties
TcxCustomDateEditProperties Properties

TcxCustomDateEditProperties          Legend

In TcxCustomDateEditProperties

ArrowsForYear

AssignedValues

DateButtons

DateOnError

InputKind

Kind

MaxDate

MinDate

SaveTime

ShowTime

WeekNumbers

YearsInMonthList

Derived from TcxCustomPopupEditProperties

PopupControl

PopupSizeable

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

IncrementalSearch

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 TcxCustomDateEditProperties
TcxCustomDateEditProperties Methods

TcxCustomDateEditProperties          Legend

Derived from TcxCustomMaskEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults


Events for TcxCustomDateEditProperties
TcxCustomDateEditProperties Events

TcxCustomDateEditProperties          Legend

Derived from TcxCustomDropDownEditProperties

OnCloseQuery

OnCloseUp

OnInitPopup

OnPopup

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomDateEditProperties.ArrowsForYear

TcxCustomDateEditProperties

Specifies whether arrow buttons are displayed within the ‘Year’ field of the editor dropdown calendar.

property ArrowsForYear: Boolean;

Description

Use the ArrowsForYear property to hide or display buttons within the year portion of the date within the editor dropdown calendar.  With this property set to True, an end user can easily select the desired year by clicking the buttons or using the mouse wheel while the mouse cursor hovers over the ‘Year’ field:

Property’s Value	False	True

The default value of the ArrowsForYear property is True.


TcxCustomDateEditProperties.AssignedValues

TcxCustomDateEditProperties

Contains the property flags that indicate which properties specific to a date editor have been changed.

property AssignedValues: TcxDateEditPropertiesValues;

Description

Use the AssignedValues property to track the changes made to a date editor’s DateButtons, DisplayFormat, EditFormat, InputKind, MaxLength, MaxValue, MinValue and ReadOnly properties and undo them.  Once the property being tracked is set to a value other than the default one, the changes are reflected in the AssignedValues property (its corresponding property flag is set to True).  To undo the changes made and reverse the property back to its default value, set the corresponding property flag to False or call the AssignedValues.RestoreDefaults method to reverse all these properties back to their default values and reset all the property flags.  Use the AssignedValues.BeginUpdate and AssignedValues.EndUpdate methods to control when the editor repaints and avoid any flickering when the property flags are modified.


TcxCustomDateEditProperties.DateButtons

TcxCustomDateEditProperties

Specifies buttons to display within the editor dropdown calendar.

type

  TDateButton = (btnClear, btnNow, btnToday);

  TDateButtons = set of TDateButton;

property DateButtons: TDateButtons;

Description

Use the DateButtons property to hide or display buttons within a dropdown calendar.

There are 3 buttons that can appear within the date editor:

Button	Action
btnClear	Clears the date value by setting the editor’s Date property to the NullDate constant value.
btnNow	Sets the current date and time.
btnToday	Sets the current date only.  The time portion of the date editor’s value remains unmodified.

When the Properties.Kind property is set to ckDate, the default value of the DateButtons property is [btnToday,btnClear]; otherwise, [btnToday,btnNow].


TcxCustomDateEditProperties.DateOnError

TcxCustomDateEditProperties

Determines the date to be assigned to an editor in case of invalid date input.

type

  TDateOnError = (deNoChange, deToday, deNull);

property DateOnError: TDateOnError;

Description

Use the DateOnError property to set the date assigned to the date edit in case of invalid date input.

There are three kinds of value which can be assigned to the editor EditValue property:

Kind	Description
deNoChange	The current editor’s value remains unchanged.
deToday	Sets the editor’s value to a current date-time.
deNull	Clears the editor’s value by setting its EditValue property to Null.

The default value of the DateOnError property is deNoChange.


TcxCustomDateEditProperties.InputKind

TcxCustomDateEditProperties

Determines the type of validation used to validate user input.

type

  TcxInputKind = (ikStandard, ikMask, ikRegExpr);

property InputKind: TcxInputKind;

Description

Use the InputKind property to determine the type of validation used to validate user input.

The date editor supports three validation types:

Kind	Description
ikStandard	No validation.  This validation type does however support the SmartInput feature via the SmartTextToDate function.
ikMask	Validating by mask. Same as the Delphi Native MaskEdit mask. The validation mask is obtained from the TcxFormatController.StandardDateEditMask property’s value. This validation type doesn’t support the SmartInput feature.
ikRegExpr	Validating using regular expressions and the auto-complete feature. The validation mask is obtained from the TcxFormatController.RegExprDateEditMask property’s value. This validation type supports the SmartInput feature via the SmartTextToDate function.

The default value of the InputKind property is ikMask.


TcxCustomDateEditProperties.Kind

TcxCustomDateEditProperties

Specifies the kind of the dropdown calendar within the editor.

type

  TcxCalendarKind = (ckDate, ckDateTime);

property Kind: TcxCalendarKind;

Description

Use the Kind property to determine the date specific information which is displayed in the editor's dropdown calendar.  The kind specifies which portions of the date editor’s value can edited by an end-user.

The dropdown calendar can be one of the following two kinds:

Kind	Description
ckDate	Only the date portion of the date editor’s value can be edited.
ckDateTime	Both date and time portions of the date editor’s value can be edited.

The default value of the Kind property is ckDate.


TcxCustomDateEditProperties.MaxDate

TcxCustomDateEditProperties

Specifies the upper limit for the entered date.

property MaxDate: TDateTime;

Description

Use the MaxDate property to specify the maximum date that can be entered as the EditValue for a DateEdit.  If the supplied EditValue is greater than the MaxDate property setting, then an exception occurs.


TcxCustomDateEditProperties.MinDate

TcxCustomDateEditProperties

Specifies the lower limit for the entered date.

property MinDate: TDateTime;

Description

Use the MinDate property to specify the minimum date that can be entered as the EditValue for a DateEdit.  If the supplied EditValue is less than the MinDate property setting, then an exception occurs.


TcxCustomDateEditProperties.SaveTime

TcxCustomDateEditProperties

Specifies whether the time stored within the editor’s value is preserved when an end-user modifies the date using an editor or its dropdown calendar.

property SaveTime: Boolean;

Description

If this property is set to False, the time part of the date/time value modified via an editor or its dropdown calendar is truncated (i.e. the fractional part of the value is discarded).

Note:	This property is in effect for date editors that allow only the date part of date/time values to be edited (i.e. the Kind property is set to ckDate).

The default value of the SaveTime property is True.


TcxCustomDateEditProperties.ShowTime

TcxCustomDateEditProperties

Defines whether to display the time portion as well as the date portion of a value.

property ShowTime: Boolean;

Description

The ShowTime property specifies whether to display the time portion, if any, within a date editor when it is not focused.  When focused, only the date portion is displayed and can be edited.

Note:	This property is in effect for date editors that allow only the date part of date/time values to be edited (i.e. the Kind property is set to ckDate).

You can use the Date property to set the date/time value for your editor.

The default value of the ShowTime property is True.


TcxCustomDateEditProperties.WeekNumbers

TcxCustomDateEditProperties          See Also

Specifies whether week numbers are displayed within the editor's dropdown calendar.

property WeekNumbers: Boolean;

Description

Set the WeekNumbers property to True to specify that every week within the editor's dropdown calendar is painted with its corresponding week number.  Otherwise, week numbers will not be displayed.

You can use the TcxFormatController.FirstWeekOfYear property to specify the first week of the year for date editors.

The default value of the WeekNumbers property is False.


TcxCustomDateEditProperties.YearsInMonthList

TcxCustomDateEditProperties          See Also

Specifies whether year values should be displayed in the month list of the editor dropdown calendar.

property YearsInMonthList: Boolean;

Description

The YearsInMonthList property allows you to display or hide year values in the month list of the editor dropdown calendar.  The month list can be displayed while an end user clicks the ‘Month’ field and holds the mouse button down.

The table below shows the resulting month list when various values assigned to the YearsInMonthList property.

Property’s Value	False	True

Note that a year is displayed in either case with the ArrowsForYear property set to False.

An end user can easily select the desired month by using the mouse wheel while the mouse cursor hovers over the ‘Month’ field:

The default value of the YearsInMonthList property is True.


TcxDateEditPropertiesValues
TcxDateEditPropertiesValues Object

Hierarchy          Properties          Methods

Contains the property flags that indicate which properties specific to a date editor have been changed.

Unit

cxCalendar

TcxDateEditPropertiesValues = class(TcxTextEditPropertiesValues);

Description

The TcxDateEditPropertiesValues class tracks the changes made to a date editor’s DateButtons, DisplayFormat, EditFormat, InputKind, MaxLength, MaxValue, MinValue and ReadOnly properties.  Once one of these properties is set to a value other than the default one, the changes are reflected in the TcxDateEditPropertiesValues class (its corresponding property flag is set to True).  To undo the changes made and reverse the property back to its default value, set the corresponding property flag to False or call the RestoreDefaults method to reverse all these properties back to their default values and reset all the property flags.  Use the BeginUpdate and EndUpdate methods to control when the date editor repaints and avoid any flickering when the property flags are modified.


TcxDateEditPropertiesValues Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditPropertiesValues

     |

TcxTextEditPropertiesValues

     |


Properties for TcxDateEditPropertiesValues
TcxDateEditPropertiesValues Properties

TcxDateEditPropertiesValues          Legend

In TcxDateEditPropertiesValues

DateButtons

InputKind

Derived from TcxTextEditPropertiesValues

DisplayFormat

EditFormat

MaxLength

MaxValue

MinValue

Derived from TcxCustomEditPropertiesValues

ReadOnly


Methods for TcxDateEditPropertiesValues
TcxDateEditPropertiesValues Methods

TcxDateEditPropertiesValues          Legend

In TcxDateEditPropertiesValues

RestoreDefaults

Derived from TcxCustomEditPropertiesValues

BeginUpdate

EndUpdate


TcxDateEditPropertiesValues.DateButtons

TcxDateEditPropertiesValues          See Also

Specifies whether the visible state of any of the buttons within the dropdown calendar has been changed.

property DateButtons; Boolean;

Description

Once a date editor’s Properties.DateButtons property is set to a value other than the default one, the DateButtons property flag is set to True.  Otherwise, it’s set to False.  To undo the changes made to the date editor’s Properties.DateButtons property and reverse it back to its default value, call the RestoreDefaults method which resets all the property flags or set the DateButtons property flag to False.


TcxDateEditPropertiesValues.InputKind

TcxDateEditPropertiesValues          See Also

Specifies whether the type of validation used to validate user input has been changed.

property InputKind; Boolean;

Description

Once a date editor’s Properties.InputKind property is set to a value other than the default one, the InputKind property flag is set to True.  Otherwise, it’s set to False.  To undo the changes made to the date editor’s Properties.InputKind property and reverse it back to its default value, call the RestoreDefaults method which resets all the property flags or set the InputKind property flag to False.


TcxDateEditPropertiesValues.RestoreDefaults

TcxDateEditPropertiesValues          See Also

Reverses the values of the properties (changes to which are being tracked) back to their default values.

procedure RestoreDefaults; override;

Description

The RestoreDefaults method undoes any changes made to the properties and resets their values back to the default ones.  Calling this method sets the date editor’s properties being tracked (DateButtons, DisplayFormat, EditFormat, InputKind, MaxLength, MaxValue, MinValue and ReadOnly) to the default values and resets the corresponding property flags to False.  Setting the property flag of each property being tracked to False has the same result as calling the RestoreDefaults method.


TcxDateEdit
 TcxDateEdit Object

Hierarchy          Properties          Methods          Events          See Also

TcxDateEdit is an edit control with a dropdown calendar.

Unit

cxCalendar

TcxDateEdit = class(TcxCustomDateEdit);

Description

The TcxDateEdit class represents an editor which allows the selection and editing of date values.

Similar to other ExpressEditors, the TcxDateEdit class allows the managing of various attributes via the Properties property.  These attributes are the input kind, buttons, the savetime feature and many others.

In addition to entering dates via the dropdown calendar, a date editor allows a user to enter dates within an edit box in a number of ways depending on the Properties.InputKind property.  The following table lists some of the possible formats recognized by a date editor in a system with default English (United States) regional settings.

InputKind value	Examples of dates
ikStandard	01/31 01/31/2002 9-Aug August/09/2002 Smart input strings: today; tomorrow; Sunday; now; bom today–7; now+3
IkMask	01/31/2002
IkRegExpr	01/31/2002 Aug/09/2002 Smart input strings: today; tomorrow; Sunday; now; bom today–7; now+3

If the year is omitted in the ikStandard mode, the current year is assumed.  The syntax in the ikRegExpr mode supports the auto-completion function.  Also validation is performed and this restricts the user input.

Smart input strings are discussed in the SmartTextToDate topic.  See the Using SmartTextToDate Function section to know how to expand possible constants.

Use the Style, StyleDisabled, StyleFocused and StyleHot properties to adjust the look & feel of an editor in various control’s states.

TcxDateEdit publishes many of the properties and methods inherited from TcxCustomDateEdit, but it does not introduce any new behavior.


TcxDateEdit Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomPopupEdit

     |

TcxCustomDateEdit

     |


Properties for TcxDateEdit
TcxDateEdit Properties

TcxDateEdit          Legend

Derived from TcxCustomDateEdit

ActiveProperties

Date

Properties

Derived from TcxCustomPopupEdit

ActiveProperties

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxDateEdit
TcxDateEdit Methods

TcxDateEdit          Legend

Derived from TcxCustomPopupEdit

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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxDateEdit
TcxDateEdit Events

TcxDateEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxDateEditProperties
TcxDateEditProperties Object

Hierarchy          Properties          Methods          Events

Represents properties specific to date editors.

Unit

cxCalendar

TcxDateEditProperties = class(TcxCustomDateEditProperties);

Description

The TcxDateEditProperties class does not introduce any new behavior but merely publishes properties and events inherited from base classes.  To adjust settings for a TcxCustomDateEdit control, use its Properties member.

The DateButtons member defines the buttons displayed within the date editor.  The DateOnError member determines the editor behavior when user input validation fails.  The SaveTime member determines whether the time portion is also stored along with the date.

Note:	The PostPopupValueOnTab property is effective exclusively for the date editors with the Kind property set to ckDate.


TcxDateEditProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |

TcxCustomDropDownEditProperties

     |

TcxCustomPopupEditProperties

     |

TcxCustomDateEditProperties

     |


Properties for TcxDateEditProperties
TcxDateEditProperties Properties

TcxDateEditProperties          Legend

Derived from TcxCustomDateEditProperties

ArrowsForYear

AssignedValues

DateButtons

DateOnError

InputKind

Kind

MaxDate

MinDate

SaveTime

ShowTime

WeekNumbers

YearsInMonthList

Derived from TcxCustomPopupEditProperties

PopupControl

PopupSizeable

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

IncrementalSearch

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 TcxDateEditProperties
TcxDateEditProperties Methods

TcxDateEditProperties          Legend

Derived from TcxCustomMaskEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults


Events for TcxDateEditProperties
TcxDateEditProperties Events

TcxDateEditProperties          Legend

Derived from TcxCustomDropDownEditProperties

OnCloseQuery

OnCloseUp

OnInitPopup

OnPopup

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxDBDateEdit
 TcxDBDateEdit Object

Hierarchy          Properties          Methods          Events          See Also

Represents a data-aware edit control with a dropdown calendar that enables editing date values.

Unit

cxDBEdit

TcxDBDateEdit = class(TcxCustomDateEdit);

Description

The TcxDBDateEdit control allows editing the contents of a datetime dataset field.  Similar to other ExpressDBEditors the TcxDBDateEdit class allows managing various attributes via the Properties property.  These attributes include the input kind, buttons and the savetime feature.

In addition to entering dates via the dropdown calendar, a date editor allows a user to enter dates within an edit box in a number of ways depending on the Properties.InputKind property.  The following table lists some of the possible formats recognized by a date editor in a system with default English (United States) regional settings.

InputKind value	Examples of dates
ikStandard	01/31 01/31/2002 9-Aug August/09/2002 Smart input strings: today; tomorrow; Sunday; now; bom today–7; now+3
ikMask	01/31/2002
ikRegExpr	01/31/2002 Aug/09/2002 Smart input strings: today; tomorrow; Sunday; now; bom today–7; now+3

If the year is omitted in the ikStandard mode, the current year is assumed.  The syntax in the ikRegExpr mode supports the auto-completion function.  Also validation is performed and this restricts the user input.

Smart input strings are discussed in the SmartTextToDate topic.  See the Using SmartTextToDate Function section to know how to expand possible constants.

Use the Style, StyleDisabled, StyleFocused and StyleHot properties to adjust the look & feel of an editor in various control’s states.  Working with styles is discussed in the TcxCustomEditStyle class topic.

To connect a data aware control to a dataset, it is necessary to set the DataSource and DataField properties of the DataBinding object.


TcxDBDateEdit Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomPopupEdit

     |

TcxCustomDateEdit

     |


Properties for TcxDBDateEdit
TcxDBDateEdit Properties

TcxDBDateEdit          Legend

In TcxDBDateEdit

DataBinding

Derived from TcxCustomDateEdit

ActiveProperties

Date

Properties

Derived from TcxCustomPopupEdit

ActiveProperties

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxDBDateEdit
TcxDBDateEdit Methods

TcxDBDateEdit          Legend

Derived from TcxCustomPopupEdit

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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxDBDateEdit
TcxDBDateEdit Events

TcxDBDateEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxDBDateEdit.DataBinding

TcxDBDateEdit

Specifies the connection to a dataset.

property DataBinding: TcxDBEditDataBinding;

Description

Use the DataBinding property to access a TcxDBEditDataBinding instance via which the connection to a dataset is established.  To allow a TcxDBDateEdit control to edit a specific field value from a dataset it is necessary to set the DataSource and DataField properties of the DataBinding object.


scxGridDatePopupClear constant
scxDatePopupClear global constant

Represents the Clear button caption.

Unit

cxCalendar

scxGridDatePopupClear : string = cxSDatePopupClear;

Description

By setting this constant value, you change the Clear button caption within a dropdown calendar of a TcxCustomDateEdit control.


scxGridDatePopupToday constant
scxDatePopupToday global constant

Represents the Today button caption.

Unit

cxCalendar

scxGridDatePopupToday : string = cxSDatePopupToday;

Description

By setting this constant value, you change the Today button caption within a dropdown calendar of a TcxCustomDateEdit control.


cxRadioGroup Unit Overview
cxRadioGroup Unit

Classes

TcxCustomRadioGroup

TcxCustomRadioGroupProperties

TcxRadioButton

TcxRadioGroup

TcxRadioGroupItem

TcxRadioGroupItems

TcxRadioGroupProperties

Other Types

TcxCustomRadioGroupButtonClass


TcxCustomRadioGroup
TcxCustomRadioGroup Object

Hierarchy          Properties          Events          Methods

Implements the basic functionality for radio group controls.

Unit

cxRadioGroup

TcxCustomRadioGroup = class(TcxCustomButtonGroup)

Description

Radio group controls combine a number of radio buttons into a group so that a single button from the group can be selected at a time.  The TcxCustomRadioGroup class implements the basic functionality of such control.  It serves as the ancestor for the TcxRadioGroup and TcxDBRadioGroup editors.

Radio buttons that can be joined in the groups are represented by the TcxRadioButton controls.


TcxCustomRadioGroup Hierarchy
Hierarchy

TcxCustomEdit

     |

TcxCustomGroupBox

     |

TcxCustomButtonGroup

     |


Properties for TcxCustomRadioGroup
TcxCustomRadioGroup Properties

TcxCustomRadioGroup          Legend

In TcxCustomRadioGroup

ActiveProperties

Caption

Buttons

ItemIndex

Properties

Derived from TcxCustomButtonGroup

ActiveProperties

Properties

Derived from TcxCustomGroupBox

Alignment

CaptionBkColor

Derived from TcxCustomEdit

ActiveProperties

AutoSize

DataBinding

EditModified

EditValue

InnerEdit

ModifiedAfterEnter

Properties

RepositoryItem

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxCustomRadioGroup
TcxCustomRadioGroup Methods

TcxCustomRadioGroup          Legend

In TcxCustomRadioGroup

Clear

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCustomRadioGroup
TcxCustomRadioGroup Events

TcxCustomRadioGroup          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCustomRadioGroup.ActiveProperties

TcxCustomRadioGroup          See Also

Obtains the properties that are currently applied to a radio group editor.

property ActiveProperties: TcxCustomRadioGroupProperties;

Description

Use the ActiveProperties property to obtain the properties of the current radio group editor that are currently in effect.  This property is especially useful when the radio group 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 radio group editor.  Otherwise, the inherent radio group editor’s properties are returned.

ReadOnly Property


TcxCustomRadioGroup.Buttons

TcxCustomRadioGroup

Provides access to the radio group items as the standalone radio buttons.

property Buttons[Index: Integer]: TcxRadioButton;

Description

The Buttons property enables you to access the radio group items as the standalone radio buttons.  The accessed button is specified by its zero-based index via the Index parameter.  If the Index parameter value is negative or exceeds the last available index, an exception is raised.

The following code demonstrates how to highlight the selected radio group item with the bold font style.  The OnChange event is handled for this purpose.

procedure TForm1.cxRadioGroup1PropertiesChange(Sender: TObject);

var I: Integer;

begin

  for I := 0 to cxRadioGroup1.Properties.Items.Count - 1 do

  begin

    if (I = cxRadioGroup1.ItemIndex) then

      cxRadioGroup1.Buttons[I].Font.Style := [fsBold]

    else

      cxRadioGroup1.Buttons[I].Font.Style := [];

  end;

end;

ReadOnly Property


TcxCustomRadioGroup.Caption

TcxCustomRadioGroup

Specifies the radio group caption.

property Caption: TCaption;

Description

Use the Caption property to specify or obtain the radio group caption.  The specified string is displayed in the left-top corner of the control, as displayed in the image below.


TcxCustomRadioGroup.ItemIndex

TcxCustomRadioGroup

Indicates which radio button in the group is currently selected.

property ItemIndex: Integer;

Description

The ItemIndex property contains the zero-based index of the selected radio button.  The radio group item representing the selected button can be obtained by this index using the Items property.

The value of ItemIndex property changes at runtime as the user selects radio buttons.  If you want one of the buttons to appear selected when the application starts, assign that button index to the ItemIndex property at design time; otherwise, leave the ItemIndex property set to the default value of -1, which means that no button is selected.

The default value of the ItemIndex property is -1.


TcxCustomRadioGroup.Properties

TcxCustomRadioGroup

Defines settings specific to radio groups.

property Properties: TcxCustomRadioGroupProperties;

Description

The Properties property is used to access various settings for radio groups.  These settings define the radio group items (the Items property), column count (the Columns property), etc.  Please refer to the TcxCustomRadioGroupProperties class description for details.


TcxCustomRadioGroup.Clear

TcxCustomRadioGroup

Removes all radio buttons from the radio group.

procedure Clear; override;

Description

Use this method to remove all radio buttons from the radio group. The Clear method destroys all item instances and frees the occupied memory.


TcxCustomRadioGroupProperties
TcxCustomRadioGroupProperties Object

Hierarchy          Properties          Methods          Events

Contains settings common for all radio groups.

Unit

cxRadioGroup

TcxCustomRadioGroupProperties = class(TcxCustomButtonGroupProperties)

Description

The TcxCustomRadioGroupProperties class provides the set of settings common to all radio groups that are TcxCustomRadioGroup descendants.  It is the base class for the TcxRadioGroupProperties class, which represents the type of the radio group controls’ Properties property.

The visual settings provided by the TcxCustomRadioGroupProperties class are the control’s caption, its collection of items, the number of columns into which items are arranged, and word wrapping.


TcxCustomRadioGroupProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomGroupBoxProperties

     |

TcxCustomButtonGroupProperties

     |


Properties for TcxCustomRadioGroupProperties
TcxCustomRadioGroupProperties Properties

TcxCustomRadioGroupProperties          Legend

In TcxCustomRadioGroupProperties

DefaultCaption

DefaultValue

Items

Derived from TcxCustomButtonGroupProperties

Columns

Items

WordWrap

Derived from TcxCustomEditProperties

Alignment

AutoSelect

BeepOnError

Buttons

ButtonsViewStyle

ClearKey

ClickKey

ImmediatePost

ReadOnly

UseLeftAlignmentOnEditing

UseMouseWheel

ValidateOnEnter


Methods for TcxCustomRadioGroupProperties
TcxCustomRadioGroupProperties Methods

TcxCustomRadioGroupProperties          Legend

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCustomRadioGroupProperties
TcxCustomRadioGroupProperties Events

TcxCustomRadioGroupProperties          Legend

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomRadioGroupProperties.DefaultCaption

TcxCustomRadioGroupProperties

Specifies the display value for a radio group when no item is selected.

property DefaultCaption: WideString;

Description

The DefaultCaption property is used when a radio group serves as an in-place editor. It specifies the display value of the editor when none of the radio buttons within the group are selected. In ExpressQuantumGrid, this display value is used in the following two cases:

•	When exporting grid's data. Cells of columns that use the radio group editor are exported in the following manner. If a radio button is selected, its caption is written into the destination file (to the corresponding cell of the XLS file, for instance). If none of buttons are selected, the DefaultCaption property value is written to the corresponding cell of the target file.

•	When using filter dropdowns for columns. The DefaultCaption property value is displayed within the filter dropdown of columns that use radio groups.  When clicking this item, the grid displays only those records which have no radio buttons selected in the corresponding column.


TcxCustomRadioGroupProperties.DefaultValue

TcxCustomRadioGroupProperties

Represents the radio group edit value when no item is checked.

type

  TcxEditValue = Variant;

property DefaultValue: TcxEditValue;

Description

Use the DefaultValue property to specify the edit value when no item is checked.  (The edit value can be obtained via the EditValue property of the editor).  If an item is checked, the radio group’s edit value is specified by the Value property of the corresponding item.


TcxCustomRadioGroupProperties.Items

TcxCustomRadioGroupProperties

Provides access to the collection of items within the radio group control.

property Items: TcxRadioGroupItems;

Description

Use the Items property to access the collection of items within the radio group.  You can use the obtained object to add, move or delete individual items.  Moreover, the collection provides access to individual items, so you can specify their captions and associated values.


TcxRadioButton
 TcxRadioButton Object

Hierarchy          Properties

Represents the radio button control.

Unit

cxRadioGroup

TcxRadioButton = class(TRadioButton)

Description

The TcxRadioButton object represents an advanced version of the TRadioButton control.  It inherits all ancestor functionality and adds two features, enhancing the look & feel of a control.

The LookAndFeel property specifies the look & feel settings for a radio button. The default settings can be obtained from the operating system color scheme (the LookAndFeel.NativeStyle property has True value).  If not, then the radio button control is painted in one of the predefined painted styles, as specified by the LookAndFeel.Kind property.

The WordWrap property determines whether the radio button caption is wrapped when it is too long to display within the radio button bounds.

The following image demonstrates checked radio button in UltraFlat painting style:


TcxRadioButton Hierarchy
Hierarchy

TRadioButton

     |


Properties for TcxRadioButton
TcxRadioButton Properties

TcxRadioButton          Legend

In TcxRadioButton

LookAndFeel

WordWrap


TcxRadioButton.LookAndFeel

TcxRadioButton

Specifies the look & feel of a TcxRadioButton control.

property LookAndFeel: TcxLookAndFeel;

Description

Use the LookAndFeel property to specify the default look & feel of a radio button control.

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

If LookAndFeel.NativeStyle is set to False, then the LookAndFeel.Kind property specifies the default look and feel of a radio button.  The styles enumerated by the TcxLookAndFeel type determine the manner in which the radio button is painted and how it responds to mouse events.


TcxRadioButton.WordWrap

TcxRadioButton

Specifies whether the radio button caption is wrapped, if it is too long.

property WordWrap: Boolean;

Description

Setting the WordWrap property to True enables text wrapping within the radio button caption. Text wrapping occurs when the radio button width is not enough to fit its caption.  If the WordWrap property value is False, then the radio button caption occupies a single line, regardless of whether the caption fits into the control.

An example of the wrapped radio button caption is demonstrated below:

The default value of the WordWrap property is False.


TcxRadioGroup
 TcxRadioGroup Object

Hierarchy          Properties          Methods          Events

Represents a container for radio buttons, functioning together.

Unit

cxRadioGroup

TcxRadioGroup = class(TcxCustomRadioGroup)

Description

The TcxRadioGroup object represents a number of grouped radio buttons.  Grouped radio buttons affect each other – if a user checks one, the others become unchecked.

The collection of radio buttons in the radio group is represented by the Properties.Items property.  You can access the collection to add, move and delete individual items using the methods it provides.  Each item in the collection is represented by the TcxRadioGroupItem object.  You can use the Caption property of this object to change the caption displayed beside the button.

Each item also has the Value property, which represents the EditValue of the radio group control.  When you click the radio buttons, included into a group, that group’s EditValue accepts the Value property value of the checked button.  And vice versa, supplying an EditValue checks an item, whose Value property matches the supplied EditValue.

Note:	when the selected item’s Value property is equal to NULL, the radio group’s EditValue property returns the caption of the selected item.

The EditValue of the radio group is also affected by the ItemIndex property.  If the ItemIndex property value is –1 (which means, that no item is selected within a group), then the EditValue accepts the value of the Properties.DefaultValue property.

You can specify the appearance and functionality of a radio group by the Properties and Style properties.

The following image demonstrates a radio group control, containing four items:


TcxRadioGroup Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomGroupBox

     |

TcxCustomButtonGroup

     |

TcxCustomRadioGroup

     |


Properties for TcxRadioGroup
TcxRadioGroup Properties

TcxRadioGroup          Legend

Derived from TcxCustomRadioGroup

ActiveProperties

Buttons

Caption

ItemIndex

Properties

Derived from TcxCustomButtonGroup

ActiveProperties

Properties

Derived from TcxCustomGroupBox

Alignment

CaptionBkColor

Derived from TcxCustomEdit

ActiveProperties

AutoSize

DataBinding

EditModified

EditValue

InnerEdit

ModifiedAfterEnter

Properties

RepositoryItem

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TControl

Align


Methods for TcxRadioGroup
TcxRadioGroup Methods

TcxRadioGroup          Legend

Derived from TcxCustomRadioGroup

Clear

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxRadioGroup
TcxRadioGroup Events

TcxRadioGroup          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxRadioGroupItem
TcxRadioGroupItem Object

Hierarchy          Properties

Represents an individual radio button in a radio group.

Unit

cxRadioGroup

TcxRadioGroupItem = class(TcxButtonGroupItem)

Description

The TcxRadioGroupItem object represents a radio button in a group.  The Caption property value of that object specifies the text displayed beside the radio button within a group.  The Value property specifies the EditValue of the owning radio group when this item is selected.


TcxRadioGroupItem Hierarchy
Hierarchy

TCollectionItem

     |

TcxButtonGroupItem

     |


Properties for TcxRadioGroupItem
TcxRadioGroupItem Properties

TcxRadioGroupItem          Legend

In TcxRadioGroupItem

Value

Derived from TcxButtonGroupItem

Caption

Enabled

Tag


TcxRadioGroupItem.Value

TcxRadioGroupItem

Represents the radio group’s EditValue when the current item is checked.

type

  TcxEditValue = Variant;

property Value: TcxEditValue;

Description

The Value property of a radio group item represents the EditValue of the radio group control.  When you click the radio buttons, included into a group, that group’s EditValue accepts the Value property value of the checked button.  And vice versa, supplying an EditValue checks an item, whose Value property matches the supplied EditValue.

The EditValue of the radio group is also affected by the ItemIndex property.  If the ItemIndex property value is –1 (which means, that no item is selected within a group), then the EditValue accepts the value of the Properties.DefaultValue property.


TcxRadioGroupItems
TcxRadioGroupItems Object

Hierarchy          Properties

Represents the collection of radio buttons owned by a radio group.

Unit

cxRadioGroup

TcxRadioGroupItems = class(TcxButtonGroupItems)

Description

The TcxRadioGroup control owns the collection of items (radio buttons).  Use the Properties.Items property to access this collection.  The items collection is represented by the TcxRadioGroupItems class instance.

Each item in the collection is represented by a TcxRadioGroupItem class instance.  You can access individual items using the Items property.


TcxRadioGroupItems Hierarchy
Hierarchy

TOwnedCollection

     |

TcxButtonGroupItems

     |


Properties for TcxRadioGroupItems
TcxRadioGroupItems Properties

TcxRadioGroupItems          Legend

In TcxRadioGroupItems

Items

Derived from TcxButtonGroupItems

Items


TcxRadioGroupItems.Items

TcxRadioGroupItems

Provides indexed access to individual radio group items.

property Items[Index: Integer]: TcxRadioGroupItem;

Description

Use the Items property to access radio buttons in the Properties.Items collection of a radio group.  Radio group items are represented by the TcxRadioGroupItem objects.   Properties of these objects specify the caption of an item and the EditValue for the radio group when the item is checked.


TcxRadioGroupProperties
TcxRadioGroupProperties Object

Hierarchy          Properties          Methods          Events

Contains settings specific to radio group controls.

Unit

cxRadioGroup

TcxRadioGroupProperties = class(TcxCustomRadioGroupProperties)

Description

The TcxRadioGroupProperties object represents attributes common to all radio group controls.  These attributes can be accessed by the cxRadioGroup.Properties property.

The properties of the TcxRadioGroupProperties class specify:

•	the radio group caption;

•	the arrangement of radio buttons within a group.  The arrangement is determined by the number of columns in which the buttons are positioned;

•	the collection of items displayed within a group;

•	the default EditValue, returned when no item is checked within a group;

•	the item caption wrapping, if it is too long to fit the item width.

To control any changes made to the control’s ReadOnly property and reverse its value back to the default one, use the AssignedValues property.

All the functionality of the TcxRadioGroupProperties object is implemented by its ancestor.  The object simply publishes some of the properties.


TcxRadioGroupProperties Hierarchy
Hierarchy

TcxCustomEditProperties

     |

TcxCustomGroupBoxProperties

     |

TcxCustomButtonGroupProperties

     |

TcxCustomRadioGroupProperties

     |


Properties for TcxRadioGroupProperties
TcxRadioGroupProperties Properties

TcxRadioGroupProperties          Legend

Derived from TcxCustomRadioGroupProperties

DefaultCaption

DefaultValue

Items

Derived from TcxCustomButtonGroupProperties

Columns

Items

WordWrap

Derived from TcxCustomEditProperties

Alignment

AssignedValues

AutoSelect

BeepOnError

Buttons

ButtonsViewStyle

ClearKey

ClickKey

ImmediatePost

ReadOnly

UseLeftAlignmentOnEditing

UseMouseWheel

ValidateOnEnter


Methods for TcxRadioGroupProperties
TcxRadioGroupProperties Methods

TcxRadioGroupProperties          Legend

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxRadioGroupProperties
TcxRadioGroupProperties Events

TcxRadioGroupProperties          Legend

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomRadioGroupButtonClass
TcxCustomRadioGroupButtonClass type

Represents the type of radio buttons used within a radio group.

Unit

cxRadioGroup

type

  TcxCustomRadioGroupButtonClass = class of TcxCustomRadioGroupButton;

Description

If you need a specific functionality of radio buttons included into the group, you can create a descendant of the TcxCustomRadioGroupButton class.  After such a class is declared you can use it to represent buttons within radio group controls.  For this purpose, you need to create a descendant of the TcxCustomRadioGroup class (your own radio group control) and override its GetButtonClass method.  This method’s return value is of the TcxCustomRadioGroupButtonClass type (the type of the radio button descendant).  You need to return your custom button class in this method.  In this case, the created radio group descendant control will use custom radio buttons.


TcxDBRadioGroup
 TcxDBRadioGroup Object

Hierarchy          Properties          Methods          Events

Represents a data-aware version of the radio group control.

Unit

cxDBEdit

TcxDBRadioGroup = class(TcxCustomRadioGroup)

Description

The TcxDBRadioGroup object represents a data-aware version of the radio group control.  It inherits all basic functionality from its ancestor – TcxCustomRadioGroup class.

The data-aware functionality is encapsulated within the DataBinding property.  It allows you to specify the DataSource and the DataField to which an editor is bound.  The values of the data field specified by the DataBinding.DataField property must correspond to the Value property value of the radio buttons included into a group.  If the bound field’s value matches a value of a radio button within the group, this item appears selected.  If the field value doesn’t match any of item values, none of buttons in the radio group are selected.


TcxDBRadioGroup Hierarchy
Hierarchy

TCustomControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomGroupBox

     |

TcxCustomButtonGroup

     |

TcxCustomRadioGroup

     |


Properties for TcxDBRadioGroup
TcxDBRadioGroup Properties

TcxDBRadioGroup          Legend

In TcxDBRadioGroup

DataBinding

Derived from TcxCustomRadioGroup

ActiveProperties

Buttons

ItemIndex

Properties

Derived from TcxCustomButtonGroup

ActiveProperties

Properties

Derived from TcxCustomGroupBox

Alignment

CaptionBkColor

Derived from TcxCustomEdit

ActiveProperties

AutoSize

DataBinding

EditModified

EditValue

InnerEdit

ModifiedAfterEnter

Properties

RepositoryItem

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TControl

Align


Methods for TcxDBRadioGroup
TcxDBRadioGroup Methods

TcxDBRadioGroup          Legend

Derived from TcxCustomRadioGroup

Clear

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxDBRadioGroup
TcxDBRadioGroup Events

TcxDBRadioGroup          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxDBRadioGroup.DataBinding

TcxDBRadioGroup

Binds the data aware radio group control to a dataset field.

property DataBinding: TcxDBEditDataBinding;

Description

The data-aware functionality of a TcxDBRadioGroup object is encapsulated within the DataBinding property.  This property represents a TcxDBEditDataBinding object.  It allows specifying the DataSource and the DataField to which an editor is connected.  The values of the data field specified by the DataBinding.DataField property must correspond to the Value property value of the radio buttons included into a group.  The radio group item, whose value matches the current field value appears selected within the group.


cxLookupEdit Unit Overview
cxLookupEdit Unit

Classes

TcxCustomLookupEdit

TcxCustomLookupEditProperties


TcxCustomLookupEdit
TcxCustomLookupEdit Object

Hierarchy          Properties          Methods          Events          See Also

Represents the base class for lookup editors.

Unit

cxLookupEdit

TcxCustomLookupEdit = class(TcxCustomComboBox);

Description

The TcxCustomLookupEdit class is the base class for all classes implementing lookup functionality for a combo box.  All settings required for the lookup functionality of an editor are stored in the Properties member.  It specifies only base settings:

•	the DropDownAutoSize property determines whether the dropdown window is automatically resized in order to fit all dropdown columns in the best way possible

•	the DropDownWidth property specifies the fixed width of the dropdown window

•	the IncrementalFiltering property enables/disables an incremental filtering of records within the dropdown window

The TcxCustomDBLookupEdit class derives from TcxCustomLookupEdit and declares additional properties common to LookupComboBox and ExtLookupComboBox controls.

For further explanations, see the description of the TcxCustomDBLookupEdit class in this help system.


TcxCustomLookupEdit Hierarchy
Hierarchy

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomComboBox

     |


Properties for TcxCustomLookupEdit
TcxCustomLookupEdit Properties

TcxCustomLookupEdit          Legend

In 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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxCustomLookupEdit
TcxCustomLookupEdit Methods

TcxCustomLookupEdit          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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCustomLookupEdit
TcxCustomLookupEdit Events

TcxCustomLookupEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCustomLookupEdit.ActiveProperties

TcxCustomLookupEdit          See Also

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

property ActiveProperties: TcxCustomLookupEditProperties;

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


TcxCustomLookupEdit.Properties

TcxCustomLookupEdit

Contains settings specific to lookup editors.

property Properties: TcxCustomLookupEditProperties;

Description

Use the Properties property to specify a set of options controlling the lookup editor behavior.  These settings allow you to specify:

•	the width of an editor’s dropdown window

•	Automatic calculation of the dropdown width

•	the ability to perform incremental filtering


TcxCustomLookupEditProperties
TcxCustomLookupEditProperties Object

Hierarchy          Properties          Methods          Events          See Also

Contains settings specific to lookup editors.

Unit

cxLookupEdit

TcxCustomLookupEditProperties = class(TcxCustomComboBoxProperties);

Description

The TcxCustomLookupEditProperties object contains settings determining the lookup editor’s behavior.  These settings allow you to specify:

•	the width and height of an editor’s dropdown window

•	Automatic calculation of the dropdown width

•	the ability to perform incremental filtering


TcxCustomLookupEditProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |

TcxCustomDropDownEditProperties

     |

TcxCustomComboBoxProperties

     |


Properties for TcxCustomLookupEditProperties
TcxCustomLookupEditProperties Properties

TcxCustomLookupEditProperties          Legend

In 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

IncrementalSearch

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 TcxCustomLookupEditProperties
TcxCustomLookupEditProperties Methods

TcxCustomLookupEditProperties          Legend

Derived from TcxCustomMaskEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults


Events for TcxCustomLookupEditProperties
TcxCustomLookupEditProperties Events

TcxCustomLookupEditProperties          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


TcxCustomLookupEditProperties.DropDownAutoSize

TcxCustomLookupEditProperties          See Also

Determines whether an editor’s dropdown window is resized in order to entirely display lookup columns.

property DropDownAutoSize: Boolean;

Description

Use the DropDownAutoSize property to determine whether an editor’s dropdown window is resized to entirely display lookup columns.  If the editor’s dropdown window contains several lookup columns, these columns may be too wide to be displayed fully.  To avoid this, set DropDownAutoSize to False and specify the required window’s width via the DropDownWidth property.

If DropDownAutoSize is False and the DropDownWidth property value is 0 (the default), the dropdown window width is equal to the editor width.

The default value of the DropDownAutoSize property is False.


TcxCustomLookupEditProperties.DropDownHeight

TcxCustomLookupEditProperties          See Also

Indicates the height of the dropdown window in pixels.

property DropDownHeight: Integer;

Description

You can use the DropDownHeight property to limit the height of the dropdown window.  If DropDownHeight is set to 0, the window’s height is determined by the DropDownRows property which specifies the maximum number of visible rows in the dropdown.  If DropDownHeight is set to a value greater than 0, the DropDownRows property is ignored and DropDownHeight defines the height of the dropdown in pixels.

See the DropDownSizeable property to enable sizing of the dropdown at runtime.

The default value of the DropDownHeight property is 0.


TcxCustomLookupEditProperties.DropDownListStyle

TcxCustomLookupEditProperties

Specifies the lookup editor’s behavior during text input.

type

  TcxEditDropDownListStyle = (lsEditFixedList, lsEditList, lsFixedList);

property DropDownListStyle: TcxEditDropDownListStyle;

Description

Use the DropDownListStyle property to specify the manner in which a lookup editor reacts to characters input.

Value	Meaning
lsEditFixedList	Text input is allowed and the entered text is automatically completed if it matches one of the words from the lookup editor’s dropdown window.  Entering new values is prohibited.
lsEditList	Text input is allowed and the entered text is automatically completed if it matches one of the words from the lookup editor’s dropdown window.  New values can be entered.
lsFixedList	Text input is prohibited. The lookup editor can only navigate through the values stored within its popup.

The lookup editor’s dropdown window is activated during text input regardless of the DropDownListStyle property settings.

The default value of the DropDownListStyle property is lsEditFixedList.


TcxCustomLookupEditProperties.DropDownWidth

TcxCustomLookupEditProperties          See Also

Specifies the width of an editor’s dropdown window.

property DropDownWidth: Integer;

Description

Use the DropDownWidth property to specify the width of an editor’s dropdown window.  The default property value means that the editor’s dropdown window width is equal to the editor’s Width property.  If the DropDownAutoSize property value is True, the DropDownWidth property is ignored.

The default value of the DropDownWidth property is 0.


TcxCustomLookupEditProperties.IncrementalFiltering

TcxCustomLookupEditProperties

Determines whether the incremental filtering feature is active.

property IncrementalFiltering: Boolean;

Description

Use the IncrementalFiltering property to activate the lookup editor feature of the same name.  When a user types within the edit box, a lookup editor implements an incremental search against the field displayed in the edit region.  During typing, the editor’s dropdown window opens and locates the first record whose field value starts with the characters typed.  If the IncrementalFiltering property value is True, the lookup editor filters records within the list based on the first characters typed into the editor.

To specify a field displayed in the edit box and against which the incremental search/filtering is performed, use the ListFieldIndex property (declared in the TcxCustomDBLookupEditProperties class containing properties for both LookupEditors and ExtLookupEditors).  For ExtLookupEditors, you have to use the ListFieldItem property instead.

Note: You may input text into a lookup editor only if the Properties.DropDownListStyle property value is not IsFixedList.

The default value of the IncrementalFiltering property is True.


cxDBLookupEdit Unit Overview
cxDBLookupEdit Unit

Classes

TcxCustomDBLookupEdit

TcxCustomDBLookupEditProperties


TcxCustomDBLookupEdit
TcxCustomDBLookupEdit Object

Hierarchy          Properties          Methods          Events

Represents the base class for LookupComboBox and ExtLookupComboBox controls.

Unit

cxDBLookupEdit

TcxCustomDBLookupEdit = class(TcxCustomLookupEdit);

Description

The TcxCustomDBLookupEdit object represents the base class for lookup editors (TcxCustomLookupComboBox and TcxCustomExtLookupComboBox) displaying values from a data source within a dropdown window.  For a LookupComboBox editor, the data source is specified by its Properties.ListSource attribute.  An ExtLookupComboBox displays a data-aware (banded) table view in its dropdown, and the data source is identified by this view.

TcxCustomDBLookupComboBox provides settings common to both LookupComboBox and ExtLookupComboBox editors.  To access them, use the Properties object.

Data source fields are identified by the Properties.ListFieldNames property value.  For LookupComboBox editors, you can use this property to specify fields to display in the dropdown window.  For each field, a column in the dropdown is created.  The alternative way is to add columns directly via the Properties.ListColumns collection.

A data source field whose value is displayed within the editor’s edit box is determined via the Properties.ListFieldIndex property.  It represents the zero-based index of a field within the Properties.ListFieldNames list.

For ExtLookupComboBox controls, this property is read-only.  You can specify the field to display in the edit box via the Properties.ListFieldItem attribute.

The editor’s EditValue property value matches the value(s) of the data source key field(s) (identified via the Properties.KeyFieldNames property), corresponding to the record containing the currently displayed value.  A user can specify the edit value manually, but if there is no corresponding record in a data source, the editor displays nothing.

Lookup combo box editors support the incremental search feature.  When a user types within the edit region, the editor activates the dropdown window and locates the first value within the dropdown list whose first characters match the typed characters.  If the Properties.IncrementalFiltering property value is True, the editor filters the dropdown list values based on the first typed characters.


TcxCustomDBLookupEdit Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomComboBox

     |

TcxCustomLookupEdit

     |


Properties for TcxCustomDBLookupEdit
TcxCustomDBLookupEdit Properties

TcxCustomDBLookupEdit          Legend

In 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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading


Methods for TcxCustomDBLookupEdit
TcxCustomDBLookupEdit Methods

TcxCustomDBLookupEdit          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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCustomDBLookupEdit
TcxCustomDBLookupEdit Events

TcxCustomDBLookupEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCustomDBLookupEdit.ActiveProperties

TcxCustomDropDownEdit           See Also

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

property ActiveProperties: TcxCustomDBLookupEditProperties;

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


TcxCustomDBLookupEdit.Properties

TcxCustomDBLookupEdit

Contains settings controlling the behavior of lookup editors.

property Properties: TcxCustomDBLookupEditProperties;

Description

Use the attributes of the Properties object to customize the lookup editor.  You can specify:

•	the fields (the ListFieldNames property) to display in the dropdown window (every field is represented by a column);

•	the field (the ListFieldIndex property) whose value is displayed within the editor’s edit region;

•	the fields (the KeyFieldNames property) whose values match the edit value(s) of the lookup editor.

LookupComboBox and ExtLookupComboBox controls provide additional properties to customize lookup editors.


TcxCustomDBLookupEditProperties
TcxCustomDBLookupEditProperties Object

Hierarchy          Properties          Methods          Events          See Also

Represents a set of properties controlling the behavior of lookup editors.

Unit

cxDBLookupEdit

TcxCustomDBLookupEditProperties = class(TcxCustomLookupEditProperties);

Description

The TcxCustomDBLookupEditProperties class provides properties common to both LookupComboBox and ExtLookupComboBox controls.  These controls extend the functionality of the TcxCustomDBLookupEditProperties class by declaring additional properties.

A lookup editor displays a set of records obtained from a data source in its dropdown window.  For a LookupComboBox editor, the data source is specified by its Properties.ListSource attribute.  An ExtLookupComboBox displays a data-aware (banded) table view in its dropdown, and the data source is identified by this view.

The TcxCustomDBLookupEditProperties allows you to specify a list of fields displayed in the dropdown window via the ListFieldNames property.  For a LookupComboBox editor you can do the same via its Properties.ListColumns property.  The ExtLookupComboBox control displays a data-aware (banded) table view in the dropdown.  So you are able to specify the visibility and group position of each column via the view’s properties.

When a user selects a specific record from the dropdown window, this changes the edit value of the lookup editor and display text.  The display text is defined by the selected record’s field whose index is set via the ListFieldIndex property.  The editor’s edit value is obtained from the record’s field(s) identified by the KeyFieldNames property.  If you specify several fields via the KeyFieldNames property, the edit value will hold an array of variants.  The edit value is accessible via the editor’s EditValue property.  Changing it results in selecting a record whose key field values (KeyFieldNames) match the edit value(s).  The CaseSensitiveSearch property allows you to specify whether the matching is case sensitive.


TcxCustomDBLookupEditProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |

TcxCustomDropDownEditProperties

     |

TcxCustomComboBoxProperties

     |

TcxCustomLookupEditProperties

     |


Properties for TcxCustomDBLookupEditProperties
TcxCustomDBLookupEditProperties Properties

TcxCustomDBLookupEditProperties          Legend

In 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

IncrementalSearch

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 TcxCustomDBLookupEditProperties
TcxCustomDBLookupEditProperties Methods

TcxCustomDBLookupEditProperties          Legend

Derived from TcxCustomMaskEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults


Events for TcxCustomDBLookupEditProperties
TcxCustomDBLookupEditProperties Events

TcxCustomDBLookupEditProperties          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


TcxCustomDBLookupEditProperties.CaseSensitiveSearch

TcxCustomDBLookupEditProperties

Specifies whether the matching of the key field value(s) with edit value(s) is case sensitive.

property CaseSensitiveSearch: Boolean;

Description

By default, a lookup editor performs a case-sensitive record search using the edit value(s).  To improve performance when working with large datasets, set the CaseSensitiveSearch property to True.

The default value of the CaseSensitiveSearch property is False.


TcxCustomDBLookupEditProperties.DataController

TcxCustomDBLookupEditProperties

Provides access to the data controller managing the bound control’s connection to a data store.

property DataController: TcxDBDataController;

Description

A data controller is the object which manages the bound control’s connection to a data store.  It implements the retrieval and posting of data and performs data manipulation operations such as grouping and filtering.

ReadOnly Property


TcxCustomDBLookupEditProperties.KeyFieldNames

TcxCustomDBLookupEditProperties

Specifies the name(s) of the data source field(s) whose values identify data source records.

property KeyFieldNames: string;

Description

Use the KeyFieldNames property to specify the names of the data source fields whose values are used to identify records.  These field values match the editor’s edit value(s) accessible via the EditValue property.

For data-aware lookup editors (TcxDBLookupComboBox and TcxDBExtLookupComboBox), a field defined by the KeyFieldNames property also matches the field set via the editor’s DataBinding.DataField property.

When a user selects a specific record from the lookup editor’s dropdown window, this changes the edit value and display text.  The editor’s edit value is obtained from the selected record’s field(s) identified by the KeyFieldNames property.  The edit value is then used to modify the DataBinding.DataField value (for data-aware editors).

Conversely, changing the edit value programmatically or the DataBinding.DataField value (for data-aware editors only) results in selecting a record whose key field values (KeyFieldNames) match the edit value(s).

Note:	To improve performance when working with large datasets, set the CaseSensitiveSearch property to True.


TcxCustomDBLookupEditProperties.ListField

TcxCustomDBLookupEditProperties

Provides access to the dropdown list field whose value is displayed within the editor’s edit box.

property ListField: TField;

Description

Use the ListFieldIndex property to specify the dropdown list field whose value needs to be displayed within the editor’s edit box.  This index is a zero-based index of a field within the ListFieldNames list.

ReadOnly Property


TcxCustomDBLookupEditProperties.ListFieldIndex

TcxCustomDBLookupEditProperties

Specifies the index of the dropdown list field whose value is displayed within the editor’s edit box.

property ListFieldIndex: Integer;

Description

Use the ListFieldIndex property to specify the index of the dropdown list field whose value is displayed within an editor during text input or when a user navigates through a data source or the editor’s dropdown list.  This index is a zero-based index of a field within the ListFieldNames list.

For ExtLookupComboBox editors, you are not able to change the ListFieldIndex property.  Instead, you should use the editor’s Properties.ListFieldItem attribute to specify a column within the editor’s dropdown view whose value is displayed in the edit box.

The default value of the ListFieldIndex property is 0.


TcxCustomDBLookupEditProperties.ListFieldNames

TcxCustomDBLookupEditProperties

Specifies the list of data source fields whose values are displayed within the dropdown list of an editor.

property ListFieldNames: string;

Description

Use the ListFieldNames property to specify the list of data source fields displayed within the editor’s dropdown list.  To specify several field names, delimit them with semicolons.

For each field added via the ListFieldNames property, a column in the lookup editor’s dropdown window will be created.

For a LookupComboBox control, an alternative way to specify fields to display in the dropdown window is to add columns via the editor’s Properties.ListColumns collection.

For an ExtLookupComboBox editor, which displays a grid view in its dropdown window, columns are retrieved from this view.  All columns can be accessed via the editor’s Properties.View.Items collection.

If a user adds the name of the existing data source field to the ListFieldNames property value, then an additional column is added.  If the field name is removed from ListFieldNames, an appropriate column is removed as well.

To specify the source of records to display in the dropdown window, see:

•	the ListSource property for LookupComboBox controls;

•	the View property for ExtLookupComboBox editors.


cxDBLookupComboBox Unit Overview

Classes

TcxCustomLookupComboBox

TcxDBLookupComboBox

TcxLookupComboBox

TcxLookupComboBoxProperties


TcxCustomLookupComboBox
TcxCustomLookupComboBox Object

Hierarchy          Properties          Methods          Events

Represents the base class for TcxLookupComboBox and TcxDBLookupComboBox controls.

Unit

cxDBLookupComboBox

TcxCustomLookupComboBox = class(TcxCustomDBLookupEdit);

Descrip`tion

The TcxCustomLookupComboBox object represents the base class for the lookup editors displaying values from a data source within a dropdown list.  The data source is specified via the Properties.ListSource property.  The ListSource field values are displayed within an editor dropdown window.

Fields, whose values are displayed within a dropdown window, are identified via the Properties.ListFieldNames property value.  Each field has a corresponding column within the editor dropdown window and in the Properties.ListColumns collection.  A data source field whose value is displayed and edited within the editor’s edit box is determined via the Properties.ListFieldIndex property.  This property in turn represents the index of the required field within the Properties.ListFieldNames list (or Properties.ListColumns collection).

The EditValue property value matches the value of the data source key field (identified via the Properties.KeyFieldNames property), corresponding to the record containing the currently displayed value.  A user can specify EditValue manually, but if the EditValue property value does not have the corresponding record in a data source, the editor displays nothing.

Lookup combo box editors support the incremental search feature.  When a user types within the edit region, the editor activates the dropdown window and locates the first value within the dropdown list whose first characters match the typed characters.  If the Properties.IncrementalFiltering property value is True, the editor filters the dropdown list values based on the first typed characters.


TcxCustomLookupComboBox Hierarchy
Hierarchy

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomComboBox

     |

TcxCustomLookupEdit

     |

TcxCustomDBLookupEdit

     |


Properties for TcxCustomLookupComboBox
TcxCustomLookupComboBox Properties

TcxCustomLookupComboBox          Legend

In TcxCustomLookupComboBox

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxCustomLookupComboBox
TcxCustomLookupComboBox Methods

TcxCustomLookupComboBox          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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCustomLookupComboBox
TcxCustomLookupComboBox Events

TcxCustomLookupComboBox          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCustomLookupComboBox.ActiveProperties

TcxCustomLookupComboBox          See Also

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

property ActiveProperties: TcxLookupComboBoxProperties;

Description

Use the ActiveProperties property to obtain the properties of the current lookup combo box editor that are currently in effect.  This property is especially useful when the lookup combo box 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 combo box editor.  Otherwise, the inherent lookup combo box editor’s properties are returned.

ReadOnly Property


TcxCustomLookupComboBox.EditValue

TcxCustomLookupComboBox

Specifies the value being edited by the editor.

property EditValue: Variant;

Description

A lookup editor allows you to edit a value by picking up a record in the dropdown list which displays data from the ListSource datasource.  The edit value matches the value of the selected record’s field identified by the KeyFieldNames property.  The display value is obtained from the record’s field whose index is specified by the ListFieldIndex property.

Changing the edit value results in selecting another record from the ListSource datasource whose key field value matches the edit value.  You can see the visual effect of this in a change of the display text.

If the KeyFieldNames property specifies several fields delimited by semicolons, the EditValue property will hold an array of variants.


TcxCustomLookupComboBox.Properties

TcxCustomLookupComboBox

Contains settings controlling the behavior of a lookup combo box control.

property Properties: TcxLookupComboBoxProperties;

Description

Use the Properties property to specify settings controlling the behavior of a lookup combo box control.

The ListSource property specifies the lookup data source whose field values are displayed within the lookup combo box’s dropdown window.  The ListFieldNames property specifies which ListSource fields are displayed within it.  Setting this property creates columns within the dropdown window.  Alternatively, you can use the ListColumns property to create columns to display in the dropdown window.  Adding and removing columns via ListColumns is automatically reflected in the ListFieldNames property and vice versa.

The ListFieldIndex property addresses the data source field whose value is displayed in the editor’s edit box.  The KeyFieldNames property specifies the lookup data source field(s) whose values are used to identify data source records.  These field values match the edit value(s) (accessible via the editor’s EditValue property) and the value of the DataBinding.DataField field (for a data-aware lookup combo box).


TcxCustomLookupComboBox.Text

TcxCustomLookupComboBox

Specifies the text displayed within the edit region.

property Text: TCaption;

Description

Use the Text property to specify the text displayed within the edit region.  Setting this property programmatically is similar to locating a record within the data source whose specific field value is equal to the Text property.  The data source field to locate is identified via the ListFieldIndex property value, which represents the index of a field within the ListFieldNames list.

If the Text property value has no matching record within the data source, no text is displayed within the lookup combo box.


TcxDBLookupComboBox
 TcxDBLookupComboBox Object

Hierarchy          Properties          Methods          Events          See Also

Represents a data-aware editor displaying a set of values from a lookup dataset used for editing values in another dataset.

Unit

cxDBLookupComboBox

TcxDBLookupComboBox = class(TcxCustomLookupComboBox);

Description

Use the TcxDBLookupComboBox control to provide a user with a dropdown list of values from one dataset, which are used for editing records in another dataset.  The dataset containing values for the dropdown list is specified via the Properties.ListSource property.  The dataset whose records are edited is specified via the DataBinding.DataSource property.  A relation must be established between these two datasets.  This relation connects a key field from the first dataset (the required field name is specified via the Properties.KeyFieldNames property) to a field from the second dataset (the required field name is specified via the DataBinding.DataField property).

If a TcxDBLookupComboBox control is linked to a lookup field component, it automatically obtains its property values, such as Properties.ListFieldNames, Properties.KeyFieldNames from a lookup field component.  In this instance, an editor is set up right after the lookup field name is assigned to the DataBinding.DataField property.

When a user navigates through the dropdown list, the editor’s EditValue matches the value of the Properties.ListSource key field, corresponding to the currently selected dropdown list record.  If EditValue is posted, the DataBinding.DataSource field value specified via the DataBinding.DataField property matches the current EditValue.

The Properties.ListFieldIndex property specifies the index of the field whose value is displayed within the edit box of the lookup editor.  A user is allowed to enter text within the editor’s edit box.  In this instance, the editor implements an incremental search within the dropdown list in order to locate the first record whose ListFieldIndex field value starts with the entered text.

If the Properties.IncrementalFiltering property value is True, the editor filters the dropdown list items based on the first characters entered into it:


TcxDBLookupComboBox Hierarchy
Hierarchy

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomComboBox

     |

TcxCustomLookupEdit

     |

TcxCustomDBLookupEdit

     |

TcxCustomLookupComboBox

     |


Properties for TcxDBLookupComboBox
TcxDBLookupComboBox Properties

TcxDBLookupComboBox          Legend

In TcxDBLookupComboBox

DataBinding

Derived from TcxCustomLookupComboBox

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

Properties

RepositoryItem

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxDBLookupComboBox
TcxDBLookupComboBox Methods

TcxDBLookupComboBox          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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxDBLookupComboBox
TcxDBLookupComboBox Events

TcxDBLookupComboBox          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxDBLookupComboBox.DataBinding

TcxDBLookupComboBox

Represents an editor connection to a dataset field being edited.

property DataBinding: TcxDBEditDataBinding;

Description

The DataBinding property represents an object providing an editor connection to a data storage.  For the TcxDBLookupComboBox control, the DataBinding.DataSource property identifies a TDataSource object connected to a dataset whose records are edited.  The field being edited is determined by the DataBinding.DataField property.

A lookup combo box allows you to edit a DataField value by picking up a record from the dropdown list which displays data from another data source (the Properties.ListSource property).  This data source must contain a key field matching DataField.  Use the editor’s Properties.KeyFieldNames property to specify the key field.

When a user navigates through the dropdown list, the editor’s EditValue matches the value of the key field, corresponding to the currently selected dropdown list record.  Posting the edit value modifies a DataField value.


TcxLookupComboBox
 TcxLookupComboBox Object

Hierarchy          Properties          Methods          Events          See Also

Represents a lookup combo box control.

Unit

cxDBLookupComboBox

TcxLookupComboBox = class(TcxCustomLookupComboBox);

Description

The TcxLookupComboBox object represents an editor displaying values from the data source specified via the Properties.ListSource property.  The ListSource field values are displayed within the editor dropdown window, containing a TcxLookupGrid control.  The following image demonstrates the lookup combo box displaying two columns within the dropdown:

Fields, whose values are displayed within the dropdown window, are identified via the Properties.ListFieldNames property value.  Each field has a corresponding column within the editor’s dropdown window and in the Properties.ListColumns collection.  A data source field, whose values are displayed and edited within the edit region, is identified by the Properties.ListFieldIndex property, which represents the index of a column within the Properties.ListColumns collection.

The editor’s edit value (the EditValue property) matches the ListSource key field value (identified via the Properties.KeyFieldNames property) corresponding to the record containing the currently displayed value.

You can specify the EditValue via code.  If there is no records in ListSource whose key field values match the edit value, the editor displays nothing.

The TcxLookupComboBox supports an incremental search feature against the field whose value is displayed in the edit box (it is addressed by the Properties.ListFieldIndex property).  When a user types within the edit region, the editor activates the dropdown window and locates the first record whose key field value starts with the characters typed.

If the Properties.IncrementalFiltering property value is True, the editor filters the dropdown list values according to the first characters typed.  The following image demonstrates the lookup combo box during typing with the Properties.IncrementalFiltering property set to True:


TcxLookupComboBox Hierarchy
Hierarchy

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomComboBox

     |

TcxCustomLookupEdit

     |

TcxCustomDBLookupEdit

     |

TcxCustomLookupComboBox

     |


Properties for TcxLookupComboBox
TcxLookupComboBox Properties

TcxLookupComboBox          Legend

Derived from TcxCustomLookupComboBox

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

Properties

RepositoryItem

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxLookupComboBox
TcxLookupComboBox Methods

TcxLookupComboBox          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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxLookupComboBox
TcxLookupComboBox Events

TcxLookupComboBox          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxLookupComboBoxProperties
TcxLookupComboBoxProperties Object

Hierarchy          Properties          Methods          Events          See Also

Contains settings controlling the behavior of TcxLookupComboBox and TcxDBLookupComboBox editors.

Unit

cxDBLookupComboBox

TcxLookupComboBoxProperties = class(TcxCustomDBLookupEditProperties);

Description

The TcxLookupComboBoxProperties object contains settings specific to LookupComboBox editors represented by the TcxLookupComboBox and TcxDBLookupComboBox classes.

The ListSource property specifies a lookup data source whose field values are displayed within the dropdown window of the lookup combo box.  The inherited ListFieldNames property specifies which fields from the ListSource are displayed within the lookup combo box dropdown.  Setting this property’s value creates columns for all fields set via ListFieldNames.  These columns can be accessed via the ListColumns collection.  However, you can use ListColumns as well to specify columns/fields to display in the dropdown window.

The ListFieldIndex property addresses the ListSource field whose values are displayed within the edit box of an editor.

The KeyFieldNames property specifies the ListSource key field(s) whose values are used to identify data source records.  These field values match the editor’s edit value (see the EditValue property).  For a data-aware lookup combo box (TcxCustomDBLookupEdit), key field values also match values of a data source field being edited.  To set this field, use the editor’s DataBinding.DataField property.

To control any changes made to the editor’s DisplayFormat, EditFormat, MaxLength, MaxValue, MinValue and ReadOnly properties and reverse their values back to the default ones, use the AssignedValues property.


TcxLookupComboBoxProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |

TcxCustomDropDownEditProperties

     |

TcxCustomComboBoxProperties

     |

TcxCustomLookupEditProperties

     |

TcxCustomDBLookupEditProperties

     |


Properties for TcxLookupComboBoxProperties
TcxLookupComboBoxProperties Properties

TcxLookupComboBoxProperties          Legend

In TcxLookupComboBoxProperties

GridMode

ListColumns

ListOptions

ListSource

Derived from TcxCustomDBLookupEditProperties

CaseSensitiveSearch

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

IncrementalSearch

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 TcxLookupComboBoxProperties
TcxLookupComboBoxProperties Methods

TcxLookupComboBoxProperties          Legend

Derived from TcxCustomMaskEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults


Events for TcxLookupComboBoxProperties
TcxLookupComboBoxProperties Events

TcxLookupComboBoxProperties          Legend

In TcxLookupComboBoxProperties

OnSortingChanged

Derived from TcxCustomComboBoxProperties

OnDrawItem

OnMeasureItem

Derived from TcxCustomDropDownEditProperties

OnCloseQuery

OnCloseUp

OnInitPopup

OnPopup

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxLookupComboBoxProperties.GridMode

TcxLookupComboBoxProperties

Specifies whether a lookup grid is in GridMode.

property GridMode: Boolean;

Description

You can use the GridMode property to enable Grid Mode for the lookup grid.  This allows you 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 decreased 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 combo box is used as an in-place editor in a Grid control.

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 ListFieldIndex 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.


TcxLookupComboBoxProperties.ListColumns

TcxLookupComboBoxProperties          See Also

Specifies the collection of columns displayed within the dropdown window of a lookup editor.

property ListColumns: TcxLookupDBGridColumns;

Description

A LookupComboBox editor displays records from the ListSource datasource within the dropdown window.  Records are arranged in columns which can be accessed via the ListColumns collection.  You can use the ListColumns property to add/remove columns and access their properties.

A lookup edit column represents a TcxLookupDBGridColumn instance.  To bind a column to a datasource field, use its TcxLookupDBGridColumn.FieldName property.

Columns can be added to or removed from the collection both at design time and via code.  At design time, a user can work with the ListColumns collection editor in order to add or remove columns from the collection, specify the data source field for each column, change a specific column’s settings, such as width and sorting possibility etc.

Another way of editing the ListColumns collection is to work with the ListFieldNames property.  A user can add a column to the collection by adding the name of a new data source field to the ListFieldNames property value.  A column can be removed if the name of the corresponding data source field is removed from the ListFieldNames property value.


TcxLookupComboBoxProperties.ListOptions

TcxLookupComboBoxProperties

Specifies the look & feel options of the lookup grid displayed within the lookup editor dropdown.

property ListOptions: TcxLookupGridOptions;

Description

Use the ListOptions property to specify the look and feel options of the lookup grid representing the dropdown list of a lookup editor.  These options specify whether the editor dropdown list can be sorted, whether column headers are displayed, which grid lines are present within the dropdown list, etc.


TcxLookupComboBoxProperties.ListSource

TcxLookupComboBoxProperties          See Also

Specifies the TDataSource instance containing data to display within a lookup editor.

property ListSource: TDataSource;

Description

Use the ListSource property to specify the TDataSource instance containing data to display within a lookup editor.  Setting this property value is not enough for the lookup editor to display data within the dropdown list.  The lookup editor must have at least one column in the ListColumns collection bound to a specific ListSource field.

Also you have to specify a key field(s) via the KeyFieldNames property used to identify records within the ListSource.  A key field value(s) of a record selected in the dropdown list matches the edit value of an editor and can be accessed via the EditValue property.

The value displayed in the edit region of a lookup combo box is addressed by the ListFieldIndex property.


TcxLookupComboBoxProperties.OnSortingChanged

TcxLookupComboBoxProperties

This event is fired after data sorting has changed.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnSortingChanged: TNotifyEvent;

Description

Handle the OnSortingChanged event to react in the situations when data sorting has changed.  For an in-place editor, data sorting is controlled by the data controller which is accessible via the DataController property.


cxDropDownEdit Unit Overview
cxDropDownEdit Unit

Classes

TcxComboBox

TcxComboBoxProperties

TcxCustomComboBox

TcxCustomComboBoxProperties

TcxCustomDropDownEdit

TcxCustomDropDownEditProperties

TcxCustomPopupEdit

TcxCustomPopupEditProperties

TcxPopupEdit

TcxPopupEditProperties

Other Types

TcxEditDropDownListStyle


TcxCustomComboBox
TcxCustomComboBox Object

Hierarchy          Properties          Methods          Events          Example

Represents the base class of those editors which incorporate a list of values within a dropdown window.

Unit

cxDropDownEdit

TcxCustomComboBox = class(TcxCustomDropDownEdit);

Description

The TcxCustomComboBox class is the base class for the TcxComboBox class and for other classes representing single-line text editors, enhanced with a dropdown window, containing a list of values.  It provides properties and methods defining the basic functionality of combo box editors.  The dropdown window can be activated by clicking the editor’s button.

Note: The editor dropdown window can be activated only if it contains at least one value.

To close and open the dropdown window, use the Alt+Up arrow, Alt+Down arrow or F4 key.  These keystrokes invoke the CloseUp method with the AAccept parameter set to True.  This forces your editor to change the edit value to the one selected in the dropdown window.  When the dropdown window is active, pressing the Esc key discards the user selection and closes the dropdown window.  After pressing the Esc key the editor keeps the previously selected value.


TcxCustomComboBox Hierarchy
Hierarchy

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |


Properties for TcxCustomComboBox
TcxCustomComboBox Properties

TcxCustomComboBox          Legend

In 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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxCustomComboBox
TcxCustomComboBox Methods

TcxCustomComboBox          Legend

In 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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCustomComboBox
TcxCustomComboBox Events

TcxCustomComboBox          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCustomComboBox.ActiveProperties

TcxCustomComboBox           See Also

Obtains the properties that are currently applied to a combo box editor.

property ActiveProperties: TcxCustomComboBoxProperties;

Description

Use the ActiveProperties property to obtain the properties of the current combo box editor that are currently in effect.  This property is especially useful when the combo box 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 combo box editor.  Otherwise, the inherent combo box editor’s properties are returned.

ReadOnly Property


TcxCustomComboBox.ItemIndex

TcxCustomComboBox

Specifies the currently selected item in a combo box dropdown window.

property ItemIndex: Integer;

Description

Use the ItemIndex property to specify which combo box item is selected.  This property value is zero-based.  If the combo box’s Items collection does not contain any value or no combo box item is selected, the ItemIndex property value is -1.  Combo box items can be scrolled by changing the ItemIndex property value even if the combo box dropdown is inactive.


TcxCustomComboBox.Properties

TcxCustomComboBox

Identifies the main attributes specific to an editor.

property Properties: TcxCustomComboBoxProperties;

Description

Use the Properties property to set specific attributes which control the editor behavior.  Properties specific to combo box editors are stored in the TcxCustomComboBoxProperties class.


TcxCustomComboBox.CanDropDown

TcxCustomComboBox

Determines whether the combo box dropdown window can be opened.

function CanDropDown: Boolean; override;

Description

The CanDropDown method can be overridden in a class descending from the TcxCustomComboBox class.  Use it to determine whether the combo box dropdown window can be opened.


TcxCustomComboBoxProperties
  TcxCustomComboBoxProperties Object

Hierarchy          Properties          Methods          Events

Contains settings specific to combo box editors.

Unit

cxDropDownEdit

TcxCustomComboBoxProperties = class(TcxCustomDropDownEditProperties);

Description

The TcxCustomComboBoxProperties class represents a set of attributes controlling the behavior of combo box editors.  Editor properties are set via the Properties property of the corresponding editor.

The DropDownListStyle property specifies the editor behavior during text input.  The DropDownRows property specifies the number of rows displayed within the editor dropdown window. The Revertable property determines whether the editor dropdown values can be cycled through by a double click within the editor.


TcxCustomComboBoxProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |

TcxCustomDropDownEditProperties

     |


Properties for TcxCustomComboBoxProperties
TcxCustomComboBoxProperties Properties

TcxCustomComboBoxProperties          Legend

In 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

IncrementalSearch

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 TcxCustomComboBoxProperties
TcxCustomComboBoxProperties Methods

TcxCustomComboBoxProperties          Legend

Derived from TcxCustomMaskEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults


Events for TcxCustomComboBoxProperties
TcxCustomComboBoxProperties Events

TcxCustomComboBoxProperties          Legend

In TcxCustomComboBoxProperties

OnDrawItem

OnMeasureItem

Derived from TcxCustomDropDownEditProperties

OnCloseQuery

OnCloseUp

OnInitPopup

OnPopup

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomComboBoxProperties.DropDownAutoWidth

TcxCustomComboBoxProperties          See Also

Specifies whether the dropdown list width is changed to display entirely.

property DropDownAutoWidth: Boolean;

Description

Use the DropDownAutoWidth property to specify whether the dropdown list width is changed to display all list values entirely.  If this property is set to True, then the dropdown list width is set according to the largest list item but it cannot exceed the editor width.  If this property is set to False, then the dropdown list width is specified via the DropDownWidth property.

The default value of the DropDownAutoWidth property is True.


TcxCustomComboBoxProperties.DropDownListStyle

TcxCustomComboBoxProperties

Specifies the combo box behavior during text input.

type

  TcxEditDropDownListStyle = (lsEditFixedList, lsEditList, lsFixedList);

property DropDownListStyle: TcxEditDropDownListStyle;

Description

Use the DropDownListStyle property to specify the manner in which a combo box reacts to characters input.

Value	Meaning
lsEditFixedList	Text input is allowed and the entered text is automatically completed if it matches one of the words from the combo box dropdown.  Entering new values is prohibited.
lsEditList	Text input is allowed and the entered text is automatically completed if it matches one of the words from the combo box dropdown.  New values can be entered.
lsFixedList	Text input is prohibited. The combo box can only navigate through the values stored within its popup.

The combo box dropdown is activated during text input regardless of the DropDownListStyle property settings.

The default value of the DropDownListStyle property is lsEditList.


TcxCustomComboBoxProperties.DropDownRows

TcxCustomComboBoxProperties

Specifies the number of values displayed in the dropdown window of the active combo box.

property DropDownRows: Integer;

Description

Use the DropDownRows property to specify the number of rows simultaneously displayed within the dropdown window of the active combo box.  If this number is greater than the total number of items within the combo box, the DropDownRows property value is ignored. If the DropDownRows property value is less than the total number of items within the combo box, the combo box dropdown displays the number of rows specified via the DropDownRows property, but the dropdown is supplied with a vertical scrollbar that allows displaying hidden items:

The default value of the DropDownRows property is 7.


TcxCustomComboBoxProperties.DropDownSizeable

TcxCustomComboBoxProperties

Determines whether an end user can resize the dropdown window by dragging its borders.

property DropDownSizeable: Boolean;

Description

Use the DropDownSizeable property to specify whether the dropdown window can be resized by an end-user.  If this property value is False, then the dropdown window size is determined by the DropDownWidth and the DropDownRows properties.

The smallest portion by which the dropdown window height can be changed is the height of a dropdown list item.

The default value of the DropDownSizeable property is False.


TcxCustomComboBoxProperties.DropDownWidth

TcxCustomComboBoxProperties

Specifies the width of the editor dropdown window.

property DropDownWidth: Integer;

Description

Use the DropDownWidth property to specify the width of the editor dropdown.  If this property value is 0, then the dropdown width is equal to the editor width.  If the DropDownAutoWidth property is set to True, then the DropDownWidth property settings are ignored.

The default value of the DropDownWidth property is 0.


TcxCustomComboBoxProperties.ImmediateUpdateText

TcxCustomComboBoxProperties

Determines whether the text displayed within the combo box edit region is updated during keyboard navigation of the combo box dropdown.

property ImmediateUpdateText: Boolean;

Description

The ImmediateUpdateText property determines whether the text displayed within the combo box edit region is updated during keyboard navigation of the combo box dropdown.  If this property value is True, then the edit region text is updated immediately after a user selects another value from the editor dropdown.  Otherwise, data posting needs to be performed in order to reflect changes.

The default value of the ImmedaiteUpdateText property is False.


TcxCustomComboBoxProperties.ItemHeight

TcxCustomComboBoxProperties          See Also

Specifies the height of an item in the combo box editor.

property ItemHeight: Integer;

Description

Use the ItemHeight property to specify the height of items in the combo box editor in pixels.  The default value is 0 and this indicates that the height of items is calculated automatically based on the font settings of the editor.

You can change this value as your needs dictate.  For instance, this can be useful when you want to perform custom draw of items via the OnDrawItem event.

To specify the width of items, see the DropDownWidth property.  Note that DropDownWidth is in effect only if the DropDownAutoWidth property is set to False.

It is possible to specify different heights for individual items in the combo box editor.  See the OnMeasureItem event.

The ItemHeight property is published in the TcxComboBoxProperties and TcxMRUEditProperties classes.

The default value of the ItemHeight property is 0.


TcxCustomComboBoxProperties.Items

TcxCustomComboBoxProperties

Specifies the list of expressions used for automatic completion when a user enters the first characters into an editor.

property Items: TStrings;

Description

Use the Items property to specify the list of expressions available for automatic completion by an editor.  This list may be filled in random order as it can be sorted afterwards by setting the Sorted property to True.  Expressions from the Items list are displayed within the ExpressComboBox editor dropdown.

Note:	The Items list may contain several expressions with the same starting characters.  If the expression list is not sorted, then during input, the ExpressComboBox dropdown may locate an expression placed later in alphabetical order than other expressions with the same starting characters presented in the Items list.

The default value of this property is False.


TcxCustomComboBoxProperties.Revertable

TcxCustomComboBoxProperties

Determines whether the dropdown values of the combo box can be cycled through by a double click within the editor.

property Revertable: Boolean;

Description

Use the Revertable property to determine whether the dropdown values of the combo box can be cycled through by double-clicking within the editor.

Note:	This property is not in effect when the DropDownListStyle property is set to the IsFixedList value.  In this instance, clicking or double-clicking within your editor invokes the editor dropdown.

The default value of the Revertable property is False.


TcxCustomComboBoxProperties.Sorted

TcxCustomComboBoxProperties

Determines whether the auto completion expression list is sorted in alphabetical order.

property Sorted: Boolean;

Description

Use the Sorted property to determine whether the auto completion expression list is sorted.

Note:	The Items list may contain several expressions with the same starting characters.  If the expression list is not sorted, then during input, the ExpressComboBox dropdown may locate an expression placed later in alphabetical order, than other expressions with the same starting characters presented in the Items list.

The default value of the Sorted property is False.


TcxCustomComboBoxProperties.OnDrawItem

TcxCustomComboBoxProperties          See Also           Example

Occurs when a combo box item is painted.

type

  TcxEditDrawItemEvent = procedure(AControl: TcxCustomComboBox; ACanvas: TcxCanvas; AIndex: Integer; const ARect: TRect; AState: TOwnerDrawState) of object;

property OnDrawItem: TcxEditDrawItemEvent;

Description

Use the OnDrawItem event to perform custom draw of items in the combo box and MRU-editors.  If you handle the OnDrawItem event, the combo box editor will not draw any item.

The event occurs every time an item should be redrawn.  The currently painted item is addressed by the AIndex parameter defining the position of the item in the Items list.  Use the Items property to access the text that should be displayed.

The editor itself is passed as the AControl parameter.

The AState parameter represents a set of options specifying the manner in which an item should be drawn.  You usually need to process the odSelected option indicating that the item should be drawn selected.

The graphic surface and bounds for drawing are passed as ACanvas and ARect respectively.

You can use the DropDownWidth and ItemHeight properties to specify the width of the dropdown window and the height of items respectively.  By default (if ItemHeight is set to 0), the height of items is calculated automatically based on current font settings.

If you need to change the height of individual items, you should use the OnMeasureItem event.  This event is raised before OnDrawItem.


TcxCustomComboBoxProperties.OnMeasureItem

TcxCustomComboBoxProperties          See Also           Example

Occurs each time a combo box item should be repainted.

type

  TMeasureItemEvent = procedure(AControl: TcxCustomComboBox; AIndex: Integer; ACanvas: TcxCanvas; var AHeight: Integer) of object;

property OnMeasureItem: TMeasureItemEvent;

Description

Use the OnMeasureItem event when you need to change the default height of individual items in the combobox and MRU-editors.  The default height is determined by the ItemHeight property and is passed in AHeight.  To change the default height, set a new value to the AHeight parameter.

The currently processed item is identified by the AIndex parameter.  This represents the index of the item in the Items list.  The editor itself is passed as the AControl parameter.

ACanvas specifies the canvas for drawing an item.  You can use members of the ACanvas object, for instance, to determine the height of the sample text drawn on this canvas using a particular font.

The OnMeasureItem event can be useful when you perform custom draw of items via the OnDrawItem event.  In this case, handle the OnMeasureItem event to allocate sufficient space for your item.  Then draw the item by handling the OnDrawItem event.


TcxComboBox
 TcxComboBox Object

Hierarchy          Properties          Methods          Events          See Also          Example

Represents a combo box editor.

Unit

cxDropDownEdit

TcxComboBox = class(TcxCustomComboBox)

Description

The TcxComboBox object represents an editor, which combines the functionality of a single-line text editor with the dropdown window.  The dropdown window is used to display a list of text strings.  Use the Properties.Items property to populate this strings list.  When a user enters text into an editor, that text can be automatically completed to a value from the editor dropdown, if the entered text has the same starting characters as the editor dropdown value.

The TcxComboBox class does not implement functionality other than that defined in the TcxCustomComboBox class.

The combo box editor can be used to display values from its dropdown without text input (set the DropDownListStyle to the IsFixedList value to implement this type of the combo box behavior).  A user can activate the popup by clicking the dropdown button or by pressing the Up Arrow and Down Arrow keys combined with the Alt key, or by pressing the F4 key.  Combo box items navigation can be performed even if the popup is closed - press the Up and Down arrows keys or the Ctrl + Page Up (Page Down) combinations for this purpose.

The following image demonstrates the combo box editor with the opened dropdown window:

Use the Properties and style (the Style, StyleDisabled, StyleFocused and StyleHot) properties to specify the behavior and look & feel of the combo box editor.  Working with styles is discussed in the TcxCustomEditStyle class topic.


TcxComboBox Hierarchy
Hierarchy

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomComboBox

     |


Properties for TcxComboBox
TcxComboBox Properties

TcxComboBox          Legend

In TcxComboBox

Text

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

Derived from TWinControl

ImeMode

ImeName


Methods for TcxComboBox
TcxComboBox Methods

TcxComboBox          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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxComboBox
TcxComboBox Events

TcxComboBox          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxComboBox.Text

TcxComboBox

Specifies the text displayed within a combo box editor.

property Text: TCaption;

Description

Use the Text property to specify the text displayed within a combo box editor.

Note: If the DropDownListStyle property is set to IsEditFixedList or IsFixedList, the Text property can only be set to a value contained within the combo box dropdown.


TcxComboBoxProperties
TcxComboBoxProperties Object

Hierarchy          Properties          Methods          Events

Contains settings specific to combo box editors.

Unit

cxDropDownEdit

TcxComboBoxProperties = class(TcxCustomComboBoxProperties)

Description

The TcxComboBoxProperties class represents a set of attributes controlling the behavior of combo box editors.  Editor properties are set via the Properties member of the corresponding editor.  To control any changes made to the editor’s DisplayFormat, EditFormat, MaxLength, MaxValue, MinValue and ReadOnly properties and reverse their values back to the default ones, use the AssignedValues property.

This class inherits the functionality defined in the TcxCustomComboBoxProperties class.  It also publishes properties required for implementing the editor automatic completion feature.


TcxComboBoxProperties Hierarchy
Hierarchy

TcxCustomMaskEditProperties

     |

TcxCustomDropDownEditProperties

     |

TcxCustomComboBoxProperties

     |


Properties for TcxComboBoxProperties
TcxComboBoxProperties Properties

TcxComboBoxProperties          Legend

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

IncrementalSearch

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 TcxComboBoxProperties
TcxComboBoxProperties Methods

TcxComboBoxProperties          Legend

Derived from TcxCustomMaskEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue


Events for TcxComboBoxProperties
TcxComboBoxProperties Events

TcxComboBoxProperties          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


TcxEditDropDownListStyle
TcxEditDropDownListStyle type

Specifies the combo box behavior during text input.

Unit

cxButtonEdit

type

  TcxEditDropDownListStyle = (lsEditFixedList, lsEditList, lsFixedList);

Description

Available TcxDropDownListStyle values are listed below:

Value	Meaning
lsEditFixedList	Text input is allowed and the entered text is automatically completed if it matches one of the values within the combo box dropdown.  Entering new values is prohibited.
lsEditList	Text input is allowed and the entered text is automatically completed if it matches one of the values within the combo box dropdown.  New values can be entered.
lsFixedList	Text input is not allowed. The combo box can only navigate through the values stored within its popup.

The combo box dropdown is activated during text input regardless of the DropDownListStyle property settings.


Example: TcxCustomComboBoxProperties.OnMeasureItem, TcxCustomComboBoxProperties.OnDrawItem

Let’s consider an example that displays fonts installed in the system via a combo box editor.  The editor will display names of all the available fonts using their typefaces.

Fonts installed in the system are specified by the Fonts property of the global Screen variable.  To populate the combo box editor with items, use the Properties.Items list.  This can be done very simply in the following manner:

//Delphi

  cxComboBox1.Properties.Items := Screen.Fonts;

//C++ Builder

  cxComboBox1->Properties->Items = Screen->Fonts;

To draw customized items in a combo box, you should use the editor’s Properties.OnDrawItem event.  Since the height of items can vary depending on the font used to draw items, the Properties.OnMeasureItem event must also be handled.  In the OnMeasureItem event, the item’s height is determined by the TcxCanvas.TextHeight function.

//Delphi

procedure TForm1.cxComboBox1PropertiesMeasureItem(

  AControl: TcxCustomComboBox; AIndex: Integer; ACanvas: TcxCanvas;

  var AHeight: Integer);

var

  AFontName: string;

begin

  //Get the font name from the Items list

  AFontName := TcxComboBox(AControl).Properties.Items[AIndex];

  //Specify the font for the canvas

  ACanvas.Font.Name := AFontName;

  //Get the height of the sample text

  AHeight := ACanvas.TextHeight('Wg') + 6;

end;

//C++ Builder

void __fastcall TForm1::cxComboBox1PropertiesMeasureItem(

      TcxCustomComboBox *AControl, int AIndex, TcxCanvas *ACanvas,

      int &AHeight) {

  //Get the font name from the Items list

  String AFontName = ((TcxComboBox*)AControl)->Properties->
    Items->Strings[AIndex];

  //Specify the font for the canvas

  ACanvas->Font->Name = AFontName;

  //Get the height of the sample text

  AHeight = ACanvas->TextHeight("Wg") + 6;

}

In the OnDrawItem event, items (font names) are drawn using the corresponding font typefaces.  When an item is selected in the combo box, it is drawn highlighted.

//Delphi

procedure TForm1.cxComboBox1PropertiesDrawItem(

  AControl: TcxCustomComboBox; ACanvas: TcxCanvas; AIndex: Integer;

  const ARect: TRect; AState: TOwnerDrawState);

var

  AFontName: string;

  ATextRect: TRect;

begin

    if odSelected in AState then

    begin

      //Set the colors of the background and font for selected items

      ACanvas.Brush.Color := clHighlight;

      ACanvas.Font.Color := clWhite;

    end

    else

    begin

      //Set the colors of the background and font
      //for non-selected items

      ACanvas.Brush.Color := clWhite;

      ACanvas.Font.Color := clBlack;

    end;

    ACanvas.FillRect(ARect);

    //Get the font name from the Items list

    AFontName := TcxComboBox(AControl).Properties.Items[AIndex];

    //Specify the font for the canvas

    ACanvas.Font.Name := AFontName;

    ATextRect := ARect;

    ATextRect.Left := ATextRect.Left + 3;

    //Draw the font name using the corresponding font typeface

    ACanvas.DrawText(AFontName, ATextRect, cxAlignVCenter);

end;

//C++ Builder

void __fastcall TForm1::cxComboBox1PropertiesDrawItem(

      TcxCustomComboBox *AControl, TcxCanvas *ACanvas, int AIndex,

      const TRect &ARect, TOwnerDrawState AState) {

    if (AState.Contains(odSelected)) {

      //Set the colors of the background and font for selected items

      ACanvas->Brush->Color = clHighlight;

      ACanvas->Font->Color = clWhite;

    }

    else {

      //Set the colors of the background and font

      //for non-selected items

      ACanvas->Brush->Color = clWhite;

      ACanvas->Font->Color = clBlack;

    }

    ACanvas->FillRect(ARect);

    //Get the font name from the Items list

    String AFontName = ((TcxComboBox*)AControl)->Properties->
      Items->Strings[AIndex];

    //Specify the font for the canvas

    ACanvas->Font->Name = AFontName;

    TRect ATextRect = ARect;

    ATextRect.Left = ATextRect.Left + 3;

    //Draw the font name using the corresponding font typeface

    ACanvas->DrawTexT(AFontName, ATextRect, cxAlignVCenter);

}

The following image shows the resulting combobox editor:


TcxCustomDropDownEdit
TcxCustomDropDownEdit Object

Hierarchy          Properties          Methods           Events          See also

Represents an editor with a popup window.

Unit

cxDropDownEdit

TcxCustomDropDownEdit = class(TcxCustomMaskEdit);

Description

The TcxCustomDropDownEdit control represents an editor that has a popup window.  A user can activate the popup window by clicking the dropdown arrow within the editor.  To close and open the popup window use the Alt+Up arrow, Alt+Down arrow or F4 keys.  These keystrokes invoke the CloseUp method with the AAccept parameter set to True.  This forces the editor to change the edit value to the one selected in the popup window.  When the popup window is active, pressing the Esc key discards the user selection and closes the popup window.  After pressing the Esc key, the editor restores the previously selected value.

Do not create instances of the TcxCustomDropDownEdit class.  Use its descendants such as TcxComboBox and TcxPopupEdit instead.


TcxCustomDropDownEdit Hierarchy
Hierarchy

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |


Properties for TcxCustomDropDownEdit
TcxCustomDropDownEdit Properties

TcxCustomDropDownEdit          Legend

In 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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxCustomDropDownEdit
TcxCustomDropDownEdit Methods

TcxCustomDropDownEdit          Legend

In 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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCustomDropDownEdit
TcxCustomDropDownEdit Events

TcxCustomDropDownEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCustomDropDownEdit.ActiveProperties

TcxCustomDropDownEdit           See Also

Obtains the properties that are currently applied to an editor.

property ActiveProperties: TcxCustomDropDownEditProperties;

Description

Use the ActiveProperties property to obtain the properties of the current editor that are currently in effect.  This property is especially useful when the 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 editor.  Otherwise, the inherent editor’s properties are returned.

ReadOnly Property


TcxCustomDropDownEdit.DroppedDown

TcxCustomDropDownEdit

Specifies whether the popup window is open.

property DroppedDown: Boolean;

Description

Use the DroppedDown property to return the current state of the editor popup window.  To open the popup window you can set the DroppedDown property to True.  Setting this property to False forces the editor to close up the popup window.


TcxCustomDropDownEdit.PopupWindow

TcxCustomDropDownEdit           See also

Defines the popup window for the current editor.

property PopupWindow: TcxCustomEditPopupWindow;

Description

The PopupWindow property specifies the popup form displayed when a user clicks the dropdown button.  The popup window represents a container on which different objects are placed.  For instance, the TcxComboBox editor places a list box control onto the popup to display its items.  The TcxPopupEdit editor places the control specified via the TcxCustomPopupEditProperties.PopupControl property onto a popup form.

The TcxCustomEditPopupWindow class is a descendant of the TForm class.

ReadOnly Property


TcxCustomDropDownEdit.Properties

TcxCustomDropDownEdit           See also

Specifies settings managing the look & feel and behavior of an editor.

property Properties: TcxCustomDropDownEditProperties;

Description

Use Properties to set specific attributes which control the editor behavior.  They define the alignment of the editor contents, the collection of buttons that can be displayed within it, the read-only status, etc.  Properties specific to popup editors are stored in the TcxCustomDropDownEditProperties class.  It declares additional attributes that control the look & feel and behavior of the popup window.


TcxCustomDropDownEdit.CanDropDown

TcxCustomDropDownEdit           See Also

Determines whether the popup window can be opened.

function CanDropDown: Boolean; virtual;

Description

Descendants of the TcxCustomDropDownEdit class override the CanDropDown method to provide specific conditions when the popup window cannot be opened.  The popup window is opened only if the CanDropDown function returns True.

When a user tries to open the popup window, the OnInitPopup event occurs and the CanDropDown method is called.  If it returns True, the editor generates the OnPopup event and displays the popup window.  If the CanDropDown function is False, the popup window is not displayed and the OnPopup event is not generated.


TcxCustomDropDownEdit.CloseUp

TcxCustomDropDownEdit           See Also

Closes the popup window and passes the selected item’s value to an editor.

type

  TcxEditCloseUpReason = (crUnknown, crTab, crClose, crCancel, crEnter);

procedure CloseUp(AReason: TcxEditCloseUpReason); virtual;

Description

The CloseUp method closes the popup window.  The AReason parameter specifies why the popup window is being closed.  All the possible values for this parameter are listed in the description of the TcxEditCloseUpReason type.

The currently selected item’s value is displayed in the editor and is assigned to the editor’s EditValue property when the reason for the popup window closing is specified by the crTab, crEnter, or crClose values.


TcxCustomDropDownEdit.Create

TcxCustomDropDownEdit

Creates an instance of the TcxCustomDropDownEdit class.

constructor Create(AOwner: TComponent); override;

Description

The constructor creates and initializes an instance of the TcxCustomDropDownEdit class.  The AOwner parameter specifies the component, which becomes the owner of an editor.  The owner is responsible for destroying the edit control.


TcxCustomDropDownEdit.Destroy

TcxCustomDropDownEdit

Destroys an instance of the TcxCustomDropDownEdit class.

destructor Destroy; override;

Description

The destructor destroys the editor and frees all resources allocated by it.  Do not call Destroy directly in an application. Instead, call the Free method.  The Free method verifies that the control is not nil, and only then calls the Destroy method.


TcxCustomDropDownEdit.DropDown

TcxCustomDropDownEdit           See Also

Opens the popup window.

procedure DropDown; virtual;

Description

The DropDown method is for internal use only.  A user can open the popup window by using the DroppedDown property.  Setting it to True calls the DropDown method which generates the TcxCustomDropDownEditProperties.OnInitPopup and TcxCustomDropDownEditProperties.OnPopup events.  The popup window is opened only if the CanDropDown function returns True.


TcxCustomDropDownEdit.Focused

TcxCustomDropDownEdit

Determines whether an edit control or its popup window has focus.

function Focused: Boolean; override;

Description

The Focused function returns True if an editor or its popup window has focus.  Otherwise, False is returned.


TcxCustomDropDownEdit.PopupWindowClosed

TcxCustomDropDownEdit           See Also

The method is called after closing the popup window.

procedure PopupWindowClosed(Sender: TObject); virtual;

Description

The PopupWindowClosed method is virtual.  It can be overridden in custom editors to perform specific operations after the popup has been closed.  Use the PopupWindowClosing method to perform operations before the popup window is closed.


TcxCustomDropDownEdit.PopupWindowClosing

TcxCustomDropDownEdit           See Also

Called before closing the popup window.

procedure PopupWindowClosing(Sender: TObject); virtual;

Description

The PopupWindowClosing method is virtual.  It can be overridden in custom editors to perform specific operations when the popup window is about to close.  To perform operations after the popup window is closed use the PopupWindowClosed method.


TcxCustomDropDownEditProperties
  TcxCustomDropDownEditProperties Object

Hierarchy          Properties          Methods          Events          See also

Contains settings specific to editors with the popup window.

Unit

cxDropDownEdit

TcxCustomDropDownEditProperties = class(TcxCustomMaskEditProperties);

Description

The TcxCustomDropDownProperties class defines settings for the TcxCustomDropDownEdit control.  It represents a set of attributes controlling the behavior of popup editors.  Editor properties are set via the Properties member of the corresponding editor.

TcxCustomDropDownProperties extends functionality of the TcxCustomMaskEditProperties class by providing attributes that control the behavior and placement of the popup window.  These settings define whether the popup window is sizeable, determine its dimensions and position relative to the editor window and specify the image drawn on the dropdown button.


TcxCustomDropDownEditProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |


Properties for TcxCustomDropDownEditProperties
TcxCustomDropDownEditProperties Properties

TcxCustomDropDownEditProperties          Legend

In 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

IncrementalSearch

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 TcxCustomDropDownEditProperties
TcxCustomDropDownEditProperties Methods

TcxCustomDropDownEditProperties          Legend

Derived from TcxCustomMaskEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults


Events for TcxCustomDropDownEditProperties
TcxCustomDropDownEditProperties Events

TcxCustomDropDownEditProperties          Legend

In TcxCustomDropDownEditProperties

OnCloseQuery

OnCloseUp

OnInitPopup

OnPopup

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomDropDownEditProperties.ButtonGlyph

TcxCustomDropDownEditProperties

Specifies the bitmap drawn on the dropdown button surface.

property ButtonGlyph: TBitmap;

Description

To open the popup window a user can click the dropdown button at the right edge of the popup editor.  Use the ButtonGlyph property to specify a custom image, which will be displayed on the surface of the dropdown button.  If no image is assigned to the ButtonGlyph property, the down arrow is drawn.

Note:	For TcxMRUEdit and TcxColorComboBox editors (and their data-aware versions), the glyph will be displayed on the ellipsis button (…) provided that it’s visible.  If this button is hidden, the glyph is displayed on the dropdown button.  Use the ShowEllipsis and AllowSelectColor options to control the general appearance of the ellipsis button.


TcxCustomDropDownEditProperties.ImmediateDropDown

TcxCustomDropDownEditProperties

Determines whether the popup window is opened immediately after a user has pressed an alphanumeric character within an editor.

property ImmediateDropDown: Boolean;

Description

Set the ImmediateDropDown property to True to activate the popup window immediately after a user has pressed an alphanumeric character within the editor.  If the ImmediateDropDown property is set to False, the popup window cannot be opened in this way.  To open the popup in this instance you can either press the Alt+Up arrow, Alt+Down arrow, F4 keys or click the dropdown button.

The default value of the ImmediateDropDown property is True.


TcxCustomDropDownEditProperties.ImmediatePopup

TcxCustomDropDownEditProperties

Determines whether the popup window is opened immediately after a user has activated an in-place editor.

property ImmediatePopup: Boolean;

Description

This property is effective for in-place editors only.  Set the ImmediatePopup property to True to activate the popup window immediately after a user has activated the editor (e.g. focused it in a grid).  If the ImmediatePopup property is set to False, the popup window cannot be opened in this way.

The default value of the ImmediatePopup property is False.


TcxCustomDropDownEditProperties.PopupAlignment

TcxCustomDropDownEditProperties

Specifies the manner in which the dropdown window is aligned relative to the editor.

property PopupAlignment: TAlignment;

Description

Use the PopupAlignment property to specify the horizontal placement of the dropdown window relative to the editor window.  It can be aligned either to the right, left, or centered.

The default value of the PopupAlignment property is taLeftJustify.


TcxCustomDropDownEditProperties.PopupAutoSize

TcxCustomDropDownEditProperties           See Also

Specifies whether the popup window is resized to accommodate the control placed on it.

property PopupAutoSize: Boolean;

Description

The PopupAutoSize property specifies whether the dropdown window automatically changes its size based on the size of the control.  If True, it is the same size as the control.  Otherwise, its width and height are determined by the PopupWidth and PopupHeight properties.

Note:	For BLOB editors that display images (their BlobEditKind property is set to bekPict), the PopupAutoSize property returns the PictureAutoSize property value.

The default value of the PopupAutoSize property is True.


TcxCustomDropDownEditProperties.PopupHeight

TcxCustomDropDownEditProperties           See Also

Determines the height of the dropdown window.

property PopupHeight: Integer;

Description

The PopupHeight and PopupWidth properties identify the height and width of the popup window in pixels if the PopupAutoSize property is set to False.  Otherwise, the actual height and width are determined by the dimensions of the control placed on the popup.

The default value of the PopupHeight property is 200.


TcxCustomDropDownEditProperties.PopupClientEdge

TcxCustomDropDownEditProperties

Specifies whether to display the inner border within the popup window.

property PopupClientEdge: Boolean;

Description

Set PopupClientEdge to True to display the client border within the popup window.  The client border is displayed along with the popup outer border determined by the Style.PopupBorderStyle property.  If the PopupClientEdge property is set to False, only the outer border is drawn.

The next two images display the TcxPopupEdit control containing the TMemo control.  The PopupClientEdge property is set to False and True respectively.  Other properties are set as follows:

•	the editor’s BorderStyle to ebsUltraFlat;

•	the editor’s PopupBorderStyle to epbsFlat;

•	the TMemo control’s BorderStyle to bsNone.

The default value of the PopupClientEdge property is False.


TcxCustomDropDownEditProperties.PopupMinHeight

TcxCustomDropDownEditProperties           See also

Determines the minimum height of the popup window.

property PopupMinHeight: Integer;

Description

If the popup window is sizable (the PopupSizeable property is set to True), you cannot resize it to dimensions less than those determined by the PopupMinHeight and PopupMinWidth properties.

The default value of the PopupMinHeight property is 100.


TcxCustomDropDownEditProperties.PopupMinWidth

TcxCustomDropDownEditProperties           See also

Determines the minimum width of the popup window.

property PopupMinWidth: Integer;

Description

If the popup window is sizable (the PopupSizeable property is set to True), you cannot resize it to dimensions less than those determined by the PopupMinHeight and PopupMinWidth properties.

The default value of the PopupMinWidth property is 100.


TcxCustomDropDownEditProperties.PopupSizeable

TcxCustomDropDownEditProperties           See also

Determines whether the popup window is sizeable.

property PopupSizeable: Boolean;

Description

Set the PopupSizeable property to True to allow a user to change the size of the popup window using the mouse.  If PopupSizeable is set to False, the user cannot resize the popup.  The minimum width and height of the popup window are determined by the PopupMinWidth and PopupMinHeight properties respectively.

The default value of the PopupSizeable property is False.


TcxCustomDropDownEditProperties.PopupSysPanelStyle

TcxCustomDropDownEditProperties

Specifies whether to display the system panel at the bottom of the popup window.

property PopupSysPanelStyle: Boolean;

Description

Set the SysPanelStyle property to True to display the system panel at the bottom of the popup window.  The system panel allows a user to resize the popup window and to close it by clicking the ‘X’ button.

If SysPanelStyle is False, the popup window can be closed by setting focus to another control.  To close the popup window programmatically, use the DroppedDown property.

The default value of the PopupSysPanelStyle property is False.


TcxCustomDropDownEditProperties.PopupWidth

TcxCustomDropDownEditProperties           See Also

Determines the width of the popup window.

property PopupWidth: Integer;

Description

When the PopupAutoSize property is set to True, the actual height and width of the popup window are determined by the dimensions of the control placed on the popup.  Otherwise, the PopupHeight and PopupWidth properties identify the height and width of the popup window in pixels.  If the PopupWidth property is set to 0, the width is determined by the owner control (for instance, a grid item associated with the in-place popup editor).

The default value of the PopupWidth property is 250.


TcxCustomDropDownEditProperties.PostPopupValueOnTab

TcxCustomDropDownEditProperties

Specifies whether the selected item’s value is posted to the editor when the popup window is closed using the Tab key.

property PostPopupValueOnTab: Boolean;

Description

Use the PostPopupValueOnTab property to specify the editor’s behavior when an end user closes the popup window by pressing the Tab key.  In this case the selected item’s value is posted to the editor if the PostPopupValueOnTab property is set to True.  Otherwise, the editor’s edit value remains unchanged and focus moves to the next control.

The default value of the PostPopupValueOnTab property is False.


TcxCustomDropDownEditProperties.OnCloseQuery

TcxCustomDropDownEditProperties           See Also

Occurs before closing the popup window.

type

  TCloseQueryEvent = procedure(Sender: TObject; var CanClose: Boolean) of object;

property OnCloseQuery: TCloseQueryEvent;

Description

The OnCloseQuery event is generated when the popup window is about to close.  It is generated when a user clicks the close (x) button on the system panel in the popup or when setting the ModalResult property of the popup form to a value other than mrNone.  To display the popup system panel you have to set the PopupSysPanelStyle property to True.

The CanClose parameter specifies whether the popup can be closed.  Set it to False to prevent the popup window from closing.  The Sender parameter identifies the edit control which generates the event.

Use the OnCloseUp event to perform specific actions when the popup window is closed.


TcxCustomDropDownEditProperties.OnCloseUp

TcxCustomDropDownEditProperties           See Also

Occurs after the popup window is closed.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnCloseUp: TNotifyEvent;

Description

Handle the OnCloseUp event to perform specific actions after the popup window is closed.  You can use the OnCloseQuery event to prevent the popup window from closing by setting the CanClose parameter to False.


TcxCustomDropDownEditProperties.OnInitPopup

TcxCustomDropDownEditProperties           See Also

Occurs as the popup window is about to be opened.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnInitPopup: TNotifyEvent;

Description

OnInitPopup is the first event generated before opening the popup window.  In some cases, the popup window cannot be opened (for instance, if no popup control is assigned to the TcxPopupEdit object).  The virtual TcxCustomDropDownEdit.CanDropDown method determines whether the popup can be activated.  The OnInitPopup event is always generated regardless of whether the popup window can be opened or not.

You can use the OnInitPopup event to initialize the popup window (for instance, populate the TcxComboBox control with items, assign the popup control to the TcxPopupEdit editor, etc.)

After the popup window is displayed, the OnPopup event is generated.  This event occurs only when the CanDropDown function returns True.


TcxCustomDropDownEditProperties.OnPopup

TcxCustomDropDownEditProperties           See Also

Occurs when the popup window is displayed on screen.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnPopup: TNotifyEvent;

Description

The OnPopup event is generated when the popup window is displayed on screen.  It is generated only if the popup window can be displayed, which is determined by the TcxCustomDropDownEdit.CanDropDown function.

Before the OnPopup event occurs, the OnInitPopup event is generated.  It is generated in all cases, regardless of whether the popup window can be displayed or not.


TcxCustomPopupEdit
TcxCustomPopupEdit Object

Hierarchy          Properties          Methods          Events           See also

Represents the base class for those editors which enable embedding another control in the popup window.

Unit

cxDropDownEdit

TcxCustomPopupEdit = class(TcxCustomDropDownEdit);

Description

The TcxCustomPopupEdit class extends functionality of a simple popup editor and allows embedding another control in the corresponding popup window.  Do not instantiate the TcxCustomPopupEdit class.  Use its descendants such as TcxPopupEdit, which publish necessary properties.

At runtime, a user can work with the control placed on the popup window in the same way as he/she did with the standalone version of the control.

The control to embed is specified via the PopupControl attribute of the Properties member.  The popup window of the TcxCustomPopupEdit editor appears only if the control is assigned to the PopupControl property.


TcxCustomPopupEdit Hierarchy
Hierarchy

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |


Properties for TcxCustomPopupEdit
TcxCustomPopupEdit Properties

TcxCustomPopupEdit          Legend

In TcxCustomPopupEdit

ActiveProperties

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxCustomPopupEdit
TcxCustomPopupEdit Methods

TcxCustomPopupEdit          Legend

In TcxCustomPopupEdit

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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCustomPopupEdit
TcxCustomPopupEdit Events

TcxCustomPopupEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCustomPopupEdit.ActiveProperties

TcxCustomPopupEdit           See Also

Obtains the properties that are currently applied to an editor.

property ActiveProperties: TcxCustomPopupEditProperties;

Description

Use the ActiveProperties property to obtain the properties of the current editor that are currently in effect.  This property is especially useful when the 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 editor.  Otherwise, the inherent editor’s properties are returned.

ReadOnly Property


TcxCustomPopupEdit.Properties

TcxCustomPopupEdit           See Also

Identifies the main attributes specific to an editor.

property Properties: TcxCustomPopupEditProperties;

Description

Use Properties to set specific attributes controlling the editor behavior.  They define the alignment of an editor’s contents, the collection of buttons that can be displayed within the editor, the read-only status, the position and dimensions of the popup window, etc.

The TcxCustomPopupEditProperties class provides the PopupControl property via which the control is displayed within the popup window is assigned.


TcxCustomPopupEdit.CanDropDown

TcxCustomPopupEdit           See Also

Determines whether the popup window can be displayed.

function CanDropDown: Boolean; override;

Description

The CanDropDown function determines whether the popup window can be opened.  The popup window can be opened only if the control to display is assigned to the editor.  To assign a control, use the PopupControl attribute of the Properties member.


TcxCustomPopupEditProperties
  TcxCustomPopupEditProperties Object

Hierarchy          Properties          Methods          Events           See also

Contains settings specific for the editors which enable embedding another controls into a popup window.

Unit

cxDropDownEdit

TcxCustomPopupEditProperties = class(TcxCustomDropDownEditProperties);

Description

The TcxCustomPopupEditProperties class defines settings for the TcxCustomPopupEdit control.  It represents a set of attributes controlling the behavior of popup editors.  Editor properties are set via the Properties member of the corresponding editor.

Properties define settings for text displaying, popup size and position, the read-only status, button collection, etc.  TcxCustomPopupEditProperties extends functionality of the TcxCustomDropDownEditProperties class by providing the PopupControl property by which assign the control to embed in the popup.


TcxCustomPopupEditProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |

TcxCustomDropDownEditProperties

     |


Properties for TcxCustomPopupEditProperties
TcxCustomPopupEditProperties Properties

TcxCustomPopupEditProperties          Legend

In TcxCustomPopupEditProperties

PopupControl

PopupSizeable

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

IncrementalSearch

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 TcxCustomPopupEditProperties
TcxCustomPopupEditProperties Methods

TcxCustomPopupEditProperties          Legend

Derived from TcxCustomMaskEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults


Events for TcxCustomPopupEditProperties
TcxCustomPopupEditProperties Events

TcxCustomPopupEditProperties          Legend

Derived from TcxCustomDropDownEditProperties

OnCloseQuery

OnCloseUp

OnInitPopup

OnPopup

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomPopupEditProperties.PopupControl

TcxCustomPopupEditProperties           See Also

Determines the control displayed within the popup window of an editor.

property PopupControl: TControl;

Description

Use the PopupControl property to assign a control to be displayed within the popup window of the TcxCustomPopupEdit editor.  You can work with the embedded control in the same way as you did with its standalone version.


TcxCustomPopupEditProperties.PopupSizeable

TcxCustomPopupEditProperties           See Also

Identifies whether the popup window is sizeable.

property PopupSizeable: Boolean;

Description

Set the PopupSizeable property to True to allow a user to change the size of the popup window using the mouse.  If PopupSizeable is set to False, the user cannot resize the popup.  The minimum width and height of the popup window are determined by the PopupMinWidth and PopupMinHeight properties respectively.

The default value of the PopupSizeable property is True.


TcxPopupEdit
 TcxPopupEdit Object

Hierarchy          Properties          Methods         Events          See also

Represents a text editor that enables embedding another control in its popup window.

Unit

cxDropDownEdit

TcxPopupEdit = class(TcxCustomPopupEdit);

Description

The TcxPopupEdit class represents a control that allows editing textual data.  The main feature of the popup editor is that it enables embedding another control in the associated popup window.  To set the control to embed in the popup window, use the PopupControl property of the Properties object.  At runtime, a user can work with the control placed on the popup window in the same way as he/she did with its standalone version.

TcxPopupEdit does not provide any new behavior.  It simply publishes necessary properties and events inherited from base classes.  The primary class that introduces the popup functionality is TcxCustomDropDownEdit.

To open or close the popup window you can use the DroppedDown property.  Set it to True to activate the popup window.  At runtime, a user can activate the popup by clicking the dropdown button, or by pressing the Up Arrow and Down Arrow keys combined with the Alt key, or by pressing the F4 key.

The next image demonstrates the TcxPopupEdit editor, which displays a TPanel control within its popup window.  The panel contains three buttons and a memo component.  The popup window is painted in the XP style.


TcxPopupEdit Hierarchy
Hierarchy

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMaskEdit

     |

TcxCustomDropDownEdit

     |

TcxCustomPopupEdit

     |


Properties for TcxPopupEdit
TcxPopupEdit Properties

TcxPopupEdit          Legend

In TcxPopupEdit

Text

Derived from TcxCustomPopupEdit

ActiveProperties

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxPopupEdit
TcxPopupEdit Methods

TcxPopupEdit          Legend

Derived from TcxCustomPopupEdit

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

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxPopupEdit
TcxPopupEdit Events

TcxPopupEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxPopupEdit.Text

TcxPopupEdit

Specifies the text displayed within an editor.

property Text: TCaption;

Description

Use the Text property to specify the text displayed within the TcxPopupEdit editor.


TcxPopupEditProperties
TcxPopupEditProperties Object

Hierarchy          Properties          Methods          Events         See also

Contains settings specific to the editors which enable embedding another control in the popup window.

Unit

cxDropDownEdit

TcxPopupEditProperties = class(TcxCustomPopupEditProperties);

Description

The TcxPopupEditProperties class defines settings for the TcxPopupEdit control.  It represents a set of attributes controlling the behavior of popup editors.  Editor properties are set via the Properties member of the corresponding editor.  To control any changes made to the editor’s DisplayFormat, EditFormat, MaxLength, MaxValue, MinValue and ReadOnly properties and reverse their values back to the default ones, use the AssignedValues property.

Properties define settings for text displaying, popup size and position, the read-only status, button collection, etc.  TcxPopupEditProperties does not introduce any new behavior, but publishes properties responsible for popup editor adjustments.  The main property you should use to set a control to display within the popup window is PopupControl.


TcxPopupEditProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMaskEditProperties

     |

TcxCustomDropDownEditProperties

     |

TcxCustomPopupEditProperties

     |


Properties for TcxPopupEditProperties
TcxPopupEditProperties Properties

TcxPopupEditProperties          Legend

In TcxPopupEditProperties

ImmediatePopup

Derived from TcxCustomPopupEditProperties

PopupControl

PopupSizeable

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

IncrementalSearch

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 TcxPopupEditProperties
TcxPopupEditProperties Methods

TcxPopupEditProperties          Legend

Derived from TcxCustomMaskEditProperties

GetEmptyString

ValidateDisplayValue

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults


Events for TcxPopupEditProperties
TcxPopupEditProperties Events

TcxPopupEditProperties          Legend

Derived from TcxCustomDropDownEditProperties

OnCloseQuery

OnCloseUp

OnInitPopup

OnPopup

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxPopupEditProperties.ImmediatePopup

TcxPopupEditProperties

Determines whether the popup window is opened immediately after a user has activated an in-place editor.

property ImmediatePopup: Boolean;

Description

This property is effective for in-place editors only.  Set the ImmediatePopup property to True to activate the popup window immediately after a user has activated the editor (e.g. focused it in a grid).  If the ImmediatePopup property is set to False, the popup window cannot be opened in this way.

The default value of the ImmediatePopup property is True.


cxTextEdit Unit Overview
cxTextEdit Unit

Classes

TcxCustomTextEdit

TcxCustomTextEditProperties

TcxTextEdit

TcxTextEditProperties

TcxTextEditPropertiesValues


TcxCustomTextEdit
TcxCustomTextEdit Object

Hierarchy          Properties          Methods          Events

Represents the base class for text editors.

Unit

cxTextEdit

TcxCustomTextEdit = class(TcxCustomEdit);

Description

The TcxCustomTextEdit class is the base class for the controls representing text editors and for the user-defined classes representing single-line text editors. It provides properties and methods defining the basic functionality of text editors.  Use the Properties property to access the properties that control the behavior specific to text editors.


TcxCustomTextEdit Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |


Properties for TcxCustomTextEdit
TcxCustomTextEdit Properties

TcxCustomTextEdit          Legend

In 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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxCustomTextEdit
TcxCustomTextEdit Methods

TcxCustomTextEdit          Legend

In TcxCustomTextEdit

Clear

ClearSelection

CopyToClipboard

Create

CutToClipboard

SelectAll

SetSelection

Undo

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCustomTextEdit
TcxCustomTextEdit Events

TcxCustomTextEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCustomTextEdit.ActiveProperties

TcxCustomTextEdit          See Also

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

property ActiveProperties: TcxCustomTextEditProperties;

Description

Use the ActiveProperties property to obtain the properties of the current text editor that are currently in effect.  This property is especially useful when the text 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 text editor.  Otherwise, the inherent text editor’s properties are returned.

ReadOnly Property


TcxCustomTextEdit.BeepOnEnter

TcxCustomTextEdit

Determines whether a sound is produced every time a user presses the Enter key after entering text into an editor.

property BeepOnEnter: Boolean;

Description

Use the BeepOnEnter property to determine whether a sound is produced each time a user presses the Enter key after entering text into an editor.  Setting this property to False disables the sound.

The default value of the BeepOnEnter property is True.


TcxCustomTextEdit.CursorPos

TcxCustomTextEdit

Specifies the cursor position within an editor.

property CursorPos: Integer;

Description

Use the CursorPos property to obtain the current cursor position within an editor.

ReadOnly Property


TcxCustomTextEdit.EditingText

TcxCustomTextEdit

Specifies the text displayed in the edit box of the edit control.

property EditingText: TCaption;

Description

You can use the EditingText property to modify the contents of the editor.  EditingText matches the text displayed in the editor’s edit box.

Assigning a text string to the EditingText property:

•	sets a corresponding dataset to edit mode (for data-aware editors);

•	modifies the text displayed in the edit box;

•	sets the EditModified flag to True and this indicates that the edit value should be posted when the editor loses focus or when a user presses the Enter key.

Changing the editor’s Text property does not sets a corresponding dataset to edit mode and does not activate the EditModified flag.


TcxCustomTextEdit.Properties

TcxCustomTextEdit

Identifies main attributes specific to an editor.

property Properties: TcxCustomTextEditProperties;

Description

Use Properties to set specific attributes controlling the editor behavior.  They define the alignment of the editor contents, the collection of buttons that can be displayed within the editor, the read-only status, etc.  Properties specific to text editors are stored in the TcxCustomTextEditProperties class.


TcxCustomTextEdit.SelLength

TcxCustomTextEdit

Determines the number of selected characters.

property SelLength: Integer;

Description

Use the SelLength property to set the number of selected characters within an editor. The character starting a selection is determined via the SelStart property value. Setting SelLength to a value greater than the number of characters from SelStart to the text end results in selecting all characters from SelStart to the text end.


TcxCustomTextEdit.SelStart

TcxCustomTextEdit

Determines the position of the first selected character.

property SelStart: Integer;

Description

Use the SelStart property to determine the position of the first selected character.  The SelStart property is zero based where 0 indicates the first character.  If no text is selected, the SelStart property indicates the cursor position.  Set the SelStart property to remove the current selection and place the cursor just before the character indicated by the supplied value.  To select a particular text range, first set the SelStart property to position the cursor and then set the SelLength property to extend the selection.


TcxCustomTextEdit.SelText

TcxCustomTextEdit

Specifies the selected portion of editor text.

property SelText: TCaption;

Description

Read SelText to determine the value of the selected text. Set SelText to replace the selected text with a new string. If there is no selection, but the edit control has focus, set SelText to insert a new string into the text at the cursor position.


TcxCustomTextEdit.Clear

TcxCustomTextEdit

Clears the contents of an editor.

procedure Clear; override;

Description

Use the Clear method to delete all text from an editor.  Use the ClearSelection method instead to remove only the selected text.


TcxCustomTextEdit.ClearSelection

TcxCustomTextEdit

Removes the selected text from an editor.

procedure ClearSelection; override;

Description

Use the ClearSelection method to remove the selected text from an editor.  The character starting a selection is determined via the SelStart property value.  The selection length is determined via the SelLength property value.  Use the Clear method instead to remove all editor text.


TcxCustomTextEdit.CopyToClipboard

TcxCustomTextEdit           See Also

Copies the selected text to the clipboard.

procedure CopyToClipboard; override;

Description

Use the CopyToClipBoard method to copy the selected text from an editor to the clipboard. If no text is selected within the editor, this method is not in effect. To select a portion of editor text, use the SelStart property to specify the starting character in the selection and the SelLength property to specify the selection’s length.


TcxCustomTextEdit.Create

TcxCustomTextEdit

Creates a TcxCustomTextEdit class instance.

procedure Create(AOwner: TComponent); override;

Description

Use the Create method to create and initialize a new instance of the TcxCustomTextEdit class.


TcxCustomTextEdit.CutToClipboard

TcxCustomTextEdit

Removes the selected text from an editor and places it to the clipboard.

procedure CutToClipboard; override;

Description

Use the CutToClipboard method to copy the selected text from an editor to the clipboard with a subsequent text removal. If no text is selected within the editor, this method is not in effect. To select a portion of editor text, use the SelStart property to specify the starting character in the selection and the SelLength property to specify the selection’s length.


TcxCustomTextEdit.SelectAll

TcxCustomTextEdit           See Also

Selects all text within an editor.

procedure SelectAll; override;

Description

Use the SelectAll method to select all text within an editor.  After the text is selected it can be copied to the clipboard using the CopyToClipboard or CutToClipboard method.


TcxCustomTextEdit.SetSelection

TcxCustomTextEdit          See Also

Sets the text selection within a text editor.

procedure SetSelection(ASelStart: Integer; ASelLength: Integer);

Description

Each text editor allows a user to select any portion of text using the cursor keys.  The selected characters are highlighted and can be copied by Ins key to clipboard, deleted by Del key or replaced by another character entered.  You can use the SetSelection method to set the text selection within a text editor.  SetSelection sets the SelStart and SelLength properties to values passed as ASelStart and ASelLength parameters respectively.  This sets the selection for the text portion starting from the ASelStart position.  The ASelLength parameter specifies the number of characters to select.  Setting ASelLength to 0 removes the selection.

To select all the text, use the SelectAll method.


TcxCustomTextEdit.Text

TcxCustomTextEdit

Specifies the editor display value.

property Text: TCaption;

Description

Use the Text property to obtain the currently displayed editor text.  Generally, this property value is equal to the EditValue property value.  When a user enters text into an editor, the entered text is stored in the Text property.  Until a user confirms input by pressing the Enter key (if the ValidateOnEnter property value is True) or by setting focus to another control, the EditValue property value will not reflect Text property value changes.


TcxCustomTextEdit.Undo

TcxCustomTextEdit

Discards changes made to an editor’s text.

procedure Undo;

Description

Use the Undo method to discard changes made to an editor’s text.  Some actions cannot be rolled back though.  These actions include direct modifications of the Text and EditValue properties, calls to the PasteFromClipboard and CutFromClipboard methods etc.

Note:	Changes made to the editor’s text can be discarded via the Undo method only while focus remains within the editor.  When focus leaves it, the current editor’s EditValue is saved.


TcxCustomTextEditProperties
TcxCustomTextEditProperties Object

Hierarchy          Properties          Methods          Events

Contains settings specific to text editors.

Unit

cxTextEdit

TcxCustomTextEditProperties = class(TcxCustomEditProperties);

Description

The TcxCustomTextEditProperties class represents a set of attributes that control the behavior of text editors.  Properties of an editor are set via the Properties member of the corresponding editor.

The text editor properties control several aspects of the editor behavior: the HideSelection property affects the character selection within an editor; the CharCase and EchoMode properties affect the appearance of items entered into an editor; the MaxLength property determines the number of characters a user may enter into an editor; the IncrementalSearch property enables the automatic completion feature within an editor, etc.


TcxCustomTextEditProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |


Properties for TcxCustomTextEditProperties
TcxCustomTextEditProperties Properties

TcxCustomTextEditProperties          Legend

In TcxCustomTextEditProperties

AssignedValues

CharCase

DisplayFormat

EchoMode

EditFormat

HideCursor

HideSelection

ImeMode

ImeName

IncrementalSearch

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 TcxCustomTextEditProperties
TcxCustomTextEditProperties Methods

TcxCustomTextEditProperties          Legend

In TcxCustomTextEditProperties

IsDisplayValueValid

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue


Events for TcxCustomTextEditProperties
TcxCustomTextEditProperties Events

TcxCustomTextEditProperties          Legend

In TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomTextEditProperties.AssignedValues

TcxCustomTextEditProperties

Contains the property flags that indicate which properties specific to a text editor have been changed.

property AssignedValues: TcxTextEditPropertiesValues;

Description

Use the AssignedValues property to track the changes made to a text editor’s DisplayFormat, EditFormat, MaxLength, MaxValue, MinValue and ReadOnly properties and undo them.  Once the property being tracked is set to a value other than the default one, the changes are reflected in the AssignedValues property (its corresponding property flag is set to True).  To undo the changes made and reverse the property back to its default value, set the corresponding property flag to False or call the AssignedValues.RestoreDefaults method to reverse all these properties back to their default values and reset all the property flags.  Use the AssignedValues.BeginUpdate and AssignedValues.EndUpdate methods to control when the editor repaints and avoid any flickering when the property flags are modified.


TcxCustomTextEditProperties.CharCase

TcxCustomTextEditProperties

Specifies the case of editor text.

type

  TEditCharCase = (ecNormal, ecUpperCase, ecLowerCase);

property CharCase: TEditCharCase;

Description

Use the CharCase property to force the contents of an editor to assume a particular case.

All the possible values for this property are listed in the following table.

Value	Meaning
ecLowerCase	Text is converted to lower case.
ecNormal	Text appears in the mixed case and no conversion occurs.
ecUpperCase	Text is converted to upper case.

When the CharCase property is set to ecLowerCase or ecUpperCase, the case of characters is converted as a user types them into the editor.  Changing the CharCase property to ecLowerCase or ecUpperCase changes the actual text contents, not just its appearance.  Moreover, any case information is lost and can’t be recaptured by changing CharCase to ecNormal.

The default value of the CharCase property is ecNormal.


TcxCustomTextEditProperties.DisplayFormat

TcxCustomTextEditProperties          See Also

Determines the manner in which the editor's text is formatted.

property DisplayFormat: string;

Description

Use the DisplayFormat property to define the format string for the editor's text.  The DisplayFormat controls the way in which this text is displayed when the editor does not have focus.

Note:	The cxDBSpinEdit and cxCurrencyEdit editors use the DisplayFormat property to show their editor's texts.  For the cxDBSpinEdit, the default value for its DisplayFormat property is an empty string.  For the cxCurrencyEdit, the default value for its DisplayFormat property is based on the system's regional currency settings.  For instance, for English (United States) locale the default value for the DisplayFormat property is ‘$,0.00;-$,0.00’.  You can use the global CurrencyString, CurrencyFormat and other variables declared in the SysUtils unit to change the way currencies are formatted by default.

You can change the default format by assigning a new format string to the DisplayFormat property.  The RestoreDefaults method restores the default value of DisplayFormat along with some other properties.

Note that the UseDisplayFormatWhenEditing property specifies the format which is used to display the editor's text in edit mode.

Refer to the TNumericField.DisplayFormat property's topic in the Delphi (C++ Builder) documentation for more information on formatting values.


TcxCustomTextEditProperties.EditFormat

TcxCustomTextEditProperties          See Also

Determines the manner in which the editor's text is formatted when it is being edited.

property EditFormat: string;

Description

Use the EditFormat property to define the format string applied to the editor's text when it's edited.  The EditFormat controls the way in which this text is displayed when the editor has focus.

When the EditFormat property is unassigned, but the DisplayFormat property has a value, the DisplayFormat string is used.

Note, that the UseDisplayFormatWhenEditing property specifies the format which is used to display the editor's text when in edit mode.

Refer to the TNumericField.EditFormat property's topic in the Delphi (C++ Builder) documentation for more information on formatting values.


TcxCustomTextEditProperties.EchoMode

TcxCustomTextEditProperties          See Also

Specifies the manner in which editor text is displayed.

type

  TcxEditEchoMode = (eemNormal, eemPassword{$IFNDEF VCL}, eemNone{$ENDIF});

property EchoMode: TcxEditEchoMode;

Description

Use the EchoMode property to control the manner in which text is displayed when entering.

All the possible values for this property are listed in the following table.

Value	Meaning
eemNormal	Characters are displayed as they are entered.
eemPassword	The PasswordChar characters are displayed in the place of the typed characters.
eemNone	Characters are not displayed as they are entered.

The EchoMode property only affects the look & fell of an editor.  The Text property value reflects the actually typed characters.

Note:	The EchoMode property affects both user input text and text inserted programmatically.

The default value of the EchoMode property is eemNormal.


TcxCustomTextEditProperties.HideCursor

TcxCustomTextEditProperties

Specifies whether the edit cursor is hidden.

property HideCursor: Boolean;

Description

Set the HideCursor property to True to hide the edit cursor.  This prevents a user from modifying the edit contents.  If HideCursor is set to False, the cursor is visible and data can be edited using the keyboard.

The default value of the HideCursor property is False.


TcxCustomTextEditProperties.HideSelection

TcxCustomTextEditProperties

Determines whether the visual indication of the selected text remains when the editor loses focus.

property HideSelection: Boolean;

Description

Set the HideSelection property to False to provide visual feedback of the selected text portion even when the editor does not have focus.  Set the HideSelection property to True to show the selection only when the editor has focus.   This property does not affect the actual value of the selection, only the visual indication.

The default value of the HideSelection property is True.


TcxCustomTextEditProperties.ImeMode

TcxCustomTextEditProperties

Specifies the current mode of an Input Method Editor (IME).

type

  TImeMode = (imDisable, imClose, imOpen, imDontCare, imSAlpha, imAlpha, imHira, imSKata, imKata, imChinese, imSHanguel, imHanguel);

property ImeMode: TImeMode;

Description

The ImeMode property represents the way an IME operates to convert keyboard input typed on an Asian version of Windows.  The ImeName property specifies the IME used for the conversion.  Refer to the TImeMode topic in the Delphi (C++ Builder) documentation for details.

The default value of the ImeMode property is imDontCare.


TcxCustomTextEditProperties.ImeName

TcxCustomTextEditProperties

Specifies the input method editor (IME) to use for converting keyboard input to Asian language characters.

type

  TImeName = type string;

property ImeName: TImeName;

Description

Set the ImeName property to specify which IME to use for converting keystrokes.  The ImeMode property controls the operating mode of the IME.  Refer to the TImeName topic in the Delphi (C++ Builder) documentation for details.


TcxCustomTextEditProperties.IncrementalSearch

TcxCustomTextEditProperties

Enables the automatic completion feature of an editor.

property IncrementalSearch: Boolean;

Description

If the IncrementalSearch property is set to True, typing within the editor displays the item which starts with the characters entered.  This also selects the item in a list within a derived editor with a dropdown window.

You can specify the items that are recognized and automatically completed by the editor via the LookupItems list.  If the IncrementalSearch property is set to False, any characters typed appear within the editor.

The default value of the IncrementalSearch property is True.


TcxCustomTextEditProperties.LookupItems

TcxCustomTextEditProperties

Specifies the list of words required to implement the automatic completion feature within an editor.

property LookupItems: TStrings;

Description

The LookupItems property specifies the list of words, which will be automatically completed when a user enters their first symbols into an editor.  Set the editor’s Properties.IncrementalSearch property to True to enable the automatic completion feature within the editor.

The LookupItemsSorted property determines whether the automatic completion words list is sorted in alphabetical order. The automatic completion words list can be navigated through by pressing the Up and Down keys when the editor has focus (implemented for all editors starting from TcxCustomDropDownEdit).


TcxCustomTextEditProperties.LookupItemsSorted

TcxCustomTextEditProperties

Specifies whether the automatic completion words list is sorted in alphabetical order.

property LookupItemsSorted: Boolean;

Description

The LookupItemsSorted property determines whether the automatic completion words list is sorted in alphabetical order. This list is specified via the LookupItems property.  The automatic completion words list can be navigated through by pressing the Up and Down keys when the editor has focus (implemented for all editors starting from TcxCustomDropDownEdit).


TcxCustomTextEditProperties.MaxLength

TcxCustomTextEditProperties

Specifies the maximum number of characters a user can enter into an editor.

property MaxLength: Integer;

Description

Use the MaxLength property to specify the maximum number of characters a user can enter into an editor. If this property value is 0, no limitations are applied to the length of entered text.  If the number of characters already entered equals the MaxLength property value, further text input is ignored.

The default value of the MaxLength property for a data-aware editor is determined by the MaxLength attribute of the dataset field to which this editor is connected (the default value is obtained only for string fields; for other field types the default value is 0).  If a user enters and posts a string whose length is greater than the default value of the MaxLength property, the string is truncated.

You can use the RestoreDefaults method to revert to default values of the MaxLength property and other properties retrieved from the related TField object attributes.

Note:	The MaxLength property value does not affect the entered text by changing the Text or EditValue property.


TcxCustomTextEditProperties.MaxValue

TcxCustomTextEditProperties          See Also

Specifies the maximum numerical value an editor can display.

property MaxValue: Double;

Description

It is possible to define the range of values for the editors displaying numbers by setting the MaxValue and MinValue properties.  A user is then restricted to numbers located within this range.  If the MaxValue and MinValue properties are equal, the editor accepts any numbers.

The default value of the MaxValue property for a data-aware editor is determined by the MaxValue attribute of the dataset field to which this editor is connected (default values can be obtained only for integer, float and BCD dataset fields).  If a user enters and posts a value greater than the default maximum value, an exception is raised.

You can use the RestoreDefaults method to revert to default values of the MaxValue property and other properties retrieved from the related TField object attributes.


TcxCustomTextEditProperties.MinValue

TcxCustomTextEditProperties          See Also

Specifies the minimum numerical value an editor can display.

property MinValue: Double;

Description

It is possible to restrict the range of values for the editors displaying numbers by setting the MaxValue and MinValue properties.  A user can enter only a number located within this range.  If MaxValue and MinValue are equal, the editor accepts any numbers.

The default value of the MinValue property for a data-aware editor is determined by the MinValue attribute of the dataset field to which this editor is connected (default values can be obtained only for integer, float and BCD dataset fields).  If a user enters and posts a value smaller than the default minimum value, an exception is raised.

You can use the RestoreDefaults method to revert to default values of the MinValue property and other properties retrieved from the related TField object attributes.


TcxCustomTextEditProperties.OEMConvert

TcxCustomTextEditProperties

Determines whether characters typed in an editor are converted from ANSI to OEM and back to ANSI.

property OEMConvert: Boolean;

Description

To ensure that any characters typed in your editor can be unambiguously converted to the OEM character set, set the OEMConvert property to True. This forces all characters to be converted from ANSI to OEM and then back to ANSI as they are typed. Set the OEMConvert property to False to avoid the overhead of this conversion when it does not matter whether text can be unambiguously mapped to an OEM string.

The OEMConvert property is most useful for edit controls used to enter file names when the application does not use Unicode file names.

 The default value of the OEMConvert property is False.


TcxCustomTextEditProperties.PasswordChar

TcxCustomTextEditProperties          See Also

Specifies the character (if any) to display in place of the actual characters typed into an editor.

type

  TCaptionChar = {$IFDEF VCL}Char{$ELSE}WideChar{$ENDIF};

property PasswordChar: TCaptionChar;

Description

Use the PasswordChar property to specify a special character which will be displayed in the place of any text entered into the editor.  If the PasswordChar is set to the null character (ANSI character zero), the editor displays its text normally.  If the PasswordChar is any other character, the editor displays the PasswordChar character in the place of each character typed in.  The PasswordChar affects the appearance of the editor's text only. The value of the Text property reflects the actual characters that are typed.

The EchoMode property specifies the manner in which the typed text is displayed in the editor.


TcxCustomTextEditProperties.UseDisplayFormatWhenEditing

TcxCustomTextEditProperties

Specifies the format which is used to display the editor's text in edit mode.

property UseDisplayFormatWhenEditing: Boolean;

Description

By setting the UseDisplayFormatWhenEditing property to True, you can designate that the editor's text in edit mode is formatted using the format string specified by the DisplayFormat property instead of the EditFormat property.  Otherwise, the EditFormat property's value will be used to format the editor's text.

Use this property to standardize the format of the editor's text for both edit and display modes.

The default value of the UseDisplayFormatWhenEditing property is False.


TcxCustomTextEditProperties.ValidChars

TcxCustomTextEditProperties

Specifies additional characters valid for a data-aware editor.

type

  TcxTextEditChars = set of Char;

property ValidChars: TcxTextEditChars;

Description

The ValidChars property specifies a set of characters a user can enter in a data-aware editor in addition to those that are acceptable by the field to which the editor is connected.  ValidChars is used by the editor’s IsValidChar function to determine whether the current character can appear in the edit box.


TcxCustomTextEditProperties.ViewStyle

TcxCustomTextEditProperties

Specifies the view style of the text and buttons in a text editor.

type

  TcxTextEditViewStyle = (vsNormal, vsHideCursor, vsButtonsOnly, vsButtonsAutoWidth);

property ViewStyle: TcxTextEditViewStyle;

Description

Use the ViewStyle property to specify the manner (view style) in which text and buttons are displayed in a text editor.  The table below describes the values that can be assigned to this property.

Value	Meaning
vsNormal	The text editor displays its text and buttons (if any).
vsHideCursor	The text editor displays its text and buttons (if any) and hides the edit cursor.  See the Properties.HideCursor property for details.
vsButtonsOnly	The text editor displays buttons only (if any).
vsButtonsAutoWidth	The text editor displays buttons only (if any).  The width of the text editor is adjusted according to the buttons’ widths.

The width of a particular button is controlled by their Width and Stretchable properties.

The default value of the ViewStyle property is vsNormal.


TcxCustomTextEditProperties.IsDisplayValueValid

TcxCustomTextEditProperties           See Also

Determines whether the specified display value is valid.

type

  TcxEditValue = Variant;

function IsDisplayValueValid(var DisplayValue: TcxEditValue): Boolean; virtual;

Description

The IsDisplayValueValid method returns True if the specified display value is valid and can be assigned to the Text property which stores the display value for an editor.  Otherwise, it returns False.

The function is called when

1)	assigning a value to the editor Text property;

2)	pasting the text from the clipboard;

3)	cutting the text to the clipboard.

If a user changes the display value by typing text, every character is validated by the editor’s IsValidChar protected method instead.

The ValidateDisplayValue method validates the display value before converting it to the edit value (when a user moves focus to another control or presses the Enter key).


TcxCustomTextEditProperties.OnNewLookupDisplayText

TcxCustomTextEditProperties

Occurs when the text entered into the editor does not belong to the automatic completion words list.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnNewLookupDisplayText: TNotifyEvent;

Description

The OnNewLookupDisplayText event occurs when the text entered into the editor does not belong to the automatic completion words list. Note that the OnNewLookupDisplayText event occurs only if the ValidateEdit method’s return value is True, i.e. the editor display text can be stored in the editor edit value.


TcxTextEditPropertiesValues
TcxTextEditPropertiesValues Object

Hierarchy          Properties          Methods

Contains the property flags that indicate which properties specific to a text editor have been changed.

Unit

cxTextEdit

TcxTextEditPropertiesValues = class(TcxCustomEditPropertiesValues);

Description

The TcxTextEditPropertiesValues class tracks the changes made to an editor’s DisplayFormat, EditFormat, MaxLength, MaxValue, MinValue and ReadOnly properties.  Once one of these properties is set to a value other than the default one, the changes are reflected in the TcxTextEditPropertiesValues class (its corresponding property flag is set to True).  To undo the changes made and reverse the property back to its default value, set the corresponding property flag to False or call the RestoreDefaults method to reverse all these properties back to their default values and reset all the property flags.  Use the BeginUpdate and EndUpdate methods to control when the editor repaints and avoid any flickering when the property flags are modified.


TcxTextEditPropertiesValues Hierarchy
Hierarchy

TPersistent

     |

TcxCustomEditPropertiesValues

     |


Properties for TcxTextEditPropertiesValues
TcxTextEditPropertiesValues Properties

TcxTextEditPropertiesValues          Legend

In TcxTextEditPropertiesValues

DisplayFormat

EditFormat

MaxLength

MaxValue

MinValue

Derived from TcxCustomEditPropertiesValues

ReadOnly


Methods for TcxTextEditPropertiesValues
TcxTextEditPropertiesValues Methods

TcxTextEditPropertiesValues          Legend

In TcxTextEditPropertiesValues

RestoreDefaults

Derived from TcxCustomEditPropertiesValues

BeginUpdate

EndUpdate


TcxTextEditPropertiesValues.DisplayFormat

TcxTextEditPropertiesValues          See Also

Specifies whether the format string of a text editor has been modified.

property DisplayFormat: Boolean;

Description

Once a text editor’s DisplayFormat property is set to a value other than the default one, the DisplayFormat property flag is set to True.  Otherwise, it’s set to False.  To undo the changes made to the text editor’s DisplayFormat property and reverse it back to its default value, call the RestoreDefaults method which resets all the property flags or set the DisplayFormat property flag to False.


TcxTextEditPropertiesValues.EditFormat

TcxTextEditPropertiesValues          See Also

Specifies if the format string used by a text editor when it's in edit mode has been modified.

property EditFormat: Boolean;

Description

Once a text editor’s EditFormat property is set to a value other than the default one, the EditFormat property flag is set to True.  Otherwise, it’s set to False.  To undo the changes made to the text editor’s EditFormat property and reverse it back to its default value, call the RestoreDefaults method which resets all the property flags or set the EditFormat property flag to False.


TcxTextEditPropertiesValues.MaxLength

TcxTextEditPropertiesValues          See Also

Specifies whether the maximum number of characters an end user can enter into an editor has been changed.

property MaxLength: Boolean;

Description

Once a text editor’s MaxLength property is set to a value other than the default one, the MaxLength property flag is set to True.  Otherwise, it’s set to False.  To undo the changes made to the text editor’s MaxLength property and reverse it back to its default value, call the RestoreDefaults method which resets all the property flags or set the MaxLength property flag to False.


TcxTextEditPropertiesValues.MaxValue

TcxTextEditPropertiesValues          See Also

Specifies whether the maximum numerical value that an editor can display has been changed.

property MaxValue: Boolean;

Description

Once a text editor’s MaxValue property is set to a value other than the default one, the MaxValue property flag is set to True.  Otherwise, it’s set to False.  To undo the changes made to the text editor’s MaxValue property and reverse it back to its default value, call the RestoreDefaults method which resets all the property flags or set the MaxValue property flag to False.


TcxTextEditPropertiesValues.MinValue

TcxTextEditPropertiesValues          See Also

Specifies whether the minimum numerical value that an editor can display has been modified.

property MinValue: Boolean;

Description

Once a text editor’s MinValue property is set to a value other than the default one, the MinValue property flag is set to True.  Otherwise, it’s set to False.  To undo the changes made to the text editor’s MinValue property and reverse it back to its default value, call the RestoreDefaults method which resets all the property flags or set the MinValue property flag to False.


TcxTextEditPropertiesValues.RestoreDefaults

TcxTextEditPropertiesValues          See Also

Reverses the values of the properties (changes to which are being tracked) back to their default values.

procedure RestoreDefaults; override;

Description

The RestoreDefaults method undoes any changes made to the properties and resets their values back to the default ones.  Calling this method sets the text editor’s properties being tracked (DisplayFormat, EditFormat, MaxLength, MaxValue, MinValue and ReadOnly) to the default values and resets the corresponding property flags to False.  Setting the property flag of each property being tracked to False has the same result as calling the RestoreDefaults method.


TcxTextEdit
 TcxTextEdit Object

Hierarchy          Properties          Methods          Events           See Also

Represents a single-line text editor.

Unit

cxTextEdit

TcxTextEdit = class(TcxCustomTextEdit);

Description

The TcxTextEdit class represents a TextEdit on a form. This editor is used as a single-line text editor. The TcxTextEdit class provides facilities to select text within the text editor, copy and cut the selection to the clipboard, specify the case and look & feel of the entered text etc. It also performs special functions, such as entered value validation and the automatic completion feature. The following image demonstrates the TextEdit painted using the UltraFlat style:


TcxTextEdit Hierarchy
Hierarchy

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |


Properties for TcxTextEdit
TcxTextEdit Properties

TcxTextEdit          Legend

Derived from TcxCustomTextEdit

ActiveProperties

BeepOnEnter

CursorPos

EditingText

Properties

SelLength

SelStart

SelText

Text

Derived from TcxCustomEdit

ActiveProperties

AutoSize

DataBinding

EditModified

EditValue

InnerEdit

ModifiedAfterEnter

Properties

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName


Methods for TcxTextEdit
TcxTextEdit Methods

TcxTextEdit          Legend

Derived from TcxCustomTextEdit

Clear

ClearSelection

CopyToClipboard

Create

CutToClipboard

SelectAll

SetSelection

Undo

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

SetSize

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxTextEdit
TcxTextEdit Events

TcxTextEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxTextEditProperties
TcxTextEditProperties Object

Hierarchy          Properties          Methods          Events

Contains settings specific to text editors.

Unit

cxTextEdit

TcxTextEditProperties = class(TcxCustomTextEditProperties);

Description

The TcxTextEditProperties class represents a set of attributes that control the behavior of text editors.  Properties for an editor are set via the Properties member of the corresponding editor.  To control any changes made to the editor’s DisplayFormat, EditFormat, MaxLength, MaxValue, MinValue and ReadOnly properties and reverse their values back to the default ones, use the AssignedValues property.

Properties of text editors control several aspects of the editor behavior: the HideSelection property affects the character selection within an editor; the CharCase and EchoMode properties affect the appearance of items entered into an editor; the MaxLength property determines the number of characters a user may input into an editor; the LookupItems property contains the list of words used for implementing the automatic completion feature within an editor, etc.


TcxTextEditProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |


Properties for TcxTextEditProperties
TcxTextEditProperties Properties

TcxTextEditProperties          Legend

Derived from TcxCustomTextEditProperties

AssignedValues

CharCase

EchoMode

HideCursor

HideSelection

ImeMode

ImeName

IncrementalSearch

LookupItems

LookupItemsSorted

MaxLength

MaxValue

MinValue

OEMConvert

PasswordChar

ValidChars

Derived from TcxCustomEditProperties

Alignment

AssignedValues

AutoSelect

BeepOnError

Buttons

ButtonsViewStyle

ClearKey

ClickKey

ImmediatePost

ReadOnly

UseLeftAlignmentOnEditing

UseMouseWheel

ValidateOnEnter


Methods for TcxTextEditProperties
TcxTextEditProperties Methods

TcxTextEditProperties          Legend

Derived from TcxCustomTextEditProperties

IsDisplayValueValid

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue


Events for TcxTextEditProperties
TcxTextEditProperties Events

TcxTextEditProperties          Legend

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomEdit
TcxCustomEdit Object

Hierarchy          Properties          Methods          Events           See Also

Represents the base class for all editors.

Unit

cxEdit

TcxCustomEdit = class(TcxContainer);

Description

The TcxCustomEdit class implements the basic functionality for all editors.

Most of editors (except image editors and checkbox controls) create an inner editor, inside which a user manipulates an edit value.  The inner editor is placed within a container which implements border drawing.  To access the inner editor directly use the InnerEdit property, though it is not a usual practice.

Edit values are set via the EditValue property.  The main members of TcxCustomEdit are Properties and Style, StyleDisabled, StyleFocused and StyleHot properties.  Properties store main attributes specific to the editor.  The styles control the look & feel of the editor (its background, border color, border style, font and many others) in various editor states.  The Styles property provides indexed access to these styles.

The TcxCustomEdit class introduces the Transparent property which controls the transparency state of an editor’s background.  Descendants of the TcxCustomEdit class publish this property if required for each specific editor.

Editors derived from the TcxCustomEdit class can work in two modes: standalone and in-place.  In-place editors allow you to embed them in other controls.  For instance, you can edit a cell value in a grid control using an in-place editor.  To create an in-place editor you should call the constructor and pass True as an AIsInplace argument.  In-place editors are drawn without a border.  The AutoSize property of in-place editors always returns False.  In-place editors cannot be used as data-aware controls by connecting directly to the data storage.

Do not create instances of the TcxCustomEdit class.  Use TcxCustomEdit descendants, which fully implement specific editors.

Editors derived from TcxCustomEdit can be bound to data storage.  In this instance, the editor displays a value from a specific field of this data storage and also can post the modified value back.  The connection with the data storage is organized by the DataBinding object.  Data binding is not implemented in non data-aware editors.

You can override some methods of the TcxCustomEdit class to create custom editors.


TcxCustomEdit Hierarchy
Hierarchy

TObject

     |

TPersistent

     |

TComponent

     |

TControl

     |

TWinControl

     |

TCustomControl

     |

TcxControl

     |

TcxContainer

     |


Properties for TcxCustomEdit
TcxCustomEdit Properties

TcxCustomEdit          Legend

In TcxCustomEdit

ActiveProperties

AutoSize

DataBinding

EditModified

EditValue

InnerEdit

ModifiedAfterEnter

Properties

RepositoryItem

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxCustomEdit
TcxCustomEdit Methods

TcxCustomEdit          Legend

In TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCustomEdit
TcxCustomEdit Events

TcxCustomEdit          Legend

In TcxCustomEdit

OnEditing

OnFocusChanged


TcxCustomEdit.ActiveProperties

TcxCustomEdit          See Also

Obtains the properties that are currently applied to an editor.

property ActiveProperties: TcxCustomEditProperties;

Description

Use the ActiveProperties property to obtain the properties of the current editor that are currently in effect.  This property is especially useful when the 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 editor.  Otherwise, the inherent editor’s properties are returned.

ReadOnly Property


TcxCustomEdit.AutoSize

TcxCustomEdit          See Also

Specifies whether an editor is resized to entirely display its contents.

property AutoSize: Boolean;

Description

Use the AutoSize property to specify whether an editor sizes itself automatically.  When AutoSize is set to True, the editor resizes automatically when its contents change.  Most descendant editors which support auto sizing simply modify their height according to the changes.  However, the TcxImage, TcxLabel and their data-aware versions, TcxDBImage and TcxDBLabel controls also adjust their widths.  For instance, when you change the font of the text editor, its height is resized to the minimum value that allows all its text to be displayed.  The TcxCustomImage editor also adjusts its width to accommodate the entire image.

The default value of the AutoSize property is True.


TcxCustomEdit.DataBinding

TcxCustomEdit           See also

Specifies the object binding an editor to data storage.

property DataBinding: TcxEditDataBinding;

Description

The DataBinding property connects an editor with data storage.  Data binding is not implemented in non data-aware editors.  Data-aware editors provide retrieving and posting data from a dataset.

Note: You can create your own data-binding class to supply data from custom data storage.  New classes must be derived from TcxEditDataBinding.  To make an editor use a new data-binding object, you have to override the GetDataBindingClass function declared in TcxCustomEdit.


TcxCustomEdit.EditModified

TcxCustomEdit

Indicates whether the edit value has been changed.

property EditModified: Boolean;

Description

The EditModified property is set to True if a user has modified the edit value.  If you assign the EditValue property programmatically, the EditModified flag is automatically set to False.


TcxCustomEdit.EditValue

TcxCustomEdit

Determines the edit value of an editor.

type

  TcxEditValue = Variant;

property EditValue: TcxEditValue;

Description

Use the EditValue property to access the value of an editor.

Some editors do not store the values being edited by a user in the EditValue property immediately.  They will be stored in EditValue after a user presses the Enter key sets focus to another control or performs any other action specific to the editor.  In this case, the currently edited value is validated first.

Some editors though (e.g. a checkbox control), store values directly in the EditValue property.


TcxCustomEdit.InnerEdit

TcxCustomEdit           See also

Specifies the inner editor wherein values are edited.

property InnerEdit: IcxCustomInnerEdit;

Description

The TcxCustomEdit class creates an inner editor within a container.  The inner editor is used to edit values, while the container draws the borders of the desired style around the editor.

The inner editor is created by the CreateInnerEdit method.

ReadOnly Property


TcxCustomEdit.ModifiedAfterEnter

TcxCustomEdit

Specifies whether the editor’s value has been modified after the editor has received focus.

property ModifiedAfterEnter: Boolean;

Description

Read the ModifiedAfterEnter property to determine whether the editor’s value has been changed since the editor has received focus.  Note that this property value isn’t automatically set to True if the editor’s value is changed via code.  At the same time, editor validation doesn’t take place if this property value is False.  Thus, you may need to set the ModifiedAfterEnter property to True manually when changing an editor’s value via code.

Please refer to the OnValidate event description for details on editor validation.


TcxCustomEdit.Properties

TcxCustomEdit           See Also

Identifies the main attributes specific to an editor.

property Properties: TcxCustomEditProperties;

Description

Use Properties to set specific attributes which control the editor behavior.  They define the alignment of editor contents, the collection of buttons displayed and the read-only status, etc.

The Properties object implements the validation of the display value before converting it to an edit value, of characters before entering them into the editor, of the display value before pasting from the clipboard or cutting to the clipboard.  The Properties property also provides events that are generated when clicking an editor button and when changing the editor display value, etc.


TcxCustomEdit.RepositoryItem

TcxCustomEdit          See Also

Specifies an object controlling values of editor properties.

property RepositoryItem: TcxEditRepositoryItem;

Description

A repository item is a standalone object defining specific editor properties.  When a repository item is assigned to the RepositoryItem attribute, all its properties (TcxEditRepositoryItem.Properties) are assigned to editor properties (TcxCustomEdit.Properties).

A repository item can be assigned to several editors.  You can define properties via a repository item and then assign it to several editors thus providing centralized behavior of editors.

Changing the properties of a repository item results in changing properties of all linked editors.  Similarly, if you change the properties of an editor assigned to a repository item, the changes are automatically applied to the properties of the repository item itself and thus to any other editors linked to it.


TcxCustomEdit.Style

TcxCustomEdit           See Also

Determines the style of an editor in the normal state.

property Style: TcxEditStyle;

Description

The Style property controls the different look & feel attributes of the editor in the normal state.  It allows you to adjust the border and background color, border style, font and many other properties.

Note:	In order to apply similar property values to several edit control simultaneously you should use the style controller.  To apply similar property values to all edit controls within your application, use the default style controller.


TcxCustomEdit.StyleDisabled

TcxCustomEdit           See Also

Determines the style of a disabled editor.

property StyleDisabled: TcxEditStyleEx;

Description

The StyleDisabled property controls different look & feel attributes of the disabled editor.  It allows you to adjust the border and background color, border style and font attributes.

Note:	In order to apply similar property values to several edit controls simultaneously you should use the style controller.  To apply similar property values to all the edit controls within your application, use the default style controller.


TcxCustomEdit.StyleFocused

TcxCustomEdit           See Also

Determines the style of a focused editor.

property StyleFocused: TcxEditStyleEx;

Description

The StyleFocused property controls different look & feel attributes of the editor which has focus.  It allows you to adjust the border and background color, border style and font attributes.

Note:	In order to apply similar property values to several edit controls simultaneously you should use the style controller.  To apply similar property values to all edit controls within your application, use the default style controller.


TcxCustomEdit.StyleHot

TcxCustomEdit           See Also

Determines the style of a disabled editor.

property StyleHot: TcxEditStyleEx;

Description

The StyleDisabled property controls different look & feel attributes of the disabled editor.  It allows you to adjust the border and background color, border style and font attributes.

Note:	In order to apply similar property values to several edit control simultaneously you should use the style controller.  To apply similar property values to all edit controls within your application, use the default style controller.


TcxCustomEdit.Transparent

TcxCustomEdit

Specifies whether the background of the current editor is transparent.

property Transparent: Boolean;

Description

Use the Transparent property to specify the transparency state of the current editor’s background.  Set the Transparent property to True to make the background of the editor transparent.  Otherwise, it appears opaque.

The default value of the Transparent property is False.


TcxCustomEdit.Styles

TcxCustomEdit

Provides access to the styles assigned to the current editor.

procedure Styles[AState: TcxContainerStateItem]: TcxCustomEditStyle;

Description

Each style corresponds to a particular editor state such as normal, disabled, etc. (see the TcxContainerStateItem type description for details).  The Styles property provides access to the specific style which is assigned to the current editor and matches the control state specified by the AState parameter.


TcxCustomEdit.AdjustInnerEditPosition

TcxCustomEdit

Adjusts the position of the inner editor.

procedure AdjustInnerEditPosition; virtual;

Description

The AdjustInnerEditPosition method adjusts the position of the inner editor within a container.  The TcxCustomEdit class descendants can override this method to correct the bounds and position of the inner editor.


TcxCustomEdit.AreChangeEventsLocked

TcxCustomEdit

Returns True when edit value change notifications are postponed by LockChangeEvents method calls.

function AreChangeEventsLocked: Boolean;


TcxCustomEdit.CanModify

TcxCustomEdit           See Also

Specifies whether the edit value can be modified.

function CanModify: Boolean; virtual;

Description

The CanModify method returns True if the edit value can be changed.  If ReadOnly of the Properties property is set to True, the CanModify method always returns False.  The CanModify method calls the CanModify method of the Properties object.

Descendants of the TcxCustomEdit class can override this method and provide their own conditions to enable modification.


TcxCustomEdit.Clear

TcxCustomEdit

Deletes the contents of an editor.

procedure Clear; virtual;

Description

The Clear method deletes the contents of an editor. After the call of this method, the EditValue property value depends on the editor type.  For instance, for the TcxTextEdit it is the empty string and for the TcxSpinEdit it is 0.


TcxCustomEdit.CopyToClipboard

TcxCustomEdit           See Also

Copies the selected portion of a value within an editor to the clipboard.

procedure CopyToClipboard; virtual;

Description

The CopyToClipboard method copies the selected portion of a value to the clipboard.  The TcxCustomEdit class does not implement this operation.  But some of its descendants implement it to copy text, graphics.


TcxCustomEdit.Create

TcxCustomEdit           See Also

Creates an instance of the TcxCustomEdit class.

constructor Create(AOwner: TComponent); override;

constructor Create(AOwner: TComponent; AIsInplace: Boolean); virtual;

Description

The constructor creates and initializes an instance of the TcxCustomEdit class.  You should never instantiate TcxCustomEdit directly.  This class serves as the base class from which other editors descend.

The AOwner parameter specifies the component, which becomes the owner of an editor.  It is responsible for destroying the edit control.

The second constructor allows you to create an in-place editor by specifying True as an AIsInplace parameter.  An in-place editor can be embedded in another control (a grid control, for instance).


TcxCustomEdit.CreateInnerEdit

TcxCustomEdit           See Also

Creates an inner editor within an edit control.

function CreateInnerEdit: IcxCustomInnerEdit; virtual;

Description

The CreateInnerEdit method creates an inner editor wherein a user edits values.  The inner editor does not have its own borders, thus is placed within a container which draws the borders.

To create an inner editor, the CreateInnerEdit method retrieves information on the inner editor ‘s class via the GetInnerEditClass function.


TcxCustomEdit.CutToClipboard

TcxCustomEdit           See Also

Cuts the selected portion of the display value within an editor to the clipboard.

procedure CutToClipboard; virtual;

Description

The CutToClipboard method copies the selected portion of the display value to the clipboard and then deletes it from the editor.  The TcxCustomEdit class does not implement this operation, but some of its descendants implement it to cut text, graphics.


TcxCustomEdit.Destroy

TcxCustomEdit

Destroys a TcxCustomEdit object.

destructor Destroy; override;

Description

The destructor destroys your editor and frees all resources allocated to it.  Do not call Destroy directly in applications, call the Free method instead.  The Free method verifies that the control is not nil and only then calls Destroy.


TcxCustomEdit.DoButtonClick

TcxCustomEdit           See Also

Performs some preprocessing when a user clicks an editor button.

procedure DoButtonClick(AButtonVisibleIndex: Integer); virtual;

Description

The DoButtonClick method is called after an editor button was clicked.  Editor buttons are provided by the Buttons collection of the Properties property.  The AButtonVisibleIndex parameter specifies the visible index of the clicked button.  The DoButtonClick method is called after the DoButtonDown and DoButtonUp methods.

The DoButtonClick method generates the OnButtonClick event.


TcxCustomEdit.DoButtonDown

TcxCustomEdit           See Also

Performs some processing when a user presses an editor button.

procedure DoButtonDown(AButtonVisibleIndex: Integer); virtual;

Description

The DoButtonDown method is called when a user presses an editor button.  Editor buttons are provided by the Buttons collection of the Properties property.  The AButtonVisibleIndex parameter specifies the visible index of a button.


TcxCustomEdit.DoButtonUp

TcxCustomEdit           See Also

Performs some processing when a user releases the pressed editor button.

procedure DoButtonUp(AButtonVisibleIndex: Integer); virtual;

Description

The DoButtonDown method is called when a user releases an editor button.  Editor buttons are provided by the Buttons collection of the Properties property.  The AButtonVisibleIndex parameter specifies the visible index of a button.


TcxCustomEdit.DoEditKeyDown

TcxCustomEdit           See Also

Performs some processing when a user presses any key while the editor has focus.

procedure DoEditKeyDown(var Key: Word; Shift: TShiftState); virtual;

Description

The Key parameter is a keyboard key.  The Shift parameter indicates whether the Shift, Alt, or Ctrl key is combined with a keystroke.

Before calling DoEditKeyDown, the OnKeyDown event is generated.


TcxCustomEdit.DoEditKeyPress

TcxCustomEdit           See Also

Performs some processing when a user has pressed and released a key within an editor.

procedure DoEditKeyPress(var Key: Char); virtual;

Description

The Key parameter identifies the ASCII code of the pressed key.  The DoEditKeyDown method is called only for the keys corresponding to the ASCII Char value.  The Shift or F1 keys, for instance, do not invoke the DoEditKeyDown method.

Before calling DoEditKeyPress, the OnKeyPress event is generated.


TcxCustomEdit.DoEditKeyUp

TcxCustomEdit           See Also

Performs some processing when a user releases the pressed key.

procedure DoEditKeyUp(var Key: Word; Shift: TShiftState); virtual;

Description

The Key parameter is a keyboard key.  The Shift parameter indicates whether the Shift, Alt, or Ctrl key is combined with a keystroke.

Before calling DoEditKeyUp, the OnKeyUp event is generated.


TcxCustomEdit.DoOnChange

TcxCustomEdit

Performs additional processing when the display value within an editor is about to be changed.

procedure DoOnChange; virtual;

Description

The DoOnChange method fires the Properties.OnChange event, thus by overriding the DoOnChange method in the TcxCustomEdit descendant you can perform additional custom actions (if required), prior to the editor’s displayed value being changed and the Properties.OnChange event is fired.


TcxCustomEdit.DoOnEditValueChanged

TcxCustomEdit

Performs additional processing when the edit value within an editor is about to be changed.

procedure DoOnEditValueChanged; virtual;

Description

The DoOnEditValueChanged method fires the Properties.OnEditValueChanged event, thus by overriding the DoOnEditValueChanged method in the TcxCustomEdit descendant you can perform additional custom actions (if required), prior the editor’s edit value being changed and the Properties.OnEditValueChanged event is fired.


TcxCustomEdit.GetInnerEditClass

TcxCustomEdit           See Also

Returns the class of an inner editor.

type

  TControlClass = class of TControl;

function GetInnerEditClass: TControlClass; virtual;

Description

The GetInnerEditClass method returns the class of an inner editor.  The CreateInnerEdit method uses information on the class returned by GetInnerEditClass to create an instance of the inner editor.


TcxCustomEdit.GetPropertiesClass

TcxCustomEdit           See Also

Returns the class of a Properties object.

type

  TcxCustomEditPropertiesClass = class of TcxCustomEditProperties;

class function GetPropertiesClass: TcxCustomEditPropertiesClass; virtual;

Description

The GetPropertiesClass returns the class of a Properties object.  Properties defines a set of attributes specific to the editor.


TcxCustomEdit.IsValidChar

TcxCustomEdit          See Also

Determines whether the specified character can be entered into an editor.

function IsValidChar(AChar: Char): Boolean; virtual;

Description

The IsValidChar method is called whenever a user enters a character in the editor.  The IsValidChar function returns True if the character provided by the AChar parameter can be entered into the editor.  If the function returns False, the character is ignored.  When a user changes the display value by pasting from the clipboard or cutting to the clipboard, the value is checked by the Properties.IsDisplayValueValid function.

For instance, if a data-aware edit control is connected to the field that provides only integer values, a user can only enter the digits 0-9.  Other symbols are ignored by the IsValidChar function.

The Properties.ValidateDisplayValue method validates the display value before converting it to the edit value (when a user moves focus to another control or presses the Enter key).


TcxCustomEdit.LockChangeEvents

TcxCustomEdit          See Also

Enables/postpones edit value change notification events.

procedure LockChangeEvents(ALock: Boolean; AInvokeChangedOnUnlock: Boolean = True);

Description

To prevent the Properties.OnChange and Properties.OnEditValueChanged events from being generated during intermediate edit value updates, enclose the code performing the updates within LockChangeEvents(True) / LockChangeEvents(False) blocks.

Pass False as the AInvokeChangedOnUnlock parameter to prohibit these events from being generated when the last LockChangeEvents(False) call is made.

Use the AreChangeEventsLocked property to determine whether change notifications are currently postponed for the editor.


TcxCustomEdit.LockEditValueChanging

TcxCustomEdit          See Also

Enables/postpones the OnEditing event.

procedure LockEditValueChanging(ALock: Boolean);

Description

To prevent the OnEditing event from being generated during intermediate value edit mode initializations, enclose the code performing these operations within LockEditValueChanging(True) / LockEditValueChanging(False) blocks.


TcxCustomEdit.PasteFromClipboard

TcxCustomEdit           See Also

Pastes the contents of the clipboard to an editor by replacing the current selection.

procedure PasteFromClipboard; virtual;

Description

The PasteFromClipboard method pastes the contents of the clipboard to an editor at the current position.  It replaces the editor selection with the clipboard contents.  TcxCustomEdit does not implement this operation, but some of its descendants implement it to paste text, graphics.


TcxCustomEdit.PostEditValue

TcxCustomEdit           See Also

Writes the value to a data storage.

procedure PostEditValue;

Description

The PostEditValue method writes the edit value to a data storage by assigning it to the StoredValue property of the DataBinding object.


TcxCustomEdit.PropertiesChanged

TcxCustomEdit           See Also

Performs some processing when changing editor properties.

procedure PropertiesChanged(Sender: TObject); virtual;

Description

The PropertiesChanged method is called when any attributes of the Properties property are changed.  PropertiesChanged updates the editor by calling RefreshEdit.


TcxCustomEdit.RefreshEdit

TcxCustomEdit

Updates an edit control.

type

  TcxMouseButton = (cxmbNone, cxmbLeft, cxmbRight, cxmbMiddle);

function RefreshEdit(AIsMouseEvent: Boolean): Boolean; virtual;

function RefreshEdit(P: TPoint; Button: TcxMouseButton; Shift: TShiftState; AIsMouseEvent: Boolean): Boolean; virtual;

Description

The RefreshEdit method is called when it is necessary to update an editor.  It is updated by redrawing its elements (inner editor, buttons, borders).    The method determines the region to update.  For this purpose, it requires information on the mouse coordinates (the P parameter) and the state of the mouse buttons (the Button and Shift parameters).  The AIsMouseEvent parameter specifies whether the updating is performed due to the mouse event.

The first variant of the RefreshEdit method invokes the second overloaded variant.  It calls the system functions to determine the mouse cursor coordinates and state of the mouse buttons.


TcxCustomEdit.ResetEditValue

TcxCustomEdit           See Also

Restores the previous edit value.

procedure ResetEditValue; virtual;

Description

Before being changed by a user, the edit value is stored in an internal variable.  The user can post his/her changes by pressing the ENTER key or cancel them by pressing the ESC key, for instance.  When the value needs to be restored, the ResetEditValue method is called.


TcxCustomEdit.SelectAll

TcxCustomEdit

Selects the edit value within an editor.

procedure SelectAll; virtual;

Description

The SelectAll method selects the contents of an editor.


TcxCustomEdit.SetSize

TcxCustomEdit           See Also

Adjusts the editor bounds.

procedure SetSize; virtual;

Description

The SetSize method sets the width and height of an editor if the AutoSize property is set to True.  All editors adjust their heights.  The TcxCustomImage adjusts the width.


TcxCustomEdit.ValidateEdit

TcxCustomEdit

Validates the display value of an editor.

function ValidateEdit(ARaiseExceptionOnError: Boolean): Boolean; virtual;

Description

When a user enters a value into an editor, he/she actually changes the display value (not the edit value).  Before converting the display value to an edit value it needs to be validated.  The ValidateEdit function returns True if the display value has been validated and converted to EditValue, otherwise, it returns False.

ValidateEdit makes a subsequent call to the Properties.ValidateDisplayValue method, performing necessary validations.  Properties.ValidateDisplayValue also generates the Properties.OnValidate event, which allows a user to redefine the validation results.  If the display value is not validated, it is not converted to an edit value.

If the ARaiseExceptionOnError parameter is True and validation failed then an exception is generated.  Otherwise, an exception is not raised.  You can use the ValidateEdit method with ARaiseExceptionOnErro set to False to safely check the display value.

If validation is successful, the Properties.OnEditValueChanged event is generated and a new edit value is assigned to the EditValue property.


TcxCustomEdit.OnEditing

TcxCustomEdit

Occurs when a user tries to modify the edit value.

type

  TcxEditEditingEvent = procedure(Sender: TObject; var CanEdit: Boolean) of object;

property OnEditing: TcxEditEditingEvent;

Description

When a user enters an editor and initiates the editing operation (presses a key) to modify the edit value, the OnEditing event is generated.  By writing an event handler you can enable or disable the following editing.  Assigning False to the CanEdit parameter cancels the editing operation.  By default, the CanEdit parameter is set to True.

As for standalone editors, if the CanEdit parameter is True, the edit mode is set for the data storage by calling the DataBinding.SetEditMode function.

If this sequence of operations succeeds, the editing is enabled; otherwise, user keystrokes are ignored.


TcxCustomEdit.OnFocusChanged

TcxCustomEdit

Occurs when an editor receives or loses the keyboard focus.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnFocusChanged: TNotifyEvent;

Description

Write an OnFocusChanged event handler to perform specific actions when an editor receives or loses the keyboard focus.  To determine whether your editor is currently focused call the Focused function.


TcxCustomEditStyle
TcxCustomEditStyle Object

Hierarchy          Properties          Methods          See Also

Represents the properties that control the look & feel of an editor.

Unit

cxEdit

TcxCustomEditStyle = class(TcxCustomContainerStyle);

Description

The TcxCustomEditStyle class contains a set of properties that control the look & feel of an edit control.  You can set the border color, border and button styles, font and many other attributes.

The LookAndFeel property determines the default look & feel of an editor.  When working in Windows XP, you can enable the native style by setting the LookAndFeel.NativeStyle attribute to True.  The LookAndFeel.Kind attribute determines the default look & feel of editor borders, buttons and highlighting effects.

You can override the default look & feel of an editor by assigning appropriate style attributes.  When you assign style attributes, the corresponding flags are set in the AssignedValues property.  This indicates that the corresponding style attributes were overridden and are used to display editor elements.  You can use the RestoreDefaults method to clear all the flags in the AssignedValues property, thus restoring the default values of the assigned style attributes.  Note that changes to the look & feel attributes are tracked explicitly as the LookAndFeel property has its own AssignedValues property.

The style controller enables you to define the same style settings for more than one editor.  Place a TcxEditStyleController instance onto a form and set the StyleController property of an edit control to the style controller.  The TcxEditStyleController.Style property contains style settings common to several editors.

The default style controller lets you define the same style settings for all editors that have no style controller assigned.  With a TcxDefaultEditStyleController instance placed onto a form you can control the appearance of all editors within your application by a single mouse click.  This greatly simplifies the customization of your application’s appearance.

If a specific style attribute is assigned either via an editor style or via the style controller linked to the editor, this attribute value will be used to display an edit control.  Otherwise, there are two cases to consider:

•	Both the editor and the linked style controller have the same style attribute assigned to some value.  In this case the value of the editor’s style attribute overrides the attribute value of the style controller.

•	Neither the editor nor the style controller has a specific style attribute assigned.  In this case the editor uses the default value of this style attribute determined by the LookAndFeel.Kind property.

For instance, you can define the same style attributes via the style controller, apply them to two edit controls and then, for instance, redefine Font for one editor.  When you assign a value to the TcxCustomEdit.Style.Font property the corresponding svFont flag is set in TcxCustomEdit.Style.AssignedValues.  It indicates that the font value should be obtained from the TcxCustomEdit.Style.Font property and not from the font attribute of the style controller.

Suppose we have two editors and the style controller linked to these editors.

// Delphi

  cxTextEdit1.Style.Font.Name := 'Courier';

  cxTextEdit1.Style.StyleController := cxEditStyleController1;

  cxTextEdit2.Style.StyleController := cxEditStyleController1;

  cxEditStyleController1.Style.Font.Name := 'Comic Sans MS';

  cxEditStyleController1.Style.BorderStyle := ebsSingle;

// C++ Builder

  cxTextEdit1->Style->Font->Name = "Courier";

  cxTextEdit1->Style->StyleController = cxEditStyleController1;

  cxTextEdit2->Style->StyleController = cxEditStyleController1;

  cxEditStyleController1->Style->Font->Name = "Comic Sans MS";

  cxEditStyleController1->Style->BorderStyle = ebsSingle;

In this example, the cxTextEdit2 editor will use the font and border styles from the style controller.  The cxTextEdit1 editor is drawn with the Courier font but the border style for the editor is defined by the style controller.  Other style attributes are not assigned either to the editor style or to the style controller and therefore are defined by the default values set in the editor style.


TcxCustomEditStyle Hierarchy
Hierarchy

TPersistent

     |

TcxCustomContainerStyle

     |


Properties for TcxCustomEditStyle
TcxCustomEditStyle Properties

TcxCustomEditStyle          Legend

In TcxCustomEditStyle

ActiveStyleController

AssignedValues

BaseStyle

BorderStyle

ButtonTransparency

Edit

PopupBorderStyle

StyleController

Derived from TcxCustomContainerStyle

BorderColor

ButtonStyle

Color

Container

Edges

Font

HotTrack

LookAndFeel

Shadow

State

TextColor

TextStyle

TransparentBorder


Methods for TcxCustomEditStyle
TcxCustomEditStyle Methods

TcxCustomEditStyle          Legend

Derived from TcxCustomContainerStyle

RestoreDefaults


TcxCustomEditStyle.ActiveStyleController

TcxCustomEditStyle

Identifies the style controller which manages the appearance of an editor.

property ActiveStyleController: TcxEditStyleController;

Description

Use the ActiveStyleController property to get the style controller (TcxEditStyleController or TcxDefaultEditStyleController descendant) which actually manages the style of the editor and defines the style properties common to several editor controls.

See the Editor Style and StyleControllers topic for detailed information about style controllers.

ReadOnly Property


TcxCustomEditStyle.AssignedValues

TcxCustomEditStyle           See Also

Specifies which style properties are assigned via the TcxCustomEditStyle class.

property AssignedValues: TcxEditStyleValues;

Description

The AssignedValues property is a set of flags demonstrating which style properties were set by a user at design time or programmatically.  AssignedValues controls whether values for style properties are obtained from the current TcxCustomEditStyle instance or from the style controller, which can be set via the StyleController property.

The RestoreDefaults method restores the default values of the assigned style attributes and clears all the flags in the AssignedValues property of the current TcxCustomEditStyle object.


TcxCustomEditStyle.BaseStyle

TcxCustomEditStyle

Determines the base style which is used to paint an editor.

property BaseStyle: TcxCustomEditStyle;

Description

When the ParentStyle property is assigned, the BaseStyle property returns its value as the base style used to paint the editor control.  Otherwise, the current style is returned.

ReadOnly Property


TcxCustomEditStyle.BorderColor

TcxCustomEditStyle           See Also

Specifies the border color of an editor.

property BorderColor: TColor;

Description

Use this property to get or set the color used to draw the border around your editor.  Only editors with BorderStyle set to the ebsThick or ebsSingle value use BorderColor to draw the border.

When the BorderColor property is assigned, the svBorderColor flag is set to the AssignedValues property.


TcxCustomEditStyle.BorderStyle

TcxCustomEditStyle           See Also

Defines the border style.

property BorderStyle: TcxEditBorderStyle;

Description

The BorderStyle property specifies the style of the border around an editor.  Border styles are described by the TcxEditBorderStyle enumerator.  You can set the border color using the BorderColor property for the editors with the BorderStyle property set to ebsThick or ebsSingle.

When the BorderStyle property is assigned, the svBorderStyle flag is set to the AssignedValues property.


TcxCustomEditStyle.ButtonStyle

TcxCustomEditStyle           See Also

Identifies the style of buttons within an editor.

property ButtonStyle: TcxEditButtonStyle;

Description

Use the ButtonStyle property to specify the style of buttons within an editor.  Button styles are represented by the TcxEditButtonStyle enumerator.  If ButtonStyle is set to btsDefault, buttons are drawn in the manner in which the editor borders are displayed.

When the ButtonStyle property is assigned, the svButtonStyle flag is set to the AssignedValues property.


TcxCustomEditStyle.ButtonTransparency

TcxCustomEditStyle           See Also

Specifies the manner in which editor buttons are displayed.

property ButtonTransparency: TcxEditButtonTransparency;

Description

The ButtonTransparency property allows you to define the different manners in which editor buttons are displayed when the edit control has or has not focus and when the mouse is positioned over it.  The TcxEditButtonTransparency enumerator represents the button transparency styles.

When the ButtonTransparency property is assigned, the svButtonTransparency flag is set to the AssignedValues property.


TcxCustomEditStyle.Color

TcxCustomEditStyle

Specifies the background color of an edit control.

property Color: TColor;

Description

Use the Color property to get and set the background color of an editor.


TcxCustomEditStyle.Edges

TcxCustomEditStyle

Defines which edges are displayed within an editor.

type

  TcxBorder = (bLeft, bTop, bRight, bBottom);

  TcxBorders = set of TcxBorder;

property Edges: TcxBorders;

Description

Use the Edges property to hide/show individual edges of your editor.  The following table describes the meaning of the TcxBorder values.

Value	Meaning	Edges do not contain the corresponding flag
bLeft	If the flag is not set, the left border edge is invisible.
bTop	If the flag is not set, the top border edge is invisible.
bRight	If the flag is not set, the right border edge is invisible.
bBottom	If the flag is not set, the bottom border edge is invisible.

The BorderStyle property determines when the borders should be painted.  If they should, the editor determines which edges to draw by examining the Edges property.


TcxCustomEditStyle.Edit

TcxCustomEditStyle

Specifies the editor which owns the current style.

property Edit: TcxCustomEdit;

Description

Use the Edit property to get the editor which owns the current style.  For non-TcxCustomEdit descendants, this property returns nil.


TcxCustomEditStyle.Font

TcxCustomEditStyle

Specifies the font to draw the text of an editor.

property Font: TFont;

Description

Use the Font property to specify the font to draw the editor text.


TcxCustomEditStyle.HotTrack

TcxCustomEditStyle

Specifies whether editor items are highlighted when the mouse is positioned over an editor control.

property HotTrack: Boolean;

Description

Set the HotTrack property to True to highlight an editor in response to mouse movements.

The next image demonstrates the TcxButtonEdit control where BorderStyle is set to ebsFlat, ButtonStyle is set to btsDefault and the HotTrack property value is set to True.


TcxCustomEditStyle.LookAndFeel

TcxCustomEditStyle

Determines the default appearance of an editor.

property LookAndFeel: TcxLookAndFeel;

Description

Use the LookAndFeel property to specify the editor’s default appearance.  It provides two attributes: NativeStyle and Kind.

NativeStyle determines whether control elements (borders, buttons, and background) are drawn using the Windows XP style.  If you use the native style, other style attributes (the BorderStyle, BorderColor, ButtonStyle, Edges, PopupBorderStyle, TcxLookAndFeel.Kind and TransparentBorder properties) are ignored.

The Kind property specifies the default appearance of an editor.  It determines the appearance of the editor borders, buttons and highlighting effects only if the BorderStyle is not explicitly set in the current TcxCustomEditStyle object or in the style controller (the TcxCustomEditStyle.AssignedValues and StyleController.AssignedValues properties do not contain the corresponding svBorderStyle flag).


TcxCustomEditStyle.PopupBorderStyle

TcxCustomEditStyle

Defines the style of the popup window border.

type

  TcxEditPopupBorderStyle = (epbsDefault, epbsSingle, epbsFrame3D, epbsFlat);

property PopupBorderStyle: TcxEditPopupBorderStyle;

Description

Use the PopupBorderStyle property to set the border style of the popup window associated with an editor.  The TcxEditPopupBorderStyle type enumerates the popup window’s border styles.  If PopupBorderStyle is set to epbsDefault, the popup borders are drawn in the manner in which the editor borders are displayed.


TcxCustomEditStyle.Shadow

TcxCustomEditStyle

Specifies whether to display a shadow for an editor.

property Shadow: Boolean;

Description

Set the Shadow property to True to provide the shadow effect for an editor.  Set the Shadow property to False to disable the shadow effect.

The following image demonstrates the TcxButtonEdit control with the shadow effect enabled.

When the Shadow property is assigned, the svShadow flag is set to the AssignedValues property.


TcxCustomEditStyle.StyleController

TcxCustomEditStyle           See Also

Identifies the style controller for the current TcxCustomEditStyle object.

property StyleController: TcxEditStyleController;

Description

Use the StyleController property to assign the style controller, defining the style attributes common to several editors.  To force editors to use specific style attributes from the style controller, you should assign these style attributes in the TcxEditStyleController.Style and not in the current TcxCustomEditStyle object (the corresponding flags must be set in the TcxEditStyleController.Style.AssignedValues property, but not in the AssignedValues property of the current TcxCustomEditStyle object).


TcxCustomEditStyle.TransparentBorder

TcxCustomEditStyle           See Also

Specifies whether a transparent border is drawn around an editor.

property TransparentBorder: Boolean;

Description

Set the TransparentBorder property to True to draw a transparent border around an editor.  Otherwise, it will not be drawn.  The width of a transparent border depends on the current border’s width specified by the BorderStyle property.  The aggregate transparent border’s and current border’s width cannot exceed 2 pixels.  For instance, a transparent border is 2 pixels wide for an editor with its BorderStyle property set to ebsNone and 1 pixel wide for an editor with the BorderStyle property set to ebsSingle, ebsUltraFlat or ebsOffice11.  For an editor which uses native windows style for its painting the transparent border is drawn when its BorderStyle property is set to ebsNone.  When the TransparentBorder property is assigned, the svTransparentBorder flag is set to the AssignedValues property.


TcxCustomEditStyle.RestoreDefaults

TcxCustomEditStyle

Restores the default values of style attributes.

procedure RestoreDefaults;

Description

The RestoreDefaults method restores the style attributes (BorderColor, BorderStyle, ButtonStyle, ButtonTransparency, Color, Edges, Font, HotTrack, LookAndFeel.Kind, PopupBorderStyle, Shadow, TextColor, TextStyle and TransparentBorder) to their default values and clears all the flags in the AssignedValues property.  Default style attributes are determined by the LookAndFeel property.

If an editor is linked to the style controller, which has the style attributes assigned to some values, the RestoreDefaults method forces the editor to use the corresponding style properties from the style controller.


TcxEditStyle
TcxEditStyle Object

Hierarchy          Properties          Methods          See also

Represents the properties controlling the editor’s look & feel in the normal state.

Unit

cxEdit

TcxEditStyle = class(TcxCustomEditStyle);

Description

The TcxEditStyle class describes the style attributes for popup editors such as TcxCustomPopupEdit in their normal state.  It publishes the ButtonStyle, ButtonTransparency, PopupBorderStyle, TextColor and TextStyle properties which define the style of editor buttons and the popup window associated with the edit control.

TcxEditStyleController provides the Style property of class TcxEditStyle and this allows the same appearance style to be specified for several editors in the normal state.

Refer to the TcxCustomEditStyle topic to learn about style adjustment.


TcxEditStyle Hierarchy
Hierarchy

TPersistent

     |

TcxCustomContainerStyle

     |

TcxCustomEditStyle

     |


Properties for TcxEditStyle
TcxEditStyle Properties

TcxEditStyle          Legend

Derived from TcxCustomEditStyle

ActiveStyleController

AssignedValues

BaseStyle

ButtonStyle

ButtonTransparency

Edit

PopupBorderStyle

StyleController

Derived from TcxCustomContainerStyle

BorderColor

BorderStyle

Color

Container

Edges

Font

HotTrack

LookAndFeel

Shadow

State

TextColor

TextStyle

TransparentBorder


Methods for TcxEditStyle
TcxEditStyle Methods

TcxEditStyle          Legend

Derived from TcxCustomContainerStyle

RestoreDefaults


TcxEditStyleEx
TcxEditStyleEx Object

Hierarchy          Properties          Methods          See also

Represents the properties controlling the editor’s look & feel in states other than the normal one such as disabled, focused and hot-tracked.

Unit

cxEdit

TcxEditStyleEx = class(TcxCustomEditStyle);

Description

The TcxEditStyleEx class describes the style attributes for popup editors such as TcxCustomPopupEdit in the disabled, focused and hot-tracked states.  It publishes the ButtonStyle, TextColor and TextStyle properties which define the style of editor buttons associated with the edit control.

TcxEditStyleController provides the StyleDisabled, StyleFocused and StyleHot properties of the TcxEditStyleEx class and this allows the same appearance style to be specified for several editors in the normal state.

Refer to the TcxCustomEditStyle topic to learn about style adjustment.


TcxEditStyleEx Hierarchy
Hierarchy

TPersistent

     |

TcxCustomContainerStyle

     |

TcxCustomEditStyle

     |


Properties for TcxEditStyleEx
TcxEditStyleEx Properties

TcxEditStyleEx          Legend

Derived from TcxCustomEditStyle

ActiveStyleController

AssignedValues

BaseStyle

ButtonStyle

ButtonTransparency

Edit

PopupBorderStyle

StyleController

Derived from TcxCustomContainerStyle

BorderColor

BorderStyle

Color

Container

Edges

Font

HotTrack

LookAndFeel

Shadow

State

TextColor

TextStyle

TransparentBorder


Methods for TcxEditStyleEx
TcxEditStyleEx Methods

TcxEditStyleEx          Legend

Derived from TcxCustomContainerStyle

RestoreDefaults


cxNavigator Unit Overview
cxNavigator Unit

Classes

TcxCustomDBNavigator

TcxCustomNavigator

TcxCustomNavigatorButtons

TcxCustomNavigatorControl

TcxDBNavigator

TcxDBNavigatorButtons

TcxNavigatorButton

TcxNavigator

TcxNavigatorControlButtons

Interfaces

IcxNavigator

IcxNavigatorOwner

Global Constants

NavigatorButtonCount

NBDI_APPEND

NBDI_CANCEL

NBDI_DELETE

NBDI_EDIT

NBDI_FILTER

NBDI_FIRST

NBDI_GOTOBOOKMARK

NBDI_INSERT

NBDI_LAST

NBDI_NEXT

NBDI_NEXTPAGE

NBDI_POST

NBDI_PRIORPAGE

NBDI_PRIOR

NBDI_REFRESH

NBDI_SAVEBOOKMARK


TcxCustomDBNavigator
TcxCustomDBNavigator Object

Hierarchy          Properties          Methods

The TcxCustomDBNavigator class implements the navigation functionality used for managing controls connected to a data source.

Unit

cxNavigator

TcxCustomDBNavigator = class(TcxCustomNavigator);

Description

TcxCustomDBNavigator is a further development of the TcxCustomNavigator class.  This class provides for connecting to a custom data source via the DataSource property.

The Buttons property provides access to the buttons collection.  Each button in this collection represents a certain action to be performed on data records.  For instance, the First button moves the cursor to the first record in the dataset, the Insert button inserts a new record, etc.


TcxCustomDBNavigator Hierarchy
Hierarchy

TCustomControl

     |

TcxCustomNavigator

     |


Properties for TcxCustomDBNavigator
TcxCustomDBNavigator Properties

TcxCustomDBNavigator          Legend

In TcxCustomDBNavigator

Buttons

DataSource

Derived from TcxCustomNavigator

CustomButtons

LookAndFeel


Methods for TcxCustomDBNavigator
TcxCustomDBNavigator Methods

TcxCustomDBNavigator          Legend

Derived from TcxCustomNavigator

 NavigatorButtonsStateChanged

 RefreshNavigator


TcxCustomDBNavigator.Buttons

TcxCustomDBNavigator

Provides access to db-aware navigator buttons.

property Buttons: TcxDBNavigatorButtons;

Description

Use the Buttons property to access the collection of buttons for cxDBNavigator.  Refer to the TcxDBNavigatorButtons topic for the list of the available navigator buttons.

These buttons represent the db-aware functionality, i.e. all the actions refer to the specified database.   By contrast, the standard non-db buttons have functionality as defined in the appropriate control (see IcxNavigator).


TcxCustomDBNavigator.DataSource

TcxCustomDBNavigator

Provides the link between the navigator control and a dataset.

property DataSource: TDataSource;

Description

Use the DataSource property to link a navigator to the dataset.  Specify the data source component that identifies the dataset manipulated by the navigator.  Using this property, you can specify all source types, for instance, BDE and ADO.  The only limitation is that you should use a non-db navigator (TcxNavigator) when working with unbound controls.

cxDBNavigator provides a two-way communication between the control and the dataset, every navigator action affects the dataset and the dataset state is reflected by the control.  For instance, if the dataset cursor is programmatically moved to the first record – the First button is disabled, etc.

An example from the supplied EditorsMaskDemo:

//Delphi

DBNavigator1.DataSource := EditorsMaskDemoMainDM.DataSourceUSERS;

//C++ builder

DBNavigator1->DataSource = EditorsMaskDemoMainDM->DataSourceUSERS;


TcxCustomNavigator
TcxCustomNavigator Object

Hierarchy          Properties          Methods

This class implements basic navigator functionality with capabilities exceeding the standard Delphi navigator.

Unit

cxNavigator

TcxCustomNavigator = class(TCustomControl, IcxMouseTrackingCaller, IcxNavigatorOwner);

Description

TcxCustomNavigator is the base class for all (db and non-db) navigators provided by the ExpressEditors suite.  In contrast to a standard navigator, it presents a collection of customizable buttons that can be accessed using the CustomButtons property.  Each button can have its own image (default or custom) and hint.

Navigator functionality is implemented by the Button, Buttons and ViewInfo classes.  As these classes do not have their own window control, they do not possess a canvas for drawing.  Thus, they require an external window to display themselves and this is accessed via the IcxNavigatorOwner interface.

The look & feel of a navigator can be specified by its LookAndFeel property.  The LookAndFeel.NativeStyle property determines whether the navigator is painted using XP themes.  The LookAndFeel.Kind property specifies the borders, colors and highlighting settings applied to the navigator.

This class provides facilities for monitoring the state of the managed control and setting appropriate button states.  This is implemented via the NavigatorButtonsStateChanged method.

When it is necessary to recalculate and repaint a navigator control due to any view changes, the RefreshNavigator method is called.  This is required, for instance, when a button is hidden or when a button image is changed.


TcxCustomNavigator Hierarchy
Hierarchy

TCustomControl

     |


Properties for TcxCustomNavigator
TcxCustomNavigator Properties

TcxCustomNavigator          Legend

In TcxCustomNavigator

CustomButtons

LookAndFeel


Methods for TcxCustomNavigator
TcxCustomNavigator Methods

TcxCustomNavigator          Legend

In TcxCustomNavigator

 NavigatorButtonsStateChanged

 RefreshNavigator


TcxCustomNavigator.CustomButtons

TcxCustomNavigator

Used to provide access to navigator buttons.

property CustomButtons: TcxCustomNavigatorButtons;

Description

Use the Buttons property to access the collection of buttons for a navigator control.  Refer to the TcxCustomNavigatorButtons topic to learn about the available navigator buttons and their functionality.  Note that this functionality may differ for db and non-db navigators.

ReadOnly Property


TcxCustomNavigator.LookAndFeel

TcxCustomNavigator

Specifies the look and feel of a navigator control.

property LookAndFeel: TcxLookAndFeel;

Description

The LookAndFeel property controls the look and feel of the navigator control and the style behavior in response to user actions.

The NativeStyle attribute determines whether the control’s elements 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 or themes are not supported, the Kind property specifies the look and feel of the navigator.  The styles enumerated by the TcxLookAndFeel type determine the manner in which the navigator is painted and how it responds to mouse events.


TcxCustomNavigator.NavigatorButtonsStateChanged

TcxCustomNavigator

Sets the appropriate state (enabled or disabled) for each navigator button in accordance with the managed object state.

procedure NavigatorButtonsStateChanged;

Description

The NavigatorButtonsStateChanged method checks the object to which the navigator is applied and updates the state of each navigator button - one by one.  Each button has its own conditions for enabling/disabling.  For instance, when the first record is active, the First button must be disabled.  When a user presses the First navigator button – it is disabled automatically, but this action may occur without using the navigator.  In this case, the NavigatorButtonsStateChanged method must be used.

Another example:

When the EOF attribute of the dataset is True (when there are no more records to advance), Last, Next and NextPage buttons are disabled.


TcxCustomNavigator.RefreshNavigator

TcxCustomNavigator         See Also

Repaints the control due to view modifications.

procedure RefreshNavigator;

Description

The RefreshNavigator method is called internally to recalculate and repaint a navigator on screen.  It in turn calls the Repaint method.  The RefreshNavigator method is called when any view information is changed.  For instance, this method is called when the button’s Enable property is modified.


TcxCustomNavigatorControl
TcxCustomNavigatorControl Object

Hierarchy          Properties          Methods          See Also

This class implements base navigator component functionality for working with unbound controls.

Unit

cxNavigator

TcxCustomNavigatorControl = class(TcxCustomNavigator);

Description

TcxCustomNavigatorControl is a direct descendant of the base navigator class.  Users who want to create their own visual navigator controls for working with unbound controls must inherit from this class.

TcxCustomNavigatorControl and its descendants are designed to manage an external control.  This control must implement the IcxNavigator interface, which in turn has all functionality to manipulate data.

If the control implements this interface, it must provide the appropriate procedure for each button.  In that way any custom actions can be applied to buttons and even unbound data can be managed using the navigator control.


TcxCustomNavigatorControl Hierarchy
Hierarchy

TCustomControl

     |

TcxCustomNavigator

     |


Properties for TcxCustomNavigatorControl
TcxCustomNavigatorControl Properties

TcxCustomNavigatorControl          Legend

In TcxCustomNavigatorControl

Buttons

Control

Derived from TcxCustomNavigator

CustomButtons

LookAndFeel


Methods for TcxCustomNavigatorControl
TcxCustomNavigatorControl Methods

TcxCustomNavigatorControl          Legend

Derived from TcxCustomNavigator

 NavigatorButtonsStateChanged

 RefreshNavigator


TcxCustomNavigatorControl.Buttons

TcxCustomNavigatorControl

Provides access to the buttons collection of a non-db navigator.

property Buttons: TcxNavigatorControlButtons;

Description

Use the Buttons property to access a certain button within the collection.  Buttons of the TcxNavigatorControlButtons class have default actions.  These actions depend on the procedures implemented in the IcxNavigator interface of the managed control.  Without an implementation of this interface, a non-db navigator control cannot perform any actions.  The following table represents the default functionality of each navigator button according to the IcxNavigator interface procedures:

Button Name	Description
First	Calls the IcxNavigatorControl.First procedure.
PriorPage	Calls the IcxNavigatorControl.PriorPage procedure.
Prior	Calls the IcxNavigatorControl.Prior procedure.
Next	Calls the IcxNavigatorControl.Next procedure.
NextPage	Calls the IcxNavigatorControl.NextPage procedure.
Last	Calls the IcxNavigatorControl.Last procedure.
Insert	Calls the IcxNavigatorControl.Insert procedure.
Delete	Calls the IcxNavigatorControl.Delete procedure.
Edit	Calls the IcxNavigatorControl.Edit procedure.
Post	Calls the IcxNavigatorControl.Post procedure.
Cancel	Calls the IcxNavigatorControl.Cancel procedure.
Refresh	Calls the IcxNavigatorControl.Refresh procedure.
SaveBookmark	Calls the IcxNavigatorControl.SaveBookmark procedure.
GotoBookmark	Calls the IcxNavigatorControl.GotoBookmark procedure.
Filter	Calls the IcxNavigatorControl.Filter procedure.

The following example changes the hint of the First navigator button:

//Delphi

cxNavigatorControl1.Buttons.First.Hint := ‘Press this button to jump to the beginning’;

//C++ builder

cxNavigatorControl1->Buttons->First->Hint = "Press this button to jump to the beginning";


TcxCustomNavigatorControl.Control

TcxCustomNavigatorControl          See Also

Specifies the external control managed by the navigator.

property Control: TComponent;

Description

The navigator control can be applied to any external control in order to manage its data.  The TcxCustomNavigatorControl class is used to manage data for controls, so these controls must implement the IcxNavigator interface.

All navigation functionality provided by a control must be implemented using this interface.  A developer must provide actions for each button along with state conditions.  In other words, it is necessary to specify the EOF and BOF conditions and determine when it is possible to insert, edit and delete data.


TcxDBNavigator
 TcxDBNavigator Object

Hierarchy          Properties          Methods         See Also

cxDBNavigator is used to move through the data of external datasets and perform operations on it, such as inserting a blank record, posting a record, etc.

Unit

cxNavigator

TcxDBNavigator = class(TcxCustomDBNavigator);

Description

Use the navigator control to manipulate data-aware controls.  cxDBNavigator lets a user control the dataset when editing or viewing data.  When a user presses one of the navigator buttons, the appropriate action occurs in the dataset to which the navigator is linked.  For instance, if a user clicks the Insert button, a blank record is inserted into the dataset.

Refer to the TcxDBNavigatorButtons topic for the list of the available navigator buttons.

In order to obtain additional information on using the cxDBNavigator, refer to the following demos: EditorsLookupDemo, EditorsMaskDemo, IssueList and MasterDetailCardDemo.


TcxDBNavigator Hierarchy
Hierarchy

TCustomControl

     |

TcxCustomNavigator

     |

TcxCustomDBNavigator

     |


Properties for TcxDBNavigator
TcxDBNavigator Properties

TcxDBNavigator          Legend

Derived from TcxCustomDBNavigator

Buttons

DataSource

Derived from TcxCustomNavigator

CustomButtons

LookAndFeel

Derived from TControl

Align


Methods for TcxDBNavigator
TcxDBNavigator Methods

TcxDBNavigator          Legend

Derived from TcxCustomNavigator

NavigatorButtonsStateChanged

RefreshNavigator


TcxNavigator
 TcxNavigator Object

Hierarchy          Properties          Methods          See Also

The cxNavigator component manages access to data in external controls.

Unit

cxNavigator

TcxNavigator = class(TcxCustomNavigatorControl);

Description

cxNavigator is designed to manage external controls which do not have an assigned dataset.  In contrast to a db navigator, cxNavigator is assigned to a control instead of the data source.  This external control must implement the IcxNavigator interface, which in turn presents methods and properties to manipulate data.  It must also provide the appropriate procedure for each button.

As all the navigator functionality is implemented in the buttons collection, refer to the TcxNavigatorControlButtons class in order to learn more about the list of buttons and their default actions.


TcxNavigator Hierarchy
Hierarchy

TCustomControl

     |

TcxCustomNavigator

     |

TcxCustomNavigatorControl

     |


Properties for TcxNavigator
TcxNavigator Properties

TcxNavigator          Legend

Derived from TcxCustomNavigatorControl

Buttons

Control

Derived from TcxCustomNavigator

CustomButtons

LookAndFeel

Derived from TControl

Align


Methods for TcxNavigator
TcxNavigator Methods

TcxNavigator          Legend

Derived from TcxCustomNavigator

 NavigatorButtonsStateChanged

 RefreshNavigator


TcxCustomNavigatorButtons
TcxCustomNavigatorButtons Object

Hierarchy          Properties          Methods          Events          See Also

This class represents the collection of buttons used in navigator controls.

Unit

cxNavigator

TcxCustomNavigatorButtons = class(TPersistent);

Description

TcxCustomNavigatorButtons is the base class for the buttons collection used in navigator controls.  It can be used as an ancestor for developing user-defined buttons.  Currently this class incorporates 16 buttons:

Button Name	Image	Default Index
First		NBDI_FIRST
PriorPage		NBDI_PRIORPAGE
Prior		NBDI_PRIOR
Next		NBDI_NEXT
NextPage		NBDI_NEXTPAGE
Last		NBDI_LAST
Insert		NBDI_INSERT
Append		NBDI_APPEND
Delete		NBDI_DELETE
Edit		NBDI_EDIT
Post		NBDI_POST
Cancel		NBDI_CANCEL
Refresh		NBDI_REFRESH
SaveBookmark		NBDI_SAVEBOOKMARK
GotoBookmark		NBDI_GOTOBOOKMARK
Filter		NBDI_FILTER

The above table displays default indexes in the collection, and images for each button defined in this class.

All the actions assigned to navigator buttons are implemented in descendants.


TcxCustomNavigatorButtons Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxCustomNavigatorButtons
TcxCustomNavigatorButtons Properties

TcxCustomNavigatorButtons          Legend

In TcxCustomNavigatorButtons

Append

ButtonCount

Buttons

Cancel

ConfirmDelete

Delete

Edit

Filter

First

GotoBookmark

Images

Insert

Last

Next

NextPage

Post

Prior

PriorPage

Refresh

SaveBookmark


Methods for TcxCustomNavigatorButtons
TcxCustomNavigatorButtons Methods

TcxCustomNavigatorButtons          Legend

In TcxCustomNavigatorButtons

 CreateButtons

 DoButtonClick

 GetButtonEnabled

 GetButtonHint

 GetButtonImageOffset

 ReleaseBookmark


Events for TcxCustomNavigatorButtons
TcxCustomNavigatorButtons Events

TcxCustomNavigatorButtons          Legend

In TcxCustomNavigatorButtons

 OnButtonClick


TcxCustomNavigatorButtons.Append

TcxCustomNavigatorButtons          See Also

property Append: TcxNavigatorButton;

Description

This button appends a record and makes it the current one.  This button is always enabled regardless of the state of the other buttons.  However, you can disable it as and when required.

The default index of this button in the collection is NBDI_APPEND.


TcxCustomNavigatorButtons.ButtonCount

TcxCustomNavigatorButtons

Returns the number of buttons in a navigator control.

property ButtonCount: Integer;

Description

For this class this property value is always equal to 16.

ReadOnly Property


TcxCustomNavigatorButtons.Buttons

TcxCustomNavigatorButtons

Specifies the list of navigator buttons.

property Buttons[Index: Integer]: TcxNavigatorButton;

Description

The Buttons property maintains the list of TcxNavigatorButton instances.  It provides indexed access to navigator buttons.  There is an alternative to work with buttons though, instead a user can refer to each button using the appropriate property - TcxCustomNavigatorButtons.First – for instance.

The following sample code creates buttons in the collection and assigns the default index to each of them.

//Delphi

  for I := 0 to NavigatorButtonCount - 1 do

  begin

    FButtons[I] := TcxNavigatorButton.Create(self);

    FButtons[I].DefaultIndex := I;

  end;

//C++ builder

for (int I = 0; I < NavigatorButtonCount; I++){

    FButtons[I] = new TcxNavigatorButton(this);

    FButtons[I]->DefaultIndex = I;

  }

ReadOnly Property


TcxCustomNavigatorButtons.Cancel

TcxCustomNavigatorButtons

property Cancel: TcxNavigatorButton;

Description

This button cancels modifications to the current record, restores the record display to its condition prior to editing, disables the Post button and enables the Edit button.  Cancel is enabled only after editing; otherwise it is disabled.

The default index of this button in the collection is NBDI_CANCEL.


TcxCustomNavigatorButtons.ConfirmDelete

TcxCustomNavigatorButtons

Specifies whether to display the confirmation dialog when pressing the Delete button.

property ConfirmDelete: Boolean;

Description

Deleting a record is an irreversible action.  Set the ConfirmDelete property to True in order to display the confirmation dialog before deleting a record.

The default value of the ConfirmDelete property is True.


TcxCustomNavigatorButtons.Delete

TcxCustomNavigatorButtons          See Also

property Delete: TcxNavigatorButton;

Description

This button deletes the current record and makes the next record the current one.  This button is always enabled regardless of the state of the other buttons.  However, you can disable it as and when required.

The default index of this button in the collection is NBDI_DELETE.


TcxCustomNavigatorButtons.Edit

TcxCustomNavigatorButtons

property Edit: TcxNavigatorButton;

Description

This button switches the dataset into edit state so that the current record can be modified.  It enables the Post and Cancel buttons but becomes disabled once editing has started.  Press Post or Cancel to end editing, thus re-enabling the Edit button.

The default index of this button in the collection is NBDI_EDIT.


TcxCustomNavigatorButtons.GotoBookmark

TcxCustomNavigatorButtons

property GotoBookmark: TcxNavigatorButton;

Description

This button moves the cursor to the previously saved bookmark in the underlying dataset.  It is enabled if a bookmark was previously set via the SaveBookmark button.  You can, however, disable it as and when necessary.

The current bookmark can be removed via the ReleaseBookmark method.

The default index of this button in the collection is NBDI_GOTOBOOKMARK.


TcxCustomNavigatorButtons.Filter

TcxCustomNavigatorButtons

property Filter: TcxNavigatorButton;

Description

This button invokes the Filter Builder dialog in order to create filter expressions.  With TcxCustomDBNavigator, it is possible to customize the filter action using the OnShowFilterDialog event handler and create your own filter dialog.  This button is always enabled regardless of the state of the other buttons.

The default index of this button in the collection is NBDI_FILTER.


TcxCustomNavigatorButtons.First

TcxCustomNavigatorButtons

property First: TcxNavigatorButton;

Description

This button sets the current record to the first record in the dataset, disables the First, Prior, PriorPage buttons and ensures that the Last, Next, NextPage buttons are enabled.

The default index of this button in the collection is NBDI_FIRST.


TcxCustomNavigatorButtons.Images

TcxCustomNavigatorButtons

Lists the images which can appear on the navigator buttons.

property Images: TCustomImageList;

Description

The Images property contains a list of images that can be used instead of the default button images.  Each navigator button’s ImageIndex property determines the specific image displayed. If the Images property is unassigned, default images are displayed on navigator buttons.

In order to use this property, you should:

1)	place an image list on a form;

2)	populate it with appropriate images;

3)	select the required button in the Object Inspector;

4)	assign the list as shown below:

or via code:

//Delphi

DBNavigator1.Buttons.Images := ilMain;

//C++ Builder

DBNavigator1->Buttons->Images = ilMain;


TcxCustomNavigatorButtons.Insert

TcxCustomNavigatorButtons          See Also

property Insert: TcxNavigatorButton;

Description

This button inserts a new record before the current record, enables the Post and Cancel buttons and disables Edit.

The default index of this button in the collection is NBDI_INSERT.


TcxCustomNavigatorButtons.Last

TcxCustomNavigatorButtons

property Last: TcxNavigatorButton;

Description

This button sets the current record to the last record in the dataset, disables the Last, Next, NextPage buttons and ensures that the First, Prior, PriorPage buttons are enabled.

The default index of this button in the collection is NBDI_LAST.


TcxCustomNavigatorButtons.Next

TcxCustomNavigatorButtons

property Next: TcxNavigatorButton;

Description

This button sets the current record to the next record and enables the First and Prior buttons if they are disabled.

The default index of this button in the collection is NBDI_NEXT.


TcxCustomNavigatorButtons.NextPage

TcxCustomNavigatorButtons          See Also

property NextPage: TcxNavigatorButton;

Description

This button scrolls the dataset one page forward relative to the active record.  This button also posts all changes.  If the cursor is moved to the last record, the Last, Next, and NextPage buttons are disabled.

The term "page" means a set of records to move by.  A programmer can specify the number of records via the PageSize property.  For a data-aware navigator, the page size is determined by the number of records in the internal cache.  Most datasets (except for unidirectional ones) maintain an internal cache of records from the underlying database tables.  For instance, if the dataset is used to populate a data-aware grid, the cache includes a record for each visible row in the grid.

For an unbound navigator, the page size must be determined by the IcxNavigatorControl implemented in the external control.

For instance, the page size in the ExpressQuantumGrid is specified by the number of visible records.

The default index of this button in the collection is NBDI_NEXTPAGE.


TcxCustomNavigatorButtons.Post

TcxCustomNavigatorButtons

property Post: TcxNavigatorButton;

Description

This button writes changes made in the current record to the data storage.  By default, this button is disabled and is only enabled when the dataset is switched into edit state, i.e. by using the Edit or Insert buttons.

The default index of this button in the collection is NBDI_POST.


TcxCustomNavigatorButtons.Prior

TcxCustomNavigatorButtons

property Prior: TcxNavigatorButton;

Description

Sets the current record to the previous record and ensures that the Last, Next, and NextPage buttons are enabled.

The default index of this button in the collection is NBDI_PRIOR.


TcxCustomNavigatorButtons.PriorPage

TcxCustomNavigatorButtons          See Also

property PriorPage: TcxNavigatorButton;

Description

This button scrolls the dataset one page backward relative to the active record.  This button also posts all changes.  If the cursor is moved to the first record, the First, Prior, and PriorPage buttons are disabled.

The default index of this button in the collection is NBDI_PRIORPAGE.


TcxCustomNavigatorButtons.Refresh

TcxCustomNavigatorButtons

property Refresh: TcxNavigatorButton;

Description

This button refreshes data in the associated dataset to update the dataset’s view of the data.  Most datasets try to maintain the current record position when refreshing.  However, it is not always possible.  For instance, the current record may have been deleted from the server by another user.

This button is always enabled regardless of the state of the other buttons.

The default index of this button in the collection is NBDI_REFRESH.


TcxCustomNavigatorButtons.ReleaseBookmark

TcxCustomNavigatorButtons          See Also

When implemented, removes the current bookmark in the dataset.

procedure ReleaseBookmark; virtual;

Description

By default, this method does nothing.

Use the SaveBookmark and GotoBookmark methods to specify a bookmark and navigate to this bookmark in the dataset.


TcxCustomNavigatorButtons.SaveBookmark

TcxCustomNavigatorButtons

property SaveBookmark: TcxNavigatorButton;

Description

This button specifies the current bookmark in the dataset.  A bookmark marks a location in the dataset so that an application can easily return to that location.  Only one bookmark can be set using a navigator control.

This button is always enabled regardless of the state of other buttons.  However, you can disable it as and when required.

The current bookmark can be removed via the ReleaseBookmark method.

The default index of this button in the collection is NBDI_SAVEBOOKMARK.


TcxCustomNavigatorButtons.CreateButtons

TcxCustomNavigatorButtons

Creates a collection of buttons for a navigator control.

procedure CreateButtons; virtual;

Description

The CreateButtons method is used to create navigator buttons.  All buttons are created one by one with default indexes assigned.  The buttons collection can be accessed via the Buttons property.  After buttons are created, a user can specify their settings: hint, image and visibility.  This method can be overridden in descendants in order to create user-defined buttons.  For instance, it is possible to create a subset of buttons with predefined property values.  The following sample code creates a collection of disabled buttons:

//Delphi

procedure CreateButtons;

var

  I: Integer;

  FButtons: TcxCustomNavigatorButtons;

begin

  for I := 0 to NavigatorButtonCount - 1 do

  begin

    FButtons[I] := TcxNavigatorButton.Create(Self);

    FButtons[I].DefaultIndex := I;

    FButtons[I].Enabled := False;

  end;

end;

//C++ builder

void CreateButtons() {

  int I;

  TcxCustomNavigatorButtons *FButtons;

for (I = 0; I < NavigatorButtonCount; I++){

    FButtons[I] = new TcxNavigatorButton(this);

    FButtons[I]->DefaultIndex = I;

    FButtons[I]->Enabled = false;

  }

}


TcxCustomNavigatorButtons.DoButtonClick

TcxCustomNavigatorButtons          See Also

Implements the functionality associated with a navigator button.

procedure DoButtonClick(ADefaultIndex: Integer); virtual;

Description

The DoButtonClick method is used to determine the actions to be performed when a navigator button is clicked.  The ADefaultIndex parameter specifies the clicked button index within the collection of navigator buttons.  According to this index, the appropriate action should be executed.  As the TcxCustomNavigatorButtons class is merely a base class, its DoButtonClick method does not provide any actions.  For the detailed information refer to the method descriptions in the descendants: TcxDBNavigatorButtons and TcxNavigatorControlButtons.


TcxCustomNavigatorButtons.GetButtonEnabled

TcxCustomNavigatorButtons          See Also

Specifies the conditions for enabling or disabling navigator buttons.

function GetButtonEnabled(ADefaultIndex: Integer): Boolean; virtual;

Description

The Navigator is always connected to a data source (bound or unbound).  Its buttons should reflect the current state of the cursor within the data source.  For instance, if a cursor reaches the first record, the First, Prior, and PriorPage buttons must be disabled as a user cannot use them.  Such a condition must be set in the GetButtonEnabled method.  As conditions must be set for all buttons, the ADefaultIndex parameter specifies the button index within the collection of navigator buttons.  The TcxCustomNavigatorButtons class represents the base class and its GetButtonEnabled method always returns True.  For the detailed information refer to the method descriptions in the descendants: TcxDBNavigatorButtons and TcxNavigatorControlButtons.


TcxCustomNavigatorButtons.GetButtonHint

TcxCustomNavigatorButtons

Sets default hints for all navigator buttons.

function GetButtonHint(ADefaultIndex: Integer): string; virtual;

Description

The GetButtonHint method associates each button with an appropriate resource string containing hint information.  For more information on working with them, refer to resource strings.

Use this method to redefine hints according to button indexes.  You also may change hints one by one accessing the Hint property of each button.


TcxCustomNavigatorButtons.GetButtonImageOffset

TcxCustomNavigatorButtons

Sets the offset for images displayed on navigator buttons.

function GetButtonImageOffset: Integer; virtual;

Description

The GetButtonImageOffset method of the TcxCustomNavigatorButtons class always returns 2.  This method can be overridden by descendants to specify a different value.  The specified offset is used by internal methods to determine the minimum bounds when resizing the control.


TcxCustomNavigatorButtons.OnButtonClick

TcxCustomNavigatorButtons

Enables you to process navigator button clicks manually.

type

  TcxNavigatorButtonClickEvent = procedure(Sender: TObject; AButtonIndex: Integer; var ADone: Boolean) of object;

property OnButtonClick: TcxNavigatorButtonClickEvent;

Description

Handle the OnButtonClick event if you need to implement custom behavior for navigator buttons.  This event’s Sender parameter represents the navigator buttons collection whose button has been clicked (a TcxCustomNavigatorButtons descendant).  The AButtonIndex parameter identifies the clicked button.  This parameter value matches the clicked button’s DefaultIndex property value.

The ADone parameter specifies whether the navigator should perform default actions in response to a button click.  If you have implemented all the required actions in the OnButtonClick event handler and default processing is not required, set the ADone parameter to True.  In this case, the default actions are not invoked.  If the parameter value, which is initially False, is not changed, the control will perform default actions after the event handler has been executed.


TcxNavigatorButton
TcxNavigatorButton Object

Hierarchy          Properties          Methods          Events          See Also

This class is used to manage buttons within the data-aware and non-db navigator controls.

Unit

cxNavigator

TcxNavigatorButton = class(TPersistent);

Description

The Express Navigator controls provide the ability to customize each button.  You can access buttons via the Buttons property of the appropriate class using the default index or the properties of the TcxDBNavigatorButtons and TcxNavigatorControlButtons classes.

The following code strings are interchangeable and each hides the PriorPage button (which has the default index of NBDI_PRIORPAGE):

//Delphi

DBNavigator1.Buttons[NBDI_PRIORPAGE].Visible := False;

DBNavigator1.Buttons.PriorPage.Visible := False;

//C++ builder

DBNavigator1->Buttons[NBDI_PRIORPAGE]->Visible = False;

DBNavigator1->Buttons->PriorPage->Visible = False;

The TcxNavigatorButton class provides attributes which allow you to customize buttons.  You can disable buttons via the Enabled property.  Set the Visible property to False to completely exclude a button from a navigator control.  Navigator controls provide button hints defined in resource strings.  Use the Hint property to substitute the resource string value by your own string.


TcxNavigatorButton Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxNavigatorButton
TcxNavigatorButton Properties

TcxNavigatorButton          Legend

In TcxNavigatorButton

DefaultIndex

Enabled

Hint

ImageIndex

Visible


Methods for TcxNavigatorButton
TcxNavigatorButton Methods

TcxNavigatorButton          Legend

In TcxNavigatorButton

 DoClick


Events for TcxNavigatorButton
TcxNavigatorButton Events

TcxNavigatorButton          Legend

In TcxNavigatorButton

 OnClick


TcxNavigatorButton.DefaultIndex

TcxNavigatorButton

Determines the index of a certain button in the buttons collection.

property DefaultIndex: Integer;

Description

All navigator control buttons are placed into the collection with a zero-based index.  The default index for each button is specified in the global constant.  When the buttons collection is created (CreateButtons), this index is associated with each button.  This property value is used to access each button via the Buttons property of the appropriate class.


TcxNavigatorButton.Enabled

TcxNavigatorButton

Specifies whether a button can be clicked.

property Enabled: Boolean;

Description

Though the button state is determined automatically according to the dataset status, a user may disable or enable buttons according to his/her own needs.  For instance, when the first record in the dataset is active, the Prior button is disabled (regardless of the Enabled property value).  When the cursor is moved to another record, this button is enabled.  If you set the Enabled property to False, this button will never be enabled.

When a button is disabled, it is not highlighted and cannot be clicked in order to perform the default action.

The default value of the Enabled property is True.


TcxNavigatorButton.Hint

TcxNavigatorButton

Specifies the text string that can appear when a user moves the mouse pointer over a navigator button.

property Hint: string;

Description

Set the Hint property to a string providing more information about the meaning of a particular button.  The hint text appears in the Help Hint window when a user pauses with the mouse pointer over the button.  This property overrides the default hint strings presented in the following table:

Button Name	Description
First	First record
PriorPage	Prior page
Prior	Prior record
Next	Next record
NextPage	Next page
Last	Last record
Insert	Insert record
Append	Append record
Delete	Delete record
Edit	Edit record
Post	Post edit
Cancel	Cancel edit
Refresh	Refresh data
SaveBookmark	Save Bookmark
GotoBookmark	Goto Bookmark
Filter	Filter data

The following code is used to change the default hint of the PriorPage button with - "Use this button to jump to the previous page":

//Delphi

DBNavigator1.Buttons[NBDI_PRIORPAGE].Hint := 'Use this button to jump to the previous page';

//C++ Builder

DBNavigator1->Buttons[NBDI_PRIORPAGE]->Hint = "Use this button to jump to the previous page";


TcxNavigatorButton.ImageIndex

TcxNavigatorButton          See Also

Determines which image is displayed as the icon for a navigator button.

property ImageIndex: TImageIndex;

Description

Use the ImageIndex property to designate an image that should be displayed on the navigator button.  The image is specified by its index within the source images collection.  The source of the images is assigned via the Images property.

In order to use this property, you should:

1)	place an image list on a form;

2)	populate it with appropriate images;

3)	select the required button in the Object Inspector;

4)	assign the list as shown below:

Now you can assign images from this list to navigator buttons.

You also may use default navigator images – see TcxCustomNavigatorButtons.

If the ImageIndex property is set to –1, the default image is displayed.

The default value of the ImageIndex property is –1.


TcxNavigatorButton.Visible

TcxNavigatorButton

Specifies whether the button can be displayed.

property Visible: Boolean;

Description

Use the Visible property to control a button’s visibility.  Set this property value to False to hide the button.  In this case, the navigator button is completely excluded from the control instead of just being disabled.  For instance, if you do not want to provide the end-user with filtering capability, you can just hide the Filter button.

The default value of the Visible property is True.


TcxNavigatorButton.DoClick

TcxNavigatorButton          See Also

Generates the OnClick event.

procedure DoClick; dynamic;

Description

The DoClick method is called after a navigator button has been clicked.  It invokes the command associated with the selected button via the appropriate methods: TcxDBNavigatorButtons.DoButtonClick or TcxNavigatorControlButtons.DoButtonClick.  You should use their descendants to change the default button action.  You may also change the button action directly in this control via the OnClick event handler.


TcxNavigatorButton.OnClick

TcxNavigatorButton          See Also

Occurs when a user clicks a certain button with the mouse.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnClick: TNotifyEvent;

Description

Use the OnClick event handler to write code that responds to the click event.  Navigator buttons already have default actions that occur when they are clicked, so it is not usually necessary to write an OnClick event handler.


TcxNavigatorControlButtons
TcxNavigatorControlButtons Object

Hierarchy          Properties          Methods          Events          See Also

This class represents the collection of buttons used in non-db navigator controls.

Unit

cxNavigator

TcxNavigatorControlButtons = class(TcxCustomNavigatorButtons);

Description

The TcxNavigatorControlButtons class provides the collection of buttons for a non-db navigator control.  In contrast to db-oriented buttons, TcxNavigatorControlButtons works directly with a control and this needs to implement the IcxNavigator interface.  Procedures of this interface provide all the necessary default actions.  The following table displays the default index in the collection, and describes functionality provided by each button.

Button Name	Default Index	Description
First	NBDI_FIRST	Moves the cursor to the first record.
PriorPage	NBDI_PRIORPAGE	Moves the cursor to the previous page.
Prior	NBDI_PRIOR	Moves the cursor to the previous record.
Next	NBDI_NEXT	Moves the cursor to the next record.
NextPage	NBDI_NEXTPAGE	Moves the cursor to the next page.
Last	NBDI_LAST	Moves the cursor to the last record.
Insert	NBDI_INSERT	Inserts a new record.
Append	NBDI_APPEND	Appends a new record.
Delete	NBDI_DELETE	Deletes the current record.
Edit	NBDI_EDIT	Sets the dataset to the edit state.
Post	NBDI_POST	Writes the modified record.
Cancel	NBDI_CANCEL	Cancels modifications to the active record.
Refresh	NBDI_REFRESH	Updates the data view in the appropriate control.
SaveBookmark	NBDI_SAVEBOOKMARK	Saves a certain bookmark.
GotoBookmark	NBDI_GOTOBOOKMARK	Moves the cursor to the previously saved bookmark.
Filter	NBDI_FILTER	Invokes the Filter Dialog.

You can modify behavior of buttons, as required, by overriding the DoButtonClick method.  In order to change the conditions controlling enabling/disabling buttons, you should override the GetButtonEnabled method.

For more information on how to customize buttons’ look and feel see TcxNavigatorButton.


TcxNavigatorControlButtons Hierarchy
Hierarchy

TPersistent

     |

TcxCustomNavigatorButtons

     |


Properties for TcxNavigatorControlButtons
TcxNavigatorControlButtons Properties

TcxNavigatorControlButtons          Legend

Derived from TcxCustomNavigatorButtons

Append

ButtonCount

Buttons

Cancel

ConfirmDelete

Delete

Edit

Filter

First

GotoBookmark

Images

Insert

Last

Next

NextPage

Post

Prior

PriorPage

Refresh

SaveBookmark


Methods for TcxNavigatorControlButtons
TcxNavigatorControlButtons Methods

TcxNavigatorControlButtons          Legend

In TcxNavigatorControlButtons

 DoButtonClick

 GetButtonEnabled

 ReleaseBookmark

Derived from TcxCustomNavigatorButtons

 CreateButtons

 DoButtonClick

 GetButtonEnabled

 GetButtonHint

 GetButtonImageOffset

 ReleaseBookmark


Events for TcxNavigatorControlButtons
TcxNavigatorControlButtons Events

TcxNavigatorControlButtons          Legend

Derived from TcxCustomNavigatorButtons

OnButtonClick


TcxNavigatorControlButtons.DoButtonClick

TcxNavigatorControlButtons          See Also

Implements the appropriate functionality for each non-db navigator button.

procedure DoButtonClick(ADefaultIndex: Integer); override;

Description

The DoButtonClick method overrides the method of the TcxCustomNavigatorButtons class and provides default actions for non-db navigator buttons.  The ADefaultIndex parameter specifies the clicked button whose functionality is defined by this method.

In contrast to db navigator buttons, this method associates buttons with the IcxNavigator interface procedures. Thus, all default actions must be implemented by the developer.


TcxNavigatorControlButtons.GetButtonEnabled

TcxNavigatorControlButtons          See Also

Sets the button state according to the associated control’s status.

function GetButtonEnabled(ADefaultIndex: Integer): Boolean; override;

Description

The GetButtonEnabled method provides the condition defining whether a navigator button is enabled.

First, Prior, and PriorPage buttons are enabled when the IsBof property of the IcxNavigator interface is False.  For instance, when a user moved the focus to the second record within the ExpressQuantumGrid data view.

Last, Next, and NextPage buttons are enabled when the IsEof property of the IcxNavigator interface is False.  For instance, when any record except for the last one is focused within the ExpressQuantumGrid data view.

The Insert button is enabled when the CanInsert property of the IcxNavigator interface is True.

The Delete button is enabled when the CanDelete property of the IcxNavigator interface is True and the dataset is not empty.

The Edit button is enabled when the CanEdit property of the IcxNavigator interface is True and the dataset not in edit mode.

The Post and Cancel buttons are enabled when the CanEdit and IsEditing properties of the IcxNavigator interface are True.

The GotoBookmark button is enabled when there is a previously saved bookmark.

The ADefaultIndex parameter specifies the button whose status is checked.


TcxNavigatorControlButtons.ReleaseBookmark

TcxCustomNavigatorButtons          See Also

Removes the current bookmark in the dataset.

procedure ReleaseBookmark; override;

Description

By default, this method calls the data navigator control’s ClearBookmark method.


TcxDBNavigatorButtons
TcxDBNavigatorButtons Object

Hierarchy          Properties          Methods          Events          See Also

This class represents the collection of buttons used in db navigator controls.

Unit

cxNavigator

TcxDBNavigatorButtons = class(TcxCustomNavigatorButtons);

Description

The TcxDBNavigatorButtons class provides a collection of buttons for the database navigator control.  In contrast to non-db buttons, the TcxDBNavigatorButtons class works with the dataset.  This class provides the default action functionality for processing dataset records.  The following table displays the default index in the collection, and describes functionality provided by each button.

Button Name	Default Index	Description
First	NBDI_FIRST	Moves the cursor to the first dataset record.
PriorPage	NBDI_PRIORPAGE	Moves the cursor to the previous dataset page.
Prior	NBDI_PRIOR	Moves the cursor to the previous dataset record.
Next	NBDI_NEXT	Moves the cursor to the next dataset record.
NextPage	NBDI_NEXTPAGE	Moves the cursor to the next dataset page.
Last	NBDI_LAST	Moves the cursor to the last dataset record.
Insert	NBDI_INSERT	Inserts a new record into the connected dataset.
Append	NBDI_APPEND	Appends a new record into the connected dataset.
Delete	NBDI_DELETE	Deletes the current record from the connected dataset.
Edit	NBDI_EDIT	Sets the connected dataset into edit state.
Post	NBDI_POST	Saves the modified record to the connected dataset.
Cancel	NBDI_CANCEL	Cancels all the unsaved modifications to the current record of the connected dataset.
Refresh	NBDI_REFRESH	Fetches data from the dataset to update the data view in the appropriate control.
SaveBookmark	NBDI_SAVEBOOKMARK	Saves a bookmark for the connected dataset.
GotoBookmark	NBDI_GOTOBOOKMARK	Moves the cursor to the previously saved bookmark in the connected dataset.
Filter	NBDI_FILTER	Invokes the Filter Dialog for the managed dataset.

You can modify behavior of the buttons as required by overriding the DoButtonClick method.  In order to change the conditions controlling the enable/disable status of one or more buttons, you should override the GetButtonEnabled method.

For more information on how to customize buttons’ look and feel see TcxNavigatorButton.


TcxDBNavigatorButtons Hierarchy
Hierarchy

TPersistent

     |

TcxCustomNavigatorButtons

     |


Properties for TcxDBNavigatorButtons
TcxDBNavigatorButtons Properties

TcxDBNavigatorButtons          Legend

In TcxDBNavigatorButtons

PageSize

Derived from TcxCustomNavigatorButtons

Append

ButtonCount

Buttons

Cancel

ConfirmDelete

Delete

Edit

Filter

First

Images

Insert

Last

Next

NextPage

Post

Prior

PriorPage

Refresh


Methods for TcxDBNavigatorButtons
TcxDBNavigatorButtons Methods

TcxDBNavigatorButtons          Legend

In TcxDBNavigatorButtons

 DoButtonClick

 GetButtonEnabled

 ReleaseBookmark

Derived from TcxCustomNavigatorButtons

 CreateButtons

 DoButtonClick

 GetButtonEnabled

 GetButtonHint

 GetButtonImageOffset

 ReleaseBookmark


Events for TcxDBNavigatorButtons
TcxNavigatorControlButtons Events

TcxNavigatorControlButtons          Legend

Derived from TcxCustomNavigatorButtons

OnButtonClick


TcxDBNavigatorButtons.PageSize

TcxDBNavigatorButtons          See Also

Sets the number of records to be represented on one "page".

property PageSize: Integer;

Description

NextPage and PriorPage navigator buttons are used to move a data source cursor by a set of records forward or backward.  This set is called a "page" in terms of the Navigator control.

Use the PageSize property to specify the number of records in this set.

If you do not specify a number of records using this property (the default value is set to 0), the page size is determined automatically.

All datasets use a number of records in an internal cache set via the BufferCount property as the page size.  If the dataset is used to populate a data-aware grid, the cache includes a record for each visible row in the grid.

For instance, the page size in ExpressQuantumGrid is specified by the number of visible records.

For a non-db navigator, the page size is determined by IcxNavigatorControl implemented by the external control.

The default value of the PageSize property is 0.


TcxDBNavigatorButtons.DoButtonClick

TcxDBNavigatorButtons          See Also

Implements the appropriate functionality for each database navigator button.

procedure DoButtonClick(ADefaultIndex: Integer); override;

Description

The DoButtonClick method overrides the method of the TcxCustomNavigatorButtons class and provides default actions for db navigator buttons.  The ADefaultIndex parameter specifies the clicked button whose functionality is defined by this method.

In contrast to non-db navigator buttons whose actions are implemented via the IcxNavigatorControl interface procedures, TcxDBNavigatorButtons provides default actions for each button.  The following table describes the action for each button in terms of the controlled dataset.

Button Name	Default Action
First	Moves to the first record in the dataset: • posts any changes to the active record • fetches the first record and makes it active • sets the dataset’s Bof property to True
PriorPage	Posts any changes to the active record and moves the active record backward by the number of records specified by the PageSize property.
Prior	Moves to the previous record in the dataset: • posts any changes to the active record • sets the dataset’s Bof and Eof properties to False • fetches the previous record and makes it active • sets the Bof property to True if the first record in the dataset has already been active
Next	Moves to the next record in the dataset: • posts any changes to the active record • sets the dataset’s Bof and Eof properties to False • fetches the next record and makes it active • sets the Eof property to True if the last record in the dataset has already been active
NextPage	Posts any changes to the active record and moves the active record forward by the number of records specified by the PageSize property.
Last	Moves to the last record in the dataset: • posts any changes to the active record • fetches the last record and makes it active • sets the dataset’s Eof property to True
Insert	Posts any changes to the active record and inserts a new, empty record into the dataset.  The newly inserted record is posted according to the dataset type.
Append	Posts any changes to the active record and inserts a new, empty record into the dataset.  The newly inserted record is posted according to the dataset type.
Delete	Deletes the active record and positions the dataset on the next record.  If the deleted record was the last record in the dataset, the previous one becomes the current record.
Edit	Enables editing of data in the dataset.  Retrieves the record, sets the dataset into edit state, and broadcasts the state change to associated controls.
Post	Writes the edited record to the data storage or to the internal change log depending on the dataset type.  Sets the dataset state to browse state.
Cancel	Cancels all the unsaved modifications to the current record if those changes have not been posted yet.  If the dataset is not in edit state, Cancel does nothing.
Refresh	Fetches latest data from the database to update the dataset’s view of data.  Used to ensure that an application has the latest data from the database.  Most datasets try to maintain the current record position when refreshing. However, it is not always possible. For example, the current record may have been deleted from the server by another user. Unidirectional datasets have no mechanism to locate the current record after refreshing and always move back to the first record.
SaveBookmark	Allocates a bookmark for the active record in the dataset.  Establishing a bookmark for a record enables the dataset to return to that record.
GotoBookmark	Position the dataset on a bookmarked record.
Filter	Displays the Filter Building Dialog implemented via the TcxDBFilterControl class.  For more information on how to use this feature see Runtime Filtering topic.


TcxDBNavigatorButtons.GetButtonEnabled

TcxDBNavigatorButtons           See Also

Gets the button state according to the dataset status.

function GetButtonEnabled(ADefaultIndex: Integer): Boolean; override;

Description

The GetButtonEnabled method defines the conditions when a navigator button is enabled.

All buttons are disabled if the database navigator is not connected to a dataset.

The First, Prior, and PriorPage buttons are enabled when the dataset’s Bof property is False.

The Last, Next, and NextPage buttons are enabled when the dataset’s Eof property is False.

The Insert button is enabled when the dataset’s CanModify property is True.

The Delete button is enabled when the dataset’s CanModify property is True and dataset contains at least one record.

The Edit button is enabled when the dataset’s CanModify property is True and the dataset is not in edit mode.

The Post and Cancel buttons are enabled when the CanModify property is True and the dataset is in edit mode.

The GotoBookmark button is enabled when there is a previously saved bookmark.

The Refresh button is enabled when the dataset’s CanModify property is True.

The ADefaultIndex parameter specifies the button whose status is checked.


TcxDBNavigatorButtons.ReleaseBookmark

TcxCustomNavigatorButtons          See Also

Removes the current bookmark in the dataset.

procedure ReleaseBookmark; override;

Description

By default, this method removes the current bookmark and frees any resources allocated for this bookmark by calling the dataset’s FreeBookmark method.


IcxNavigator
IcxNavigator Interface

Hierarchy          Methods

Implementing this interface allows controls to have their navigation managed by a TcxNavigator.

Unit

cxNavigator

IcxNavigator = interface(IUnknown)

Description

The TcxNavigator control displays a set of buttons that have no predefined functionality.  This allows a developer to use it with any other control.  For instance, you can implement navigation in a runtime created dataset.  Another example can be using the navigator to move through pages of a tab control or modify the edit value of a date edit.  This is possible by having actions performed by navigator buttons implemented by the target control.  This is done by the target control implementing the IcxNavigator interface that declares methods that must implement the navigator’s functionality.

The navigator can be bound to a specific control by initializing its Control property value.  This property can be set to any object that implements the IcxNavigator interface.

The methods declared by the IcxNavigator interface can be divided into three categories.

The first includes methods that are called when a navigator control becomes bound to the control and when a navigator is disconnected.  This is required since you need to notify the bound navigator controls of changes within the target control.  For instance, if the selected tab of a tab control changes, the tab control must notify all bound navigator controls of the fact.

The navigator control must be able to query the target control to see whether specific actions can be currently performed.  For instance, the navigator control must decide whether forward navigation can be performed, and if not the Next button becomes disabled.  The updating of navigator controls is performed by means of the second group of methods which must be implemented to return Boolean values that indicate whether a particular action can be currently performed.

The last group of methods that is declared by the IcxNavigator must implement the functionality of the buttons.  There is a method for each type of button.


IcxNavigator Hierarchy
Hierarchy

IUnknown

     |


Methods for IcxNavigator
IcxNavigator Methods

IcxNavigator          Legend

In IcxNavigator

 AddNavigator

 Cancel

 CanDelete

 CanEdit

 CanInsert

 ClearBookmark

 Delete

 Edit

 Filter

 First

 GotoBookmark

 Insert

 IsBof

 IsBookmarkAvailable

 IsEditing

 IsEof

 Last

 Next

 NextPage

 Post

 Prior

 PriorPage

 Refresh

 RemoveNavigator

 SaveBookmark


IcxNavigator.AddNavigator

IcxNavigator          See Also

This interface on a control is called when a Navigator is told to manage navigation of that control.

procedure AddNavigator(ANavigator: IcxNavigatorOwner);

Description

The Navigator can be bound to any controls that implement the IcxNavigator interface by assigning the target control to the navigator’s Control property.  When this is performed, the AddNavigator method of the target control is called.

Implement the AddNavigator method to perform specific actions when binding a navigator to a control.  The ANavigator parameter specifies the navigator control whose Control property value is being initialized.  Most commonly, you will need to store a reference to the navigator.  This must be performed to have the ability to refresh the navigator when needed.  Otherwise, you will have no information which navigator is to be updated.

Additionally, you may perform navigator initialization in the AddNavigator method.  For instance, you may need to hide some of the navigator buttons when it is bound to a specific control.  In which case, you are most likely to show them again when the navigator becomes unbound.  The RemoveNavigator method enables you to perform this kind off cleanup.


IcxNavigator.Cancel

IcxNavigator          See Also

This interface on a control is called when the linked navigator's Cancel button is pressed.

procedure Cancel;

Description

Navigator controls call the Cancel method of their bound controls in response to clicking the Cancel button.  Implement this method to provide the appropriate response to clicking the button.

Please refer to the ‘Responding to Navigator Button Clicks’ document for details.


IcxNavigator.CanDelete

IcxNavigator          See Also

Returns whether the Delete button should be enabled.

function CanDelete: Boolean;

Description

When the navigator control updates the state of its buttons (its NavigatorButtonsStateChanged method is called), the navigator calls a number of methods that specify whether a particular button must be enabled or disabled.  The CanDelete method is called among them.  Implement it to specify whether the current state of the control should allow deletion (whether the Delete button should be enabled).  To enable the button for the current state, return True.  Otherwise, it will be disabled.


IcxNavigator.CanEdit

IcxNavigator          See Also

Returns whether editing can be performed.

function CanEdit: Boolean;

Description

When navigating the target control, the navigator needs to be refreshed.  This is performed by calling the navigator’s NavigatorButtonsStateChanged method.  The method call results in checking the validity of all button states.  The number of methods is called to determine whether buttons need to be enabled or disabled for the current item.

The CanEdit method is used in combination with the IsEditing method.  If both methods return True (which implies that editing is being performed), the Edit button becomes disabled while the Post and Cancel buttons are enabled.  If the CanEdit returns True but the IsEditing method returns False, the Post and Cancel buttons become disabled and the Edit button is enabled.  If the CanEdit method returns False, all the three mentioned buttons are disabled.


IcxNavigator.CanInsert

IcxNavigator          See Also

Returns whether the Insert button should be enabled.

function CanInsert: Boolean;

Description

Each time the state of navigation of the control is changed, the NavigatorButtonsStateChanged method of the navigator must be called.  This method checks the enabled state of all buttons.  For this purpose, it calls several methods of the IcxNavigator interface implemented by the bound control.  One of them is the CanInsert method, whose return value specifies whether the Insert button should be enabled.  To enable the button for the current item, return True.  If False is returned, the button will be disabled.


IcxNavigator.ClearBookmark

IcxNavigator

Clears a saved bookmark when it becomes invalid.

procedure ClearBookmark;

Description

The implementation of this method isn’t required for non-db navigators.


IcxNavigator.Delete

IcxNavigator          See Also

This interface on a control is called when the linked navigator's Delete button is pressed.

procedure Delete;

Description

Navigator controls call the Delete method of their bound controls in response to clicking the Delete button.  Implement this method to provide the appropriate response to clicking the button.

Please refer to the Responding to Navigator Button Clicks topic for details.


IcxNavigator.Edit

IcxNavigator          See Also

This interface on a control is called when the linked navigator's Edit button is pressed.

procedure Edit;

Description

Navigator controls call the Edit method of their bound controls in response to clicking the Edit button.  Implement this method to provide the appropriate response to clicking the button.

Please refer to the Responding to Navigator Button Clicks topic for details.


IcxNavigator.Filter

IcxNavigator          See Also

This interface on a control is called when the linked navigator's Filter button is pressed.

procedure Filter;

Description

Navigator controls call the Filter method of their bound controls in response to clicking the Filter button.  Implement this method to provide the appropriate response to clicking the button.

Please refer to the Responding to Navigator Button Clicks topic for details.


IcxNavigator.First

IcxNavigator          See Also

This interface on a control is called when the linked navigator's First button is pressed.

procedure First;

Description

Navigator controls call the First method of their bound controls in response to clicking the First button.  Implement this method to provide the appropriate response to clicking the button.

Please refer to the Responding to Navigator Button Clicks topic for details.


IcxNavigator.GotoBookmark

IcxNavigator          See Also

This interface on a control is called when the linked navigator's GotoBookmark button is pressed.

procedure GotoBookmark;

Description

Navigator controls call the GotoBookmark method of their bound controls in response to clicking the GotoBookmark button.  Implement this method to provide the appropriate response to clicking the button.

Please refer to the Responding to Navigator Button Clicks topic for details.


IcxNavigator.Insert

IcxNavigator          See Also

This interface on a control is called when the linked navigator's Insert button is pressed.

procedure Insert;

Description

Navigator controls call the Insert method of their bound controls in response to clicking the Insert button.  Implement this method to provide the appropriate response to clicking the button.

Please refer to the Responding to Navigator Button Clicks topic for details.


IcxNavigator.IsBof

IcxNavigator          See Also

Returns whether the control is at the beginning of its navigable range.

function IsBof: Boolean;

Description

The Prior, PriorPage and First buttons are intended to navigate backwards through items of the bound control.  Each time the currently selected item changes, the control must call the navigator’s NavigatorButtonsStateChanged method that updates the navigator.  This method checks the state of all navigator buttons by calling several methods.  The IsBof method is called among them.  If this method returns True, the Prior, PriorPage and First buttons become disabled.  Otherwise, they are enabled.

When the last item of the control is achieved, the Next, NextPage and Last navigator buttons must become disabled.  Implement the IsEof method to provide such logic.


IcxNavigator.IsBookmarkAvailable

IcxNavigator          See Also

Returns whether the control is able to bookmark or save its position within its navigable range.

function IsBookmarkAvailable: Boolean;

Description

Navigator controls provide the SaveBookmark and GotoBookmark buttons that are intended to save the bookmark for the current item of the bound control and to navigate to that item respectively.  To provide such functionality, you need to implement the SaveBookmark and GotoBookmark methods.

The GotoBookmark button must be enabled only when there is a bookmark stored.  This must be determined by the IsBookmarkAvailable method.  If the method returns True, the GotoBookmark button is enabled.  Otherwise, it is disabled.


IcxNavigator.IsEditing

IcxNavigator          See Also

Returns whether the control is currently being Edited.

function IsEditing: Boolean;

Description

There are three buttons displayed by navigator controls that affect editing.  These are the Edit, Post and Cancel buttons.  The enabled state of these buttons is controlled by the IsEditing and CanEdit methods.  If both methods return True, the Edit button is disabled but the Post and Cancel buttons are enabled.  If the IsEditing method returns False while CanEdit returns True, the Edit button is enabled while other mentioned buttons are disabled.  All the three buttons are disabled when both methods return False.

Note that button state is updated when the NavigatorButtonsStateChanged method of the navigator is called.  This method must be called by the control each time its navigation state (moving to a new position in its navigable range) changes.


IcxNavigator.IsEof

IcxNavigator          See Also

Returns whether the control is at the end of its navigable range.

function IsEof: Boolean;

Description

Forward navigation of the control is performed by clicking the Next, NextPage and Last buttons of the navigator.  When the control has reached the end of its navigable range, these buttons are supposed to become disabled.  Implement the IsEof event to determine whether the currently selected item is the last.  If this method returns True, the mentioned buttons become disabled.  Otherwise, they are enabled.

Implement the IsBof method to control the state of the Prior, PriorPage and First buttons.


IcxNavigator.Last

IcxNavigator          See Also

This interface on a control is called when the linked navigator's Last button is pressed.

procedure Last;

Description

Navigator controls call the Last method of their bound controls in response to clicking the Last button.  Implement this method to provide the appropriate response to clicking the button.

Please refer to the Responding to Navigator Button Clicks topic for details.


IcxNavigator.Next

IcxNavigator          See Also

This interface on a control is called when the linked navigator's Next button is pressed.

procedure Next;

Description

Navigator controls call the Next method of their bound controls in response to clicking the Next button.  Implement this method to provide the appropriate response to clicking the button.

Please refer to the Responding to Navigator Button Clicks topic for details.


IcxNavigator.NextPage

IcxNavigator          See Also

This interface on a control is called when the linked navigator's NextPage button is pressed.

procedure NextPage;

Description

Navigator controls call the NextPage method of their bound controls in response to clicking the NextPage button.  Implement this method to provide the appropriate response to clicking the button.

Please refer to the Responding to Navigator Button Clicks topic for details.


IcxNavigator.Post

IcxNavigator          See Also

This interface on a control is called when the linked navigator's Post button is pressed.

procedure Post;

Description

Navigator controls call the Post method of their bound controls in response to clicking the Post button.  Implement this method to provide the appropriate response to clicking the button.

Please refer to the Responding to Navigator Button Clicks topic for details.


IcxNavigator.Prior

IcxNavigator          See Also

This interface on a control is called when the linked navigator's Prior button is pressed.

procedure Prior;

Description

Navigator controls call the Prior method of their bound controls in response to clicking the Prior button.  Implement this method to provide the appropriate response to clicking the button.

Please refer to the Responding to Navigator Button Clicks topic for details.


IcxNavigator.PriorPage

IcxNavigator          See Also

This interface on a control is called when the linked navigator's PriorPage button is pressed.

procedure PriorPage;

Description

Navigator controls call the PriorPage method of their bound controls in response to clicking the PriorPage button.  Implement this method to provide the appropriate response to clicking the button.

Please refer to the Responding to Navigator Button Clicks topic for details.


IcxNavigator.Refresh

IcxNavigator          See Also

This interface on a control is called when the linked navigator's Refresh button is pressed.

procedure Refresh;

Description

Navigator controls call the Refresh method of their bound controls in response to clicking the Refresh button.  Implement this method to provide the appropriate response to clicking the button.

Please refer to the Responding to Navigator Button Clicks topic for details.


IcxNavigator.RemoveNavigator

IcxNavigator          See Also

Must be implemented to respond to unlinking a navigator from the control.

procedure RemoveNavigator(ANavigator: IcxNavigatorOwner);

Description

When assigning a control to the Control property of the navigator, the AddNavigator method of the control is called.  This method can be used for several purposes.  One of them is to customize the buttons of the navigator when it is bound to specific control.  For instance, you may want to hide specific buttons if they are not needed for this control type.

The RemoveNavigator method must be implemented to undo any changes made to the navigator in the AddNavigator method.  For instance, if the AddNavigator method makes some buttons invisible, the RemoveNavigator should make these buttons visible again.


IcxNavigator.SaveBookmark

IcxNavigator          See Also

This interface on a control is called when the linked navigator's SaveBookmark button is pressed.

procedure SaveBookmark;

Description

Navigator controls call the SaveBookmark method of their bound controls in response to clicking the SaveBookmark button.  Implement this method to provide the appropriate response to clicking the button.

Please refer to the Responding to Navigator Button Clicks topic for details.


IcxNavigatorOwner
IcxNavigatorOwner Interface

Hierarchy          Methods

Represents an interface that is implemented by navigator controls and is available for the navigated control to call.

Unit

cxNavigator

IcxNavigatorOwner = interface(IUnknown)

Description

Navigator controls (TcxNavigator and TcxDBNavigator objects) implement methods of the IcxNavigatorOwner interface to provide information about the navigator to other objects.  References to this interface are transmitted to some methods as parameters and returned by some properties.  For instance, they are passed as parameters to AddNavigator and RemoveNavigator methods of the IcxNavigator interface.  The reference to interface enables you to obtain all the desired information about the navigator.  For instance, you can obtain the collection of buttons displayed within the control, the bounds of the navigator, its look and feel, etc.


IcxNavigatorOwner Hierarchy
Hierarchy

IUnknown

     |


Methods for IcxNavigatorOwner
IcxNavigatorOwner Methods

IcxNavigatorOwner          Legend

In IcxNavigatorOwner

 GetNavigatorBounds

 GetNavigatorButtons

 GetNavigatorCanvas

 GetNavigatorControl

 GetNavigatorFocused

 GetNavigatorLookAndFeel

 GetNavigatorOwner

 GetNavigatorShowHint

 GetNavigatorTabStop

 NavigatorButtonsStateChanged

 RefreshNavigator


IcxNavigatorOwner.GetNavigatorBounds

IcxNavigatorOwner

Gets the bounding rectangle of the navigator control.

function GetNavigatorBounds: TRect;

Description

The GetNavigatorBounds method is implemented by navigator controls to return their bounding rectangles.  This can be used to evaluate the current navigator size and adjust it if needed, for instance.  To change the size of the control you must access it via the GetNavigatorControl method and use its Width and Height properties.


IcxNavigatorOwner.GetNavigatorButtons

IcxNavigatorOwner

Returns an object that provides button settings for the navigator control.

function GetNavigatorButtons: TcxCustomNavigatorButtons;

Description

The GetNavigatorButtons method is implemented by navigator controls to return objects representing their Buttons property.  This enables you to modify settings of buttons displayed by the navigator.  For instance, if implementing the IcxNavigator interface, you may call GetNavigatorButtons in the AddNavigator method to hide some buttons of the navigator when it becomes bound to a control.


IcxNavigatorOwner.GetNavigatorCanvas

IcxNavigatorOwner

Gets the navigator’s underlying canvas.

function GetNavigatorCanvas: TCanvas;

Description

Navigator controls implement the GetNavigatorCanvas method to return the canvas which is used for painting them.  This member is used internally for navigator painting.  You will probably have no need to use it in most applications.


IcxNavigatorOwner.GetNavigatorControl

IcxNavigatorOwner

Returns the navigators control.

function GetNavigatorControl: TWinControl;

Description

Navigator controls implement the GetNavigatorControl property to return objects representing themselves.  This can be used to change any settings of the navigator control when needed.

Suppose you implement the AddNavigator and RemoveNavigator methods of the IcxNavigator interface.  These methods are called when a navigator becomes linked or unlinked to the control.  You may want to modify the size of the navigator control when binding and then restore the original size when unlinking.

Note that you need to perform the desired typecasts if you want to use type specific properties of the navigator control.


IcxNavigatorOwner.GetNavigatorFocused

IcxNavigatorOwner

Returns whether the navigator control is focused.

function GetNavigatorFocused: Boolean;

Description

This method is implemented by navigator controls to return True if they have input focus and False otherwise.  Actually, the Focused property value of the navigator control is returned.

This method is used internally.  You will probably have no need to use it in most applications.


IcxNavigatorOwner.GetNavigatorLookAndFeel

IcxNavigatorOwner

Returns an object containing look and feel settings of the navigator control.

function GetNavigatorLookAndFeel: TcxLookAndFeel;

Description

The GetNavigatorLookAndFeel method is implemented by navigator controls to return the TcxLookAndFeel object that contains look and feel settings for the control.  These settings specify whether the native painting is enabled (XP painting, if the Windows XP operating system is used) and the painting style used if not.  Modify properties of the obtained TcxLookAndFeel object if you need to provide a different appearance for the navigator.


IcxNavigatorOwner.GetNavigatorOwner

IcxNavigatorOwner

Returns the owner of the navigator control.

function GetNavigatorOwner: TComponent;

Description

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


IcxNavigatorOwner.GetNavigatorShowHint

IcxNavigatorOwner

Returns whether button hints are enabled.

function GetNavigatorShowHint: Boolean;

Description

The GetNavigatorShowHint method is implemented by navigator controls to return True if hints are displayed for buttons and False otherwise.  Actually, the ShowHint property value is returned.

If you need to change the ShowHint property value or other settings of the navigator control, you can access it via the GetNavigatorControl method.


IcxNavigatorOwner.GetNavigatorTabStop

IcxNavigatorOwner

Returns whether end users can tab to the navigator control.

function GetNavigatorTabStop: Boolean;

Description

The GetNavigatorTabStop property value is implemented to return the value of the navigator control’s TabStop property.  This property specifies whether the control is in the tab order.  In other words, if it is set to True, end users can use the Tab key to access the control.

You will probably have no need to use the GetNavigatorTabStop method in most applications.


IcxNavigatorOwner.NavigatorButtonsStateChanged

IcxNavigatorOwner

Updates the enabled state of buttons displayed within the navigator.

procedure NavigatorButtonsStateChanged;

Description

The navigator control displays a set of buttons that change their enabled state with respect to the control bound to it.  For instance, if a navigator is used to operate on dataset records, the Next, NextPage and Last buttons need to be disabled when the current record is the last.  When the NavigatorButtonsStateChanged method is called, the navigator performs the required checking and applies the proper enabled state of buttons.

The TcxNavigator control, for instance, can operate on any object supporting the IcxNavigator interface.  This interface provides a number of methods that allow to determine whether this or that button must be disabled.  However, the TcxNavigator is not automatically notified of changes in its bound control.  Thus, when navigation is performed within the target control, you need to call the NavigatorButtonsStateChanged method of the bound navigator manually.  It performs checks using the mentioned methods and sets button states as needed.


IcxNavigatorOwner.RefreshNavigator

IcxNavigatorOwner

Repaints the navigator control.

procedure RefreshNavigator;

Description

The RefreshNavigator method is implemented by navigator controls to repaint themselves (actually invalidate themselves telling windows to repaint them as soon as possible).  You will probably have no need to use the RefreshNavigator control in most applications.  The control is automatically repainted if its properties or properties of its buttons change.

Sometimes, you may need to call the NavigatorButtonsStateChanged method to force the control to update the enabled state of its buttons.  Please refer to this method description for details.


Responding to Navigator Button Clicks

See Also

The TcxNavigator control enables you to add navigation capabilities to any object.  For instance, it may be used to navigate through a dataset created at runtime or perform navigation through items of some control.  This is possible because the object affected by the navigator control is specified by the Control property which is of the IcxNavigator type.  This means that you can assign any object implementing the IcxNavigator interface to it.  If you need to bind the navigator to an existing object that doesn’t support the interface, you must create a descendant and implement interface methods in it.

The methods declared by the IcxNavigator interface can be divided into three groups:

•	Methods that are called when the navigator’s Control property is initialized and cleared;

•	Methods that specify the enabled state of buttons displayed by the navigator;

•	Methods that implement buttons’ functionality.  They are called when corresponding buttons of the navigator are clicked by end users.

This topic is concerned with the third group of methods.  They are:

Method	Description
Cancel	Must be implemented to response to clicking the Cancel button.  This button is intended to cancel changes made to the underlying data if they haven’t been posted already.  The button’s settings can be accessed via the Buttons.Cancel property of the navigator.
Delete	Must be implemented to response to clicking the Delete button.  This button is intended to delete the currently selected item of the underlying data.  The button’s settings can be accessed via the Buttons.Delete property of the navigator.
Edit	Must be implemented to response to clicking the Edit button.  This button is intended to switch the underlying object to the edit mode.  The button’s settings can be accessed via the Buttons.Edit property of the navigator.
Filter	Must be implemented to response to clicking the Filter button.  This button is intended to apply filtering to the underlying data.  The button’s settings can be accessed via the Buttons.Filter property of the navigator.
First	Must be implemented to response to clicking the First button.  This button is intended to select the first item of the underlying data.  The button’s settings can be accessed via the Buttons.First property of the navigator.
GotoBookmark	Must be implemented to response to clicking the GotoBookmark button.  This button is intended to locate the item corresponding to the saved bookmark.  The button’s settings can be accessed via the Buttons.GotoBookmark property of the navigator.
Insert	Must be implemented to response to clicking the Insert button.  This button is intended to insert a new item to the current position.  The button’s settings can be accessed via the Buttons.Insert property of the navigator.
Last	Must be implemented to response to clicking the Last button.  This button is intended to select the last item of the underlying data.  The button’s settings can be accessed via the Buttons.Last property of the navigator.
Next	Must be implemented to response to clicking the Next button.  This button is intended to select the next item.  The button’s settings can be accessed via the Buttons.Next property of the navigator.
NextPage	Must be implemented to response to clicking the NextPage button.  This button intended to move selection by a predefined number of items forward.  The button’s settings can be accessed via the Buttons.NextPage property of the navigator.
Post	Must be implemented to response to clicking the Post button.  This button is intended to apply changes made to the underlying data.  The button’s settings can be accessed via the Buttons.Post property of the navigator.
Prior	Must be implemented to response to clicking the Prior button.  This button is intended to select the previous item.  The button’s settings can be accessed via the Buttons.Prior property of the navigator.
PriorPage	Must be implemented to response to clicking the PriorPage button.  This button is intended to move the selection by the predefined number of items backwards.  The button’s settings can be accessed via the Buttons.PriorPage property of the navigator.
Refresh	Must be implemented to response to clicking the Refresh button.  This button is intended to update the underlying data (or to update its visual representation).  The button’s settings can be accessed via the Buttons.Refresh property of the navigator.
SaveBookmark	Must be implemented to response to clicking the SaveBookmark button.  This button is intended to store a bookmark corresponding to the current record.  The button’s settings can be accessed via the Buttons.SaveBookmark property of the navigator.

As you can see, each button provided by the navigator control has its specific meaning.  Additionally, each button has a descriptive image assigned by default.  So it is natural to implement methods listed above so that they perform actions similar to their meaning.  This will suite your needs most commonly.

Actually, when using the TcxNavigator control, each button can perform any actions you like.  This means that the control should not necessarily be used to navigate through and edit data only.  For instance, you may provide a button that copies the content of the currently selected data item into the clipboard.  Another example can be using navigator buttons to assign different styles to data items visually represented in the control bound to the navigator.

It is not enough to provide custom behavior for a button by implementing the corresponding interface method in a specific manner.  You need to provide another appearance for the button in this case.  This must be performed in the implementation of the AddNavigator method of the IcxNavigator interface.  The method is automatically called the object implementing the interface becomes bound to the navigator.  To access settings of the desired button, use properties listed in the table above.

You can also use the AddNavigator method to hide the buttons of the navigator control that are not needed when operating on the object of a specific type.  Note that you must use the RemoveNavigator method if you need to restore the initial navigator’s settings when disconnecting the navigator from the object.


Using the MaskEdit

See Also

MaskEdit is an advanced version of the TextEdit editor for providing user input validation facilities.

Use the TcxMaskEdit object to place a masked edit control onto your form.

TcxMaskEdit implements the generic behavior introduced in TcxCustomMaskEdit by publishing many of the properties and methods inherited from it, but does not introduce any new behavior.

The major feature of the MaskEdit is the edit mask that provides mask validating and the formatting of user input.  MaskEdit supports three types of edit mask:

1.	Standard

2.	Regular Expressions

3.	Extended Regular Expressions

Standard

The standard edit mask is a string that consists of three fields with semicolons separating them.  The first part of the mask is the mask itself.  The second part is the character that determines whether literal characters within the mask are saved as part of the data.  The third part of the mask is the character used to represent un-entered characters in the mask.

These are the special characters used in the first field of the mask:

Character	Meaning in mask
!	If the ! character appears in the mask, optional characters are represented in the text as leading blanks.  If the ! character is not present, optional characters are represented in the text as trailing blanks.
>	If the > character appears in the mask, all characters that follow are in uppercase until the end of the mask or until the < character is encountered.
<	If the < character appears in the mask, all characters that follow are in lowercase until the end of the mask or until the > character is encountered.
<>	If these two characters appear together in the mask, no case checking is done and the data is formatted with the case the user uses to enter data.
\	The character that follows the \ character is a literal character.  Use this character to use any of the mask special characters as a literal in the entered data.
L	The L character requires an alphabetic character only in this position.  For the US, this is A-Z, a-z.
l	The l character permits only an alphabetic character in this position, but doesn't require it.
A	The A character requires an alphanumeric character only in this position. For the US, this is A-Z, a-z, 0-9.
a	The a character permits an alphanumeric character in this position, but doesn't require it.
C	The C character requires an arbitrary character in this position.
c	The c character permits an arbitrary character in this position, but doesn't require it.
0	The 0 character requires a numeric character only in this position.
9	The 9 character permits a numeric character in this position, but doesn't require it.
#	The # character permits a numeric character or a plus or minus sign in this position, but doesn't require it.
:	The : character is used to separate hours, minutes, and seconds in times.  If the character that separates hours, minutes, and seconds differs from the regional settings of the Control Panel utility on your computer system, that character is used instead.
/	The / character is used to separate months, days, and years in dates.  If the character that separates months, days, and years differs from the regional settings of the Control Panel utility on your computer system, that character is used instead.
;	The ; character is used to separate the three fields of the mask.
_	The _ character automatically inserts spaces into the text.  When the user enters characters in the field, the cursor skips the _ character.

Any character that does not appear in the preceding table can appear in the first part of the mask as a literal character.  Literal characters must be matched exactly in the edit control.  They are inserted automatically, and the cursor skips over them during editing.  The special mask characters can also appear as literal characters if preceded by a backslash character (\).

The second field of the mask is a single character that indicates whether literal characters from the mask should be included as part of the text for the edit control.  For example, the mask for a telephone number with area code could be the following string:

(000)_000-0000;0;*

The 0 in the second field indicates that the Text property for the edit control would consist of the 10 digits that were entered, rather than the 14 characters that make up the telephone number as it appears in the edit control.

A 0 in the second field indicates that literals should be omitted, any other character indicates that they should be included.

The third field of the mask is the character that appears in the edit control for blanks (characters that have not been entered).  By default, this is the same as the character that stands for literal spaces.  The two characters appear the same in an edit window.  However, when a user edits the text in a masked edit control, the cursor selects each blank character in turn, and skips over the space character.

Regular Expressions

MaskEdit supports regular expressions to validate and format user input.  For a complete regular expression reference see the Using Regular Expressions topic.

Extended Regular Expression

This is similar to a regular expression but with an added auto complete facility.  If, while entering text into a MaskEdit a user has no alternative text to enter, the text is auto-completed to the point where an alternative appears again.

For example, the regular expression is:

\w+’ ’like’ ’\w+’ ‘apples!

After a user enters, for instance ‘I’ and presses the space button, the text is auto completed to the following:

‘I like ’;

After a user enters, for instance ‘red’ and presses space again, the text is auto completed to the following:

‘I like red apples!’


Using Regular Expressions

See Also

Preface

This specification covers the regular expressions syntax.

We use regular expressions to validate user input in the TcxMaskEdit via mask.  This editor provides two mask representations:

•	Easy to use Delphi standard mask

•	A very powerful regular expressions mask.

Reference

A regular expression can consist of characters (letters, digits and others which are not command characters), command characters and metacharacters.

1.	Characters

If one of the characters listed below occurs in the mask, the input string must contain the same character at this position.

The following characters are supported:

A-Z, a-z, 0-9,

and non-letter and non–digit characters:

~, ', !, @, #, $, %, ^, &, -, _, =, ,, <, >, /, ;, :, ".

Note: you can use other characters by placing \ before them.  For instance, \[ will be treated as [ by the regular expression compiler.

Spaces are ignored by the compiler unless they are enclosed in single quotes - '.

Example:

The Making' 'RAD' 'a' 'Reality! expression matches only the Making RAD a Reality! string.

2.	Command characters:

These characters are not interpreted as symbols but as commands by the compiler.  They are used to organize grouping, quantifications and conditions.

•	Grouping:

Character Sequence Grouping – ( )

This grouping is commonly used in quantifier operations: ?, +, *. (These are described later.)

Examples:

(a)+ matches a, aaa or aaaa. (+ means that the preceding character can occur one or more times)

(abc)+ matches abc, abcabc or abcabcabc.

This grouping is also used in back references.  A back reference is a part of regular expression that can be referenced via a special metacharacter \n (where 1 =< n =< 9).

You can use them in the expression to make it shorter and easier to read.

The 3abcabcabc expression will be better written as 3(abc)\1\1.  In this example the \1 references abc sequence.

OR Grouping – [ ]

Means that any symbol listed within square brackets can represent a character.

Examples:

[bfc]at matches bat, fat and cat.

OR grouping supports all quantifiers: ?, * and + (described later).  But quantifiers enclosed in square brackets are treated as simple characters.

[bfc]?at matches bat, fat, cat and at.

b[oa]+t matches bot, bat, boot and boat.

a[in]*t matches at, ait and ant.

OR grouping supports ranges:

[A-Z] matches any Latin capital letter.

[0-9A-Fa-f] matches any hexadecimal number.

Exclusive OR Grouping – [^]

Means that any symbol except those in square brackets can represent a character.

Example:

[^abc] matches any symbol except a, b, and c.

Exclusive OR grouping supports all quantifiers: ?, * and +.(described later).  But quantifiers enclosed in square brackets are treated as simple characters.

Example:

[^0-9]+ Matches any text sting without digits (for instance, ExpressQuantumGrid but not ExpressQuantumGrid4).

Variant Grouping – ( | )

Contains several sequences that can match on an OR basis.

Example:

(b|z)oo matches both zoo and boo.

(abc|123) matches abc and 123.

?	Quantifiers

* matches the preceding expression zero or more times.

The expression can be a symbol or group of symbols.

Example:

zo* matches z, zo and zoo.

[#$][0-9a-f]* matches $00ff00, #ff1234234, $ or #.

[0-9]*[.][0-9] matches any decimal value with a single digit after the decimal separator.

(a|b|c)* matches aaaa, bbb, cc, abc, acc, cba or an empty string.

+ matches the preceding expression one or more times.

The expression can be a symbol or group of symbols.

Example:

zo+ matches zo and zoo, but not z.

$[0-9]+.99 matches any string, thus representing a currency format.

[#$][0-9a-f]+ matches $00ff00, #ff1234234, but not $ or #.

? matches the preceding expression zero or one time.

The expression can be a symbol or group of symbols.

Example:

zoo? matches zo and zoo, but not z.

[#$][0-9a-f]? - matches $, #e, but not #2a.

{n} matches the preceding expression exactly n times.

The expression can be a symbol or group of symbols.

Example:

zo{2} matches zoo but not zo or zooo.

$[0-9a-f]{8} matches $00ff01de but not $ff or $0ffffe333.

{n,} matches the preceding expression at least n times.

The expression can be a symbol or group of symbols.

Example:

zo{2,} matches zoo or zooo but not z or zo.

$[0-9a-f]{4,} matches $00ff or $ffddee but not $ff.

{n,m} matches the preceding expression at least n times and at most m times.

The expression can be a symbol or group of symbols.

Example:

zo{1,2} matches zo and zoo but not z or zooo.

$[0-9a-f]{4,8} matches $00ff01de and $00ff but not $ff or $0ffffe333.

3.	Metacharacters

Metacharacters are used to represent a symbol or a range of symbols.

Character	Description
\d	Matches a digit character. Equivalent to [0-9].
\D	Matches a non digit character. Equivalent to [^0-9].
\f	Matches a form-feed character. Equivalent to \x0c.
\n	Matches a new line character. Equivalent to \x0a.
\r	Matches a carriage return character. Equivalent to \x0d.
\s	Matches any white space character including space, tab, form-feed, etc.
\S	Matches any non white space character.
\t	Matches a tab character. Equivalent to \x09.
\w	Matches any word character including underscore. Equivalent to '[A-Za-z0-9_]'.
\W	Matches any non-word character. Equivalent to '[^A-Za-z0-9_]'.
\xn	Matches n, where n is a hexadecimal escape value.  Hexadecimal escape values must be exactly two digits long.  For example, '\x41' matches "A". '\x041' is equivalent to '\x04' & "1".  Allows ASCII codes to be used in regular expressions.
.	Matches any symbol. It is treated as full stop within square brackets.

Examples:

\d\d\d\-\d\d\-\d\d matches any phone number (for instance 555-65-92 or 123-45-67).

\w+\d? matches any sequence on non-digit characters followed by an optional digit (for instance ExpressQuantumGrid or ExpressQuantumGrid4 but not All4You).

Some complex examples of regular expressions:

([01]?\d|2[0-3]):[0-5]\d:[0-5]\d – a regular expression representing the pattern for 24 hours time format.

Let us consider it in detail:

[01]?\d matches any number between 0 and 19. Zero can precede single digit numbers (for instance 0, 5, 02 or 14).

2[0-3] matches any number between 20 and 23.

([01]?\d|2[0-3]) matches any number between 0 and 23.

: - means that there must be a valid time separator.  A valid time separator is obtained from the system regional settings.

[0-5]\d matches any number between 0 and 59.  Zero precedes all single digit numbers (for instance 00, 05, 34, 59)

[\w\-.]+@[\w\-]+(\.[\w\-]+)+ - a regular expression that represents a pattern for e-mail addresses.

Let us consider it in detail:

[\w\-.]+ matches any letter, digit, hyphen, underscore or full stop one or more times.

[\w\-]+ matches any letter, digit, underscore or hyphen one or more times.

(\.[\w\-]+)+ matches full stop followed by a letter, digit, underscore or hyphen sequence one or more times.


Using the SmartTextToDate Function

See Also

As well as entering dates using the date editor’s dropdown calendar, a user can enter dates manually within the edit box.  If the editor’s Properties.InputKind is set to ikStandard or ikRegExpr, then a user can type one of the predefined strings to enter specific dates.  For instance, typing ‘today’ results in setting the present date in the editor.

A date editor uses the global SmartTextToDate function for this purpose.  It converts human readable strings such as "today", "yesterday" or "Sunday" into TDateTime format.  Strings supported by a date editor and the SmartTextToDate function are stored as resources and they are listed in the table below:

Constant	Value	Description
cxSDateToday	'today'	the current date
cxSDateYesterday	'yesterday'	yesterday’s date
cxSDateTomorrow	'tomorrow'	tomorrow’s date
cxSDateSunday	'Sunday'	next Sunday *
cxSDateMonday	'Monday’	next Monday *
cxSDateTuesday	'Tuesday'	next Tuesday *
cxSDateWednesday	'Wednesday'	next Wednesday *
cxSDateThursday	'Thursday'	next Thursday *
cxSDateFriday	'Friday'	next Friday *
cxSDateSaturday	'Saturday'	next Saturday *
cxSDateFirst	'first'	the first day of the current week
cxSDateSecond	'second'	the second day of the current week
cxSDateThird	'third'	the third day of the current week
cxSDateFourth	'fourth'	the fourth day of the current week
cxSDateFifth	'fifth'	the fifth day of the current week
cxSDateSixth	'sixth'	the sixth day of the current week
cxSDateSeventh	'seventh'	the seventh day of the current week
cxSDateBOM	'bom'	the first day of the current month
cxSDateEOM	'eom'	the last day of the current month
cxSDateNow	'now'	the current date, including the current time
* If the constant coincides with today, the SmartTextToDate function returns the current date.

For localization purposes, you might want to substitute the value of a specific resource string.  To change a resource string, use the cxSetResourceString procedure available within the cxClasses unit.

For instance, to set cxSDateToday to a value of ‘current_day’, implement the following code:

//Delphi

  cxSetResourceString(@cxSDateToday, 'current_day');

//C++ Builder

  cxSetResourceString(&_cxSDateToday, "current_day");

Note:	if you want date editors to recognize the ‘current_day’ string, you need to rebuild the masks used by the editors.  To do so, just call the GetFormats and NotifyListeners functions of the global format controller object:

//Delphi

  cxFormatController.GetFormats;

  cxFormatController.NotifyListeners;

var

  VDate: TDateTime;

//...

  if SmartTextToDate('tomorrow', VDate) then

    ShowMessage(FormatDateTime('d mmmm yyyy', VDate));

  cxSetResourceString(@cxSDateTomorrow, 'next_day');

  if SmartTextToDate('tomorrow', VDate) then

    ShowMessage(FormatDateTime('d mmmm yyyy', VDate))

  else

    ShowMessage('No such constant');

  if SmartTextToDate('next_day', VDate) then

    ShowMessage(FormatDateTime('d mmmm yyyy', VDate));

While executing the code, you will see how resource constant changing works.

The first SmartTextToDate function call will be a success.

The second will fail because we have changed the value of the tomorrow constant to "next_day".

The third call will be a success because we call SmartTextToDate function with the changed constant.

These constants are mainly used with the SmartTextToDate function.  The AText parameter of the SmartTextToDate function specifies the string which is compared with every embedded constant. If a match is found, the function places the associated value into the ADateTime parameter and returns True. If there is no match to the input string, the function simply returns False.

If the supplied constants are not sufficient, you can write your own parser function to parse the AText parameter and use it to convert your own constants into TDateTime type.

The following code provides a user parser function which recognizes "Independence_day" and "Christmas" strings and converts them into appropriate TDateTime values.

//Delphi

const

  cxIndependenceDay = 'Independence_day';

  cxChristmas = 'Christmas';

function MySmartTextToDate(const AText: string; var ADate: TDateTime): Boolean;

var

  Year: Integer;

begin

  if AnsiCompareText(AText, cxIndependenceDay) = 0 then

  begin

    //Getting the current year (see GetDateElement function in

    //cxDateUtils.pas).

    Year := GetDateElement(Date, deYear);

    //Encoding the 4th of July and current year.

    ADate := EncodeDate(Year, 7, 4);

    //Indicating that function was a success.

    Result := True;

  end

  else if AnsiCompareText(AText, cxChristmas) = 0 then

  begin

    //Getting the current year (see GetDateElement function in

    //cxDateUtils.pas).

    Year := GetDateElement(Date, deYear);

    //Encoding the 25th of December and current year.

    ADate := EncodeDate(Year, 12, 25);

    //Indicating that function was a success.

    Result := True;

  end

  else

    //Otherwise the function was a failure.

    Result := False;

end;

In order to use the parser function, you should use the SmartTextToDateFunc global variable (nil by default).  If you assign your parser function to this variable, then it will be called on conversion failure. The SmartTextToDate function passes the AText and ADate parameters to your function and calls it. The following code demonstrates this procedure:

//Delphi

var

  VDate: TDateTime;

begin

  //Assigning user parser function to the global variable

  //SmartTextToDateFunc

  SmartTextToDateFunc := MySmartTextToDate;

  //Executing SmartTextToDate with a non-embedded constant

  //When it fails it will call MySmartTextToDate

  //And according to the MySmartTextToDate implementation

  //(see above) it will succeed.

  if SmartTextToDate(cxChristmas, VDate) then

    //Showing the message box to confirm successful

    //conversion.

    ShowMessage(FormatDateTime('d mmmm yyyy', VDate));

end;

If we assume that current year is 2002 you will see the following message box:

Although the SmartTextToDate function is now able to recognize the ‘Independence_day’ and ‘Christmas’ strings, a date editor does not allow you to enter these strings when regular expressions are used for input validation, i.e. when the editor’s Properties.InputKind property is set to ikRegExpr.  To enable a date editor to recognize these strings, you need to modify the regular expression specified by the RegExprDateEditMask property of the global format controller.  In a system with English(United States) regional settings, the regular expression is generated by default as follows:

(((0?[1-9]|1[012])|
(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec))'/'([012]?[1-9]|[123]0|31)'/'\d\d\d\d)|
((today|yesterday|tomorrow|Sunday|Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|first|second|third|fourth|fifth|sixth|seventh|bom|eom|now)((\+|-)\d(\d(\d(\d?)?)?)?))

We will insert new strings after word ‘now’:

//Delphi

var

  ANewItems, ANewMask: string;

//...

  ANewItems := '|' + cxIndependenceDay + '|' + cxChristmas;

  with cxFormatController do

  begin

    ANewMask := RegExprDateEditMask;

    Insert(ANewItems, ANewMask, Length(ANewMask) - 27);

    RegExprDateEditMask := ANewMask;

  end;


Using Lookup Editors

See Also

The ExpressEditors Library introduces four editors implementing lookup functionality:

•	LookupComboBox editors (represented by the TcxLookupComboBox and TcxDBLookupComboBox classes) display dataset records within a dropdown window in a column-based format

•	ExtLookupComboBox editors (TcxExtLookupComboBox and TcxDBExtLookupComboBox editors) display a data-aware (banded) table view within the dropdown window

This topic explains how to set up a LookupComboBox control.  However, an ExtLookupComboBox editor can be customized in a similar way.  The main differences are as follows:

•	a data source to display in the dropdown window is assigned indirectly, via the view object (the Properties.View attribute).  The view determines the visibility of columns, their group indexes, etc.

•	a column whose data is displayed in the edit box and against which an incremental search/filtering is performed is specified by the Properties.ListFieldItem property

In the first section you can find detailed information on the LookupComboBox and the second section contains information on how to manage the DBLookupComboBox which is designed to edit a dataset field.

1.Setting up a LookupComboBox

The LookupComboBox editor is capable of displaying dataset values.  Values are displayed within the edit region of an editor and its dropdown window (which displays data in a tabular manner).  To establish a connection between the LookupComboBox and the dataset being displayed within the editor, a user needs to specify the Properties.ListSource property value.  This property identifies a TDataSource instance connected to the dataset (for instance, a TTable object).  In this example, the LookupComboBox will be connected to the Customer table from the DBDEMOS database shipped with Borland Delphi or C++ Builder.  The following image demonstrates how to connect a LookupComboBox to a data source at design time:

The following code line performs the same actions:

//Delphi

  cxLookupComboBox1.Properties.ListSource := DataSource1;

//C++ Builder

  cxLookupComboBox1->Properties->ListSource = DataSource1;

After that, you must choose the dataset fields to display within the LookupComboBox by setting the Properties.ListFieldNames property value.  This property contains the names of dataset fields and they are separated by semicolon(s).  The following image demonstrates how to set up the Properties.ListFieldNames property value at design time:

The following code sets the Properties.ListFieldNames property value:

//Delphi

  cxLookupComboBox1.Properties.ListSource := DataSource1;

  cxLookupComboBox1.Properties.ListFieldNames := 'Company;Addr1';

//C++ Builder

  cxLookupComboBox1->Properties->ListSource = DataSource1;

  cxLookupComboBox1->Properties->ListFieldNames = "Company;Addr1";

Note:  On adding a dataset field to the Properties.ListFieldNames property value, a column is added to the Properties.ListColumns collection.  Use the list columns collection editor at design time to edit this collection (or modify the Properties.ListFieldNames property value):

This editor allows you to set up different options for the dropdown list columns of a lookup combo box.  The main property of each lookup combo box column is the FieldName property, which specifies the dataset field displayed within a specific column.  The Sorting and SortOrder properties determine the display order of a specific column.  The RepositoryItem property is used to specify the repository item to use as an editor of a specific column’s contents.  For instance, a user can assign a TcxCheckBox control to represent the values when the ListSource field contains Boolean data.  Other properties define the visual representation of columns within the editor dropdown (Caption, Width, MinWidth and HeaderAlignment properties).

The next important thing is to specify the key field used to identify records of the dataset to be displayed within the editor dropdown.  The name of the Properties.ListSource key field must be assigned to the Properties.KeyFieldNames property. The design time approach is demonstrated on the following image:

The following code shoes how to set the Properties.KeyFieldNames property value programmatically:

//Delphi

  cxLookupComboBox1.Properties.ListSource := DataSource1;

  cxLookupComboBox1.Properties.ListFieldNames := 'Company;Addr1';

  cxLookupComboBox1.Properties.KeyFieldNames := 'CustNo';

//C++ Builder

  cxLookupComboBox1->Properties->ListSource = DataSource1;

  cxLookupComboBox1->Properties->ListFieldNames = "Company;Addr1";

  cxLookupComboBox1->Properties->KeyFieldNames = "CustNo";

To choose which field values to display within the edit region of the LookupComboBox, set the Properties.ListFieldIndex property to the required value.  This value represents the index of a field within the Properties.ListFieldNames list.  In this example, the Properties.ListFieldIndex property value is 0 (the default value).

After this step, the LookupComboBox is connected to the dataset and is fully operational.  However, if we launch the application, you will notice that the edit region of the LookupComboBox is empty.  When you select a specific record in the dropdown, the value of the record’s field addressed by the Properties.ListFieldIndex property is picked out into the edit region.

The editor’s edit value is also obtained from the selected record and can be accessed via the EditValue property.  This property value matches the ListSource key field value (identified via the Properties.KeyFieldNames property).  A user can specify the EditValue property by code or via the Object Inspector, but if there is no records whose key field values match the edit value, the editor displays nothing.

If the EditValue property value is specified at design time (see the image below), the LookupComboBox displays an appropriate value:

You may also adjust the editor by setting the Properties.DropDownAutoSize property to True.  This allows the width of the LookupComboBoxs dropdown window to resize according to it’s contents.  Set the Properties.IncrementalFiltering property to True (the default), to enable filtering during the incremental search.  The following image demonstrates a LookupComboBox with the Properties.IncrementalFiltering set to True):

2. Setting up a DBLookupComboBox

The DBLookupComboBox is a data-aware version of the LookupComboBox described in the previous section.  The DBLookupComboBox editor is capable of editing dataset values using values from the lookup combo box’s dropdown list.

Setting up a DBLookupComboBox consists of two phases: the first phase includes setting up the editor dropdown list, similar to the actions described in the previous section; and the second, which enables the editing capability of the DBLookupComboBox.

To set up a DBLookupComboBox we must have two datasets: one providing values for the editor dropdown list and another, the one being edited using values from the editor dropdown.  In this example, the dataset used for populating the DBLookupComboBox dropdown list is the Customer table of the DBDEMOS database and the Orders table is being edited.  A one-to-many relation connects these two tables via their common CustNo field

Connect your DBLookupComboBox to the Customer table as described in the previous section.  Unlike the LookupComboBox, the data-aware version uses the DataBinding property instead of the EditValue property to specify the value to display within the edit region of its combo box.  Next, assign a TDataSource instance to the DataBinding.DataSource property of the DBLookupComboBox.  The following image demonstrates the design time approach:

Use the following code to set a specific value to the DataBinding.DataSource property:

//Delphi

  cxDBLookupComboBox1.DataBinding.DataSource := DataSource2;

//C++ Builder

  cxDBLookupComboBox1->DataBinding->DataSource = DataSource2;

You should now choose a dataset field to be edited via the DBLookupComboBox.  This field is identified via the DataBinding.DataField property value.  The following image demonstrates how to set the DataBinding.DataField property value at design time:

The following code demonstrates how to set the DataBinding.DataField property value programmatically:

//Delphi

  cxDBLookupComboBox1.DataBinding.DataSource := DataSource2;

  cxDBLookupComboBox1.DataBinding.DataField := 'CustNo';

//C++ Builder

  cxDBLookupComboBox1->DataBinding->DataSource = DataSource2;

  cxDBLookupComboBox1->DataBinding->DataField := "CustNo";

Note: A dataset field identified via the DataBinding.DataField property must contain the same values as the field specified via the Properties.KeyFieldNames property.   Note:  these fields may have different names.

Now that the DBLookupComboBox is set up, let’s test its editing capabilities.

Place the TcxGrid control onto a form.  Connect it to the dataset, that you have previously assigned to the DataBinding.DataSource property of the DBLookupComboBox.  Now launch the application.  If you navigate through the TcxGrid rows, you will notice that the value displayed within the DBLookupComboBox edit region changes.  The following image demonstrates the created sample form:

Note that the currently focused row within the TcxGrid has 1380 as a CustNo field value and the DBLookupComboBox displays the Company field value (the Properties.ListSource dataset) corresponding to the current value of the CustNo field.

Now open the DBLookupComboBox dropdown list and select any item except for the currently focused one.  See the image below:

Note that the TcxGrid has switched into editing mode for the focused record.  If we post the EditValue to the editor, the dataset record will be updated.  See the changes on the following image:

The TcxGrid now displays 1351 as the CustNo field value.  That value corresponds to the CustNo field value within the Properties.ListSource dataset as displayed within the DBLookupComboBox.

The DBLookupComboBox can obtain data from the lookup field defined for the dataset.  This lookup field is a read-only field that displays values at runtime based on the search criteria you specify. In its simplest form, the following parameters are passed to a lookup field: the name of the existing field to search by, the field value to search for and the lookup dataset field to be displayed.

Let’s create a lookup field to display values from the Customer table identified via the Orders table records.  Place two TTable components onto a form and connect them to the Orders and Customer tables.  Lookup fields can be defined via the Fields Editor for a specific dataset.

Activate the New Field dialog for the dataset corresponding to the Orders table.  This dialog provides a convenient way of adding new dataset fields

•	Enter a new name for the lookup field in the Name edit box. (not an existing field).

•	Choose a data type for the field from the Type combo box.

•	Enter the size of the field in the Size edit box (as appropriate).

•	Select Lookup in the Field type radio group. Selecting Lookup enables the Dataset and Key Fields combo boxes.

•	Choose a DataSet from the Dataset combo box drop-down list.  This will be used to look up field values. The lookup dataset must differ from the dataset for the field component itself, or else a circular reference exception will be  raised at runtime. Specifying a lookup dataset enables the Lookup Keys and Result Field combo boxes.

•	Choose from the Key Fields drop-down list a field in the current dataset for which to match the lookup data set key field values. To match more than one field, enter field names directly instead of choosing from the drop-down list. Separate multiple field names with semicolons. If you are using more than one field, you must use persistent field components.

•	Choose from the Lookup Keys drop-down list a field in the lookup dataset to match against the Key Fields field you specified in the previous step. If you specified more than one key field, you must specify the same number of lookup keys. To specify more than one field, enter field names directly, separating multiple field names with semicolons.

•	Choose from the Result Field drop-down list a field in the lookup dataset to return as the value of the lookup field you are creating.

See the image below to know how to populate a New Field dialog:

When a lookup field is used as a data source for a DBLookupComboBox, setting up a lookup combo box is very simple – assign the dataset containing a lookup field to the Databinding.DataSource property and specify the lookup field name as a DataBinding.DataField property value.  If an appropriate dataset is active, the DBLookupComboBox displays appropriate values within the edit region and the dropdown list.  Note that in this instance, the DBLookupComboBox property values are obtained from the lookup field settings.  This relates to the Properties.ListFieldNames property, which is assigned the name of the resulting field and to the Properties.KeyFieldNames property, which is assigned the name of the lookup key field.  The Properties.ListSource property value is not specified, but all necessary settings are obtained from the lookup field.  A user can add required field names from the lookup dataset to the Properties.ListFieldNames property value, but the name of the resulting lookup field must remain unchanged.


cxFormats Unit Overview
cxFormats Unit

Classes

TcxFormatController

Interfaces

IcxFormatContollerListener

Routines

cxFormatController


TcxFormatController
TcxFormatController Object

Hierarchy          Properties          Methods          See Also

Represents a class controlling the formatting of currency and date values for a number of controls.

Unit

cxFormats

TcxFormatController = class(TCustomForm);

Description

The TcxFormatController class manages the formatting of currency and date values for several controls.  It provides the CurrencyFormat, RegExprDateEditMask, StandardDateEditMask and StartOfWeek properties which specify the currency and date formats for all editors registered in TcxFormatController.  Providing the same formatting for several editors is implemented via a ‘listener’ technique.  An editor must implement the IcxFormatControllerListener interface and register itself in TcxFormatController by calling the AddListener method.  When the currency and date formats are changed, all listeners receive "format changed" notifications and thus their values are always formatted correctly.

TcxFormatController stores the currency and date formatting for the TcxCustomCurrencyEdit and TcxCustomDateEdit controls.  When these editors are created, they add themselves as listeners to a TcxFormatController global instance.  Every time currency and date formats are changed, the controller calls the IcxFormatControllerListener.FormatChanged method for each listener and thus editors reflect all changes by updating specific properties, if necessary.  When editors are destroyed, they invoke the RemoveListener method.

There are three ways to change currency and date formatting:

•	update specific format variables declared in the SysUtils unit;

•	change system locale settings;

•	set the above-mentioned format controller’s properties.

Default values for the date and currency formats are determined based on the system locale.  Some properties are constructed based on values of the format variables declared in the SysUtils unit (ShortDateFormat, CurrencyString, CurrencyFormat etc).  You can programmatically change these variables, however editors will not reflect changes until you manually invoke the controller’s GetFormats and NotifyListeners methods.  Use the cxFormatController function to return a global instance of the TcxFormatController class.

If the TApplication.UpdateFormatSettings property is set to True, TcxFormatController receives WM_WININICHANGE messages.  In this case, the controller recreates the currency and date format strings based on the system locale and SysUtils variables and notifies its listeners of the format changes.

Setting the format controller’s properties directly invokes the NotifyListeners method.  If several properties must be changed, use the BeginUpdate and EndUpdate mechanism to eliminate unnecessary repainting.


TcxFormatController Hierarchy
Hierarchy

TCustomForm

     |


Properties for TcxFormatController
TcxFormatController Properties

TcxFormatController          Legend

In TcxFormatController

CurrencyFormat

FirstWeekOfYear

RegExprDateEditMask

StandardDateEditMask

StartOfWeek

UseDelphiDateTimeFormats


Methods for TcxFormatController
TcxFormatController Methods

TcxFormatController          Legend

In TcxFormatController

AddListener

BeginUpdate

EndUpdate

GetFormats

NotifyListeners

RemoveListener


TcxFormatController.CurrencyFormat

TcxFormatController          See Also

Defines the format to represent currency values.

property CurrencyFormat: string;

Description

The CurrencyFormat property specifies the format for the editors representing currency values.  The currency format is constructed based on the CurrencyString, CurrencyFormat and CurrencyDecimals properties defined in the SysUtils unit.  Format specifiers are listed in the TcxCustomTextEditProperties.DisplayFormat topic.  For the English (United States) locale the default value of CurrencyFormat is ‘$,0.00;-$,0.00’.

When this property is changed (either by the TcxFormatController class to reflect system locale changes or by changing the property directly), all subscribed controls receive a "format changed" notification.

Note:	If you change several TcxFormatController properties it is best to enclose the update operations within the BeginUpdate and EndUpdate methods.


TcxFormatController.FirstWeekOfYear

TcxFormatController          See Also

Specifies the first week of the year for date editors.

type

  TcxFirstWeekOfYear = (fwySystem, fwyJan1, fwyFirstFullWeek, fwyFirstFourDays);

property FirstWeekOfYear: TcxFirstWeekOfYear;

Description

Use the FirstWeekOfYear property to specify which week should be considered the first week of the year for date editors such as the TcxDateEdit and its data-aware version, the TcxDBDateEdit.  The property’s value affects how weeks are enumerated within the year and are painted within the date editor’s dropdown calendar provided that the editor’s Properties.WeekNumbers property is set to True.

When the FirstWeekOfYear property is changed (either by the TcxFormatController class to reflect system locale changes or by changing the property directly), all subscribed controls receive a "format changed" notification.

Note:	If you change several TcxFormatController properties it is best to enclose the update operations within the BeginUpdate and EndUpdate methods.


TcxFormatController.RegExprDateEditMask

TcxFormatController          See Also

Specifies the mask with a regular expression syntax to enter date values.

property RegExprDateEditMask: string;

Description

The RegExprDateEditMask property defines the mask with a regular expression syntax to enter date values.  Date editors presented by the TcxCustomDateEdit class use this mask when the corresponding mask mode is set via the TcxCustomDateEditProperties.InputKind property.  The mask is constructed based on the ShortDateFormat, ShortMonthNames and DateSeparator variables declared in the SysUtils unit.

When the RegExprDateEditMask property is changed (either by the TcxFormatController class to reflect system locale changes or by changing the property directly), all subscribed controls receive a "format changed" notification.

Note:	If you change several TcxFormatController properties it is best to enclose the update operations within the BeginUpdate and EndUpdate methods.

Set the TApplication.UpdateFormatSettings property to False to disable the TcxFormatController members update because of changes to the system locale settings.


TcxFormatController.StandardDateEditMask

TcxFormatController          See Also

Specifies the mask with a standard TMaskEdit syntax to enter date values.

property StandardDateEditMask: string;

Description

The StandardDateEditMask property defines a mask to enter date values.  The mask is constructed using syntax for a standard TMaskEdit control.  It is based on the ShortDateFormat variable declared in the SysUtils unit.  Date editors presented by the TcxCustomDateEdit class use this mask when the corresponding mask mode is set via the TcxCustomDateEditProperties.InputKind property.

When the StandardDateEditMask property is changed (either by the TcxFormatController class to reflect system locale changes or by changing the property directly), all subscribed controls receive a "format changed" notification.

Note:	If you change several TcxFormatController properties it is best to enclose the update operations within the BeginUpdate and EndUpdate methods.

Set the TApplication.UpdateFormatSettings property to False to disable the TcxFormatController members update because of changes to the system locale settings.


TcxFormatController.StartOfWeek

TcxFormatController          See Also

Specifies the first day of the week.

type

  TDayOfWeek = 0..6;

property StartOfWeek: TDayOfWeek;

Description

The StartOfWeek property defines the first day of the week.  Values 0…6 correspond to the days of the week starting from Sunday.  The default value for the StartOfWeek property is retrieved from the system locale settings.  It determines the appearance of the TcxDateEdit control, which allows displaying a calendar for a month.

When the StartOfWeek property is changed (either by the TcxFormatController class to reflect system locale changes or by changing the property directly), all subscribed controls receive a "format changed" notification.

Note:	If you change several TcxFormatController properties it is best to enclose the update operations within the BeginUpdate and EndUpdate methods.

Set the TApplication.UpdateFormatSettings property to False to disable the TcxFormatController members update because of changes to the system locale settings.


TcxFormatController.UseDelphiDateTimeFormats

TcxFormatController          See Also

Defines whether to use the SysUtils conversion functions to represent date values.

property UseDelphiDateTimeFormats: Boolean;

Description

Set the UseDelphiDateTimeFormats property to True to employ the SysUtils functions (DateTimeToStr) to convert date values to text representation.  Otherwise, the system functions (GetDateFormat) are called for converting purposes.

The following code lets you use the short time format instead of the long time format in the TcxDateEdit control.

// Delphi

uses

  cxFormats;

...

  LongTimeFormat := 'hh:mm';

  cxFormatController.UseDelphiDateTimeFormats := True;


TcxFormatController.AddListener

TcxFormatController          See Also

Adds a new listener to a TcxFormatController instance.

procedure AddListener(AListener: IcxFormatControllerListener); virtual;

Description

The AddListener method adds a new listener, which will receive notifications on date and currency format changes.  Editors, which require "format changed" notifications (TcxCustomDateEdit and TcxCustomCurrencyEdit, for instance) add themselves as listeners to TcxFormatController.  Thus, all editors subscribed to one format controller employ the same date and currency formats.  The date and currency formats can be changed either by the TcxFormatController class due to an update in the system locale or by setting the format properties directly.  To prevent a format controller from updating format properties because of changes to the system locale, set the TApplication.UpdateFormatSettings property to False

Use the RemoveListener method to remove a specific listener from the notification list.


TcxFormatController.BeginUpdate

TcxFormatController          See Also

Prevents sending notification events until the EndUpdate method is called.

procedure BeginUpdate;

Description

Use the BeginUpdate and EndUpdate methods to enclose the operations changing the currency and date formats.  The BeginUpdate method increments the internal counter while the EndUpdate method decrements it.  Listeners subscribed to TcxFormatController will receive a "format changed" notification after the EndUpdate method sets this counter to zero.


TcxFormatController.EndUpdate

TcxFormatController          See Also

Enables sending notifications to TcxFormatController listeners.

procedure EndUpdate;

Description

Use the BeginUpdate and EndUpdate methods to enclose the operations changing the currency and date formats.  The BeginUpdate method increments the internal counter and the EndUpdate method decrements it.  Listeners subscribed to TcxFormatController will receive a "format changed" notification after the EndUpdate method sets this counter to zero.


TcxFormatController.GetFormats

TcxFormatController          See Also

Generates the date and currency formats based on the SysUtils unit’s variables and system locale settings.

procedure GetFormats;

Description

The GetFormats method reconstructs the date and currency formats identified by the RegExprDateEditMask, StandardDateEditMask, CurrencyFormat properties based on variables in the SysUtils unit and the system locale.  GetFormats also resets the StartOfWeek property value by reading the corresponding system setting.

When you programmatically change the currency and date format variables declared in the SysUtils unit, you need to call the GetFormats method followed by NotifyListeners.


TcxFormatController.NotifyListeners

TcxFormatController          See Also

Notifies registered listeners of format changes.

procedure NotifyListeners;

Description

The NotifyListeners method sends a "format changed" notification to all registered listeners.  NotifyListeners is called automatically after changing the RegExprDateEditMask, StandardDateEditMask, CurrencyFormat, and StartOfWeek properties.  If system locale settings are changed and the TApplication.UpdateFormatSettings property is set to True, the NotifyListeners procedure is also called.

If you change the currency and date format variables declared in the SysUtils unit, you will need to manually call the GetFormats and NotifyListeners methods.


TcxFormatController.RemoveListener

TcxFormatController          See Also

Removes a specific listener from the notification list.

procedure RemoveListener(AListener: IcxFormatControllerListener); virtual;

Description

Call the RemoveListener method to remove a specific listener from the notification list.  RemoveListener removes the listener that was added to the notification list by the AddListener method.


IcxFormatContollerListener
IcxFormatControllerListener Interface

Hierarchy          Methods           See Also

Represents an interface for the controls that require notifications of currency and date format changes.

Unit

cxFormats

IcxFormatControllerListener = interface(IUnknown);

Description

Editors that should receive notifications of currency and date format changes must implement the IcxFormatControllerListener interface.  The TcxFormatController object maintains the currency and date format settings common to all editors registered within it.  Use the TcxFormatController.AddListener method to register a control within the format controller.

Editors such as TcxCustomDateEdit and TcxCustomCurrencyEdit implement a single FormatChanged method of the IcxFormatControllerListener interface.  As they need to be notified of currency and date format changes, they add themselves as listeners to the global instance of the TcxFormatController class.  The cxFormatController function allows you to return this object.  All listeners read the currency and date formats from the TcxFormatController object and, whenever changes are made, editors immediately receive notifications via the FormatChanged method and update their appropriate properties.


IcxFormatContollerListener Hierarchy
Hierarchy

IUnknown

     |


Methods for IcxFormatContollerListener
IcxFormatControllerListener Methods

IcxFormatControllerListener          Legend

In IcxFormatControllerListener

 FormatChanged


IcxFormatContollerListener.FormatChanged
IcxFormatControllerListener.FormatChanged

IcxFormatControllerListener          See Also

The function is called when any of the date and currency formats are changed.

procedure FormatChanged;

Description

Use the FormatChanged function to implement updates of the editor’s appropriate properties because of date and currency format changes.  The format controller presented by a TcxFormatController class instance notifies all registered listeners of date and currency format changes by calling the listener’s FormatChanged method.


cxFormatController
cxFormatController Function

Returns a global instance of the TcxFormatController class.

Unit

cxFormats

function cxFormatController: TcxFormatController;

Description

Use the cxFormatController function to get a global instance of the TcxFormatController class controlling the currency and date formats common to a number of editors.  Refer to the TcxFormatController and IcxFormatControllerListener topics for more information.


cxListView Unit Overview
cxListView Unit

Classes

TcxCustomListView

TcxListView


TcxCustomListView
TcxCustomListView Object

Hierarchy          Properties          Methods          Events

Serves as a base class for classes representing list view controls.

Unit

cxListView

TcxCustomListView = class(TcxContainer)

Description

The TcxCustomListView class implements the functionality of the list view control, which can display a list of items in various modes.

The following screenshot demonstrates an example of the list view control appearance:

Please refer to the Items property description for details on how to create the items structure.

Items of TcxCustomListView descendant controls are represented by TListItem objects.  Visually, items are comprised of text labels and images.  If such item representation doesn’t suit your application needs, you can paint items manually by handling the OnCustomDrawItem and OnAdvancedCustomDrawItem events.  Additionally you can create your own TListItem class descendant to represent items within the control.  You must handle the OnCreateItemClass event to perform the replacement.

In addition to painting individual items, you can paint the entire list view control manually.  This can be performed by handling the OnCustomDraw and OnAdvancedCustomDraw events.

The TcxListView control has three image lists containing images associated with the items.  The LargeImages and SmallImages properties contain images helping to understand the item contents.  The StateImages property contains images representing item states.

Two more significant features implemented by the TcxCustomListView class are multi selection of items and item sorting.  Please refer to the MultiSelect and SortType property descriptions for details.

Do not create instances of TcxCustomListView. Use it as a base class when implementing custom list views with some extra features and advanced functionality. If you need a list view control on your form, use the derived TcxListView, which publishes properties of the TcxCustomListView class.


TcxCustomListView Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |


Properties for TcxCustomListView
TcxCustomListView Properties

TcxCustomListView          Legend

In TcxCustomListView

AllocBy

ColumnClick

Columns

HideSelection

HotTrack

HoverTime

IconOptions

Items

LargeImages

MultiSelect

OwnerData

OwnerDraw

ReadOnly

ShowColumnHeaders

ShowWorkAreas

SmallImages

SortType

StateImages

ViewStyle

Derived from TcxContainer

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxCustomListView
TcxCustomListView Methods

TcxCustomListView          Legend

In TcxCustomListView

 AddItem

 AlphaSort

 Arrange

 Clear

 ClearSelection

 CopySelection

 CustomSort

 DeleteSelected

 FindCaption

 FindData

 GetHitTestInfoAt

 GetItemAt

 GetNearestItem

 GetNextItem

 GetSearchString

 IsEditing

 SelectAll

 StringWidth

 UpdateItems

Derived from TcxControl

 Create

 Destroy

 InvalidateRect


Events for TcxCustomListView
TcxCustomListView Events

TcxCustomListView          Legend

In TcxCustomListView

 OnAdvancedCustomDraw

 OnAdvancedCustomDrawItem

 OnAdvancedCustomDrawSubItem

 OnCancelEdit

 OnChange

 OnChanging

 OnColumnClick

 OnColumnDragged

 OnColumnRightClick

 OnCompare

 OnCreateItemClass

 OnCustomDraw

 OnCustomDrawItem

 OnCustomDrawSubItem

 OnData

 OnDataFind

 OnDataHint

 OnDataStateChange

 OnDeletion

 OnDrawItem

 OnEdited

 OnEditing

 OnGetImageIndex

 OnGetSubItemImage

 OnInfoTip

 OnInsert

 OnSelectItem


TcxCustomListView.AllocBy

TcxCustomListView

Indicates the number of items that can be stored by a list view.

property AllocBy: Integer;

Description

The AllocBy property defines the amount of memory the list view allocates to store the items. Before adding a large number of items, specify the number of items in the AllocBy property. This will allow the list view control to allocate the required memory as a single block rather than several smaller blocks. This will increase the performance of the list view.

The default value of the AllocBy property is 0.


TcxCustomListView.ColumnClick

TcxCustomListView          See Also          Example

Defines whether the column header acts like a button or not.

property ColumnClick: Boolean;

Description

Use the ColumnClick property to specify the behavior type of a list view header, which can be displayed at the top of a control. If ColumnClick is True, the header acts like a button - when the user clicks on a header, the OnColumnClick event occurs. You can handle this event to implement some specific reaction on header clicks.

If ColumnClick is False nothing happens to the header when the user clicks it. The OnColumnClick event is not fired.

Note: the column headers are visible within the list view control only if the ViewStyle is set to vsReport and the ShowColumnHeaders property is set to True. Otherwise changing of the ColumnClick property will have no effect.

The default value of the ColumnClick property is True.


TcxCustomListView.Columns

TcxCustomListView          See Also

Contains columns settings for a list view.

property Columns: TListColumns;

Description

The Columns property defines the columns that can be used to arrange elements when the vsReport ViewStyle is selected.

You can access the Columns property both at design and at run-time. At design time, click the ellipsis button in the Object Inspector beside the Columns property:

This invokes the Columns editor, which allows you to add, remove and edit columns:

You can customize the column’s Caption, ImageIndex, Width and several other properties in the Object Inspector:

Please take into account, that columns headers are visible only when the ShowColumnHeaders property is True. Even if it is False, the items still will be arranged into the columns you define.


TcxCustomListView.HideSelection

TcxCustomListView

Specifies whether selection is hidden when the list view looses focus.

property HideSelection: Boolean;

Description

The HideSelection property determines whether the selection mark is hidden within the list view when it loses focus.  When False, the selection mark remains in the control so that the selected element is highlighted. When True, the selection mark is removed from the control.

Note:	The HideSelection property affects the selection mark only.  The selected item remains the same.  Use the ClearSelection method to remove the selection from a list view.

The default value of the HideSelection property is True.


TcxCustomListView.HotTrack

TcxCustomListView          See Also

Determines whether the list view items can be hot-tracked.

property HotTrack: Boolean;

Description

Use the HotTrack property to determine whether the list view items can be hot-tracked.  When the mouse pointer hovers over the list view items and the HotTrack property is set to True, the items are hot-tracked.  The delay between positioning the mouse over the item and hot-tracking of that item is specified via the HoverTime property.

The following screenshot demonstrates the list view control.  The "Michael" item appears hot-tracked:

The next screenshot demonstrates the list view control with selected "Michael" item:

The default value of the HotTrack property is False.


TcxCustomListView.HoverTime

TcxCustomListView          See Also

Specifies how long the user must pause with the mouse before an item is selected.

property HoverTime: Integer;

Description

The HoverTime property defines the delay between the moment when the user puts the mouse cursor over the item and the moment, when this item becomes selected.  This property is not in effect when the HotTrack property is set to False.

If the HoverTime property is –1, the default Windows hover time is applied.

The default value of the HoverTime property is -1.


TcxCustomListView.IconOptions

TcxCustomListView          See Also

Contains the icon options for a list view.

property IconOptions: TIconOptions;

Description

The IconOptions property contains various options affecting icons within a list view.

The IconOptions.Arrangement property defines the manner in which the icons are aligned within a list view:

Value	Meaning
iaTop	Items are aligned left to right in rows at the top of the view control.
iaLeft	Items are aligned in columns top to bottom at the left of the view control.

IconOptions.AutoArrange property defines whether the list view icons are automatically rearranged when icons are added, moved or deleted within a list view.  If this property value is False, then icons are rearranged only after the call of the Arrange method.

IconOptions.WrapText property determines whether the text within the icon’s label is wrapped.

Note:	The IconOptions settings are in effect only if the ViewStyle is set to vsIcon or vsSmallIcon.


TcxCustomListView.Items

TcxCustomListView          See Also

Contains the list of items displayed in a list view.

property Items: TListItems;

Description

The Items property contains the elements that are displayed within the list view.  To edit Items at design-time press the ellipsis button beside the Items property in the Object Inspector:

This invokes the Items editor allowing you to add, edit, remove and configure the arrangement of the items that are displayed in the list view:

You can define items and sub items. Sub items appear in the secondary columns when the vsReport ViewStyle is selected. The following screenshot demonstrates the list view control with the Items structure, designed as demonstrated on the previous image:

In addition to the Caption property, which specified the item’s text label, you can configure the ImageIndex and StateIndex properties that specify the images assigned to the items. Please refer to the VCL reference for complete description of these properties.


TcxCustomListView.LargeImages

TcxCustomListView          See Also

Specifies the images that are associated with the list view items.

property LargeImages: TCustomImageList;

Description

The LargeImages property holds the collection of images that are associated with the list view items.   These images are displayed when the ViewStyle property is set to vsIcon.

Each item has the ImageIndex property.  This property identifies an image from the LargeImages and SmallImages lists, associated with an item.  If this property value is –1, then no image is associated with an item.

The following image demonstrates the list view control whose items have an image associated with them:


TcxCustomListView.MultiSelect

TcxCustomListView          See Also

Determines whether multiple items can be selected.

property MultiSelect: Boolean;

Description

Use the MultiSelect property to determine whether a user can select multiple items within the list view.

If this property is set to True, then a user can select multiple items by clicking the required items with Ctrl or Shift key pressed.

If this property is set to False, then multiple selections can be performed neither by an end user, nor by code.

The default value of the MultiSelect property is False.


TcxCustomListView.OwnerData

TcxCustomListView          See Also          Example

Specifies that the list view control functions in virtual mode.

property OwnerData: Boolean;

Description

Use the OwnerData property to specify that the list view control functions in virtual mode.

In this mode, the list view control can support huge number of items.  The number of items is specified by the Items.Count property.  The items in the virtual list view must be managed manually, by handling the OnData, OnDataFind, OnDataHint and OnDataStateChange events.

Virtual list view stores only the selection and focus positions.

See the example of using the cxListView in virtual mode.

The default value of the OwnerData property is False.


TcxCustomListView.OwnerDraw

TcxCustomListView          See Also

Specifies whether a list view receives the OnDrawItem event.

property OwnerDraw: Boolean;

Description

Use the OwnerDraw property to enable the cxListView control to receive the OnDrawItem event.  Handle this event if the custom painting of the list view items is required.

The difference between the OnDrawItem and the custom draw events (OnCustomDraw, OnCustomDrawItem, OnCustomDrawSubItem, OnAdvancedCustomDraw, OnAdvancedCustomDrawItem, OnAdvancedCustomDrawSubItem) is that the latter occur at more steps during the control painting and there is a slight difference in information provided on the drawn item state.

The default value of the OwnerDraw property is False.


TcxCustomListView.ReadOnly

TcxCustomListView          See Also

Determines whether a user can change the contents of the control.

property ReadOnly: Boolean;

Description

Use the ReadOnly property to enable or disable items editing within the list view. If ReadOnly is True, users are not allowed to edit data.

If False is assigned to the ReadOnly property, the OnEditing event occurs when the user begins editing the list item. The OnEdited event occurs when the user finishes editing.


TcxCustomListView.ShowColumnHeaders

TcxCustomListView          See Also

Toggles the visibility of the column headers.

property ShowColumnHeaders: Boolean;

Description

Use the ShowColumnHeader property to specify the column headers visibility. By default, the column headers are visible if the ViewStyle is set to vsReport.  If the ViewStyle is not vsReport, then the ShowColumnHeaders property is not in effect.

Property’s Value	Example
True
False

The default value of the ShowColumnHeaders property is True.


TcxCustomListView.ShowWorkAreas

TcxCustomListView

Determines whether the visual properties of work areas are displayed.

property ShowWorkAreas: Boolean;

Description

The ShowWorkAreas property specifies whether the list view should paint each work area in its own color and label it with its display name.  If the list view’s WorkAreas property includes any work areas, the icons in the list view are always grouped visually by these work areas.  The ShowWorkAreas property determines whether the properties of individual work area components are used to make each area stand out visually.

When the ShowWorkAreas property is set to True, each work area is painted in the color specified by its Color property and labeled by the string in its DisplayName property. When the ShowWorkAreas is set to False, icons appear grouped by work areas, but there is no other visual indication.

Note:	To use work areas in a list view, the ViewStyle property must be set to vsIcon or vsSmallIcon.

The default value of the ShowWorkAreas property is False.


TcxCustomListView.SmallImages

TcxCustomListView          See Also

Specifies the images that are displayed in the list view when the "icon" view style is selected.

property SmallImages: TCustomImageList;

Description

The SmallImages property holds the collection of images associated with the list view items.  Images from this collection are displayed beside the list view items if the ViewStyle is not vsIcon.

Each item has the ImageIndex property.  This property identifies an image from the LargeImages and SmallImages lists, associated with an item.  If this property value is –1, then no image is associated with an item.

The following screenshots demonstrate list view controls with ViewStyle set to vsList and vsSmallIcons correspondingly:


TcxCustomListView.SortType

TcxCustomListView          See Also

Specifies the sort type, applied to the items within the list view.

type

  TSortType = (stNone, stData, stText, stBoth);

property SortType: TSortType;

Description

The SortType property specifies how the items are sorted inside the list view. The following options are supported:

Value	Meaning
stNone	Specifies that sorting is not applied to items of the list view.  This means that the control will not automatically resort items until the SortType property is set to another value.  However, items can still be sorted programmatically by calling the AlphaSort or CustomSort method. Changing the SortType property to stNone when items are already sorted will not restore the original order of items
stText	Specifies that items of the list view are sorted by their captions in ascending order.  Each time the caption of an item is changed, items are resorted.  To toggle the sorting order, call the AlphaSort method. You can implement custom sorting logic by handling the OnCompare event.  In this case, the stText value merely implies that items need to be resorted each time a item caption changes.  Thus you must use this value if the sorting logic uses captions of items only (the Caption property) to perform item comparison.  The resulting sorting order depends on the OnCompare event handler implementation.
stData	Setting the SortType property doesn’t apply any predefined sorting order to items.  This value merely implies that items resorting must be invoked each time the value of a item’s Data property is changed.  The sorting logic must be implemented by handling the OnCompare event. Set the SortType property to the stData value if you implement sorting that is based on the Data property value of items and doesn’t depend on their Caption property value.  If the sorting algorithm uses both properties, set the SortType property to stBoth.
stBoth	This value implies that items sorting takes place each time the Caption or Data property of a item is changed.  The sorting logic must be implemented in the OnCompare event handler.  Use the stBoth value if your sorting algorithm uses both the Caption and Data properties of items to perform item comparing.  If only the Caption or Data property is used, set the SortType property to stText or stData respectively.
You may need to use a sorting procedure that uses custom item settings (other than the Caption or Data property) to perform sorting.  In this case, you must leave the SortType property set to stNone to disable automatic item resorting when changing the mentioned properties.  When settings used in your sorting algorithm are changed or items are added to the list view, you must manually call the AlphaSort method.


TcxCustomListView.StateImages

TcxCustomListView          See Also

Specifies the images associated with the list view items.

property StateImages: TCustomImageList;

Description

The StateImages property holds the collection of images associated with the list view items.

While the LargeImages and SmallImages image lists provide images explaining the item contents, the StateImages list provides images, indicating the item’s state.

Each item has the ImageIndex and StateIndex properties.  The ImageIndex property identifies an image from the LargeImages and SmallImages lists, associated with an item.  If this property value is –1, then no image is associated with an item.  The StateIndex property specifies an image from the StateImages list, associated with an item.


TcxCustomListView.ViewStyle

TcxCustomListView          See Also

Defines the manner in which the list view items are displayed.

type

  TViewStyle = (vsIcon, vsSmallIcon, vsList, vsReport);

property ViewStyle: TViewStyle;

Description

The ViewStyle property specifies the style, which is used for displaying of the list view items. The following view styles are supported:

Property’s Value	Meaning	Effect
vsIcon	The items are displayed as the large icons with a text label next to each. The icon bitmaps are specified by the TcxCustomListView.LargeImages property.
vsSmallIcons	The items are displayed as the small icons with a text label next to each. The icon bitmaps are specified by the TcxCustomListView.SmallImages property.
vsList	The items are arranged into columns. Option icons can be specified by the TcxCustomListView.SmallImages property.
vsReport	The items are arranged into columns.  Each item has additional information associated with it (see the Item.SubItems property description).  Each column has a header (unless the ShowColumnHeaders property is False).

The default value of the ViewStyle property is vsIcon.


TcxCustomListView.AddItem

TcxCustomListView          See Also

Adds an item into the list view.

procedure AddItem(Item: string; AObject: TObject);

Description

Use the AddItem method to add a new item into the list view.

The AItem parameter specifies the caption of the item displayed within the list view.  The AObject parameter contains an object representing the Data property value of the added item.  This property value can be used as the sorting criterion (see the SortType and AlphaSort members descriptions for details).


TcxCustomListView.AlphaSort

TcxCustomListView          See Also          Example

Sorts the list view items.

function AlphaSort: Boolean;

Description

Call the AlphaSort method to sort items within the list view control.  By default, the method sorts items by their captions.  If items are not currently sorted, the ascending sort order is applied.  If the items are already sorted, the AlphaSort method toggles the sort order.

If the OnCompare event handler is written, it is used to compare items when sorting using the AlphaSort method.  This enables you to implement custom algorithms of items sorting.

Note that calling the AlphaSort method is equivalent to calling the CustomSort method with the first parameter set to nil.  Actually, the AlphaSort simply calls that method to perform its task.

Note that the AlphaSort method is used when the control performs automatic items sorting.  This takes place when the SortType property of the control is set to a value different from stNone.  If the SortType property is set to stText, the AlphaSort method is automatically called each time the Caption property of any item changes.  If the SortType property is set to stData, these methods are called each time the Data property of items is changed.  Finally, setting the SortType property to stBoth forces the control to call these methods when either the Caption or Data property of items are changed.


TcxCustomListView.Arrange

TcxCustomListView          See Also

Arranges the icons in a list view.

type

  TListArrangement = (arAlignBottom, arAlignLeft, arAlignRight, arAlignTop, arDefault, arSnapToGrid);

procedure Arrange(Code: TListArrangement);

Description

The Arrange method arranges the icons within the list view.  This method is in effect only when the ViewStyle is vslcon or vsSmallIcon.

The Code parameter specifies the arrangement style:

Value	Meaning
arAlignBottom	Aligns items along the bottom edge of the list view.
arAlignLeft	Aligns items along the left edge of the list view.
arAlignRight	Aligns items along the right edge of the list view.
arAlignTop	Aligns items along the top edge of the lit view.
arDefault	Aligns items according to the style associated with the list view when the list view was created.
arSnapToGrid	Snaps all icons to the nearest grid position. This value is not supported if the application is running in virtual mode.


TcxCustomListView.Clear

TcxCustomListView

Removes all items from a list view.

procedure Clear;

Description

Call Clear if you wish, for some reason, to remove all items from the list view. The Items property appears empty after this method is executed.


TcxCustomListView.ClearSelection

TcxCustomListView          See Also

Removes the selection mark from a list view.

procedure ClearSelection;

Description

Call ClearSelection to remove a selection mark from the list view. Nothing happens to the selected item. This method affects only the selection mark.

The below images show the way in which the ClearSelection method works:


TcxCustomListView.CopySelection

TcxCustomListView          See Also

Copies the selection from one list view to another.

procedure CopySelection(Destination: TCustomListControl);

Description

Use CopySelection to duplicate the selection from the current list view to another one, which is specified by the Destination parameter.

The following code demonstrates using of this method:

cxListView1.CopySelection(TCustomListControl(cxListView2.InnerListView));

Note:	This method creates copies of the selected items in the Items collection of the destination list view.  If that list view control has no associated image lists (see the LargeImages, SmallImages and StateImages properties), then the copied items will have no associated images.


TcxCustomListView.CustomSort

TcxCustomListView          See Also

Sorts items using the specified item comparing routine.

{$IFNDEF CLR}

type

  TTVCompare = function(lParam1, lParam2, lParamSort: Longint): Integer stdcall;

function TcxCustomTreeView.CustomSort(SortProc: TTVCompare; Data: Longint; ARecurse: Boolean = True): Boolean;

{$ELSE}

type

  TTVCompareProc = function(lParam1, lParam2: TTreeNode; lParamSort: TTag): Integer;

function TcxCustomTreeView.CustomSort(SortProc: TTVCompareProc; Data: TTag; ARecurse: Boolean = True): Boolean;

{$ENDIF}

Description

The CustomSort method is used to perform item sorting using the comparison routine specified by the SortProc parameter.  If nil is passed as the SortProc parameter, the method behaves as the AlphaSort method.  Please refer to the TCustomListView.CustomSort method description for details on using the CustomSort method.

It is not recommended to use the CustomSort method.  Instead, call the AlphaSort method and handle the OnCompare event to specify the items comparing logic.  If the OnCompare event is not handled, the AlphaSort method compares items by their captions (the Caption property of TListItem objects representing items).


TcxCustomListView.DeleteSelected

TcxCustomListView

Removes the selected items from a list view.

procedure DeleteSelected;

Description

Call DeleteSelected to remove all selected items from the list view control.  If the MultiSelect property value is True and several items are selected, the DeleteSelected method removes all selected items.


TcxCustomListView.FindCaption

TcxCustomListView          See Also

Returns the item by the specified caption.

function FindCaption(StartIndex: Integer; Value: string; Partial, Inclusive, Wrap: Boolean): TListItem;

Description

The FindCaption method searched the Items of the list view control for an element with the specified caption. The parameters passed the FindCaption method specify the search options:

Parameter	Meaning
StartIndex	The index of the item, from which to begin search.
Value	The string to search for (the search criteria)
Partial	If True, the Caption matches if it starts with the substring Value. If False, the Caption must match Value exactly.
Inclusive	If True, the item, specified by the StartIndex parameter, is included into the search.
Wrap	If True, the search continues at the top of the list if a match has not been found before reaching the bottom.
The FindCaption method returns the first located item.  If no item is found, the FindCaption returns nil.


TcxCustomListView.FindData

TcxCustomListView          See Also

Returns a list view item, which is associated with the specified data.

function FindData(StartIndex: Integer; Value: Pointer; Inclusive, Wrap: Boolean): TListItem;

Description

The FindData method searches the Items of a list view for an element, whose Data property value matches the search criteria by data. The parameters passed the FindData method specify the search options:

Parameter	Meaning
StartIndex	The index of the item, from which to begin search.
Value	The data to search for (the search criteria)
Inclusive	If True, the item, specified by the StartIndex parameter, is included into the search.
Wrap	If True, the search continues at the top of the list if a match has not been found before reaching the bottom.

The FindData method returns the first item whose Data property matches the Value parameter.  If no item is found the FindData returns nil.


TcxCustomListView.GetHitTestInfoAt

TcxCustomListView          See Also

Determines the elements of the control located under the specified point.

type

  THitTest = (htAbove, htBelow, htNowhere, htOnItem, htOnButton, htOnIcon, htOnIndent, htOnLabel, htOnRight, htOnStateIcon, htToLeft, htToRight);

  THitTests = set of THitTest;

function GetHitTestInfoAt(X, Y: Integer): THitTests;

Description

Use the GetHitTestInfoAt method to determine the element of the control located under the specified point.  The point is specified by its horizontal and vertical coordinates using the X and Y method parameters.  Note that coordinates must be set in the control’s client coordinates.  Thus, if you have screen coordinates of the point, use the control’s ScreenToClient method to obtain client coordinates.

The following code handles the TcxListView.OnClick event to change the images, displayed next to the list view items.  If a user clicks a list view, then the item’s state image is replaced with a check mark:

//Delphi

procedure TForm1.cxListView1Click(Sender: TObject);

var

  MousePos: TPoint;

  AItem: TListItem;

begin

  MousePos := Mouse.CursorPos;

  MousePos := cxListView1.ScreenToClient(MousePos);

  AItem := cxListView1.GetItemAt(MousePos.X, MousePos.Y);

  if AItem <> nil then

  begin

    if htOnIcon in cxListView1.GetHitTestInfoAt(MousePos.X, MousePos.Y) then

    begin

      if AItem.StateIndex <> 3 then

      AItem.StateIndex := 3

    end;

  end;

end;

The result of the code execution is demonstrated below:


TcxCustomListView.GetItemAt

TcxCustomListView          See Also

Returns the item by the specified location.

function GetItemAt(X, Y: Integer): TListItem;

Description

Use the GetItemAt method to obtain the TListItem object representing the item located under the specified point.  The point is specified by its horizontal and vertical coordinates via the X and Y parameters respectively.  Note that the control’s client coordinates must be specified.  If you have screen coordinates, you should use the ScreenToClient method of the control to obtain client coordinates.

See the GetHitTestInfoAt method description for the example of using the GetItemAt method.


TcxCustomListView.GetNearestItem

TcxCustomListView          See Also

Returns the item nearest item to the specified location in the list view.

type

  TSearchDirection = (sdLeft, sdRight, sdAbove, sdBelow, or sdAll);

function GetNearestItem(Point: TPoint; Direction: TSearchDirection): TListItem;

Description

The GetNearestItem method searched for an item in the list view. The search begins from the location, which is specified by the Point parameter. The search direction is specified by the Direction parameter.

The Direction parameter can take the following values:

Value	Meaning
sdLeft	Look to the left of a specified item.
sdRight	Look to the right of a specified item.
sdAbove	Look above a specified item.
sdBelow	Look below a specified item.
sdAll	Look in the order that items appear in the Items property.


TcxCustomListView.GetNextItem

TcxCustomListView          See Also

Searches for the item next to the specified one in the list view.

type

  TItemState = (isNone, isCut, isDropHilited, isFocused, isSelected, isActivating);

  TItemStates = set of TItemState;

  TSearchDirection = (sdLeft, sdRight, sdAbove, sdBelow, or sdAll);

function GetNextItem(StartItem: TListItem; Direction: TSearchDirection; States: TItemStates): TListItem;

Description

The GetNextItem method searches for the item in the list view, which is located next to the specified one. The following parameters are required:

•	The StartItem parameter identifies an item to search from.

•	The Direction parameter specifies the search direction.  All the possible values of the Direction parameter are listed in the following table:

Value	Meaning
sdLeft	Look to the left of a specified item.
sdRight	Look to the right of a specified item.
sdAbove	Look above a specified item.
sdBelow	Look below a specified item.
sdAll	Look in the order that items appear in the Items property.
•	The States parameter – only items in the specified states are considered.  Can take the following values:

Value	Meaning
IsNone	Item is in its default state.
isCut	Item is cut (for cut and paste operation).
isDropHilited	Item is highlighted as a drag-and-drop target.
isFocused	Item is focused.
isSelected	Item is selected.
isActivating	Item is active.


TcxCustomListView.GetSearchString

TcxCustomListView

Returns the incremental search string of a list view control.

function GetSearchString: string;

Description

The GetSearchString returns the sequence of characters typed by the user when he or she performs the quick search by typing the name of the item to locate. Each time the user types a character, it is added to the search string. A timeout period of less than a second is associated with each character that the user types. If the timeout period elapses before the user types another character, the search string is reset. If the system finds a match, it selects the item and, if necessary, scrolls it into view.


TcxCustomListView.IsEditing

TcxCustomListView

Indicates whether any item in the list view is being edited.

function IsEditing: Boolean;

Description

Use the IsEditing method to determine whether the user is currently editing the item’s caption.  If so, the method returns True.  Otherwise, False is returned.  Note that item editing is only allowed if the ReadOnly property of the list view is set to False.


TcxCustomListView.SelectAll

TcxCustomListView          See Also

Selects all items in the list view area.

procedure SelectAll;

Description

Call the SelectAll method to select all items within a list view.  This method is not in effect if the MultiSelect property is set to False.


TcxCustomListView.StringWidth

TcxCustomListView

Returns the width of the string in pixels.

function StringWidth(S: string): Integer;

Description

Call the StringWidth method to calculate the width of the specified string in pixels as it is drawn with the current font, selected in the list view control. You may use this method to determine whether the string will fit the client area or not without scrolling.  The string to measure is specified by the S parameter.


TcxCustomListView.UpdateItems

TcxCustomListView

Redraws a range of items.

procedure UpdateItems(FirstIndex, LastIndex: Integer);

Description

Call the UpdateItems to redraw the items in the list view control.

The parameters of this method specify the range of items to redraw.


TcxCustomListView.OnAdvancedCustomDraw

TcxCustomListView          See Also

Enables you to paint the list view control (or a part of it) before or after default painting takes place.

type

  TLVAdvancedCustomDrawEvent = procedure(Sender: TCustomListView; const ARect: TRect; Stage: TCustomDrawStage; var DefaultDraw: Boolean) of object;

property OnAdvancedCustomDraw: TLVAdvancedCustomDrawEvent;

Description

The OnAdvancedCustomDraw event fires at different stages of control painting.  First it fires before any default painting is performed.  Then it fires after all painting is finished.  Use the Stage parameter to determine the stage of painting.  It returns the cdPrePaint value if the event fires before any other painting.  If the cdPostPaint value is returned, all painting procedures have already been finished.  Note that the Stage parameter cannot return any other values listed by the TCustomDrawState enumeration.

The DefaultDraw parameter specifies whether default painting must proceed after the OnAdvancedCustomDraw event is executed.  If handling the event when the Stage parameter is cdPrePaint, setting the DefaultDraw parameter to True prohibits all further painting.  This means that items of the control will not be painted.  You cannot paint them manually also in this case, since the OnCustomDrawItem and OnAdvancedCustomDrawItem events will not fire.  Thus, you need to set the DefaultDraw parameter to True only when all the desired painting is performed in the OnAdvancedCustomDraw event and no further painting is needed.

When the Stage parameter returns the cdPostPaint value, the DefaultDraw parameter should not be used.  No painting will take place afterwards anyway.

Note:	If you need to perform only background painting (when the Stage parameter value is cdPrePaint), handle the OnCustomDraw event.  This event fires twice as little times as the OnAdvancedCustomDraw event, which gives you a performance benefit.

The Sender parameter of the event provides access to the underlying list view control.  Use the Canvas property of the object representing this parameter to obtain the canvas used to paint.  The bounding rectangle of the control can be obtained using the ARect parameter.

The following sample code shows how to perform painting when all default painting routines are finished.  The code handles the OnAdvancedCustomDraw event to paint a red cross over the control’s client area.

//Delphi

procedure TForm1.cxListView1AdvancedCustomDraw(Sender: TCustomListView; const ARect: TRect; Stage: TCustomDrawStage; var DefaultDraw: Boolean);

begin

  if Stage = cdPostPaint then

  begin

    with Sender.Canvas do

    begin

      Pen.Color := clRed;

      Pen.Style := psSolid;

      Pen.Width := 3;

      MoveTo(ARect.Left, ARect.Top);

      LineTo(ARect.Right, ARect.Bottom);

      MoveTo(ARect.Left, ARect.Bottom);

      LineTo(ARect.Right, ARect.Top);

    end;

  end;

end;

The result of the code execution is demonstrated below:


TcxCustomListView.OnAdvancedCustomDrawItem

TcxCustomListView          See Also

Enables you to paint items of the list view control before or after default painting takes place.

type

  TLVAdvancedCustomDrawItemEvent = procedure(Sender: TCustomListView; Item: TListItem; State: TCustomDrawState; Stage: TCustomDrawStage; var DefaultDraw: Boolean) of object;

property OnAdvancedCustomDrawItem: TLVAdvancedCustomDrawItemEvent;

Description

The OnAdvancedCustomDrawItem event fires for each individual item of the control before and after its default painting takes place.  The Stage parameter enables you to identify whether item painting is about to be performed or has been completed.

If the Stage parameter returns the cdPrePaint value, item painting has not been performed yet.  In this case you may perform your own painting of the processed item and set the DefaultDraw parameter to False.  This value of the DefaultDraw parameter implies that default painting of the processed item will not be performed.  Note that if you only need to perform painting before the default drawing routine is executed, you should handle the OnCustomDrawItem event instead.  This event fires twice as little times as the OnAdvancedCustomDrawItem event, which results in a performance benefit.

If the Stage parameter returns the cdPostPaint value, item painting has already been finished.  At this time, you may perform any additional painting you like.  For instance, you can paint a stop sign over the item’s image.  Note that the DefaultDraw parameter is not in effect when the Stage parameter value is cdPostPaint.  The reason is that no other painting will take place further anyway.

The Sender parameter of the event specifies the control whose item is being painted.  Use the Canvas property of the object representing this parameter to obtain the canvas used to paint.  The Item parameter enables you to determine the currently processed item.  Use it to get the bounding rectangle of the item (the DisplayRect method) and other information needed when painting (caption text, image indexes, etc).  The State parameter can be used to determine the state of the painted item.  The cdsSelected and cdsHot values included into this parameter’s value indicate that the item is selected or hot-tracked respectively.


TcxCustomListView.OnAdvancedCustomDrawSubItem

TcxCustomListView          See Also

Occurs during the painting of the list view sub-items in an owner-draw list view.

type

  TLVAdvancedCustomDrawSubItemEvent = procedure(Sender: TCustomListView; Item: TListItem; SubItem: Integer; State, Stage: TCustomDrawState; var DefaultDraw: Boolean) of object;

property OnAdvancedCustomDrawSubItem: TLVAdvancedCustomDrawSubItemEvent;

Description

The OnAdvancedCustomDrawSubItem event fires for each individual sub-item of the control’s items before and after its default painting takes place.  The Stage parameter enables you to identify whether item painting is about to be performed or has been completed.

If the Stage parameter returns the cdPrePaint value, sub-item painting has not been performed yet.  In this case, you may perform your own painting of the processed item and its sub-items and set the DefaultDraw parameter to False.  This value of the DefaultDraw parameter implies that default painting of the processed item will not be performed.  Note that if you only need to perform painting before the default drawing routine is executed, you should handle the OnCustomDrawItem event instead.  This event fires twice as little times as the OnAdvancedCustomDrawItem event, which results in a performance benefit.

If the Stage parameter returns the cdPostPaint value, sub-item painting has already been finished.  At this time, you may perform any additional painting you like.  Note that the DefaultDraw parameter is not in effect when the Stage parameter value is cdPostPaint.  The reason is that no other painting will take place further anyway.

The Sender parameter of the event specifies the control whose sub-item is being painted.  Use the Canvas property of the object representing this parameter to obtain the canvas used to paint.  The Item parameter enables you to determine the currently processed item.  Use it to get the bounding rectangle of the item (the DisplayRect method) and other information needed when painting (caption text, image indexes, etc).  The State parameter can be used to determine the state of the painted item.  The cdsSelected and cdsHot values included into this parameter’s value indicate that the item is selected or hot-tracked respectively.

The following code handles the OnAdvancedCustomDrawSubItem event.  It paints the background of sub-items’ text labels with textures of different colors.  The custom font settings are applied also:

//Delphi

procedure TForm1.cxListView1AdvancedCustomDrawSubItem(

Sender: TCustomListView; Item: TListItem; SubItem: Integer;

State: TCustomDrawState; Stage: TCustomDrawStage;

var DefaultDraw: Boolean);

var

  ACanvas: TCanvas;

  ARect, ALabelRect, ASubRect: TRect;

  AOddPicture, AEvenPicture: TBitmap;

  ALeft, ATop, AWidth, AHeight: Integer;

begin

//loading the required bitmaps from files

  AOddPicture := TBitmap.Create;

  AEvenPicture := TBitmap.Create;

  AOddPicture.LoadFromFile('C:\IMAGES\BLUE.BMP');

  AEvenPicture.LoadFromFile('C:\IMAGES\RED.BMP');

  ACanvas := Sender.Canvas;

//ARect contains a rectangle representing the whole item area, including all subitems

  ARect := Item.DisplayRect(drBounds);

//ALabelRect contains a rectangle representing the text label of an item

  ALabelRect := Item.DisplayRect(drLabel);

//obtaining the subitem bounding rectangle

  ALeft := ALabelRect.Right;

  ATop := ARect.Top;

  AWidth := ARect.Right - ALabelRect.Right;

  AHeight := ARect.Bottom - ARect.Top;

  ASubRect := Bounds(Aleft, ATop, AWidth, AHeight);

//

  if Stage = cdPrePaint then

  begin

//background of subitems within odd rows is filled with blue texture

    if Odd(Item.Index) then ACanvas.StretchDraw(ASubRect, AOddPicture)

    else

//background of subitems within even rows is filled with red texture

      if not Odd(Item.Index) then ACanvas.StretchDraw(ASubRect, AEvenPicture);

//applying font settings for subitems: transparent background, white color and bold style

    SetBkMode(ACanvas.Handle, TRANSPARENT);

    SetTextColor(ACanvas.Handle, clWhite);

    ACanvas.Font.Style := [fsBold];

//selecting the prepared font object

    SelectObject(ACanvas.Handle, ACanvas.Font.Handle);

//drawing the subitem text using the prepared font settings

    ACanvas.TextOut(ASubRect.Left + 1, ASubRect.Top + 1, Item.SubItems[SubItem - 1]);

  end;

  AOddPicture.Free;

  AEvenPicture.Free;

end;

The following image demonstrates the result of the code execution:


TcxCustomListView.OnCancelEdit

TcxCustomListView          See Also          Example

Occurs when a user cancel item editing.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnCancelEdit: TNotifyEvent;

Description

The OnCancelEdit event occurs when a user cancel item editing.  Item editing is canceled when the Esc key is pressed or focus leaves the edited item.

Handle the OnEdited and OnEditing events in order to respond to the successful item editing.

See the example demonstrating handling of the events, listed above.


TcxCustomListView.OnChange

TcxCustomListView          See Also

Occurs after a list view item had been changed.

type

  TLVChangeEvent = procedure(Sender: TObject; Item: TListItem; Change: TItemChange) of object;

property OnChange: TLVChangeEvent;

Description

Handle the OnChange event if you wish to implement some specific action to react to changes of the items.  The Sender parameter identifies a cxListView control, which receives the event.  The Item parameter represents the changed item.  The Change contains information about the type of the change performed.


TcxCustomListView.OnChanging

TcxCustomListView

Occurs before the item in the list view is about to be changed.

type

  TLVChangingEvent = procedure(Sender: TObject; Item: TListItem; Change: TItemChange; var AllowChange: Boolean) of object;

property OnChanging: TLVChangingEvent;

Description

Handle the OnChanging event if you wish to implement some specific action before the item is changed. By applying an appropriate handler if may, for example, prevent some particular items from changing but allow others to be changed.

The following code demonstrates the OnChanging event handler.  This handler checks whether the item’s caption is edited within a list view and restricts editing if the index of the edited item is 2:

//Delphi

procedure TForm1.cxListView1Changing(Sender: TObject; Item: TListItem;

Change: TItemChange; var AllowChange: Boolean);

begin

  if cxListView1.IsEditing then

    if (Item.Index = 2) and (Change = ctText) then AllowChange := False;

end;


TcxCustomListView.OnColumnClick

TcxCustomListView          See Also          Example

Occurs when the user clicks the column header.

type

  TLVColumnClickEvent = procedure(Sender: TObject; Column: TListColumn) of object;

property OnColumnClick: TLVColumnClickEvent;

Description

The OnColumnClick event is fired when the user clicks the column header within the list view.  Column headers are visible when the ViewStyle is vsReport and the ShowColumnHeader property is True.  See the example of using the OnColumnClick event handler.

The Sender parameter identifies a list view, which receives the event.  The Column is the item in Columns, which was clicked by a user.


TcxCustomListView.OnColumnDragged

TcxCustomListView          See Also

Occurs when the user drags a column.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnColumnDragged: TNotifyEvent;

Description

Handle the OnColumnDragged event to respond when the user drags a column to a new position. OnColumnDragged occurs after all columns are in their new positions but before the list view repaints to reflect the change.

OnColumnDragged only occurs when ViewStyle is vsReport and ShowColumnHeaders is True.


TcxCustomListView.OnColumnRightClick

TcxCustomListView          See Also

Occurs when a user right clicks the column header.

type

  TLVColumnRClickEvent = procedure(Sender: TObject; Column: TListColumn; Point: TPoint) of object;

property OnColumnRightClick: TLVColumnRClickEvent;

Description

The OnColumnRightClick event is fired when the user right clicks the column header, which is visible when the ViewStyle is vsReport and the ShowColumnHeader property is True.

The Sender parameter identifies a list view, which receives the event.  The Column parameter specifies the clicked column.  The Point parameter specifies the client coordinates, where clicking occurred.


TcxCustomListView.OnCompare

TcxCustomListView          See Also          Example

Fires during the sorting process to compare two items.

type

  TLVCompareEvent = procedure(Sender: TObject; Item1, Item2: TListItem; Data: Integer; var Compare: Integer) of object;

property OnCompare: TLVCompareEvent;

Description

You can force item sorting by calling the AlphaSort method of the control.  Also, you can force the control to resort the list automatically each time the Caption or Data property of a item is changed.  Set the SortType property to the appropriate value for this purpose.

By default, the control sorts items alphabetically by their captions.  However, if a handler for the OnCompare event is written, the control uses the handler to compare items.  Thus, you may implement any sorting logic you need.

The Sender parameter of the event is the control whose items are sorted.  The Item1 and Item2 parameters identify the items to be compared.  Use their properties to determine which of them should reside first within the sorted list.  The result of comparing must to specified using the Compare parameter.  The table below explains what values must be assigned to it.

Value	Meaning
Negative	Item1 is less than Item2.  This means that the item specified by the Item1 parameter will reside above the item specified by the Item2 parameter.
0	Item1 is equal to Item2.
Positive	Item1 is greater than Item2.  This means that the item specified by the Item1 parameter will reside below the item specified by the Item2 parameter.


TcxCustomListView.OnCreateItemClass

TcxCustomListView

Enables you to supply items of a custom type to the list view control.

type

  TLVCreateItemClassEvent = procedure(Sender: TCustomListView; var ItemClass: TListItemClass) of object;

property OnCreateItemClass: TLVCreateItemClassEvent;

Description

The OnCreateItemClass event fires before a item is added to the control.  For instance, it is raised when calling the AddItem method.  You can handle this event to specify the type of the object that will represent the added item.  The type must be a TListItem descendant.

The Sender parameter of the event specifies the control to which a item is about to be added.  The class of the item to be added must be assigned to the ItemClass parameter of the event.

Handle the OnCreateItemClass event if you need additional item settings as compared to the TListItem class.  For instance, you may want to specify different font style for each item and use them when handling the OnCustomDrawItem event.


TcxCustomListView.OnCustomDraw

TcxCustomListView          See Also

Enables you to paint the list view control in a custom manner.

type

  TLVCustomDrawEvent = procedure(Sender: TCustomListView; const ARect: TRect; var DefaultDraw: Boolean) of object;

property OnCustomDraw: TLVCustomDrawEvent;

Description

The OnCustomDraw event occurs each time the control needs to be repainted, but before the default painting is made.  The Sender parameter specifies the control which is painted.  Use the Canvas property of the object representing it to obtain the canvas used to paint.  The ARect parameter returns the bounding rectangle of the control so that you know where to paint.

The DefaultDraw parameter of the event specifies whether further painting must be performed by the control.  Set this parameter to False if all the desired painting is performed within the OnCustomDraw event handler.  In this case, the control will not paint items.  The OnCustomDrawItem and OnAdvancedCustomDrawItem events will not be raised also.  However, if you need to perform custom painting of the control’s background only, set the DefaultDraw parameter to True.

Note that you can also perform painting of the control’s foreground.  Please refer to the OnAdvancedCustomDraw event description for details on performing this.

The following sample code handles the OnCustomDraw event to fill the background of the list view with a texture.  The DefaultDraw parameter is not set to False to allow item painting.

procedure TForm1.cxListView1CustomDraw(Sender: TCustomListView;

  const ARect: TRect; var DefaultDraw: Boolean);

var

  ABitmap: TBitmap;

  ABrush: HBRUSH;

begin

  ABitmap := TBitmap.Create;

  ABitmap.LoadFromFile('C:\IMAGES\lightblue.BMP');

  ABrush := CreatePatternBrush(ABitmap.Handle);

  FillRect(Sender.Canvas.Handle, ARect, ABrush);

  SetBkMode(Sender.Canvas.Handle, TRANSPARENT);

  ABitmap.Free;

end;

The following image demonstrates the result of the code execution:


TcxCustomListView.OnCustomDrawItem

TcxCustomListView          See Also

Occurs when an item in a list view is rendered.

type

  TLVCustomDrawItemEvent = procedure(Sender: TCustomListView; Item: TListItem; State: TCustomDrawState; var DefaultDraw: Boolean) of object;

property OnCustomDrawItem: TLVCustomDrawItemEvent;

Description

The OnAdvancedCustomDrawItem event fires for each individual item of the control before its default painting takes place.

The Sender parameter of the event specifies the control whose item is being painted.  Use the Canvas property of the object representing this parameter to obtain the canvas used to paint.  The Item parameter enables you to determine the currently processed item.  Use it to get the bounding rectangle of the item (the DisplayRect method) and other information needed when painting (caption text, image indexes, etc).  The State parameter can be used to determine the state of the painted item.  The cdsSelected and cdsHot values included into this parameter’s value indicate that the item is selected or hot-tracked respectively.

The following code paints the label background for the items using the texture, loaded from a bitmap.  Note, that two different textures are used according to the item’s selection state:

procedure TForm1.cxListView1CustomDrawItem(Sender: TCustomListView; Item: TListItem; State: TCustomDrawState; var DefaultDraw: Boolean);

var

  ASelectedBitmap, ABitmap: TBitmap;

  ARect: TRect;

  ABrush: HBRUSH;

begin

  ASelectedBitmap := TBitmap.Create;

  ABitmap := TBitmap.Create;

  ASelectedBitmap.LoadFromFile('C:\IMAGES\red.BMP');

  ABitmap.LoadFromFile('C:\IMAGES\blue.BMP');

  ARect := Item.DisplayRect(drLabel);

  if cdsSelected in State then

    ABrush := CreatePatternBrush(ASelectedBitmap.Handle)

  else

    ABrush := CreatePatternBrush(ABitmap.Handle);

  FillRect(Sender.Canvas.Handle, ARect, ABrush);

  SetBkMode(Sender.Canvas.Handle, TRANSPARENT);

  SetTextColor(Sender.Canvas.Handle, clWhite);

  SelectObject(Sender.Canvas.Handle, Sender.Canvas.Font.Handle);

  Sender.Canvas.TextOut(ARect.Left + 1, ARect.Top + 1, Item.Caption);

  ABitmap.Free;

  ASelectedBitmap.Free;

  DefaultDraw := True;

end;

The following image demonstrates the result of the code execution:


TcxCustomListView.OnCustomDrawSubItem

TcxCustomListView          See Also

Occurs when a sub-item in an owner-draw list view must be rendered.

type

  TLVCustomDrawSubItemEvent = procedure(Sender: TCustomListView; Item: TListItem; SubItem: Integer; State: TCustomDrawState; var DefaultDraw: Boolean) of object;

property OnCustomDrawSubItem: TLVCustomDrawSubItemEvent;

Description

The OnAdvancedCustomDrawSubItem event fires for each individual sub-item of the control’s items before its default painting takes place.

The Sender parameter of the event specifies the control whose sub-item is being painted.  Use the Canvas property of the object representing this parameter to obtain the canvas used to paint.  The Item parameter enables you to determine the currently processed item.  Use it to get the bounding rectangle of the item (the DisplayRect method) and other information needed when painting (caption text, image indexes, etc).  The State parameter can be used to determine the state of the painted item.  The cdsSelected and cdsHot values included into this parameter’s value indicate that the item is selected or hot-tracked respectively.


TcxCustomListView.OnData

TcxCustomListView          See Also          Example

Occurs before the item is displayed within a list view.

type

  TLVOwnerDataEvent = procedure(Sender: TObject; Item: TListItem) of object;

property OnData: TLVOwnerDataEvent;

Description

The OnData event occurs only if the OwnerData property is True.  If so, then the list view control functions in virtual mode.  In this mode, the list view control can support huge number of items.  The number of items is specified by the Items.Count property.

The OnData event can be used to customize the properties of an item before it is displayed.  If this event is not handled (i.e. item settings are not customized), then the list view control does not display anything.

The Sender parameter identifies the TcxListView control, whose item is about to be displayed.  The Item specifies the list view item, which is about to be displayed within the TcxListView control.

See the example of using the OnData event handler.


TcxCustomListView.OnDataFind

TcxCustomListView          See Also          Example

Occurs when the search operation is performed within the TcxListView control.

type

  TSearchDirection = (sdLeft, sdRight, sdAbove, sdBelow, or sdAll);

  TItemFind = (ifData, ifPartialString, ifExactString, ifNearest);

  TLVOwnerDataFindEvent = procedure(Sender: TObject; Find: TItemFind; const FindString: string; const FindPosition: TPoint; FindData: Pointer; StartIndex: Integer; Direction: TSearchDirection; Wrap: Boolean; var Index: Integer) of object;

property OnDataFind: TLVOwnerDataFindEvent;

Description

The OnDataFind event occurs when the FindData and FindCaption methods are performed.  Actually, this event fires each time a user presses a key when the list view control has focus.

Parameter	Meaning
Sender	The list view control, which fires the event.
Find	The type of search to perform. For more details, refer to the description of the TItemFind type in the VCL reference.
FindString	The string to search for.
FindPosition	The starting position for the search.
FindData	The data to search for.
StartIndex	The index of the item from which the search should start.
Direction	The search direction. This parameter is in effect only if the Find parameter value is ifNearest.  For more details, please refer to the description of the TSearchDirection type in the VCL reference.
Wrap	Determines whether the search should continue from the start of the list view control if no match is found.
Index	The var parameter, in which you should store the found item. If no item found, assign –1 to Index.
See the example of using the OnDataFind event handler.


TcxCustomListView.OnDataHint

TcxCustomListView          See Also

Occurs when the range of items needs to be updated.

type

  TLVOwnerDataHintEvent = procedure(Sender: TObject; StartIndex, EndIndex: Integer) of object;

property OnDataHint: TLVOwnerDataHintEvent;

Description

The OnDataHint event occurs when the range of items needs to be updated.  It occurs before the OnData event.  Handle this event in order to update the specified range of items (e.g. when the user resizes the control client area or scrolls). This method of updating items is more efficient than handling the OnData event to update all list view items.

The Sender parameter identifies the list view control, which fires the event.  The StartIndex and EndIndex parameters specify the range of items.


TcxCustomListView.OnDataStateChange

TcxCustomListView          See Also

Occurs when a dataset, with which the list view is associated, changes.

type

  TItemState = (isNone, isCut, isDropHilited, isFocused, isSelected, isActivating);

  TItemStates = set of TItemState;

  TLVOwnerDataStateChangeEvent = procedure(Sender: TObject; StartIndex, EndIndex: Integer; OldState, NewState: TItemStates) of object;

property OnDataStateChange: TLVOwnerDataStateChangeEvent;

Description

The OnDataStateChange event is fired automatically in response to changes within the list view control.

Parameter	Meaning
Sender	The list view control, which fires the event.
StartIndex	The index of the first item that has changed.
EndIndex	The index of the last item that has changed.
OldState	The old state of the items.
NewState	The new state of the items.


TcxCustomListView.OnDeletion

TcxCustomListView

Occurs before an item is deleted from a list view.

type

  TLVDeletedEvent = procedure(Sender: TObject; Item: TListItem) of object;

property OnDeletion: TLVDeletedEvent;

Description

Handle the OnDeletion event if you wish to take some specific action before an item is deleted from the list view.

The Sender parameter identifies a TcxListView control, which receives the event.  The Item parameter represents the item, which is about to be deleted.


TcxCustomListView.OnDrawItem

TcxCustomListView

Occurs when an item must be drawn within a list view.

type

  TOwnerDrawState = set of (odSelected, odGrayed, odDisabled, odChecked, odFocused, odDefault, odHotLight, odInactive, odNoAccel, odNoFocusRect, odReserved1, odReserved2, odComboBoxEdit);

  TLVDrawItemEvent = procedure(Sender: TCustomListView; Item: TListItem; Rect: TRect; State: TOwnerDrawState) of object;

property OnDrawItem: TLVDrawItemEvent;

Description

The OnDrawItem event occurs when an item must be drawn within a list view.  Unlike the custom draw events, the OnDrawItem event is received only if the OwnerDraw property is set to True.  The custom draw events occur at more points during the paint process and there is a difference in information provided on drawn item state.

Parameter	Meaning
Sender	The TcxListView control, which fires the event.
Item	The item, which is redrawn.
Rect	The rectangle, in which the item is drawn.
State	The state of the item (e.g. selected, disabled, hot, and so on).


TcxCustomListView.OnEdited

TcxCustomListView          See Also          Example

Occurs after editing of the item caption.

type

  TLVEditedEvent = procedure(Sender: TObject; Item: TListItem; var S: string) of object;

property OnEdited: TLVEditedEvent;

Description

The OnEdited event occurs after editing of the list view item caption.  The Sender parameter identifies the TcxListView control, which fires the event.  The Item parameter specifies the item, whose caption had been edited.  The S parameter contains the value, entered by a user as the new item caption. You can change the value of the S parameter if you wish to modify the user input.

See the example of using the OnEdited event handler.


TcxCustomListView.OnEditing

TcxCustomListView          See Also          Example

Occurs when editing of the item caption starts.

type

  TLVEditingEvent = procedure(Sender: TObject; Item: TListItem; var AllowEdit: Boolean) of object;

property OnEditing: TLVEditingEvent;

Description

The OnEditing event occurs when editing of the list view item caption starts.  The Sender parameter identifies the TcxListView control, which fires the event.  The Item parameter specifies the item, whose caption is being edited.  The AlloEdit parameter determines whether caption editing is allowed.  Set this parameter to False to restrict editing.

See the example of using the OnEditing event handler.


TcxCustomListView.OnGetImageIndex

TcxCustomListView          See Also

Occurs when it is required to determine image associated with an item.

type

  TLVNotifyEvent = procedure(Sender: TObject; Item: TListItem) of object;

property OnGetImageIndex: TLVNotifyEvent;

Description

Handle the OnGetImageIndex event if you wish to take some specific action when the TcxListView control attempts to retrieve the index of the image, which is associated with an item. Images that can be displayed in the TcxListView control are stored in the StateImages, LargeImages and SmallImages properties. By handling the OnGetImageIndex event you may vary images assigned to a specific item.

The Sender parameter identifies a cxListView control, which fires the event.  The Item parameter specifies the item, whose image index is requested.


TcxCustomListView.OnGetSubItemImage

TcxCustomListView          See Also

Occurs when it is required to determine image associated with a sub-item.

type

  TLVSubItemImageEvent = procedure(Sender: TObject; Item: TListItem; SubItem: Integer; var ImageIndex: Integer) of object;

property OnGetSubItemImage: TLVSubItemImageEvent;

Description

Handle the OnGetSubImageIndex event if you wish to take some specific action when the TcxListView control attempts to retrieve the index of the image, which is associated with a sub-item. Images that can be associated with the list view sub-items are stored in the SmallImages image list.  To assign an image to the sub-item, use the SubItemImages property of a TListItem instance, representing a list view item.  The following code demonstrates assigning sub-item images by handling the TForm.OnCreate event:

procedure TForm1.FormCreate(Sender: TObject);

const

Names: array[0..5, 0..1] of string = (

('Rubble', 'Barney'),

('Michael', 'Johnson'),

('Bunny', 'Bugs'),

('Silver', 'HiHo'),

('Simpson', 'Bart'),

('Squirrel', 'Rocky')

);

var

  I: Integer;

  ListItem: TListItem;

begin

  for I := Low(Names) to High(Names) do

  begin

    ListItem := cxListView1.Items.Add;

    ListItem.Caption := Names[I][0];

    ListItem.SubItems.Add(Names[I][1]);

    ListItem.SubItemImages[0] := High(Names) - I;

    ListItem.ImageIndex := I;

    ListItem.StateIndex := 1;

  end;

end;

The result is demonstrated on the following screenshot:

By handling the OnGetImageIndex property you can dynamically associated images with specific sub-items.

The Sender parameter identifies the TcxListView control, which fires the event.  The Item parameter specifies the item, whose sub-item’s image index is requested.  The SubItem represents the index of the required sub-item within the Item.SubItems collection.  The ImageIndex is the var parameter, specifying the required image index.


TcxCustomListView.OnInfoTip

TcxCustomListView

Occurs before the hint is displayed within the list view.

type

  TLVInfoTipEvent = procedure(Sender: TObject; Item: TListItem; var InfoTip: string) of object;

property OnInfoTip: TLVInfoTipEvent;

Description

When the mouse cursor is positioned over an item within the TcxListView control, the hint (tip) appears.  Hints are displayed only for partially visible items.  The OnInfoTip event is fired before the hint is displayed.   You can use this event handler to change the hint, displayed for a specific item.

The Sender parameter identifies the TcxListView control, which fires the event.  The Item parameter specifies the item, whose hint is to be displayed.  The InfoTip parameter specifies the tip string for an item.


TcxCustomListView.OnInsert

TcxCustomListView          See Also

Occurs after the new item is inserted into the list view.

type

  TLVDeletedEvent = procedure(Sender: TObject; Item: TListItem) of object;

property OnInsert: TLVDeletedEvent;

Description

The OnInsert event occurs after the new item is inserted into the list view.

The Sender parameter identifies a TcxListView control, which receives the event.  The Item parameter represents the inserted item.

Example:

procedure TMainForm.ListViewInsert(Sender: TObject; Item: TListItem);

begin

  StatusBar.Panels[1].Text := 'Item ' + Item.Caption + ' is inserted';

end;


TcxCustomListView.OnSelectItem

TcxCustomListView

Occurs after an item within a list view control is selected or deselected.

type

  TLVSelectItemEvent = procedure(Sender: TObject; Item: TListItem; Selected: Boolean) of object;

property OnSelectItem: TLVSelectItemEvent;

Description

The OnSelectItem event occurs when the user selects or deselects an item in the TcxListView control.

The Sender parameter identifies the TcxListView control, which receives the event.  The Item represents the selected item.  The Selected parameter indicates, whether the user selects (True) or deselects (False) the item.


TcxListView
TcxListView Object

Hierarchy          Properties          Methods          Events

Represents an advanced list view control, which is capable of displaying items in various modes.

Unit

cxListView

TcxListView = class(TcxCustomListView)

Description

The TcxCustomListView class implements the functionality of the list view control, which can display a list of items in various modes.

The following screenshot demonstrates an example of the list view control appearance:

Please refer to the Items property description for details on how to create the items structure.

Items of TcxCustomListView descendant controls are represented by TListItem objects.  Visually, items are comprised of text labels and images.  If such item representation doesn’t suit your application needs, you can paint items manually by handling the OnCustomDrawItem and OnAdvancedCustomDrawItem events.  Additionally you can create your own TListItem class descendant to represent items within the control.  You must handle the OnCreateItemClass event to perform the replacement.

In addition to painting individual items, you can paint the entire list view control manually.  This can be performed by handling the OnCustomDraw and OnAdvancedCustomDraw events.

The TcxListView control has three image lists containing images associated with the items.  The LargeImages and SmallImages properties contain images helping to understand the item contents.  The StateImages property contains images representing item states.

Two more significant features implemented by the TcxCustomListView class are multi selection of items and item sorting.  Please refer to the MultiSelect and SortType property descriptions for details.

Do not create instances of TcxCustomListView. Use it as a base class when implementing custom list views with some extra features and advanced functionality. If you need a list view control on your form, use the derived TcxListView, which publishes properties of the TcxCustomListView class.


TcxListView Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomListView

     |


Properties for TcxListView
TcxListView Properties

TcxListView          Legend

Derived from TcxCustomListView

AllocBy

ColumnClick

Columns

HideSelection

HotTrack

HoverTime

IconOptions

Items

LargeImages

MultiSelect

OwnerData

OwnerDraw

ReadOnly

ShowColumnHeaders

ShowWorkAreas

SmallImages

SortType

StateImages

ViewStyle

Derived from TcxContainer

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TControl

Align


Methods for TcxListView
TcxListView Methods

TcxListView          Legend

Derived from TcxCustomListView

 AddItem

 AlphaSort

 Arrange

 Clear

 ClearSelection

 CopySelection

 CustomSort

 DeleteSelected

 FindCaption

 FindData

 GetHitTestInfoAt

 GetItemAt

 GetNearestItem

 GetNextItem

 GetSearchString

 IsEditing

 SelectAll

 StringWidth

 UpdateItems

Derived from TcxControl

 Create

 Destroy

 InvalidateRect


Events for TcxListView
TcxListView Events

TcxListView          Legend

Derived from TcxCustomListView

 OnAdvancedCustomDraw

 OnAdvancedCustomDrawItem

 OnAdvancedCustomDrawSubItem

 OnCancelEdit

 OnChange

 OnChanging

 OnColumnClick

 OnColumnDragged

 OnColumnRightClick

 OnCompare

 OnCreateItemClass

 OnCustomDraw

 OnCustomDrawItem

 OnCustomDrawSubItem

 OnData

 OnDataFind

 OnDataHint

 OnDataStateChange

 OnDeletion

 OnDrawItem

 OnEdited

 OnEditing

 OnGetImageIndex

 OnGetSubItemImage

 OnInfoTip

 OnInsert

 OnSelectItem


Example: Sorting the cxListView items by clicking the column headers

This example demonstrates implementing sorting within the cxListView by clicking the column headers.

The OnColumnClick event handler is used to determine the index of the clicked column.  This index is stored in the FColumnToSort variable.  It also determines and changes the current sort order applied to the cxListView (current sort order is stored in FSortOrder variable).  After changing of the sort order, the AlphaSort method is called.

The OnCompare event handler provides the custom sorting procedure.  It determines whether the column, containing the item or sub-item was clicked.  Then it uses the CompareText function to determine the sort order for the clicked column (depending on the FSortOrder value).

//Delphi

var

  FColumnToSort: Integer;

  FSortOrder: TListViewSortOrder;

//...

procedure TForm1.FormCreate(Sender: TObject);

begin

  FSortOrder := soDescend;

end;

procedure TForm1.cxListView1ColumnClick(Sender: TObject;

Column: TListColumn);

begin

//storing the clicked column index

  FColumnToSort := Column.Index;

//switching the sort order

  if FSortOrder = soDescend then FSortOrder := soAscend

  else

    FSortOrder := soDescend;

//sorting the items within a column

  (Sender as TcustomListView).AlphaSort;

end;

procedure TForm1.cxListView1Compare(Sender: TObject; Item1,

Item2: TListItem; Data: Integer; var Compare: Integer);

var

  ASubIndex, ACompare: Integer;

begin

//if the first column was clicked, then the compare criterion is created based

//on the item captions

  if FColumnToSort = 0 then ACompare := CompareText(Item1.Caption,Item2.Caption)

  else

  begin

//if the column containing sub-items was clicked, then the compare criterion

//is created based on the sub-items captions

      ASubIndex := FColumnToSort - 1;

      ACompare := CompareText(Item1.SubItems[ASubIndex],Item2.SubItems[ASubIndex]);

  end;

//if the ascending sort order is applied, then the sign of the compare

//criterion stays the same

  if FSortOrder = soAscend then Compare := ACompare

  else

//if the descending sort order is applied, then the sign of the compare

//criterion inverts

    Compare := - ACompare;

end;


Example: Using OnEditing, OnEdited, OnCancelEdit events.
Example: Using OnEditing, OnEdited, OnCancelEdit events

The following code demonstrates using the OnEditing, OnEdited and OnCancelEdit events.

The OnEditing event handler changes the state image associated with the edited item.  It also restricts editing of the fourth item.  The OnEdited event handler switches the state image back to default and changes the edited item’s Caption case.  The OnCancelEdit event handler switches the state image if editing was canceled by switching to another item or pressing the Esc key.

procedure TForm1.cxListViewEditing(Sender: TObject; Item: TListItem; var AllowEdit: Boolean);

begin

  if Item.Index = 3 then

    AllowEdit := False

  else

    Item.StateIndex := 2;

end;

procedure TForm1.cxListViewEdited(Sender: TObject; Item: TListItem; var S: String);

begin

  Item.StateIndex := 1;

  S := UpperCase(S);

end;

procedure TForm1.cxListViewCancelEdit(Sender: TObject);

begin

  with Sender as TcxListView do

    Items[ItemIndex].StateIndex := 1;

end;

The following screenshot demonstrates the cxListView items in default state:

And during editing:


Example: Using cxListView in virtual mode

This example explains using cxListView control in virtual mode.  This mode is activated when the OwnerData property of a list view control is set to True.  In this case, a user must manage the OnData, OnDataFind, OnDataHint and OnDataStateChange event handlers.

Event	Description
OnData	Fires before displaying of an item within a virtual list view.  This event also fires when list view items need to be updated.
OnDataFind	Fires when the list view control receives a search request, such as when the FindData and FindCaption methods are called.  List view control receives search requests with each key pressing.
OnDataHint	Fires before the OnData event.  Can be used to update list view items, for instance, during scrolling.
OnDataStateChange	Fires when the item’s state changes.

When the list view control functions in virtual mode, it contains no information about items within it, except for their number and selection/focus position.  The number of items within the virtual list view must be specified by the Items.Count property value.

Before the virtual list view is loaded, the OnData event is fired as many times as specified by the Items.Count property.  Handle this event to supply the necessary item properties: Caption, ImageIndex, StateIndex, SubItems, etc.

Note: if the Items.Count property value is not specified, then the virtual list view does not contain any data, even if the OnData event is properly handled.

The following code demonstrates the OnData and OnDataFind event handlers.  The OnData event handler populates the list view with items.  Item and sub-item captions are obtained from the strings array.  The OnDataFind event handler implements incremental search functionality during user typing within the list view control.

procedure TForm1.FormCreate(Sender: TObject);

begin

  cxListView1.Items.Count := 10;

end;

procedure TForm1.cxListViewData(Sender: TObject; Item: TListItem);

const

  Names: array[0..10, 0..1] of string = (

    ('Davolio', 'Nancey'), ('Fuller', 'Andrew'), ('Leverling', 'Janet'),

    ('Peacock', 'Margaret'), ('Buchanan', 'Steven'), ('Suyama', 'Michael'),

    ('King', 'Robert'), ('Callahan', 'Laura'), ('Dodsworth', 'Anne'),

    ('Diego', 'Roel'), ('Paula', 'Wilson'));

begin

  Item.Caption := Names[Item.Index][0];

  Item.ImageIndex := Item.Index;

  Item.StateIndex := 1;

  Item.SubItems.Add(Names[Item.Index][1]);

  Item.SubItemImages[0] := High(Names) - Item.Index;

end;

procedure TForm1.cxListViewDataFind(Sender: TObject; Find: TItemFind;

const FindString: String; const FindPosition: TPoint; FindData: Pointer;

StartIndex: Integer; Direction: TSearchDirection; Wrap: Boolean;

var Index: Integer);

var

  I: Integer;

  Found: Boolean;

begin

  I := StartIndex;

//if the search is performed during user typing (i.e. item is located according

//to its Caption)

  if (Find = ifPartialString) or (Find = ifExactString) then

  begin

    repeat

//if the search has reached the end of the Items collection

      if I = cxListView1.Items.Count - 1 then

//wrapping the search direction

        if Wrap then I := 0 else Exit;

//if the current item caption contains the typed character, the Found flag is

//activated. This flag indicates that the search was successful

    Found := Pos(UpperCase(FindString), UpperCase(cxListView1.Items[I].Caption)) = 1;

//moving to the next item

      Inc(I);

//until the search was completed successfully or the all items were involved

//into search

    until Found or (I = StartIndex);

  end;

//if the search was completed successfully, the found item is selected

  if Found then Index := I - 1;

end;


TcxButtonGroupItem
TcxButtonGroupItem Object

Hierarchy          Properties          See Also

Serves as the base for items used by the radio group, check group and check combo box controls.

Unit

cxGroupBox

TcxButtonGroupItem = class(TCollectionItem)

Description

The TcxButtonGroupItem class implements the basic functionality of items used by the TcxRadioGroup, TcxCheckGroup and TcxCheckComboBox editors.  Thus, it serves as the base for the TcxRadioGroupItem, TcxCheckGroupItem and TcxCheckComboBoxItem objects.  Such objects are available via the Properties.Items property of the controls mentioned.


TcxButtonGroupItem Hierarchy
Hierarchy

TCollectionItem

     |


Properties for TcxButtonGroupItem
TcxButtonGroupItem Properties

TcxButtonGroupItem          Legend

In TcxButtonGroupItem

Caption

Enabled

Tag


TcxButtonGroupItem.Caption

TcxButtonGroupItem

Specifies the item’s caption.

property Caption: TCaption;

Description

Use the Caption property to specify the text representing an item.  This is the text displayed near a check box or radio button (depending on the control you use).  If this property value is not specified, then the item is represented by a control element only.

The image below shows a radio group control sample.  The first item’s Caption property value is an empty string.


TcxButtonGroupItem.Enabled

TcxButtonGroupItem

Specifies whether the item’s state can be changed at runtime.

property Enabled: Boolean;

Description

The Enabled property lets you prevent the end-user from changing the item’s state.  If the Enabled property is set to False, clicking the checkbox or pressing the space bar while the item is selected doesn’t change the item’s state.

Note that radio group items do not use this property.

The default value of the Enabled property is True.


TcxButtonGroupItem.Tag

TcxButtonGroupItem

Stores a value associated with the item.

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 items or when you need to have an additional item identification mechanism.


TcxButtonGroupItems
TcxButtonGroupItems Object

Hierarchy          Properties

Represents a collection of TcxButtonGroupItem objects.

Unit

cxGroupBox

TcxButtonGroupItems = class(TOwnedCollection, IcxCheckItems)

Description

The TcxButtonGroupItems object implements the basic functionality of item collections used by the TcxRadioGroup, TcxCheckGroup and TcxCheckComboBox controls.  Thus, it serves as the base for the TcxRadioGroupItems, TcxCheckGroupItems and TcxCheckComboBoxItems objects.  Such objects can be accessed via the Properties.Items property of the controls mentioned.


TcxButtonGroupItems Hierarchy
Hierarchy

TOwnedCollection

     |


Properties for TcxButtonGroupItems
TcxButtonGroupItems Properties

TcxButtonGroupItems          Legend

In TcxButtonGroupItems

Items


TcxButtonGroupItems.Items

TcxButtonGroupItems

Provides indexed access to individual items.

property Items[Index: Integer]: TcxButtonGroupItem;

Description

The Items property overrides the base class property to return items of the TcxButtonGroupItem type.  TcxButtonGroupItems descendants also override this property to return objects of particular types.

The property is used to access individual items by their indexes that should be passed as the Index parameter.  The first item’s index is zero.  The last item’s index is the Count property value decremented by one.


TcxCustomButtonGroup
TcxCustomButtonGroup Object

Hierarchy          Properties          Methods          Events

Implements the basic functionality of controls displaying multiple check boxes or radio buttons.

Unit

cxGroupBox

TcxCustomButtonGroup = class(TcxCustomGroupBox)

Description

The TcxCustomButtonGroup class serves as the base for the TcxRadioGroup and TcxCheckGroup controls.  It inherits the border and caption painting functionality from the group box control.  Additionally, it overrides the Properties property to return an object providing common settings for radio group and check group controls.

Do not create TcxCustomButtonGroup objects directly.  To create a radio or check group, use an appropriate descendant.


TcxCustomButtonGroup Hierarchy
Hierarchy

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomGroupBox

     |


Properties for TcxCustomButtonGroup
TcxCustomButtonGroup Properties

TcxCustomButtonGroup          Legend

In TcxCustomButtonGroup

ActiveProperties

Properties

Derived from TcxCustomGroupBox

Alignment

CaptionBkColor

Derived from TcxCustomEdit

ActiveProperties

AutoSize

DataBinding

EditModified

EditValue

InnerEdit

ModifiedAfterEnter

Properties

RepositoryItem

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxCustomButtonGroup
TcxCustomButtonGroup Methods

TcxCustomButtonGroup          Legend

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCustomButtonGroup
TcxCustomButtonGroup Events

TcxCustomButtonGroup          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCustomButtonGroup.ActiveProperties

TcxCustomButtonGroup          See Also

Obtains the properties that are currently applied to a button group editor.

property ActiveProperties: TcxCustomButtonGroupProperties;

Description

Use the ActiveProperties property to obtain the properties of the current button group editor that are currently in effect.  This property is especially useful when the button group 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 button group editor.  Otherwise, the inherent button group editor’s properties are returned.

ReadOnly Property


TcxCustomButtonGroup.Properties

TcxCustomButtonGroup

Provides access to the object containing editor-specific properties.

property Properties: TcxCustomButtonGroupProperties;

Description

The Properties property provides access to a TcxCustomButtonGroupProperties object providing common settings for radio group and check group editors.  Descendant controls (TcxRadioGroup and TcxCheckGroup) override this property to return TcxCustomButtonGroupProperties descendants.  These descendants extend the options set to meet a particular editor’s needs.

ReadOnly Property


TcxCustomButtonGroupProperties
TcxCustomButtonGroupProperties Object

Hierarchy          Properties          Methods          Events

Declares settings common for the TcxRadioGroup and TcxCheckGroup controls.

Unit

cxGroupBox

TcxCustomButtonGroupProperties = class(TcxCustomGroupBoxProperties)

Description

Properties declared by the TcxCustomButtonGroupProperties object are common for the radio group and check group controls.  Thus, this object serves as the base for the TcxRadioGroupProperties and TcxCheckGroupProperties objects.  These objects can be accessed via the Properties property of editors mentioned.


TcxCustomButtonGroupProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomGroupBoxProperties

     |


Properties for TcxCustomButtonGroupProperties
TcxCustomButtonGroupProperties Properties

TcxCustomButtonGroup          Legend

In TcxCustomButtonGroupProperties

Columns

Items

WordWrap

Derived from TcxCustomEditProperties

Alignment

AssignedValues

AutoSelect

BeepOnError

Buttons

ButtonsViewStyle

ClearKey

ClickKey

ImmediatePost

ReadOnly

UseLeftAlignmentOnEditing

UseMouseWheel

ValidateOnEnter


Methods for TcxCustomButtonGroupProperties
TcxCustomButtonGroupProperties Methods

TcxCustomButtonGroup          Legend

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue

Derived from TcxControl

Create

Destroy

InvalidateRect


Events for TcxCustomButtonGroupProperties
TcxCustomButtonGroupProperties Events

TcxCustomButtonGroup          Legend

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomButtonGroupProperties.Columns

TcxCustomButtonGroupProperties

Specifies the column count within the radio group or check group control.

property Columns: Integer;

Description

When the Columns property value is 1, items are arranged one under another within the group.  Setting the Columns property to a value greater than 1 arranges items into the specified number of columns (if possible).

The image represents the radio group with eight items and three columns.

Note: the Columns property cannot be set to a value less than 1.

The default value of the Columns property is 1.


TcxCustomButtonGroupProperties.Items

TcxCustomButtonGroupProperties

Provides access to the items collection.

property Items: TcxButtonGroupItems;

Description

The Items property is used to set up the collection of items (check boxes or radio buttons) displayed by the control.  The collection is empty initially.  Thus, you have to add items to that collection to display radio buttons or check boxes within the control.

Note that the TcxRadioGroupProperties and TcxCheckGroupProperties objects override the Items property to return an object of a proper type. This is required since check boxes and radio buttons have slightly different settings.


TcxCustomButtonGroupProperties.WordWrap

TcxCustomButtonGroupProperties

Specifies whether captions of items are wrapped, if they are too long.

property WordWrap: Boolean;

Description

Setting the WordWrap property to True enables text wrapping for items’ captions. Text wrapping occurs when the area supplied to an item is not enough to fit its caption.  If the WordWrap property value is False, then the radio item caption occupies a single line, regardless of whether the caption fits into the control.

An example of a wrapped radio item caption is demonstrated below:

The default value of the WordWrap property is False.


cxCheckGroup Unit Overview
cxCheckGroup Unit

Classes

TcxCheckGroup

TcxCheckGroupItem

TcxCheckGroupItems

TcxCheckGroupProperties

TcxCustomCheckGroup

TcxCustomCheckGroupProperties


TcxCheckGroup
TcxCheckGroup Object

Hierarchy          Properties          Methods          Events

Represents an editor displaying a set of check boxes.

Unit

cxCheckGroup

TcxCheckGroup = class(TcxCustomCheckGroup)

Description

Use the TcxCheckGroup editor when the edit value can be represented as a set of options.  Each option can be represented by an individual check box that can have three states: unchecked, checked and grayed.  Individual check boxes are represented by the TcxCheckGroupItem objects available via the Properties.Items property.

The editor supports four edit value formats.  You can choose the required format using the Properties.EditValueFormat property.  If you are not satisfied with the formats supplied, you can implement custom correspondence between the check states and the edit value.  Handle the Properties.OnStatesToEditValue and Properties.OnEditValueToStates events.

The CalculateCheckStatesValue and CalculateCheckStates methods let you calculate the editor’s edit value by the items’ check states and vice versa.

The image below displays the TcxCheckGroup control’s sample appearance.

Note that you can alternatively use the TcxCheckListBox and TcxCheckComboBox controls that are used to edit values of the same type.  If you need a data-aware check group, use the TcxDBCheckGroup editor.


TcxCheckGroup Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomGroupBox

     |

TcxCustomButtonGroup

     |

TcxCustomCheckGroup

     |


Properties for TcxCheckGroup
TcxCheckGroup Properties

TcxCheckGroup          Legend

Derived from TcxCustomCheckGroup

ActiveProperties

Properties

States

Derived from TcxCustomButtonGroup

ActiveProperties

Properties

Derived from TcxCustomGroupBox

Alignment

CaptionBkColor

Derived from TcxCustomEdit

ActiveProperties

AutoSize

DataBinding

EditModified

EditValue

InnerEdit

ModifiedAfterEnter

Properties

RepositoryItem

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TControl

Align


Methods for TcxCheckGroup
TcxCheckGroup Methods

TcxCheckGroup          Legend

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit


Events for TcxCheckGroup
TcxCheckGroup Events

TcxCheckGroup          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCheckGroupItem
TcxCheckGroupItem Object

Hierarchy          Properties

Represents an individual check box within the TcxCheckGroup and TcxDBCheckGroup controls.

Unit

cxCheckGroup

TcxCheckGroupItem = class(TcxButtonGroupItem)

Description

To display check boxes within a TcxCheckGroup or TcxDBCheckGroup control, you need to add TcxCheckGroupItem objects into the control’s Properties.Items collection.  Each object added represents an individual check box.  The TcxCheckGroupItem object’s properties enable you to specify the check box’s caption, enabled state and tag.  Note that all these settings are inherited from the TcxButtonGroupItem object.  The TcxCheckGroupItem class simply publishes the inherited properties.


TcxCheckGroupItem Hierarchy
Hierarchy

TCollectionItem

     |

TcxButtonGroupItem

     |


Properties for TcxCheckGroupItem
TcxCheckGroupItem Properties

TcxCheckGroupItem          Legend

Derived from TcxButtonGroupItem

Caption

Enabled

Tag


TcxCheckGroupItems
TcxCheckGroupItems Object

Hierarchy          Properties

Represents the check boxes collection within a TcxCheckGroup control.

Unit

cxCheckGroup

TcxCheckGroupItems = class(TcxButtonGroupItems)

Description

TcxCheckGroupItems objects are available via the Properties.Items property of a TcxCheckGroup control.  Such objects hold check boxes collections displayed by the owning controls.  Each individual item in the collection is represented by a TcxCheckGroupItem object. You can access these objects via the collection’s Items property.

The TcxCheckGroupItems object is the TOwnedCollection descendant and thus inherits the common members for collection management.


TcxCheckGroupItems Hierarchy
Hierarchy

TOwnedCollection

     |

TcxButtonGroupItems

     |


Properties for TcxCheckGroupItems
TcxCheckGroupItems Properties

TcxCheckGroupItems          Legend

In TcxCheckGroupItems

Items

Derived from TcxButtonGroupItems

Items


TcxCheckGroupItems.Items

TcxCheckGroupItems

Provides indexed access to individual check boxes within the group.

property Items[Index: Integer]: TcxCheckGroupItem;

Description

Use the Items property to access check boxes by their indexes.  The desired check box’s index should be passed as the Index parameter.  The first item’s index is zero.  The last item’s index is the Count property value decremented by one.  Note that passing an invalid item index will raise an exception.

Note:	If you need to set a particular check box’s state, use the control’s States property.


TcxCheckGroupProperties
TcxCheckGroupProperties Object

Hierarchy          Properties          Methods          Events

Provides settings specific for the TcxCheckGroup and TcxDBCheckGroup editors.

Unit

cxCheckGroup

TcxCheckGroupProperties = class(TcxCustomCheckGroupProperties)

Description

TcxCheckGroupProperties objects are available via the Properties property of TcxCheckGroup and TcxDBCheckGroup controls.  Such objects provide properties and events specific to the owning editor.  When a radio group editor is used for in-place editing in container controls, editor settings are also provided by TcxCheckGroupProperties objects that are available via container control’s particular members.  To control any changes made to the editor’s ReadOnly property and reverse its value back to the default one, use the AssignedValues property.

The TcxCheckGroupProperties object inherits all its functionality from the TcxCustomCheckGroupProperties object and simply publishes the required properties and events.


TcxCheckGroupProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomGroupBoxProperties

     |

TcxCustomButtonGroupProperties

     |

TcxCustomCheckGroupProperties

     |


Properties for TcxCheckGroupProperties
TcxCheckGroupProperties Properties

TcxCheckGroupProperties          Legend

Derived from TcxCustomCheckGroupProperties

AllowGrayed

EditValueFormat

Glyph

GlyphCount

ItemAlignment

Items

Derived from TcxCustomButtonGroupProperties

Columns

Items

WordWrap

Derived from TcxCustomEditProperties

Alignment

AssignedValues

AutoSelect

BeepOnError

Buttons

ButtonsViewStyle

ClearKey

ClickKey

ImmediatePost

ReadOnly

UseLeftAlignmentOnEditing

UseMouseWheel

ValidateOnEnter


Methods for TcxCheckGroupProperties
TcxCheckGroupProperties Methods

TcxCheckGroupProperties          Legend

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue


Events for TcxCheckGroupProperties
TcxCheckGroupProperties Events

TcxCheckGroupProperties          Legend

Derived from TcxCustomCheckGroupProperties

OnEditValueToStates

OnStatesToEditValue

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomCheckGroup
TcxCustomCheckGroup Object

Hierarchy          Properties          Methods          Events

Implements the basic functionality of check group controls.

Unit

cxCheckGroup

TcxCustomCheckGroup = class(TcxCustomButtonGroup)

Description

The TcxCustomCheckGroup class serves as the base for the TcxCheckGroup and TcxDBCheckGroup objects.  It inherits the button and border painting functionality (when using an editor as a standalone) from the TcxCustomButtonGroup class.  Additionally, it overrides the Properties property to provide settings specific to check box groups.  It also implements the States property that enables you to specify check states for individual check boxes within the control.

Note that the check group’s edit value is updated automatically when changing the individual combo boxes’ check states.  The edit value’s format is specified by the Properties.EditValueFormat property.  You can also override default conversion logic by handling the Properties.OnStatesToEditValue and Properties.OnEditValueToStates events.


TcxCustomCheckGroup Hierarchy
Hierarchy

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomGroupBox

     |

TcxCustomButtonGroup

     |


Properties for TcxCustomCheckGroup
TcxCustomCheckGroup Properties

TcxCustomCheckGroup          Legend

In TcxCustomCheckGroup

ActiveProperties

Properties

States

Derived from TcxCustomButtonGroup

ActiveProperties

Properties

Derived from TcxCustomGroupBox

Alignment

CaptionBkColor

Derived from TcxCustomEdit

ActiveProperties

AutoSize

DataBinding

EditModified

EditValue

InnerEdit

ModifiedAfterEnter

Properties

RepositoryItem

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading


Methods for TcxCustomCheckGroup
TcxCustomCheckGroup Methods

TcxCustomCheckGroup          Legend

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit


Events for TcxCustomCheckGroup
TcxCustomCheckGroup Events

TcxCustomCheckGroup          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCustomCheckGroup.ActiveProperties

TcxCustomCheckGroup          See Also

Obtains the properties that are currently applied to an editor.

property ActiveProperties: TcxCustomCheckGroupProperties;

Description

Use the ActiveProperties property to obtain the properties of the current editor that are currently in effect.  This property is especially useful when the 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 editor.  Otherwise, the inherent editor’s properties are returned.

ReadOnly Property


TcxCustomCheckGroup.Properties

TcxCustomCheckGroup

Provides access to settings specific for check group controls.

property Properties: TcxCustomCheckGroupProperties;

Description

Use the Properties property to access properties and events specific to radio group controls.  The properties enable you to specify custom check glyphs, edit value format, item captions alignment, etc.  The events enable you to provide a custom correspondence between the check states and the edit value.


TcxCustomCheckGroup.States

TcxCustomCheckGroup          See Also

Specifies check states for individual check boxes.

type

  TcxCheckBoxState = (cbsUnchecked, cbsChecked, cbsGrayed);

property States[Index: Integer]: TcxCheckBoxState;

Description

Use the States property to obtain or change the check state of an individual item within the group.  The item whose state is to be returned or modified is specified by its index via the Index parameter.  The first item’s index is zero.  The last item’s index is the number of items decremented by one.  Specifying an invalid item index will raise an exception.

Note that the grayed state availability is controlled by the Properties.AllowGrayed property.  However, you can set a check box’s state to grayed via code regardless of that property’s value.

Setting this property at design time invokes the "cxCheckGroup – CheckStates editor" which helps you customize the check states of items.

Note:	Use the CalculateCheckStatesValue and CalculateCheckStates methods to calculate the editor’s edit value by the items’ check states and vice versa.


TcxCustomCheckGroupProperties
TcxCustomCheckGroupProperties Object

Hierarchy          Properties          Methods          Events

Provides settings for check group editors.

Unit

cxCheckGroup

TcxCustomCheckGroupProperties = class(TcxCustomButtonGroupProperties)

Description

The TcxCustomCheckGroupProperties class serves as the base for the TcxCheckGroupProperties object.  The latter provides settings for the TcxCheckGroup and TcxDBCheckGroup editors.  Note that the TcxCustomCheckGroupProperties class implements all the properties and events required by its descendant.  The TcxCheckGroupProperties class simply publishes these members.

Properties provided by the TcxCustomCheckGroupProperties object enable you to specify the check boxes collection, the layout and appearance of check boxes, the available check states and custom check glyphs.  The introduced OnStatesToEditValue and OnEditValueToStates events enable you to provide a custom correspondence between the check states and the edit value.


TcxCustomCheckGroupProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomGroupBoxProperties

     |

TcxCustomButtonGroupProperties

     |


Properties for TcxCustomCheckGroupProperties
TcxCustomCheckGroupProperties Properties

TcxCustomCheckGroupProperties          Legend

In TcxCustomCheckGroupProperties

AllowGrayed

EditValueFormat

Glyph

GlyphCount

ItemAlignment

Items

Derived from TcxCustomButtonGroupProperties

Columns

Items

WordWrap

Derived from TcxCustomEditProperties

Alignment

AssignedValues

AutoSelect

BeepOnError

Buttons

ButtonsViewStyle

ClearKey

ClickKey

ImmediatePost

ReadOnly

UseLeftAlignmentOnEditing

UseMouseWheel

ValidateOnEnter


Methods for TcxCustomCheckGroupProperties
TcxCustomCheckGroupProperties Methods

TcxCustomCheckGroupProperties          Legend

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue


Events for TcxCustomCheckGroupProperties
TcxCustomCheckGroupProperties Events

TcxCustomCheckGroupProperties          Legend

In TcxCustomCheckGroupProperties

OnEditValueToStates

OnStatesToEditValue

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomCheckGroupProperties.AllowGrayed

TcxCustomCheckGroupProperties

Specifies whether end users can change check boxes’ states to grayed.

property AllowGrayed: Boolean;

Description

Use the AllowGrayed property to specify whether individual check boxes support the grayed state.  If the property value is True, clicking an unchecked item changes its state to grayed.  Clicking a grayed item changes its state to checked.  The same takes place when pressing the SPACE key while the item is selected.  If the AllowGrayed property value is False, clicking an unchecked item changes the item’s state to checked immediately.

You can change check states via code using the control’s States property.  Note that the AllowGrayed property value is not taken into account in this case.  It can only be used to control end user actions.

The default value of the AllowGrayed property is False.


TcxCustomCheckGroupProperties.EditValueFormat

TcxCustomCheckGroupProperties

Specifies the edit value format.

type

  TcxCheckStatesValueFormat = (cvfCaptions, cvfIndices, cvfInteger, cvfStatesString);

property EditValueFormat: TcxCheckStatesValueFormat;

Description

Use the EditValueFormat to specify how the editor interprets the check boxes’ states into the edit value.  See the TcxCheckStatesValueFormat type description for the list of available options.

Note that you can provide a custom conversion from check states to the edit value.  To do so, you should handle the Properties.OnStatesToEditValue and Properties.OnEditValueToStates events.

The default value of the EditValueFormat property is cvfIndices.

Note:	If you want to provide support for grayed items in an editor, set its EditValueFormat property to something other than a cvfInteger value.


TcxCustomCheckGroupProperties.Glyph

TcxCustomCheckGroupProperties

Provides custom images for check boxes.

property Glyph: TBitmap;

Description

Check group controls enable you to specify custom images for various check box states.  You can specify up to 6 images.  These images are used for the unchecked, checked, grayed and pressed states of the check box.

The bitmap assigned to the Glyph property should contain the desired number of images arranged horizontally one after another.  Each image (a bitmap part) will be used for a particular check box state.  Note that the number of images supplied within the bitmap should be assigned to the GlyphCount property.  For instance, if the GlyphCount property’s value is 3, the bitmap supplied will be divided into three equal parts horizontally and these parts will be used to represent the unchecked, checked and grayed states, respectively.

Please refer to the GlyphCount property’s description for details.


TcxCustomCheckGroupProperties.GlyphCount

TcxCustomCheckGroupProperties          See Also

Specifies the number of images supplied by the Glyph bitmap.

property GlyphCount: Integer;

Description

The GlyphCount property should be used if you supply custom images for check states.  This property specifies the number of parts within the bitmap specified by the Glyph property.  Each part, in turn, corresponds to a particular check state.  The following table describes the possible GlyphCount values:

Value	Meaning
0	A glyph is not used.  The standard check box is displayed.
1	A full size image is displayed instead of the check box.
2	The Glyph bitmap contains two parts (images).  The first image is used to represent the unchecked state.  The second image represents the checked state.
3	The Glyph bitmap contains three parts (images).  They represent the unchecked, checked, and grayed states respectively.
6	The Glyph bitmap contains six parts (images).  The first, second and third images represent the unchecked, checked and grayed states respectively when the check box is not pressed.  Other three images represent the same states when the check box is pressed.

The default value of the GlyphCount property is 6.


TcxCustomCheckGroupProperties.ItemAlignment

TcxCustomCheckGroupProperties

Specifies whether captions are displayed to the left or to the right of check boxes.

type

  TLeftRight = taLeftJustify..taRightJustify;

property ItemAlignment: TLeftRight;

Description

Use the ItemAlignment property to specify whether captions should be displayed to the left or to the right of check boxes.

The image below shows the same control when the property is set to taLeftJustify and taRightJustify respectively.

The default value of the ItemAlignment property is taLeftJustify.


TcxCustomCheckGroupProperties.Items

TcxCustomCheckGroupProperties

Provides access to the check boxes collection.

property Items: TcxCheckGroupItems;

Description

The Items property represents a collection that holds elements representing individual check boxes displayed by the control.  This collection is empty initially.  Thus, you should add items to that collection to display check boxes within the control.

The property provides access to the TcxCheckGroupItems object which is a TOwnedCollection descendant and thus gives you all common members for collection management.  Individual items can be accessed using that object’s Items property.

If you need to change check states for individual items, use the control’s States property.


TcxCustomCheckGroupProperties.OnEditValueToStates

TcxCustomCheckGroupProperties

Enables you to manually convert an edit value to a check state.

type

  TcxEditValue = Variant;

  TcxCheckBoxState = (cbsUnchecked, cbsChecked, cbsGrayed);

  TcxCheckStates = array of TcxCheckBoxState;

  TcxValueToCheckStatesEvent = procedure(Sender: TObject; const AValue: TcxEditValue; var ACheckStates: TcxCheckStates) of object;

property OnEditValueToStates: TcxValueToCheckStatesEvent;

Description

The OnEditValueToStates event fires each time the editor needs to update its check states (for instance, when changing the edit value).  You should handle this event if you use a check group control to display data stored in a format that is not supported by the control.  For the supported formats list, refer to the EditValueFormat topic.

Note that manual conversion of edit values to check states generally requires a custom conversion of check states to the edit value.  Otherwise, the control may not work correctly.  Thus, you will need to handle the OnEditValueToStates event in combination with the Properties.OnStatesToEditValue event.  There are cases, however, when you don’t need to handle the Properties.OnStatesToEditValue event.  For instance, you may want to display a data field’s values using a read-only check group editor.

The event’s Sender parameter specifies the editor whose edit value is converted to its check states.  The AValue parameter enables you to determine the new edit value.  The corresponding check states should be written to the ACheckStates parameter.

Note:	Use the CalculateCheckStatesValue and CalculateCheckStates methods to calculate the editor’s edit value by the items’ check states and vice versa.


TcxCustomCheckGroupProperties.OnStatesToEditValue

TcxCustomCheckGroupProperties

Enables you to convert a check state to an edit value manually.

type

  TcxEditValue = Variant;

  TcxCheckBoxState = (cbsUnchecked, cbsChecked, cbsGrayed);

  TcxCheckStates = array of TcxCheckBoxState;

  TcxCheckStatesToValueEvent = procedure(Sender: TObject; const ACheckStates: TcxCheckStates; out AValue: TcxEditValue) of object;

property OnStatesToEditValue: TcxCheckStatesToValueEvent;

Description

The OnStatesToEditValue event fires each time the check states change (when an end user clicks individual check boxes or when the check states are changed via code using the control’s States property).  Handle this event if none of the supported edit value formats suit your needs.  Note that in this case, you should also handle the Properties.OnEditValueToStates event.  Please refer to the latter's description for details.

The event’s Sender parameter specifies the editor whose check states are converted to edit value.  The ACheckStates parameter enables you to determine the current check states.  The corresponding edit value should be written to the AValue parameter.

Note:	Use the CalculateCheckStatesValue and CalculateCheckStates methods to calculate the editor’s edit value by the items’ check states and vice versa.


cxDBCheckGroup Unit Overview
cxDBCheckGroup Unit

Classes

TcxDBCheckGroup


TcxDBCheckGroup
TcxDBCheckGroup Object

Hierarchy          Properties          Methods          Events          See Also

Represents a data-aware check group control.

Unit

cxDBCheckGroup

TcxDBCheckGroup = class(TcxCheckGroup)

Description

Use the TcxDBCheckGroup editor when you need a data-aware version of the check group control.  This editor provides the same features as its ancestor TcxCheckGroup control.  Additionally, it introduces the DataBinding property that binds the control to a dataset field.


TcxDBCheckGroup Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomGroupBox

     |

TcxCustomButtonGroup

     |

TcxCustomCheckGroup

     |

TcxCheckGroup

     |


Properties for TcxDBCheckGroup
TcxDBCheckGroup Properties

TcxDBCheckGroup          Legend

In TcxDBCheckGroup

DataBinding

Derived from TcxCustomCheckGroup

ActiveProperties

Properties

States

Derived from TcxCustomButtonGroup

ActiveProperties

Properties

Derived from TcxCustomGroupBox

Alignment

CaptionBkColor

Derived from TcxCustomEdit

ActiveProperties

AutoSize

DataBinding

EditModified

EditValue

InnerEdit

ModifiedAfterEnter

Properties

RepositoryItem

Style

StyleDisabled

StyleFocused

StyleHot

Styles

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TControl

Align


Methods for TcxDBCheckGroup
TcxDBCheckGroup Methods

TcxDBCheckGroup          Legend

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

ValidateEdit


Events for TcxDBCheckGroup
TcxDBCheckGroup Events

TcxDBCheckGroup          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxDBCheckGroup.DataBinding

TcxDBCheckGroup

Specifies a data source connection.

property DataBinding: TcxDBEditDataBinding;

Description

Use the DataBinding property to access a TcxDBEditDataBinding instance used to establish a connection to a data source.  The DataBinding.DataSource property identifies a dataset to which to connect.  The DataBinding.DataField property specifies the data source field whose values are to be displayed by the check group control.


 TcxDefaultEditStyleController

Hierarchy          Properties          Methods          See Also

Represents the style controller which defines the style properties common to all controls that have no style controller assigned.

Unit

cxEdit

TcxDefaultEditStyleController = class(TComponent);

Description

The TcxDefaultEditStyleController class lets you customize the default values of the style attributes for all the controls (editors and style controllers) that have unassigned style attributes (set to their defaults) and have no style controller assigned, i.e. when a default style controller is present and an editor or a style controller has an unassigned style attribute and is not associated with a style controller that specifies this value, the corresponding default style controller’s attribute can be set via the default style controller.

Use the default controller’s Style, StyleDisabled, StyleFocused, StyleHot members to specify the style categories which control the style attributes for the normal, disabled, focused and highlighted (hot-tracked) editor states, respectively.

You can redefine individual style attributes by setting them explicitly via the editor’s TcxCustomEdit.Style, TcxCustomEdit.StyleDisabled, TcxCustomEdit.StyleFocused and TcxCustomEdit.StyleHot properties.  The editor, the style controller and the default style controller each have the AssignedValues property, which specifies whether the style attributes should be obtained from the editor style or from the (default) style controller.  This property represents a set of flags that describe where the style attributes were explicitly assigned: in the editor style, the style controller or the default style controller, respectively.  Editor style attributes have a higher priority than the attributes defined in the style controller, which in turn override the attributes specified in the default style controller.  If a specific style attribute is set both in the editor style and (default) style controller, the editor will obtain the style attribute value from the editor style.

Unlike the style controller, you cannot connect one default style controller to another default style controller.


TcxDefaultEditStyleController Hierarchy
Hierarchy

TComponent

     |


Properties for TcxDefaultEditStyleController
TcxDefaultEditStyleController Properties

TcxDefaultEditStyleController          Legend

In TcxDefaultEditStyleController

 Style

 StyleDisabled

 StyleFocused

 StyleHot

 Styles


Methods for TcxDefaultEditStyleController
TcxDefaultEditStyleController Methods

TcxDefaultEditStyleController          Legend

In TcxDefaultEditStyleController

 RestoreStyles


TcxDefaultEditStyleController.Style

TcxDefaultEditStyleController          See Also

Specifies the style attributes provided by the current default style controller for editors in the normal state.

property Style: TcxEditStyle;

Description

Use the Style property to specify the normal state’s style attributes applied via the default style controller to editors.  To redefine individual style attributes you need to assign values to the corresponding properties via the TcxCustomEdit.Style property.


TcxDefaultEditStyleController.StyleDisabled

TcxDefaultEditStyleController          See Also

Specifies the style attributes provided by the current default style controller for disabled editors.

property StyleDisabled: TcxEditStyleEx;

Description

Use the StyleDisabled property to specify the disabled state’s style attributes applied via the default style controller to editors.  To redefine individual style attributes you need to assign values to the corresponding properties via the TcxCustomEdit.StyleDisabled property.


TcxDefaultEditStyleController.StyleFocused

TcxDefaultEditStyleController          See Also

Specifies the style attributes provided by the current style controller for focused editors.

property StyleFocused: TcxEditStyleEx;

Description

Use the StyleFocused property to specify the focused state’s style attributes applied via the default style controller to editors.  To redefine individual style attributes you need to assign values to the corresponding properties via the TcxCustomEdit.StyleFocused property.


TcxDefaultEditStyleController.StyleHot

TcxDefaultEditStyleController          See Also

Specifies the style attributes provided by the current style controller for the highlighted (hot-tracked) editor.

property StyleHot: TcxEditStyleEx;

Description

Use the StyleHot property to specify the highlighted state’s style attributes applied via the default style controller to editors.  To redefine individual style attributes you need to assign values to the corresponding properties via the TcxCustomEdit.StyleHot property.


TcxDefaultEditStyleController.Styles

TcxDefaultEditStyleController          See Also

Provides access to the styles assigned to the current default style controller.

procedure Styles[AState: TcxContainerStateItem]: TcxCustomEditStyle;

Description

Each style corresponds to a particular control state such as normal, disabled, etc. (see the TcxContainerStateItem type description for details).  The Styles property provides access to the specific style which is assigned to the current default style controller and matches the control state specified by the AState parameter.


TcxDefaultEditStyleController.RestoreStyles

TcxDefaultEditStyleController          See Also

Restores the default values to all the style attributes associated with the current default style controller.

procedure RestoreStyles;

Description

The RestoreStyles method merely calls the RestoreDefaults method for each style defined in the container control (see the Style, StyleDisabled, StyleFocused and StyleHot for details) which is associated with the current default style controller.


cxRichEdit Unit Overview
cxRichEdit Unit

Classes

TcxCustomRichEdit

TcxCustomRichEditProperties

TcxRichEdit

TcxRichEditProperties


TcxCustomRichEdit
TcxCustomRichEdit Object

Hierarchy          Properties          Methods          Events          See Also

Represents the base class for rich edit controls such as the TcxRichEdit and TcxDBRichEdit.

Unit

cxRichEdit

TcxCustomRichEdit = class(TcxCustomMemo);

Description

The TcxCustomRichEdit introduces new properties and methods to expand the capabilities of the TcxCustomMemo for rich text.

Do not create instances of the TcxCustomRichEdit class directly. Instead, use its descendants such as the TcxRichEdit or TcxDBRichEdit.  The TcxCustomRichEdit can be used as a base class for control objects that implement rich text capabilities in an edit control. The properties and methods of the TcxCustomRichEdit provide basic behavior that descendant classes inherit as well as behavior which components can override to customize their behavior.


TcxCustomRichEdit Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMemo

     |


Properties for TcxCustomRichEdit
TcxCustomRichEdit Properties

TcxCustomRichEdit          Legend

In TcxCustomRichEdit

ActiveProperties

CanUndo

DefAttributes

Lines

PageRect

Paragraph

Properties

SelAttributes

Derived from TcxCustomMemo

ActiveProperties

CaretPos

Lines

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxCustomRichEdit
TcxCustomRichEdit Methods

TcxCustomRichEdit          Legend

In TcxCustomRichEdit

FindText

Print

Undo

Derived from TcxCustomTextEdit

Clear

ClearSelection

CopyToClipboard

Create

CutToClipboard

SelectAll

SetSelection

Undo

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

SetSize

ValidateEdit


Events for TcxCustomRichEdit
TcxCustomRichEdit Events

TcxCustomRichEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxCustomRichEdit.ActiveProperties

TcxCustomRichEdit          See Also

Obtains the properties that are currently applied to a rich text editor.

property ActiveProperties: TcxCustomRichEditProperties;

Description

Use the ActiveProperties property to obtain the properties of the current rich text editor that are currently in effect.  This property is especially useful when the rich text 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 rich text editor.  Otherwise, the inherent rich text editor’s properties are returned.

ReadOnly Property


TcxCustomRichEdit.CanUndo

TcxCustomRichEdit          See Also

Indicates whether the rich text editor contains changes that can be reversed.

property CanUndo: Boolean;

Description

Use the CanUndo property to determine whether a user has made any changes to the text that can be undone by calling the Undo method. This is useful when enabling or disabling menu items that correspond to this command.

ReadOnly Property


TcxCustomRichEdit.DefAttributes

TcxCustomRichEdit

Describes the rich text characteristics of the default font for the rich edit control.

property DefAttributes: TTextAttributes;

Description

Use the DefAttributes property to retrieve or set the default font characteristics that the rich edit control uses for newly inserted text.  These are the text’s characteristics before any special attributes have been applied.  Once any special attributes are applied to a portion of text, no text from that point on is considered to have the default attributes, even if the attributes match the DefAttributes property’s values.

For example, if a rich edit control has had no attributes applied, the entire text has the default attributes.  Selecting a portion of text in the middle and applying a specific attribute (such as a font change) results in three sections: a first section with the default attributes, a middle section with the applied attribute, and a final section with a non-default set of attributes that match the default attributes.  Changing the DefAttributes property affects only the first section.

When inserting new text, the font characteristics of the new text will match the font characteristics at the cursor's position, or, if the typed text replaces a selection, the font characteristics of the selected text.  New text will only have the default attributes when typed into the section of text that has the default attributes.

Note:	The DefAttributes property’s values are available only at run time.


TcxCustomRichEdit.Lines

TcxCustomRichEdit

Represents a list of strings displayed by a rich text editor.

property Lines: TStrings;

Description

Use Lines to manipulate text within a rich text control.  Using the methods and properties of the TStrings class, you can add, delete or access a specific line of text.  The Text property is inherited from the TControl class and it allows you to work with all the text at once.


TcxCustomRichEdit.PageRect

TcxCustomRichEdit

Specifies the dimensions (in pixels) of the logical page size used when printing the contents of a rich text edit control.

property PageRect: TRect;

Description

Use the PageRect property to specify the logical page size in pixels used when formatting the contents of the rich edit control for printing.


TcxCustomRichEdit.Paragraph

TcxCustomRichEdit

Specifies the formatting information for the current paragraphs.

property Paragraph: TParaAttributes;

Description

Use the Paragraph property to get the TParaAttributes object used by a rich edit control to specify paragraph formatting information.  Use the TParaAttributes object to read or write the paragraph formatting information for the current paragraphs.  Paragraph formatting information includes alignment, indentation, numbering, and tabs.

Paragraph is a read-only property, because a TcxCustomRichEdit object has only one TParaAttributes object, which cannot be changed.  The attributes of the current paragraphs however can be changed, by setting the properties of the TParaAttributes object.

The current paragraphs are the paragraphs that contain the selected text.  If no text is selected, the current paragraph is the one which contains the cursor.

Note:	The Paragraph property’s values are only available at run time.

ReadOnly Property


TcxCustomRichEdit.Properties

TcxCustomRichEdit          See Also

Defines the settings that are specific to rich text editors.

property Properties: TcxCustomRichEditProperties;

Description

The Properties object specifies various settings for rich text editors.  Use the MemoMode to select the mode for rich text editors, the HideScrollBars member of a Properties instance to hide/display scrollbars only when it’s necessary.  Other properties adjust the alignment and maximum length of the text, char case, etc.


TcxCustomRichEdit.SelAttributes

TcxCustomRichEdit

Describes the rich text characteristics of the selected text in the rich edit control.

property SelAttributes: TTextAttributes;

Description

Use the SelAttributes property to retrieve or set the font characteristics of the currently selected text.  The SelAttributes property specifies the text’s characteristics such as the font face, color, size, style, and pitch.  To change all the attributes of the currently selected text, set the SelAttributes property to a TTextAttributes object that represents the desired attributes configuration.  If no text is selected, the SelAttributes property represents the attributes at the cursor's position.

When inserting new text, the font characteristics of the new text will match the SelAttributes property’s values.

Note:	The SelAttributes property’s values are only available at run time.


TcxCustomRichEdit.FindText

TcxCustomRichEdit

Searches a given range in the text for the specified string.

function FindText(const ASearchStr: string; AStartPos, ALength: Integer; AOptions: TSearchTypes): Integer;

Description

Use the FindText function to search the range of text in a rich edit control for the string specified by the ASearchStr parameter.  Only the text in the range starting at the AStartPos position and continuing through to the next ALength positions will be searched.  Assign the AOptions parameter to specify whether the search should match whole words only and whether the search should be case sensitive.  The FindText function returns the zero-based position of the search string, as opposed to the first position in the search range.  If the search string does not appear in the indicated range, this function returns -1.

Use the FindText function rather than programmatically searching through the text of the control, to avoid false results caused by the encoding of rich text characteristics.


TcxCustomRichEdit.Print

TcxCustomRichEdit

Formats and prints the contents of the rich edit control.

procedure Print(const Caption: string); virtual;

Description

Use the Print method to print the contents of a rich edit control.  The Caption parameter specifies the title that appears in the print manager and on network title pages.


TcxCustomRichEdit.Undo

TcxCustomRichEdit          See Also

Reverses the last change made to the text using the undo buffer.

procedure Undo; override;

Description

Call the Undo method to cancel the last change made to the text.  To determine whether there are any changes in the undo buffer, check the CanUndo property.


TcxCustomRichEditProperties
TcxCustomRichEditProperties Object

Hierarchy          Properties          Methods          Events          See Also

Contains settings specific to rich text edit controls.

Unit

cxRichEdit

TcxCustomRichEditProperties = class(TcxCustomMemoProperties);

Description

The TcxCustomRichEditProperties class extends the TcxCustomMemoProperties functionality and provides additional properties specific to rich text edit controls.  To set rich text edit properties, use the Properties member of a corresponding editor class.  The TcxRichEditProperties class is derived from TcxCustomRichEditProperties and publishes the members that need to be accessed from the TcxRichEdit editors.

The TcxCustomRichEditProperties class extends the settings common to all rich text edit controls (the Alignment, ScrollBars, VisibleLineCount, WantReturns, WantTabs and WordWrap properties) with additional ones such as the HideScrollBars, MemoMode, PlainText and SelectionBar properties.


TcxCustomRichEditProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMemoProperties

     |


Properties for TcxCustomRichEditProperties
TcxCustomRichEditProperties Properties

TcxCustomRichEditProperties          Legend

In TcxCustomRichEditProperties

HideScrollBars

MemoMode

PlainText

SelectionBar

Derived from TcxCustomMemoProperties

Alignment

AutoSelect

ScrollBars

VisibleLineCount

WantReturns

WantTabs

WordWrap

Derived from TcxCustomTextEditProperties

AssignedValues

CharCase

DisplayFormat

EchoMode

EditFormat

HideCursor

HideSelection

ImeMode

ImeName

IncrementalSearch

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 TcxCustomRichEditProperties
TcxCustomRichEditProperties Methods

TcxCustomRichEditProperties          Legend

Derived from TcxCustomTextEditProperties

IsDisplayValueValid

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue


Events for TcxCustomRichEditProperties
TcxCustomRichEditProperties Events

TcxCustomRichEditProperties          Legend

In TcxCustomRichEditProperties

OnProtectChange

OnResizeRequest

OnSaveClipboard

OnSelectionChange

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxCustomRichEditProperties.HideScrollBars

TcxCustomRichEditProperties

Determines whether the scroll bars disappear when they are not needed.

property HideScrollBars: Boolean;

Description

Use the HideScrollBars property to determine whether the scroll bars disappear from the edit control when the text appears completely within the edit window.  Set the HideScrollBars property to False to prevent the scroll bars from flashing on and off when the contents of the rich edit control change.

This HideScrollBars does nothing when the Properties.ScrollBars property is set to ssNone (The default value for the TcxRichEdit object).

The default value of the HideScrollBars property is True.


TcxCustomRichEditProperties.MemoMode

TcxCustomRichEditProperties

Specifies whether the rich text editor is in memo mode or rich text mode.

property MemoMode: Boolean;

Description

Set the MemoMode property to True to switch the rich text editor to memo mode.  This automatically turns the editor’s text into plain text thus losing any applied formatting.  Otherwise, the text appears as rich text.  Switching to rich mode also affects the multilevel undo feature’s behavior in such a way that the subsequent operations which are of the same type (for instance, text editing, insertion or deletion) are undone all together (as a group) rather than one by one in memo mode.

Note:	It is recommended that customizing text style attributes such as the TextColor and TextStyle is done in memo mode only.

The default value of the MemoMode property is False.


TcxCustomRichEditProperties.PlainText

TcxCustomRichEditProperties

Controls whether the rich edit control treats the text as plain text or rich text when getting or inserting it into a stream.

property PlainText: Boolean;

Description

To write the rich text in the control to a plain text file, set the PlainText property to True before getting or inserting it to a stream.  To ignore the rich text information in a stream, set the PlainText property to True before streaming the text to the control.  To stream in the rich text attributes, or save the encoding of the rich text attributes to a stream, set the PlainText property to False.

If the rich text attributes in a stream are encoded in some format other than rich text format (RTF), it is necessary to use a converter on the text, even when the PlainText property is set to True.

Note:	Rich edit controls do not directly support streaming.  Use the Lines property to stream to or from a file.

The default value of the PlainText property is False.


TcxCustomRichEditProperties.SelectionBar

TcxCustomRichEditProperties

Controls the visibility of the selection bar within a rich text editor.

property SelectionBar: Boolean;

Description

The selection bar is a special blank region which helps a user select entire lines within the rich text editor using the mouse.  The selection bar is displayed at the left edge of the rich text editor.  By hovering the mouse cursor over the selection bar and holding down the left mouse button while moving the mouse, an end-user can select lines within the editor.

Set the SelectionBar property to True to make it visible within the editor.  Otherwise, it will be hidden.

The following table shows the manner in which two lines in the rich text editor are selected using the selection bar.

Property’s Value	False	True

The default value of the SelectionBar property is False.


TcxCustomRichEditProperties.OnProtectChange

TcxCustomRichEditProperties

Occurs when a user attempts to modify text that is marked as protected.

type

  TRichEditProtectChange = procedure(Sender: TObject; StartPos, EndPos: Integer; var AllowChange: Boolean) of object;

property OnProtectChange: TRichEditProtectChange;

Description

Handle the OnProtectChange event to allow text with the protected attribute to be modified.  The StartPos and EndPos parameters indicate the beginning and end of the range of text that will be affected by the modification, where 0 is the first character in the text.  To allow protected text to be modified, set the AllowChange parameter to True.

To set or unset the protected attribute for a section of text, select the text and use the Protected property of the rich edit control’s SelAttributes property.  To cause text to have the protected attribute by default, use the Protected property of the rich edit object’s DefAttributes property.


TcxCustomRichEditProperties.OnResizeRequest

TcxCustomRichEditProperties

Occurs when the text in a control has grown either too small or too large for the control's window size.

type

  TRichEditResizeEvent = procedure(Sender: TObject; Rect: TRect) of object;

property OnResizeRequest: TRichEditResizeEvent;

Description

Handle the OnResizeRequest event to respond to notifications that the edit control is trying to resize due to changes in the text.  The Rect parameter gives the desired bounding rectangle that will display all the text, in screen coordinates.


TcxCustomRichEditProperties.OnSaveClipboard

TcxCustomRichEditProperties

Occurs when the window of the rich text edit control is about to be destroyed and the edit control has delayed rendering of the text copied to the clipboard.

type

  TRichEditSaveClipboard = procedure(Sender: TObject; NumObjects, NumChars: Integer; var SaveClipboard: Boolean) of object;

property OnSaveClipboard: TRichEditSaveClipboard;

Description

Handle the OnSaveClipboard event to respond to notifications that the window of the edit control is about to be destroyed and the clipboard needs information from the edit control.  The NumObjects parameter is the number of objects on the clipboard, and the NumChars parameter represents the number of characters on the clipboard.  To clear all the information about the edit control from the clipboard, set the SaveClipboard parameter to False.


TcxCustomRichEditProperties.OnSelectionChange

TcxCustomRichEditProperties

Occurs when the current selection changes.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnSelectionChange: TNotifyEvent;

Description

Handle the OnSelectionChange event to respond to changes in the selected text.  Changes in selection occur when the user changes the selection using the mouse or keyboard, or when the selection is changed via the SelText property.  Portions of the selection can be changed via the Lines property.


TcxRichEditProperties
TcxRichEditProperties Object

Hierarchy          Properties          Methods          Events          See Also

Represents settings specific to rich text editors.

Unit

cxRichEdit

TcxRichEditProperties = class(TcxCustomRichEditProperties);

Description

The TcxRichEditProperties class provides various settings which are specific to rich text editors.  Rich text editors are presented by the TcxCustomRichEdit class's descendants, such as the TcxRichEdit and TcxDBRichEdit.  TcxRichEditProperties does not introduce any new functionality, but instead publishes the necessary properties and events inherited from base classes.  To set rich text properties, use the Properties member of a corresponding editor class.  To control any changes made to the editor’s DisplayFormat, EditFormat, MaxLength, MaxValue, MinValue and ReadOnly properties and reverse their values back to the default ones, use the AssignedValues property.

The TcxCustomRichEditProperties class extends the settings common to all rich text edit controls (the Alignment, ScrollBars, VisibleLineCount, WantReturns, WantTabs and WordWrap properties) with additional ones such as the HideScrollBars, MemoMode, PlainText and SelectionBar properties.


TcxRichEditProperties Hierarchy
Hierarchy

TcxInterfacedPersistent

     |

TcxCustomEditProperties

     |

TcxCustomTextEditProperties

     |

TcxCustomMemoProperties

     |

TcxCustomRichEditProperties

     |


Properties for TcxRichEditProperties
TcxRichEditProperties Properties

TcxRichEditProperties          Legend

Derived from TcxCustomRichEditProperties

HideScrollBars

MemoMode

PlainText

SelectionBar

Derived from TcxCustomMemoProperties

Alignment

AutoSelect

ScrollBars

VisibleLineCount

WantReturns

WantTabs

WordWrap

Derived from TcxCustomTextEditProperties

AssignedValues

CharCase

DisplayFormat

EchoMode

EditFormat

HideCursor

HideSelection

ImeMode

ImeName

IncrementalSearch

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 TcxRichEditProperties
TcxRichEditProperties Methods

TcxRichEditProperties          Legend

Derived from TcxCustomTextEditProperties

IsDisplayValueValid

Derived from TcxCustomEditProperties

BeginUpdate

CanModify

CanValidate

EndUpdate

GetButtonsClass

GetContainerClass

GetStyleClass

GetViewInfoClass

IsEditValueValid

RestoreDefaults

ValidateDisplayValue


Events for TcxRichEditProperties
TcxRichEditProperties Events

TcxRichEditProperties          Legend

Derived from TcxCustomRichEditProperties

OnProtectChange

OnResizeRequest

OnSaveClipboard

OnSelectionChange

Derived from TcxCustomTextEditProperties

OnNewLookupDisplayText

Derived from TcxCustomEditProperties

OnButtonClick

OnChange

OnEditValueChanged

OnPropertiesChanged

OnValidate


TcxRichEdit
 TcxRichEdit Object

Hierarchy          Properties          Methods          Events          See Also

Represents an edit control which allows rich text to be edited.

Unit

cxRichEdit

TcxRichEdit = class(TcxCustomRichEdit);

Description

The TcxRichEdit control represents an editor, which lets you customize the standard text layout with font attributes and paragraph formatting variations.  It provides the Lines property which defines the list of strings displayed by a rich text editor.

The Properties member defines a number of settings that are specific to rich text editors.  They define the text's alignment, the maximum text length, read-only status and many others.  The behavior of a rich text editor control is similar to the standard TRichEdit component.

Use the Style, StyleDisabled, StyleFocused and StyleHot properties to adjust the look & feel of a rich text editor in various control’s states.  Working with styles is discussed in the TcxCustomEditStyle class topic.


TcxRichEdit Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMemo

     |


Properties for TcxRichEdit
TcxRichEdit Properties

TcxRichEdit          Legend

Derived from TcxCustomRichEdit

ActiveProperties

CanUndo

DefAttributes

Lines

PageRect

Paragraph

Properties

SelAttributes

Derived from TcxCustomMemo

ActiveProperties

Lines

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName

Derived from TControl

Align


Methods for TcxRichEdit
TcxRichEdit Methods

TcxRichEdit          Legend

Derived from TcxCustomRichEdit

FindText

Print

Undo

Derived from TcxCustomTextEdit

Clear

ClearSelection

CopyToClipboard

Create

CutToClipboard

SelectAll

SetSelection

Undo

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

SetSize

ValidateEdit


Events for TcxRichEdit
TcxRichEdit Event

TcxRichEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


cxDBRichEdit Unit Overview
cxDBRichEdit Unit

Classes

TcxDBRichEdit


TcxDBRichEdit
 TcxDBRichEdit Object

Hierarchy          Properties          Methods          Events          See Also

Represents a data-aware version of the TcxRichEdit control.

Unit

cxDBRichEdit

TcxDBRichEdit = class(TcxCustomRichEdit);

Description

The TcxDBRichEdit control is a data-aware version of the TcxRichEdit control.  The TcxRichEdit control is an editor, which lets you customize the standard text layout with font attributes and paragraph formatting variations.

To connect a data-aware control to a dataset, set the DataSource and DataField properties of the DataBinding object.

The TcxDBRichEdit control provides the Lines property which defines the list of strings displayed by a rich text editor.  The Properties member defines a number of settings specific to rich text editors.  They define the text's alignment, the maximum text length, read-only status and various others settings.  The behavior of a rich text editor control is similar to the standard TRichEdit component.

Use the Style, StyleDisabled, StyleFocused and StyleHot properties to control the look & feel of a rich text editor depending upon its state.  Working with styles is discussed in the TcxCustomEditStyle class topic.


TcxDBRichEdit Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxContainer

     |

TcxCustomEdit

     |

TcxCustomTextEdit

     |

TcxCustomMemo

     |


Properties for TcxDBRichEdit
TcxDBRichEdit Properties

TcxDBRichEdit          Legend

In TcxDBRichEdit

DataBinding

Derived from TcxCustomRichEdit

ActiveProperties

CanUndo

DefAttributes

Lines

PageRect

Paragraph

Properties

SelAttributes

Derived from TcxCustomMemo

ActiveProperties

Lines

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

Transparent

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

ImeMode

ImeName

Derived from TControl

Align


Methods for TcxDBRichEdit
TcxDBRichEdit Methods

TcxDBRichEdit          Legend

Derived from TcxCustomRichEdit

FindText

Print

Undo

Derived from TcxCustomTextEdit

Clear

ClearSelection

CopyToClipboard

Create

CutToClipboard

SelectAll

SetSelection

Undo

Derived from TcxCustomEdit

AdjustInnerEditPosition

AreChangeEventsLocked

CanModify

Clear

CopyToClipboard

Create

CreateInnerEdit

CutToClipboard

Destroy

DoButtonClick

DoButtonDown

DoButtonUp

DoEditKeyDown

DoEditKeyPress

DoEditKeyUp

DoOnChange

DoOnEditValueChanged

GetInnerEditClass

GetPropertiesClass

IsValidChar

LockChangeEvents

LockEditValueChanging

PasteFromClipboard

PostEditValue

PropertiesChanged

RefreshEdit

ResetEditValue

SelectAll

SetSize

ValidateEdit


Events for TcxDBRichEdit
TcxDBRichEdit Event

TcxDBRichEdit          Legend

Derived from TcxCustomEdit

OnEditing

OnFocusChanged


TcxDBRichEdit.DataBinding

TcxDBRichEdit

Specifies the dataset connection.

type

   TcxDBRichEditDataBinding = class(TcxDBTextEditDataBinding);

property DataBinding: TcxDBRichEditDataBinding;

Description

Use the DataBinding property to access a TcxDBRichEditDataBinding which is a descendant of the TcxDBTextEditDataBinding class to establish a connection to a dataset.  You should use the DataSource and DataField properties of the DataBinding object to enable the TcxDBRichEdit control to edit a specific field value from the dataset.


cxShellControls Unit Overview
cxShellControls Unit

Classes

TcxShellListViewOptions


TcxShellListViewOptions
TcxShellListViewOptions Object

Hierarchy          Properties

Represents the shell list view options.

Unit

cxShellControls

TcxShellListViewOptions = class(TcxShellOptions)

Description

The TcxShellListViewOptions class contains options specific to the shell list view controls.  This class inherits its basic functionality from the TcxShellOptions class.  It also introduces the AutoNavigate property, determining the shell list view response to double-clicking an item.


TcxShellListViewOptions Hierarchy
Hierarchy

TPersistent

     |

TcxShellOptions

     |


Properties for TcxShellListViewOptions
TcxShellListViewOptions Properties

TcxShellListViewOptions          Legend

In TcxShellListViewOptions

AutoNavigate

Derived from TcxShellOptions

ContextMenus

ShowFolders

ShowHidden

ShowNonFolders

ShowToolTip

TrackShellChanges


TcxShellListViewOptions.AutoNavigate

TcxShellListViewOptions

Determines whether the shell list view automatically activates the double-clicked shell item.

property AutoNavigate: Boolean;

Description

Use the AutoNavigate property to specify whether the double-clicked shell item is automatically activated by a shell list view.  Shell items activation means:

•	browsing folder shell items;

•	launching the default associated program for the file shell items.

If this option is deactivated, then you can handle the OnDblClick event to process double-clicking within the control.

The default value of the AutoNavigate property is True.


cxInplaceContainer Unit Overview
cxInplaceContainer Unit

Classes

TcxControlDataController

TcxControlOptionsBehavior

TcxControlOptionsData

TcxControlOptionsView

TcxCustomControlStyles

TcxCustomEditContainerItemOptions

TcxCustomHitTestController

TcxCustomInplaceEditContainer

TcxCustomItemDataBinding

TcxCustomViewInfoItem

TcxEditCellViewInfo

TcxEditContainerStyles

TcxEditingControl

TcxExtEditingControl

TcxItemDataBinding


TcxControlDataController
TcxControlDataController Object

Hierarchy          Properties          Methods           Events

Represents a data controller for a data-aware control.

Unit

cxInplaceContainer

TcxControlDataController = class(TcxDataController);

Description

The data controller is an object, which provides access to data in a data storage thus enabling you to operate with it.  The TcxControlDataController class inherits all the functionality of the TcxDataController class and introduces facilities for sending notifications from the data source to an editing control on data changes such as inserting, deleting or editing.


TcxControlDataController Hierarchy
Hierarchy

TPersistent

     |

TcxCustomDataController

     |

TcxDataController

     |


Properties for TcxControlDataController
TcxControlDataController Properties

TcxControlDataController          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 TcxControlDataController
TcxControlDataController Methods

TcxControlDataController          Legend

Derived from TcxCustomDataController

Append

AppendRecord

BeginFullUpdate

BeginUpdate

BeginUpdateFields

Cancel

ChangeDetailExpanding

ChangeRowSelection

CheckFocusedSelected

ClearBookmark

ClearDetailLinkObject

ClearDetails

ClearSelection

ClearSorting

CollapseDetails

DeleteFocused

DeleteRecord

DeleteSelection

Edit

EndUpdateFields

EndFullUpdate

EndUpdate

FindRecordIndexByText

ForEachRow

FocusDetails

GetDetailDataController

GetMasterDataController

GetMasterRecordIndex

GetPatternDataController

GetRowDisplayText

GetRowIndexByRecordIndex

GetRowInfo

GetRowValue

GetSelectedCount

GetSelectedRowIndex

GotoBookmark

GotoFirst

GotoLast

GotoNext

GotoPrev

Insert

InsertRecord

IsBOF

IsBookmarkAvailable

IsDetailMode

IsEOF

IsGridMode

IsRowSelected

LoadFromStream

MakeRecordVisible

Post

RefreshExternalData

SaveBookmark

SaveToStream

SelectAll

SelectRows

SetEditValue

SetValue

SyncSelected


Events for TcxControlDataController
TcxControlDataController Events

TcxControlDataController          Legend

Derived from TcxCustomDataController

OnAfterCancel

OnAfterDelete

OnAfterInsert

OnAfterPost

OnBeforeCancel

OnBeforeDelete

OnBeforeInsert

OnBeforePost

OnCompare

OnDataChanged

OnDetailCollapsed

OnDetailCollapsing

OnDetailExpanded

OnDetailExpanding

OnFilterRecord

OnGroupingChanged

OnNewRecord

OnRecordChanged

OnSortingChanged


TcxControlOptionsBehavior
TcxControlOptionsBehavior Object

Hierarchy          Properties          See Also

Contains common settings for customizing the control's behavior.

Unit

cxInplaceContainer

TcxControlOptionsBehavior = class(TcxOwnedPersistent);

Description

The TcxControlOptionsBehavior class contains settings determining the control's response to user actions via the keyboard and mouse.  Controls owning TcxControlOptionsBehavior objects represent data by cells.


TcxControlOptionsBehavior Hierarchy
Hierarchy

TPersistent

     |

TcxOwnedPersistent

     |


Properties for TcxControlOptionsBehavior
TcxControlOptionsBehavior Properties

TcxControlOptionsBehavior          Legend

In TcxControlOptionsBehavior

AlwaysShowEditor

CellHints

DragDropText

FocusCellOnCycle

FocusFirstCellOnNewRecord

GoToNextCellOnEnter

GoToNextCellOnTab

ImmediateEditor

IncSearch

IncSearchItem


TcxControlOptionsBehavior.AlwaysShowEditor

TcxControlOptionsBehavior

Determines whether the focused cell’s editor is always active.

property AlwaysShowEditor: Boolean;

Description

Use this property to make the focused cell’s editor always active.  It means that you shouldn't press Enter or F2 to enable cell editing.

This option is not in effect if editing is disabled within an editing control.

The default value of the AlwaysShowEditor property is False.


TcxControlOptionsBehavior.CellHints

TcxControlOptionsBehavior

Specifies whether a hint is displayed for a cell when the text does not fit into the cell’s area.

property CellHints: Boolean;

Description

If the CellHints property is set to True, pointing to the cells, whose text is displayed partially, results in displaying a hint window with the entire cell text.  Otherwise, cell hints are not displayed.

The default value of the CellHints property is False.


TcxControlOptionsBehavior.DragDropText

TcxControlOptionsBehavior

Specifies whether an image of the currently dragged object is being layered over the control.

property DragDropText: Boolean;

Description

If the value of this property is True the image of the currently dragged object is visible.

The default value of the DragDropText property is False.


TcxControlOptionsBehavior.FocusCellOnCycle

TcxControlOptionsBehavior

Determines the manner in which edit cells are focused.

property FocusCellOnCycle: Boolean;

Description

Set the FocusCellOnCycle property to True to enable moving focus to the next row after it reaches the last edit cell within the current row.  Otherwise, focus is moved to the first edit cell of the current row.

The default value of the FocusCellOnCycle property is False.


TcxControlOptionsBehavior.FocusFirstCellOnNewRecord

TcxControlOptionsBehavior

Determines the manner in which focus is positioned within the newly created row.

property FocusFirstCellOnNewRecord: Boolean;

Description

New added records are automatically focused.  If the FocusCellOnNewRecord property is set to True, focus is moved to the first cell within the record.  Otherwise, the cell focus is not changed.

The default value of the FocusFirstCellOnNewRecord property is False.


TcxControlOptionsBehavior.GoToNextCellOnEnter

TcxControlOptionsBehavior          See Also

Determines whether control items can be navigated by using the Enter key.

property GoToNextCellOnEnter: Boolean;

Description

Use the GoToNextCellOnEnter property to enable control item navigation by using the Enter key.

The default value of the GoToNextCellOnEnter property is False.


TcxControlOptionsBehavior.GoToNextCellOnTab

TcxControlOptionsBehavior          See Also

Determines whether the Tab key is used to navigate through the current editing control cells.

property GoToNextCellOnTab: Boolean;

Description

Set the FocusCellOnTab property to True to enable moving through cells using the Tab key.  If set to False, pressing the Tab key results in moving focus to the next control in the tab order.

The default value of the GoToNextCellOnTab property is False.


TcxControlOptionsBehavior.ImmediateEditor

TcxControlOptionsBehavior

Determines whether the appropriate editor is activated immediately after an edit cell is clicked.

property ImmediateEditor: Boolean;

Description

Set the ImmediateEditor property to True to activate an editor when a user clicks an edit cell.  If set to False, clicking a cell only focuses it.  To invoke the cell’s editor, one more click is required.

The default value of the ImmediateEditor property is True.


TcxControlOptionsBehavior.IncSearch

TcxControlOptionsBehavior          See Also

Specifies whether a user can perform incremental search within an editing control.

property IncSearch: Boolean;

Description

Set the IncSearch property to True to enable the incremental search feature.  If enabled, end users can locate records by typing cell values.  When typing, the control automatically finds the closest match and focuses the corresponding record.  If the IncSearch property is False, a user cannot locate records this way.  The IncSearchItem property specifies whether incremental search can be performed by individual items (treelist columns) and overrides the editing control’s behavior.

If the IncSearchItem property is not specified, the incremental search is performed by the currently focused item.

The default value of the IncSearch property is False.


TcxControlOptionsBehavior.IncSearchItem

TcxControlOptionsBehavior          See Also

Specifies the item against which incremental search is performed.

property IncSearchItem: TcxCustomInplaceEditContainer;

Description

The incremental search feature allows the end user to locate the required record by a specific item value.  In order to enable the incremental search functionality for an editing control, you should set the IncSearch property to True.  The IncSearchItem property specifies the item to which incremental search is applied. A user can find the desired node (row) by typing the beginning of the required value. The cell containing the typed value will be located within the item and the corresponding record will be focused.


TcxControlOptionsData
TcxControlOptionsData Object

Hierarchy          Properties          See Also

Contains settings determining the functionality of data-aware editing control descendants.

Unit

cxInplaceContainer

TcxControlOptionsData = class(TPersistent)

Description

The TcxControlOptionsData class contains common settings determining the functionality of data-aware editing control descendants.  For instance, the TreeList control is a data-aware and data-representing control.  It can be connected to a database and represent data by cells:

The TcxControlOptionsData class provides settings that determine whether data can be edited (the Editing property).

A data-aware control has the OptionsData property representing a TcxControlOptionsData descendant.

Data-aware controls inherit their data options to implement specific options.


TcxControlOptionsData Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxControlOptionsData
TcxControlOptionsData Properties

TcxControlOptionsData          Legend

In TcxControlOptionsData

CancelOnExit

Editing


TcxControlOptionsData.CancelOnExit

TcxControlOptionsData

Determines whether empty records are posted to a dataset when a control loses focus.

property CancelOnExit: Boolean;

Description

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

The default value of the CancelOnExit property is True.


TcxControlOptionsData.Editing

TcxControlOptionsData

Determines whether a user can edit data within a control.

property Editing: Boolean;

Description

The Editing property determines whether data represented within a control can be edited.  CX controls supporting the in-place editor technology use this property to prevent in-place editors from editing data.  Data cells can still represent data by means of in-place editors but a user is not allowed to modify it.

The default value of the Editing property is True.


TcxControlOptionsView
TcxControlOptionsView Object

Hierarchy          Properties          See Also

Contains common settings for customizing the CX control’s appearance.

Unit

cxInplaceContainer

TcxControlOptionsView = class(TPersistent)

Description

The TcxControlOptionsView class contains common settings for customizing the editing control's appearance that supports in-place editors. (for instance, the TreeList).

The TcxControlOptionsView class provides settings that allow you to customize the editing control’s appearance.  The editing control has the OptionsView property representing a TcxControlOptionsView descendant.  TcxControl descendants inherit their view options to implement control-specific options.

Common options assume that a control represents data in data cells, so all general options are cell related:

•	CellAutoHeight - determines whether the cell height (while the width is fixed) is automatically calculated to accommodate its contents.

•	CellEndEllipsis - determines whether the cell text is clipped with the ellipsis if it does not fit into the cell’s area.

•	CellTextMaxLineCount - determines the maximum number of text lines within a data cell if the CellAutoHeight property is True.

The text line height (and the cell height) is calculated according to the font size and the cell style. These settings can be changed by modifying the TcxCustomControlStyles.Content property. When custom drawing a cell, you should manually adjust the cell size.


TcxControlOptionsView Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxControlOptionsView
TcxControlOptionsView Properties

TcxControlOptionsView          Legend

In TcxControlOptionsView

CellAutoHeight

CellEndEllipsis

CellTextMaxLineCount

ScrollBars

ShowEditButtons


TcxControlOptionsView.CellAutoHeight

TcxControlOptionsView          See Also

Determines whether the cell height (while the width is fixed) is automatically calculated to accommodate its contents.

property CellAutoHeight: Boolean;

Description

The CellAutoHeight option assumes that a control represents data in data cells.  If the control's cell width is smaller than the cell content width, the content is clipped.  The clipping method for text cells is determined by the CellEndElipsis property. If the CellEndElipsis property is set to true, the text is clipped with the ellipsis.

You can set the CellAutoHeight property to True to allow a cell to automatically change the text lines count (cell height) while the cell width remains unchanged to accommodate the whole text without its clipping.

You can limit the number of text lines by setting the CellTextMaxLineCount property to a value different from zero. The CellTextMaxLineCount value will determine the maximum text lines count within a cell. If the number of text lines within a cell is less than the CellTextMaxLineCount property value, the line count remains unchanged.

Cells containing images adjust their height to accommodate the whole images.

The default value of the CellAutoHeight property is False.


TcxControlOptionsView.CellEndEllipsis

TcxControlOptionsView          See Also

Determines whether to clip cell text with the ellipsis.

property CellEndEllipsis: Boolean;

Description

The CellEndEllipsis option assumes that a control represents textual data in data cells.  Use the CellEndEllipsis property to determine whether to clip the text that exceeds the cell width with the ellipsis.

The default value of the CellEndEllipsis property is False.


TcxControlOptionsView.CellTextMaxLineCount

TcxControlOptionsView          See Also

Determines the maximum number of text lines for cells when in CellAutoHeight mode.

property CellTextMaxLineCount: Integer;

Description

If the CellAutoHeight property is set to True, the cell's text lines and its height are calculated automatically based on the text size. In this case, you can limit the number of text lines via the CellTextMaxLineCount property.

If the CellTextMaxLineCount property is 0, the cell height is calculated to accommodate its contents.

If the CellAutoHeight property is set to False, the CellTextMaxLineCount property has no effect.

The default value of the CellTextMaxLineCount property is 0.


TcxControlOptionsView.ScrollBars

TcxControlOptionsView

Specifies scroll bars to display within a CX control.

property ScrollBars: TScrollStyle;

Description

The ScrollBars property determines scroll bars to display within a CX control.

Scroll bars appear if the control's contents exceed a bounding rectangle.  Scroll bars can be horizontal, vertical or both:

The default value of the ScrollBars property is ssBoth.


TcxControlOptionsView.ShowEditButtons

TcxControlOptionsView

Specifies the manner in which editors are displayed within cells.

type

  TcxEditingControlEditShowButtons = (ecsbAlways, ecsbFocused, ecsbNever);

property ShowEditButtons: TcxEditingControlEditShowButtons;

Description

If an in-place cell editor has buttons, you can enable their display for a focused cell or for all item cells.  Set the ShowEditButtons property to the appropriate value to specify the manner in which editor buttons are displayed within the control.

There are three settings available:

Value	Description
ecsbNever	Editor buttons are not displayed.
ecsbAlways	Editor buttons are always visible.
ecsbFocused	Editor buttons are visible only for cells within the focused record.

The default value of the ShowEditButtons property is ecsbNever.


TcxCustomControlStyles
TcxCustomControlStyles Object

Hierarchy          Properties          Events

Implements the common functionality and properties for editing control styles.

Unit

cxInplaceContainer

TcxCustomControlStyles = class(TcxStyles)

Description

An editing control (a TcxEditingControl descendant) can consist of many elements.  In this case, every control's visual element has its own style. Styles are used to modify the editing control’s appearance.  An element style consists of background color or background image, text color and text font. Of course, not every visual element contains text. So text color and font properties are useless for this element.

The TcxCustomControlStyles class inherits the Values property that allows you to access all styles within the styles collection by the zero-based index, but also TcxCustomControlStyles provides a more comprehensive way to access styles.  Each style within the collection is represented by the corresponding property. (the control’s background style is represented by the Background property, the control’s content style is represented by the Content property etc.).

TcxCustomControlStyles class descendants are used in editing controls via their Styles property.

You shouldn't create a TcxCustomControlStyles class or its descendant; they are created automatically by editing controls.

You can inherit from the TcxCustomControlStyles class to create a styles collection for your own control.


TcxCustomControlStyles Hierarchy
Hierarchy

TcxStyles

     |


Properties for TcxCustomControlStyles
TcxCustomControlStyles Properties

TcxCustomControlStyles          Legend

In TcxCustomControlStyles

Background

Content

Control

Inactive

Selection

Derived from TcxCustomStyles

StyleSheet


Events for TcxCustomControlStyles
TcxCustomControlStyles Events

TcxCustomControlStyles          Legend

In TcxCustomControlStyles

OnGetContentStyle


TcxCustomControlStyles.Background

TcxCustomControlStyles

Represents an editing control’s background style.

property Background: TcxStyle;

Description

The Background property allows you to define the background style (background image or background color) for the editing control.


TcxCustomControlStyles.Content

TcxCustomControlStyles

Represents an editing control’s content style.

property Content: TcxStyle;

Description

The Content property allows you to define the content style (text font and text color, background image or background color) for the editing control.  In data representing controls, such as treelist, the content style is applied to data representing cells.

There is a remark for the controls that support in-place editors (treelist):

As an in-place editor has its own painter, it is painted by its own means. Additionally, the in-place editor painter is aware of the control’s content style. So it paints an editor according to all style settings (text font and color and background color) except the background bitmap when an editor is active.

You can custom paint the content via the OnGetContentStyle event. This event is fired when the editing control content is about to be painted. You can pass the custom style as its AStyle parameter and the content will be painted according to the passed style settings.


TcxCustomControlStyles.Control

TcxCustomControlStyles

Accesses an editing control.

property Control: TcxEditingControl;

Description

The Control property allows you to access the editing control’s properties and methods.

This property is used by the internal control infrastructure to notify the control of style changes.

ReadOnly Property


TcxCustomControlStyles.Inactive

TcxCustomControlStyles

Specifies the selection style applied when an editing control is not focused.

property Inactive: TcxStyle;

Description

The Inactive property allows you to define the selection style (text font and color, background color or image) when an editing control is not active (not focused).


TcxCustomControlStyles.Selection

TcxCustomControlStyles

Specifies the selection style within an editing control.

property Selection: TcxStyle;

Description

The Selection property allows you to define the selection style (text font and color, background color or image) within the current editing control when it is active (focused).


TcxCustomControlStyles.OnGetContentStyle

TcxCustomControlStyles

Fires when the editing control content is about to be painted.

type

  TcxOnGetContentStyleEvent = procedure(Sender: TObject; AData: Pointer; out AStyle: TcxStyle) of object;

property OnGetContentStyle: TcxOnGetContentStyleEvent;

Description

The OnGetContentStyle event occurs every time the editing control content is about to be painted. This allows you to substitute the assigned content style for any other style.

Data-representing editing controls (TreeList) use the content style for data-representing cells. The event is fired when a single cell needs to be repainted. This allows you to change the style for every visible data cell.

To change the content style, you should write an event handler that passes an EXISTING TcxStyle class instance to the control via the AStyle parameter. Note that the AStyle parameter doesn't represent any TcxStyle instance and is nil by default. So you couldn't implement the following code:

AStyle.Assign(MyStyle) or AStyle.Color := clBlack

before assigning a TcxStyle instance to it.

The following code is not recommended either:

AStyle := TcxStyle.Create;

In this case, a TcxStyle instance will be created every time the event occurs and will be never deleted until the application termination. Implementing the above code creates excessive TcxStyle instances and excessive memory usage as a result. The proper method is to create a TcxStyle instance outside the event handler but pass it to the control via the AStyle parameter within the event handler.  For instance, you can use the StylesRepository  class to create and store your custom styles.

The Sender parameter of the event contains the editing control that owns the styles collection.

The AData parameter is reserved in this event. You can use it in your own controls to pass specific event data. Editing controls override the OnGetContentStyle event where the AData parameter is replaced with the parameters specific to the control. See the TcxTreeListStyles.OnGetContentStyle event for details.


TcxCustomEditContainerItemOptions
TcxCustomEditContainerItemOptions Object

Hierarchy          Properties

Represents a set of options common to editing control items.

Unit

cxInplaceContainer

TcxCustomEditContainerItemOptions = class(TPersistent)

Description

The TcxCustomEditContainerItemOptions class provides settings controlling the user's capability to manipulate editing control items and specify their appearance.

To customize settings for an item, use the Options property of this item. The ‘item’ term meaning can be different for various CX controls.  In TreeList, ‘item’ refers to a column.

You can also set options common to all editing control items via its OptionsCustomizing, OptionsSelection, OptionsData and OptionsView properties.


TcxCustomEditContainerItemOptions Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxCustomEditContainerItemOptions
TcxCustomEditContainerItemOptions Properties

TcxCustomEditContainerItemOptions          Legend

In TcxCustomEditContainerItemOptions

Customizing

Editing

Filtering

Focusing

IncSearch

Moving

ShowEditButtons

Sorting

TabStop


TcxCustomEditContainerItemOptions.Customizing

TcxCustomEditContainerItemOptions

Specifies whether an item can be moved to the customization box.

property Customizing: Boolean;

Description

A CX control may provide a customization box for some items.  The customization box is usually a separate form listing elements, which are not displayed within the control.  For instance, in the treelist control the customization box stores invisible columns.

If this property is set to True, a user can place elements into the customization box.  Otherwise, such actions are prohibited.

The default value of the Customizing property is True.


TcxCustomEditContainerItemOptions.Editing

TcxCustomEditContainerItemOptions

Defines whether item cells editing is enabled.

property Editing: Boolean;

Description

Set the Editing property to False to prevent a user from modifying item data.  Otherwise, a user is allowed to modify data unless this option is disabled by another item or editing control options.

The default value of the Editing property is True.


TcxCustomEditContainerItemOptions.Filtering

TcxCustomEditContainerItemOptions

Specifies whether a user can create a filter condition for a specific item.

property Filtering: Boolean;

Description

If the Filtering property is True, the end-user is allowed to set the filter criteria for it.  If the Filtering property is False, filtering is disabled.

The default value of the Filtering property is True.


TcxCustomEditContainerItemOptions.Focusing

TcxCustomEditContainerItemOptions

Specifies whether an item edit cell can be focused.

property Focusing: Boolean;

Description

Set the Focusing property to False to prevent item cell focusing.  A user cannot focus an item via a mouse click or key press.  Otherwise, item cell focusing is enabled unless any other properties prevent it.

The default value of the Focusing property is True.


TcxCustomEditContainerItemOptions.IncSearch

TcxCustomEditContainerItemOptions

Specifies whether incremental search can be performed by the current item.

property IncSearch: Boolean;

Description

The IncSearch property specifies whether a user can perform incremental search by the current item. If the property is True, the search is enabled within a control item (unless any other property prevents it).

In TreeList columns the incremental search works as follows: when a specific column is focused, a user starts typing and the control will navigate to the row that contains the closest partial match within that column.

The default value of the IncSearch property is True.


TcxCustomEditContainerItemOptions.Moving

TcxCustomEditContainerItemOptions

Specifies whether a user can move an item within a control.

property Moving: Boolean;

Description

Use the Moving property to define whether an item can be moved within an editing control.  If the Moving property is set to False, a user cannot change the column's position by dragging.

The default value of the Moving property is True.


TcxCustomEditContainerItemOptions.ShowEditButtons

TcxCustomEditContainerItemOptions

Identifies the manner in which in-place editors are displayed within item cells.

type

  TcxEditItemShowEditButtons = (eisbDefault, eisbNever, eisbAlways);

property ShowEditButtons: TcxEditItemShowEditButtons;

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 within a control or prevent their display at all.

There are three settings available:

Value	Description
eisbNever	Editor buttons are not displayed.
eisbAlways	Editor buttons are always visible.
eisbDefault	Editor buttons are visible only when a cell is focused.

The default value of the ShowEditButtons property is eisbDefault.


TcxCustomEditContainerItemOptions.Sorting

TcxCustomEditContainerItemOptions

Specifies whether a user can sort data against an item.

property Sorting: Boolean;

Description

If the Sorting property is True, data can be sorted against an item.

In TreeList columns a user sorts data either by setting the TcxTreeListColumn.SortOrder property or by clicking the column header.

The default value of the Sorting property is True.


TcxCustomEditContainerItemOptions.TabStop

TcxCustomEditContainerItemOptions

Determines whether the end-user can focus an item by using the Tab key.

property TabStop: Boolean;

Description

The TabStop property allows you to specify whether a user can focus the current item using the Tab key.  If the property is True, the end-user can press the Tab key to move focus to it.

Otherwise, pressing the Tab key doesn't allow you to move to that item and it can be focused only by a mouse click (if implemented).

The default value of the TabStop property is True.


TcxCustomHitTestController
TcxCustomHitTestController Object

Hierarchy          Properties

Provides general information about a specific point of the editing control.

Unit

cxInplaceContainer

TcxCustomHitTestController = class(TObject)

Description

The TcxCustomHitTestController class provides general information about a specific point of the editing control.

1.	The point coordinates can be obtained via the HitX and HitY properties or the HitPoint property;

2.	Hit test codes (unique identifiers for an editing control element) can be obtained via the HitState property;

3.	The element to which the point belongs can be obtained via the HitTestItem property.


TcxCustomHitTestController Hierarchy
Hierarchy

TObject

     |


Properties for TcxCustomHitTestController
TcxCustomHitTestController Properties

TcxCustomHitTestController          Legend

In TcxCustomHitTestController

HitCode

HitPoint

HitState

HitTestItem

HitX

HitY


TcxCustomHitTestController.HitCode

TcxCustomHitTestController

Specifies whether the tested point is within a specific editing control element.

type

  TcxHitCode = Int64;

property HitCode[ACode: TcxHitCode]: Boolean;

Description

The HitCode property allows you to determine whether the tested point belongs to the editing control element whose hit code is specified via the ACode parameter.  The property returns True if this element contains the tested point, otherwise, it will return False.


TcxCustomHitTestController.HitPoint

TcxCustomHitTestController

Indicates the tested point within an editing control.

property HitPoint: TPoint;

Description

Use the HitPoint property to obtain or to set the exact coordinates of the tested point.

You can also set the appropriate point via the HitX and HitY properties.


TcxCustomHitTestController.HitState

TcxCustomHitTestController

Determines the control element to which the current point belongs.

type

  TcxHitCode = Int64;

property HitState: TcxHitCode;

Description

Use this property to obtain the HitCode of the control element that owns the current point.

Unlike the HitCode property, HitState does not check whether the current point belongs to a certain control element according to the passed HitCode but immediately provides this HitCode.

ReadOnly Property


TcxCustomHitTestController.HitTestItem

TcxCustomHitTestController

Specifies the editing control element to which the current point belongs.

property HitTestItem: TObject;

Description

Unlike the HitCode or the HitTestItem property, this property does not provide an element’s code but instead it specifies its class.  So you can access the element’s properties and methods.  Use this property when it is necessary to work with control elements without their HitCodes.


TcxCustomHitTestController.HitX

TcxCustomHitTestController

Specifies the horizontal coordinate of the point within an editing control.

property HitX: Integer;

Description

In order to specify the tested point within the editing control, you can use the HitPoint property or the HitX and HitY properties.  The HitX property determines the X coordinate of such a point.  It is more convenient to use the HitX and HitY properties than the HitPoint property if it is necessary to process a set of points, which have the same X or Y coordinate.


TcxCustomHitTestController.HitY

TcxCustomHitTestController

Specifies the vertical coordinate of the point within an editing control.

property HitY: Integer;

Description

In order to specify the tested point within the editing control, you can use the HitPoint property or the HitX and HitY properties.  The HitY property determines the Y coordinate of such a point.  It is more convenient to use the HitY and HitX properties than the HitPoint property if it is necessary to process a set of points, which have the same X or Y coordinate.


TcxCustomInplaceEditContainer
TcxCustomInplaceEditContainer Object

Hierarchy          Properties          Events

Represents the base class for editing control items that can contain in-place editors.

Unit

cxInplaceContainer

TcxCustomInplaceEditContainer = class(TComponent)

Description

The TcxCustomInplaceEditContainer class provides the base functionality for editing the control items whose cell values can be edited by an in-place editor.  A cell with the assigned in-place editor uses its painter to draw itself and to edit cell values.  The editor becomes active when a cell is in the edit state. Generally, the style of editing and the type of the in-place editor depend on the data type of an editing control item.


TcxCustomInplaceEditContainer Hierarchy
Hierarchy

TComponent

     |


Properties for TcxCustomInplaceEditContainer
TcxCustomInplaceEditContainer Properties

TcxCustomInplaceEditContainer          Legend

In TcxCustomInplaceEditContainer

DataBinding

Editing

EditValue

ItemIndex

Options

Properties

PropertiesClass

PropertiesClassName

RepositoryItem

Styles


Events for TcxCustomInplaceEditContainer
TcxCustomInplaceEditContainer Events

TcxCustomInplaceEditContainer          Legend

In TcxCustomInplaceEditContainer

OnGetEditProperties


TcxCustomInplaceEditContainer.DataBinding

TcxCustomInplaceEditContainer

Represents an object linking the current item to a data storage.

property DataBinding: TcxCustomItemDataBinding;

Description

The DataBinding property implements retrieving data from and posting it to a data storage.  You can use the DataBinding properties to specify the dataset field to which a specific item is connected (for the editing control linked to a dataset) and perform other operations.  The Data attribute of a DataBinding object allows you to associate arbitrary data with your item.


TcxCustomInplaceEditContainer.Editing

TcxCustomInplaceEditContainer

Determines whether an item of an editing control is being edited.

property Editing: Boolean;

Description

Use the Editing property to determine whether a cell is in edit mode.  Set the property value to True to charge the item state to editing mode.


TcxCustomInplaceEditContainer.EditValue

TcxCustomInplaceEditContainer

Specifies the value stored in the currently focused item’s editor.

property EditValue: Variant;

Description

Use the EditValue property to access the editor value within an item.  Some editors do not store the values being edited by a user in the EditValue property immediately.  They are stored in EditValue after a user presses the Enter key or sets focus to another item.  In this case, the currently edited value is validated first.


TcxCustomInplaceEditContainer.ItemIndex

TcxCustomInplaceEditContainer

Specifies the current item index.

property ItemIndex: Integer;

Description

As the control may require different editors types, then a specific item must be created for each editor type.  Upon creation each item is placed into the items collection.  The item index is uniquely identifies it within the collection.  So, it can be easily accessed for further work.

Item index is zero-based, so the first control's item has an index of 0.

ReadOnly Property


TcxCustomInplaceEditContainer.Options

TcxCustomInplaceEditContainer

Contains a set of options managing the behavior of an editing control’s item.

property Options: TcxCustomEditContainerItemOptions;

Description

The Options object contains a number of attributes which enable/disable operations performed on items by a user at runtime.  These operations include:

•	Editing item data;

•	Focusing items;

•	Moving items;

•	Filtering items;

•	Sorting data by an item.

The TcxCustomInplaceEditContainer class descendants publish the necessary options and declare other attributes specific to them.

You can also set options common to all items within your editing control via the OptionsCustomizing, OptionsSelection and OptionsView properties.


TcxCustomInplaceEditContainer.Properties

TcxCustomInplaceEditContainer

Specifies the editor’s properties available for editing item data.

property Properties: TcxCustomEditProperties;

Description

You can assign a particular editor to edit item cells contents in two ways.

The first way is to set the PropertiesClass property.

The second one is to assign a repository item to the RepositoryItem property.  If an editor is assigned via RepositoryItem, the Properties and PropertiesClass member values 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 they are created.


TcxCustomInplaceEditContainer.PropertiesClass

TcxCustomInplaceEditContainer

Specifies the editor class used to edit item data.

type

  TcxCustomEditPropertiesClass = class of TcxCustomEditProperties;

property PropertiesClass: TcxCustomEditPropertiesClass;

Description

Use the PropertiesClass property to assign a specific editor to edit item cell data.  To assign an editor, set the PropertiesClass property to a TcxCustomEditProperties class descendant.  Once PropertiesClass is set, the Properties property provides access to available editor settings.  The TcxCustomInplaceEditContainer.RepositoryItem property also allows you to assign an editor to an item.  If it is assigned via TcxCustomInplaceEditContainer.RepositoryItem, PropertiesClass and Properties are ignored.


TcxCustomInplaceEditContainer.PropertiesClassName

TcxCustomInplaceEditContainer

Specifies the editor class name used to edit item data.

property PropertiesClassName: string;

Description

The PropertiesClassName property’s functionality is similar to the PropertiesClass property, but it specifies the exact class name instead of an object.


TcxCustomInplaceEditContainer.RepositoryItem

TcxCustomInplaceEditContainer

Specifies the repository item for a specific item’s 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 the RepositoryItem property, the Properties and PropertiesClass values are ignored.


TcxCustomInplaceEditContainer.Styles

TcxCustomInplaceEditContainer

Specifies the styles managing the appearance of an editing control’s item.

property Styles: TcxEditContainerStyles;

Description

Use the Styles property to specify the styles for editing control elements (treelist columns, for instance).


TcxCustomInplaceEditContainer.OnGetEditProperties

TcxCustomInplaceEditContainer

Occurs when obtaining an item editor’s properties.

type

  TcxGetEditPropertiesEvent = procedure(Sender: TObject; AData: Pointer; var AEditProperties: TcxCustomEditProperties) of object;

property OnGetEditProperties: TcxGetEditPropertiesEvent;

Description

The OnGetEditProperties event allows you to implement the multieditors feature, i.e. provide different editors for a single item.  You can handle the OnGetEditProperties event to change the default item editor for a cell.  The Sender parameter determines the editing control item for which this event handler is applied.  The AData parameter must be overridden in descendants in order to specify the exact control item to apply this event.  The default item editor’s properties are passed in the AEditProperties parameter.

To redefine the default editor, assign another properties object (a TcxCustomEditProperties class descendant) corresponding to the required editor to the AEditProperties parameter.


TcxCustomItemDataBinding
TcxCustomItemDataBinding Object

Hierarchy          Properties

Represents an abstract data binding.

Unit

cxInplaceContainer

TcxCustomItemDataBinding = class(TPersistent)

Description

The TcxCustomItemDataBinding class represents an abstract data binding.  It implements the base functionality for data binding:

•	connection to the data controller;

•	events posting from an editing control to a dataset.


TcxCustomItemDataBinding Hierarchy
Hierarchy

TPersistent

     |


TcxCustomViewInfoItem
TcxCustomViewInfoItem Object

Hierarchy          Properties          Methods

Represents an abstract ViewInfo object.

Unit

cxInplaceContainer

TcxCustomViewInfoItem = class(TObject)

Description

Each editing control has its own painter.  Painter is an object that paints a control on a specific canvas based on its visual settings, colors, texts styles, size etc.  Sometimes it takes much time to calculate all control or element visual settings (for instance, element position within a control).  To avoid pauses during repainting and to ensure smooth painting, all calculations are performed on demand and results are stored within the ViewInfo object. ViewInfo collects, stores and provides all necessary information for control and element painters.  If any visual element setting is changed, ViewInfo is immediately recalculated.  Not only painters use ViewInfo.  It can be used by OnCustomDrawXXX event handlers.  The OnCustomDrawXXX event (if available for a specific element) occurs when the element is about to be painted.  This allows you to custom draw this element.  As a rule, ViewInfo of the painted control is passed as an event parameter.  So you can use it for easy access and modifying various element visual settings.


TcxCustomViewInfoItem Hierarchy
Hierarchy

TObject

     |


Properties for TcxCustomViewInfoItem
TcxCustomViewInfoItem Properties

TcxCustomViewInfoItem          Legend

In TcxCustomViewInfoItem

Control

ControlViewInfo

Owner

BoundsRect

ViewParams

Visible

VisibleRect


Methods for TcxCustomViewInfoItem
TcxCustomViewInfoItem Methods

TcxCustomViewInfoItem          Legend

In TcxCustomViewInfoItem

Invalidate


TcxCustomViewInfoItem.BoundsRect

TcxCustomViewInfoItem

Represents an element’s bounding rectangle.

property BoundsRect: TRect;

Description

The BoundsRect property contains the bounding rectangle of an element.

This property is very useful while implementing custom draw of elements. It allows you to determine the element position within the control (BoundsRect.Top, BoundsRect.Left) and its size (BoundsRect.Bottom - BoundsRect.Top, BoundsRect.Right - BoundsRect.Left).

ReadOnly Property


TcxCustomViewInfoItem.ViewParams

TcxCustomViewInfoItem

Represents the basic view parameters of an element.

property ViewParams: TcxViewParams;

Description

The ViewParams property contains the base view parameters of elements. They include: background and content colors.

The parameters are represented by the following properties:

•	Color - represents an element’s background color;

•	Bitmap - represents an element’s background bitmap;

•	Font – represents an element’s text font;

•	TextColor - represents an element’s text color.

ReadOnly Property


TcxCustomViewInfoItem.Visible

TcxCustomViewInfoItem

Indicates whether an element is visible.

property Visible: Boolean;

Description

The Visible property indicates whether an element is painted within a control.  Use this property in CustomDraw events to determine if a specific element needs to be painted.

ReadOnly Property


TcxCustomViewInfoItem.VisibleRect

TcxCustomViewInfoItem

Represents an element’s visible portion.

property VisibleRect: TRect;

Description

Sometimes it occurs that the whole element is no seen within a control (partially visible cells in a tree list).

The VisibleRect property contains a rectangle that represents an element’s visible portion.

For instance, you can compare the BoundsRect and VisibleRect properties values to determine whether an element is fully visible.

ReadOnly Property


TcxCustomViewInfoItem.Invalidate

TcxCustomViewInfoItem

Repaints a ViewInfo element.

procedure Invalidate(ARecalculate: Boolean = False);

Description

Use the Invalidate method to repaint elements whenever you need.  You can force ViewInfo to be recalculated before repainting by setting the ARecalculate parameter to True.  By default, ViewInfo is not recalculated to save system time and resources and to provide smooth repainting.  Elements can have a complex structure and recalculating their ViewInfos is a very slow operation.  So force ViewInfo recalculation only if it is extremely necessary.


TcxCustomViewInfoItem.Control

TcxCustomViewInfoItem

Provides access to the editing control that owns the current ViewInfo.

property Control;

Description

Use the Control property to access the owner control’s properties and methods. This is useful when custom painting according to the control’s specific settings.


Properties for TcxCustomItemDataBinding

TcxCustomViewInfoItem          Legend

In TcxCustomItemDataBinding

Data


TcxEditCellViewInfo
TcxEditCellViewInfo Object

Hierarchy          Properties

Provides display information for editing control data cells.

Unit

cxInplaceContainer

TcxEditCellViewInfo = class(TcxCustomViewInfoItem)

Description

TcxEditCellViewInfo contains information about data cells of tabular editing controls (e.g. the TreeList).  It provides information for the data cell’s painter.  When an in-place editor is active within a data cell, the editor's ViewInfo is used to paint the data cell.  Otherwise, the data cell represents the DisplayValue property value and is painted based on its own view information.

For details about ViewInfos, see editing control painting technology.


TcxEditCellViewInfo Hierarchy
Hierarchy

TObject

     |

TcxCustomViewInfoItem

     |


Properties for TcxEditCellViewInfo
TcxEditCellViewInfo Properties

TcxEditCellViewInfo          Legend

In TcxEditCellViewInfo

Borders

ContentRect

DisplayValue

Focused

RecordIndex

Derived from TcxCustomViewInfoItem

BoundsRect

Control

ViewParams

Visible

VisibleRect


TcxEditCellViewInfo.Borders

TcxEditCellViewInfo

Represents the active borders of a data cell.

type

  TcxBorder = (bLeft, bTop, bRight, bBottom);

  TcxBorders = set of TcxBorder;

property Borders: TcxBorders;

Description

The Borders property allows you to determine which data cell borders are drawn around a cell.  The property value is the combination of the border indicators (bLeft, bRight, bTop, bBottom - each specifies a cell border).  The BoundsRect property includes borders width while the ContentRect property doesn't.

ReadOnly Property


TcxEditCellViewInfo.ContentRect

TcxEditCellViewInfo

Represents a cell rectangle excluding the width of its borders.

property ContentRect: TRect;

Description

The ContentRect property represents the rectangle available for the cell’s content.

The ContentRect property does not include the width of the borders while the BoundsRect property does.

ReadOnly Property


TcxEditCellViewInfo.DisplayValue

TcxEditCellViewInfo

Represents the value actually displayed within a cell.

property DisplayValue: Variant;

Description

The DisplayValue property contains the corresponding data field value.  The value is a variant and you can obtain its type via the VarType method.

ReadOnly Property


TcxEditCellViewInfo.Focused

TcxEditCellViewInfo

Indicates whether a cell is focused.

property Focused: Boolean;

Description

The Focused property indicates whether a cell is focused.  This allows you to implement custom drawing based on the cell’s state (focused or normal).

ReadOnly Property


TcxEditCellViewInfo.RecordIndex

TcxEditCellViewInfo

Specifies the record index in a dataset.

property RecordIndex: Integer;

Description

Specifies the record index in a dataset.

ReadOnly Property


TcxEditContainerStyles
TcxEditContainerStyles Object

Hierarchy          Properties

Contains style for the editing control cells.

Unit

cxInplaceContainer

TcxEditContainerStyles = class(TcxStyles)

Description

TcxEditContainerStyles object represents the collection of editing control styles.  It inherits all the TcxStyles collection functionality and adds a new style (Content).  This style defines the appearance of the editing control cells when the in-place editor is inactive.


TcxEditContainerStyles Hierarchy
Hierarchy

TcxStyles

     |


Properties for TcxEditContainerStyles
TcxEditContainerStyles Properties

TcxEditContainerStyles          Legend

In TcxEditContainerStyles

Content


TcxEditContainerStyles.Content

TcxEditContainerStyles

Specifies a style for a cell’s content.

property Content: TcxStyle;

Description

The Content property specifies a style for the editing control cells’ contents.  This style is applied to the cells only when the in-place editor is inactive.


TcxEditingControl
TcxEditingControl Object

Hierarchy          Properties          Methods          Events

Represents an object providing the base functionality for editing controls that support in-place editors.

Unit

cxInplaceContainer

TcxEditingControl = class(TcxControl)

Description

The TcxEditingControl class provides the base functionality that enables data-aware controls to use in-place editors for data editing.

The TcxEditingControl provides several events that allow you to control data editing by in-place editors:

OnEditChanged - occurs when editing a cell within an editing control.

OnEdited - occurs after deactivating a control cell’s editor.

OnEditing - occurs before activating a control cell’s editor.

OnEditValueChanged - occurs when changing the edit value of the active cell editor.

OnInitEdit - occurs after the editor is invoked for a cell.


TcxEditingControl Hierarchy
Hierarchy

TcxControl

     |


Properties for TcxEditingControl
TcxEditingControl Properties

TcxEditingControl          Legend

In TcxEditingControl

LockUpdate

Styles

Derived from TcxControl

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel


Methods for TcxEditingControl
TcxEditingControl Methods

TcxEditingControl          Legend

In TcxEditingControl

BeginUpdate

CancelUpdate

EndUpdate

LayoutChanged


Events for TcxEditingControl
TcxEditingControl Events

TcxEditingControl          Legend

In TcxEditingControl

OnCustomDrawCell

OnEditChanged

OnEdited

OnEditing

OnEditValueChanged

OnInitEdit


TcxEditingControl.Styles

TcxEditingControl

Specifies the set of styles that define the appearance of control elements.

property Styles: TcxCustomControlStyles;

Description

Use the Styles property to gain access to the set of styles defining elements’ appearance.  This set is expanded when the Styles property is re-defined by TcxEditingControl descendants.  In the base class, the Styles set includes a style defining the appearance of the current control background.  In this class, the style collection contains styles for cell contents, the selection bar and other control elements.


TcxEditingControl.BeginUpdate

TcxEditingControl

Prevents an editing control from being updated until the EndUpdate or the CancelUpdate method is called.

procedure BeginUpdate;

Description

Each time you modify a property of an editing 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 around the code updating your editing control.

The BeginUpdate method postpones control updates.  To apply the changes made, you should call the EndUpdate method, which also causes the editing control’s 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 editing control.  If you call the CancelUpdate method after performing changes that affect the visual representation of the control, an exception will occur.

Ensure that every call to BeginUpdate has a corresponding call to the EndUpdate method (or to CancelUpdate).


TcxEditingControl.CancelUpdate

TcxEditingControl

Enables updating of an editing control to resume after the BeginUpdate method was called.

procedure CancelUpdate;

Description

Each time you modify a property of an editing 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 around the code updating your editing control.

The BeginUpdate method postpones control updates.  To apply the changes made, you should call the EndUpdate method, which also causes the editing control’s 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 editing control.  If you call the CancelUpdate method after performing changes that affect the visual representation of the control, an exception will occur.

Ensure that every call to BeginUpdate has a corresponding call to the EndUpdate method (or to CancelUpdate).


TcxEditingControl.EndUpdate

TcxEditingControl

Enables updating of an editing control after the BeginUpdate method was called.

procedure EndUpdate;

Description

Each time you modify a property of an editing 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 around the code updating your editing control.

The BeginUpdate method postpones control updates.  To apply the changes made, you should call the EndUpdate method, which also causes the editing control’s 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 editing control.  If you call the CancelUpdate method after performing changes that affect the visual representation of the control, an exception will occur.

Ensure that every call to BeginUpdate has a corresponding call to the EndUpdate method (or to CancelUpdate).


TcxEditingControl.LayoutChanged

TcxEditingControl

Invalidates an editing control in response to layout changes.

procedure LayoutChanged;

Description

The LayoutChanged method invalidates an editing control when the layout changes.  Typically, use this when you want to force recalculations of the control’s view information.


TcxEditingControl.OnEditChanged

TcxEditingControl

Occurs when changing an open editor’s value.

type

  TcxecItemEvent = procedure(Sender: TObject; AItem: TcxCustomInplaceEditContainer) of object;

property OnEditChanged: TcxecItemEvent;

Description

The OnEditChanged event is generated when changing an editor’s value. This event is equivalent to the editor’s Properties.OnChange event.

For text editors, the 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 changing the state.

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 check box editors state;

•	selects a radio button within a radio group.

In these cases, the OnEditValueChanged event is generated.


TcxEditingControl.OnEdited

TcxEditingControl

Occurs after deactivating a cell editor.

type

  TcxecItemEvent = procedure(Sender: TObject; AItem: TcxCustomInplaceEditContainer) of object;

property OnEdited: TcxecItemEvent;

Description

Use the OnEdited event handler to validate the cell value after its modification.  The Sender parameter identifies the control and the AItem parameter identifies the control's item that was edited.


TcxEditingControl.OnEditing

TcxEditingControl

Occurs before activating a cell editor.

type

  TcxecEditingEvent = procedure(Sender, AItem: TObject; var Allow: Boolean) of object;

property OnEditing: TcxecEditingEvent;

Description

Use the OnEditing event handler to enable or disable editing within a control.  The Sender parameter identifies the control and the AItem parameter identifies the control's item to be edited.  The AAllow parameter determines whether editing can be initiated. Set it to False to prevent it.


TcxEditingControl.OnEditValueChanged

TcxEditingControl

Occurs when the edit value of the active cell editor has changed.

type

  TcxecItemEvent = procedure(Sender: TObject; AItem: TcxCustomInplaceEditContainer) of object;

property OnEditValueChanged: TcxecItemEvent;

Description

The OnEditValueChanged event occurs after changing the edit value of the active editor in an editing control.  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 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 check box editors state;

•	selects a radio button within a radio group.

The modified edit value is posted back to the corresponding dataset field at the following times:

•	when setting focus to another record;

•	when posting data programmatically using the data controller’s or the 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.


TcxEditingControl.OnInitEdit

TcxEditingControl

Occurs after the editor is invoked for a cell.

type

  TcxecInitEditEvent = procedure(Sender, AItem: TObject; AEdit: TcxCustomEdit) of object;

property OnInitEdit: TcxecInitEditEvent;

Description

The OnInitEdit event gives you the ability to customize the cell editor opened for a particular cell.  The control generating the event is passed as the Sender parameter.  The AItem parameter 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.

The OnInitEdit event handler shown in the following example enables automatic opening of the popup window of dropdown editors.

//Delphi

procedure TForm1.tvCustomersInitEdit(Sender, AItem: TObject; AEdit: TcxCustomEdit)

begin

  if AEdit is TcxCustomDropDownEdit then

    TcxCustomDropDownEdit(AEdit).DroppedDown := True;

end;

//C++ Builder

void __fastcall TForm1::tvCustomersInitEdit(TObject *Sender, TObject *AItem, TcxCustomEdit *AEdit)

{

  TcxCustomDropDownEdit * ADropDownEdit;

  if (ADropDownEdit = dynamic_cast<TcxCustomDropDownEdit*>(AEdit))

    ADropDownEdit->DroppedDown = true;

}


TcxEditingControl.LockUpdate

TcxEditingControl

Indicates the number of BeginUpdate method calls that have not been matched by EndUpdate method calls.

property LockUpdate: Integer;

Description

Use the LockUpdate property to keep track of calls to the BeginUpdate and EndUpdate methods. Every time a call is made to the BeginUpdate method, it increments the LockUpdate property value. Every call to the EndUpdate or the CancelUpdate method decrements the LockUpdate property value.


TcxEditingControl.BufferedPaint

TcxEditingControl

Determines whether the control’s image is rendered directly in the window or is first painted to an in-memory bitmap.

property BufferedPaint: Boolean;

Description

When the BufferedPaint property is false, the control paints itself directly in the window. When BufferedPaint is true, the control paints itself to an in-memory bitmap that is then used to paint the window. Double buffering reduces the amount of flickering when the control repaints, but is more memory intensive.


TcxEditingControl.OnCustomDrawCell

TcxEditingControl

Occurs when a cell within a control needs to be painted.

type

  TcxCustomDrawViewInfoItemEvent = procedure(Sender: TObject; Canvas: TcxCanvas; AViewInfo: TcxCustomViewInfoItem; var ADone: Boolean) of object;

property OnCustomDrawCell: TcxCustomDrawViewInfoItemEvent;

Description

The OnCustomDrawCell property occurs every time a cell needs to be painted. Similar to the other custom draw events, it provides a canvas for the control (the ACanvas parameter) and the view information to get the bounding rectangle of the painted element (the AViewInfo parameter and its Bounds property). Sender is usually an element that causes the repainting. The ADone parameter is initially False and you should set it to True to notify the control that you have chosen to custom draw the item.


TcxExtEditingControl
TcxExtEditingControl Object

Hierarchy          Properties          Methods          Events

Represents an editing control that contains options collections.

Unit

cxInplaceContainer

TcxExtEditingControl = class(TcxEditingControl)

Description

The TcxExtEditingControl is a TcxEditingControl descendant that extends its functionality by adding options collections.  Options collections are classes, arranging the control's options into logical groups.

The TcxExtEditingControl provides the following options collections:

•	TcxExtEditingControl.OptionsBehavior - contains settings determining the control's response to user actions.

•	TcxExtEditingControl.OptionsData - contains settings determining the functionality of a data-aware control.

•	TcxExtEditingControl.OptionsView - contains settings determining the control appearance.

All editing controls such as the TcxTreeList control are TcxExtEditingControl descendants.


TcxExtEditingControl Hierarchy
Hierarchy

TcxControl

     |

TcxEditingControl

     |


Properties for TcxExtEditingControl
TcxExtEditingControl Properties

TcxExtEditingControl          Legend

In TcxExtEditingControl

OptionsBehavior

OptionsData

OptionsView

Derived from TcxEditingControl

BufferedPaint

LockUpdate

Styles

Derived from TcxControl

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel


Methods for TcxExtEditingControl
TcxExtEditingControl Methods

TcxExtEditingControl          Legend

Derived from TcxEditingControl

BeginUpdate

CancelUpdate

EndUpdate

LayoutChanged


Events for TcxExtEditingControl
TcxExtEditingControl Events

TcxExtEditingControl          Legend

Derived from TcxEditingControl

OnCustomDrawCell

OnEditChanged

OnEdited

OnEditing

OnEditValueChanged

OnInitEdit


TcxExtEditingControl.OptionsBehavior

TcxExtEditingControl

Contains settings determining the control's response to user actions.

property OptionsBehavior: TcxControlOptionsBehavior;

Description

Use the OptionsBehavior property to access the settings determining the control’s response to 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.


TcxExtEditingControl.OptionsData

TcxExtEditingControl

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

property OptionsData: TcxControlOptionsData;

Description

Use OptionsData to determine which actions can be performed for the dataset providing records for the current control.  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 to the dataset.


TcxExtEditingControl.OptionsView

TcxExtEditingControl

Contains settings determining the control’s appearance.

property OptionsView: TcxControlOptionsView;

Description

Use the OptionsView property to access the settings specifying the control’s appearance.  These options specify editor buttons visibility and determine whether item captions & cells are automatically enlarged to display their full contents.


TcxItemDataBinding
TcxItemDataBinding Object

Hierarchy          Properties

Represents an object linking an editing control item to a dataset field.

Unit

cxInplaceContainer

TcxItemDataBinding = class(TcxCustomItemDataBinding)

Description

Every editing item 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 your item works properly.

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 (items movement, 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 items.


TcxItemDataBinding Hierarchy
Hierarchy

TPersistent

     |

TcxCustomItemDataBinding

     |


Properties for TcxItemDataBinding
TcxItemDataBinding Properties

TcxItemDataBinding          Legend

In TcxItemDataBinding

ValueType

ValueTypeClass

Derived from TcxCustomItemDataBinding

Data


TcxItemDataBinding.ValueType

TcxItemDataBinding

Represents a textual representation of the data binding value type.

property ValueType: string;

Description

The ValueType property contains the name of the data binding value type.  Generally, this property value is the same as the Delphi type name.  For instance, if the data binding value type is String, the ValueType property will contain 'String', if Boolean – 'Boolean', etc.

To obtain the data binding value type class, use the ValueTypeClass property.

In bound mode, the default item editor is determined by the field type.  Please refer to the TcxDBItemDataBinding.FieldName property topic.


TcxItemDataBinding.ValueTypeClass

TcxItemDataBinding

Determines the data type the data binding provides.

type

  TcxValueType = class(TObject);

  TcxValueTypeClass = class of TcxValueType;

property ValueTypeClass: TcxValueTypeClass;

Description

The ValueTypeClass property specifies the data type provided by the data binding, thus determining the values types displayed by an item.  As a rule, you should only set ValueTypeClass for unbound and provider modes.  This provides correct memory allocation, validation and item values sorting.  In bound mode, ValueTypeClass is assigned automatically based on the field type.

In unbound mode, ValueTypeClass also determines the default editor type used to edit an item content.  For instance, assigning ValueTypeClass to TcxBooleanValueType results in using the TcxCheckBox editor for items.  See the TcxValueType class topic for more details.

To obtain the textual representation of the value type, use the ValueType property.

In bound mode, the default item editor is determined by the field type.  Please refer to the TcxDBItemDataBinding.FieldName property topic.


TcxCustomItemDataBinding.Data

TcxCustomItemDataBinding

Represents a placeholder for user-defined data.

property Data: Pointer;

Description

Use the Data property of the data binding as the Tag property of any VCL control.  This property is provided to store any data along with data binding.  The property is effective when working in provider mode.  You can store the control's item dataset index within the Data property.


Edit Repository Items

See Also

The Repository represents a TcxEditRepository component, which supports a collection of repository items.  Repository items define settings specific to corresponding editors.  The ExpressEditors Library provides repository items for every editor it contains.  For instance, it provides a TcxEditRepositoryCheckBoxItem for the TcxCheckBox editor.  Repository items are descendants of the base TcxEditRepositoryItem class.  Every repository item declares a Properties member via which you can adjust different attributes specific to a corresponding editor.

There are two main tasks repository items solve.

The first is to define the properties common to several editors.  Use the Properties attribute of a repository item to adjust specific editor properties.  To set a repository item for an editor, use the editor’s RepositoryItem property.  Each modification of a repository item's properties results in the update of the properties of all linked editors and vice versa.

When you set a repository item for an editor, the editor uses the properties of the repository item (the editor’s properties are preserved and are restored when clearing the RepositoryItem property).

The second task is to specify the editor with which to edit data of grid items (grid items represent columns in a grid table view and rows in a card view).  A grid editor is created based on the information obtained from the repository item assigned via TcxCustomGridTableItem.RepositoryItem.  Editors are not created for all item cells at once.  Only one editor instance exists per item at a time.  Editors are not created for the other item cells.  Instead, cells are drawn with the help of the corresponding ViewInfo object and this knows how to render an editor on a canvas.  The ViewInfo object is retrieved via the virtual GetViewInfoClass function of the TcxEditRepositoryItem.Properties object.

When an editor must be created, information on the editor’s class is also obtained from the Properties object of a repository item via the GetContainerClass function.  After an editor is instantiated, the Properties member of a repository item is assigned to the Properties member of the edit control, thus creating an editor with the required behavior.

You can use the Edit Repository dialog to add repository items at design time.  Just place a TcxEditRepository component onto a form and double-click the icon to open the dialog:

The Add button allows you to add a repository item of the required type.  To adjust the properties of a repository item, use the Object Inspector window.


Editor Style and StyleControllers

Every editor in the ExpressEditors Library allows you to adjust its appearance in various states via its Style members.  The Style, StyleDisabled, StyleFocused and StyleHot properties correspond to a specific editor’s state: the normal, disabled, focused and hot-tracked state respectively.  Each property contains different attributes controlling the appearance and the look & feel of an editor in a particular state.  The Styles properties’ type depends on the editor type.  The TcxCustomEditStyle class is the base class for styles.  Descendants of this class publish additional properties specific to particular editors.

Each Style member specifies various settings which control the appearance of the editor elements such as: border color, border and button styles, background color, font attributes, look & feel etc.

Default Style Settings

The LookAndFeel property determines the default appearance of an editor.  It provides two attributes: NativeStyle and Kind.  NativeStyle is applicable only to Windows® XP and represents a Boolean value indicating whether editor elements are drawn using the current Windows® XP theme.  If NativeStyle is set to True, most of the other style attributes are ignored.  The Kind property specifies the default appearance of your editor if it is not drawn using a Windows XP theme.  It represents an enumeration of predefined default styles which can be applied to the editor.

Style Attributes and Assigned Values

To redefine the default editor’s appearance in each state, you just need to assign appropriate style attributes.  But you can revert to their default values at any moment by calling the TcxCustomEditStyle.RestoreDefaults method.  This method clears all modifications in style attributes, if any, and restores the default values.  At design time, you can restore style attributes for every state by right-clicking the editor and selecting the Restore styles option from the context menu.

The AssignedValues property represents a set of Boolean flags each of which indicates whether a particular style attribute has been assigned.  The following image demonstrates the Object Inspector window for a TcxTextEdit control with its BorderStyle attribute set to ebs3D.  The AssignedValues property contains the BorderStyle flag as a specific value was assigned to BorderStyle.

The RestoreDefaults method not only reverts to default values, but also clears all flags in the AssignedValues set.  You can clear a specific flag in AssignedValues to restore the default value of an individual style attribute.

Style Controller

A style controller is a separate component, which can be used when necessary to apply a set of style settings to multiple editors.  Place a TcxEditStyleController instance onto a form, assign its style attributes as needed and connect the style controller to your editors by setting their TcxCustomEditStyle.StyleController property.  For instance, by setting the style controller’s Style property which corresponds to the style which will be applied to editors in the normal state, you can specify style attributes’ values for all editors that are connected to this controller.  The properties assigned in this way are tracked by the style controller’s AssignedValues property.  Note that new attribute values are applied only for the editor’s properties which have default values as an editor’s style settings have a higher priority than the settings of a style controller.  Thus they override the settings of a linked style controller, if assigned.

Default Style Controller

A default style controller is a separate component, which can be used to apply a set of style settings to all editors that have no style controllers.  Place a TcxDefaultEditStyleController instance onto a form and assign its Style, StyleDisabled, StyleFocused and StyleHot properties which correspond to various editor states as necessary.  Set the TcxDefaultEditStyleController component’s properties to set new style attributes.  Unlike the TcxEditStyleController component, you need not connect a default style controller to editors as its style settings are automatically applied to all editors that have no style controllers assigned (i.e. have their TcxCustomEditStyle.StyleController property unassigned).  Note that a style controller’s style settings (if it is connected to an editor) have a higher priority than the settings of a default style controller.  But an editor’s style settings has a higher priority than the style controller’s ones and override them, if assigned.  If a particular style attribute is not assigned either in an editor style or in a style controller, editors will use the default value of this attribute as specified by a default style controller (if any).


Editor Properties

Every editor in the ExpressEditors Library maintains various properties via the Properties object.  Using the Properties object’s attributes, you can adjust the editor behavior as your programming needs dictate. The base class representing the editor properties is TcxCustomEditProperties.  Other property classes add new functionality as needed by the different types of editor.  The following image shows the Object Inspector window displaying the properties of a TcxTextEdit control.

You can assign a repository item to editors and this enables you to provide centralized property values for these editors.  Once a repository item is assigned, all its attribute values are copied to an editor.  Use the RepositoryItem property to set a repository item.  For more details, refer to the Edit Repository Items topic.

Many text editors implement an automatic completion feature.  These editors provide a list of predefined strings which a user can select by typing their initial characters.  This list of strings is contained in the LookupItems member.  LookupItems also maintains a list of strings for the incremental search function for the text editors containing an associated dropdown list.  When a user types within the edit box of such a control, the dropdown window is opened and the first value within the dropdown list is located whose first characters match the typed characters.

The Properties object publishes a number of events, enabling you to control different aspects of an editor’s behavior and thus extend its functionality.

Default Property Values

The data-aware and corresponding non data-aware editors have the same Properties object class.  However, working with a data-aware editor is a bit different.  One of the distinctions is the editor’s read-only status: data-aware editors cannot write to a read-only dataset field even if you set the editor’s ReadOnly property to False.  The ReadOnly property of a data-aware editor has a default value obtained from the linked dataset field.  It is based on the TField.CanModify attribute value.  You can set the ReadOnly property to False, but still cannot modify the edit value if your editor is linked to a read-only field.  Unlike data-aware editors, the default value of the ReadOnly property for a non data-aware editor is always False.

Some other editor properties also have default values obtained from the linked dataset field.  These properties include:

•	Alignment (declared in TcxCustomEditProperties, TcxCustomCheckBoxProperties and TcxCustomMemoProperties); default values are determined only for the horizontal alignment from the TField.Alignment attribute value.

•	MaxLength; default values are retrieved from the TField.Size property.

•	MinValue and MaxValue; default values for these properties are determined for integer, float and BCD dataset fields.  For instance, if an editor is linked to an integer field, the default values are defined by TIntegerField.MinValue and TIntegerField.MaxValue respectively.

•	EditMask; default values are determined by the TField.EditMask property value.

•	ValueType; default values are vtFloat for float, currency and BCD fields.

•	DisplayFormat; default values are determined from the TNumericField.DisplayFormat property value.

You can change the above-mentioned property values and later revert to default values by calling the RestoreDefaults method.  At design time, you can revert to default values by right-clicking on your editor and selecting the Restore properties option from the popup menu as shown below:


cxShellCommon Unit Overview
cxShellCommon Unit

Classes

TcxCustomShellRoot

TcxDragDropSettings

TcxShellFolder

TcxShellOptions

Other Types

TcxBrowseFolder

Routines

GetPidlName


TcxCustomShellRoot
TcxCustomShellRoot Object

Hierarchy          Properties

Represents the base class for objects specifying the starting folder options for shell controls.

Unit

cxShellCommon

TcxCustomShellRoot = class(TPersistent)

Description

The TcxCustomShellRoot class is the base class for objects containing the starting folder options for the shell controls.  The BrowseFolder property allows setting the starting location to any of the common folders: Desktop, Favorites, Program Files, My Computer, etc.  When BrowseFolder is set to bfCutomPath, then the CustomPath property specifies the path to the starting location.


TcxCustomShellRoot Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxCustomShellRoot
TcxCustomShellRoot Properties

TcxCustomShellRoot          Legend

In TcxCustomShellRoot

BrowseFolder

CustomPath

PIdl

ShellFolder


TcxCustomShellRoot.BrowseFolder

TcxCustomShellRoot

Specifies one of the common folders as the starting location.

type

  TcxBrowseFolder = (bfCustomPath, bfAltStartup, bfBitBucket, bfCommonDesktopDirectory, bfCommonDocuments, bfCommonFavorites, bfCommonPrograms, bfCommonStartMenu, bfCommonStartup, bfCommonTemplates, bfControls, bfDesktop, bfDesktopDirectory, bfDrives, bfPrinters, bfFavorites, bfFonts, bfHistory, bfMyMusic, bfMyPictures, bfNetHood, bfProfile, bfProgramFiles, bfPrograms, bfRecent, bfStartMenu, bfStartUp, bfTemplates);

property BrowseFolder: TcxBrowseFolder;

Description

Use the BrowseFolder to select one of the common folders as the starting location for a shell control.  Common folders include: My Computer, Desktop, Program Files, Favorites, etc.  If this property is set to the bfCustomPath, then the CustomPath property specifies the starting location.


TcxCustomShellRoot.CustomPath

TcxCustomShellRoot

Specifies the custom path as the starting location.

property CustomPath: WideString;

Description

Use the CustomPath property to specify the custom starting location for a shell control.  This property value is in effect only if the BrowseFolder property is set to bfCustomPath.  Otherwise, the starting location is defined via the BrowseFolder property.


TcxCustomShellRoot.Pidl

TcxCustomShellRoot

Specifies the pointer to an item identifier list (PIDL) for the starting location.

property Pidl: PItemIDList;

Description

The value specified by setting the Pidl property designates the PIDL for the starting location of a shell control as well as the ShellFolder property which corresponds to the immediate parent folder of the object described by the Pidl property.


TcxCustomShellRoot.ShellFolder

TcxCustomShellRoot

Indicates the shell folder for which the object described by the Pidl property is related to.

property ShellFolder: IShellFolder;

Description

Often, the shell folder specified is the immediate parent folder of the object described by the Pidl property.

ReadOnly Property


TcxDragDropSettings
TcxDragDropSettings Object

Hierarchy          Properties          See Also

Stores settings controlling the drag-and-drop behavior of the shell controls.

Unit

cxShellCommon

TcxDragDropSettings = class(TPersistent)

Description

The TcxDragAndDropSettings class contains the drag-and-drop settings for the shell controls.  These settings specify: whether drag-and-drop operations are allowed within a shell control, the drop effects during drag-and-drop.

You can access these settings via the DragDropSettings property.


TcxDragDropSettings Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxDragDropSettings
TcxDragDropSettings Properties

TcxDragDropSettings          Legend

In TcxDragDropSettings

AllowDragObjects

DefaultDropEffect

DropEffect


TcxDragDropSettings.AllowDragObjects

TcxDragDropSettings

Determines whether the drag-and-drop operations are allowed for a shell control.

property AllowDragObjects: Boolean;

Description

Use the AllowDragObjects to determine whether the drag-and-drop operations are available to an end-user.  If this property value is True, then a user can drag objects between a shell control and any program that supports OLE drag-and-drop operations.


TcxDragDropSettings.DefaultDropEffect

TcxDragDropSettings          See Also

Specifies the default action performed when a shell item is dragged from a shell control.

type

  TcxDropEffect = (deCopy, deMove, deLink);

property DefaultDropEffect: TcxDropEffect;

Description

The DropEffect property specifies the type of action performed when a shell item is dragged from a shell control.  If more than one action is available (corresponding DropEffect values are True), then the exact action type is determined by the key pressed:

•	•	dragging an item with the Ctrl key pressed results in copying the dragged item;

•	•	dragging an item with the Shift key pressed results in moving the dragged item;

•	•	dragging an item with the Ctrl + Shift key combination results in creating a link to the dragged item.

If there were no keys pressed during drag-and-drop operation, then the action type is specified via the DefaultDropEffect property.


TcxDragDropSettings.DropEffect

TcxDragDropSettings          See Also

Specifies the action occurring when a shell item is dragged from a shell control.

type

  TcxDropEffect = (deCopy, deMove, deLink);

  TcxDropEffectSet = set of TcxDropEffect;

property DropEffect: TcxDropEffectSet;

Description

Use the DropEffect property to specify the action which takes place when a shell item is dragged from a shell control.  The list of possible values is given below:

Value	Meaning
deCopy	Drop results in a copy. The original data is untouched by the drag source.
deMove	Drag source should remove the data.
deLink	Drag source should create a link to the original data.

If more than one action is available (corresponding DropEffect values are True), then the exact action type is determined by the key pressed:

•	•	dragging an item with the Ctrl key pressed results in copying the dragged item;

•	•	dragging an item with the Shift key pressed results in moving the dragged item;

•	•	dragging an item with the Ctrl + Shift key combination results in creating a link to the dragged item.

If there were no keys pressed during drag-and-drop operation, then the action type is specified via the DefaultDropEffect property.

When only one DropEffect value is True, then only the corresponding action is allowed.


TcxShellOptions
TcxShellOptions Object

Hierarchy          Properties

Contains settings common to all shell objects.

Unit

cxShellCommon

TcxShellOptions = class(TPersistent)

Description

The TcxShellOptions class contains options affecting the functionality common to all shell controls.

These options affect the visibility of the shell items of different types (files or folders), the availability of the context menus to end-users, etc.

You can access the set of options using the Options property of a shell control.


TcxShellOptions Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxShellOptions
TcxShellOptions Properties

TcxShellOptions          Legend

In TcxShellOptions

ContextMenus

ShowFolders

ShowHidden

ShowNonFolders

ShowToolTip

TrackShellChanges


TcxShellOptions.ContextMenus

TcxShellOptions

Determines whether the popup menu is displayed for the right-clicked shell items.

property ContextMenus: Boolean;

Description

Use the ContextMenus property to enable displaying the context menus for the right-clicked shell items.  This menu provides access to many actions specific to the shell items.

The default value of the ContextMenus property is True.


TcxShellOptions.ShowFolders

TcxShellOptions          See Also

Determines whether folder shell items are displayed.

property ShowFolders: Boolean;

Description

Use the ShowFolders property to enable displaying folder shell items.  In general, this option enables displaying of the shell items that have sub-items.

If the ShowFolders and ShowNonFolders options are deactivated, then the shell control displays nothing.

The default value of the ShowFolders property is True.


TcxShellOptions.ShowHidden

TcxShellOptions          See Also

Determines whether the hidden shell items are displayed.

property ShowHidden: Boolean;

Description

Use the ShowHidden property to enable displaying of the hidden shell items.  This property is in effect only if either the ShowFolders or ShowNonFolders option is activated.

The default value of the ShowHidden property is False.


TcxShellOptions.ShowNonFolders

TcxShellOptions          See Also

Determines whether the file shell items are displayed.

property ShowNonFolders: Boolean;

Description

Use the ShowNonFolders property to enable displaying only file shell items.  In general, this option enables displaying of the shell items that have no sub-items.

If the ShowFolders and ShowNonFolders options are deactivated, then the shell control displays nothing.

The default value of the ShowNonFolders property is True.


TcxShellOptions.ShowToolTip

TcxShellOptions

Determines whether the tooltips are displayed for the shell items.

property ShowToolTip: Boolean;

Description

Use the ShowToolTip property to enable displaying of the tooltips for the shell items.  The item tooltip is displayed when the mouse pointer hovers over an item.

Note: enabling tooltips results in application slowdown.

The default value of the ShowToolTip property is False.


TcxShellOptions.TrackShellChanges

TcxShellOptions

Determines whether the shell changes are tracked via a shell control.

property TrackShellChanges: Boolean;

Description

Use the TrackShellChanges to specify whether the shell changes are tracked via a shell control.  If this property value is True, then the changes applied to the shell outside of a shell control (for instance, via the Windows Explorer) are instantly reflected by a shell control.

Handle a shell control’s OnShellChange event to determine the event which caused the shell to change.

The default value of the TrackShellChanges property is True.


TcxShellFolder
TcxShellFolder Object

Properties          See Also

Represents a shell item.

Unit

cxShellCommon

Description

Each shell item corresponds to a folder object or file object and is represented by an instance of the TcxShellFolder class.  The TcxShellFolder class provides detailed file system information (such as attributes, capabilities and various other properties) on the corresponding shell item.


Properties for TcxShellFolder
TcxShellFolder Properties

TcxShellFolder          Legend

In TcxShellFolder

AbsolutePIDL

Attributes

Capabilities

DisplayName

IsFolder

ParentShellFolder

PathName

Properties

RelativePIDL

ShellFolder

StorageCapabilities

SubFolders


TcxShellFolder.AbsolutePIDL

TcxShellOptions          See Also

Gets the full identifier of the current shell item.

property AbsolutePIDL: PItemIDList;

Description

When working with the Shell API directly, use the AbsolutePIDL property to determine the full identifier of the current shell item relative to the desktop object.  The identifier of the current shell item relative to some root object which is set in a shell control can be obtained via the RelativePIDL property.

The full identifier can be used to access both virtual and standard shell items.  Note that virtual shell items have no physical analogs – files or folders on hard drives.

You can obtain the text representation of the item’s full identifier by calling the GetPidlName function.

ReadOnly Property


TcxShellFolder.Attributes

TcxShellOptions

Returns the file system attributes of the current shell item.

type

  TcxShellFolderAttribute = (sfaGhosted, sfaHidden, sfaIsSlow, sfaLink, sfaReadOnly, sfaShare);

  TcxShellFolderAttributes = set of TcxShellFolderAttribute;

property Attributes: TcxShellFolderAttributes;

Description

Use the Attributes property to get the set of file system attributes which are associated with the current shell item (a folder or file).  All the possible values which can comprise the resulting set are listed in the following table.

Value	Meaning
sfaGhosted	An item should be displayed using a ghosted icon.
sfaHidden	An item is hidden and should not be displayed unless the corresponding option within a shell control is enabled.
sfaIsSlow	Indicates that accessing a shell item (through IStream or other storage interfaces) is a slow operation.  Applications should avoid accessing items which are flagged with this attribute.
sfaLink	An item is a shortcut.
sfaReadOnly	An item is read-only.  In the case of a folder, this means that new items cannot be created in this folder.
sfaShare	A folder item is shared.
ReadOnly Property


TcxShellFolder.Capabilities

TcxShellOptions

Returns the file system capability attributes of the current shell item.

type

  TcxShellFolderCapability = (sfcCanCopy, sfcCanDelete, sfcCanLink, sfcCanMove, sfcCanRename, sfcDropTarget, sfcHasPropSheet);

  TcxShellFolderCapabilities = set of TcxShellFolderCapability;

property Capabilities: TcxShellFolderCapabilities;

Description

Use the Capabilities property to determine the set of file system capability attributes which are associated with the current shell item (a folder or file).  All the possible values which the returned set can consist of are listed in the following table.

Value	Meaning
sfcCanCopy	An item can be copied.
sfcCanDelete	An item can be deleted (for instance, by selecting Delete from its context menu).
sfcCanLink	Indicates that a shortcut for a shell item which is flagged with this attribute can be created.
sfcCanMove	An item can be moved.
sfcCanRename	An item can be renamed.
sfcDropTarget	An item is a drop target (a target for data during a drag-and-drop operation).
sfcHasPropSheet	An item has a property sheet, i.e. a window that allows an end-user to view and edit the properties of the item.
ReadOnly Property


TcxShellFolder.DisplayName

TcxShellOptions

Gets the display name of the current shell item.

property DisplayName: string;

Description

The DisplayName property returns the string with the display name of the current shell item (as it is displayed within a shell control).

ReadOnly Property


TcxShellFolder.IsFolder

TcxShellOptions

Determines whether the current shell item corresponds to a folder object.

property IsFolder: Boolean;

Description

Use this property to distinguish between folder objects and file objects.  If the current shell item corresponds a folder object, the IsFolder property returns True.  Otherwise, False is returned.

ReadOnly Property


TcxShellFolder.ParentShellFolder

TcxShellOptions

Gets the parent folder object of the current shell item.

property ParentShellFolder: IShellFolder;

Description

The ParentShellFolder property returns the folder object which is an immediate parent folder object for the current shell item.  For the shell items within the root of the namespace, the ParentShellFolder property returns the desktop folder.

ReadOnly Property


TcxShellFolder.PathName

TcxShellOptions

Gets the fully qualified path name for the current shell item.

property PathName: string;

Description

The PathName property returns the fully qualified path name for the current shell item.  The path is always an absolute path, which is relative from the root of the namespace.  For virtual shell items, the PathName property returns the display name of the item.

ReadOnly Property


TcxShellFolder.Properties

TcxShellOptions

Returns the properties of the current shell item.

type

  TcxShellFolderProperty = (sfpBrowsable, sfpCompressed, sfpEncrypted, sfpNewContent, sfpNonEnumerated, sfpRemovable);

  TcxShellFolderProperties = set of TcxShellFolderProperty;

property Properties: TcxShellFolderProperties;

Description

Use the Properties property to determine the set of properties of the current shell item.  All the possible values which the returned set can consist of are listed in the following table.

Value	Meaning
sfpBrowsable	An item can be browsed in place.
sfpCompressed	An item is compressed and may require special presentation.
sfpEncrypted	An item is encrypted and may require special presentation.
sfpNewContent	An item contains new content.
sfpNonEnumerated	An item is a non-enumerated item.  That is, it’s not returned by the enumerator created by the IShellFolder.EnumObjects method.
sfpRemovable	An item is on removable media or is itself a removable device.
ReadOnly Property


TcxShellFolder.RelativePIDL

TcxShellOptions          See Also

Gets the relative identifier of the current shell item.

property RelativePIDL: PItemIDList;

Description

When working with the Shell API directly, use the RelativePIDL property to determine the relative identifier of the current shell item which is relative to some root object which is set in a shell control.  The identifier which describes the object relative to the desktop object can be obtained via the AbsolutePIDL property.

The relative identifier can be used to access both virtual and standard shell items.  Note that virtual shell items have no physical analogs – files or folders on hard drives.

ReadOnly Property


TcxShellFolder.ShellFolder

TcxShellOptions

Gets the folder object or file object for the current shell item.

property ShellFolder: IShellFolder;

Description

The ShellFolder property returns the folder object (or file object) which is associated with the current shell item.

ReadOnly Property


TcxShellFolder.StorageCapabilities

TcxShellOptions

Returns the storage capability attributes of the current shell item.

type

  TcxShellFolderStorageCapability = (sfscFileSysAncestor, sfscFileSystem, sfscFolder, sfscLink, sfscReadOnly, sfscStorage, sfscStorageAncestor, sfscStream);

  TcxShellFolderStorageCapabilities = set of TcxShellFolderStorageCapability; property StorageCapabilities: TcxShellFolderStorageCapabilities;

Description

Use the StorageCapabilities property to determine the set of storage capability attributes of the current shell item.  All the possible values which the returned set can consist of are listed in the following table.

Value	Meaning
sfscFileSysAncestor	An item is either a file system folder or has at least one descendant (child, grandchild, or later) that is a file system folder.
sfscFileSystem	An item is part of the file system (that is, it’s a file, directory, or root directory).  The parsed names of the items can be assumed to be valid Win32 file system paths.  These paths can be either Universal Naming Convention (UNC) or drive-letter based.
sfscFolder	An item corresponds to a folder object.  Items can have both sfscStream and sfscFolder capabilities, such as a .zip file.
sfscLink	An item is a shortcut.
sfscReadOnly	An item is read-only.  In the case of a folder, this means that new items cannot be created in this folder.
sfscStorage	An item can be bound to an IStorage interface via the IShellFolder.BindToObject method.
sfscStorageAncestor	The children of this item are accessible through IStream or IStorage interfaces and have either sfscStorage or sfscStream storage capabilities.
sfscStream	An item has a stream associated with it that can be accessed by a call to the IShellFolder.BindToObject method with IID_IStream passed as the riid parameter.  Note that items can have both sfscStream and sfscFolder capabilities, such as a .zip file.
ReadOnly Property


TcxShellFolder.SubFolders

TcxShellOptions

Determines whether the current item contains subfolders.

property SubFolders: Boolean;

Description

The SubFolders property returns True for a folder object which may have subfolders.  Otherwise, False is returned.  The SubFolders property’s value is only advisory, and may be equal to True for certain shell folder implementations even if they do not contain any subfolders.

ReadOnly Property


GetPidlName
GetPidlName Function

Obtains file system path for the specified PIDL.

Unit

cxShellCommon

function GetPidlName(pidl:PItemIDList): WideString;

Description

Use the GetPIDLName function to obtain file system path of a shell item specified via its PIDL.  To obtain the identifier (PIDL) of a shell item corresponding to the specified node you can call the GetItemAbsolutePIDL function (for the TcxCustomShellListView) or the GetNodeAbsolutePIDL function (for the TcxCustomShellTreeView class).


TcxBrowseFolder
TcxBrowseFolder type

The list of possible values for Root.BrowseFolder property.

Unit

cxShellCommon

type

  TcxBrowseFolder = (bfCustomPath, bfAltStartup, bfBitBucket, bfCommonDesktopDirectory, bfCommonDocuments, bfCommonFavorites, bfCommonPrograms, bfCommonStartMenu, bfCommonStartup, bfCommonTemplates, bfControls, bfDesktop, bfDesktopDirectory, bfDrives, bfPrinters, bfFavorites, bfFonts, bfHistory, bfMyMusic, bfMyPictures, bfNetHood, bfProfile, bfProgramFiles, bfPrograms, bfRecent, bfStartMenu, bfStartUp, bfTemplates);

Description

Each value corresponds to one of common paths.

Value	Description
bfAltStartup	File system directory that corresponds to the user's non-localized Startup program group.
bfBitBucket	Virtual folder containing the objects in the user's Recycle Bin.
bfCommonDesktopDirectory	File system directory that contains files and folders that appear on the desktop for all users. A typical path is C:\Documents and Settings\All Users\Desktop. Valid only for Windows NT® systems.
bfCommonDocuments	File system directory that contains documents that are common to all users. Typical paths are C:\Documents and Settings\All Users\Documents. Valid for Windows NT® systems and Windows 95 and Windows 98 systems with Shfolder.dll installed.
bfCommonFavorites	File system directory that serves as a common repository for all users' favorite items. Valid only for Windows NT® systems.
bfCommonPrograms	File system directory that contains the directories for the common program groups that appear on the Start menu for all users. A typical path is C:\Documents and Settings\All Users\Start Menu\Programs. Valid only for Windows NT® systems.
bfCommonStartMenu	File system directory that contains the programs and folders that appear on the Start menu for all users. A typical path is C:\Documents and Settings\All Users\Start Menu. Valid only for Windows NT® systems.
bfCommonStartup	File system directory that contains the programs that appear in the Startup folder for all users. A typical path is C:\Documents and Settings\All Users\Start Menu\Programs\Startup. Valid only for Windows NT® systems.
bfCommonTemplates	File system directory that contains the templates that are available to all users. A typical path is C:\Documents and Settings\All Users\Templates. Valid only for Windows NT® systems.
bsControls	Virtual folder containing icons for the Control Panel applications.
bfDesktop	Windows Desktop — virtual folder that is the root of the namespace.
bfDesktopDirectory	File system directory used to physically store file objects on the desktop (not to be confused with the desktop folder itself). A typical path is C:\Documents and Settings\username\Desktop
bfDrives	My Computer — virtual folder containing everything on the local computer: storage devices, printers, and Control Panel. The folder may also contain mapped network drives.
bfFavorites	File system directory that serves as a common repository for the user's favorite items. A typical path is C:\Documents and Settings\username\Favorites.
bfFonts	Virtual folder containing fonts. A typical path is C:\WINNT\Fonts.
bfHistory	File system directory that serves as a common repository for Internet history items.
bfMyMusic	File system directory that serves as a common repository for music files. A typical path is C:\My Music.
bfMyPictures	Version 5.0.  My Pictures folder. A typical path is C:\Documents and Settings\username\My Documents\My Pictures.
bfNetHood	A file system folder containing the link objects that may exist in the My Network Places virtual folder. It is not the same as CSIDL_NETWORK, which represents the network namespace root. A typical path is C:\Documents and Settings\username\NetHood.
bfPrinters	Virtual folder containing installed printers.
bfProfile	Version 5.0.  User's profile folder.
bfProgramFiles	Version 5.0.  Program Files folder. A typical path is C:\Program Files.
bfPrograms	File system directory that contains the user's program groups (which are also file system directories). A typical path is C:\Documents and Settings\username\Start Menu\Programs.
bfRecent	File system directory that contains the user's most recently used documents. A typical path is C:\Documents and Settings\username\Recent. To create a shortcut in this folder, use SHAddToRecentDocs. In addition to creating the shortcut, this function updates the Shell's list of recent documents and adds the shortcut to the Documents submenu of the Start menu.
bfStartMenu	File system directory containing Start menu items. A typical path is C:\Documents and Settings\username\Start Menu.
bfStartUp	File system directory that corresponds to the user's Startup program group. The system starts these programs whenever any user logs onto Windows NT® or starts Windows® 95. A typical path is C:\Documents and Settings\username\Start Menu\Programs\Startup.
bfTemplates	File system directory that serves as a common repository for document templates.


Legend

 Protected

 Published

ReadOnly