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


cxClasses Unit Overview
cxClasses Unit

Classes

TcxComponentCollection

TcxComponentCollectionItem

TcxDialogMetricsInfo

TcxDialogsMetricsStore

TcxInterfacedPersistent

TcxMRUItem

TcxMRUItems

Interfaces

IcxDialogMetricsInfoData

Other Types

TdxSkinName

Routines

cxDialogsMetricsStore

cxGetResourceString

cxSetResourceString


TcxComponentCollection
TcxComponentCollection Object

Hierarchy          Properties          Methods

Represents a collection of components.

Unit

cxClasses

TcxComponentCollection = class(TPersistent)

Description

The TcxComponentCollection class introduces members that allow you to:

•	determine the number of elements in the collection (Count property);

•	access a particular element (Items property);

•	check whether a given component is in a collection (FindItemByID method);

•	manage elements in the collection (the Add, Insert, Delete, and Clear methods).


TcxComponentCollection Hierarchy
Hierarchy

TPersistent

     |

TcxComponentCollection


Properties for TcxComponentCollection
TcxComponentCollection Properties

TcxComponentCollection          Legend

In TcxComponentCollection

Count

Items


Methods for TcxComponentCollection
TcxComponentCollection Methods

TcxComponentCollection          Legend

In TcxComponentCollection

 Add

 BeginUpdate

 Clear

 Delete

 EndUpdate

 FindItemByID

 Insert

 Update


TcxComponentCollection.Count

TcxComponentCollection          See Also

Gets the number of elements in the collection.

property Count: Integer;

ReadOnly Property


TcxComponentCollection.Items

TcxComponentCollection          See Also

Provides indexed access to the collection elements.

property Items[AIndex: Integer]: TcxComponentCollectionItem;

Description

Use the Items property to get the element at the position specified by the zero-based Index parameter.


TcxComponentCollection.Add

TcxComponentCollection          See Also

Creates a new TcxComponentCollectionItem instance and appends it to the collection.

function Add: TcxComponentCollectionItem;

Description

The Add method creates a new TcxComponentCollectionItem instance and adds it to the end of the collection. A reference to the TcxComponentCollectionItem instance that was added is returned.


TcxComponentCollection.BeginUpdate

TcxComponentCollection

Acquires a lock on the collection.

procedure BeginUpdate; virtual;

Description

Use the BeginUpdate method, if bulk changes are to be made to the collection.

This method is used in combination with the EndUpdate method to wrap a block of statements, which update the collection.

Note: since the execution of the block of statements can exit with either a normal or exception state, these statements and the EndUpdate method should be contained within try…  finally… blocks following the BeginUpdate method to ensure that the lock will be released in all cases.


TcxComponentCollection.Clear

TcxComponentCollection          See Also

Deletes all the TcxComponentCollectionItem instances from the collection and destroys them.

procedure Clear;

Description

Use the Clear method to remove all the TcxComponentCollectionItem objects from the collection.


TcxComponentCollection.Delete

TcxComponentCollection          See Also

Removes the specified TcxComponentCollectionItem instance from the collection and destroys it.

procedure Delete(AIndex: Integer);

Description

The zero-based AIndex parameter specifies the position of the TcxComponentCollectionItem object which is to be removed in the collection.


TcxComponentCollection.EndUpdate

TcxComponentCollection          See Also

Releases a lock and updates the collection.

procedure EndUpdate; virtual;

Description

Use the EndUpdate method paired with the BeginUpdate method to enclose a block of statements, which make bulk updates to the collection.

Note: since the execution of a block of statements can exit in either a normal or exception state, the enclosed statements and the EndUpdate method should be contained within try…  finally… blocks following the BeginUpdate method to ensure that the lock will be released in all cases.


TcxComponentCollection.FindItemByID

TcxComponentCollection          See Also

Returns a reference to a collection element, by its unique identifier.

function FindItemByID(ID: Integer): TcxComponentCollectionItem;

Description

The FindItemID method returns a value of nil, if there are no elements with ids that match the specified id.

The zero-based ID parameter specifies the unique identifier of the required element.


TcxComponentCollection.Insert

TcxComponentCollection          See Also

Creates a new TcxComponentCollectionItem instance and inserts it into the collection at the position specified by the zero-based AIndex parameter.

function Insert(AIndex: Integer): TcxComponentCollectionItem;

Description

The Insert method returns a reference to the TcxComponentCollectionItem instance that was inserted.


TcxComponentCollection.Update

TcxComponentCollection          See Also

Updates a collection to reflect any changes made.

procedure Update(AItem: TcxComponentCollectionItem); virtual;

Description

The Update method has an empty implementation and is intended to allow developers to provide appropriate functionality in the TcxComponentCollection subclasses.

The Update method is called automatically after the changes to the collection elements have been completed.

The AItem parameter specifies the TcxComponentCollectionItem instance that was changed. If an argument of nil is passed, then more than one collection element was updated.


TcxComponentCollectionItem
TcxComponentCollectionItem Object

Hierarchy          Properties          Methods

The TcxComponentCollectionItem class implements an element of the TcxComponentCollection collection.

Unit

cxClasses

TcxComponentCollectionItem = class(TComponent)

Description

The goal of designing the TcxComponentCollectionItem class as the TComponent’s descendant is to make the Delphi IDE aware of a collection element as a component.

The TcxComponentCollectionItem class allows the unique identifier of the current element to be determined (see the ID property) and its index in the collection (see the Index property).


TcxComponentCollectionItem Hierarchy
Hierarchy

TComponent

     |

TcxComponentCollectionItem


Properties for TcxComponentCollectionItem
TcxComponentCollectionItem Properties

TcxComponentCollectionItem          Legend

In TcxComponentCollectionItem

ID

Index


Methods for TcxComponentCollectionItem
TcxComponentCollectionItem Methods

TcxComponentCollectionItem          Legend

In TcxComponentCollectionItem

AddToCollection

GetParentComponent

RemoveFromCollection


TcxComponentCollectionItem.ID

TcxComponentCollectionItem          See Also

Gets the unique identifier of the current collection element.

property ID: Integer;

ReadOnly Property


TcxComponentCollectionItem.Index

TcxComponentCollectionItem          See Also

Specifies the zero-based index of the current element in the collection.

property Index: Integer;


TcxComponentCollectionItem.AddToCollection

TcxComponentCollectionItem          See Also

Adds the current collection element to a collection.

procedure AddToCollection(ACollection: TcxComponentCollection);

Description

Call the AddToCollection method to add the current collection element to the collection specified by the ACollection parameter.  Firstly the collection element is removed from the collection which owns it and then added as the last element to the specified collection (thus the element’s ID and Index properties are modified accordingly).

Note:	If nil is passed as the ACollection parameter then the current collection element is simply removed from the collection which owns it.


TcxComponentCollectionItem.RemoveFromCollection

TcxComponentCollectionItem          See Also

Removes the current collection element from a collection.

procedure RemoveFromCollection(ACollection: TcxComponentCollection);

Description

Call the RemoveFromCollection method to remove the current collection element from the collection specified by the ACollection parameter.


TcxComponentCollectionItem.GetParentComponent

TcxComponentCollectionItem          See Also

Returns the parent component of the current item’s collection.

function GetParentComponent: TComponent; override;

Description

A collection and its items have the same parent component.  Use the GetParentComponent function to access the parent component of a collection item (the parent component of the collection).

If the current item does not belong to a collection, the GetParentComponent function returns nil.


TcxDialogMetricsInfo
TcxDialogMetricsInfo Object

Hierarchy          Properties          See Also

The TcxDialogMetricsInfo represents the dialog information.

Unit

cxClasses

TcxDialogMetricsInfo = class(TObject)

Description

The dialog information – built-in layout settings and custom settings (provided by the IcxDialogMetricsInfoData implementer) – is stored with the TcxDialogsMetricsStore for further use during the application session.

This class implements multiple properties that store built-in layout settings.

The dialog’s custom information is stored with the TcxDialogMetricsInfo.Data property.

The TcxDialogMetricsInfo is used internally by the TcxDialogsMetricsStore.


TcxDialogMetricsInfo Hierarchy
Hierarchy

TObject

     |

TcxDialogMetricsInfo


Properties for TcxDialogMetricsInfo
TcxDialogMetricsInfo Properties

TcxDialogMetricsInfo          Legend

In TcxDialogMetricsInfo

ClientHeight

ClientWidth

Data

DialogClass

Left

Maximized

Top


TcxDialogMetricsInfo.ClientHeight

TcxDialogMetricsInfo          See Also

Returns the height of the dialog's client area, in pixels.

property ClientHeight: Integer;

ReadOnly Property


TcxDialogMetricsInfo.ClientWidth

TcxDialogMetricsInfo          See Also

Returns the width of the dialog's client area, in pixels.

property ClientWidth: Integer;

ReadOnly Property


TcxDialogMetricsInfo.Data

TcxDialogMetricsInfo          See Also

Returns a pointer to a value object that contains custom dialog information.

property Data: Pointer;

ReadOnly Property


TcxDialogMetricsInfo.DialogClass

TcxDialogMetricsInfo

Returns a dialog class type.

property DialogClass: TClass;

ReadOnly Property


TcxDialogMetricsInfo.Left

TcxDialogMetricsInfo          See Also

Returns the horizontal coordinate of the dialog’s top-left corner.

property Left: Integer;

ReadOnly Property


TcxDialogMetricsInfo.Maximized

TcxDialogMetricsInfo

Returns whether the dialog window is maximized.

property Maximized: Boolean;

Description

If the dialog window is maximized, the Maximized property returns True.

ReadOnly Property


TcxDialogMetricsInfo.Top

TcxDialogMetricsInfo          See Also

Returns the vertical coordinate of the dialog’s top-left corner.

property Top: Integer;

ReadOnly Property


TcxDialogsMetricsStore
TcxDialogsMetricsStore Object

Hierarchy          Properties          Methods          See Also

The TcxDialogsMetricsStore implements storage for dialog settings.

Unit

cxClasses

TcxDialogsMetricsStore = class(TObject)

Description

The TcxDialogsMetricsStore is used to store information on the dialog (dialog layout built-in settings and custom information) during the application session.

By default, the TcxDialogsMetricsStore stores dialog built-in layout settings. To store custom settings, the dialog class needs to implement the IcxDialogMetricsInfoData interface.

The TcxDialogsMetricsStore can be instantiated using the cxDialogsMetricsStore routine.

The following example demonstrates how to use the TcxDialogsMetricsStore, in order to provide the same dialog settings for different dialog sessions:

// Delphi

// ...

uses

  // ...

  cxClasses;

  TDialogForm = class(TForm)

  public

    function ShowModal: Integer; override;

  end;

// ...

function TDialogForm.ShowModal: Integer;

begin

  cxDialogsMetricsStore.InitDialog(Self);

  Result := inherited ShowModal;

  cxDialogsMetricsStore.StoreMetrics(Self);

end;


TcxDialogsMetricsStore Hierarchy
Hierarchy

TObject

     |

TcxDialogsMetricsStore


Properties for TcxDialogsMetricsStore
TcxDialogsMetricsStore Properties

TcxDialogsMetricsStore          Legend

In TcxDialogsMetricsStore

DefaultPosition


Methods for TcxDialogsMetricsStore
TcxDialogsMetricsStore Methods

TcxDialogsMetricsStore          Legend

In TcxDialogsMetricsStore

 InitDialog

 StoreMetrics


TcxDialogsMetricsStore.DefaultPosition

TcxDialogsMetricsStore          See Also

Specifies the dialog’s default position.

property DefaultPosition: TPosition;

Description

The specified position is used for the dialog that doesn’t have stored dialog settings.

The default value of the DefaultPosition property is poMainFormCenter.

The following example demonstrates how to specify that the default position of the dialog is the center of the screen:

// Delphi

// ...

uses

  // ...

  cxClasses;

initialization

  cxDialogsMetricsStore.DefaultPosition := poDesktopCenter;


TcxDialogsMetricsStore.InitDialog

TcxDialogsMetricsStore          See Also

Applies settings to the AForm dialog.

procedure InitDialog(AForm: TForm);

Description

The InitDialog method first determines whether settings (previously saved using the StoreMetrics method) exist for the specified dialog. If they do exist, the method simply applies them to the dialog. Otherwise, the default position (specified by the DefaultPosition property) is only applied to the dialog.


TcxDialogsMetricsStore.StoreMetrics

TcxDialogsMetricsStore          See Also

Saves the AForm dialog’s settings.

procedure StoreMetrics(AForm: TForm);

Description

Use the StoreMetrics method to store dialog settings for further use during the application session.


TcxInterfacedPersistent
TcxInterfacedPersistent Object

Hierarchy

Represents a base class for objects implementing interfaces which support loading and saving of properties from/to a stream.

Unit

cxClasses

TcxInterfacedPersistent = class({$IFDEF DELPHI6}TInterfacedPersistent {$ELSE}TPersistent, IUnknown {$ENDIF});

Description

The TcxInterfacedPersistent class is designed to provide support for persistent objects implementing interfaces via different versions of the IDE.  If you use an IDE prior to Delphi 6, it provides the members necessary to implement the functionality for working with interfaces.

Additionally, it overrides the GetOwner method so it returns the class passed as the parameter to the constructor.


TcxInterfacedPersistent Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent


TcxMRUItem
TcxMRUItem Object

Methods          See Also

Represents an item in the lists of most recently used items.

Unit

cxClasses

TcxMRUItem = class

Description

A list of most recently used items is used to maintain the choices (such as filtering options in the ExpressQuantumGrid) made by end-users for future use or tracking activities.  The TcxMRUItem class is the base class for classes which represent this kind of items.  The Equals abstract function is the only member which is introduced by the TcxMRUItem class.  When implemented in descendant classes this function determines whether the item which is represented by an instance of the TcxMRUItem class is equal to the specified item.


Methods for TcxMRUItem
TcxMRUItem Methods

TcxMRUItem          Legend

In TcxMRUItem

Equals


TcxMRUItem.Equals

TcxMRUItem

Determines whether the current item is equal to the specified item.

function Equals(AItem: TcxMRUItem): Boolean; virtual; abstract;

Description

This function is abstract.  Descendants of the TcxMRUItem class have to implement the Equals function to return whether the current item is equal to the item which is specified by the AItem parameter.  When the items are the same, this function returns True. Otherwise, False is returned.


TcxMRUItems
TcxMRUItems Object

Properties          Methods

Represents a list of most recently used items.

Unit

cxClasses

TcxMRUItems = class

Description

A list of most recently used items (MRU list for short) is used to maintain the choices (such as filtering options in the ExpressQuantumGrid) made by end-users for future use or tracking activities.  The TcxMRUItems class is the base class for classes which represent MRU lists.  Each item in MRU lists is represented by an instance of the TcxMRUItem class.

The TcxMRUItems class provides the Add and ClearItems methods and, the Count and MaxCount properties for managing the MRU list’s contents.  Use the Items property to access the contents (items).  Call the IndexOf function to determine the position of a specific item within the MRU list.


Properties for TcxMRUItems
TcxMRUItems Properties

TcxMRUItems          Legend

In TcxMRUItems

Count

Items

MaxCount


Methods for TcxMRUItems
TcxMRUItems Methods

TcxMRUItems          Legend

In TcxMRUItems

Add

ClearItems

IndexOf


TcxMRUItems.Count

TcxMRUItems

Specifies the number of items within the current MRU list.

property Count: Integer;

Description

Use the Count to determine the number of items within the current MRU list.  You can decrease the number of items by setting the Count property to the value which is less than the current value.  This results in deleting all the items up to the item (inclusive) with the index specified by the new Count property’s value.

Use the MaxCount property to limit the maximum number of items within the current MRU list.


TcxMRUItems.Items

TcxMRUItems

Provides indexed access to the items within the current MRU list.

property Items[Index: Integer]: TcxMRUItem;

Description

Use the Items property to access the items within the current MRU list using the index.  To determine the index of a specific item, call the IndexOf function.

Use the Count property to get and set the number of items within the current MRU list.  Use the MaxCount property to limit the maximum number of items within the list.  To add new items to the current MRU list, call the Add method.

ReadOnly Property


TcxMRUItems.MaxCount

TcxMRUItems

Specifies the maximum number of items within the current MRU list.

property MaxCount: Integer;

Description

To limit the maximum number of items within the current MRU list up to a specific value, set the MaxCount property to the value which is greater than 0.  That is adding the items via the Add method does not enlarge the number of items within the list since it is limited to the MaxCount property’s value.

Setting the MaxCount property to 0 indicates that the current MRU list’s capacity is unlimited.

Use the Count property to determine the number of items within the current MRU list.

You can decrease the number of items by setting the MaxCount property to the value which is less than the current Count property’s value.  This results in deleting all the items up to the item (inclusive) with the index specified by the new MaxCount property’s value.


TcxMRUItems.Add

TcxMRUItems

Adds an item to the current MRU list.

procedure Add(AItem: TcxMRUItem);

Description

Prior to adding the item specified by the AItem parameter to the current MRU list, the Add method determines whether the item is already in the list.  When the list contains the item, it is moved to the topmost position (with index equal to 0).  Otherwise, the item is added to the MRU list at the topmost position thus enlarging the number of items within it.  This takes place until the number of items reaches the MaxCount property’s value.  Furthermore, adding an item results in this item being added to the top of the MRU list and deleting the bottom item in that list.

Use the Count property to determine the number of items within the current MRU list.

Call the IndexOf function to determine the position of a specific item within the MRU list.


TcxMRUItems.ClearItems

TcxMRUItems         See Also

Removes all items from the current MRU list.

procedure ClearItems;

Description

Call the ClearItems method to clear the current MRU list by removing all its items.


TcxMRUItems.IndexOf

TcxMRUItems         See Also

Determines the position (index) of an item within the current MRU list.

function IndexOf(AItem: TcxMRUItem): Integer;

Description

Call the IndexOf function to determine the position (index) of the item specified by the AItem parameter within the current MRU list.  This function returns -1 when the specified item does not exist within the current MRU list.


IcxDialogMetricsInfoData
IcxDialogMetricsInfoData Interface

Hierarchy          Methods          See Also

Allows a dialog to store custom settings when used with TcxDialogsMetricsStore.

Unit

cxClasses

IcxDialogMetricsInfoData = interface(IUnknown)

Description

To persist custom dialog settings, a dialog class must implement the IcxDialogMetricsInfoData interface, so that TcxDialogMetricsInfo (which is used by the TcxDialogsMetricsStore) can save and restore the required custom information for a given dialog.


IcxDialogMetricsInfoData Hierarchy
Hierarchy

IUnknown

     |

IcxDialogMetricsInfoData


Methods for IcxDialogMetricsInfoData
IcxDialogMetricsInfoData Methods

IcxDialogMetricsInfoData          Legend

In IcxDialogMetricsInfoData

 GetInfoData

 GetInfoDataSize

 SetInfoData


IcxDialogMetricsInfoData.GetInfoData

IcxDialogMetricsInfoData          See Also

Returns a pointer to a value object that contains a dialog’s custom settings.

function GetInfoData: Pointer;


IcxDialogMetricsInfoData.GetInfoDataSize

IcxDialogMetricsInfoData          See Also

Returns the size, in bytes, of memory occupied by a value object that contains a dialog’s custom settings.

function GetInfoDataSize: Integer;


IcxDialogMetricsInfoData.SetInfoData

IcxDialogMetricsInfoData          See Also

Populates the AData value object with a dialog’s custom settings.

procedure SetInfoData(AData: Pointer);


TdxSkinName type

See Also

Represents a skin name.

Unit

cxClasses

type

  TdxSkinName = type string;


cxDialogsMetricsStore
cxDialogsMetricsStore Function

See Also

Instantiates a TcxDialogsMetricsStore object that stores a dialog’s settings.

Unit

cxClasses

Declaration

function cxDialogsMetricsStore: TcxDialogsMetricsStore;

Description

The cxDialogsMetricsStore routine returns a reference to the TcxDialogsMetricsStore instance.


cxGetResourceString
cxGetResourceString Function

Retrieves a resource string for the specified resource identifier.

Unit

cxClasses

Declaration

function cxGetResourceString(const ResString: Pointer): string;

Description

The cxGetResourceString function retrieves a resource string for the resource identifier specified by the ResString parameter.  You pass the address of the resource string as the identifier

String constants for Express products are stored as resources.  The cxGetResourceString function is used internally to retrieve strings for specific control elements.  For instance, a date editor determines the caption to be displayed on the Clear button within the dropdown calendar by reading the value of the cxSDatePopupClear resource string as follows:

  cxGetResourceString(@cxSDatePopupClear);

By default, it displays ‘Clear’.

For the purpose of localization, you can change the resource strings depending on the language and the regional settings.  To do so, call the cxSetResourceString procedure passing a resource identifier and the new value of the resource string as parameters.  This procedure substitutes the value of the resource string during execution only.

For instance, the following code specifies a new value for the cxSDatePopupClear resource string in the German language:

//Delphi

cxSetResourceString(@cxSDatePopupClear, 'Löschen');

//C++ Builder

cxSetResourceString(&_cxSDatePopupClear, "Löschen");


cxSetResourceString
cxSetResourceString Procedure

Substitutes a value of the resource string retrieved by the cxGetResourceString function.

Unit

cxClasses

Declaration

procedure cxSetResourceString(const ResString: Pointer; const Value: string);

Description

String constants for Express products are stored as resources.  The cxGetResourceString function is used internally to retrieve strings for specific control elements.  You might use the cxSetResourceString procedure to substitute a value of a specific resource string during the program execution for localization purposes.  Note that a new value does not replace a resource in an executable file.

The ResString argument specifies a resource string identifier.  You should pass an address of the resource string as the ResString parameter.  A new value of the resource string is determined by Value.

In the cxEditConsts unit, the cxSDatePopupClear resource string is declared.  By default, it identifies the ‘Clear’ string displayed in a button within the dropdown calendar of the date editor.  To display the German equivalent of the string, you can use the cxSetResourceString procedure.

//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.


cxContainer Unit Overview
cxContainer Unit

Classes

TcxContainer

TcxContainerStyle

TcxContainerStyleEx

TcxCustomContainerStyle

TcxStyleController

Interfaces

IcxContainerInnerControl

Global Constants

cxContainerShadowWidth

cxDefaultAutoCompleteDelay

Other Types

TcxContainerBorderStyle

TcxContainerStateItem

Routines

GetcxContainer


TcxContainer
TcxContainer Object

Hierarchy          Properties          Methods          See Also

Represents a class which clips child windowed controls within a specified region.

Unit

cxContainer

TcxContainer = class(TcxControl, IcxMouseTrackingCaller);

Description

The TcxContainer class is the base class for TcxCustomEdit which provide the base functionality for ExpressQuantumEditors.  The TcxContainer class implements the clipping of a windowed control.  When placing child windowed controls onto the client region of a TcxContainer, only the region defined by the client rectangle is painted.  The TcxContainer class introduces the style attributes (see the Style, StyleDisabled, StyleFocused and StyleHot properties) which control the appearance of the container control in various states such as normal, disabled, focused and hot-tracked (highlighted), respectively.  The TcxContainer class provides the RestoreStyles method to restore the default style attributes’ values for a container control.  A custom editor has to implement the IcxContainerInnerControl interface in order to provide a link to the container control associated with it (see the GetcxContainer function).


TcxContainer Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |


Properties for TcxContainer
TcxContainer Properties

TcxContainer          Legend

In TcxContainer

 Style

 StyleDisabled

 StyleFocused

 StyleHot

 Styles

Derived from TcxControl

BorderStyle

Bounds

Canvas

ClientBounds

FocusOnClick

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxContainer
TcxContainer Methods

TcxContainer          Legend

In TcxContainer

 RestoreStyles

Derived from TcxControl

 Create

 Destroy


TcxContainer.Style

TcxContainer

Provides access to the TcxContainerStyle object containing the normal state settings for the container control.

property Style: TcxContainerStyle;

Description

The Style property provides access to the TcxContainerStyle object that contains the style settings applied to the container control in the normal state.  You can use its properties to specify the border color, border style, background color, font settings and look & feel of the container which are accessible via the corresponding properties.

Note:	To customize the style settings that are used for drawing the container control in states other than the normal one, such as disabled, focused or hot-tracked, use the StyleDisabled, StyleFocused and StyleHot properties, respectively.


TcxContainer.StyleDisabled

TcxContainer

Provides access to the TcxContainerStyleEx object containing the disabled state settings for the container control.

property StyleDisabled: TcxContainerStyleEx;

Description

The StyleDisabled property provides access to the TcxContainerStyleEx object that contains the style settings applied to the disabled container control.  You can use its properties to specify the border color, border style, background color and font settings which are accessible via the corresponding properties.

Note:	To customize the style settings that are used for drawing the container control in states other than the disabled one, such as normal, focused or hot-tracked, use the Style, StyleFocused and StyleHot properties, respectively.


TcxContainer.StyleFocused

TcxContainer

Provides access to the TcxContainerStyleEx object containing the focused state settings for the container control.

property StyleFocused: TcxContainerStyleEx;

Description

The StyleFocused property provides access to the TcxContainerStyleEx object that contains the style settings applied to the focused container control.  You can use its properties to specify the border color, border style, background color and font settings which are accessible via the corresponding properties.

Note:	To customize the style settings that are used for drawing the container control in states other than the focused one, such as normal, disabled or hot-tracked, use the Style, StyleDisabled and StyleHot properties, respectively.


TcxContainer.StyleHot

TcxContainer

Provides access to the TcxContainerStyleEx object containing the highlighted state settings for the container control.

property StyleHot: TcxContainerStyleEx;

Description

The StyleHot property provides access to the TcxContainerStyleEx object that contains the style settings applied to the highlighted (hot-tracked) container control (when the mouse cursor hovers over it).  You can use its properties to specify the border color, border style, background color and font settings which are accessible via the corresponding properties.

Note:	To customize the style settings that are used for drawing the container control in states other than the highlighted one, such as normal, disabled or focused, use the Style, StyleDisabled and StyleFocused properties, respectively.


TcxContainer.Styles

TcxContainer

Provides access to the styles assigned to the current container control.

procedure Styles[AState: TcxContainerStateItem]: TcxCustomContainerStyle;

Description

Each style corresponds to a particular container control’s state such as normal, disabled, etc. (see the TcxContainerStateItem type description for details).  The Styles property provides an access to the specific style which is assigned to the current container control and matches the control state specified by the AState parameter.


TcxContainer.RestoreStyles

TcxContainer

Restores the default values to the style attributes of all the styles provided by the current container control.

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).


TcxStyleController
TcxStyleController Object

Hierarchy          Properties          Methods

Represents the base class for objects managing style attributes common to several components.

Unit

cxContainer

TcxStyleController = class(TComponent);

Description

A style controller manages style properties common to several components.  When a style is assigned a style controller, it is automatically registered as a listener of this style controller.  Thus, when you change properties via a style controller, all style objects will receive corresponding notifications and repaint their components as necessary.  Use the Styles property to access a specific style and call the RestoreStyles method to restore the default values to all the style attributes of every style object.

The TcxStyleController is the base class for TcxEditStyleController which allows you to define style properties common to several editors.


TcxStyleController Hierarchy
Hierarchy

TComponent

     |


Properties for TcxStyleController
TcxStyleController Properties

TcxStyleController          Legend

In TcxStyleController

 Styles


Methods for TcxStyleController
TcxStyleController Methods

TcxStyleController          Legend

In TcxStyleController

 RestoreStyles


TcxStyleController.Styles

TcxStyleController

Provides access to the styles assigned to the current style controller.

procedure Styles[AState: TcxContainerStateItem]: TcxCustomContainerStyle;

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 style controller and matches the control state specified by the AState parameter.


TcxStyleController.RestoreStyles

TcxStyleController

Restores the default values to all the style attributes associated with the current 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 style controller.


TcxContainerStyle
TcxContainerStyle Object

Hierarchy          Properties          Methods

Contains the style settings applied to the associated container control.

Unit

cxContainer

TcxContainerStyle = class(TcxCustomContainerStyle)

Description

The TcxContainerStyle class does not introduce any new properties or methods that control the appearance of the associated container control, instead it merely publishes the properties of the TcxCustomContainerStyle class instead.

The TcxContainerStyle class represents the type of the Style property in the TcxContainer class which provides the base functionality for all ExpressQuantumEditors.


TcxContainerStyle Hierarchy
Hierarchy

TPersistent

     |

TcxCustomContainerStyle

     |


Properties for TcxContainerStyle
TcxContainerStyle Properties

TcxContainerStyle          Legend

Derived from TcxCustomContainerStyle

ActiveStyleController

 AssignedValues

 BorderColor

 BorderStyle

 Color

Container

 Edges

 Font

 HotTrack

 LookAndFeel

 Shadow

State

 StyleController

 TextColor

 TextStyle

 TransparentBorder


Methods for TcxContainerStyle
TcxContainerStyle Methods

TcxContainerStyle          Legend

Derived from TcxCustomContainerStyle

 Assign

 BeginUpdate

 Create

 Destroy

 EndUpdate

 RestoreDefaults


TcxContainerStyleEx
TcxContainerStyleEx Object

Hierarchy          Properties          Methods

Contains the style settings which are applied to the associated container control for special states such as disabled, focused or hot-tracked.

Unit

cxContainer

TcxContainerStyleEx = class(TcxCustomContainerStyle)

Description

The TcxContainerStyleEx class, like the TcxContainerStyle class does not introduce new properties and methods that control the appearance of the associated container control, instead it publishes the properties of the TcxCustomContainerStyle class.  The set of published properties is determined by the TcxContainerStyleEx class’s functionality, i.e. only border, background color and text style attributes can be used to show that the control is in a special state such as disabled, focused or hot-tracked.

The TcxContainerStyleEx class represents the type of the StyleDisabled, StyleFocused and StyleHot properties in the TcxContainer class which provides base functionality for all ExpressQuantumEditors.


TcxContainerStyleEx Hierarchy
Hierarchy

TPersistent

     |

TcxCustomContainerStyle

     |


Properties for TcxContainerStyleEx
TcxContainerStyleEx Properties

TcxContainerStyleEx          Legend

Derived from TcxCustomContainerStyle

ActiveStyleController

 AssignedValues

 BorderColor

 BorderStyle

 Color

Container

Edges

Font

HotTrack

LookAndFeel

Shadow

State

StyleController

 TextColor

 TextStyle

TransparentBorder


Methods for TcxContainerStyleEx
TcxContainerStyleEx Methods

TcxContainerStyleEx          Legend

Derived from TcxCustomContainerStyle

 Assign

 BeginUpdate

 Create

 Destroy

 EndUpdate

 RestoreDefaults


TcxCustomContainerStyle
TcxCustomContainerStyle Object

Hierarchy          Properties          Methods          Events

Represents the style settings which can be applied to the associated container control.

Unit

cxContainer

TcxCustomContainerStyle = class(TPersistent)

Description

The TcxCustomContainerStyle class introduces properties that control the appearance of the associated container control.  The following style characteristics can be modified:

•	Border color, style and displayed edges (see the BorderColor, BorderStyle and Edges properties);

•	Background color (see the Color property);

•	Font (see the Font property);

•	Displaying shadow (see the Shadow property);

•	Look & feel (see the LookAndFeel property) - you can either use the native style defined by the operating system or apply one of the three predefined styles;

•	Color and style for the text (see the TextColor and TextStyle properties).

The TcxCustomContainerStyle class is a base class for the container control and editor styles.


TcxCustomContainerStyle Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxCustomContainerStyle
TcxCustomContainerStyle Properties

TcxCustomContainerStyle          Legend

In TcxCustomContainerStyle

ActiveStyleController

AssignedValues

BorderColor

BorderStyle

Color

Container

Edges

Font

HotTrack

LookAndFeel

 ParentStyle

Shadow

State

StyleController

TextColor

TextStyle

TransparentBorder


Methods for TcxCustomContainerStyle
TcxCustomContainerStyle Methods

TcxCustomContainerStyle          Legend

In TcxCustomContainerStyle

 Assign

 BeginUpdate

 Create

 Destroy

 EndUpdate

 GetVisibleFont

 RestoreDefaults


Events for TcxCustomContainerStyle
TcxCustomContainerStyle Events

TcxCustomContainerStyle          Legend

In TcxCustomContainerStyle

OnChanged


TcxCustomContainerStyle.ActiveStyleController

TcxCustomContainerStyle

Identifies the style controller which manages the appearance of the associated container control.

property ActiveStyleController: TcxStyleController;

Description

Use the ActiveStyleController property to get the style controller (TcxEditStyleController or TcxDefaultEditStyleController component) which manages the style of the associated container control and defines the style properties common to several controls.

See the Editor Style and StyleController topic for detailed information about the style controllers.

ReadOnly Property


TcxCustomContainerStyle.AssignedValues

TcxCustomContainerStyle

Specifies which style properties are assigned via the TcxCustomContainerStyle class.

property AssignedValues: TcxContainerStyleValues;

Description

The AssignedValues property is a set of flags demonstrating which style properties were set by a user at design time or programmatically.  The AssignedValues property controls whether values for style properties are obtained from the current TcxCustomContainerStyle instance or from the style controller, which can be set via the StyleController property.  In this case, the assignment of the property values using the specified style controller is not tracked via the control’s AssignedValues property, you should use the style controller’s AssignedValues property instead.

The RestoreDefaults method restores the default values of the assigned style attributes and clears all the flags in the AssignedValues property of the current TcxCustomContainerStyle object.


TcxCustomContainerStyle.BorderColor

TcxCustomContainerStyle

Specifies the border color for the associated container control.

property BorderColor: TColor;

Description

Use the BorderColor property to change the border color of the associated container control.  Note that this property is in effect only if the BorderStyle property's value is either cbsSingle or cbsThick.

The image below shows the list box control when the BorderColor property is set to clActiveCaption while the BorderStyle property's value is cbsThick.

Note: the BorderColor property is not in effect if the LookAndFeel.NativeStyle property is set to True (the border color and style is specified by the operating system's settings).

When the BorderColor property is assigned, the csvBorderColor flag is set to the AssignedValues property.

The default value of the BorderColor property is clWindowFrame.


TcxCustomContainerStyle.BorderStyle

TcxCustomContainerStyle

Specifies the border style of the associated container control.

property BorderStyle: TcxContainerBorderStyle;

Description

Use the BorderStyle property to change the border style applied to the associated container control.  The Edges property specifies which border sides are to be displayed.  See the TcxContainerBorderStyle type's description for the list of available values for the BorderStyle property.

Note: if the BorderStyle property is set to a value other than cbsNone this property is not in effect while the LookAndFeel.NativeStyle property is set to True.  The border style in this case is specified by the operating system's settings.

When the BorderStyle property is assigned, the csvBorderStyle flag is set to the AssignedValues property.

The default value of the BorderStyle property is cbsDefault.


TcxCustomContainerStyle.Color

TcxCustomContainerStyle

Specifies the background color of the associated container control.

property Color: TColor;

Description

Use the Color property to specify the background color of the control.  The image below displays the list box control, when the Color property is set to clWhite and clInactiveCaptionText, respectively.

When the Color property is assigned, the csvColor flag is set to the AssignedValues property.

The default value of the Color property is clWindow.


TcxCustomContainerStyle.Container

TcxCustomContainerStyle

Gets the associated container control.

property Container: TcxContainer;

Description

The TcxCustomContainerStyle object specifies the style settings for bound controls.  For instance, it is used to control the style of the TcxListBox control and can be accessed via its Style property.

The Container property returns the associated container control to which style settings are applied.  Normally, you will not need to use this property in your applications.

ReadOnly Property


TcxCustomContainerStyle.Edges

TcxCustomContainerStyle

Specifies which border edges are to be displayed.

type

  TcxBorder = (bLeft, bTop, bRight, bBottom);

  TcxBorders = set of TcxBorder;

property Edges: TcxBorders;

Description

Use the Edges property to specify which borders  are displayed around the control.  This property can contain a set of values corresponding to border edges.  The table below lists the available values and describes them.

Value	Description
bLeft	If this value is in the set, the left border edge is displayed.
bTop	If this value is in the set, the top border edge is displayed.
bRight	If this value is in the set, the right border edge is displayed.
bBottom	If this value is in the set, the bottom border edge is displayed.

The image below displays the list box control when the Edges property is set to [bLeft, bTop] and the BorderStyle property value is cbsSingle.

When the Edges property is assigned, the csvEdges flag is set to the AssignedValues property.

The default value of the Edges property is [bLeft,bTop,bRight,bBottom].


TcxCustomContainerStyle.Font

TcxCustomContainerStyle

Specifies the font used to display the text content of the associated container control.

property Font: TFont;

Description

Use the Font property to change the font used to paint the control’s content.  When the Font property is assigned, the csvFont flag is set to the AssignedValues property.

The image below shows the list box with a standard and custom font applied.

Note:	The values of the Font, TextColor and TextStyle properties comprise the font settings used to paint the control’s content and can be obtained via the GetVisibleFont function.


TcxCustomContainerStyle.HotTrack

TcxCustomContainerStyle

Specifies whether the associated container control changes its border style when the mouse pointer enters or leaves its area.

property HotTrack: Boolean;

Description

If the HotTrack property is set to True, the associated container control is hot-tracked when the mouse pointer enters its area.  Note that when this control has focus, it doesn’t respond to mouse movements.  Controls are only hot-tracked if another control is currently focused.  Controls are hot-tracked by changing their border style.  Note, that the HotTrack property is not in effect when the border is painted in 3D or thick style.  The border style depends on the BorderStyle and LookAndFeel.Kind property values.  When the HotTrack property is assigned, the csvHotTrack flag is set to the AssignedValues property.

The default value of the HotTrack property is True.


TcxCustomContainerStyle.LookAndFeel

TcxCustomContainerStyle

Specifies the look & feel settings of the associated container control.

property LookAndFeel: TcxLookAndFeel;

Description

Use the LookAndFeel property to specify the painting style for the control and the way it responds to user actions.  You can use the system-defined painting style and behavior by setting the LookAndFeel.NativeStyle property to True.  If so, most of the style settings specified by the TcxCustomContainerStyle object’s properties are ignored.  Otherwise, the look & feel of the associated container control is specified by the LookAndFeel.Kind or LookAndFeel.SkinName property taking into account the specified style settings.

The image below shows the list box control when the LookAndFeel.NativeStyle property's value is True (The image assumes that the Windows XP operating system is used).

The next image displays the same control when the LookAndFeel.Kind property's value is lfFlat, lfStandard, lfUltraFlat, and lfOffice11 respectively (the LookAndFeel.NativeStyle property value is False).


TcxCustomContainerStyle.ParentStyle

TcxCustomContainerStyle

Retrieves the parent style for the current style of the associated container control.

property ParentStyle: TcxCustomContainerStyle;

Description

Use the ParentStyle property to get the style used as a base style for various painting styles (disabled, focused, hot-tracked).

ReadOnly Property


TcxCustomContainerStyle.Shadow

TcxCustomContainerStyle

Specifies whether a shadow is displayed for the associated container control.

property Shadow: Boolean;

Description

Set the Shadow property to True to display the control’s shadow.  The width of the shadow is specified by the cxContainerShadowWidth global constant.  When the Shadow property is assigned, the csvShadow flag is set to the AssignedValues property.

The image below shows the list box control when the Shadow property is set to False and True respectively.

The default value of the Shadow property is False.


TcxCustomContainerStyle.State

TcxCustomContainerStyle

Indicates the state which the current style represents.

property State: TcxContainerStateItem;

Description

Use the State property to determine the state of the associated container control which the current style represents.  See the TcxContainerStateItem for a list of the possible control states.

ReadOnly Property


TcxCustomContainerStyle.StyleController

TcxCustomContainerStyle

Identifies the style controller for the current TcxCustomContainerStyle object.

property StyleController: TcxStyleController;

Description

Use the StyleController property to assign a style controller which defines style attributes common to several controls.

See the Editor Style and StyleController topic for detailed information about style controllers.


TcxCustomContainerStyle.TextColor

TcxCustomContainerStyle

Specifies the color of the text which is displayed by the associated container control.

property TextColor: TColor;

Description

The TextColor defines the color of the text (in contrast to the background color determined by the Color property).  When the TextColor property is assigned, the csvTextColor flag is set to the AssignedValues property.  For an unassigned TextColor property, the return value is equal to the Font.Color property’s value.

Note:	The values of the Font, TextColor and TextStyle properties comprise the font settings used to paint the control’s content and can be obtained via the GetVisibleFont function.


TcxCustomContainerStyle.TextStyle

TcxCustomContainerStyle

Specifies the style of the text which is displayed by the associated container control.

property TextStyle: TFontStyles;

Description

There are four styles available: Bold, Italic, Underline and StrikeOut.  When the TextStyle property is assigned, the csvTextStyle flag is set to the AssignedValues property.  For an unassigned TextStyle property, the return value is equal to the Font.Style property’s value.

Note:	The values of the Font, TextColor and TextStyle properties comprise the font settings used to paint the control’s content and can be obtained via the GetVisibleFont function.


TcxCustomContainerStyle.TransparentBorder

TcxCustomContainerStyle

Specifies whether a transparent border is drawn around the associated container control.

property TransparentBorder: Boolean;

Description

Set the TransparentBorder property to True to draw a transparent border around the control.  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 a container control with its BorderStyle property set to cbsNone and 1 pixel wide for a container control with the BorderStyle property set to cbsSingle, cbsUltraFlat or cbsOffice11.  For a control which uses native windows style for its painting the transparent border is drawn when its BorderStyle property is set to cbsNone.  When the TransparentBorder property is assigned, the csvTransparentBorder flag is set to the AssignedValues property.


TcxCustomContainerStyle.Assign

TcxCustomContainerStyle

Assigns settings of one TcxContainerStyle object to another.

procedure Assign(Source: TPersistent); override;

Description

Use the Assign method to copy the settings of one TcxContainerStyle object to the another.  The Source parameter represents the source object.  The caller is the destination object.

Use this method if you want to assign the same or slightly different style settings to several controls.


TcxCustomContainerStyle.BeginUpdate

TcxCustomContainerStyle

Prevents the associated container control from updating due to style changes.

procedure BeginUpdate;

Description

Each time a property of the TcxContainerStyle object is changed, the associated container control is updated.  This behavior is undesirable when you want to perform sequential style changes, since the control will be repainted several times.  The BeginUpdate and EndUpdate methods allow you to avoid this.

Each time the BeginUpdate method is called, it increments the internal counter.  The control is notified of style changes only when this counter is zero (its initial value).  Thus, you can perform any style changes after the BeginUpdate method call and they will not affect the control.  When calling the EndUpdate method, the counter is decremented, and the control is updated to reflect all style changes performed.


TcxCustomContainerStyle.Create

TcxCustomContainerStyle

Creates a new instance of the TcxContainerStyle object.

procedure Create(AOwner: TPersistent; ADirectAccessMode: Boolean); virtual;

Description

The constructor is used to create a new TcxContainerStyle object with default style settings.  The AOwner parameter represents the associated container control.  The ADirectAccessMode parameter is used to indicate whether the control accesses the style settings directly, or the style object should notify it of changes performed.  It must be set to False to enable automatic notification.

Commonly, you will have no need to create TcxContainerStyle objects in applications.  They are created automatically by controls that use them.


TcxCustomContainerStyle.Destroy

TcxCustomContainerStyle

Destroys the TcxContainerStyle object.

procedure Destroy; override;

Description

The destructor is used to dispose the TcxContainerStyle object and free any allocated memory.  Commonly, you will have no need to destroy such objects manually in applications.  Objects of this type are automatically destroyed by controls that use them.


TcxCustomContainerStyle.EndUpdate

TcxCustomContainerStyle

Updates the associated container control with respect to style changes made after the BeginUpdate method call.

procedure EndUpdate;

Description

The BeginUpdate and EndUpdate methods are used in combination.  The first one increments the internal counter, while the second decrements it and updates the control.  The internal counter is initially zero and must be zero for the control to update.  So you can implement sequential style changes between the BeginUpdate and EndUpdate method calls and the control will be repainted only once.


TcxCustomContainerStyle.GetVisibleFont

TcxCustomContainerStyle

Retrieves the font settings that the current style specified for displaying the container control’s text.

function GetVisibleFont: TFont;

Description

Retrieves the font settings of the TFont type the current style specified via the Font, TextColor and TextStyle properties for displaying the container control’s text.


TcxCustomContainerStyle.RestoreDefaults

TcxCustomContainerStyle

Applies default look & feel to the control.

procedure RestoreDefaults; virtual;

Description

The RestoreDefaults method assigns an empty set to the LookAndFeel.AssignedValues property.  Thus, the LookAndFeel property doesn’t affect the style of the associated container control.  Values of other properties are preserved and specify the appearance of the control.


TcxCustomContainerStyle.OnChanged

TcxCustomContainerStyle

Occurs when any property of the TcxCustomContainerStyle class is changed.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnChanged: TNotifyEvent;

Description

The OnChanged event occurs every time any property of the TcxCustomContainerStyle class is changed.


GetcxContainer
GetcxContainer Function

Obtains the container control for a particular control.

Unit

cxContainer

Declaration

function GetcxContainer(AControl: TWinControl): TcxContainer;

Description

The GetcxContainer method obtains the container control of the TcxContainer type for the control specified by the AControl parameter.  This function performs the appropriate cast for the TcxContainer descendant.  If an object implements the IcxContainerInnerControl interface the function retrieves the container control via the IcxContainerInnerControl.ControlContainer property.


cxContainerShadowWidth constant
cxContainerShadowWidth global constant

Specifies the width of the shadow painted for container controls.

Unit

cxContainer

cxContainerShadowWidth = 3;

Description

Container controls (for instance, the TcxListBox control) use the TcxContainerStyle object to control their appearance.  This object’s Shadow property specifies whether the shadow is displayed.  The width of the shadow is specified by the cxContainerShadowWidth global constant which is equal to 3 by default.


cxDefaultAutoCompleteDelay constant
cxDefaultAutoCompleteDelay global constant

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.

Unit

cxContainer

cxDefaultAutoCompleteDelay = 500;

Description

The cxDefaultAutoCompleteDelay global constant is used by the container controls which support incremental search (for instance, the TcxCustomListBox, TcxListBox, TcxCustomCheckListBox, TcxCheckListBox controls) to specify the time interval during which any additional key presses that are made will be treated as an addition to the filter string used in the incremental search.  When the number of milliseconds specified by cxDefaultAutoCompleteDelay has passed, the filter string is reset so that it consists only of the last key pressed.

The default value of the cxDefaultAutoCompleteDelay global constant is equal to 500 (which means a half second delay).


TcxContainerStyleValue type

Enumerates the flags that describe which control style attributes are assigned.

Unit

cxContainer

TcxEditStyleValue = (csvBorderColor, csvBorderStyle, csvColor, csvEdges, csvFont, csvHotTrack, csvShadow, csvTextColor, csvTextStyle, csvTransparentBorder);

Description

The TcxContainerStyleValue type enumerates the flags that indicate which control style attributes are assigned to the TcxCustomContainerStyle object.  These flags are set via the TcxCustomContainerStyle.AssignedValues property.

Value	Meaning
csvBorderColor	Indicates that the TcxCustomContainerStyle.BorderColor property is assigned a value.
csvBorderStyle	Indicates that the TcxCustomContainerStyle.BorderStyle property is assigned a value.
csvColor	Indicates that the TcxCustomContainerStyle.Color property is assigned a value.
csvEdges	Indicates that the TcxCustomContainerStyle.Edges property is assigned a value.
csvFont	Indicates that the TcxCustomContainerStyle.Font property is assigned a value.
csvHotTrack	Indicates that the TcxCustomContainerStyle.HotTrack property is assigned a value.
csvShadow	Indicates that the TcxCustomContainerStyle.Shadow property is assigned a value.
csvTextColor	Indicates that the TcxCustomContainerStyle.TextColor property is assigned a value.
csvTextStyle	Indicates that the TcxCustomContainerStyle.TextStyle property is assigned a value.
csvTransparentBorder	Indicates that the TcxCustomContainerStyle.TransparentBorder property is assigned a value.


TcxContainerStyleValues type

Represents a set of flags indicating which container style attributes are assigned.

Unit

cxContainer

TcxContainerStyleValues = set of TcxContainerStyleValue;

Description

Each container control provides the Style, StyleDisabled, StyleFocused and StyleHot properties which present style attributes for various states of a control.  The TcxCustomContainerStyle.AssignedValues member of the TcxContainerStyleValues type describes which style attributes are explicitly assigned to these style properties.


TcxContainerStateItem type

Specifies the state of the control.

type

  TcxContainerStateItem = (csNormal, csActive, csDisabled, csHotTrack);

Description

Represents the state of the control.  The following table lists the possible states of a control.

Value	Meaning
csNormal	The normal state of the control.
csActive	The control is active, i.e. has focus.
csDisabled	The control is disabled.
csHotTrack	The control is highlighted, i.e. hot-tracked.


TcxContainerBorderStyle type

Specifies the border style of the associated container control.

Unit

cxContainer

type

  TcxContainerBorderStyle = (cbsNone, cbsSingle, cbsThick, cbsFlat, cbs3D, cbsUltraFlat, cbsOffice11);

Description

Specifies the border style of the container control.  The following table below lists the possible border styles.

Value	Description	Image
cbsDefault	The border style is specified by the look & feel applied to the control (the LookAndFeel property).
cbsNone	No border is painted around the control.
cbsSingle	A single-pixel border is painted around the control.  Its color is specified by the BorderColor property.
cbsThick	A thick border is painted around the control.  Its color is specified by the BorderColor property.
cbsFlat	A flat border is painted around the control.
cbs3D	A 3D lowered border is painted around the control.
cbsUltraFlat	An ultra flat border is painted around the control.
cbsOffice11	A border is painted around the control in the  Office 2003 control style.


IcxContainerInnerControl
IcxContainerInnerControl Interface

Properties         Methods

Unit

cxContainer

Description

Every inner Developer Express control, which is placed in the TcxContainer control, has to implement the IcxContainerInnerControl interface to provide a link to its container via the ControlContainer property.


Properties for IcxContainerInnerControl
IcxContainerInnerControl Properties

IcxContainerInnerControl          Legend

In IcxContainerInnerControl

 ControlContainer


Methods for IcxContainerInnerControl
IcxContainerInnerControl Methods

IcxContainerInnerControl          Legend

In IcxContainerInnerControl

 GetControlContainer


IcxContainerInnerControl.ControlContainer

IcxContainerInnerControl

property ControlContainer: TcxContainer read GetControlContainer;

Description

Gets the container control which is returned by the GetControlContainer function.

ReadOnly Property


IcxContainerInnerControl.GetControlContainer

IcxContainerInnerControl

function GetControlContainer: TcxContainer;

Description

Returns the container control associated with the current inner control.


cxPropertiesStore Unit Overview
cxPropertiesStore Unit

Classes

TcxCustomPropertiesStore

TcxPropertiesStore

TcxPropertiesStoreComponent

TcxPropertiesStoreComponents


TcxCustomPropertiesStore
TcxCustomPropertiesStore Object

Hierarchy          Properties          Methods           Example          See Also

Represents the base class for the TcxPropertiesStore object.

Unit

cxPropertiesStore

TcxCustomPropertiesStore = class(TComponent)

Description

The TcxCustomPropertiesStore class is the base class for the TcxPropertiesStore object.  It defines the basic functionality for the TcxPropertiesStore component.

The TcxCustomPropertiesStore class defines properties and methods required for saving and restoring properties of selected components to a specific storage (registry, INI file or stream).  It is possible to store/restore published properties of all components placed on the same form as a TcxPropertiesStore component.

If the property, selected for saving/restoring, represents a TPersistent descendant, all its sub-properties can be stored/restored.  For instance, if you specify the control’s Font property to store, all its published sub-properties (Charset, Color, Height, Name, Pitch, Size and Style) will be saved.  You can insert the "Font.Style" string into the TcxPropertiesStoreComponent.Properties list instead of "Font".  This will save only the Style property of the TFont object associated with the Font property.

The cxPropertiesStore component enables you to save/restore properties of TCollection elements.  For instance, this can be used to save summary items (TcxDataSummary.FooterSummaryItems, TcxDataSummary.DefaultGroupSummaryItems, TcxDataSummary.SummaryGroups), bands in a grid control (TcxGridBandedTableView.Bands), etc.  At design time, the cxPropertiesStore only allows you to select entire collections for storing/restoring.  Using code though, allows saving individual items from collections, as well as the properties of a particular collection item.  When restoring elements from a storage, the collection must contain the same number of items as in the storage.

The PropertiesStore object does not allow you to store/restore sub-properties of the properties derived from the TComponent class.  When a property references a TComponent descendant, only the object’s Name is saved.

To select components to store/restore using the TcxPropertiesStore object, you should add items to its Components collection.  Every element in the collection represents a TcxPropertiesStoreComponent instance referring to the component and its properties.  The component and its properties are specified by the TcxPropertiesStoreComponent.Component and TcxPropertiesStoreComponent.Properties attributes respectively.  If you do not specify any properties via the Properties list, no properties will be stored to/restored from the storage.

The TcxPropertiesStore component automatically restores properties of selected components when the form owning the component is created.  On destroying the form, the TcxPropertiesStore automatically overwrites (or creates) the storage and saves the properties of selected components.  This default behavior may be disabled by setting the Active property to False.  In this case, the selected components’ settings can still be saved/restored by calling the StoreTo/RestoreFrom methods manually.

The storage used for saving component settings is specified by two properties: StorageType and StorageName.

The StoreTo/RestoreFrom methods allow you to save/restore properties for all selected components.  To operate on individual components, you need to call the StoreTo.../RestoreFrom... methods (for instance, StoreToRegistry or RestoreFromStream) of the corresponding TcxPropertiesStoreComponent instances within the Components collection.


TcxCustomPropertiesStore Hierarchy
Hierarchy

TComponent

     |


Properties for TcxCustomPropertiesStore
TcxCustomPropertiesStore Properties

TcxCustomPropertiesStore          Legend

In TcxCustomPropertiesStore

Active

Components

StorageName

StorageStream

StorageType


Methods for TcxCustomPropertiesStore
TcxCustomPropertiesStore Methods

TcxCustomPropertiesStore          Legend

In TcxCustomPropertiesStore

RestoreFrom

StoreTo


TcxCustomPropertiesStore.Active

TcxCustomPropertiesStore          See Also

Determines whether the default save/restore functionality is enabled or disabled.

property Active: Boolean;

Description

Use this property to determine whether the component’s default functionality is enabled or disabled.  If Active is set to False, then saving selected properties on closing the form and restoring upon its creation, are disabled.  However, saving/restoring can be implemented by calling the StoreTo/RestoreFrom methods at any time.

The default value of the Active property is True.


TcxCustomPropertiesStore.Components

TcxCustomPropertiesStore          See Also

Represents a collection of objects whose properties are stored to/restored from a storage.

property Components: TcxPropertiesStoreComponents;

Description

The TcxCustomPropertiesStore object is used to save  and restore component settings using the storage specified by the StorageType and StorageName properties.

Each component to be saved/restored has a corresponding item in the Components collection.  Each element in this collection represents a TcxPropertiesStoreComponent object.

The TcxPropertiesStoreComponent.Component property specifies a TComponent descendant whose properties must be stored/restored.  To specify the component settings to store/restore, see the TcxPropertiesStoreComponent.Properties member.


TcxCustomPropertiesStore.StorageName

TcxCustomPropertiesStore          See Also

Identifies the storage used to save/restore selected component settings.

property StorageName: string;

Description

The TcxCustomPropertiesStore object is able to save component-specific information to three storage types: INI file, registry key and stream.  All components available for saving/restoring can be accessed by the Components collection.  Properties to save/restore are listed by the Properties property of each item within this collection.

The StorageName property value interpretation varies depending on the storage type specified by the StorageType property.


TcxCustomPropertiesStore.StorageStream

TcxCustomPropertiesStore          See Also

Specifies the stream used for storing/restoring components' properties when StorageType is set to stStream.

property StorageStream: TStream;

Description

Use the StorageStream property to specify a stream (a descendant of the TStream class) used for storing/restoring components' properties.

This property value is in effect only if the StorageType property value is stStream.

If a TStream descendant instance is chosen as the storage, the StorageName property is not in effect.


TcxCustomPropertiesStore.StorageType

TcxCustomPropertiesStore          See Also

Specifies the type of storage used for saving/restoring components' properties.

type

  TcxStorageType = (stIniFile, stRegistry, stStream);

property StorageType: TcxStorageType;

Description

Use the StorageType property to specify the type of storage for saving/restoring components' properties.  All components, selected for saving/restoring, can be accessed by the Components collection.  Properties to save/restore are listed by the Properties property for each item within this collection.

This property value affects the StorageName property value interpretation.

StorageType	StorageName Interpretation
stIniFile	The path and the name of the INI file.
stRegistry	The registry key name. This name is relative to HKEY_CURRENT_USER.
stStream	The StorageName property is not in effect. Use the StorageStream property instead to specify a stream for storing/restoring components' properties.

The default value of the StorageType property is stIniFile.


TcxCustomPropertiesStore.RestoreFrom

TcxCustomPropertiesStore          See Also

Restores component settings from the currently specified storage.

procedure RestoreFrom;

Description

Use the RestoreFrom method to restore components' settings from the storage specified by the StorageName and StorageType properties.

After calling this method the cxPropertiesStore component restores settings of all components referenced within the Components collection.  If the storage does not exist or if there are no components selected, this method does nothing.

To save components' settings, use the StoreTo method.


TcxCustomPropertiesStore.StoreTo

TcxCustomPropertiesStore          See Also

Saves component settings to the current storage.

procedure StoreTo(const AReCreate: Boolean = True);

Description

Use the StoreTo method to save components' settings to the storage specified by the StorageName and StorageType properties.

After calling this method, the cxPropertiesStore component saves settings of all components referenced within the Components collection.  If there are no components selected, this method does nothing.

To restore components' settings, use the RestoreFrom method.

The AReCreate parameter determines whether the selected storage is deleted and then re-created by the StoreTo method.  If this parameter value is False, information is appended to the end of the existing storage.


TcxPropertiesStore
 TcxPropertiesStore Object

Hierarchy          Properties          Methods          Example          See Also

Represents a TcxPropertiesStore component.

Unit

cxPropertiesStore

TcxPropertiesStore = class(TcxCustomPropertiesStore)

Description

The TcxPropertiesStore component is used to save and restore component-specific information to a storage of a specific type.  It allows you to store/restore required published properties of selected components on the form containing the PropertiesStore component.

The PropertiesStore component provides a design-time editor to choose components and their properties to save/restore using the storage.

The TcxPropertiesStore supports the following storage types: registry (VCL only), INI file and stream.

To enable the TcxPropertiesStore object:

1.	Place a TcxPropertiesStore component on a form

2.	Specify the components and their properties to be stored/restored using the storage

3.	Specify the storage name and type via the StorageName and StorageType properties

When the form is opened, TcxPropertiesStore attempts to read settings of the selected components from the storage.  If the storage exists, its property settings replace the settings of existing components.  When the form is destroyed, the storage is recreated and properties of the selected components are saved.  Disable this automatic functionality by setting its Active property to False.

Manual operation is also available by calling the StoreTo and RestoreFrom methods to store/restore selected component settings to the current storage at any time.

The cxPropertiesStore allows the saving and restoring of properties at design time.  The storage for design time saving/restoring is identified by the StorageName and StorageType properties.

Refer to the TcxCustomPropertiesStore description for information on property types which can be stored/restored.


TcxPropertiesStore Hierarchy
Hierarchy

TComponent

     |

TcxCustomPropertiesStore

     |


Properties for TcxPropertiesStore
TcxPropertiesStore Properties

TcxPropertiesStore          Legend

Derived from TcxCustomPropertiesStore

Active

Components

StorageName

StorageStream

StorageType


Methods for TcxPropertiesStore
TcxPropertiesStore Methods

TcxPropertiesStore          Legend

Derived from TcxCustomPropertiesStore

RestoreFrom

StoreTo


TcxPropertiesStoreComponent
TcxPropertiesStoreComponent Object

Hierarchy          Properties          Methods          See Also

Represents a reference to a component with properties stored by a TcxPropertiesStore object.

Unit

cxPropertiesStore

TcxPropertiesStoreComponent = class(TCollectionItem, IcxStoredObject, IcxStoredParent)

Description

The TcxPropertiesStore component is used to save/restore published properties of components present on a form.

Components with properties being saved/restored by a TcxPropertiesStore instance are accessible via its Components collection.  Each item in this collection is a TcxPropeprtiesStoreComponent object.

The Component property identifies the component whose properties are being saved/restored.  To select the component’s properties to store/restore, see the Properties object.

If the selected property represents a TPersistent descendant (like the Font property of a component), you can specify its sub-properties to store.  A sub-property is delimited from the main property by a dot.  For instance, you can insert the "Font.Style" string into the Properties list instead of "Font".  This will save only the Style property of the TFont object associated with the Font property.  If you specify the control’s Font property to store, all its published sub-properties (Charset, Color, Height, Name, Pitch, Size and Style) will be automatically saved.

The TcxPropertiesStoreComponent class’s methods allow you to save/restore individual components from the Components collection to any type of supported storage (registry, INI file, stream).


TcxPropertiesStoreComponent Hierarchy
Hierarchy

TCollectionItem

     |


Properties for TcxPropertiesStoreComponent
TcxPropertiesStoreComponent Properties

TcxPropertiesStoreComponent          Legend

In TcxPropertiesStoreComponent

Component

Properties


Methods for TcxPropertiesStoreComponent
TcxPropertiesStoreComponent Methods

TcxPropertiesStoreComponent          Legend

In TcxPropertiesStoreComponent

RestoreFromIniFile

RestoreFromRegistry

RestoreFromStream

StoreToIniFile

StoreToRegistry

StoreToStream


TcxPropertiesStoreComponent.Component

TcxPropertiesStoreComponent          See Also

Specifies a component whose properties are stored/restored by the PropertiesStore object.

property Component: TComponent;

Description

Each component with properties being saved/restored by a TcxPropertiesStore object, has a corresponding item within its Components collection.  Items in this collection represent TcxPropertiesStoreComponent objects.

The Component property of the TcxPropertiesStoreComponent object identifies the component whose settings are stored/restored.  To select the component’s settings to save/restore, see the Properties attribute.


TcxPropertiesStoreComponent.Properties

TcxPropertiesStoreComponent          See Also

Specifies the properties of a component to store/restore using a storage.

property Properties: TStrings;

Description

Use the Properties property to specify which published properties of a component will be saved/restored.  To specify the component itself, see the Component property.

Note that only existing properties can be saved.  If the component to store does not have a property with a name in the Properties list, this property is ignored.

If a property relates to a TPersistent descendant, you can store its specific attributes.  To specify the attributes to store, you need to add a string consisting of the property and attribute names delimited by a dot. For instance, if you wish to save only the Height sub-property of the Font property, you need to add the "Font.Height" string to the Properties string list.  If you specify the control’s Font property to store, all its published sub-properties (Charset, Color, Height, Name, Pitch, Size and Style) will be automatically saved.

Note that if your property references a TComponent descendant, only the object’s Name is saved in this case.  See example for details.


TcxPropertiesStoreComponent.RestoreFromIniFile

TcxPropertiesStoreComponent          See Also

Restores the current component’s properties from an INI file.

procedure RestoreFromIniFile(const AStorageName: string);

Description

Use this method to restore the properties of the component specified by the Component property from an INI file.  The properties to restore are specified by the Properties list.

You can call the RestoreFromIniFile method even if the StorageType of the current TcxPropertiesStore instance is not set to stIniFile.

The AStorageName parameter specifies the path and the name of the INI file used as a storage.  If such a file does not exist, the RestoreFromIniFile method does nothing.


TcxPropertiesStoreComponent.RestoreFromRegistry

TcxPropertiesStoreComponent          See Also

Restores the current component’s properties from the registry.

procedure RestoreFromRegistry(const AStorageName: string);

Description

Use this method to restore the properties of the component specified by the Component property from the registry.  The properties to restore are specified by the Properties list.

You can call the RestoreFromRegistry method even if the StorageType of the current TcxPropertiesStore instance is not set to stRegistry.

The AStorageName parameter specifies the suffix to the HKEY_CURRENT_USER registry key.  So, the whole registry key, used as a storage, looks like HKEY_CURRENT_USER\ + the AStorageName parameter value.


TcxPropertiesStoreComponent.RestoreFromStream

TcxPropertiesStoreComponent          See Also

Restores the current component’s properties from a stream.

procedure RestoreFromStream(const AStream: TStream);

Description

Use this method to restore the properties of the component specified by the Component property from a stream.  The properties to restore are specified by the Properties list.

You can call the RestoreFromStream method even if the StorageType of the current TcxPropertiesStore instance is not set to stStream.

The AStream parameter specifies the stream used as a storage.


TcxPropertiesStoreComponent.StoreToIniFile

TcxPropertiesStoreComponent          See Also

Saves the current component’s properties to an INI file.

procedure StoreToIniFile(const AStorageName: string; const AReCreate: Boolean);

Description

Use this method to save the properties of the component specified by the Component property to an INI file.  The properties to store are specified by the Properties list.

You can call the StoreToIniFile method even if the StorageType of the current TcxPropertiesStore instance is not set to stIniFile.

The AStorageName parameter specifies the name and the path to the INI file used as the storage.  The AReCreate parameter determines whether the INI file is deleted and created again with each call to this method.  If this parameter value is False, information is appended to the end of the existing file.


TcxPropertiesStoreComponent.StoreToRegistry

TcxPropertiesStoreComponent          See Also

Saves the current component’s properties to the registry.

procedure StoreToRegistry(const AStorageName: string; const AReCreate: Boolean);

Description

Use this method to save the properties of the component specified by the Component property to the registry.  The properties to store are specified by the Properties list.

You can call the StoreToRegistry method even if the StorageType of the current TcxPropertiesStore instance is not set to stRegistry.

The AStorageName parameter specifies the suffix to the HKEY_CURRENT_USER registry key.  So, the whole registry key, used as a storage, looks like HKEY_CURRENT_USER\ + the AStorageName parameter value.  The AReCreate parameter determines whether the registry key is deleted and created again with each call to this method.  If this parameter value is False, information is appended to the existing key.


TcxPropertiesStoreComponent.StoreToStream

TcxPropertiesStoreComponent          See Also

Saves the current component’s properties to a stream.

procedure StoreToStream(const AStream: TStream; const AReCreate: Boolean);

Description

Use this method to save the properties of the component specified by the Component property to a stream (a TStream descendant).  The properties to store are specified by the Properties list.

You can call the StoreToStream method even if the StorageType of the current TcxPropertiesStore instance is not set to stStream.

The AStream parameter identifies the TStream descendant used as the storage.  The AReCreate parameter determines whether the storage stream is destroyed and created again with each call to this method.  If this parameter value is False, information is appended to the end of the existing storage.


TcxPropertiesStoreComponents
TcxPropertiesStoreComponents Object

Hierarchy          Properties          See Also

Represents a collection of references to the components whose properties are saved/restored by the TcxPropertiesStore component.

Unit

cxPropertiesStore

TcxPropertiesStoreComponents = class(TOwnedCollection)

Description

Each component with properties saved/restored by a TcxPropertiesStore component, is represented by a TcxPropertiesStoreComponent object.

References to all stored components are contained within the Components collection.

To add components in order to store/restore this collection at design time, do one of the following:

1.	Use the PropertiesStore Editor.  It allows the selecting of components and their properties by right-clicking elements within the list.  In this case, the properties of the added item (Component and Properties) are initialized automatically.

2.	In the Object Inspector, use the TcxCustomEditPropwertiesStore.Components property editor to manually initialize properties of the item being added.


TcxPropertiesStoreComponents Hierarchy
Hierarchy

TOwnedCollection

     |


Properties for TcxPropertiesStoreComponents
TcxPropertiesStoreComponents Properties

TcxPropertiesStoreComponents          Legend

In TcxPropertiesStoreComponents

ComponentItems


TcxPropertiesStoreComponents.ComponentItems

TcxPropertiesStoreComponents          See Also

Provides indexed access to the components to store/restore.

property ComponentItems[Index: Integer]: TcxPropertiesStoreComponent;

Description

Use this property to access individual components within the Components collection of the PropertiesStore object.  The Index parameter represents an item's position within the collection.


Example TcxPropertiesStore.StoreTo

The following example demonstrates how to use the cxPropertiesStore component.  Consider storing the Color property value of the cxStyle object.  This object (cxTabStyle) is assigned to the RootLevelStyles.Tab property of a cxGrid control.

The cxPropertiesStore component does not allow you to save/restore sub-properties of the properties referring to TComponent descendants.  So, saving the Color property of a cxStyle object needs a special approach.  The following code shows the correct method of saving the Color property of the cxTabStyle style:

//Delphi

//...

//setting the level tabs painting style to cxTabStyle

cxGrid1.RootLevelStyles.Tab := cxTabStyle;

with cxPropertiesStore1 do

begin

//adding a reference to the cxGrid1 control into the Components collection

     with TcxPropertiesStoreComponent(Components.Add) do

     begin

          Component := cxGrid1;

          //specifying the

          Properties.Add('RootLevelStyles.Tab');

     end;

//adding a reference to cxTabStyle into the Components collection

     with TcxPropertiesStoreComponent(Components.Add) do

     begin

          Component := cxTabStyle;

          //specifying the Color property for storing/restoring

          Properties.Add('Color');

     end;

//setting the storage type to INI file

     StorageType := stIniFile;

//specifying the name of the INI file

     StorageName := 'c:\store.ini';

//saving information

     StoreTo;

end;

//...

//C++ Builder

//...

//setting the level tabs painting style to cxTabStyle

  cxGrid1->RootLevelStyles->Tab = cxTabStyle;

  TcxPropertiesStoreComponent * APSComponent;

//adding a reference to the cxGrid1 control into the Components collection

  APSComponent = (TcxPropertiesStoreComponent *)cxPropertiesStore1->Components->Add();

  APSComponent->Component = cxGrid1;

//specifying the

  APSComponent->Properties->Add("RootLevelStyles.Tab");

//adding a reference to cxTabStyle into the Components collection

  APSComponent = (TcxPropertiesStoreComponent *)cxPropertiesStore1->Components->Add();

  APSComponent->Component = cxTabStyle;

//specifying the Color property for storing/restoring

  APSComponent->Properties->Add("Color");

//setting the storage type to INI file

  cxPropertiesStore1->StorageType = stIniFile;

//specifying the name of the INI file

  cxPropertiesStore1->StorageName = "c:\\store.ini";

//saving information

  cxPropertiesStore1->StoreTo();

//...

The result of this code execution is shown below:

[cxGrid1: TcxPropertiesStoreComponent]

=

RootLevelStyles.Tab=cxTabStyle

[cxTabStyle: TcxPropertiesStoreComponent]

=

Color=15451300

The resulting file contains all the required information – the RootLevelStyles.Tab style object and the Color property value for that object.


cxGraphics Unit Overview
cxGraphics Unit

Classes

TcxCanvas

Components

TcxImageList

Other Types

TcxBorder

TcxBorders

TcxViewParams


TcxCanvas
TcxCanvas Object

Hierarchy          Properties          Methods

An enhanced device context wrapper compared with the standard VCL canvas.

Unit

cxGraphics

TcxCanvas = class(TObject)

Description

The TCanvas class enables you to use device contexts in a convenient and easy to understand OOP style.  The TcxCanvas class also provides access to the device context API.  But in comparison with TCanvas, it provides additional useful functions such as DrawFocusRect and DrawFrame.  The class is not derived from TCanvas, but it uses a TCanvas class instance to store data. This canvas can be accessed via the TcxCanvas.Canvas property.


TcxCanvas Hierarchy
Hierarchy

TObject

     |


Properties for TcxCanvas
TcxCanvas Properties

TcxCanvas          Legend

In TcxCanvas

Brush

Canvas

CopyMode

Font

Handle

Pen

Pixels


Methods for TcxCanvas
TcxCanvas Methods

TcxCanvas          Legend

In TcxCanvas

CopyRect

Draw

DrawComplexFrame

DrawEdge

DrawFocusRect

DrawImage

DrawText

FillRect

FontHeight

FrameRect

LineTo

MoveTo

Polygon

Polyline

TextExtent

TextHeight

TextWidth


TcxCanvas.Brush

TcxCanvas

Determines the color and pattern for filling graphical shapes and backgrounds.

property Brush: TBrush;

Description

Set the Brush property to specify the color and pattern to use when drawing the background or filling in graphical shapes.  The value of the Brush property is a TBrush object.  Set the properties of the TBrush object to specify the color and pattern or the bitmap to use when filling in spaces on a canvas.

Note: When assigning the Brush property, all source brush settings are copied to the TcxCanvas brush.


TcxCanvas.Canvas

TcxCanvas

Provides access to the standard VCL canvas.

property Canvas: TCanvas;

Description

The TcxCanvas class is a VCL canvas wrapper that extends its facilities with a set of drawing methods.  The TcxCanvas class uses a TCanvas class instance to store data. This canvas can be accessed by the Canvas property.

ReadOnly Property


TcxCanvas.CopyMode

TcxCanvas

Specifies the manner in which a graphical image is copied onto a canvas.

property CopyMode: TCopyMode;

Description

Set CopyMode to affect the manner in which graphical images are drawn on a canvas.  The CopyMode property value represents a type of Raster Operation.

Use raster operations to achieve a variety of effects when rendering an image.  For example, merged images and making parts of a bitmap transparent by combining multiple images with different raster operations.

Although there are 256 possible raster operations, only 15 are worth mentioning here. The following table explains their meanings:

Value	Meaning
cmBlackness	Fills the destination using the color associated with index 0 in the physical palette. (This color is black for the default physical palette.)
cmDstInvert	Inverts the destination bitmap colors and ignores the source.
cmMergeCopy	Merges the colors of the source with the brush color of the destination by using the Boolean AND operator.
cmMergePaint	Combines the inverted source bitmap with the image on the canvas by using the Boolean OR operator.
cmNotSrcCopy	Copies the inverted source bitmap onto a canvas.
cmNotSrcErase	Combines the image on the canvas and the source bitmap by using the Boolean OR operator and inverts the result.
cmPatCopy	Copies the source pattern onto a canvas.
cmPatInvert	Combines the source pattern with the image on the canvas using the Boolean XOR operator.
cmPatPaint	Combines the inverted source bitmap with the source pattern by using the Boolean OR operator.  Combines the result of this operation with the image on a canvas by using the Boolean OR operator.
cmSrcAnd	Combines the image on the canvas and the source bitmap by using the Boolean AND operator.
cmSrcCopy	Copies the source bitmap onto a canvas.
cmSrcErase	Inverts the image on the canvas and combines the result with the source bitmap by using the Boolean AND operator.
cmSrcInvert	Combines the image on the canvas and the source bitmap by using the Boolean XOR operator.
cmSrcPaint	Combines the image on the canvas and the source bitmap by using the Boolean OR operator.
cmWhiteness	Fills the destination using the color associated with index 1 in the physical palette. (This color is white for the default physical palette.)

The following table shows the results of some raster operations:

Value	Source	Destination	Result
cmBlackness*
cmDstInvert
cmMergeCopy
cmMergePaint
cmNotSrcCopy
cmNotSrcErase
cmPatCopy
cmPatInvert
cmPatPaint
cmSrcAnd
cmSrcCopy
cmSrcErase
cmSrcInvert
cmSrcPaint
cmWhiteness*

* - Depends on the system palette settings.

The CopyMode property value is used internally by the CopyRect and Draw methods to achieve various effects while drawing.


TcxCanvas.Font

TcxCanvas

Specifies the font to use when writing text on a canvas.

property Font: TFont;

Description

Set the Font property to specify the font to use for writing text on a canvas.  The Font property value is a TFont object.  Set the properties of the TFont object to specify the font face, color, size, style etc.

Note: When assigning the Font property, all source font settings are copied to the TcxCanvas font.


TcxCanvas.Handle

TcxCanvas

Specifies the handle for a canvas.

property Handle: HDC;

Description

The Handle property specifies the Windows GDI handle to the device context for a canvas.

Read the Handle property to supplement the drawing services provided by the TcxCanvas object with API calls that require a handle to the device context.  Most of the Windows GDI calls require a device context handle.

ReadOnly Property


TcxCanvas.Pen

TcxCanvas

Specifies the pen type the canvas uses for drawing lines and outlining shapes.

property Pen: TPen;

Description

Set the Pen property to specify the pen to use for drawing lines and outlining shapes on a canvas.  The Pen property value is a TPen object.  Set the properties of the TPen object to specify the color, style, width, and mode of the pen.

Note: When assigning the Pen property, all source pen settings are copied to the TcxCanvas pen.


TcxCanvas.Pixels

TcxCanvas

Specifies the color of pixels within the current clipping rectangle of a canvas.

property Pixels[X, Y: Integer]: TColor;

Description

Read the Pixels property to learn the color of the drawing surface at a specific pixel position within the current clipping region.  If the position is outside the clipping rectangle, the Pixels property value is -1.

Write the Pixels property to change the color of individual pixels within the drawing surface.

Note: Getting and setting the Pixels property is a very slow operation.  Use it only when it is unavoidable.


TcxCanvas.CopyRect

TcxCanvas

Copies a portion of an image from one canvas onto another.

procedure CopyRect(const Dest: TRect; ACanvas: TCanvas; const Source: TRect);

Description

Use the CopyRect method to transfer a portion of an image from one canvas to the image of the TCanvas object.  The Dest parameter specifies the rectangle on the canvas where the source image will be copied.  The ACanvas parameter specifies the canvas with the source image.  The Source parameter specifies the rectangle bounding the portion of the source canvas to be copied.  So if you need to copy an image from one TcxCanvas to another, you should implement the following code:

  //the following code copies ARect2 from cxCanvas2 to ARect1 of cxCanvas1

  cxCanvas1.CopyRect(ARect1, cxCanvas2.Canvas, ARect2);

The copy uses the mode specified by the CopyMode property.


TcxCanvas.Draw

TcxCanvas

Renders a graphic object on a canvas.

procedure Draw(X, Y: Integer; Graphic: TGraphic);

Description

Call the Draw method to draw a graphic object (specified by the Graphic parameter) on a canvas.  The position to place the upper-left corner of the object is specified by the X and Y parameters.

Graphics can be bitmaps, icons, or metafiles.  If it is a TBitmap object, the bitmap is rendered using the CopyMode property value.


TcxCanvas.DrawComplexFrame

TcxCanvas

Draws a two-color border around a rectangle.

procedure DrawComplexFrame(const R: TRect; ALeftTopColor, ARightBottomColor: TColor; ABorders: TcxBorders = [bLeft, bTop, bRight, bBottom]; ABorderWidth: Integer = 1);

Description

The DrawComplexFrame method draws a two-color border around a rectangle.  The ALeftTopColor parameter provides the color for the top and left border sides and the ARightBottomColor parameters - for the bottom and right.  Optionally, you can specify the border width.  You can also determine which border sides to draw (the ABorders and ABorderWidth parameters).  This method lets you draw a complex border in a single operation (without having to manipulate pen and brush colors or to perform excessive calculations.)

The following code shows how to draw grid view's Group By box in 3D style using the DrawComplexFrame method (The code is implemented in the TcxGridTableView.OnCustomDrawPartBackground event handler):

procedure TViewTableSimpleDemoMainForm.cxgFilmsDBTableViewCustomDrawPartBackground(

  Sender: TcxGridTableView; ACanvas: TcxCanvas;

  AViewInfo: TcxCustomGridCellViewInfo; var ADone: Boolean);

var

  FOldColor: TColor;

  FBounds: TRect;

begin

  if (AViewInfo is TcxGridGroup ByBoxViewInfo) then

  begin

    FOldColor := ACanvas.Brush.Color;

    ACanvas.Brush.Color := clBtnFace;

    FBounds := AViewInfo.Bounds;

    ACanvas.FillRect(AViewInfo.Bounds);

    ACanvas.DrawComplexFrame(FBounds, clWhite, cl3DDkShadow, cxBordersAll, 1);

    InflateRect(FBounds, -1, -1); //Platform specific. May not work on Linux.

    ACanvas.DrawComplexFrame(FBounds, cl3DLight, clGray, cxBordersAll, 1);

    ACanvas.Brush.Color := FOldColor;

    ADone := True;

  end;

end;

The following images illustrate the above code.

Standard drawing (the above code is NOT implemented):

Custom drawing (the above code is implemented):


TcxCanvas.DrawEdge

TcxCanvas

Draws one or more edges of a rectangle.

procedure DrawEdge(const R: TRect; ASunken, AOuter: Boolean; ABorders: TcxBorders = [bLeft, bTop, bRight, bBottom]);

Description

The DrawEdge method draws one or more edges of the rectangle specified by the R parameter. Set the ASunken parameter to True to draw the edge sunken, otherwise it will be drawn raised.  If the AOuter parameter is True, the edge will be drawn outside the rectangle, otherwise, it is drawn within the rectangle. To specify the edges to draw, you should use the ABorders parameter.

The following code shows how to draw edges above and below the grid view's Group By box caption using the DrawEdge method (The code is implemented in the TcxGridTableView.OnCustomDrawPartBackground event handler):

procedure TViewTableSimpleDemoMainForm.cxgFilmsDBTableViewCustomDrawPartBackground(

  Sender: TcxGridTableView; ACanvas: TcxCanvas;

  AViewInfo: TcxCustomGridCellViewInfo; var ADone: Boolean);

var

  FBounds: TRect;

begin

  FBounds := AViewInfo.Bounds;

  ACanvas.FillRect(FBounds);

  InflateRect(FBounds, 0, -9); //Platform specific. May not work on Linux.

  ACanvas.DrawEdge(FBounds, True, True, [bTop, bBottom]);

  ADone := True;

end;


TcxCanvas.DrawFocusRect

TcxCanvas

Draws a rectangle using the style indicating that it has focus.

procedure DrawFocusRect(const R: TRect);

Description

The DrawFocusRect method draws a rectangle using the style indicating that it has focus.

Since the DrawFocusRect method is an XOR function, calling it for the second time with the same rectangle removes the rectangle from screen.

The image below shows the grid view's Group By box caption surrounded by the focus rectangle:


TcxCanvas.DrawImage

TcxCanvas

Renders a graphic object from a VCL image list on a canvas.

procedure DrawImage(Images: TImageList; X, Y, Index: Integer; Enabled: Boolean = True);

Description

Call the Draw method to draw a graphic object on a canvas using an image from the Images image list. The Index parameter provides the reference to the image used. The X and Y parameters provide the location of the upper-left corner of the image within the canvas.

If you want your image to be drawn as disabled, set the Enabled parameter to False.

The image below shows the grid view's the enabled image drawn in the Group By box:

and that shows the disabled one:


TcxCanvas.DrawText

TcxCanvas

Draws formatted text within a specific rectangle.

procedure DrawText(const Text: string; R: TRect; Flags: Integer; Enabled: Boolean = True);

Description

The DrawText method draws formatted text (specified by the Text parameter) within a rectangle (the R parameter).  It formats the text based on the flag values provided (expanding tabs, justifying characters, breaking lines, etc.).

The DrawText method uses the selected font, text color, and background color to draw text within a canvas.  Unless the cxDontClip flag is used, the DrawText method clips the text so that it does not appear outside the rectangle provided.  The text will be presented via multiple lines when needed unless the cxSingleLine flag is specified.

If the selected font is too large for the rectangle, the DrawText method does not attempt to replace it with a smaller one.

If you want your text to be drawn as disabled, set the Enabled parameter to False.

Value	Meaning
cxAlignBottom	Justifies the text to the bottom of the rectangle.  This value must be combined with cxSingleLine. cxAlignBottom corresponds to the DT_BOTTOM flag value of the DrawText API function.
cxAlignCenter	Centers the text within the rectangle.  This value represents a combination of the cxAlignHCenter and cxAlignVCenter values.
cxAlignHCenter	Centers the text horizontally within the rectangle. This value corresponds to the DT_CENTER flag value of the DrawText API function.
cxAlignLeft	Aligns the text to the left. This value corresponds to the DT_LEFT flag value of the DrawText API function.
cxAlignRight	Aligns the text to the right. This value corresponds to the DT_RIGHT flag value of the DrawText API function.
cxAlignTop	Top-justifies the text (single line only). This value corresponds to the DT_TOP flag value of the DrawText API function.
cxAlignVCenter	Centers the text vertically (single line only). This value corresponds to the DT_VCENTER flag value of the DrawText API function.
cxDontBreakChars	If not set, a partially visible last text line is not displayed.  Otherwise, the text is displayed as is. This value applies only in combination with the cxWordBreak flag value. The case when the cxDontBreakChars flag value is not set corresponds to calling the DrawText API function with the DT_EDITCONTROL flag value.
cxDontClip	Draws without clipping.  The DrawText method is somewhat faster when cxDontClip is used. This value corresponds to the DT_NOCLIP flag value of the DrawText API function.
cxDontPrint	Calculates the rectangle required to display the entire text.  The text won’t be drawn. This value corresponds to the DT_CALCRECT flag value of the DrawText API function.
cxExpandTabs	Expands tab characters.  The default number of characters per tab is eight. This value corresponds to the DT_EXPANDTABS flag value of the DrawText API function.
cxShowEndEllipsis	Characters at the end of the text are replaced with ellipses, if necessary, so that it fits into the specified rectangle. This value corresponds to the DT_END_ELLIPSIS flag value of the DrawText API function.
cxShowPrefix	Switches on the processing of prefix characters.  By specifying cxShowPrefix, DrawText method interprets the mnemonic-prefix character & as a directive to underscore the character that follows, and the mnemonic-prefix characters && as a directive to print a single &.  Normally, this processing is deactivated. Setting cxShowPrefix turns off the DT_NOPREFIX flag value of the DrawText API function.
cxShowPathEllipsis	Characters in the middle of the text are replaced with an ellipsis, if necessary, so that it fits into the specified rectangle.  If the string contains backslash (\) characters, the DrawText preserves as much as possible of the text after the last backslash. cxShowPathEllipsis corresponds to the DT_PATH_ELLIPSIS flag value of the DrawText API function.
cxSingleLine	Displays the text in a single line only.  Carriage returns and linefeeds do not break the line. This value corresponds to the DT_SINGLELINE flag value of the DrawText API function.
cxWordBreak	Breaks words.  Lines are automatically broken between words if a word extends past the edge of the rectangle specified by the R parameter.  A carriage return-linefeed sequence also breaks the line.  Use the cxDontBreakChars flag value to specify whether a partially visible last line of the text is displayed. cxWordBreak corresponds to the DT_WORDBREAK flag value of the DrawText API function.

The following code shows how to custom paint the grid view's Group By box caption using the DrawText method (The code is implemented in the TcxGridTableView.OnCustomDrawPartBackground event handler).  The caption is multi-line with the end ellipsis:

procedure TViewTableSimpleDemoMainForm.cxgFilmsDBTableViewCustomDrawPartBackground(

  Sender: TcxGridTableView; ACanvas: TcxCanvas;

  AViewInfo: TcxCustomGridCellViewInfo; var ADone: Boolean);

var

  FBounds: TRect;

begin

  FBounds := AViewInfo.Bounds;

  ACanvas.FillRect(FBounds);

  InflateRect(FBounds, -150, -4); //Platform specific. May not work on Linux.

  OffsetRect(FBounds, -140, 0); //Platform specific. May not work on Linux.

  ACanvas.DrawText('This is the Group By Box. ' +

                   'It is used to group records by field values. ' +

                   'Drag a column header here to group by that field.',

                   FBounds, cxWordBreak or cxShowEndEllipsis);

  ADone := True;

end;

The result is shown on the image below:


TcxCanvas.FillRect

TcxCanvas

Fills a rectangle on a canvas using the current brush.

procedure FillRect(const R: TRect);

procedure FillRect(const R: TRect; ABitmap: TBitmap);

Description

Use the FillRect method to fill the specified rectangular region.  The region is filled including the top and left sides of the rectangle, but excluding the bottom and right edges.  The rectangle to be filled is specified by the R parameter.  If the ABitmap parameter is not omitted, the rectangle is filled with the image specified by it.  Otherwise, it is filled using the current brush settings.


TcxCanvas.FontHeight

TcxCanvas

Returns the height of a string rendered in the current font in pixels.

function FontHeight(AFont: TFont): Integer;

Description

Use the FontHeight method to determine the height of a string written with the current font (the AFont parameter).  Other image elements such as lines, boxes, or additional text lines can then be positioned to accommodate the text height.


TcxCanvas.FrameRect

TcxCanvas

Draws a border around a rectangle.

procedure FrameRect(const R: TRect; Color: TColor = clDefault; ALineWidth: Integer = 1; ABorders: TcxBorders = cxBordersAll);

Description

The FrameRect method draws a color border around a rectangle.  The Color parameter specifies the border color.  Optionally you can specify the border sides to draw and the border width (the ABorders and ALineWidth parameters).


TcxCanvas.LineTo

TcxCanvas

Draws a line from the current pen position to the point specified by X and Y and updates the pen position.

procedure LineTo(X, Y: Integer);

Description

Use the LineTo method to draw a line from the current pen position up to, but not including the point specified by the X and Y coordinates.  The LineTo method changes the pen position’s value to (X,Y).  To set the pen position's value without drawing a line, use the MoveTo method.

Note: If the current pen does not have a style of psSolid, the line is drawn with the background specified by the current brush.


TcxCanvas.MoveTo

TcxCanvas

Changes the current drawing position to the point specified by the X and Y coordinates.

procedure MoveTo(X, Y: Integer);

Description

Use the MoveTo method to set the pen position before calling the LineTo method.


TcxCanvas.Polygon

TcxCanvas

Draws a series of lines on a canvas to create a filled shape.

procedure Polygon(const Points: array of TPoint);

Description

Use the Polygon method to draw a closed, many-sided shape on a canvas, using the current pen. Having completed the shape, the Polygon method fills it with the help of the current brush.

The Points parameter is an array of points that specify the vertices of a polygon.

The last point is always connected to the first point automatically, so you do not need to supply the first one twice.

To draw a polygon without filling it, use the Polyline method.


TcxCanvas.Polyline

TcxCanvas

Draws a series of connected lines with the current pen.

procedure Polyline(const Points: array of TPoint);

Description

Use the Polyline method to connect a set of points on a canvas. If you specify only two points, the Polyline method draws a single line.

The Points parameter is an array of points to be connected.

To draw a polygon and fill it with the current brush, use the Polygon method instead.


TcxCanvas.TextExtent

TcxCanvas

Returns the width and height of a string in pixels in pixels, rendered in the current font.

Overloaded Variants

function TextExtent(const Text: string): TSize;

procedure TextExtent(const Text: string; var R: TRect; Flags: Integer);

Description

Use the TextExtent method to determine the space a string will occupy within an image.

Overload 1: Other image elements such as lines, boxes, or additional text lines can be positioned to accommodate the size of text.  The TextExtent method returns the width and height of the rectangle that bounds the supplied text within a canvas.

Overload 2: The Flags parameter specifies the string format.  The flags are the same as in the DrawText method.  The R parameter returns the text’s bounding rectangle.  Other image elements such as lines, boxes, or additional text lines can be positioned to accommodate the size of the text.


TcxCanvas.TextHeight

TcxCanvas

Returns the height of a string in pixels, rendered in the current font.

function TextHeight(const Text: string): Integer;

Description

Use the TextHeight method to determine the height a string will occupy within an image.  Other image elements such as lines, boxes, or additional text lines can be positioned to accommodate the text’s height.  To determine the text’s width, use the TextWidth property.  Also, see the TextExtent method for enhanced text measuring facilities.


TcxCanvas.TextWidth

TcxCanvas

Returns the width of a string rendered in the current font (in pixels).

function TextWidth(const Text: string): Integer;

Description

Use the TextWidth method to determine the length a string will occupy within an image.  Other graphical image elements such as lines or additional strings can be positioned to accommodate the text’s width. To determine the text’s height, use the TextHeight property.  Also, see the TextExtent method for enhanced text measuring facilities.


TcxImageList
 TcxImageList Object

Hierarchy          Properties          Methods          Events

An enhanced image list control.

Unit

cxGraphics

TcxImageList = class(TDragImageList)

Description

Unlike the standard TImageList, TcxImageList allows you to store 32-bit images (including PNG images) and paint them using alpha blending.  In addition to the settings inherited from the base TDragImageList class, the TcxImageList class introduces members that allow you to:

•	Specify whether the alpha channel information is used to draw stored images (AlphaBlending).

•	Improve performance by postponing sending notifications of image list changes (BeginUpdate and EndUpdate).

•	Paint stored images using various image adjustment options (Draw).

•	Copy stored images to another image list (CopyImages).

•	Retrieve image and transparency mask bitmaps of stored images (GetImage, GetImageInfo, and GetMask).

At design time, the TcxImageList allows you to easily retrieve the dimensions of images (the Height and Width properties) and load images from any image list (a TCustomImageList descendant) on a form.  To do this, click ‘Assign From’ in the component’s context menu and select the desired list image.  Note that prior to loading images from the selected image list, the TcxImageList clears its contents.

The TcxImageList also provides a design-time editor, which allows you to load images into the image list, manage stored images within the list, and export them into files.  Refer to the Using the Image List Editor topic, to learn more about this editor.

Note:	To retrieve bitmaps of 32-bit images stored in the TcxImageList, call the GetImage or GetImageInfo method, instead of the GetBitmap method.

Important Note:	Image lists depend on Comctl32.dll.  Make sure you have the latest version of this file installed, to avoid problems displaying images.


TcxImageList Hierarchy
Hierarchy

TDragImageList

     |

TcxImageList


Properties for TcxImageList
TcxImageList Properties

TcxImageList          Legend

In TcxImageList

AlphaBlending

CompressData

Derived from TDragImageList

DragCursor

Dragging

Derived from TCustomImageList

AllocBy

BkColor

BlendColor

Count

DrawingStyle

Handle

Height

ImageType

Masked

ShareImages

Width


Methods for TcxImageList
TcxImageList Methods

TcxImageList          Legend

In TcxImageList

BeginUpdate

CopyImages

EndUpdate

Draw

GetImage

GetImageInfo

GetMask

Derived from TDragImageList

BeginDrag

DragLock

DragMove

DragUnlock

EndDrag

GetHotSpot

HideDragImage

Initialize

SetDragImage

ShowDragImage

Derived from TCustomImageList

Add

AddIcon

AddImages

AddMasked

Assign

Clear

Create

CreateSize

Delete

Destroy

Draw

DrawOverlay

FileLoad

GetBitmap

GetIcon

GetImageBitmap

GetInstRes

GetMaskBitmap

GetResource

HandleAllocated

Insert

InsertIcon

InsertMasked

Move

Overlay

RegisterChanges

Replace

ReplaceIcon

ReplaceMasked

ResInstLoad

ResourceLoad

UnRegisterChanges


Events for TcxImageList
TcxImageList Events

TcxImageList          Legend

Derived from TCustomImageList

OnChange


TcxImageList.AlphaBlending

TcxImageList

Determines whether alpha channel information is used to draw images.

property AlphaBlending: Boolean;

Description

By default this property is set to True, which indicates that images are drawn using alpha channel information.  Otherwise, this information is ignored as with the standard TImageList.Draw method.

Call the Draw method to paint images on a specific canvas.

Note:	To improve performance in Windows XP and Windows Vista, put a TXPManifest component onto a form, and set the AlphaBlending property to False.


TcxImageList.CompressData

TcxImageList

Specifies whether stored images are to be compressed.

property CompressData: Boolean;

Description

Set the CompressData property to True, to reduce the size of the stored images.

The default value of the CompressData property is False.


TcxImageList.BeginUpdate

TcxImageList

Postpones sending notifications about changes to the image list until the matching EndUpdate method is called.

procedure BeginUpdate;

Description

To improve performance and prevent all listeners from refreshing their contents during bulk updates, enclose the code performing the updates within BeginUpdate/EndUpdate blocks.

Note:	The OnChange event won’t fire unless all EndUpdate methods are executed.


TcxImageList.CopyImages

TcxImageList

Copies a set of images from the AImageList to the current image list.

procedure CopyImages(AImageList: TCustomImageList; AStartIndex: Integer = 0; AEndIndex: Integer = -1);

Description

A range of images is determined by the AStartIndex and AEndIndex parameters, which correspond to the indexes of the first and last images in the range.  When the AEndIndex parameter is set to a negative value or exceeds the index of the last image, the last image is considered to be the last element in the range.


TcxImageList.Draw

TcxImageList

Paints the image specified by the AIndex parameter on ACanvas.

Overloaded Variants

type

  TDrawingStyle = (dsFocus, dsSelected, dsNormal, dsTransparent);

  TImageType = (itImage, itMask);

procedure Draw(ACanvas: TCanvas; X, Y, AIndex: Integer; ADrawingStyle: TDrawingStyle; AImageType: TImageType; AEnabled: Boolean = True); overload;

procedure Draw(ACanvas: TCanvas; const ARect: TRect; AIndex: Integer; AStretch: Boolean = True; ASmoothResize: Boolean = False; AEnabled: Boolean = True); overload;

Description

The first overloaded variant allows you to draw the image or its associated transparency mask (as specified by the AImageType parameter) using various drawing styles.

The ADrawingStyle parameter specifies the drawing style of the image to be painted.

Pass False as the AEnabled parameter to paint the image grayed out.

The X and Y parameters specify the location where the top-left corner of the image should appear on ACanvas.

The second overloaded variant represents an extended version of the first one, and allows you to paint the image within the ARect rectangle using image adjustment options.

Set the AStretch parameter to True to scale the image to stretch or fit ARect.  Otherwise, the image will be centered within this rectangle.

Set the ASmoothResize parameter to True to smooth the resulting image when it’s scaled to the size of ARect.

As with the first overloaded variant, the AEnabled parameter indicates whether the image is painted grayed out or not.


TcxImageList.EndUpdate

TcxImageList

Enables sending notifications about changes to the image list locked by the matching BeginUpdate method.

procedure EndUpdate(AForceUpdate: Boolean = True);

Description

To improve performance and prevent all listeners to image list changes from refreshing their contents during bulk updates, enclose the code performing the updates within BeginUpdate/EndUpdate blocks.

Note:	The OnChange event won’t fire unless all EndUpdate methods are executed.  To prevent this event from being raised after the last EndUpdate method is executed, pass False as its AForceUpdate parameter.


TcxImageList.GetImage

TcxImageList          See Also

Retrieves the bitmap of an image by its index in the current image list.

procedure GetImage(AIndex: Integer; AImage: TBitmap);

Description

The index of the image to retrieve is passed as the AIndex parameter.  A value of –1 indicates that the bitmap of all images in the image list will be retrieved.

The image bitmap is returned via the AImage parameter.

Note:	To retrieve bitmaps of 32-bit images stored in the TcxImageList, call the GetImage or GetImageInfo method, instead of the GetBitmap method.


TcxImageList.GetImageInfo

TcxImageList          See Also

Retrieves the bitmap and transparency mask bitmap of a specific image or all images in the current image list.

Overloaded Variants

procedure GetImageInfo(AIndex: Integer; AImage, AMask: TBitmap); overload;

class procedure GetImageInfo(AHandle: HIMAGELIST; AIndex: Integer; AImage, AMask: TBitmap); overload;

Description

The index of the image is passed as the AIndex parameter.  A value of –1 indicates that bitmap information about all images in the image list will be retrieved.

An image bitmap and transparency mask bitmap are returned via the AImage and AMask parameters.

The second overloaded variant requires the handle of the image list that is passed as the AHandle parameter.  Use the Handle property to get the handle of the current image list.

Note:	To retrieve bitmaps of 32-bit images stored in the TcxImageList, call the GetImage or GetImageInfo method, instead of the GetBitmap method.


TcxImageList.GetMask

TcxImageList          See Also

Retrieves the transparency mask bitmap of a specific image.

procedure GetMask(AIndex: Integer; AMask: TBitmap);

Description

The index of the image is passed as the AIndex parameter.  A value of –1 indicates that the transparency mask bitmap of all images in the image list will be retrieved.

The transparency mask bitmap is returned via the AMask parameter.


GDI

Graphics Device Interface (GDI) is a subsystem of the Microsoft® Windows® family of operating systems (since Microsoft® Windows® 95) and it is responsible for displaying information on screens and printers.  GDI is an API that is exposed through a set of functions exported from the DLL (GDI32.DLL).

A graphics device interface, such as GDI, allows application programmers to display information on a screen or printer without having to be concerned about the details of particular display devices.  An application programmer makes calls to the methods provided by GDI, which in turn make appropriate calls to specific device drivers.  GDI insulates applications from graphics hardware, thus allowing developers to create device-independent applications.

The Microsoft® Windows® XP operating system provides a graphics subsystem which extends the drawing facilities far beyond the common GDI functions. It is called GDI+.  As its name suggests, GDI+ is a successor to GDI.


API

Application Programming Interface (API) is an interface between an operating system and an application.  It enables applications to communicate with the operating system and its services. For example, an API may make it possible for programs to create windows, display message boxes and use subsystems such as GDI.


Device Context

One of the chief features of the Microsoft® Win32® application programming interface (API) is device independence.  Win32-based applications can draw and print output on a variety of devices.  The software supporting this device independence is contained in two dynamic-link libraries. The first, GDI32.DLL, is referred to as the graphics device interface (GDI); the second is referred to as a device driver. The name of the second depends on the device where an application draws output. For example, if an application draws output in the client area of its window on a VGA display, this library is VGA.DLL; if it prints output on an Epson® FX-80 printer, this library is EPSON9.DLL.

An application must inform GDI of loading a particular device driver and, once the driver is loaded, to prepare a device for drawing operations (such as selecting the line color and width, the brush pattern and color, the font typeface and clipping region, etc.)  This can be accomplished by creating and maintaining a device context.  The device context is a structure that defines a set of graphic objects and their associated attributes, and the graphic modes affecting output.  Graphic objects include:

•	a pen for line drawing

•	a brush for painting and filling

•	a bitmap for copying or scrolling screen sections

•	a palette for defining a set of available colors

•	a region for clipping and other operations

•	a path for painting and drawing operations

Unlike most of the Win32 structures, applications do not have direct access to the device context; instead, they operate indirectly by calling various functions.


TcxBorder type

Specifies the cell border.

Unit

cxGraphics

type

  TcxBorder = (bLeft, bTop, bRight, bBottom);

Description

Possible TcxBorder values include:

Kind	Description
bLeft	Specifies the left border.
bTop	Specifies the top border.
bRight	Specifies the right border.
bBottom	Specifies the bottom border.


TcxBorders type

Specifies a set of cell borders.

Unit

cxGraphics

type

  TcxBorder = (bLeft, bTop, bRight, bBottom);

  TcxBorders = set of TcxBorder;

Description

The TcxBorders is used to specify a set of cell borders.  This type can contain any combination of TcxBorder values.


TcxViewParams
TcxViewParams type

Specifies attributes controlling the object’s appearance.

Unit

cxGraphics

type

  TcxViewParams = record

    Bitmap: TBitmap;

    Color: TColor;

    Font: TFont;

    TextColor: TColor;

end;

Description

The Bitmap field denotes the object’s background bitmap;

The Color field denotes the object’s background color;

The Font field denotes the font of the output text in the object;

The TextColor field denotes the output text color in the object and should be used instead of the TFont.Color property.


Known Issues and Important Changes List

All entries in the following list are grouped by Builds, in reverse order.

Build 37

1. The TcxStorageType type has been moved from the cxPropertiesStore unit to the cxStorage unit.

2. By default, the ExpressNavBar and ExpressDocking Library create device-dependent bitmaps.  Due to hardware acceleration, these bitmaps are painted faster than device-independent bitmaps.  So, to improve performance, device-dependent bitmaps are created.  However, displaying large device-dependent bitmaps may lead to EOutOfResources exceptions.  To help overcome these problems when using large bitmaps in the aforementioned products, we introduced a cxDoubleBufferedBitmapPixelFormat global variable in the cxGraphics unit.  By default, this variable is set to pfDevice indicating that device-dependent bitmaps are created.  To create device-independent bitmaps, set this variable to pf32bit before creating problematic forms.

Build 31

1. TcxImageList save format to .dfm files has been changed.  Loading forms that contain TcxImageList components from Build 31 or later, fails when using older Builds.  As a result, image lists will be empty.  To properly load these forms, do the following:

•	Install Build 31.

•	Add {$DEFINE cxImageListOldSaveFormat} to the cxGraphics unit as shown below:

//Delphi

// ...

{$DEFINE cxImageListOldSaveFormat}

unit cxGraphics;

// ...

•	Run the Express Install in Recompile mode.

•	Save the forms.  Now TcxImageList controls will be saved to .dfm files using old format.

After this, you can install Build 30 or earlier, and load the forms correctly.

2. In the cxGraphics unit, the TcxImageList.Replace function has been re-declared as a procedure.  Now, no resulting value indicating whether image replacement was successful is returned.

Build 30

1. Now, all message identifiers for Developer Express products are based on the WM_DX constant, which is declared as follows:

  WM_DX = WM_APP + 100;

To avoid conflicts with our message identifiers, define your own message identifiers between WM_APP and WM_DX.

2. In the cxClasses unit, the TTag type has been renamed to TcxTag.  This eliminates conflicts with the standard HTTPProd.TTag type.

Build 28

In the cxGraphics unit, the cxBitmapToTrueColorBitmap global procedure has been renamed to cxMakeTrueColorBitmap.  A new parameter to return the resulting bitmap has been added to this procedure.


Using cxPropertiesStore component
Using the cxPropertiesStore component

When writing a complex application with a large number of settings, you may need to restore component properties.  The ExpressQuantumGrid Suite provides the cxPropertiesStore component implementing this functionality.

By default, the cxPropertiesStore component allows restoring settings upon application creation and saving settings upon application shutdown.  Of course, you can perform saving/restoring whenever you like.  This topic covers all aspects of the cxPropertiesStore functionality.

Let’s consider the use of cxPropertiesStore.  This topic contains two examples of using cxPropertiesStore – at design-time and via code.  The cxPropertiesStore will be used to save/restore cxGrid properties.

Perform the following steps to follow the examples of this topic.  Create an empty application.  Place a cxGrid component on a form.  Create a table view and bind it to the Films table from the VideoCatalodDB.mdb demo database.  Setup the grid control as described in the table view tutorial.  Next, add another level with an associated table view, name them lvFilmsCheck and tvFilmsCheck and repeat the tutorial steps for the new view.  Place the cxPropertiesStore component on the form and name it cxStore.  The result is shown by the following screenshot:

1.	DESIGN TIME USAGE

This chapter shows how to use cxPropertiesStore at design time and describes its default functionality. This implies that the settings are saved when the application is closed and restored when it is restarted.  The example will operate on the settings of the tvFilms view and the tvFilmsCOLOR & tvFilmsYEAR columns.

Double-click on the cxPropertiesStore component’s icon.  This invokes the PropertiesStore Editor:

The editor displays a tree structure of all the components residing on the form containing the cxPropertiesStore.  The Editor buttons’ functions are listed below:

Button	Function
	Groups the Editor tree by components.
	Groups the Editor tree by properties.
	Restores the last saved selection.  The current Properties/components grouping option is saved when the dialog is closed (by pressing the OK button).
	Selects all components/properties within the tree.
	Clears all selected rows.
	Inverts row selections. If you need to select most items, select just the ones you don’t need and then click on this button.

Click the plus sign next to the cxGrid component and examine the properties available:

You can select all the component’s properties you want to save/restore by right-clicking the component name within the tree.  The following image demonstrates how to select all the properties of the tvFilmsYEAR and tvFilmsCOLOR columns:

Also, you can select individual component properties by right-clicking these property names within the tree.  The following image demonstrates how to select the tvFilms view options:

Having selected the required components and their properties, you need to specify the StorageType and StorageName property values.  For the purposes of this example, set the StorageType property value to stRegistry and the StorageName property value to "View Storage":

This tells the cxPropertiesStore component to store settings within the registry in the View Storage key.

Ensure that the Active property of the cxPropertiesStore component is set to True.   Otherwise, cxPropertiesStore will not save/restore the selected settings automatically.

Run the application.  Ungroup the tvFilms and tvFilmsCheck views by dragging the Release Year column header to the column panel.

Close the application and run it again.  Runtime changes are restored for the tvFilms view and its columns.  The tvFilmsCheck view appears with the design time settings, because its properties were not selected for saving.

The following screenshot demonstrates the View Storage registry key structure:

Another way of selecting the properties for saving/restoring is by using the Components property.  Select the cxPropertiesStore component.  Invoke the Object Inspector and click the ellipsis button next to the Components property.  This invokes the Components collection editor:

This collection contains references to all components, which you have previously selected.  Select the first component reference (corresponding to the tvFilms view) and switch to the Object Inspector.  Click the ellipsis button next to the Properties property.  This displays the list of properties selected for saving/restoring:

Go to the "OptionsCustomize" line and add the ColumnGrouping options name, by changing the line to "OptionsCustomize.ColumnGrouping":

The following screenshot demonstrates the result of saving after this change:

As you can see, now only the ColumnGrouping option value is saved instead of the whole OptionsCustomize set.

You can also save/restore properties at design time.  For this purpose, select the required properties via the cxPropertiesStore editor.  Then right-click the cxPropertiesStore component and choose the Save or Restore item from the context menu:

The StorageType and StorageName properties specify the storage used for design time saving/restoring.

2.	USING VIA CODE

This chapter describes how to use cxPropertiesStore by code and this approach provides more flexibility.  There are two features of cxPropertiesStore only available when writing code:

1.	Saving/restoring individual components from the Components collection.

2.	Saving/restoring individual Components items from a storage, different from the one specified by the StorageType and StorageName properties.

The code below handles the OnCreate event of the form to save the properties of a footer summary item.  It selects the Column, Kind and Format properties of the first footer summary item for saving.  The Active property must be set to False before saving is performed.  This disables the default functionality of the cxPropertiesStore component.  Saving is implemented Call the StoreToIniFile method to save the required item of the Components collection.  Note that this method saves footer summary item properties to an INI file, though the StorageName and StorageType properties of the cxStore component specify a registry key as a storage.  The RestoreButtonClick event handler restores the footer summary item settings by calling the RestoreFromIniFile method:

//Delphi

var

  PSComponent: TcxPropertiesStoreComponent;

//...

procedure TForm1.FormCreate(Sender: TObject);

begin

//disabling the default functionality of the cxPropertiesStore component

  cxGridStore.Active := False;

//adding an item to the Components collection

  PSComponent := TcxPropertiesStoreComponent(cxGridStore.Components.Add);

  with PSComponent do

  begin

//setting a table view for saving

    Component := tvFilms;

//selecting the Column, Kind and Format property values of the first footer summary item for saving

    Properties.Add('DataController.Summary.FooterSummaryItems.0.Column');

    Properties.Add('DataController.Summary.FooterSummaryItems.0.Kind');

    Properties.Add('DataController.Summary.FooterSummaryItems.0.Format');

//saving the selected properties to an INI file (note that design time settings designate the registry key as a storage). The storage file is recreated upon saving

    StoreToIniFile('c:\store.ini', True);

  end;

end;

//...

procedure TForm1.RestoreButtonClick(Sender: TObject);

begin

//restoring the footer summary item settings without involving any other Components collection items

  PSComponent.RestoreFromIniFile('c:\store.ini');

end;

//...

//C++ Builder

TcxPropertiesStoreComponent *PSComponent;

//...

void __fastcall TForm1::FormCreate(TObject *Sender)

{

//disabling the default functionality of the cxPropertiesStore component

  cxGridStore->Active = false;

//adding an item to the Components collection

  PSComponent = (TcxPropertiesStoreComponent*)cxGridStore->Components->Add();

//setting a table view for saving

  PSComponent->Component = tvFilms;

//selecting the Column, Kind and Format property values of the first footer summary item for saving

  PSComponent->Properties->Add("DataController.Summary.FooterSummaryItems.0.Column");

  PSComponent->Properties->Add("DataController.Summary.FooterSummaryItems.0.Kind");

  PSComponent->Properties->Add("DataController.Summary.FooterSummaryItems.0.Format");

//saving the selected properties to an INI file (note that design time settings designate the registry key as a storage). The storage file is recreated upon saving

  PSComponent->StoreToIniFile("c:\\store.ini", true);

}

//...

void __fastcall TForm1::RestoreButtonClick(TObject *Sender)

{

//restoring the footer summary item settings without involving any other Components collection items

  PSComponent->RestoreFromIniFile("c:\\store.ini");

}

//...

The result of the code execution (store.ini file contents) is demonstrated below:

[tvFilms: TcxPropertiesStoreComponent]

=

DataController.Summary.FooterSummaryItems.0.Column=tvFilmsRUNTIME

DataController.Summary.FooterSummaryItems.0.Kind=skMax

DataController.Summary.FooterSummaryItems.0.Format=MAX=0 minutes


Using the Image List Editor

See Also

The Express Cross Platform Library provides an image list component – TcxImageList.  Unlike the standard image list, it allows you to store 32-bit images (including PNG images) and paint them with alpha blending.  In this topic, you will learn how to use this component’s design-time editor.

How to Invoke the Image List Editor

To invoke this editor, double-click the TcxImageList component or choose Edit… from its context menu.

Image List Editor UI

Element	Description
Images section	Displays all the images stored within the image list.  As with the standard TImageList Editor, you can select multiple images within the list using the mouse and by holding the Shift and Ctrl keys.  The last image in the selection is displayed within the ‘Selected Image’ section.
Selected Image section	Displays the selected image.  The transparency checkerboard allows you to detect transparent areas and evaluate alpha blending parameters of the image.
Transparent Color	Displays the transparent color for the selected image.  When an image is added or imported from other image lists, its bottom-left pixel specifies the transparent color.  You can change this color via the dropdown list or by clicking directly on a pixel in the selected image. Note: You cannot modify the transparent color for images with alpha channel and icons.  It’s always clNone.
Add Image	Invokes the File Open dialog to load images from files.  Note that you can select multiple files in this dialog. Selected images may be cut into pieces depending on the image list’s Width and Height properties.  Resulting images are appended to the list.
Replace Image	Similar to Add Image.  The only difference is that the last image in the selection is replaced with the images loaded from files.
Delete Image	Removes the selected images from the list.
Clear List	Removes all images from the list.
Export Images	Invokes the Save As dialog to save the selected images to a bitmap file.  Use the dialog to specify the file name and location.
Import Images	This button is enabled when there is at least one image list (a TCustomImageList descendant) with image dimensions matching the current image list.  Click this button to display a dropdown list populated with all suitable image lists.  Choose an item in the dropdown list to append all images from the corresponding image list to the current image list.
Image Size Combo Box	Allows you to assign the image dimensions by selecting one of the standard dimensions listed in a dropdown window.
OK	Applies all pending changes to the image list and closes the Image List Editor.
Cancel	Discards all pending changes to the image list and closes the Image List Editor.
Apply	Applies all pending changes to the image list.


cxControls Unit Overview
cxControls Unit

Classes

TcxControl

TcxControlChildComponent


TcxControl
TcxControl Object

Hierarchy          Properties          Methods         Events

The TcxControl object is the base class designed by Developer Express Inc. for its cross-platform windowed controls.

Unit

cxControls

TcxControl = class(TCustomControl);

Description

The TcxControl object is used to create native cross-platform windowed controls that do not correspond to standard Windows components.  The TcxControl object is the common ancestor for all native cross-platform windowed controls.  As a direct descendant of the TCustomControl class, the TcxControl object provides a Canvas property to help native control drawing easier and to manage the drawing surface.  The Canvas property specifies the TcxCanvas object, which is designed to represent a drawing surface for cross-platform windowed controls.


TcxControl Hierarchy
Hierarchy

TCustomControl

     |


Properties for TcxControl
TcxControl Properties

TcxControl          Legend

In TcxControl

BorderStyle

Bounds

Canvas

ClientBounds

FocusOnClick

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxControl
TcxControl Methods

TcxControl          Legend

In TcxControl

Create

Destroy

InvalidateRect


Events for TcxControl
TcxControl Events

TcxControl          Legend

In TcxControl

OnMouseEnter

OnMouseLeave


TcxControl.BorderStyle

TcxControl

Specifies the border style of the associated control.

type

  TcxControlBorderStyle = (cxcbsNone, cxcbsDefault);

property BorderStyle: TcxControlBorderStyle;

Description

Use the BorderStyle property to change the border style applied to the associated control.

The table below lists values available for the BorderStyle property and provides their description:

Value	Meaning
cxcbsNone	No border is painted around the control.
cxcbsDefault	The border style is specified by the look and feel applied to the control (see the LookAndFeel property).


TcxControl.Bounds

TcxControl

Returns the bound rectangle for a control in pixels.

property Bounds: TRect;

Description

Use the Bounds property to access the TRect type that specifies the rectangular region occupied by a control.  The horizontal and vertical size of this rectangle is equal to the Width and Height property values of the TcxControl object.

ReadOnly Property


TcxControl.Canvas

TcxControl

Specifies a drawing surface for a control.

property Canvas: TcxCanvas;

Description

The Canvas property specifies a drawing surface for a control.  It also provides a library of functions to perform primitive graphic operations such as drawing lines, rectangles, images, text, etc.  The TcxCanvas class is designed to provide proper working in VCL and CLX applications.

ReadOnly Property


TcxControl.ClientBounds

TcxControl

Returns the rectangle of a control’s client area (in pixels).

property ClientBounds: TRect;

Description

Read the ClientBounds property to obtain the size of a control’s client area.  Client area size is obtained by subtracting the border (and scrollbars, if any) size from the size of the area occupied by a control (returned by the Bounds property).

ReadOnly Property


TcxControl.FocusOnClick

TcxControl

Specifies whether the control gets a focus when it has been clicked.

property FocusOnClick: Boolean;

Description

Set the FocusOnClick property to True to acquire a focus when the control has been clicked.

The default value of the FocusOnClick property is True.


TcxControl.IsDesigning

TcxControl

Specifies whether the control is currently being manipulated by the form designer.

property IsDesigning: Boolean;

Description

IsDesigning returns True if the ComponentState property inherited from the TComponent class contains the csDesigning flag indicating that the form designer is manipulating the control.  Otherwise, False is returned.

ReadOnly Property


TcxControl.IsDestroying

TcxControl

Specifies whether the control is being destroyed.

property IsDestroying: Boolean;

Description

The state of a control is determined by the ComponentState property inherited from the TComponent class.  The IsDestroying property returns True if a control is about to be destroyed (the ComponentState contains the csDestroying flag).  Otherwise, the property returns False.

ReadOnly Property


TcxControl.IsFocused

TcxControl

Indicates whether a control has focus.

property IsFocused: Boolean;

Description

Read the IsFocused property to determine if a control currently receives input from the user. The IsFocused property is set to True if the control has focus; otherwise, False.

ReadOnly Property


TcxControl.IsLoading

TcxControl

Specifies whether the current control is being loaded.

property IsLoading: Boolean;

Description

The ComponentState property, inherited from the TComponent class, determines the state of a control.  If it contains the csLoading flag meaning that a control and all its children are being loaded from a file, the IsLoading property returns True.  Otherwise, False is returned.

ReadOnly Property


TcxControl.LookAndFeel

TcxControl

Specifies the default look and feel of a control.

property LookAndFeel: TcxLookAndFeel;

Description

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

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 or LookAndFeel.SkinName property specifies the default look and feel of a control.  Four styles (standard, flat, ultra flat, and Office 2003) determine the manner in which a grid is painted and responds to user events.


TcxControl.PopupMenu

TcxControl

Specifies the popup menu that is associated with a control.

property PopupMenu: TComponent;

Description

The PopupMenu property specifies the popup menu that is associated with the current control.


TcxControl.Create

TcxControl

Creates a new TcxControl object instance.

procedure Create(AOwner: TComponent); override;

Description

Call the Create method to instantiate a control at runtime.  After calling the inherited constructor, the Create method creates a canvas and scrollbars for the control and initializes its properties and variables.  The canvas is provided by the TcxCanvas object which provides a drawing surface for cross-platform windowed controls.


TcxControl.Destroy

TcxControl

Destroys a TcxControl object instance.

procedure Destroy; override;

Description

The Destroy method is used to free any memory or resources allocated in the Create method.


TcxControl.InvalidateRect

TcxControl

Adds the region occupied by a control rectangle to a specified window's update region.  The update region represents a portion of the control client area that must be redrawn.

procedure InvalidateRect(const R: TRect; EraseBackground: Boolean);

Description

Call the InvalidateRect method when the area occupied by a control rectangle will need to be repainted.  The R parameter points to the TRect that contains client coordinates of the control rectangle to be added to the update region.  If this parameter is NULL, the entire client area is added to the update region.

The EraseBackground parameter specifies whether the background within the control rectangle region specified by the R parameter is to be erased when processing the update region.  If this parameter is True, the background is erased when redrawing the control rectangle region.  If this parameter is False, the background remains unchanged.


TcxControl.OnMouseEnter

TcxControl          See Also

Occurs when the mouse pointer moves over a control.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnMouseEnter: TNotifyEvent;

Description

Handle the OnMouseEnter event to perform specific actions when an end-user moves the mouse over the control.  For example, you can use this event to change the control’s appearance (font, color, border width, etc.) when the mouse pointer hovers over the control, and then use the OnMouseLeave event to reverse its appearance back to the default when the mouse leaves the control.


TcxControl.OnMouseLeave

TcxControl          See Also

Occurs when the mouse pointer leaves a control.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnMouseLeave: TNotifyEvent;

Description

Handle the OnMouseLeave event to perform specific actions when an end-user moves the mouse pointer off the control.  For example, you can use this event to undo any changes that were made in the OnMouseEnter event handler.


TcxControlChildComponent
TcxControlChildComponent Object

Hierarchy          Properties          Methods

Represents a child component of a control.

Unit

cxControls

TcxControlChildComponent = class(TComponent);

Description

The TcxControlChildComponent represents a base class for a child component of a control (for instance, grid views in the ExpressQuantumGrid4 control).  The parent control is passed as a parameter in the constructor.


TcxControlChildComponent Hierarchy
Hierarchy

TComponent

     |


Properties for TcxControlChildComponent
TcxControlChildComponent Properties

TcxControlChildComponent          Legend

In TcxControlChildComponent

Control

IsDestroying

IsLoading


Methods for TcxControlChildComponent
TcxControlChildComponent Methods

TcxControlChildComponent          Legend

In TcxControlChildComponent

CreateEx

Destroy


TcxControlChildComponent.Control

TcxControlChildComponent

Specifies the parent control of the current component.

property Control: TcxControl;

Description

Use the Control property to access the parent of the current component.  It is initialized by a parameter passed in the CreateEx constructor.


TcxControlChildComponent.IsDestroying

TcxControlChildComponent

Specifies whether the component is currently being destroyed.

property IsDestroying: Boolean;

Description

The IsDestroying property specifies whether the ComponentState property inherited from TComponent contains the csDestroying flag thus indicating that the component is being destroyed.

ReadOnly Property


TcxControlChildComponent.IsLoading

TcxControlChildComponent

Specifies whether the current component is being loaded.

property IsLoading: Boolean;

Description

The IsLoading property returns True, if the ComponentState property inherited from TComponent contains the csLoading flag.  This indicates that the component (including its children) is being loaded from a file.

ReadOnly Property


TcxControlChildComponent.CreateEx

TcxControlChildComponent

Creates a new child component.

constructor CreateEx(AControl: TcxControl; AAssignOwner: Boolean = True);

Description

CreateEx calls the constructor inherited from TComponent passing a specific owner as a parameter.  If the AAssignOwner parameter is True then the owner of AControl becomes the owner of the new child component.  Otherwise, no owner is passed.

The AControl parameter specifies the parent of the new child component.


TcxControlChildComponent.Destroy

TcxControlChildComponent

Destroys the current component.

destructor Destroy; override;

Description

The destructor destroys the current instance of the TcxControlChildComponent class, removes itself from the parent component and calls the inherited destructor.


cxStyles Unit Overview
cxStyles Unit

Classes

TcxCustomStyle

TcxCustomStyles

TcxStyle

TcxStyleRepository

TcxStyles

Other Types

TcxStyleValue

TcxStyleValues


TcxCustomStyle
TcxCustomStyle Object

Hierarchy          Properties          Methods          See Also

Represents a base class for styles which notify listeners about attribute changes.

Unit

cxStyles

TcxCustomStyle = class(TComponent);

Description

The TcxCustomStyle class implements the functionality required by listeners to notify them about changes to style attribute using their StyleChanged and StyleRemoved methods.  The TcxStyle class is a descendant of the TcxCustomStyle class which introduces style attributes that are shared by all components, namely the background color, font details and text color.  When any of the style attributes are changed, all listeners are notified.

TcxCustomStyles supports an abstract collection of styles, each of which is presented by the TcxCustomStyle class.  Descendants of the TcxCustomStyles class declare appropriate styles for different control elements depending upon the control’s type.  TcxCustomStyles receives notifications about style attribute changes via its StyleChanged and StyleRemoved methods.  When such notifications are received, the corresponding control elements are repainted.


TcxCustomStyle Hierarchy
Hierarchy

TComponent

     |


Properties for TcxCustomStyle
TcxCustomStyle Properties

TcxCustomStyle          Legend

In TcxCustomStyle

StyleRepository


Methods for TcxCustomStyle
TcxCustomStyle Methods

TcxCustomStyle          Legend

In TcxCustomStyle

 AddListener

 Create

 Destroy

 RemoveListener

 RestoreDefaults


TcxCustomStyle.StyleRepository

TcxCustomStyle           See Also

Specifies the repository storing the current style object.

property StyleRepository: TcxStyleRepository;

Description

A repository is an object allowing you to manage a collection of individual styles.  When a repository is destroyed, all styles it owns are also deleted.  Assigning the StyleRepository property adds the current style to this repository.


TcxCustomStyle.AddListener

TcxCustomStyle          See Also

Adds the specified listener to the notification list.

procedure AddListener(AStyles: TcxCustomStyles); virtual;

Description

When the attributes provided by the current style object are changed or the style object is destroyed, all the listeners within the notification list receive the corresponding notification. Call the AddListener method to add the listener specified by the AStyles parameter to this list.  The listener represents a collection of style links for various component elements.  To remove a listener, use the RemoveListener method.


TcxCustomStyle.Create

TcxCustomStyle

Creates a new instance of the TcxCustomStyle class.

constructor Create(AOwner: TComponent); override;

Description

The constructor creates a new instance of the TcxCustomStyle class and initializes all properties to their default values.  The AOwner specifies the component to own the created style.  The owner disposes of the component when it is destroyed.


TcxCustomStyle.Destroy

TcxCustomStyle

Destroys the current style object.

destructor Destroy; override;

Description

The destructor frees all resources allocated by the current style object.  Also, it removes itself from a repository if one is assigned and sends the destroy notification to all its listeners.


TcxCustomStyle.RemoveListener

TcxCustomStyle          See Also

Removes the specified listener from the notification list.

procedure RemoveListener(AStyles: TcxCustomStyles); virtual;

Description

The RemoveListener method removes the listener specified by the AStyles parameter from the notification list.  The listener (a collection of style links for various component elements) will no longer receive notifications when style attribute are changed or when the style object is destroyed.  To add a listener to the notification list, use the AddListener method.


TcxCustomStyle.RestoreDefaults

TcxCustomStyle

Restores default values of style attributes provided by the current style object.

procedure RestoreDefaults; virtual;

Description

RestoreDefaults is a virtual method overridden by TcxCustomStyle descendants in order to restore default style attribute values.


TcxCustomStyles
TcxCustomStyles Object

Hierarchy          Properties          Methods          See Also

Represents a collection of style links for various component elements.

Unit

cxStyles

TcxCustomStyles = class(TcxInterfacedPersistent);

Description

The TcxCustomStyles class supports an abstract collection of style links for various component elements.  Descendants of the TcxCustomStyles class declare appropriate styles for different control elements depending upon the control’s type.  The style of each control element is represented by an object of the TcxCustomStyle class.  The style of every element is represented by an instance of the TcxCustomStyles or TcxStyle class.  It’s possible to assign the same styles to several elements and even to different TcxCustomStyles objects.

TcxCustomStyles provides the StyleChanged and StyleRemoved methods which are used to respond to style changes and adds itself as a listener of its TcxCustomStyle elements.  When any of the TcxCustomStyle attributes are changed, TcxCustomStyles receives a notification and updates the corresponding control elements.

The StyleSheet property specifies the style sheet applied to the current collection of style links.  A style sheet represents a collection of styles for the elements of controls supporting Styles technology (for instance, a grid view).  Instead of specifying individual styles for each control element, you can assign it a style sheet, thus providing values for all style properties.


TcxCustomStyles Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |


Properties for TcxCustomStyles
TcxCustomStyles Properties

TcxCustomStyles          Legend

In TcxCustomStyles

StyleSheet


Methods for TcxCustomStyles
TcxCustomStyles Methods

TcxCustomStyles          Legend

In TcxCustomStyles

 Assign

 Create

 Destroy

 StyleChanged

 StyleRemoved


TcxCustomStyles.StyleSheet

TcxCustomStyles          See Also

Specifies the style sheet for the current style collection.

property StyleSheet: TcxCustomStyleSheet;

Description

The StyleSheet property specifies the style sheet for the style collection provided by the current TcxCustomStyles object.

A style collection provides multiple attributes that control the appearance of different elements of a control.  The TcxGridTableViewStyles collection, for instance, contains the Background, Content, Footer properties specifying styles for the view’s background, data cells and footer panel respectively.  A corresponding style sheet (TcxGridTableViewStyleSheet) contains the same style attributes.  If a style sheet, which is not set, is assigned to the style property within the style collection, the value of this property is determined by the corresponding property of the style sheet.  Thus, a style sheet represents another collection of styles to be assigned to TcxCustomStyles.

Once a style sheet is created and adjusted according to your preferences, it can be used in different applications over and over again.  Style sheets can be saved to an INI file by the SaveStyleSheetsToIniFile procedure and can be loaded from this file via LoadStyleSheetsFromIniFile.

Usually, you create a style sheet via a style repository of class TcxStyleRepository.  At design time, you can create a style sheet via the style repository editor.  It gives you the ability to create a style sheet of a specific type, adjust its properties, add predefined style sheets, load from and save style sheets to an INI file.


TcxCustomStyles.Assign

TcxCustomStyles

Copies one set of styles to another.

procedure Assign(Source: TPersistent); override;

Description

The Assign method copies the set of styles and style event handlers contained in the Source parameter to the current set of styles.

Descendants of the TcxCustomStyles class override this method to copy styles specific to them.  For instance, TcxGridBandStyles assigns its Background, Content, Header style properties and the OnGetHeaderStyle event handler.

Use the Assign method when you need to copy styles provided by some style collection to the current one.  This results in applying the same styles to different controls.


TcxCustomStyles.Create

TcxCustomStyles

Creates a new instance of the TcxCustomStyles class.

constructor Create(AOwner: TPersistent); override;

Description

Create calls the inherited constructor and initializes object properties to their default values.


TcxCustomStyles.Destroy

TcxCustomStyles

Destroys the current TcxCustomStyles object.

destructor Destroy; override;

Description

The destructor frees all resources allocated by the current object.


TcxCustomStyles.StyleChanged

TcxCustomStyles

The method is called when any of attributes of the specified TcxCustomStyle object are changed.

procedure StyleChanged(Sender: TcxCustomStyle);

Description

Use this method to implement operations in response to style attribute changes.  The Sender parameter identifies the style object whose attributes are changed.


TcxCustomStyles.StyleRemoved

TcxCustomStyles

This method is called when the specified style is about to be destroyed.

procedure StyleRemoved(Sender: TcxCustomStyle);

Description

Implement the StyleRemoved method to react to style destroying.  The Sender parameter defines the style object which is about to be destroyed.


TcxStyle
TcxStyle Object

Hierarchy          Properties          Methods          See Also

Specifies style attributes for an element of some control.

Unit

cxStyles

TcxStyle = class(TcxCustomStyle);

Description

TcxStyle declares properties controlling the appearance of a control element.  These attributes are background color, font details and text color.  The AssignedValues property determines whether to use these attributes when rendering control elements.  When you assign a specific style attribute, the corresponding flag is set in AssignedValues.

Controls usually have to publish styles for several elements such as background, buttons, panels, etc.  In this case, controls can declare a class derived from the TcxStyles class publishing specific style properties.  Each property of this type represents an object of the TcxStyle class.  It is possible to assign the same styles to multiple properties.  When any attribute of a particular style is changed, all TcxStyles objects owning a property with this style assigned receive notification and update the corresponding control elements.

You can use a style repository (TcxStyleRepository) to create and store individual styles.  When a repository is destroyed, it deletes all styles it owns.  The StyleRepository property indicates the repository object which owns the current style.


TcxStyle Hierarchy
Hierarchy

TComponent

     |

TcxCustomStyle

     |


Properties for TcxStyle
TcxStyle Properties

TcxStyle          Legend

In TcxStyle

AssignedValues

Bitmap

Color

Font

TextColor

Derived from TcxCustomStyle

StyleRepository


Methods for TcxStyle
TcxStyle Methods

TcxStyle          Legend

In TcxStyle

 Create

 Destroy

 RestoreDefaults

Derived from TcxCustomStyle

 AddListener

 Create

 Destroy

 RemoveListener

 RestoreDefaults


TcxStyle.AssignedValues

TcxStyle

Determines which style attributes are assigned.

type

  TcxStyleValues = set of TcxStyleValue;

property AssignedValues: TcxStyleValues;

Description

The AssignedValues property consists of a set of flags controlling which style attributes are used to render elements of a specific control.  When the Color, Font or TextColor properties are assigned, the corresponding flags in AssignedValues are enabled, thus specifying that these attributes are used when drawing a control element.  If any flag in AssignedValues is not enabled, the value of the corresponding attribute is not used when drawing.


TcxStyle.Bitmap

TcxStyle          See Also

Specifies the background bitmap for a control element.

property Bitmap: TBitmap;

Description

Use the Bitmap property to specify the background bitmap for a control element. Setting this property overrides the Color property value.

The following image shows a view with bitmaps assigned to the GroupByBox and Content styles:

When assigning the Bitmap property, the svBitmap flag is automatically activated in the AssignedValues property.


TcxStyle.Color

TcxStyle

Defines the background color for a control element.

property Color: TColor;

Description

The Color property determines the color of control background.  When assigning the Color property the svColor flag is automatically set in AssignedValues.


TcxStyle.Font

TcxStyle

Specifies the font of the output text in a control element.

property Font: TFont;

Description

The Font property defines the font attributes such as height, font family and style (bold, italic, etc.).  The TFont.Color attribute is ignored.  Use the TextColor property instead to specify the font color.  When changing Font attributes the svFont flag is set in AssignedValues.


TcxStyle.TextColor

TcxStyle

Specifies the text color.

property TextColor: TColor;

Description

The TextColor defines the color of the text (in contrast to the background color determined by the Color property).  When TextColor is assigned, the svTextColor flag is set in AssignedValues.


TcxStyle.Create

TcxStyle

Creates an instance of the TcxStyle class.

constructor Create(AOwner: TComponent); override;

Description

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


TcxStyle.Destroy

TcxStyle

Destroys an instance of the TcxStyle class.

destructor Destroy; override;

Description

The destructor frees all resources allocated by the current TcxStyle object.  The destructor deletes the object from a repository, if assigned, and sends notification when destroyed to all listeners.


TcxStyle.RestoreDefaults

TcxStyle          See Also

Clears all the flags in the AssignedValues property.

procedure RestoreDefaults; override;

Description

The RestoreDefaults method clears all the flags in the AssignedValues property, thus preventing the corresponding style attributes (Color, Font, TextColor) from being used when rendering a control element.  RestoreDefaults also sets the Color and TextColor properties to clDefault.


TcxStyleRepository
 TcxStyleRepository Object

Hierarchy          Properties          Methods          See Also

Represents an object managing collections of styles and style sheets.

Unit

cxStyles

TcxStyleRepository = class(TComponent);

Description

A style repository represents organized storage of styles applicable to Developer Express controls supporting Styles technology.  The TcxStyleRepository class allows you to create, store and access individual styles where each is presented by the TcxCustomStyle class (or its descendant).  TcxCustomStyle is an abstract class.  Use the TcxStyle class to create items in a repository.

Most Developer Express controls supporting Styles technology declare a Styles member. This supports a collection of style properties defining the appearance of particular control elements.  Usually you have to create a style, initialize its attributes as appropriate and assign the style to the control’s style property.

Using style sheets is another way of initializing style properties of a control element.  A specific style sheet represents a set of styles suitable for a particular control (for instance, a TcxGridTableViewStyleSheet class specify styles for a grid view).  Instead of specifying individual styles for a control element, you can assign it a style sheet thus specifying values for all style properties.  To assign a style sheet to a control element, use its Styles.StyleSheet property.

You can create a style sheet programmatically using the CreateStyleSheet method.  All style sheets are supported by the StyleSheets property.

The style repository editor provides you a convenient way to manipulate styles and style sheets at design time.  The next image demonstrates the Style Sheets tab of the style repository editor:


TcxStyleRepository Hierarchy
Hierarchy

TComponent

     |


Properties for TcxStyleRepository
TcxStyleRepository Properties

TcxStyleRepository          Legend

In TcxStyleRepository

Count

Items

StyleSheetCount

StyleSheets


Methods for TcxStyleRepository
TcxStyleRepository Methods

TcxStyleRepository          Legend

In TcxStyleRepository

 Clear

 ClearStyleSheets

 Create

 CreateItem

 CreateItemEx

 CreateStyleSheet

 CreateStyleSheetEx

 Destroy


TcxStyleRepository.Count

TcxStyleRepository          See Also

Gets the number of styles in the current repository.

property Count: Integer;

Description

The Count property identifies the number of styles in the Items collection.  Use either CreateItem or CreateItemEx methods to add styles to the repository.

ReadOnly Property


TcxStyleRepository.Items

TcxStyleRepository          See Also

Provides indexed access to a collection of styles in the current repository object.

property Items[Index: Integer]: TcxCustomStyle;

Description

The Items property allows you to access a specific style by its index.  The number of styles is determined by the Count property.

ReadOnly Property


TcxStyleRepository.Clear

TcxStyleRepository          See Also

Destroys all styles in the current repository.

procedure Clear;

Description

The Clear method disposes all TcxCustomStyle objects contained in the current repository object.


TcxStyleRepository.Create

TcxStyleRepository

Creates a new instance of the TcxStyleRepository class.

constructor Create(AOwner: TComponent); override;

Description

The constructor creates and initializes a new instance of the TcxStyleRepository class.  The AOwner parameter identifies the object to own the created repository.  An owner is responsible for disposing objects it owns.


TcxStyleRepository.CreateItem

TcxStyleRepository          See Also

Creates a new style in a repository.

type

  TcxCustomStyleClass = class of TcxCustomStyle;

function CreateItem(AStyleClass: TcxCustomStyleClass): TcxCustomStyle; virtual;

Description

Use the CreateItem method to create a new style in a repository.  The class of the style to create is determined by the AStyleClass parameter.  The current repository object becomes the owner of the new style and is used to initialize the TcxCustomStyle.StyleRepository property.  The method returns the style object created.


TcxStyleRepository.CreateItemEx

TcxStyleRepository          See Also

Creates a new style in the repository with a specified owner.

type

  TcxCustomStyleClass = class of TcxCustomStyle;

function CreateItemEx(AStyleClass: TcxCustomStyleClass; AOwner: TComponent): TcxCustomStyle; virtual;

Description

The CreateItemEx method allows you to create a style with a specified owner.  The AStyleClass parameter identifies the class of the style to create.  The StyleRepository property of the style created is initialized with the current TcxStyleRepository object.


TcxStyleRepository.Destroy

TcxStyleRepository

Destroys the current TcxStyleRepository object.

destrutor Destroy; override;

Description

The destructor disposes all styles the repository owns and frees all resources allocated by the object.


TcxStyles
TcxStyles Object

Hierarchy          Properties          Methods          See Also

Represents an abstract collection of styles which control the appearance of specific control elements.

Unit

cxStyles

TcxStyles = class(TcxCustomStyles);

Description

The TcxStyles class represents an abstract collection of styles for different control elements.  It doesn’t introduce any new style properties, but instead provides the ability to access styles by their indexes.  Each style is of the TcxStyle class and declares general style attributes, such as the background color, font details and text color.

Descendants of the TcxStyles class declare appropriate styles for different control elements depending upon the control’s type.

Since TcxStyles is inherited from the TcxCustomStyles class it receives notifications about style attribute changes via its StyleChanged and StyleRemoved methods.  TcxStyles adds itself as a listener to all its TcxStyle elements and receives notification when any of the TcxStyle attributes are changed and the corresponding control elements are then repainted as a result.


TcxStyles Hierarchy
Hierarchy

TInterfacedPersistent

     |

TcxInterfacedPersistent

     |

TcxCustomStyles

     |


Properties for TcxStyles
TcxStyles Properties

TcxStyles          Legend

Derived from TcxCustomStyles

StyleSheet


Methods for TcxStyles
TcxStyles Methods

TcxStyles          Legend

Derived from TcxCustomStyles

Assign

Create

Destroy


TcxStyleValue
TcxStyleValue type

Enumerates flags indicating which TcxStyle attributes are assigned.

Unit

cxStyles

type

  TcxStyleValue = (svBitmap, svColor, svFont, svTextColor);

Description

The TcxStyleValue type enumerates the flags indicating which TcxStyle attributes are assigned.  These flags are set via the TcxStyle.AssignedValues property.

Value	Meaning
svBitmap	Indicates that a value is assigned to the TcxStyle.Bitmap property.
svColor	Indicates that a value is assigned to the TcxStyle.Color property.
svFont	Indicates that a value is assigned to the TcxStyle.Font property.
svTextColor	Indicates that a value is assigned to the TcxStyle.TextColor property.


TcxStyleValues
TcxStyleValues type

Represents a set of flags indicating what style attributes of a TcxStyle object are assigned values.

Unit

cxStyles

type

  TcxStyleValues = set of TcxStyleValue;

Description

The TcxStyleValues type represents a set of flags indicating what TcxStyle attributes are set.  Use the TcxStyle.AssignedValues property to access these flags.


LoadStyleSheetsFromIniFile
LoadStyleSheetsFromIniFile Procedure

See Also

Loads style sheets from an INI file.

Unit

cxStyles

type

  TcxCustomStyleSheetClass = class of TcxCustomStyleSheet;

procedure LoadStyleSheetsFromIniFile(const AIniFileName: string; AStyleRepository: TcxStyleRepository; AStyleSheetClass: TcxCustomStyleSheetClass; const AStyleSheetNames: TStrings = nil; AOwner: TComponent = nil; const AStyleSheetList: TList = nil; AStyleGetName: TcxStyleGetName = nil);

Description

The LoadStyleSheetsFromIniFile method loads style sheets into a style repository determined by the AStyleRepository parameter from the INI file with the name specified by the AIniFileName parameter.

The AStyleSheetClass parameter determines the class of style sheet(s) to create when loading from a file.  Using the AStyleSheetNames parameter, you can specify the names of the style sheets to load.  If it is set to nil, all style sheets are loaded from the file.

Note: all style sheets created by the LoadStyleSheetsFromIniFile procedure will be the same class as defined by AStyleSheetClass.

The INI file stores information on a style sheet in the following format:

[Style Sheet Caption]

Style1=Values

Style2=Values

...

If the class defined by AStyleSheetClass does not contain specific styles loaded from a particular section of the INI file, these styles are ignored.  All other styles are used to set values for style properties of a new style sheet.

You can use the AStyleSheetList parameter to add all loaded style sheets to an external list, but this is used at design time mainly.  The AStyleGetName parameter is for internal use only.


SaveStyleSheetsToIniFile
SaveStyleSheetsToIniFile Procedure

See Also

Saves style sheets to an INI file.

Unit

cxStyles

procedure SaveStyleSheetsToIniFile(const AIniFileName: string; const AList: TList);

Description

The SaveStyleSheetsToIniFile method saves the style sheet list specified by the AList parameter into the INI file with its name specified by the AIniFileName parameter.

SaveStyleSheetsToIniFile saves only the caption of a style sheet and its assigned values.  The class name of a style sheet is not saved.


TcxStyleRepository.StyleSheetCount

TcxStyleRepository

Determines the number of style sheets within the style repository.

property StyleSheetCount: Integer;

Description

The StyleSheetCount property determines the style sheet count within the repository.  All available style sheets are represented by the StyleSheets property.

ReadOnly Property


TcxStyleRepository.StyleSheets

TcxStyleRepository

Represents all available style sheets within the style repository.

property StyleSheets[Index: Integer]: TcxCustomStyleSheet;

Description

The StyleSheets property represents all available style sheets within the style repository and enables accessing them by a zero-based index.  The index cannot be greater than StyleSheetCount–1.  At design time, you can access the available styles via the style repository editor:

ReadOnly Property


TcxStyleRepository.ClearStyleSheets

TcxStyleRepository

Removes all style sheets from the style repository.

procedure ClearStyleSheets;

Description

The ClearStyleSheets method removes all style sheets from the style repository.  Note that the TcxStyle objects created along with the style sheets are not removed.  Styles are disposed of when the style repository is destroyed.


TcxStyleRepository.CreateStyleSheet

TcxStyleRepository

Creates and adds a style sheet to the style repository.

type

  TcxCustomStyleSheetClass = class of TcxCustomStyleSheet;

function CreateStyleSheet(AStyleSheetClass: TcxCustomStyleSheetClass): TcxCustomStyleSheet; virtual;

Description

The CreateStyleSheet method creates a style sheet of class specified by the AStyleSheetClass parameter and adds it to the style repository. If the operation is successful the method returns the newly added style sheet.


TcxStyleRepository.CreateStyleSheetEx

TcxStyleRepository

Creates a style sheet and adds it to the style repository.

type

  TcxCustomStyleSheetClass = class of TcxCustomStyleSheet;

function CreateStyleSheetEx(AStyleSheetClass: TcxCustomStyleSheetClass; AOwner: TComponent): TcxCustomStyleSheet; virtual;

Description

The CreateStyleSheetEx method creates a style sheet of class specified by the AStyleSheetClass parameter and adds it to the style repository. The AOwner parameter specifies the owner component for the added style sheet.  If the operation is successful, the method returns the newly added style sheet.  You should not use this method directly. It is for internal use. Use the CreateStyleSheet method instead.


TcxCustomStyleSheet
TcxCustomStyleSheet Object

Hierarchy          Properties          Methods          See Also

Represents the base class for all style sheets.

Unit

cxStyles

TcxCustomStyleSheet = class(TComponent);

Description

A style sheet represents a collection of styles for elements of controls supporting Styles technology (for instance, a grid view).  Instead of specifying individual styles for a control element, you can assign it a style sheet, thus providing values for all style properties.  To assign a style sheet to a control element, use the StyleSheet property inherited from the TcxCustomStyles class.

The TcxCustomStyleSheet object implements functionality common to all style sheets.  It is the base class and does not actually provide any style properties.  Descendants of the class publish style properties specific to a control element for which style sheets are designed.  For instance, the TcxGridTableViewStyleSheet class declares styles specific to a grid table view.

Styles and style sheets are usually stored within a style repository (a TcxStyleRepository component) that provides WYSIWYG styles and style sheet editing facilities.  The style repository editor gives you the ability to create a style sheet of a specific type, adjust its properties, add predefined style sheets, load from and save style sheets to an INI file.  You can also load/save style sheets to an INI file programmatically via the LoadStyleSheetsFromIniFile and SaveStyleSheetsToIniFile procedures respectively.


TcxCustomStyleSheet Hierarchy
Hierarchy

TComponent

     |


Properties for TcxCustomStyleSheet
TcxCustomStyleSheet Properties

TcxCustomStyleSheet          Legend

In TcxCustomStyleSheet

Caption

StyleRepository


Methods for TcxCustomStyleSheet
TcxCustomStyleSheet Methods

TcxCustomStyleSheet          Legend

In TcxCustomStyleSheet

 Create

 Destroy

 GetStyles

 GetStylesClass

 SetStyles


TcxCustomStyleSheet.Caption

TcxCustomStyleSheet

Represents the caption of the style sheet.

property Caption: string;

Description

The Caption property specifies the style sheet caption.  Use the caption according to your needs.  For instance, it can be used to give a unique name to a style sheet in order to easily recognize it among other style sheets.


TcxCustomStyleSheet.StyleRepository

TcxCustomStyleSheet

Specifies the style repository containing the current style sheet.

property StyleRepository: TcxStyleRepository;

Description

The StyleRepository property specifies the style repository that contains the style sheet. Style sheets should be stored in repositories for proper design time handling. When created via the repository editor, style sheet is automatically placed within it.


TcxCustomStyleSheet.Create

TcxCustomStyleSheet

Creates an instance of the TcxCustomStyleSheet object.

constructor Create(AOwner: TComponent); override;

Description

Use the constructor to create a style sheet at runtime. The AOwner parameter is the owner of the TcxCustomStyleSheet object.

TcxCustomStyleSheet is an abstract class.  Use its descendants, such as TcxGridTableViewStyleSheet or TcxGridCardViewStyleSheet classes instead.


TcxCustomStyleSheet.Destroy

TcxCustomStyleSheet

Removes the style sheet from memory.

destructor Destroy; override;

Description

Do not call the Destroy method directly. Call the Free method instead.


TcxCustomStyleSheet.GetStyles

TcxCustomStyleSheet

Returns the collection of styles contained in the style sheet.

function GetStyles: TcxCustomStyles;

Description

The GetStyles method returns the collection of styles contained in the style sheet. The returned styles are specific for the control. To obtain the styles class, use the GetStylesClass method.

To set the styles collection for the style sheet, use the SetStyles method.  This allows you to set all style properties at once.  For instance, if you want to create a style sheet specifying the same styles as a style collection, use the SetStyles method and pass the style collection to it as a parameter.  Then you can save the style sheet to an INI file via the SaveStyleSheetsToIniFile procedure to save it for future use.


TcxCustomStyleSheet.GetStylesClass

TcxCustomStyleSheet

Determines the class of styles within the style sheet.

type

  TcxCustomStylesClass = class of TcxCustomStyles;

function GetStylesClass: TcxCustomStylesClass; virtual;

Description

Use this method to determine the style class. This is important when working with a styles collection.  The control styles collections may vary (have different styles) and it is necessary to determine what style collection the style sheet contains.


TcxCustomStyleSheet.SetStyles

TcxCustomStyleSheet

Sets the styles collection for the style sheet.

procedure SetStyles(const Value: TcxCustomStyles);

Description

The SetStyles method sets the style collection provided via the Value parameter. This allows you to set all style properties at once.  For instance, if you want to create a style sheet specifying the same styles as a style collection, use the SetStyles method and pass the style collection to it as a parameter.  Then you can save the style sheet to an INI file using the SaveStyleSheetsToIniFile procedure to save it for future use.

To get the styles collection, use the GetStyles method.


Legend

 Protected

 Published

 ReadOnly


WYSIWYG

"What You See Is What You Get" - Applicable to editor classes in that the author is aware at all times of the final appearance of the object being built.


Skin

Skins give you total freedom in look and feel customization.  A skin contains bitmaps showing all control elements in their various states (normal, hot-tracked, selected, pressed, etc.)  Since each control is painted using the corresponding bitmaps, the appearance of the entire skinned application does not generally depend on the Operating System.  By using skins you can introduce the Windows® XP look and feel options in applications that are not running under the XP OS.

With the ExpressSkins Library, you can add skin support to your applications built with Developer Express controls.  Note that this library is not shipped as part of the Express Cross Platform Library and must be purchased separately.


TcxCheckBoxState
TcxCheckBoxState type

Represents states for the TcxCustomCheckBox editor.

Unit

cxLookAndFeelPainters

type

  TcxCheckBoxState = (cbsUnchecked, cbsChecked, cbsGrayed);

Description

The TcxCheckBoxState class enumerates possible values for the check box state.  The check box state is set via the TcxCustomCheckBox.State property, which 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.


TcxCustomLookAndFeelPainter Object

Hierarchy

Represents a library for drawing primitives.

Unit

cxLookAndFeelPainters

TcxCustomLookAndFeelPainter = class(TObject);

Description

The TcxCustomLookAndFeelPainter class represents a library for drawing primitives used by other controls to render themselves on a graphic surface.  It provides numerous functions to draw borders, buttons, and different graphic glyphs.  TcxCustomLookAndFeelPainter is an abstract class that implements base functionality.  Its descendants override library functions to draw primitives using a specific look & feel style.  For instance, the TcxWinXPLookAndFeelPainter class implements drawing primitives using the Windows XP look & feel.

Controls are not aware of a particular painter class used to render them.  They only know the interface of the TcxCustomLookAndFeelPainter class and call its virtual functions.  These functions are used to draw different control elements:

•	buttons: DrawButton, DrawButtonBorder, DrawExpandButton, DrawCheckButton, etc.;

•	headers: DrawHeader, DrawHeaderBorder, DrawHeaderPressed, etc.;

•	indicators: DrawIndicatorItem;

•	etc.

This concept provides flexibility when implementing various styles.


TcxCustomLFPainter Hierarchy
Hierarchy

TObject

    |


cxExport Unit Overview
cxExport Unit

Global Constants

cxExportGraphicClass


cxExportGraphicClass constant
cxExportGraphicClass global constant

Specifies which type of graphics class to use to generate the images, which are applied to the exported data.

Unit

cxExport

cxExportGraphicClass : TGraphicClass = TBitmap;

Description

The DX controls (such as TcxGrid, TcxTreeList and TcxVerticalGrid) provide the means for exporting their data to various formats. To reflect the appearance of those controls in the exported formats different types of images are used. To minimize the storage requirement for the generated images the TMetafile or TJPEGImage types can be applied. Use the cxExportGraphicClass constant to specify the type of the graphics class that will be used to generate the images when the DX controls’ export routines are invoked.


dxGDIPlusClasses Unit Overview
dxGDIPlusClasses Unit

Classes

TdxPNGImage


TdxPNGImage
TdxPNGImage Object

Hierarchy          Methods

Represents a PNG image.

Unit

dxGDIPlusClasses

TdxPNGImage = class(TGraphic)

Description

This image format supports 32-bit images.  24 bits are used to represent red, green and blue channels (8 bits per each channel).  8 additional bits are needed to specify the transparency level for each pixel.

The TdxPNGImage class provides the following image operations:

•	The bi-directional transformation between BMP and PNG formats.

•	Drawing and rescaling operations.


TdxPNGImage Hierarchy
Hierarchy

TGraphic

     |

TdxPNGImage


Methods for TdxPNGImage
TdxPNGImage Methods

TdxPNGImage          Legend

In TdxPNGImage

DrawEx

GetAsBitmap

SetBitmap

StretchDraw

StretchDrawEx


TdxPNGImage.DrawEx

TdxPNGImage          See Also

Copies the ASource image fragment into the ADest rectangle.

procedure DrawEx(Graphics: GpGraphics; const ADest, ASource: TRect);

Description

The Draw method resizes the image to completely fill the destination rectangle.  Note that the image is properly resized if its initial dimensions (height and width) are two or more pixels.

The Draw method provides the same functionality as the StretchDrawEx method.

Graphics specifies the canvas.

ADest and ASource specify a destination and source rectangles.


TdxPNGImage.GetAsBitmap

TdxPNGImage          See Also

Creates a new bitmap from the currently processed PNG image.

function GetAsBitmap: TBitmap; virtual;


TdxPNGImage.SetBitmap

TdxPNGImage          See Also

Initializes this TdxPNGImage instance with an image specified by ABitmap.

procedure SetBitmap(ABitmap: TBitmap); virtual;


TdxPNGImage.StretchDraw

TdxPNGImage          See Also

Paints the image within the ADest rectangle.

Overloaded Variants

procedure StretchDraw(DC: HDC; const ADest: TRect); virtual;

procedure StretchDraw(DC: HDC; const ADest, ASource: TRect); virtual;

Description

The StretchDraw method resizes the image to completely fill the destination rectangle.  Note that the image is properly resized if its initial dimensions (height and width) are two or more pixels.

The overload copies the ASource image fragment into the ADest rectangle.

DC specifies a handle to the device context.

ADest and ASource specify a destination and source rectangles.


TdxPNGImage.StretchDrawEx

TdxPNGImage          See Also

Copies the ASource image fragment into the ADest rectangle.

procedure StretchDrawEx(Graphics: GpGraphics; const ADest, ASource: TRect); virtual;

Description

The StretchDrawEx method resizes the image to completely fill the destination rectangle.  Note that the image is properly resized if its initial dimensions (height and width) are two or more pixels.

The StretchDrawEx method provides the same functionality as the DrawEx method.

Graphics specifies the canvas.

ADest and ASource specify a destination and source rectangles.


dxFading Unit Overview
dxFading Unit

Classes

TdxFader

Other Types

TdxFaderAnimationState

Routines

dxFader

Global Constants

dxFadeInDefaultAnimationFrameCount

dxFadeInDefaultAnimationFrameDelay

dxFadeOutDefaultAnimationFrameCount

dxFadeOutDefaultAnimationFrameDelay


TdxFader
TdxFader Object

Hierarchy          Properties

Represents an object that controls fading animation effects within an application.

Unit

dxFading

TdxFader = class(TObject);

Description

This class introduces properties that allow you to:

•	Enable or disable fading animation effects within an application (State).

•	Limit the number of animations to be played at one time (MaxAnimationCount).

To access the TdxFader object within an application, use the dxFader function.  Use the dxFadeInDefaultAnimationFrameCount, dxFadeInDefaultAnimationFrameDelay, dxFadeOutDefaultAnimationFrameCount, and dxFadeOutDefaultAnimationFrameDelay global constants to customize the animation speed and smoothness.

Important Note: Fading animation effects require the Microsoft GDI+ library to be installed.  Gdiplus.dll is included with Windows XP.  GDI+ is available as a redistributable file for Windows NT 4.0 SP6, Windows 2000, Windows 98, and Windows Me.  To download the latest redistributable, see http://www.microsoft.com/downloads/details.aspx?FamilyID=6a63ab9c-df12-4d41-933c-be590feaa05a&DisplayLang=en.


TdxFader Hierarchy
Hierarchy

TObject

     |

TdxFader


Properties for TdxFader
TdxFader Properties

TdxFader          Legend

In TdxFader

MaxAnimationCount

State


TdxFader.MaxAnimationCount

TdxFader

Specifies the maximum number of animations that can be played at one time.

property MaxAnimationCount: Integer;

Description

Decreasing this property value allows you to improve performance.  Possible values are 0 through 20.

The default value of the MaxAnimationCount property is 10.


TdxFader.State

TdxFader          See Also

Enables fading animation effects within an application.

type

  TdxFaderAnimationState = (fasDefault, fasEnabled, fasDisabled);

property State: TdxFaderAnimationState;

Description

Values include:

Value	Description
fasDefault	Fading animation effects are enabled if transition effects are enabled for menus and tooltips in the Operating System.  See the corresponding option in the Effects window available via Display Properties | Appearance | Effects.  In Windows® Vista, these effects are always enabled.
fasEnabled	Fading animation effects are enabled.
fasDisabled	Fading animation effects are disabled.

Note:	Fading animation effects can only be applied if the Microsoft GDI+ library is installed and the color depth is greater than 16-bit.

The default value of the State property is fasDefault.


dxFader
dxFader global function

Provides access to an object that controls fading animation effects within an application.

Unit

dxFading

function dxFader: TdxFader;

Description

Refer to the TdxFader class description, to learn about available settings.


dxFadeInDefaultAnimationFrameCount constant
dxFadeInDefaultAnimationFrameCount global constant

See Also

Determines the default number of frames for a fade-in animation effect.

Unit

dxFading

dxFadeInDefaultAnimationFrameCount: Integer = 4;

Description

Possible values are 1 through 32.


dxFadeInDefaultAnimationFrameDelay constant
dxFadeInDefaultAnimationFrameDelay global constant

See Also

Determines the default frame delay (in milliseconds) for a fade-in animation effect.

Unit

dxFading

dxFadeInDefaultAnimationFrameDelay: Integer = 20;

Description

Possible values are 10 through 300.


dxFadeOutDefaultAnimationFrameCount constant
dxFadeOutDefaultAnimationFrameCount global constant

See Also

Determines the default number of frames for a fade-out animation effect.

Unit

dxFading

dxFadeOutDefaultAnimationFrameCount: Integer = 12;

Description

Possible values are 1 through 32.


dxFadeOutDefaultAnimationFrameDelay constant
dxFadeOutDefaultAnimationFrameDelay global constant

See Also

Determines the default frame delay (in milliseconds) for a fade-out animation effect.

Unit

dxFading

dxFadeOutDefaultAnimationFrameDelay: Integer = 20;

Description

Possible values are 10 through 300.


cxLookAndFeels Unit Overview
cxLookAndFeels Unit

Classes

TcxLookAndFeel

TcxLookAndFeelController

Interfaces

IcxLookAndFeelNotificationListener

Other Types

TcxLookAndFeelKind

TcxLookAndFeelValue

TcxLookAndFeelValues

Routines

RootLookAndFeel

Global Constants

cxDefaultLookAndFeelKind

cxDefaultLookAndFeelNativeStyle

cxDefaultLookAndFeelSkinName

cxUseSkins


TcxLookAndFeel
TcxLookAndFeel Object

Hierarchy          Properties          Methods          Events

Specifies a TcxControl descendant’s appearance and behavior when it interacts with a user.

Unit

cxLookAndFeels

TcxLookAndFeel = class(TcxInterfacedPersistent, IcxLookAndFeelNotificationListener);

Description

Each Developer Express control has its own look and feel implemented via the TcxLookAndFeel class.  This class has three properties – Kind, NativeStyle, and SkinName – that determine a control’s appearance and the manner in which the control visually responds to user actions (focus, mouse move, clicks etc.)  The NativeStyle property specifies whether to use the native windows style for control painting.  This property has a higher priority than the Kind or SkinName property.  If the NativeStyle property is set to True, the control is painted according to the native windows style (Currently, this feature only supported on Windows® XP or later).  Otherwise, the Kind or SkinName property specifies the paint style for the control.

If any of the properties mentioned above is modified, the corresponding flag is set in the AssignedValues property and the OnChanged event is raised.  To reset all the flags in the AssignedValues property, call the Reset method.

Importing/Exporting Look and Feel Settings

Every Developer Express control can export its look and feel to other Developer Express controls.  The MasterLookAndFeel property determines the imported look and feel of any Developer Express control.  Any control, which imports the look and feel of the current control, is defined as a listener.  It listens to changes within the current control via the IcxLookAndFeelNotificationListener interface.

The IcxLookAndFeelNotificationListener interface listens for two events:

•	Any look and feel setting change via the MasterLookAndFeelChanged method.

•	The TcxLookAndFeel class instance destruction via the MasterLookAndFeelDestroying method.

Listener controls reflect all changes within the current control.  If an imported TcxLookAndFeel class instance is destroyed, a listener control obtains its look and feel settings from the cxDefaultLookAndFeelKind, cxDefaultLookAndFeelNativeStyle, and cxDefaultLookAndFeelSkinName global constants.

Note: The look and feel properties of TcxControl descendants have a higher priority and override master look and feel settings.

To access the painter that is used to paint the control according to the look and feel settings, use the Painter property.

Root Look and Feel Settings

The root look and feel (a TcxLookAndFeel class instance) is automatically created on the application startup.  Its Kind, NativeStyle, and SkinName properties contain values of the cxDefaultLookAndFeelKind, cxDefaultLookAndFeelNativeStyle, and cxDefaultLookAndFeelSkinName global constants, respectively.

At design and runtime, the root look and feel can be customized via the TcxLookAndFeelController and TdxSkinController components.  At runtime, you can access the root look and feel via the RootLookAndFeel global function.  When an instance of the TcxLookAndFeel class is created, it automatically becomes a listener of the root look and feel controller.  You can change its broadcaster by assigning another look and feel to the MasterLookAndFeel property.


TcxLookAndFeel Hierarchy
Hierarchy

TcxInterfacedPersistent

     |


Properties for TcxLookAndFeel
TcxLookAndFeel Properties

TcxLookAndFeel          Legend

In TcxLookAndFeel

AssignedValues

Kind

MasterLookAndFeel

NativeStyle

Painter

SkinName


Methods for TcxLookAndFeel
TcxLookAndFeel Methods

TcxLookAndFeel          Legend

In TcxLookAndFeel

Create

Destroy

Reset


Events for TcxLookAndFeel
TcxLookAndFeel Events

TcxLookAndFeel          Legend

In TcxLookAndFeel

OnChanged


TcxLookAndFeel.AssignedValues

TcxLookAndFeel

Represents a set of assigned look and feel options.

type

  TcxLookAndFeelValue = (lfvKind, lfvNativeStyle, lfvSkinName);

  TcxLookAndFeelValues = set of TcxLookAndFeelValue;

property AssignedValues: TcxLookAndFeelValues;

Description

Changing a control’s Kind, NativeStyle, or SkinName properties sets the corresponding flag in the AssignedValues property.  When a flag is set, it forces the control to use the corresponding option in the control’s LookAndFeel property.  When a flag is not set or reset, the corresponding look and feel setting is obtained from the MasterLookAndFeel property (if set) or the cxDefaultLookAndFeelKind, cxDefaultLookAndFeelNativeStyle, and cxDefaultLookAndFeelSkinName global constants.

Value	Description
lfvKind	Corresponds to the control’s LookAndFeel.Kind property.
lfvNativeStyle	Corresponds to the control’s LookAndFeel.NativeStyle property.
lfvSkinName	Corresponds to the control’s LookAndFeel.SkinName property.

To reset the AssignedValues property, call the Reset method.


TcxLookAndFeel.Kind

TcxLookAndFeel          See Also

Determines how a control is painted.

type

  TcxLookAndFeelKind = (lfFlat, lfStandard, lfUltraFlat, lfOffice11);

property Kind: TcxLookAndFeelKind;

Description

The Kind property specifies the look of the control and how the control visually responds on user actions (focus, mouse move, clicks etc.).  Generally the Kind property determines how the control is painted.

Modifying this property sets the lfvKind flag in the AssignedValues property and raises the OnChanged event.

The NativeStyle and SkinName properties have a higher priority than the Kind property.

The default value of the Kind property is cxDefaultLookAndFeelKind.


TcxLookAndFeel.MasterLookAndFeel

TcxLookAndFeel

Specifies the imported look and feel.

property MasterLookAndFeel: TcxLookAndFeel;

Description

Every Developer Express control can export its look and feel to other Developer Express controls.  The MasterLookAndFeel property determines the imported look and feel of any Developer Express control.  Any control that imports look and feel of the current control is a listener.  It listens to changes within the current control via the IcxLookAndFeelNotificationListener interface.  Note that a control only listens to its MasterLookAndFeel property when its AssignedValues property is not set.

The IcxLookAndFeelNotificationListener interface listens for two events:

•	Any look and feel property change via the MasterLookAndFeelChanged method.

•	The TcxLookAndFeel class instance destruction via the MasterLookAndFeelDestroying method.

Listener controls reflect all changes within the current control.  If an imported TcxLookAndFeel class instance is destroyed, a listener control obtains its look and feel from the cxDefaultLookAndFeelKind, cxDefaultLookAndFeelNativeStyle, and cxDefaultLookAndFeelSkinName global constants.


TcxLookAndFeel.NativeStyle

TcxLookAndFeel          See Also

Determines whether to use the native windows style for control painting.

property NativeStyle: Boolean;

Description

Set this property to True to paint the control using the native windows style.  Otherwise, the Kind or SkinName property specifies the paint style for the control.

Modifying the NativeStyle property sets the lfvNativeStyle flag in the AssignedValues property and raises the OnChanged event.

The NativeStyle property has a higher priority than the Kind or SkinName property.

Note:	The NativeStyle property is currently only supported for the Windows® XP operating system.

The default value of the NativeStyle property is cxDefaultLookAndFeelNativeStyle.


TcxLookAndFeel.Painter

TcxLookAndFeel

Provides access to the control painter.

property Painter: TcxCustomLookAndFeelPainterClass;

Description

Every TcxLookAndFeel class instance has a painter to paint the control according to the look and feel settings.  To access the painter use the Painter property.

ReadOnly Property


TcxLookAndFeel.SkinName

TcxLookAndFeel          See Also

Specifies the name of a skin to be used for control painting.

type

  TdxSkinName = type string;

property SkinName: TdxSkinName;

Description

Assigning an empty string to the SkinName property indicates that skin support is disabled for the control.

Modifying the SkinName property sets the lfvSkinName flag in the AssignedValues property and raises the OnChanged event.

The SkinName property has a higher priority than the Kind property, but it can be overridden by the NativeStyle property.

The default value of the SkinName property is cxDefaultLookAndFeelSkinName.


TcxLookAndFeel.Create

TcxLookAndFeel

Creates an instance of the TcxLookAndFeel class and the list to hold potential listener controls.

procedure Create(AOwner: TPersistent); override;


TcxLookAndFeel.Destroy

TcxLookAndFeel

Destroys an instance of the TcxLookAndFeel class.

procedure Destroy; override;

Description

This method does the following:

•	notifies all listener controls via the IcxLookAndFeelNotificationListener.MasterLookAndFeelDestroying method;

•	destroys the list of listener controls;

•	destroys the TcxLookAndFeel class instance.


TcxLookAndFeel.Reset

TcxLookAndFeel

Resets look and feel properties.

procedure Reset;

Description

This method clears all flags in the AssignedValues property.


TcxLookAndFeel.OnChanged

TcxLookAndFeel

Occurs on any property change of the TcxLookAndFeel class.

Unit

cxLookAndFeels

type

  TcxLookAndFeelValue = (lfvKind, lfvNativeStyle, lfvSkinName);

  TcxLookAndFeelValues = set of TcxLookAndFeelValue;

  TcxLookAndFeelChangedEvent = procedure(Sender: TcxLookAndFeel; AChangedValues: TcxLookAndFeelValues) of object;

property OnChanged: TcxLookAndFeelChangedEvent;

Description

The OnChanged event occurs every time any property of the TcxLookAndFeel class is changed.


TcxLookAndFeelController
 TcxLookAndFeelController Object

Hierarchy          Properties          Methods

Represents a component providing a convenient way to manipulate common look and feel settings for all Developer Express controls (TcxControl descendants) at design time.

Unit

cxLookAndFeels

TcxLookAndFeelController = class(TComponent, IcxLookAndFeelNotificationListener)

Description

The default look and feel of any TcxControl descendant is determined by the root look and feel.  The root look and feel is a TcxLookAndFeel class instance that is created on application startup.  You can access it at runtime via the RootLookAndFeel global function.  The default values of the root look & feel’s Kind, NativeStyle, and SkinName properties are specified by the cxDefaultLookAndFeelKind, cxDefaultLookAndFeelNativeStyle, and cxDefaultLookAndFeelSkinName global constants, respectively.

To customize the root look and feel settings at design time, use the TcxLookAndFeelController or TdxSkinController component.  Drop any of these components onto a form and access the root look and feel’s Kind, NativeStyle, and SkinName properties via the Object Inspector.

Unlike the TcxLookAndFeelController, the TdxSkinController allows you to apply skins both to forms and any Developer Express controls on them.

TcxControl descendants allow you to set their own look and feel.  The control’s own look and feel is also a TcxLookAndFeel class instance that can be accessed via the control’s LookAndFeel property.


TcxLookAndFeelController Hierarchy
Hierarchy

TComponent

     |


Properties for TcxLookAndFeelController
TcxLookAndFeelController Properties

TcxLookAndFeelController          Legend

In TcxLookAndFeelController

Kind

NativeStyle

SkinName


Methods for TcxLookAndFeelController
TcxLookAndFeelController Methods

TcxLookAndFeelController          Legend

In TcxLookAndFeelController

Create

Destroy


TcxLookAndFeelController.Kind

TcxLookAndFeelController          See Also

Specifies the default look for TcxControl descendants and how they visually respond to user actions (focus, mouse move, clicks etc.) within the current application.

type

  TcxLookAndFeelKind = (lfFlat, lfStandard, lfUltraFlat, lfOffice11);

property Kind: TcxLookAndFeelKind;

Description

The NativeStyle and SkinName properties have a higher priority than the Kind property.

The LookAndFeel.Kind property value of TcxControl descendants overrides the Kind property.

The default value of the Kind property is cxDefaultLookAndFeelKind.


TcxLookAndFeelController.NativeStyle

TcxLookAndFeelController          See Also

Determines whether TcxControl descendants within the current application use the native windows paint style by default.

property NativeStyle: Boolean;

Description

The NativeStyle property has a higher priority than the Kind or SkinName property.

The LookAndFeel.NativeStyle property value of TcxControl descendants overrides the NativeStyle property.

The default value of the NativeStyle property is cxDefaultLookAndFeelNativeStyle.


TcxLookAndFeelController.SkinName

TcxLookAndFeelController          See Also

Specifies the name of a skin to be applied to all TcxControl descendants within the current application by default.

type

  TdxSkinName = type string;

property SkinName: TdxSkinName;

Description

The SkinName property has a higher priority than the Kind property, but it can be overridden by the NativeStyle property.

The LookAndFeel.SkinName property value of TcxControl descendants overrides the SkinName property.

The default value of the SkinName property is cxDefaultLookAndFeelSkinName.


TcxLookAndFeelController.Create

TcxLookAndFeelController

Creates and initializes a TcxLookAndFeelController class instance.

procedure Create(AOwner: TComponent); override;

Description

Use the Create method to instantiate a look and feel controller.  Controllers added in the form designer are created automatically.


TcxLookAndFeelController.Destroy

TcxLookAndFeelController

Destroys an instance of TcxLookAndFeelController class.

procedure Destroy; override;

Description

Do not call Destroy directly in an application.  Instead, call Free.  Free verifies that the TcxLookAndFeelController reference is not nil, and only then calls Destroy.


IcxLookAndFeelNotificationListener
IcxLookAndFeelNotificationListener Interface

Hierarchy          Methods

Unit

cxLookAndFeels

IcxLookAndFeelNotificationListener = interface(IUnknown);

Description

Every Developer Express control can export its look and feel to other Developer Express controls.  The MasterLookAndFeel property of the TcxLookAndFeel class determines the imported look and feel of any Developer Express control.  Any control, which imports the look and feel of the current control, is a listener.  It listens to changes within the current control via the IcxLookAndFeelNotificationListener interface.   Note that a control only listens to its MasterLookAndFeel property when its AssignedValues of the TcxLookAndFeel class property is not set.

The IcxLookAndFeelNotificationListener interface listens for two events:

•	Any look and feel property change via the MasterLookAndFeelChanged method.

•	The TcxLookAndFeel class instance destruction via the MasterLookAndFeelDestroying method.

Listener controls reflect all changes within the current control.  If an imported TcxLookAndFeel class instance is destroyed, a listener control obtains its look and feel from the cxDefaultLookAndFeelKind, cxDefaultLookAndFeelNativeStyle, and cxDefaultLookAndFeelSkinName global constants.


IcxLookAndFeelNotificationListener Hierarchy
Hierarchy

IUnknown

     |


Methods for IcxLookAndFeelNotificationListener
IcxLookAndFeelNotificationListener Methods

IcxLookAndFeelNotificationListener          Legend

In IcxLookAndFeelNotificationListener

GetObject

MasterLookAndFeelChanged

MasterLookAndFeelDestroying


IcxLookAndFeelNotificationListener.GetObject

IcxLookAndFeelNotificationListener

Returns the object implementing this interface.

function GetObject: TObject;

Description

The GetObject method implementing this interface is usually a TcxLookAndFeel or TcxLookAndFeelController class instance.


IcxLookAndFeelNotificationListener.MasterLookAndFeelChanged

IcxLookAndFeelNotificationListener

Notifies all current look and feel listeners that its kind or native style property has changed.

type

  TcxLookAndFeelValue = (lfvKind, lfvNativeStyle, lfvSkinName);

  TcxLookAndFeelValues = set of TcxLookAndFeelValue;

procedure MasterLookAndFeelChanged(Sender: TcxLookAndFeel; AChangedValues: TcxLookAndFeelValues);

Description

The MasterLookAndFeelChanged method is called every time the Kind, NativeStyle, or SkinName property of the current look and feel changes.  This method notifies all current look and feel listeners.  A listener is a TcxControl descendant whose MasterLookAndFeel property is set to the current look and feel.  If this property is not set, the TcxControl descendant listens to the root look and feel.  To determine what properties of the master look and feel has changed, use the AChangedValues parameter.

Note: The look and feel properties of the TcxControl descendants override the master look and feel property settings.


IcxLookAndFeelNotificationListener.MasterLookAndFeelDestroying

IcxLookAndFeelNotificationListener

Notifies all current look and feel listeners that it is being destroyed.

procedure MasterLookAndFeelDestroying(Sender: TcxLookAndFeel);

Description

The MasterLookAndFeelDestroying method is called on current look and feel destruction.  To access the root look and feel at design time, you should use the TcxLookAndFeelController component.  This component notifies all current look and feel listeners.  A listener is a TcxControl control descendant whose MasterLookAndFeel property is set to the current look and feel. If this property is not set, the TcxControl descendant listens to the root look and feel. After the master root look and feel is destroyed, the TcxControl descendant becomes the root look and feel listener. The root look and feel cannot be destroyed.

Note: The look and feel properties of TcxControl descendants override the master look and feel property settings.


RootLookAndFeel
RootLookAndFeel Function

Provides access to the root look and feel at runtime.

Unit

cxLookAndFeels

function RootLookAndFeel: TcxLookAndFeel;

Description

The RootLookAndFeel method enables you to access to the root look and feel at runtime.  The root look and feel is a TcxLookAndFeel class instance that is created on application startup.  The default values of the root look & feel’s Kind, NativeStyle, and SkinName properties are specified by the cxDefaultLookAndFeelKind, cxDefaultLookAndFeelNativeStyle, and cxDefaultLookAndFeelSkinName global constants, respectively.

TcxControl descendants allow you to set their own look and feel.  The control’s look and feel is also a TcxLookAndFeel class instance that can be accessed via the control’s LookAndFeel property.


cxDefaultLookAndFeelKind constant
cxDefaultLookAndFeelKind global constant

Determines the default value of the Kind property for all look and feel classes.

Unit

cxLookAndFeels

cxDefaultLookAndFeelKind = lfUltraFlat;


cxDefaultLookAndFeelNativeStyle constant
cxDefaultLookAndFeelNativeStyle global constant

Determines the default value of the NativeStyle property for all look and feel classes.

Unit

cxLookAndFeels

cxDefaultLookAndFeelNativeStyle = False;


cxDefaultLookAndFeelSkinName constant
cxDefaultLookAndFeelSkinName global constant

Determines the default value of the SkinName property for all look and feel classes.

Unit

cxLookAndFeels

cxDefaultLookAndFeelSkinName = '';


cxUseSkins constant
cxUseSkins global constant

See Also

Determines whether skin support is enabled in an application.

Unit

cxLookAndFeels

cxUseSkins: Boolean = True;


TcxLookAndFeelKind
TcxLookAndFeelKind type

Determines the manner in which a control is painted.

Unit

cxLookAndFeels

type

  TcxLookAndFeelKind = (lfFlat, lfStandard, lfUltraFlat, lfOffice11);

Description

There are four kinds of control painting:

Kind	Description
lfFlat
lfStandard
lfUltraFlat
lfOffice11