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


cxControls Unit Overview
cxControls Unit

Classes

TcxControl


TcxControl
TcxControl Object

Hierarchy          Properties          Methods

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


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.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 scroll bar, if any) size from the size of the area occupied by a control (returned by the Bounds property).

ReadOnly Property


TcxControl.IsFocused

TcxControl

Indicates whether a control has focus.

property IsFocused: Boolean;

Description

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

ReadOnly Property


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 scroll bars for the control and initializes its properties and variables.  The canvas is provided by the TcxCanvas object designed by Developer Express to represent 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.


Legend

 Protected

 Published

 ReadOnly


cxSSHeaders Unit Overview
cxSSHeaders Unit

Classes

TcxSSHeader

Other Types

TcxSSHeaderType

TcxSSSize


TcxSSHeader
TcxSSHeader Object

Hierarchy          Properties          Methods

Represents either a row or the column header panel of a worksheet.

Unit

cxSSHeaders

TcxSSHeader = class(TObject)

Description

The TcxSSHeader object represents a header panel, which displays column letters at the top of a worksheet or row numbers on the left side of it.  The TcxSSHeader object has a Kind property to specify whether the TcxSSHeader object represents a column or the row header panel.  The TcxSSHeader object contains properties that allow you to manipulate the default size of headers within the panel, the size and visibility of a particular header (and corresponding rows or columns).


TcxSSHeader Hierarchy
Hierarchy

TObject


Properties for TcxSSHeader
TcxSSHeader Properties

TcxSSHeader          Legend

In TcxSSHeader

DefaultSize

Kind

Lock

OwnerSheet

Size

Visible


Methods for TcxSSHeader
TcxSSHeader Methods

TcxSSHeader          Legend

In TcxSSHeader

Create

Destroy


TcxSSHeader.DefaultSize

TcxSSHeader          See Also

Specifies the default size of headers within the panel.

property DefaultSize: TcxSSSize;

Description

The DefaultSize property is used to specify the default size of headers within the panel.  Size implies column header width and row height.  The size is set in pixels.  You can also change the size of a particular header using the Size property.

The following sample code demonstrates how to change the default size of column and row headers. The code simply increments these values by 10.

The following image shows the initial state of the spreadsheet.

// Delphi

var

  AColHeader, ARowHeader: TcxSSHeader;

//...

  AColHeader := cxSpreadSheetBook1.ActiveSheet.Cols;

  ARowHeader := cxSpreadSheetBook1.ActiveSheet.Rows;

  AColHeader.DefaultSize := AColHeader.DefaultSize + 10;

  ARowHeader.DefaultSize := ARowHeader.DefaultSize + 10;

// C++ Builder

  TcxSSHeader *colHeader, *rowHeader;

  colHeader = cxSpreadSheetBook1->ActiveSheet->Cols;

  rowHeader = cxSpreadSheetBook1->ActiveSheet->Rows;

  colHeader->DefaultSize += 10;

  rowHeader->DefaultSize += 10;

The following image illustrates how changing the default header size affects the spreadsheet’s look & feel.


TcxSSHeader.Kind

TcxSSHeader          See Also

Gets a value indicating whether the header represents a column or the row header panel.

type

  TcxSSHeaderType = (htCol, htRow);

property Kind: TcxSSHeaderType;

Description

The Kind property is used to determine whether a TcxSSHeader class instance represents a column or the row header panel.  This value is initialized in the constructor, when the header is created by a workbook control for its Cols and Rows properties.

The possible values for the Kind property are as follows.

Value	Description
htCol	The header represents a column header.
htRow	The header represents a row header.

ReadOnly Property


TcxSSHeader.Lock

TcxSSHeader          See Also

Specifies whether to prevent changes to a specific column or row.

property Lock[AIndex:Integer]: Boolean;

Description

Set the Lock property to True to prevent the column or row specified by the AIndex parameter from being modified.  This means you cannot modify its size and visibility.  Set this property to False to enable column or row modifications.

If the header is a column header (the Kind property of the TcxSSHeader object is htCol), the AIndex parameter represents the column index.  If the header is a row header (the Kind property of the TcxSSHeader object is htRow), the AIndex parameter represents the row index.  Indexes are zero-based.

The following line of code prevents the B column from being modified (column index is 1).

// Delphi

cxSpreadSheetBook1.Pages[0].Cols.Lock[1] := True;

// C++ Builder

cxSpreadSheetBook1->Pages[0]->Cols->Lock[1] = true;


TcxSSHeader.OwnerSheet

TcxSSHeader

Provides access to the worksheet that contains the header panel.

property OwnerSheet: TObject;

Description

Read the OwnerSheet property to obtain the worksheet to which the header panel belongs.  You should convert the returned value to type TcxSSBookSheet in order to access the object representing the worksheet.

ReadOnly Property


TcxSSHeader.Size

TcxSSHeader          See Also

Specifies the size of a specific header element.

property Size[AIndex: Integer]: TcxSSSize;

Description

Use the Size property to specify the desired size of the header element specified by the AIndex parameter.  The Size property can represent either the width of a column header element or the height of a row header element.  The meaning of the Size property value depends on the Kind property value.  The size is set in pixels.  The index specifying the header is zero-based.

You can set the default size for all headers within the panel via the DefaultSize property.

Note: The Size property returns a zero value for hidden headers.  Use the Visible property to control the visibility of specific headers.

The image below displays the default look & feel of the worksheet.

The following sample code changes the size of the B column header (index is 1).

// Delphi

var AHeader: TcxSSHeader;

//...

AHeader := cxSpreadSheetBook1.ActiveSheet.Cols;

AHeader.Size[1] := 50;

// C++ Builder

TcxSSHeader *header;

header = cxSpreadSheetBook1->ActiveSheet->Cols;

header->Size[1] = 50;

Note: The following calls are identical since the Size property is default for the TcxSSHeader object:

AHeader.Size[1] := 50;

and

header[1] := 50; (this is true for Delphi only)


TcxSSHeader.Visible

TcxSSHeader          See Also

Specifies whether a specific row (or column) of a worksheet is visible.

property Visible[AIndex:Integer]: Boolean;

Description

Use the Visible property to specify the visibility of a specific row or column specified by the AIndex parameter.

The AIndex parameter specifies the zero-based column index, if the TcxSSHeader object represents a column header.  In this instance, if the Visible property is set to False, the column specified by the AIndex parameter is not displayed within the worksheet.

The AIndex parameter specifies the zero-based row index if the TcxSSHeader object represents a row header.  In this instance, if the Visible property is set to False, the row specified by the AIndex parameter is not displayed within the worksheet.

The Size property of the TcxSSHeader object returns 0 for invisible columns and rows.

The following sample code hides the A column (its index is 0).  The worksheet’s look & feel before code execution is displayed in the image below.

// Delphi

var AHeader: TcxSSHeader;

//...

AHeader := cxSpreadSheetBook1.ActiveSheet.Cols;

AHeader.Visible[0] := False;

// Ñ++ Builder

TcxSSHeader *header;

header = cxSpreadSheetBook1->ActiveSheet->Cols;

header->Visible[0] = false;


TcxSSHeader.Create

TcxSSHeader

Creates a TcxSSHeader object instance with specific settings.

procedure Create(AOwner: TObject; AKind: TcxSSHeaderType; ADefSize: Integer); virtual;

Description

The Create method is used to create a new TcxSSHeader class instance with specific settings.

The AOwner parameter determines the owner of the header.  The AKind parameter specifies the type of header panel (column or row header panel).  The ADefSize parameter specifies the DefaultSize property value.


TcxSSHeader.Destroy

TcxSSHeader

Destroys a TcxSSHeader object instance.

procedure Destroy; override;

Description

The Destroy method is used to destroy a TcxSSHeader object instance and release any allocated memory. The Destroy method deallocates any resources used and if it fails, an EClearError exception with message "Error clear header data" is raised.

Note that you should avoid using the Destroy method whenever possible, instead you should use the Free method to correctly deallocate any resources used.


TcxSSHeaderType
TcxSSHeaderType type

Indicates a header type.

Unit

cxSSHeaders

TcxSSHeaderType = (htCol, htRow);

Description

TcxSSHeaderType indicates the header type.

Value	Description
HtCol	The header represents a column header.
HtRow	The header represents a row header.


TcxSSSize
TcxSSSize type

Represents an integer which determines the size of a header element.

Unit

cxSSHeaders

TcxSSSize = Word;

Description

Represents an integer used for header size measurement.  If a header element is a column header (its TcxSSHeaderType type is set to htCol), TcxSSSize defines its width; otherwise it defines its height.


cxSSheet Unit Overview
cxSSheet Unit

Classes

TcxCustomSpreadSheetBook

TcxSpreadSheet

TcxSpreadSheetBook

TcxSSBookSheet

TcxSSCellObject

TcxWorkBookSubControl


TcxCustomSpreadSheetBook
TcxCustomSpreadSheetBook Object

Hierarchy          Properties          Methods          Events

The TcxCustomSpreadSheetBook object is the base class for objects that represent workbooks (the TcxSpreadSheetBook component) or separate worksheets (the TcxSpreadSheet component).

Unit

cxSSheet

TcxCustomSpreadSheetBook = class(TcxControl)

Description

The TcxCustomSpreadSheetBook object is used as the base class when defining an object representing a workbook or a separate worksheet.  Do not create instances of the TcxCustomSpreadSheetBook object directly.  To place a workbook or a worksheet onto a form, use TcxCustomSpreadSheetBook descendants, such as the TcxSpreadSheetBook or TcxSpreadSheet component.

The TcxCustomSpreadSheetBook object implements the basic functionality of the TcxSpreadSheetBook and TcxSpreadSheet components and contains properties and methods published in its direct descendants.


TcxCustomSpreadSheetBook Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |


Properties for TcxCustomSpreadSheetBook
TcxCustomSpreadSheetBook Properties

TcxCustomSpreadSheetBook          Legend

In TcxCustomSpreadSheetBook

ActiveCell

ActivePage

ActiveSheet

AutoRecalc

BufferedPaint

ColHeaderHeight

DefaultColWidth

DefaultRowHeight

DefaultStyle

DefinedNames

ExcelProtectionStyle

GridColor

HeaderColor

HeaderFont

HideSelection

History

PageCount

Pages

PageVisible

PainterType

Palette

Precision

Protected

R1C1ReferenceStyle

ReadOnly

RowHeaderWidth

RowsAutoHeight

ScrollBars

SelectionColor

SelectionRect

ShowCaptionBar

ShowFormulas

ShowGrid

ShowHeaders

Derived from TcxControl

BorderStyle

Bounds

Canvas

ClientBounds

FocusOnClick

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxCustomSpreadSheetBook
TcxCustomSpreadSheetBook Methods

TcxCustomSpreadSheetBook          Legend

In TcxCustomSpreadSheetBook

BeginUpdate

CellsNameByRef

ClearAll

Create

DefineName

DefineNameEx

DeleteName

Destroy

EndUpdate

HasRectName

HitTest

LoadFromFile

LoadFromStream

Recalc

SaveToFile

SaveToStream

UpdateControl

Derived from TcxControl

InvalidateRect


Events for TcxCustomSpreadSheetBook
TcxCustomSpreadSheetBook Events

TcxCustomSpreadSheetBook          Legend

In TcxCustomSpreadSheetBook

OnActiveCellChanging

OnActiveSheetChanging

OnAfterCalculation

OnCellChange

OnChangeColVisible

OnChangeRowVisible

OnChangeSheetCaption

OnClearCells

OnCustomPaint

OnEditing

OnEndEdit

OnFormatCells

OnHistoryChanged

OnMergeCells

OnProgress

OnResizeCol

OnResizeRow

OnSetSelection

OnSheetPopupMenu

OnCaptionPopupMenu

OnTopLeftChanging


TcxCustomSpreadSheetBook.ActiveCell

TcxCustomSpreadSheetBook

Specifies the location of the active cell within a worksheet.

property ActiveCell: TPoint;

Description

Use the ActiveCell property to get or set active cell position within the active worksheet.  This property is of type TPoint so you can read/set its X and Y fields, which respectively specify row and column indexes of the active cell.  Row and column indexes are zero-based.

The following sample code increments the column index of the active cell.  This forces focus to move one cell to the right.

// Delphi

var APoint: TPoint;

//...

APoint.X := cxSpreadSheetBook1.ActiveCell.X;

APoint.Y := cxSpreadSheetBook1.ActiveCell.Y;

APoint.X := APoint.X + 1;

cxSpreadSheetBook1.ActiveCell := APoint;

// C++ Builder

TPoint point;

//...

point.x = cxSpreadSheetBook1->ActiveCell.x;

point.y = cxSpreadSheetBook1->ActiveCell.y;

point.x++;

cxSpreadSheetBook1->ActiveCell = point;


TcxCustomSpreadSheetBook.ActivePage

TcxCustomSpreadSheetBook          See Also

Specifies the index of the active worksheet.

property ActivePage: Integer;

Description

The ActivePage property specifies the index of the active worksheet.  The index of the first worksheet is 0.  Read the ActivePage property value to obtain the index of the active worksheet.  Set this property to activate a specific sheet within a workbook. You can also set the active page via your mouse by clicking the corresponding tab or using the navigation buttons located within the caption bar.  Use the ShowCaptionBar property to show/hide the caption bar.

The following sample code navigates forward through workbook pages.  When the last worksheet is reached, the first worksheet is activated.

// Delphi

if cxSpreadSheetBook1.ActivePage < cxSpreadSheetBook1.PageCount - 1 then

  cxSpreadSheetBook1.ActivePage := cxSpreadSheetBook1.ActivePage + 1

else

  cxSpreadSheetBook1.ActivePage := 0;

// C++ Builder

if (cxSpreadSheetBook1->ActivePage < cxSpreadSheetBook1->PageCount - 1)

  cxSpreadSheetBook1->ActivePage++;

else

  cxSpreadSheetBook1->ActivePage = 0;


TcxCustomSpreadSheetBook.ActiveSheet

TcxCustomSpreadSheetBook          See Also

Gets a TcxSSBookSheet class instance corresponding to the active worksheet.

property ActiveSheet: TcxSSBookSheet;

Description

Use the ActiveSheet property to obtain access to the active workbook sheet.  This property returns a reference to the TcxSSBookSheet class instance containing properties and methods that allow you to manipulate the worksheet.  Other worksheets contained in the workbook can be accessed using the Pages property.

ReadOnly Property


TcxCustomSpreadSheetBook.AutoRecalc

TcxCustomSpreadSheetBook          See Also

Specifies whether all workbook formulas are calculated automatically.

property AutoRecalc: Boolean;

Description

Calculation is the process of computing formula values and then displaying resulting values in the cell that contains the formula.  Use the AutoRecalc property to control the process of calculation.  If the AutoRecalc property is set to True, a workbook automatically recalculates all cells depending on the cells containing the modified values.  If this property is False, automatic calculation is not performed.


TcxCustomSpreadSheetBook.BufferedPaint

TcxCustomSpreadSheetBook

Determines whether the spreadsheet is rendered directly to the window or painted to an in-memory bitmap first.

property BufferedPaint: Boolean;

Description

When the BufferedPaint property is False, the spreadsheet paints itself directly to the window. When the BufferedPaint property is True, the spreadsheet paints itself to an in-memory bitmap that is then used to paint the window. Buffered paint reduces the amount of flicker when the control repaints, but is more memory intensive.


TcxCustomSpreadSheetBook.ColHeaderHeight

TcxCustomSpreadSheetBook          See Also

Determines the height of the column header panel.

property ColHeaderHeight: Integer;

Description

The ColHeaderHeight property determines the column header panel’s height in pixels.  Use this property to set the desired height for the column header in all workbook sheets. The default look & feel of the column header panel is displayed in the image below.  The ColHeaderHeight property is equal to 20 by default.

Use the following line of code to set the height of the column header panel to 50 pixels.  The result is displayed in the image below.

// Delphi

cxSpreadSheetBook1.ColHeaderHeight := 50;

// C++ Builder

cxSpreadSheetBook1->ColHeaderHeight = 50;


TcxCustomSpreadSheetBook.DefaultColWidth

TcxCustomSpreadSheetBook          See Also

Specifies the default columns width.

property DefaultColWidth: TcxSSSize;

Description

Use the DefaultColWidth property to specify the default width for workbook columns.  You can also change the default column width of a particular sheet.  Simply use the DefaultSize property of the TcxSSHeader object corresponding to the column header panel of the desired sheet.  Utilize the TcxSSBookSheet.Cols property to obtain a TcxSSHeader class instance for a specific worksheet.

The image below displays the default look & feel of worksheets.  The DefaultColWidth property is 85 by default.

Write the following code to change the default column width of the first workbook and modify the default column width of the second worksheet.

// Delphi

cxSpreadSheetBook1.DefaultColWidth := 50;

cxSpreadSheetBook1.Pages[0].Cols.DefaultSize := 100;

// C++ Builder

cxSpreadSheetBook1->DefaultColWidth = 50;

cxSpreadSheetBook1->Pages[0]->Cols->DefaultSize = 100;

The worksheets will now have the look & feel displayed below:


TcxCustomSpreadSheetBook.DefaultRowHeight

TcxCustomSpreadSheetBook          See Also

Specifies the default row height.

property DefaultRowHeight: TcxSSSize;

Description

Use the DefaultRowHeight property to specify the default height for workbook rows.  You can also change the default row height of a specific sheet.  Simply use the DefaultSize property of the TcxSSHeader object corresponding to the row header panel of the desired sheet.

The image below displays the default look & feel of worksheets.  The DefaultRowHeight property is 20 by default.

Write the following code to change the default row height of the first workbook and modify the default row height of the second worksheet.

// Delphi

cxSpreadSheetBook1.DefaultRowHeight := 40;

cxSpreadSheetBook1.Pages[1].Rows.DefaultSize := 15;

// C++ Builder

cxSpreadSheetBook1->DefaultRowHeight = 40;

cxSpreadSheetBook1->Pages[1]->Rows->DefaultSize = 15;


TcxCustomSpreadSheetBook.DefaultStyle

TcxCustomSpreadSheetBook          See Also

Contains the default cell style.

property DefaultStyle: TcxSSCellStyle;

Description

Read the DefaultStyle property to obtain access to the workbook default cell style. The default style is initially applied to all workbook cells.  You can set the style for individual cells via the cell’s Style property.  To get a reference to a cell object, call the TcxSSBookSheet.GetCellObject method.

The following code changes the default font settings:

•	font size to 10;

•	font color index to 30.

// Delphi

var

  AStyle: TcxSSCellStyle;

//...

  AStyle := cxSpreadSheetBook1.DefaultStyle;

  with AStyle do

  begin

    AStyle.Font.Size := 10;

    AStyle.Font.FontColor := 30;

  end;

// C++ Builder

TcxSSCellStyle * style;

//...

  style = cxSpreadSheetBook1.DefaultStyle;

  style.Font.Size = 10;

  style.Font.FontColor = 30;

ReadOnly Property


TcxCustomSpreadSheetBook.DefinedNames

TcxCustomSpreadSheetBook          See Also

Represents a collection of defined names within the workbook or worksheet.

property DefinedNames: TcxSSNamesDef;

The DefinedNames property stores named cells.  You can call the DefineName method to give a specific cell or cell range a name and then use it in formulas.

ReadOnly Property


TcxCustomSpreadSheetBook.ExcelProtectionStyle

TcxCustomSpreadSheetBook          See Also

Specifies the protection style for a spreadsheet.

property ExcelProtectionStyle: Boolean;

Description

The ExcelProtectionStyle property allows a spreadsheet to be protected (as in MS Excel).  If the ExcelProtectionStyle property is set to True, the spreadsheet’s Protected property can be set to True to lock the spreadsheet, preventing any changes to cells.  To unlock a specific cell, set its Style.Locked property to False.  If the ExcelProtectionStyle property is set to False the cell’s Style.ReadOnly property can be used to specify whether this cell is editable.  To set the read-only status for an individual worksheet, or all worksheets within a spreadsheet control, use the worksheet’s ReadOnly property, or the spreadsheet control’s ReadOnly property.

The default value of the ExcelProtectionStyle property is True.


TcxCustomSpreadSheetBook.GridColor

TcxCustomSpreadSheetBook

Specifies the color for cell dividers.

property GridColor: TColor;

Description

The GridColor property determines the color of grid lines.  You can set GridColor to one of the constants defined in the Graphics unit (such as clGray), or to an explicit RGB integer value.

The default value of this property is clBtnShadow.


TcxCustomSpreadSheetBook.HeaderColor

TcxCustomSpreadSheetBook

Specifies the color of the column and row header panels.

property HeaderColor: TColor;

Description

Use the HeaderColor property to set the color of the column and row header panels by setting it to one of the constants defined in the Graphics unit (such as clGray) or to an explicit RGB integer value.


TcxCustomSpreadSheetBook.HeaderFont

TcxCustomSpreadSheetBook          See Also

Specifies the font for header panels.

property HeaderFont: TFont;

Description

Use the HeaderFont property to customize the font used to display text for header panels.  This property returns a reference to the TFont object.  This object allows you to manage font type, its size, style and character set.

The image below displays the default look & feel of worksheets.

The following code changes the typeface and size of font used to display header panel text and makes it bold and italic.

// Delphi

with cxSpreadSheetBook1.HeaderFont do

  begin

    Name := ’Verdana’;

    Size := 12;

    Style := [fsBold, fsItalic];

  end;

// C++ Builder

cxSpreadSheetBook1->HeaderFont->Name = "Verdana";

cxSpreadSheetBook1->HeaderFont->Size = 12;

cxSpreadSheetBook1->HeaderFont->Style = TFontStyles()<< fsBold << fsItalic;


TcxCustomSpreadSheetBook.HideSelection

TcxCustomSpreadSheetBook          See Also

Specifies whether the selection is hidden upon loss of focus.

property HideSelection: Boolean;

Description

If the HideSelection property is True, selection is hidden when a workbook loses focus. If the property is False, selection remains within the workbook.


TcxCustomSpreadSheetBook.History

TcxCustomSpreadSheetBook          See Also

Specifies the history of actions for a spreadsheet control.

property History: TcxSpreadSheetHistory;

Description

The History object stores lists of actions that you can undo and redo.  The MaxActions property defines the maximum number of ‘undo’ actions.  The TcxSpreadSheetHistory object stores two lists with the actions to undo or redo.  To undo or redo the last action you should programmatically call the Undo or Redo method respectively.  A user can perform these by pressing the Ctrl+Z or Ctrl+Y keystrokes respectively.

Every action such as cell content or style modification, formatting, inserting, deleting, clearing cells, merging/splitting cells and sorting cell values is stored in the history and can be undone.  For instance, when you change the border style of a cell, the spreadsheet creates a new entry in the UndoActions list of the History object.  This action can be undone either by pressing the Ctrl+Z shortcut or by calling the Undo method of the History object.  The TcxSpreadSheetHistory object allows you to record several simple actions and present them as a single complex action.  Thus, only one item appears in the ‘undo’ list.  When you undo/redo a complex action this invokes the ‘undo’/’redo’ operations for all actions represented by the complex action.

When the history is changed the spreadsheet control generates the OnHistoryChanged event.

ReadOnly Property


TcxCustomSpreadSheetBook.PageCount

TcxCustomSpreadSheetBook          See Also

Specifies the total number of sheets within a workbook.

property PageCount: Integer;

Description

Use the PageCount property to specify the total number of sheets within a workbook.  The names of sheets appear on tabs within the caption bar at the bottom of the workbook window.

When setting the PageCount property to a value greater than the total number of workbook sheets, new worksheets are added to the workbook until the total number of worksheets equals the PageCount property value.

When setting the PageCount property to a value less than the total number of workbook sheets, worksheets are deleted from the workbook until the total number of worksheets equals the PageCount property value.  The first worksheet to be deleted is the last sheet of the workbook (it has the highest index).


TcxCustomSpreadSheetBook.Pages

TcxCustomSpreadSheetBook          See Also

Returns a specified workbook sheet.

property Pages[AIndex:Integer]: TcxSSBookSheet;

Description

Use the Pages property to access a specific sheet in a workbook.  The sheet index is specified by the AIndex parameter.  Each worksheet is represented by a TcxSSBookSheet object instance.  You can read the PageCount property to obtain the total number of all worksheets within a workbook.

The following sample code changes the caption of all worksheets.

// Delphi

var i: Integer;

//...

for i := 0 to cxSpreadSheetBook1.PageCount - 1 do

begin

  with cxSpreadSheetBook1.Pages[i] do

  begin

    Caption := 'Page ' + IntToStr(i);

  end;

end;

// C++ Builder

for (int i = 0; i < cxSpreadSheetBook1->PageCount; i++)

  cxSpreadSheetBook1->Pages[i]->Caption = "Page " + IntToStr(i);

ReadOnly Property


TcxCustomSpreadSheetBook.PageVisible

TcxCustomSpreadSheetBook          See Also

Determines whether a specific page is visible.

property PageVisible[APage: Word]: Boolean;

Description

Use the PageVisible property to specify the visibility of individual pages.  The APage parameter defines the zero-based index of the required page.  The PageCount property specifies the total number of pages within a book.  To access individual page properties, use the Pages member.


TcxCustomSpreadSheetBook.PainterType

TcxCustomSpreadSheetBook

Specifies workbook drawing style.

property PainterType: TcxSSPainterType;

Description

Use the PainterType property to specify the drawing style used to draw a workbook.  Possible values for the PainterType property include:

MS Office® 97 -

MS Office® XP -

If the PainterType property is ptCustom, the OnCustomPaint event fires.  Derive your own class implementing custom worksheet drawing from the TcxSheetPainter class.  Pass a reference to this class as a parameter of the OnCustomPaint event in order to implement custom drawing.


TcxCustomSpreadSheetBook.Palette

TcxCustomSpreadSheetBook

Contains the book palette.

type

  PcxExcelPalette = ^TcxExcelPalette;

property Palette: PcxExcelPalette;

Description

The palette contains all colors that are used within the book.

The following code changes the first color of the book palette.

// Delphi

  cxSpreadSheetBook1.Palette[1] := clRed;

  cxSpreadSheetBook1.UpdateControl;

// C++ Builder

  cxSpreadSheetBook1->Palette[1] = clRed;

  cxSpreadSheetBook1->UpdateControl();

ReadOnly Property


TcxCustomSpreadSheetBook.Precision

TcxCustomSpreadSheetBook

Identifies the precision for representing numerical values within a spreadsheet.

property Precision: Byte;

Description

The Precision property defines the number of digits to the right of the decimal point when displaying the number.  However, when you edit the number it is displayed with all digits which have been entered.


TcxCustomSpreadSheetBook.Protected

TcxCustomSpreadSheetBook          See Also

Specifies whether changes can be made to the spreadsheet control’s content.

property Protected: Boolean;

Description

Set the Protected property to True to prevent any changes in the worksheets of the spreadsheet control.

The default value of the Protected property is False.


TcxCustomSpreadSheetBook.R1C1ReferenceStyle

TcxCustomSpreadSheetBook

property R1C1ReferenceStyle: Boolean;

Description

Set the R1C1ReferenceStyle property to True to enable R1C1 reference style; or to False to enable A1 reference style.

When using R1C1 reference style, both rows and columns on the worksheet are numbered. In R1C1 style, the ExpressSpreadSheet control indicates the location of a cell with letter "R" followed by a row number and letter "C" followed by a column number.

The default style is A1 Reference Style. Rows are represented by numbers, columns – by letters:

If the R1C1 Reference Style is applied then both rows and columns are represented by numbers.


TcxCustomSpreadSheetBook.ReadOnly

TcxCustomSpreadSheetBook          See Also

Specifies the read-only status of a spreadsheet control.

property ReadOnly: Boolean;

Description

Use the ReadOnly property to set the read-only status of an entire spreadsheet control.  Setting it to True prevents a user from editing cells.

To set the read-only status for an individual worksheet or a cell, use the worksheet’s ReadOnly property, or the cell’s Style.ReadOnly property, respectively.  To access a specific worksheet, use the spreadsheet control’s ActiveSheet or Pages property and a worksheet control’s Sheet property.

Note:	The ReadOnly properties are in effect only if the spreadsheet control’s ExcelProtectionStyle property is set to False.

The default value of the ReadOnly property is False


TcxCustomSpreadSheetBook.RowHeaderWidth

TcxCustomSpreadSheetBook          See Also

Determines the width of a row header.

property RowHeaderWidth: Integer;

Description

The RowHeaderWidth property determines row header width in pixels.  Use this property to set the desired width of a row header for all workbook sheets. The default look & feel of the row header panel is displayed in the image below.  The RowHeaderWidth property is equal to 85 by default.

Use the following line of code to set the width of the row header panel to 50 pixels.  The result is displayed in the image below.

// Delphi

cxSpreadSheetBook1.RowHeaderWidth := 50;

// C++ Builder

cxSpreadSheetBook1->RowHeaderWidth = 50;


TcxCustomSpreadSheetBook.RowsAutoHeight

TcxCustomSpreadSheetBook

Specifies whether the height of rows will be automatically adjusted to completely display their content.

property RowsAutoHeight: Boolean;

Description

Set the RowsAutoHeight property to False to draw rows with the height specified by the TcxSSHeader.Size property. Otherwise the row’s height will be recalculated depending upon the font type.

Note: setting the RowsAutoHeight property to False will give a significant improvement in terms of performance when loading data into the spreadsheet.

The default value of the RowsAutoHeight property is True.


TcxCustomSpreadSheetBook.ScrollBars

TcxCustomSpreadSheetBook

Determines whether the memo control has scroll bars.

property ScrollBars: TScrollStyle;

Description

Use the ScrollBars property to incorporate horizontal or vertical scroll bars in the ExpressSpreadSheet.


TcxCustomSpreadSheetBook.SelectionColor

TcxCustomSpreadSheetBook

Specifies workbook selection color

property SelectionColor: TColor;

Description

Read this property to discover which color is used to represent the selection rectangle of the workbook. Write the property to set color for the workbook’s selection rectangle.


TcxCustomSpreadSheetBook.SelectionRect

TcxCustomSpreadSheetBook         See Also

Specifies the boundaries of the selected cell range within the worksheet.

property SelectionRect: TRect;

Description

Use the SelectionRect property to select a range of cells in the worksheet.  This property is of type TRect and thus can represent either the top, left, right and bottom boundaries of the selected area or the coordinates of the top-left and bottom-right cells of the selection using row and column indexes.  As these indexes are zero-based, the B2:C4 selection range must be presented as Rect(1,1,2,3).

By accessing the SelectionRect property you actually get/set the SelectionRect property of the TcxSSBookSheet instance which represents a worksheet itself.


TcxCustomSpreadSheetBook.ShowCaptionBar

TcxCustomSpreadSheetBook          See Also

Specifies whether the caption bar is visible.

property ShowCaptionBar: Boolean;

Description

Use the ShowCaptionBar property to specify whether the caption bar is displayed within the workbook window.  The caption bar is a rectangular area at the bottom of the workbook window.  The caption bar contains tabs that display sheet captions and navigation buttons to the left of these tabs (they are used to navigate through sheets).

If the ShowCaptionBar property is set to True, the caption bar is displayed at the bottom of the workbook window.

If the ShowCaptionBar property is set to False, the caption bar is not displayed.


TcxCustomSpreadSheetBook.ShowFormulas

TcxCustomSpreadSheetBook          See Also

Specifies whether to display formulas in cells.

property ShowFormulas: Boolean;

Description

Use the ShowFormulas property to specify whether to display formulas in cells instead of resulting values.  If this property is False, all cells containing formulas display resulting values of the contained formulas.  Set the ShowFormulas property to True to force these cells to display just the formulas they contain.

The image below displays a worksheet in which cell B2 contains a formula that subtracts the values of cells A2 and B1 from the value of cell A1.  The ShowFormulas property is True.

After setting the ShowFormulas property to False, the resulting value will be displayed within cell B2.

The default value is False.


TcxCustomSpreadSheetBook.ShowGrid

TcxCustomSpreadSheetBook          See Also

Specifies whether to display gridlines within worksheets.

property ShowGrid: Boolean;

Description

Use the ShowGrid property to specify whether cell gridlines are displayed within workbook worksheets.  If the ShowGrid property is True, cell gridlines are displayed within worksheets.

Set this property to False to hide cell gridlines.


TcxCustomSpreadSheetBook.ShowHeaders

TcxCustomSpreadSheetBook          See Also

Specifies whether to display row and column headers of worksheets.

property ShowHeaders: Boolean;

Description

Use the ShowHeaders property to specify whether row and column headers are displayed within workbook worksheets.  Row and column headers display row numbers to the left side of a sheet and column letters at its top. If the ShowHeaders property is True, headers are displayed within worksheets.

Set this property to False to hide row and column headers.


TcxCustomSpreadSheetBook.BeginUpdate

TcxCustomSpreadSheetBook          See Also

Disables ExpressSpreadSheet refresh operations.

procedure BeginUpdate;

Description

Calling the BeginUpdate method disables repainting.  If the BeginUpdate procedure has been called, any changes applied to cells are not refreshed until calling the EndUpdate method.  The BeginUpdate and EndUpdate methods work together to prevent numerous updates of the ExpressSpreadSheet control when adding rows or columns.  Be sure to call the EndUpdate method after calling BeginUpdate.  Every call of the BeginUpdate method increases the internal counter by one.  Every call of the EndUpdate decreases this counter by one.  The ExpressSpreadSheet control can refresh itself only when the internal counter is 0.

Assume you need to change several cell styles in your spreadsheet.  If you do not use BeginUpdate and EndUpdate methods, the control redraws itself as many times as the number of modified cells.  Instead of prolonged delays, you may use BeginUpdate before changing the first cell and EndUpdate after changing the last cell; and thus, the control redraws itself only once.


TcxCustomSpreadSheetBook.CellsNameByRef

TcxCustomSpreadSheetBook          See Also

Returns a string representation of the specified cell range.

function CellsNameByRef(ASheet: Integer; const CellsRef: TRect; IsText: Boolean = True): string;

Description

The ASheet parameter specifies the worksheet by its index in the Pages collection.

The CellsRef parameter identifies the cell range within the worksheet.

If the IsText parameter is set to True, the DefinedNames collection is searched for the specified cell range.  If a match is found, the CellsNameByRef function returns the range name.  To suppress this search, pass False as the IsText parameter.

Note:	The resulting string is formatted using the reference style specified by the R1C1ReferenceStyle property value.


TcxCustomSpreadSheetBook.ClearAll

TcxCustomSpreadSheetBook          See Also

Clears the book content.

procedure ClearAll;

Description

The ClearAll method deletes all the worksheets and clears contents of all the worksheets within the workbook by deleting all cell text contents including the cell formatting.  ClearAll resets cells’ style to the default value defined by the DefaultStyle property.

You can use the TcxSSBookSheet.ClearAll method to clear the contents of an individual worksheet.  To clear a specific cell region, call the ClearCells method implemented in the TcxSSBookSheet object.


TcxCustomSpreadSheetBook.Create

TcxCustomSpreadSheetBook

Creates a TcxCustomSpreadSheetBook object instance.

constructor Create(AOwner: TComponent); override;

Description

The Create method is used to create a new instance of the TcxCustomSpreadSheetBook object and initialize its properties.  After calling the inherited constructor, the Create method sets properties of the TcxCustomSpreadSheetBook object to their default values.


TcxCustomSpreadSheetBook.Destroy

TcxCustomSpreadSheetBook

Destroys a TcxCustomSpreadSheetBook object instance.

destructor Destroy; override;

Description

The Destroy method is used to destroy an instance of the TcxCustomSpreadSheetBook object and to release any allocated memory.


TcxCustomSpreadSheetBook.EndUpdate

TcxCustomSpreadSheetBook          See Also

Enables ExpressSpreadSheet refresh operations.

procedure EndUpdate;

Description

Calling the BeginUpdate method disables repainting.  If the BeginUpdate procedure has been called, any changes applied to cells are not refreshed until calling the EndUpdate method.  The BeginUpdate and EndUpdate methods work together to prevent numerous updates of the ExpressSpreadSheet control when adding rows or columns.  Be sure to call the EndUpdate method after calling BeginUpdate.  Every call of the BeginUpdate method increases the internal counter by one.  Every call of the EndUpdate decreases this counter by one.  The ExpressSpreadSheet control can refresh itself only when the internal counter is 0.

Assume you need to change several cell styles in your spreadsheet.  If you do not use BeginUpdate and EndUpdate methods, the control redraws itself as many times as the number of changed cells.  Instead of prolonged delays, you may use BeginUpdate before changing the first cell and EndUpdate after changing the last cell; and thus, the control redraws itself only once.


TcxCustomSpreadSheetBook.HitTest

TcxCustomSpreadSheetBook

Determines which of the spreadsheet control’s element the mouse cursor is currently positioned over.

function HitTest(const APoint: TPoint; out HitTestInfo: TcxSSHitTestInfo): Boolean; virtual;

Description

Use the HitTest method to find out which element the mouse cursor is currently positioned over.

The APoint parameter specifies the coordinates of the hit point in pixels within the spreadsheet control;

The HitTestInfo parameter represents a record that contains information about the spreadsheet control’s elements at the hit point.


TcxCustomSpreadSheetBook.LoadFromFile

TcxCustomSpreadSheetBook          See Also

Loads workbook settings from a file.

procedure LoadFromFile(const FileName: string); virtual;

Description

The LoadFromFile method creates a file stream and calls the LoadFromStream method.  The FileName parameter specifies the name of the file from which to create a stream.


TcxCustomSpreadSheetBook.LoadFromStream

TcxCustomSpreadSheetBook          See Also

Loads workbook settings from a stream.

procedure LoadFromStream(Stream: TStream); virtual;

Description

Use the LoadFromStream method to load previously saved workbook settings.  This method allows a user to load information from a stream object. The information loaded includes:

•	workbook settings, namely: the number of pages in a workbook, the defaults, i.e. default row width, row height, current palette;

•	style settings, namely: the current brush, fonts and cell formats;

•	formulas;

•	spreadsheet cell data.

The Stream parameter specifies a stream object from which to load settings.


TcxCustomSpreadSheetBook.Recalc

TcxCustomSpreadSheetBook          See Also

Performs formula recalculation.

procedure Recalc; virtual;

Description

Calculation is the process of computing formulas and then displaying the results as values in the cells that contain these formulas.  Use the Recalc method to calculate all workbook formulas as your needs dictate.

This method is useful when you enter or change a formula in code.  In this instance, the value is not calculated automatically.

Note: The Recalc method is in effect only if the AutoRecalc property is set to True.


TcxCustomSpreadSheetBook.SaveToFile

TcxCustomSpreadSheetBook          See Also

Saves workbook settings to a file.

procedure SaveToFile(const FileName: string); virtual;

Description

The SaveToFile method creates a file stream and calls the LoadFromStream method.  The FileName parameter specifies the name of the file wherein to store settings.


TcxCustomSpreadSheetBook.SaveToStream

TcxCustomSpreadSheetBook          See Also

Saves workbook settings to a Stream.

procedure SaveToStream(Stream: TStream); virtual;

Description

Use the SaveToStream method to save all workbook settings to a stream.  These settings include information about all formulas, cell styles, fonts and etc.  The information saved includes:

•	workbook settings, namely: the number of pages in a workbook, the defaults, i.e. default row width, row height, current palette;

•	style settings, namely: the current brush, fonts used and cell formats;

•	formulas;

•	spreadsheet cells’ data.

The Stream parameter specifies a stream object wherein to store settings.


TcxCustomSpreadSheetBook.UpdateControl

TcxCustomSpreadSheetBook

Forces the ExpressSpreadSheet control to update itself.

procedure UpdateControl; virtual;

Description

Calling the UpdateControl immediately refreshes the ExpressSpreadSheet control.


TcxCustomSpreadSheetBook.OnActiveCellChanging

TcxCustomSpreadSheetBook          See Also

Occurs before changing the active cell.

type

  TcxSSActiveCellChangingEvent = procedure(Sender: TcxSSBookSheet; const NewActiveCell: TPoint; var CanSelect: Boolean) of object;

property OnActiveCellChanging: TcxSSActiveCellChangingEvent;

Description

The OnActiveCellChanging event is generated before setting focus to another cell of a worksheet.  The Sender parameter defines the worksheet for which the event occurs.  The coordinates of the new active cell are specified by NewActiveCell.  You can determine the current active cell by reading the ActiveCell property.  To prevent changing the active cell set the CanSelect parameter to False.  Otherwise, the cell specified by the NewActiveCell parameter becomes active.


TcxCustomSpreadSheetBook.OnActiveSheetChanging

TcxCustomSpreadSheetBook          See Also

Occurs before changing the active sheet within a workbook.

type

  TcxSSActiveSheetChangingEvent = procedure(Sender: TcxCustomSpreadSheetBook; const NewActiveSheet: Integer; var CanSelect: Boolean) of object;

property OnActiveSheetChanging: TcxSSActiveSheetChangingEvent;

Description

The OnActiveSheetChanging event is generated by the workbook identified by the Sender parameter, before changing the active worksheet.  The current worksheet is accessible via the ActiveSheet property.  The NewActiveSheet parameter defines the new worksheet which a user intends to select.  Use the CanSelect Boolean parameter to permit or prevent changing the active worksheet.


TcxCustomSpreadSheetBook.OnAfterCalculation

TcxCustomSpreadSheetBook          See Also

Occurs after formula calculations have been performed.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnAfterCalculation: TNotifyEvent;

Description

Use the OnAfterCalculation event to receive notifications when spreadsheet formulas are recalculated.  If the AutoRecalc property is set to True, formulas are recalculated automatically when the cells being referenced by formulas change.  You can invoke formula recalculations manually by calling the Recalc method.


TcxCustomSpreadSheetBook.OnCellChange

TcxCustomSpreadSheetBook          See Also

Occurs after changing cell attributes for a cell.

type

  TcxSSCellChangeEvent = procedure(Sender: TcxSSBookSheet; const ACol, ARow: Integer) of object;

property OnCellChange: TcxSSCellChangeEvent;

Description

The OnCellChange event is generated after the cell text or the cell style is changed.  The Sender parameter defines the worksheet generating the event.  The modified cell is identified by its column and row coordinates.

While a user is editing the cell text, the OnCellChanged event does not occur.  A spreadsheet generates this event when the cell contents have been modified and the user moves focus to another cell.

The OnCellChanged event is always generated when changing cell attributes programmatically.


TcxCustomSpreadSheetBook.OnCaptionPopupMenu

TcxCustomSpreadSheetBook          See Also

Occurs when a user invokes the popup menu over a caption bar.

type

  TcxSSPopupMenuEvent = procedure (Sender: TObject; X, Y: Integer) of object;

property OnCaptionPopupMenu: TcxSSPopupMenuEvent;

Description

The OnCaptionPopupMenu event occurs when a user right-clicks the caption bar of a workbook.  Use this event to display a popup menu with appropriate options.


TcxCustomSpreadSheetBook.OnChangeColVisible

TcxCustomSpreadSheetBook          See Also

Occurs when changing column visibility.

type

  TcxSSChangeVisible = procedure(Sender: TObject; ASheet: TcxSSBookSheet; AChangedIndex: Integer; APrevValue, ANewValue: Boolean) of object;

property OnChangeColVisible: TcxSSChangeVisible;

Description

Write an OnChangeColVisible event handler to perform specific actions when changing column visibility by hiding or displaying a column. The ASheet parameter specifies a worksheet containing the column whose visibility is being changed. The AChangedIndex parameter specifies the index of this column.  Column indexes are zero-based.

The APrevValue and ANewValue parameters specify the previous and new values of column visibility.  If column visibility changes from "hidden" to "visible", the APrevValue parameter is False and the ANewValue parameter is True.  If column visibility changes from "visible" to "hidden", the APrevValue parameter is True and the ANewValue parameter is False.

You can change the visibility of a column using the Visible property of the TcxSSHeader class.  To get a column header object, read the TcxSSBookSheet.Cols property.


TcxCustomSpreadSheetBook.OnChangeRowVisible

TcxCustomSpreadSheetBook          See Also

Occurs when changing row visibility.

type

  TcxSSChangeVisible = procedure(Sender: TObject; ASheet: TcxSSBookSheet; AChangedIndex: Integer; APrevValue, ANewValue: Boolean) of object;

property OnChangeRowVisible: TcxSSChangeVisible;

Description

Write an OnChangeRowVisible event handler to perform specific actions when changing row visibility by hiding or displaying a row. The ASheet parameter specifies the worksheet containing the row whose visibility is being changed. The AChangedIndex parameter specifies the index of this row.

The APrevValue and ANewValue parameters correspondingly specify the previous and new values for row visibility.  If row visibility changes from "hidden" to "visible", the APrevValue parameter is False and the ANewValue parameter is True.  If row visibility changes from "visible" to "hidden", the APrevValue parameter is True and the ANewValue parameter is False.

You can change the visibility of a row using the Visible property of the TcxSSHeader class.  To get a row header object, read the TcxSSBookSheet.Rows property.


TcxCustomSpreadSheetBook.OnChangeSheetCaption

TcxCustomSpreadSheetBook          See Also

Occurs before changing the worksheet caption.

type

  TcxSSChangeCaptionEvent = procedure(Sender: TcxSSBookSheet; var ACaption: string) of object;

property OnChangeSheetCaption: TcxSSChangeCaptionEvent;

Description

The OnChangeSheetCaption event occurs before changing the worksheet caption.  The ACaption parameter defines a new caption for the worksheet specified by Sender.  Use the TcxSSBookSheet.Caption property to access the old value of the caption string.


TcxCustomSpreadSheetBook.OnClearCells

TcxCustomSpreadSheetBook          See Also

Occurs before clearing the contents of a cell range.

type

  TcxSSClearCellsEvent = procedure(Sender: TcxSSBookSheet; const ACellRect: TRect; var UseDefaultStyle, CanClear: Boolean) of object;

property OnClearCells: TcxSSClearCellsEvent;

Description

The OnClearCells event occurs before clearing the contents of a cell range.  A user can clear cells by selecting them and pressing the Del key.  The ClearCells method implemented in the TcxSSBookSheet object allows you to clear a cell range programmatically.  Two other methods are available to clear cells: TcxCustomSpreadSheetBook.ClearAll (clears contents of all worksheets within a workbook) and TcxSSBookSheet.ClearAll (clears contents of a single worksheet).

The cell range to be cleared is specified by the ACellRect parameter.  It defines the coordinates of the top left and bottom right cells.  The CanClear parameter specifies whether clearing can be performed.  Set it to False to prevent clearing.  It is possible to clear not only the cell range contents but also the style applied to the cells.  If you want to reset cells’ style to the default value, you should set the UseDefaultStyle property to True.  Otherwise, only the cell contents are deleted.


TcxCustomSpreadSheetBook.OnCustomPaint

TcxCustomSpreadSheetBook          See Also

Used to implement custom workbook drawing.

type

  TcxSSCustomPaintEvent = procedure(Sender: TObject; var PainterClass: TcxSheetPainterClass) of object;

property OnCustomPaint: TcxSSCustomPaintEvent;

Description

Write an OnCustomPaint event handler when your custom painting is used to draw a workbook.  This event fires if the PainterType property is set to ptCustom.  To perform custom workbook painting you should create your own painting class derived from the TcxSheetPainter object.  The PainterClass parameter of the OnCustomPaint event is used to pass a reference to your class designed to perform custom workbook painting.

The following sample code demonstrates what you must do for the control to use your own painting routines.

// Delphi

procedure TForm1.cxSpreadSheetBook1CustomPaint(Sender: TObject;

var PainterClass: TcxSheetPainterClass);

begin

  PainterClass := TMySheetPainter;

end;

// C++ Builder

void __fastcall TForm1::cxSpreadSheetBook1CustomPaint(TObject *Sender,

      TcxSheetPainterClass &PainterClass) {

    PainterClass = __classid(TMySheetPainter);

}

Note: See the Performing Custom Painting topic for details on how to implement custom draw.


TcxCustomSpreadSheetBook.OnEditing

TcxCustomSpreadSheetBook

Occurs before editing a specific cell.

type

  TcxSSEditingEvent = procedure(Sender: TcxSSBookSheet; const ACol, ARow: Integer; var CanEdit: Boolean) of object;

property OnEditing: TcxSSEditingEvent;

Description

The OnEditing event is generated when a user tries to edit a cell.  You can prevent the following edit operation by setting the CanEdit event parameter to False.  By default, the CanEdit parameter is set to True. In this case, a user is allowed to edit the contents of any cell unless the cell’s ReadOnly property is set to True.

The Sender parameter defines the row and column of the actual cell are available via the ACol and ARow parameters.


TcxCustomSpreadSheetBook.OnEndEdit

TcxCustomSpreadSheetBook

Occurs before exiting a specific cell.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnEndEdit: TNotifyEvent;

Description

The OnEndEdit event is generated when a user exits an edited cell.  A user can finish editing a cell in a number of ways: by pressing the Enter key, one of the arrows keys, by moving focus to another cell or control or by changing the active cell programmatically.


TcxCustomSpreadSheetBook.OnFormatCells

TcxCustomSpreadSheetBook          See Also

Occurs before activating the "Format Cells" dialog.

type

  TcxSSFormatCellsEvent = procedure(Sender: TObject; var ACells: TRect; var CanFormat: Boolean; out FormatDialogClass: TcxSSFormatDialogClass) of object;

property OnFormatCells: TcxSSFormatCellsEvent;

Description

Use the OnFormatCells event to control cells formatting.  The "Format cells" dialog is activated by the FormatCells method.  The ACells parameter defines the range of cells for which formatting should be applied.  You can set the CanFormat parameter to False to prevent the dialog from displaying.

It is possible to specify a custom formatting dialog by assigning a dialog class to the FormatDialogClass parameter.  Otherwise, the standard "Format cells" dialog is activated.  To create a custom dialog you need to create a class by deriving from TcxSSFormatDialog and implementing its Execute method.


TcxCustomSpreadSheetBook.OnHistoryChanged

TcxCustomSpreadSheetBook          See Also

Occurs on changing the spreadsheet control’s history.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnHistoryChanged: TNotifyEvent;

Description

A spreadsheet control stores the last actions executed in the History object so that a user is able to undo and redo them.  These actions consist of cell contents and cell style modifications, formatting, inserting, deleting, clearing cells, merging/splitting cells and sorting cells values.  For instance, when you change the border style of a cell, a spreadsheet creates a new entry in the UndoActions list of the History object.  This action can be undone either by pressing the Ctrl+Z shortcut or by calling the Undo method of the History object.  To redo actions you can press the Ctrl+Y shortcut or invoke the Redo method.

When any changes in the History object occur, the spreadsheet control generates the OnHistoryChanged event.


TcxCustomSpreadSheetBook.OnMergeCells

TcxCustomSpreadSheetBook          See Also

Occurs before merging/splitting a cell range.

type

  TcxSSMergeCellsEvent = procedure(Sender: TcxSSBookSheet; ACellRect: TRect; AIsMerge: Boolean; var Allow: Boolean) of object;

property OnMergeCells: TcxSSMergeCellsEvent;

Description

The OnMergeCells event occurs before merging/splitting a range of cells.  The ACellRect parameter defines the range of cells affected.  It defines the coordinates of the top, left and bottom, right cells.  AIsMerge determines whether to merge or split this range.  If this parameter is True than cells are combined into a single cell.  Otherwise, the merged cell is split.  You can permit or prevent merging/splitting by using the Allow parameter.  By setting it to False, you disable the subsequent operation.  The OnMergeCells event is generated by the SetMergedState method implemented in the TcxSSBookSheet class.


TcxCustomSpreadSheetBook.OnProgress

TcxCustomSpreadSheetBook          See Also

Occurs on saving and loading data to a workbook.

type

  TcxProgressEvent = procedure (Sender: TObject; APercent: Byte) of object;

property OnProgress: TcxProgressEvent;

Description

The OnProgress event occurs when a spreadsheet loads data from or saves data to a file/stream.  The Percent parameter provides a value between 0 and 100 indicating the progress of the load/save operation.


TcxCustomSpreadSheetBook.OnResizeCol

TcxCustomSpreadSheetBook          See Also

Occurs when the width of a column in a specific worksheet changes.

type

  TcxSSResizeEvent = procedure(Sender: TcxSSBookSheet; AIndex: Integer; var ANewSize: TcxSSSize) of object;

property OnResizeCol: TcxSSResizeEvent;

Description

The OnResizeCol event is generated before a column in the page specified by the Sender parameter is resized.  The column index is defined by the AIndex parameter.  The ANewSize parameter specifies the new width of the column.  You can change the width of the column by modifying the ANewSize parameter value.


TcxCustomSpreadSheetBook.OnResizeRow

TcxCustomSpreadSheetBook          See Also

Occurs when the height of a row in a specific worksheet is changed.

type

  TcxSSResizeEvent = procedure(Sender: TcxSSBookSheet; AIndex: Integer; var ANewSize: TcxSSSize) of object;

property OnResizeRow: TcxSSResizeEvent;

Description

The OnResizeRow event is generated before a row in the page specified by the Sender parameter is resized.  The row index is defined by the AIndex parameter.  You can change the height of the row by modifying the ANewSize parameter value.


TcxCustomSpreadSheetBook.OnSetSelection

TcxCustomSpreadSheetBook          See Also

Occurs when specifying a range of selected cells within a worksheet.

type

  TcxSSSetSelectionEvent = procedure(Sender: TObject; ASheet: TcxSSBookSheet) of object;

property OnSetSelection: TcxSSSetSelectionEvent;

Description

Write an OnSetSelection event handler to perform specific actions when specifying a range of selected cells within a worksheet.  The selected region can be specified via the TcxSSBookSheet.SelectionRect property. The ASheet parameter specifies the worksheet in which a set of cells was selected.

The following sample code demonstrates how to prevent a user from selecting more than one cell.

// Delphi

procedure TForm1.cxSpreadSheetBook1SetSelection(Sender: TObject;

  ASheet: TcxSSBookSheet);

var ARect: TRect;

begin

  with ARect do

  begin

    Left := cxSpreadSheetBook1.ActiveCell.X;

    Top := cxSpreadSheetBook1.ActiveCell.Y;

    Right := Left;

    Bottom := Top;

  end;

  ASheet.SelectionRect := ARect;

end;

// C++ Builder

void __fastcall TForm1::cxSpreadSheetBook1SetSelection(TObject *Sender,

      TcxSSBookSheet *ASheet) {

  TRect rect;

  rect.Left = cxSpreadSheetBook1->ActiveCell.x;

  rect.Top = cxSpreadSheetBook1->ActiveCell.y;

  rect.Right = rect.Left;

  rect.Bottom = rect.Top;

  ASheet->SelectionRect = rect;

}


TcxCustomSpreadSheetBook.OnSheetPopupMenu

TcxCustomSpreadSheetBook          See Also

Occurs on worksheet menu popup.

type

  TcxSSPopupMenuEvent = procedure (Sender: TObject; X, Y: Integer) of object;

property OnSheetPopupMenu: TcxSSPopupMenuEvent;

Description

The OnSheetPopupMenu event occurs when a user right-clicks on a worksheet.  Use this event to display an appropriate popup menu.


TcxCustomSpreadSheetBook.OnTopLeftChanging

TcxCustomSpreadSheetBook          See Also

Occurs before the visible top left cell of a worksheet is changed.

type

  TcxSSTopLeftChangingEvent = procedure(Sender: TcxSSBookSheet; var ATopLeft: TPoint) of object;

property OnTopLeftChanging: TcxSSTopLeftChangingEvent;

Description

This event is generated when scrolling the worksheet so that the visible top left cell changes.  The ATopLeft argument defines the coordinates of the proposed new top left visible cell.  You can prevent scrolling by setting the ATopLeft to its current value.

To access the current coordinates of the visible top left cell, see the TcxSSBookSheet.Corners property.


TcxSpreadSheet
TcxSpreadSheet Object

Hierarchy          Properties          Methods          Events

Represents a worksheet control.

Unit

cxSSheet

TcxSpreadSheet = class(TcxCustomSpreadSheetBook)

Description

The TcxSpreadSheet object represents a separate worksheet.  The TcxSpreadSheet object is derived directly from the TcxCustomSpreadSheetBook class and publishes most of the TcxCustomSpreadSheetBook object’s properties and methods.

The Sheet property allows you to get a reference to the worksheet owned by a TcxSpreadSheet control.  Using this property, you can get a specific cell object, refer to header panels, select, clear, delete a cell range, sort against multiple columns, merge/split cells etc.


TcxSpreadSheet Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxCustomSpreadSheetBook


Properties for TcxSpreadSheet
TcxSpreadSheet Properties

TcxSpreadSheet          Legend

In TcxSpreadSheet

Sheet

Derived from TcxCustomSpreadSheetBook

ActiveCell

ActivePage

ActiveSheet

AutoRecalc

BufferedPaint

ColHeaderHeight

DefaultColWidth

DefaultRowHeight

DefaultStyle

DefinedNames

ExcelProtectionStyle

GridColor

HeaderColor

HeaderFont

HideSelection

History

PageCount

Pages

PageVisible

PainterType

Palette

Precision

R1C1ReferenceStyle

ReadOnly

RowHeaderWidth

RowsAutoHeight

ScrollBars

SelectionColor

SelectionRect

ShowCaptionBar

ShowFormulas

ShowGrid

ShowHeaders

Derived from TcxControl

BorderStyle

Bounds

Canvas

ClientBounds

FocusOnClick

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxSpreadSheet
TcxSpreadSheet Methods

TcxSpreadSheet          Legend

In TcxSpreadSheet

Create

Derived from TcxCustomSpreadSheetBook

BeginUpdate

CellsNameByRef

ClearAll

Create

DefineName

DefineNameEx

Destroy

EndUpdate

LoadFromFile

LoadFromStream

Recalc

SaveToFile

SaveToStream

UpdateControl

Derived from TcxControl

InvalidateRect


Events for TcxSpreadSheet
TcxSpreadSheet Events

TcxSpreadSheet          Legend

Derived from TcxCustomSpreadSheetBook

OnActiveCellChanging

OnActiveSheetChanging

OnAfterCalculation

OnCellChange

OnChangeColVisible

OnChangeRowVisible

OnChangeSheetCaption

OnClearCells

OnCustomPaint

OnEditing

OnEndEdit

OnFormatCells

OnHistoryChanged

OnMergeCells

OnProgress

OnResizeCol

OnResizeRow

OnSetSelection

OnSheetPopupMenu

OnCaptionPopupMenu

OnTopLeftChanging


TcxSpreadSheet.Sheet

TcxSpreadSheet

Gets a worksheet, which encapsulates the data editing functionality.

property Sheet: TcxSSBookSheet;

Description

Use the Sheet property to access data represented by the TcxSpreadSheet component.  It provides access to client and non-client regions of a worksheet.  The Cols and Rows properties return references to column and row header panels thus allowing you to specify the size of individual columns/rows, their visibility status and other attributes.

The TcxSSBookSheet object provides many methods to access properties of a specific cell, copy, paste, select, clear and delete a cell region, sort cell values by multiple columns and many other useful routines.

The next code demonstrates how to add a formula to cell A1 at runtime.  The formula calculates a number of empty cells in the range between A2 and D2:

// Delphi

with cxSpreadSheet1.Sheet.GetCellObject(0,0) do

try

  Text := '=COUNTBLANK(A2:D2)';

finally

  Free;

end;

// C++ Builder

TcxSSCellObject * Cell = cxSpreadSheet1->Sheet->GetCellObject(0,0);

try {

  Cell->Text = "=COUNTBLANK(A2:D2)";

}

__finally {

  delete Cell;

}

ReadOnly Property


TcxSpreadSheet.Create

TcxSpreadSheet

Creates a TcxSpreadSheet object instance.

procedure Create(AOwner: TComponent); override;

Description

The Create method is used to create an instance of the TcxSpreadSheet object and initialize its properties.  The AOwner parameter specifies the owner of your control.


TcxSpreadSheetBook
TcxSpreadSheetBook Object

Hierarchy          Properties          Methods          Events

Represents a workbook control.

Unit

cxSSheet

TcxSpreadSheetBook = class(TcxCustomSpreadSheetBook)

Description

The TcxSpreadSheetBook object represents the ExpressSpreadSheetBook component.  It allows you to work with several worksheets.

The TcxSpreadSheetBook object is derived directly from the TcxCustomSpreadSheetBook class.  The TcxSpreadSheetBook object does not introduce any new functionality except for its Create method.  This is a ‘published’ variant of the TcxCustomSpreadSheetBook object, which fully implements ExpressSpreadSheet functionality.

The Pages property provides access to all worksheets within a TcxSpreadSheetBook control.  The number of worksheets is defined by the PageCount member.  You can use the ActiveSheet property to get a reference to the active worksheet.  Every worksheet is represented by a TcxSSBookSheet object providing you the ability to get a specific cell object, obtain a reference to header panels, select, clear, delete a cell range, sort against multiple columns, merge/split cells etc.


TcxSpreadSheetBook Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxCustomSpreadSheetBook


Properties for TcxSpreadSheetBook
TcxSpreadSheetBook Properties

TcxSpreadSheetBook          Legend

Derived from TcxCustomSpreadSheetBook

ActiveCell

ActivePage

ActiveSheet

AutoRecalc

BufferedPaint

ColHeaderHeight

DefaultColWidth

DefaultRowHeight

DefaultStyle

DefinedNames

ExcelProtectionStyle

GridColor

HeaderColor

HeaderFont

HideSelection

History

PageCount

Pages

PageVisible

PainterType

Palette

Precision

R1C1ReferenceStyle

ReadOnly

RowHeaderWidth

RowsAutoHeight

ScrollBars

SelectionColor

SelectionRect

ShowCaptionBar

ShowFormulas

ShowGrid

ShowHeaders

Derived from TcxControl

BorderStyle

Bounds

Canvas

ClientBounds

FocusOnClick

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu


Methods for TcxSpreadSheetBook
TcxSpreadSheetBook Methods

TcxSpreadSheetBook          Legend

In TcxSpreadSheetBook

AddSheetPage

Create

DeleteSheet

EditActiveSheetCaption

ExchangeSheets

Derived from TcxCustomSpreadSheetBook

BeginUpdate

CellsNameByRef

ClearAll

Create

DefineName

DefineNameEx

Destroy

EndUpdate

LoadFromFile

LoadFromStream

Recalc

SaveToFile

SaveToStream

UpdateControl

Derived from TcxControl

InvalidateRect


Events for TcxSpreadSheetBook
TcxSpreadSheetBook Events

TcxSpreadSheetBook          Legend

In TcxSpreadSheetBook

OnDeleteSheet

OnExchangeSheets

Derived from TcxCustomSpreadSheetBook

OnActiveCellChanging

OnActiveSheetChanging

OnAfterCalculation

OnCellChange

OnChangeColVisible

OnChangeRowVisible

OnChangeSheetCaption

OnClearCells

OnCustomPaint

OnEditing

OnEndEdit

OnFormatCells

OnHistoryChanged

OnMergeCells

OnProgress

OnResizeCol

OnResizeRow

OnSetSelection

OnSheetPopupMenu

OnCaptionPopupMenu

OnTopLeftChanging


TcxSpreadSheetBook.AddSheetPage

TcxCustomSpreadSheetBook          See Also

Adds a sheet to a workbook.

procedure AddSheetPage(const APageName: string = ''); override;

Description

The AddSheetPage method adds a new blank sheet to a workbook. Optionally, you can provide a name for the sheet via the APageName parameter. By default, the new sheet will have no name.  You can also use the PageCount property to change the number of pages within a workbook.


TcxSpreadSheetBook.Create

TcxSpreadSheetBook

Creates a TcxSpreadSheetBook object instance.

procedure Create(AOwner: TComponent); override;

Description

The Create method is used to create an instance of the TcxSpreadSheetBook object and add one sheet to the newly created workbook.


TcxSSBookSheet
TcxSSBookSheet Object

Hierarchy          Properties          Methods

Represents a worksheet.

Unit

cxSSheet

TcxSSBookSheet = class(TcxWorkBookSubControl)

Description

The TcxSSBookSheet object represents a single worksheet contained by a TcxSpreadSheet or TcxSpreadSheetBook control.  The TcxSSBookSheet object allows you to get a specific cell object, obtain a reference to header panels, select, clear, delete a cell range, sort against multiple columns, merge/split cells etc.

The TcxSSBookSheet object corresponding to a particular worksheet can be obtained via the Pages or ActiveSheet property of a TcxSpreadSheetBook control and the Sheet property of a TcxSpreadSheet control.  Change the Parent property of the TcxSSBookSheet object in order to display the worksheet within a specific container control.


TcxSSBookSheet Hierarchy
Hierarchy

TInterfacedObject

     |

TcxWorkBookSubControl


Properties for TcxSSBookSheet
TcxSSBookSheet Properties

TcxSSBookSheet          Legend

In TcxSSBookSheet

ActiveCell

Caption

Col

Cols

ColumnCount

ContentColCount

ContentRowCount

Corners

PageIndex

ReadOnly

Row

RowCount

Rows

SelectionRect

ShowFormulas

ShowGrid

ShowHeaders


Methods for TcxSSBookSheet
TcxSSBookSheet Methods

TcxSSBookSheet          Legend

In TcxSSBookSheet

ClearAll

ClearCells

Copy

Create

DeleteCells

Destroy

FormatCells

GetCellObject

InsertCells

Paste

SelectCell

SetMergedState

SetVisibleState

Sort

Derived from TcxWorkBookSubControl

Invalidate

InvalidateRect


TcxSSBookSheet.ActiveCell

TcxSSBookSheet          See Also

Specifies active worksheet cell.

property ActiveCell: TPoint;

Description

Use the ActiveCell property to get or set the active cell position within a worksheet.  This property is of type TPoint so you can read/set its X and Y fields, which specify the horizontal and vertical coordinates of the active cell within your worksheet.  These coordinates are zero-based indexes of the column and row containing the cell.

The following sample code increments the row index of the active cell within the second worksheet.  This forces focus to move one cell down.

// Delphi

var

  APoint: TPoint;

  ABookSheet: TcxSSBookSheet;

//...

ABookSheet := cxSpreadSheetBook1.Pages[1];

with APoint do

begin

  X := ABookSheet.ActiveCell.X;

  Y := ABookSheet.ActiveCell.Y + 1;

end;

ABookSheet.ActiveCell := APoint;

// C++ Builder

TPoint point;

TcxSSBookSheet *bookSheet;

bookSheet = cxSpreadSheetBook1->Pages[1];

point.x = bookSheet->ActiveCell.x;

point.y = bookSheet->ActiveCell.y + 1;

bookSheet->ActiveCell = point;


TcxSSBookSheet.Caption

TcxSSBookSheet          See Also

Specifies the caption of a worksheet.

property Caption: string;

Description

Use the Caption property to label a worksheet. Worksheet captions are displayed within the caption bar located in the bottom-left corner of the spreadsheet.

The following sample code changes the caption of the third worksheet.  The initial look & feel of the workbook is displayed in the image below.

// Delphi

var ABookSheet: TcxSSBookSheet;

//...

ABookSheet := cxSpreadSheetBook1.Pages[2];

ABookSheet.Caption := 'Third Page';

// C++ Builder

TcxSSBookSheet *bookSheet;

bookSheet = cxSpreadSheetBook1->Pages[2];

bookSheet->Caption = "Third Page";


TcxSSBookSheet.Col

TcxSSBookSheet          See Also

Gets the column index of the active cell.

property Col: Integer;

Description

Use the Col property to obtain the column index of the active worksheet cell.  The row index of the active cell is determined by the Row property.  You can use the ActiveCell property to return the structure containing both column and row coordinates.

ReadOnly Property


TcxSSBookSheet.Cols

TcxSSBookSheet

Returns the object representing the column header panel of the current worksheet.

property Cols: TcxSSHeader;

Description

Use the Cols property to gain access to the column header panel (its properties and methods) of the current worksheet.  The Cols property returns a reference to an object of type TcxSSHeader.  The TcxSSHeader object returned by the Cols property represents the columns header panel, which contains column headers marked by letters.

The obtained object allows you to set the default width of column headers, change the width of a particular column header and make column headers visible.  All the properties affecting the size and visibility of column headers affect the size and visibility of corresponding columns.

The following sample code changes the default width of column headers, changes the width of the first column header (A) and makes the second column header (B) invisible.  All the changes are applied to the active worksheet within a workbook.

// Delphi

var

  Cols: TcxSSHeader;

//...

Cols := cxSpreadSheetBook1.ActiveSheet.Cols;

with Cols do

begin

  DefaultSize := 20;

  Size[0] := 100;

  Visible[1] := False;

end;

// C++ Builder

TcxSSHeader * Cols = cxSpreadSheetBook1->ActiveSheet->Cols;

Cols->DefaultSize = 20;

Cols->Size[0] = 100;

Cols->Visible[1] = false;

ReadOnly Property


TcxSSBookSheet.ColumnCount

TcxSSBookSheet          See Also

Specifies the number of changed columns in the worksheet.

property ColumnCount: Integer;

Description

Read the ColumnCount property to determine the number of changed columns in the current worksheet.  The ColumnCount property takes into account all changes in cells made since a spreadsheet control was loaded.

Suppose that cells to the right of column D were not changed.  If you made changes in any cell of column D and perhaps cleared these changes, the ColumnCount would still return 4.

ReadOnly Property


TcxSSBookSheet.Corners

TcxSSBookSheet          See Also

Specifies the visible left top and right bottom cells within a worksheet.

property Corners: TRect;

Description

The Corners property returns the zero-based coordinates of the visible left top and right bottom cells within a worksheet.

The image demonstrates a sample worksheet for which the Corners property returns (0;0) and (1;6) as coordinates of the top left and bottom right cells respectively.

The coordinates determined by the property do not include partially visible cells.

When the coordinates of the top left cell are changed (due to scrolling, for instance), the TcxCustomSpreadSheetBook.OnTopLeftChanging event is generated.


TcxSSBookSheet.ContentColCount

TcxSSBookSheet          See Also

Returns a number of content columns within a worksheet.

property ContentColCount: Integer;

Description

The number of content columns is determined by the rightmost column, which contains a cell with modified properties.  These properties include style attributes (borders, background color etc.) and text.  For instance, if column B contains any modified cell and columns to the right (C, D, E…) do not contain modified cells the ContentColCount returns 2.  The number of meaning rows is retrieved via the ContentRowCount property.

ReadOnly Property


TcxSSBookSheet.ContentRowCount

TcxSSBookSheet          See Also

Returns a number of meaning rows of a worksheet.

property ContentRowCount: Integer;

Description

The number of meaning rows is determined by the bottommost row, which contains a cell with modified properties.  These properties include style attributes (borders, background color etc.) and text.  For instance, if row 3 contains any modified cell and rows below (4, 5, 6…) do not contain modified cells the MeaningRowCount returns 3.  Use the ContentColCount property to get the number of meaning columns.

ReadOnly Property


TcxSSBookSheet.PageIndex

TcxSSBookSheet          See Also

Returns the zero-based index of a worksheet within a workbook’s Pages collection.

property PageIndex: Integer;

ReadOnly Property


TcxSSBookSheet.ReadOnly

TcxSSBookSheet

Specifies the read-only status of a worksheet.

property ReadOnly: Boolean;

Description

Set the ReadOnly property to True to prevent the contents of the worksheet from being modified.  Otherwise, the cell contents can be edited.

You can set the read-only status for all worksheets within a workbook, or individual cells, via the workbook’s ReadOnly property or the cell’s Style.ReadOnly property.  To access a specific worksheet, use the spreadsheet control’s ActiveSheet or Pages property and a worksheet control’s Sheet property.

Note:	The ReadOnly properties are in effect only if the spreadsheet control’s ExcelProtectionStyle property is set to False.


TcxSSBookSheet.Row

TcxSSBookSheet          See Also

Gets the row index of the active cell.

property Row: Integer;

Description

Use the Row property to obtain the row index of the active worksheet cell.  The column index of the active cell is determined by the Col property.  You can use the ActiveCell property to return the structure containing both column and row coordinates.

ReadOnly Property


TcxSSBookSheet.Rows

TcxSSBookSheet

Returns the object representing the row header panel of the current worksheet.

property Rows: TcxSSHeader;

Description

Use the Rows property to obtain access to the row header panel (its properties and methods) of the current worksheet.  The Rows property returns a reference to an object of type TcxSSHeader.  The TcxSSHeader object returned by the Rows property represents the row header panel, which displays row numbers on the left side of the active worksheet.

The obtained object allows you to set the default height of row headers, change the height of a particular row header and make column headers visible.  All the properties affecting the size and visibility of row headers affect the size and visibility of corresponding rows.

The following sample code changes the default height of row headers, changes the height of the first row header (1) and makes the second row header (2) invisible.  All the changes are applied to the active worksheet.

// Delphi

var

  Rows: TcxSSHeader;

//...

Rows := cxSpreadSheetBook1.ActiveSheet.Rows;

with Rows do

begin

  DefaultSize := 15;

  Size[0] := 30;

  Visible[1] := False;

end;

// C++ Builder

TcxSSHeader * Rows = cxSpreadSheetBook1->ActiveSheet->Rows;

Rows->DefaultSize = 15;

Rows->Size[0] = 30;

Rows->Visible[1] = false;

ReadOnly Property


TcxSSBookSheet.RowCount

TcxSSBookSheet          See Also

Specifies the number of changed rows in the worksheet.

property RowCount: Integer;

Description

Read the RowCount property to determine the number of changed rows in the current worksheet starting from the first row.

The RowCount property takes into account all changes in cells made since the spreadsheet control was loaded.

Suppose that cells below row 5 were not changed.  If you made changes in any cell of the fifth row and perhaps cleared these changes, the RowCount would still return 5.

ReadOnly Property


TcxSSBookSheet.SelectionRect

TcxSSBookSheet          See Also

Specifies the boundaries of the selected cell range within a worksheet.

property SelectionRect: TRect;

Description

Set the SelectionRect property to select a range of cells in a worksheet.  This property is of type TRect and thus can represent either the top, left, right and bottom boundaries of the selected area or the coordinates of the top-left and bottom-right cells of the selection.

The following sample code sets the B2:C4 selection range within the active worksheet.

// Delphi

var

  ABookSheet: TcxSSBookSheet;

//...

ABookSheet := cxSpreadSheetBook1.ActiveSheet;

ABookSheet.SelectionRect := Rect(1,1,2,3);

// C++ Builder

TcxSSBookSheet * ABookSheet = cxSpreadSheetBook1->ActiveSheet;

ABookSheet->SelectionRect = Rect(1,1,2,3);


TcxSSBookSheet.ShowFormulas

TcxSSBookSheet          See Also

Specifies whether to display formulas within cells in the current worksheet.

property ShowFormulas: Boolean;

Description

Use the ShowFormulas property to specify whether to display formulas within cells instead of resulting values.  If this property is False, all cells containing formulas display the resulting values of the contained formulas.  Set the ShowFormulas property to True to force these cells to display only the formulas they contain.

The image below displays a worksheet in which cell B2 contains a formula that subtracts the values of cells A2 and B1 from the value of cell A1.  The ShowFormulas property is True.

After setting the ShowFormulas property to False, the resultant value will be displayed within cell B2.

The default value is False.


TcxSSBookSheet.ShowGrid

TcxSSBookSheet          See Also

Specifies whether to display gridlines within a worksheet.

property ShowGrid: Boolean;

Description

Use the ShowGrid property to specify whether cell gridlines are displayed within a worksheet.  If the ShowGrid property is True, cell gridlines are displayed within a worksheet.

Set this property to False to hide cell gridlines.


TcxSSBookSheet.ShowHeaders

TcxSSBookSheet          See Also

Specifies whether to display row and column headers of a worksheet.

property ShowHeaders: Boolean;

Description

Use the ShowHeaders property to specify whether row and column headers are displayed within a worksheet.  Row and column headers display row numbers on the left side of the sheet and column letters at the top of the sheet, or row and column numbers if the R1C1ReferenceStyle is set to True

If the ShowHeaders property is True, headers are displayed within worksheet.

Set this property to False to hide row and column headers.


TcxSSBookSheet.ClearAll

TcxSSBookSheet          See Also

Clears the contents and formatting of the current worksheet.

procedure ClearAll;

Description

The ClearAll method clears the contents and formatting of the current worksheet.  Use the ClearCells method if you only need to clear the contents of a specific cell range.


TcxSSBookSheet.ClearCells

TcxSSBookSheet          See Also

Clears the contents of a specific cell range.

procedure ClearCells(const ARect: TRect; SetDefaultStyle: Boolean = False);

Description

Use the ClearCells method to delete the contents of the cells identified by the ARect parameter.  The ARect parameter specifies the zero-based coordinates of the top left and bottom right cells.  The ClearCells method resets style attributes of the cell range to their default values if the SetDefaultStyle parameter is True.  Otherwise, cell formatting is not affected and only the contents are deleted.

You can delete the contents of cells at runtime by selecting the required cell range and pressing the Delete key.

Before the cell contents are deleted, the spreadsheet control generates the TcxCustomSpreadSheetBook.OnClearCells event.  You can handle this event to cancel the clearing operation.


TcxSSBookSheet.Copy

TcxSSBookSheet          See Also

Copies the contents of the specified cell range.

procedure Copy(const ARect: TRect; IsCut: Boolean);

Description

Use the Copy method to copy the contents of a cell range defined by the ARect parameter to the clipboard.  It defines the coordinates of the top left and bottom right cells of a range.  The IsCut parameter determines whether the contents should be deleted after copying.  To paste from the clipboard use the Paste method.


TcxSSBookSheet.Create

TcxSSBookSheet

Creates a TcxSSBookSheet object instance.

constructor Create(AOwner: TComponent); override;

Description

The Create method is used to create an instance of the TcxSSBookSheet object and initializes its properties.  The AOwner parameter specifies the owner of the object.


TcxSSBookSheet.DeleteCells

TcxSSBookSheet          See Also

Removes specified cells from the worksheet and shifts the surrounding cells to populate the empty space.

type

  TcxSSCellsModify = (msShiftCol, msShiftRow, msAllCol, msAllRow);

procedure DeleteCells(const ACells: TRect; ACellsModify: TcxSSCellsModify);

Description

The DeleteCells method is used to remove cells specified by the ACells parameter from the current worksheet and shift the surrounding cells to populate the empty space. The ACellModify parameter specifies the direction in which the surrounding cells, rows, or columns must be shifted when deleting cells.  The UseModifyForm parameter specifies whether to use the "Delete Cells" dialog box in order to select the manner in which surrounding cells populate the empty space when deleting cells.

The following sample code deletes selected cells and entire rows.  The image below displays the spreadsheet before cell deletion.

// Delphi

cxSSBookSheet1.DeleteCells(cxSpreadSheetBook1.ActiveSheet.SelectionRect, msAllRow);

// C++ Builder

cxSSBookSheet1->DeleteCells(
  cxSpreadSheetBook1->ActiveSheet->SelectionRect, msAllRow);

The following image displays the spreadsheet after cells have been deleted.


TcxSSBookSheet.Destroy

TcxSSBookSheet

Destroys a TcxSSBookSheet object instance.

destructor Destroy; override;

Description

The Destroy method is used to destroy an instance of the TcxSSBookSheet object and release any allocated memory.


TcxSSBookSheet.FormatCells

TcxSSBookSheet          See Also

Invokes the Format Cells dialog box.

procedure FormatCells(const ACells: TRect);

Description

The FormatCells method displays the Format Cells dialog box.  This allows you to implement formatting to the cells specified by the ACellRect parameter.  The Format Cells dialog contains three pages that allow a user to set text alignment, format and wrapping, border style and fill pattern for cells.

// Delphi

var

  CellRect: TRect;

//...

with CellRect do

begin

  Left := 0;

  Top := 0;

  Right := 3;

  Bottom := 3;

end;

cxSSBookSheet1.FormatCells(CellRect);

// C++ Builder

TRect cellRect;

cellRect.Left = 0;

cellRect.Top = 0;

cellRect.Right = 3;

cellRect.Bottom = 3;

cxSSBookSheet1->FormatCells(cellRect);


TcxSSBookSheet.GetCellObject

TcxSSBookSheet

Gets an object representing a specific cell.

function GetCellObject(ACol, ARow: Integer): TcxSSCellObject; virtual;

Description

Use the GetCellObject method to gain access to the TcxSSCellObject object, which represents a specific cell within a worksheet.  Calling the GetCellObject method creates an instance of the TcxSSCellObject object for the cell specified by the ACol and ARow parameters (the ACol parameter contains the column index and the ARow parameter contains the row index of the cell).  You must destroy the object obtained by this method as soon as you finish working with it.

The TcxSSCellObject object is developed to facilitate any cell manipulations.  Just set its appropriate properties and the corresponding cell will automatically reflect all changes.

The following sample code changes the text and format of the active cell.

// Delphi

var

  ACell: TcxSSCellObject;

  X, Y: integer;

//...

X := cxSSBookSheet1.ActiveCell.X;

Y := cxSSBookSheet1.ActiveCell.Y;

ACell := cxSSBookSheet1.GetCellObject(X, Y);

with ACell do

try

  Text := 'Text for the cell [' + IntToStr (X) + ', ' + IntToStr (Y) + ']';

  with Style do

  begin

    HorzTextAlign := haCENTER;

    VertTextAlign := vaCENTER;

    with Brush do

    begin

      Style := fsSolid;

      BackgroundColor := 5; //clYellow

    end;

    with Font do

    begin

      Name := 'Verdana';

      Size := 8;

      Style := [fsBold, fsUnderline];

      FontColor := 38;

    end;

  end

finally

   Free;

end;

// C++ Builder

TcxSSCellObject *cell;

int  x, y;

x = cxSpreadSheet1->Sheet->Col;

y = cxSpreadSheet1->Sheet->Row;

cell = cxSpreadSheet1->Sheet->GetCellObject(x, y);

try {

  cell->Text = "Text for the cell [" + IntToStr (x) + ", " + IntToStr (y) + "]";

  cell->Style->Font->FontColor = 38;

  cell->Style->HorzTextAlign = haCENTER;

  cell->Style->VertTextAlign = vaCENTER;

  cell->Style->Brush->Style = fsSolid;

  cell->Style->Brush->BackgroundColor = 5; //clYellow

  cell->Style->Font->Name = "Verdana";

  cell->Style->Font->Size = 8;

  cell->Style->Font->Style = TFontStyles() << fsBold << fsUnderline;

}

__finally {

  delete cell;

}

The following image displays the active cell after applying the sample code.


TcxSSBookSheet.InsertCells

TcxSSBookSheet          See Also

Inserts a range of cells into the worksheet and shifts the surrounding cells to allocate space for the inserted cells.

type

  TcxSSCellsModify = (msShiftCol, msShiftRow, msAllCol, msAllRow);

procedure InsertCells(const ACells: TRect; ACellsModify: TcxSSCellsModify);

Description

The InsertCells method is used to insert cell regions specified by the ACells parameter into the current worksheet and shift the surrounding cells to make room for the inserted cells.  The ACellModify parameter specifies the direction in which the surrounding cells, rows, or columns must be shifted when inserting cells.

The following sample code inserts cell range B2:B3.  Neighboring cells are shifted to the right.  The appearance of the worksheet before code execution is displayed in the image below.

// Delphi

var ARect: TRect;

//...

with ARect do

begin

  Left := 1;

  Top := 1;

  Right := 1;

  Bottom := 2;

end;

cxSSBookSheet1.InsertCells(ARect, msShiftCol);

// C++ Builder

TRect rect;

rect.Left = 1;

rect.Top = 1;

rect.Right = 1;

rect.Bottom = 2;

cxSSBookSheet1->InsertCells(rect, msShiftCol, false);


TcxSSBookSheet.Paste

TcxSSBookSheet          See Also

Pastes from the clipboard into the specified cell(s).

procedure Paste(const APlace: TPoint);

Description

Use the Paste method to paste the contents of the clipboard into the worksheet starting from the specified cell.  To copy a selected spreadsheet cell range, call the Copy method.


TcxSSBookSheet.SelectCell

TcxSSBookSheet          See Also

Selects the specified cell.

procedure SelectCell(const ACol, ARow: Integer; OpenEditor: Boolean = False);

Description

The SelectCell method selects the cell with coordinates defined by ACol and ARow parameters.  This cell becomes active.  Before activating the cell the TcxCustomSpreadSheetBook.OnActiveCellChanging event is called.  The OpenEditor parameter specifies whether the cell is placed in edit mode.


TcxSSBookSheet.SetMergedState

TcxSSBookSheet          See Also

Merges/splits a specified cell region within a worksheet.

procedure SetMergedState(const ARect: TRect; IsMerge: Boolean);

Description

Use the SetMergeState method to merge/split a cell region specified by the ARect parameter within a worksheet.

The IsMerge parameter determines whether to merge cells specified by the ARect parameter.  If the IsMerge parameter is True, the SetMergeState method combines two or more cells specified by the ARect parameter into a single cell.  Otherwise, this method splits a merged cell into separate cells.

When several cells are merged, the data contained in the merged cell is stored within a single cell of the merged cells collection.  This cell is called the main cell.  Use the IsMain property of the TcxSSCellStyle object to determine whether the cell is the main cell within the merged cells collection.

The following sample code merges cell range B2:D4.  The initial appearance of the worksheet is displayed in the image below.

// Delphi

var ARect: TRect;

//...

with ARect do

begin

  Left := 1;

  Top := 1;

  Right := 3;

  Bottom := 3;

end;

cxSSBookSheet1.SetMergedState(ARect, True);

// C++ Builder

TRect rect;

rect.Left = 1;

rect.Top = 1;

rect.Right = 3;

rect.Bottom = 3;

cxSSBookSheet1->SetMergedState(rect, true);


TcxSSBookSheet.SetVisibleState

TcxSSBookSheet

Hides/displays a specified cell region within the current sheet.

procedure SetVisibleState(const ARect: TRect; ACols, ARows, AShow: Boolean);

Description

Use the SetVisibleState method to hide or display a cell region.  The method changes the visibility state for entire columns or rows based upon the ACols and ARows parameter values.

The ACols parameter determines whether columns of the specified region are to be hidden/displayed.  If this parameter is True, entire columns of the specified cell region are hidden/displayed by the SetVisibleState method.  Otherwise, the SetVisibleState method does not affect the columns.

The ARows parameter determines whether rows of the specified region are to be hidden/displayed.  If this parameter is True, entire rows of the specified cell region are hidden/displayed by the SetVisibleState method.  Otherwise, the SetVisibleState method does not affect rows.

The AShow parameter determines whether to show or hide the specified cell region.  If this parameter is True columns and/or rows become visible within the worksheet.  Otherwise, the cell region becomes hidden within the worksheet.

The following sample code demonstrates how to hide both rows and columns, which contain the currently specified rectangular area.

The appearance of the worksheet before code execution is displayed in the image below.

// Delphi

var ARect: TRect;

//...

ARect := cxSpreadSheetBook1.ActiveSheet.SelectionRect;

cxSpreadSheetBook1.ActiveSheet.SetVisibleState(ARect, True, True, False);

// C++ Builder

TRect rect;

rect = cxSpreadSheetBook1->ActiveSheet->SelectionRect;

cxSpreadSheetBook1->ActiveSheet->SetVisibleState(rect, true, true, false);


TcxSSBookSheet.Sort

TcxSSBookSheet

Sorts the specified range of cells.

procedure Sort(const ARect: TRect; const ASortTypes: array of TcxSortType);

Description

The Sort method allows sorting values against multiple columns within a range defined by the ARect parameter.  The Left and Right fields of ARect define the range of columns on which data is sorted.  The Top and Bottom fields of ARect define the top and bottom rows of this range.

You can identify the sort order for every column via the ASortTypes array.  The specified rows are sorted in the order defined by the first ASortTypes array element.  If the first column has several equal values, the corresponding rows are sorted in the sort order defined by the second ASortTypes element and so on.

Let us consider an example.  The next image demonstrates a spreadsheet control with data on countries.

Suppose, you want to sort against the continent and country columns in descending and ascending orders respectively.  The following code performs such a sorting of selected range of cells.  As the values in column C relate to the data of the two previous columns, you must specify all three columns in the Sort method (in this example, it is necessary to select three columns A, B, C before executing the code).

// Delphi

with cxSpreadSheetBook1.ActiveSheet do

  Sort(SelectionRect, [stDescending, stAscending]);

// C++ Builder

const int sortTypesSize = 2;

TcxSortType sortTypes[sortTypesSize] = {stDescending, stAscending};

TcxSSBookSheet * worksheet = cxSpreadSheetBook1->ActiveSheet;

worksheet->Sort(worksheet->SelectionRect, sortTypes, sortTypesSize);

The result is displayed below:


TcxSSCellObject
TcxSSCellObject Object

Hierarchy          Properties          Methods

Represents a cell.

Unit

cxSSheet

TcxSSCellObject = class(TObject)

Description

The TcxSSCellObject object represents a specific cell within a worksheet.  An instance of the TcxSSCellObject object is returned by the GetCellObject method of the TcxSSBookSheet object.

The TcxSSCellObject object was developed to make cell manipulations easier.  Just set its properties and the corresponding cell will automatically reflect all changes.  This object allows you to manipulate data stored in the cell and change its style (border style, fill pattern, font, etc.).


TcxSSCellObject Hierarchy
Hierarchy

TObject


Properties for TcxSSCellObject
TcxSSCellObject Properties

TcxSSCellObject          Legend

In TcxSSCellObject

CellValue

Col

DataType

DateTime

DisplayText

DisplayTextAlignment

Row

Style

StyleExist

Text


Methods for TcxSSCellObject
TcxSSCellObject Methods

TcxSSCellObject          Legend

In TcxSSCellObject

Create

Destroy

SetCellText


TcxSSCellObject.CellValue

TcxSSCellObject

Returns the current cell value.

property CellValue: Variant;

Description

The CellValue property holds the cell’s unformatted value.  The value type returned by CellValue depends on the cell contents.  If the cell contains a date/time value (the DateTime property was set), the type of CellValue is varDate.  If the cell contains numbers, the returned type is varDouble.  For text contents the CellValue property returns the value of type varString.  If the cell contains a formula, CellValue gets the formula result.  In case of a formula error, the type of CellValue is varError and the property returns the error code corresponding to the TcxSSErrorCode enumerator.

ReadOnly Property


TcxSSCellObject.Col

TcxSSCellObject          See Also

Returns the zero-based index of the column to which a cell belongs.

property Col: Integer;

Description

Use this property to get the zero-based index of the column to which a cell belongs.  The row index, which contains the cell can be obtained via the Row property.

ReadOnly Property


TcxSSCellObject.DataType

TcxSSCellObject          See Also

Determines the type of data a specific cell contains.

type

  TcxSSDataType = (dtText, dtFunction, dtDateTime, dtControl);

property DataType: TcxSSDataType;

Description

Use the DataType property to determine the type of data stored in a cell.  Possible values for the DataType property include:

Value	Description
dtText	Contains a text value.
dtFunction	Contains a formula.
dtDateTime	Contains a date/time value.
dtControl	Contains a control (RESERVED FOR FUTURE USE).

ReadOnly Property


TcxSSCellObject.DateTime

TcxSSCellObject          See Also

Represents the date and time value for a cell.

property DateTime: TDateTime;

Description

The DateTime property value determines the contents of a specific cell if the DataType property is dtDateTime.  Use this property to get or set a cell value in date-time format.  When you assign the DateTime property DataType is automatically set to dtDateTime.  You can specify the formatting of a cell value by setting the Format member of the Style object to one of the predefined formats. To return a formatted cell value you can read the DisplayText property.

To assign a text or a formula to a cell use the Text property.

The following sample code sets the current date value to cell B2.

// Delphi

var ACell: TcxSSCellObject;

//...

ACell := cxSpreadSheetBook1.ActiveSheet.GetCellObject(1, 1);

with ACell do

  try

    DateTime := Date;

    Style.Format := $0e;

  finally

    ACell.Free;

  end;

// C++ Builder

TcxSSCellObject *cell;

cell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(1, 1);

try {

  cell->DateTime = Date();

  cell->Style->Format = 0x0e;

}

__finally {

  delete cell;

}


TcxSSCellObject.DisplayText

TcxSSCellObject          See Also

Specifies the text displayed within a particular cell.

property DisplayText: string;

Description

The DisplayText property returns a text representation of the cell’s actual value.  The cell value itself can be accessed via the Text or DateTime properties depending on the DataType property value.  The CellValue property provides you the ability to access a cell value regardless of its type.

DisplayText returns a cell value formatted using the format defined by the Format member of a Style object.

ReadOnly Property


TcxSSCellObject.DisplayTextAlignment

TcxSSCellObject          See Also

Specifies the manner in which displayed text is aligned within a cell.

property DisplayTextAlignment: TcxDisplayTextAlignment;

Description

The horizontal alignment of the cell contents is defined by the HorzTextAlign property.  When this property specifies a haGENERAL format, cell content is aligned according to its type.  Text is aligned to the left, numbers are aligned to the right, logical values are centered.  To determine what alignment is applied, you can use the DisplayTextAlignment property which returns the alignment of the TcxDisplayTextAlignment enumerator.

ReadOnly Property


TcxSSCellObject.Row

TcxSSCellObject          See Also

Gets the zero-based index of the row to which a cell belongs.

property Row: Integer;

Description

Use this property to get the zero-based index of the row to which a cell belongs.  The index of the column containing the cell can be obtained via the Col property.

ReadOnly Property


TcxSSCellObject.Style

TcxSSCellObject

Specifies cell style.

property Style: TcxSSCellStyle;

Description

The Style property represents a reference to the TcxSSCellStyle object, which is used to manage cell style.  Use the Style property to manipulate the font used to display the cell value, the border style of this cell, the format of the displayed value, etc.

The following sample code changes the style of the B2 cell within the active worksheet.

// Delphi

var

  ACell: TcxSSCellObject;

  AEdge: TcxSSEdgeBorder;

//...

ACell := cxSpreadSheetBook1.ActiveSheet.GetCellObject(1, 1);

try

  ACell.Text := 'ExpressSpreadSheet';

  with ACell.Style do

  begin

    with Font do

    begin

      Name := 'Impact';

      Size := 16;

      Style := [fsBold, fsUnderline];

      FontColor := 4; //clBlue

    end;

    with Brush do

    begin

      Style := fsSolid;

      BackgroundColor := 7; //clAqua

    end;

    with Borders do

      for AEdge := eLeft to eBottom do

      begin

        Edges[AEdge].Color := 4; //clBlue

        Edges[AEdge].Style := lsDouble;

      end;

  end;

finally

  ACell.Free;

end;

// C++ Builder

TcxSSCellObject *cell;

TcxSSCellStyle *cellStyle;

TcxSSEdgeBorder edge;

cell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(1, 1);

try {

  cell->Text = "ExpressSpreadSheet";

  cellStyle = cell->Style;

  cellStyle->Font->FontColor = 4; //clBlue

  cellStyle->Font->Name = "Impact";

  cellStyle->Font->Size = 16;

  cellStyle->Font->Style = TFontStyles() << fsBold << fsUnderline;

  cellStyle->Brush->Style = fsSolid;

  cellStyle->Brush->BackgroundColor = 7; //clAqua

  for (edge = eLeft; edge <= eBottom; edge = edge + 1) {

    cellStyle->Borders->Edges[edge]->Color = 4; //clBlue

    cellStyle->Borders->Edges[edge]->Style = lsDouble;

  }

}

__finally {

  delete cell;

}


TcxSSCellObject.StyleExist

TcxSSCellObject

Indicates whether the cell has its own style or uses book default style.

property StyleExist: Boolean;

Description

If the cell has it own style, returns True; if it uses the book default style - False.  The default style is provided by the TcxCustomSpreadSheetBook.DefaultStyle property.

ReadOnly Property


TcxSSCellObject.Text

TcxSSCellObject          See Also

Specifies the text contained within a specific cell.

property Text: string;

Description

The Text property value determines the contents of a specific cell if the DataType property is set to dtText or dtFunction.  Use the Text property to assign a text string or a formula to a cell.

If the string assigned to the Text property contains the "equal" (‘=’) character as a first valid symbol followed by text recognized as a formula, then the DataType attribute is automatically set to dtFunction.  If an error occurs while parsing a formula, the DataType is not changed and will keep its old value.  To avoid parsing the text string to a formula, call the SetCellText method.

Otherwise, if the ‘equal’ character is not found, the string is interpreted as a simple text and the DataType property is set to dtText.

When you assign the DateTime property, DataType is set to dtDateTime.

The cell’s value is formatted by using the TcxSSCellStyle.Format property of the Style object.  You can use one of the predefined formats to display a cell value.  To return a formatted cell value you can read the DisplayText property.

The following sample code sets text to the A1:F6 cell range.

// Delphi

var

  i, j: Integer;

//...

for i := 0 to 5 do

  for j := 0 to 5 do

    with cxSpreadSheetBook1.ActiveSheet.GetCellObject(i, j) do

      try

        Text := 'Cell [' + IntToStr(i) + ', ' + IntToStr(j) + ']';

      finally

        Free;

      end;

// C++ Builder

int i, j;

TcxSSCellObject *cell;

for (i = 0; i <= 5; i++)

  for (j = 0; j <= 5; j++) {

    cell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(i, j);

    try {

      cell->Text = "Cell [" + IntToStr(i) + ", " + IntToStr(j) + "]";

    }

    __finally {

      delete cell;

    }

  }


TcxSSCellObject.Create

TcxSSCellObject

Creates a TcxSSCellObject object instance with specific parameters.

constructor Create(AOwner: TcxSSDataStorage; ACol, ARow: Integer); virtual;

Description

The Create method is used to create an instance of the TcxSSCellObject object with the following parameters.  The AOwner parameter specifies the TcxSSDataStorage object responsible for internal data maintenance.  The ACol parameter specifies the column index of a cell for which the TcxSSCellObject object is being created.  The ARow parameter specifies the row index of a cell for which the TcxSSCellObject object is being created.

Do not use the constructor to create TcxSSCellObject object instances.  Use the GetCellObject method of the TcxSSBookSheet object instead.


TcxSSCellObject.Destroy

TcxSSCellObject

Destroys a TcxSSCellObject object instance.

destructor Destroy; override;

Description

The Destroy method is used to destroy an instance of the TcxSSCellObject object and release any allocated memory.

Note: You should not call the Destroy method in your application. Call the Free method instead.


TcxSSCellObject.SetCellText

TcxSSCellObject          See Also

Assigns the specified text to the current cell.

procedure SetCellText(const AText: string; const NeedParse: Boolean = False);

Description

If True is passed as the NeedParse parameter, calling this method is the same as assigning the AText string to the cell’s Text property.  So, if this string contains the "equal" (‘=’) character as a first valid symbol followed by text recognized as a formula, this formula will be automatically calculated.  Refer to the Text property description for more information.

If False is passed as the NeedParse parameter, the cell’s DataType property is set to dtText and its contents are replaced with the AText string.


TcxWorkBookSubControl
TcxWorkBookSubControl Object

Hierarchy          Methods

Represents a worksheet painter.

Unit

cxSSheet

TcxWorkBookSubControl = class(TInterfacedObject);

Description

The WorkBookSubControl provides a method for TcxSSBookSheet repainting.  The Invalidate method repaints the whole control and the InvalidateRect method repaints a specific rectangle.


TcxWorkBookSubControl Hierarchy
Hierarchy

TInterfacedObject


Methods for TcxWorkBookSubControl
TcxWorkBookSubControl Methods

TcxWorkBookSubControl          Legend

In TcxWorkBookSubControl

Create

Invalidate

InvalidateRect


TcxWorkBookSubControl.Create

TcxWorkBookSubControl

Creates an instance of a TcxWorkBookSubControl instance.

procedure Create(AOwner: TcxCustomSpreadSheetBook); virtual;

Description

The Create method is used to create a new instance of the TcxWorkBookSubControl object and initialize its properties.  After calling the inherited constructor, the Create method sets properties of the TcxWorkBookSubControl object to their default values.


TcxWorkBookSubControl.Invalidate

TcxWorkBookSubControl

Repaints a sheet.

procedure Invalidate;

Description

Call the Invalidate method when the entire sheet needs to be repainted.  When more than one region within the sheet needs repainting, Invalidate will cause the entire window to be repainted in a single pass, avoiding flicker caused by redundant repaints.  There is no performance penalty for calling the Invalidate method multiple times before the control is actually repainted.


TcxWorkBookSubControl.InvalidateRect

TcxWorkBookSubControl

Repaints a specified rectangle within a sheet.

procedure InvalidateRect(ARect: TRect);

Description

Call the InvalidateRect method when a rectangle within a sheet needs to be repainted.  The ARect parameter specifies the rectangle to repaint.  There is no performance penalty for calling the InvalidateRect method multiple times before the control is actually repainted.


cxSSTypes Unit Overview
cxSSTypes Unit

Classes

ESpreadSheetError

Other Types

Tcx3DArea

TcxDisplayTextAlignment

TcxHorzTextAlign

TcxVertTextAlign

TcxSSCellsModify

TcxSSDataType

TcxSSEdgeBorder

TcxSSEdgeLineStyle

TcxSSEdgeStyleRec

TcxSSFillStyle

TcxSSFontRec

TcxSSFuncRec

TcxSSFuncStates Type

TcxSSHitTestInfo

TcxSSHitType

TcxSSNameDefinition

TcxSSNavigatorBtn

TcxSSPainterType

TcxSortType

TcxStackItem

TRange


TcxSSNavigatorBtn
TcxSSNavigatorBtn type

See Also

Enumerates the available types of the sheet tab scrolling buttons.

Unit

cxSSTypes

TcxSSNavigatorBtn = (nbStart, nbPrev, nbNext, nbEnd);

Description

Value	Meaning
nbStart	Denotes the button that shows the first sheet in the spreadsheet control
nbPrev	Denotes the button that shows the previous sheet in the spreadsheet control
nbNext	Denotes the button that shows the next sheet in the spreadsheet control
nbEnd	Denotes the button that shows the last sheet in the spreadsheet control


TcxSSPainterType
TcxSSPainterType type

See Also

Specifies the manner in which worksheets are drawn.

Unit

cxSSTypes

TcxSSPainterType = (ptOffice97Style, ptOfficeXPStyle, ptCustom);

Description

TcxSSPainterType type values are used to set the appropriate painter type for drawing specific workbook elements (header, borders, cells).  This enumerator’s values are used to set the PainterType property value of the TcxSpreadSheet or TcxSpreadSheetBook object.

The TcxSSPainterType type includes the following values:

Value	Description
ptOffice97Style	A worksheet is drawn using Office 97® look and feel.
ptOfficeXPStyle	A worksheet is drawn using Office XP® look and feel.
ptCustom	Custom drawing.
Note: To perform custom workbook painting, you should implement your own painting class derived from the TcxSheetPainter object.  Then you should pass a reference to your designed class via the PainterClass parameter of the OnCustomPaint event.


TcxSSCellsModify
TcxSSCellsModify type

Specifies the manner in which cells are to be inserted/deleted.

Unit

cxSSTypes

TcxSSCellsModify = (msShiftCol, msShiftRow, msAllCol, msAllRow);

Description

TcxSSCellsModify type values are used to specify the manner in which the contents of surrounding cells are shifted when inserting/deleting a specific cell range.  These enumerator values are used to set the ACellsModify parameter value of the InsertCells and DeleteCells methods.

Value	Inserting Cells	Deleting Cells
msShiftCol	Cells are shifted to the right.	Cells are shifted to the left.
msShiftRow	Cells are shifted to the bottom.	Cells are shifted to the right.
msAllCol	Entire column is inserted.	Entire column is deleted.
msAllRow	Entire row is inserted.	Entire row is deleted.


TcxSSEdgeBorder
TcxSSEdgeBorder type

Specifies the edge of a cell.

Unit

cxSSTypes

TcxSSEdgeBorder = (eLeft, eTop, eRight, eBottom);

Description

These enumerator values are used to specify the edge of a cell.  They are used as a parameter for the Edges property of the TcxSSBorderStyle object.  This parameter specifies the edge to which a specific style is applied.

Value	Description
eLeft	Specifies the left edge of a cell.
eTop	Specifies the top edge of a cell.
eRight	Specifies the right edge of a cell.
eBottom	Specifies the bottom edge of a cell.


TcxSSEdgeLineStyle
TcxSSEdgeLineStyle type

Specifies the line style of a cell edge.

Unit

cxSSTypes

TcxSSEdgeLineStyle = (lsDefault, lsDotted, lsDashed, lsDashDotDot, lsDashDot, lsSlantedDashDot, lsThin, lsMediumDashDotDot, lsHair, lsMediumDashDot, lsMediumDashed, lsMedium, lsThick, lsDouble, lsNone);

Description

These enumerator values are used to set the line style of a cell edge.  They are used to set the Style property value of the TcxSSEdgeStyle object.  This property specifies the line style of a specific cell edge.

Value	Line appearance
lsDefault
lsDotted
lsDashed
lsDashDotDot
lsDashDot
lsSlantedDashDot
lsThin
lsMediumDashDotDot
lsHair
lsMediumDashDot
lsMediumDashed
lsMedium
lsThick
lsDouble
lsNone	No line is displayed.


TcxSSDataType
TcxSSDataType type

Determines the data type contained within a cell.

Unit

cxSSTypes

TcxSSDataType = (dtText, dtFunction, dtDateTime, dtControl);

Description

TcxSSDataType enumerator values specify the type of data contained within a cell.  These values are returned by the DataType property of the TcxSSCellObject object.

TcxSSDataType type includes the following values.

Value	Description
dtText	A cell contains a text value.
dtFunction	A cell contains a formula.
dtDateTime	A cell contains a date/time value.
dtControl	A cell contains a control (RESERVED FOR FUTURE USE).


TcxSSEdgeStyleRec
TcxSSEdgeStyleRec type

Represents a record whose fields are used to initialize TcxSSEdgeStyle class properties.

Unit

cxSSStyles

TcxSSEdgeStyleRec = record

    Style: TcxSSEdgeLineStyle;

    Color: Word;

end;

Description

Use this record to initialize properties of the TcxSSEdgeStyle class instances via its AssignRec method.  The field values for this record initialize the corresponding properties of a TcxSSEdgeStyle class instance.  The Style field value initializes the Style property.  The Color field value initializes the Color property.


TcxSSFillStyle
TcxSSFillStyle type

Represents a type whose values are used to set the fill pattern of a cell.

Unit

cxSSStyles

TcxSSFillStyle = (fsSolid, fsGray75, fsGray50, fsGray25, fsGray12, fsGray6,

   fsHorzStrip, fsVertStrip, fsRevDiagonalStrip, fsDiagonalStrip,

   fsDiagCrossHatch, fsThickCrossHatch, fsThinHorzStrip, fsThinVertStrip,

   fsThinRevDiagonalStrip,  fsThinDiagonalStrip, fsThinDiagCrossHatch,

   fsThinThickCrossHatch);

Description

Used to set the Style property value of the TcxSSBrush object.  This property sets the fill pattern of a cell.

Value	Cell appearance
fsSolid
fsGray75
fsGray50
fsGray25
fsGray12
fsGray6
fsHorzStrip
fsVertStrip
fsRevDiagonalStrip
fsDiagonalStrip
fsDiagCrossHatch
fsThickCrossHatch
fsThinHorzStrip
fsThinVertStrip
fsThinRevDiagonalStrip
fsThinDiagonalStrip
fsThinDiagCrossHatch
fsThinThickCrossHatch

This table implies that the BackgroundColor property of the TcxSSBrush object is 1, and the ForegroundColor property is 0.  In the default palette, these values identify white and black colors respectively.


TcxHorzTextAlign

Specifies the horizontal alignment of cell contents.

Unit

cxSSTypes

type

  TcxHorzTextAlign = (haGENERAL, haLEFT, haCENTER, haRIGHT, haFILL, haJUSTIFY);

Description

The horizontal alignment of a cell contents is provided by the TcxSSCellStyle.HorzTextAlign property. The following table describes TcxHorzTextAlign values:

Value	Description
haGENERAL	Aligns cell contents according to type.  Text is aligned to the left, numbers are aligned to the right, logical values are centered.
haLEFT	Aligns cell contents to the left side of a cell.
haCENTER	Horizontally centers cell contents within a cell.
haRIGHT	Aligns cell contents to the right side of a cell.
haFILL	Aligns cell contents to the left but always displays it truncated if it is too large for the cell width.
haJUSTIFY	Justifies cell contents horizontally.  Cell text is distributed evenly between the left and right cell edges.

For text that is too wide to fit within the confines of a cell and if the WordBreak property is set to True, text wraps and it is displayed across several lines of a cell.  Otherwise text can span several cells but only if neighboring cells are empty.  If neighboring cells are not empty, text is truncated within a cell.

The next image demonstrates two cells with wide text.  The WordBreak property is set to False.  The text in cell A1 is truncated since the neighboring B1 cell is not empty.  But the text of cell B1 is displayed completely because the C1 cell contains nothing.

The image below displays the same cells with the WordBreak property set to True.


TcxVertTextAlign

Specifies the vertical alignment of cell contents.

Unit

cxSSTypes

type

  TcxVertTextAlign = (vaTOP, vaCENTER, vaBOTTOM, vaJUSTIFY);

Description

The vertical alignment of a cell contents is provided by the TcxSSCellStyle.VertTextAlign property.

The following table describes the TcxVertTextAlign values:

Value	Description
vaTOP	Aligns cell contents to the top of a cell.
vaCENTER	Vertically centers cell contents.
vaBOTTOM	Aligns cell contents to the bottom of a cell.
vaJUSTIFY	Justifies cell contents vertically.  Cell text is distributed evenly between the top and bottom cell edges.


TcxDisplayTextAlignment

Specifies the actual horizontal alignment for the cell content.

Unit

cxSSTypes

type

  TcxDisplayTextAlignment = (dtaLEFT, dtaCENTER, dtaRIGHT, dtaFILL, dtaJUSTIFY);

Description

The horizontal alignment for the cell content is specified by the HorzTextAlign property of type TcxHorzTextAlign.  The values of the TcxDisplayTextAlignment and TcxHorzTextAlign types are almost identical except that the TcxHorzTextAlign provides an additional haGENERAL format which aligns cell contents based upon its type.  Text is aligned to the left, numbers are aligned to the right, logical values are centered.  Use the DisplayTextAlignment property to ascertain which alignment is applied to the cell’s contents.  It returns a value of the TcxDisplayTextAlignment enumerator.

The following table describes TcxDisplayTextAlignment values:

Value	Description
dtaLEFT	Cell content is aligned to the left side of a cell.
dtaCENTER	Cell content is centered.
dtaRIGHT	Cell content is aligned to the right side of a cell.
dtaFILL	Cell text is left aligned but is always truncated if it is too wide for the cell width.
dtaJUSTIFY	Cell text is justified horizontally.  It is distributed evenly between the left and right cell edges.


ESpreadSheetError
ESpreadSheetError Object

Hierarchy

The ESpreadSheetError object is an exception class for workbook manipulation errors.

Unit

cxSSTypes

ESpreadSheetError = class(Exception);

Description

An ESpreadSheetError exception is raised if an error occurs while an application is working with a workbook.  When the exception is raised, an error-message string is displayed.  Error messages are stored as constants within the cxSpreadSheetRes.pas file and are passed as a parameter to an exception constructor.

Error is raised in the following cases:

•	an application fails to read or set cell information;

•	an application attempts to access a worksheet using an invalid worksheet index;

•	an application specifies an invalid stream format when attempting to load workbook settings from a stream, file stream;

•	an application attempts to insert a formula that cannot be properly calculated (calculation of this formula leads to a formula cycling error).


ESpreadSheetError Hierarchy
Hierarchy

Exception


Tcx3DArea

Tcx3DArea represents coordinates and size of a cell group within a workbook.

Unit

cxSSTypes

  Tcx3DArea = packed record

    Page: Byte;

    Area: TRange;

  end;

Description

Three coordinates are necessary to locate a cell within a workbook.  The first represents the page containing a cell (the Page parameter).  The two other parameters represent coordinates of a cell within the page.  If a group of cells must be located, it is also necessary to know the size of the group.  These parameters are contained in type TRange.  So the Tcx3DArea type determines a cell or a group of cells within a workbook.


TRange

The TRange type defines a rectangle.

Unit

cxSSTypes

type

  TRange = packed record

    case Integer of

      0: (Left, Top, Right, Bottom: Integer);

      1: (TopLeft, BottomRight: Int64);

  end;

Description

The TRange type represents the dimensions of a rectangle.  The coordinates are specified both as four separate integer values representing the left, top, right, and bottom sides, and as two values representing the locations of the top left and bottom right corners.  Since TRange is usually used to represent a cell or a group of cells, the TopLeft and BottomRight values are included to determine whether the range represents a single cell or a group of cells.  If these values are equal, the range represents a singe cell; otherwise a group of cells.


TcxSSHitTestInfo
TcxSSHitTestInfo type

See Also

Contains information about the spreadsheet’s elements at the given point.

Unit

cxSSTypes

TcxSSHitTestInfo = record

    case HitType: TcxSSHitType of

      htSheetCell: (CellCol, CellRow: Integer);

      htSheetColumn: (Col: Integer);

      htSheetRow: (Row: Integer);

      htSheetCaption: (Page: Integer);

      htCaptionButton: (Button: TcxSSNavigatorBtn);

  end;

Description

State	Values
htSheetCell	The cell’s position as a zero-based index in the column and row
htSheetColumn	The column’s position as a zero-based index in the sheet
htSheetRow	The row’s position as zero-based index in the sheet
htSheetCaption	The sheet’s position as zero-based index in the spreadsheet control
htCaptionButton	The sheet tab scrolling button's flag


TcxSSHitType
TcxSSHitType type

See Also

Enumerates the available types of the hit regions.

Unit

cxSSTypes

TcxSSHitType = (htSheetCell, htSheetColumn, htSheetRow, htSheetCaption, htCaptionButton);

Description

Value	Meaning
htSheetCell	Denotes a cell in the sheet
htSheetColumn	Denotes a column in the sheet
htSheetRow	Denotes a row in the sheet
htSheetCaption	Denotes a sheet tab
htCaptionButton	Denotes a sheet tab scrolling button


TcxSSNameDefinition

TcxSSNameDefinition represents the defined name.

Unit

cxSSTypes

type

  TcxSSNameDefinition = packed record

    Name: string;

    Definition: Tcx3DArea;

    IsDeleted: Boolean;

  end;

  PcxSSNameDefinition = ^TcxSSNameDefinition;

  TcxSSNamesDef = array of TcxSSNameDefinition;

Description

The TcxSSNameDefinition type represents the defined name for a cell in a group of cells.

The Name field represents a name of a cell or a group of cells.

The Definition field represents coordinates of a cell or coordinates and size of a group of cells.

The IsDeleted field specifies whether the defined name is marked as deleted.  These names are ignored when the DefinedNames collection is searched for specific names (for instance, when the CellsNameByRef function is called).  For names marked as deleted, the IsDeleted field is equal to True.  Otherwise – False.

Note:	Do not modify the IsDeleted field value.  This may result in wrong defined name behavior when cells, columns, or rows are deleted.  Call the DeleteName function instead.


TcxSSFuncRec Type

Contains information about a specific formula.

Unit

cxSSTypes

type

  TcxSSFuncRec = packed record

    Page: Integer;

    Col: Integer;

    Row: Integer;

    FuncTree: TcxStackItem;

    CalcResult: TcxStackItem;

    IterationCount: Integer;

    States: TcxSSFuncStates;

    IsBusy: Integer;

  end;

Description

The TcxSSFuncRec record is used to represent a specific formula and contains all settings required for that formula’s use. This record’s fields specify the location of the required formula within a sheet, the arrays of tokens representing the formula and its result, etc.

Value	Meaning
Page	Specifies a page where a specific formula is located.
Col	Specifies a column where a specific formula is located.
Row	Specifies a row where a specific formula is located.
FuncTree	Specifies an array of tokens representing a formula in the tokens stack.
CalcResult	Specifies an array of tokens representing a formula result in the tokens stack.
IterationCount	Specifies the number of iterations in which the current formula has been involved.
States	Specifies a value representing a formula’s return value type.
IsBusy	Specifies that a specific formula has been evaluated during the current iteration.


TcxStackItem Type

Represents a parsed formula within the parsed formula stack.

Unit

cxSSTypes

type

  TcxStackItem = packed record

    Size: Word;

    Tokens: PByteArray;

  end;

Description

Before calculation, each formula must be parsed into an array of tokens which can be recognized by ExpressSpreadSheet. All tokens representing formulas are stored in the tokens stack. During formula calculation, ExpressSpreadSheet extracts tokens belonging to a specific formula and executes the formula. The TcxStackItem record represents an array of tokens within the tokens stack. The Size field contains the size of the tokens array belonging to a specific formula. The Tokens field contains an array of tokens.


TcxSSFuncStates Type

Specifies the result of a formula calculation.

Unit

cxSSTypes

type

TcxSSFuncStates = (fsError, fsBool, fsSource);

Description

Value	Meaning
fsError	Specifies that an error occurred during formula execution.
fsBool	Specifies that a formula has a Boolean result.
fsSource	Specifies that a formula result is determined according to the formula and its argument types.


TcxSSFontRec

Specifies a structure to store information about a font.

Unit

cxSSTypes

type

  TcxSSFontRec = packed record

    Name: string;

    FontColor: Word;

    Style: TFontStyles;

    Charset: TFontCharset;

    Size : ShortInt;

  end;

Description

The TcxSSFontRec record stores information about a font.  The following table describes the TcxSSFontRec fields:

Value	Meaning
Name	Identifies the typeface of the font.  If the font family described by Name includes multiple character sets, be sure to set the Charset property as well.
FontColor	Specifies the color of the text.  FontColor specifies the color index in the palette.
Style	Determines the style of the font.  Refer to the description of the TFontStyles type.
Charset	Specifies the character set of the font. Refer to the description of the TFontCharset type.
Size	Specifies the height of the font in pixels.


TcxSortType
TcxSortType type

Represents a sort order for a column in a worksheet.

Unit

cxSSTypes

TcxSortType = (stAscending, stDescending);

Description

The TcxSortType type enumerates sort orders.  Use the TcxSSBookSheet.Sort method to sort spreadsheet values against multiple columns.  It is possible to specify a sort order for every column by passing an array of TcxSortType values.


Overview

Written from the ground-up, the ExpressSpreadSheet fully exploits and extends upon our many years of experience in building visual controls for the Windows® family of operating systems.

The ExpressSpreadSheet is a visual, multi OS compatible component.  It works in a similar fashion on both Windows® and Linux® operating systems.

At the heart of the ExpressSpreadSheet lies a simple premise - improve and enhance developer productivity.  With a massive collection of advanced features developers only need to specify simple property settings or write one line method calls to build cutting edge interfaces!

The following is a short summary of the features available to you in the ExpressSpreadSheet:

•	Built-in functions - ExpressSpreadSheet contains a number of useful built-in functions that allow you to simplify formulas construction.  See the Built-in Operators and Functions topic for details.

•	In addition to built-in functions, you can construct custom functions, even from external dynamic link libraries.  Refer to the Register Custom Functions topic for information on adding your own functions and using them within your SpreadSheet.

•	Import/Export to Excel files - ExpressSpreadSheet natively works with MS Excel® files, allowing you to easily import data form Excel files, work with them and store ExpressSpreadSheet data using MS Excel file formats.  Review the Export and Import Data topic to learn the ways in which data from the spreadsheet can be exported and imported.

•	Full support for Borland Delphi 4, 5, 6, C++ Builder 4, 5, 6 and Kylix 2.

•	MS Excel style cell insertion and deletion.  Refer to the Managing Cells topic for a detailed description and code examples.

•	ExpressSpreadSheet enables you to apply individual formatting to cells.  You can customize the cell borders style, background, foreground colors, brush, font attributes, vertical and horizontal alignments, and the display text format.  The Change Cell Style topic will guide you through the process of cell style management.

•	ExpressSpreadSheet provides safe merge/unmerge operations - after cells are unmerged the styles and data they contained prior to merging are completely and safely restored to their original state.  Refer to the Merge/Split Cells topic for detailed information on how to merge and split cells.

•	You can sort data against multiple columns.  ExpressSpreadSheet enables you to specify a sort order for every column.  Refer to the Sorting Data topic to get acquainted with the sorting feature.

•	ExpressSpreadSheet provides you with two predefined painting styles: Office 97 style and Office XP style.  In addition, you can implement your own custom style via the custom painting feature available within the component library. The Perform Custom Painting topic describes the basics of our custom spreadsheet drawing implementation.

•	ExpressSpreadSheet allows you to hide and display columns and rows.  Review the Hiding a Row or a Column topic to find out how rows and columns can be hidden and made visible again.

•	The ability to change the width/height of any column/row within the active and a specified worksheet.  You can also change the height/width of the column/row header panel and default width/height of columns/rows.  These values can be easily adjusted at design and runtime by the end user and in code.  See the Working with Headers topic for the detailed information and examples.

•	ExpressSpreadSheet maintains the history of actions you perform on data.  When you perform such operations as formatting, inserting, deleting, clearing cells, changing cell contents, merging/splitting cells and sorting cells, ExpressSpreadSheet stores the changes and allows you to undo and redo operations.

For more information on the ExpressSpreadSheet, visit us online at:

http://www.devexpress.com/


Class Structure

This topic covers the class structure and interaction analysis of the ExpressSpreadSheet Library components.

Hierarchical Class Structure

Interaction Among Classes

Hierarchical Class Structure

The hierarchical class structure of the ExpressSpreadSheet components (ExpressSpreadSheetBook and ExpressSpreadSheet) is rather straightforward and is described in the following image.

The common ancestor for all native cross-platform windowed controls by Developer Express Inc. is a TcxControl object.  It is used to create native cross-platform windowed controls that do not correspond to standard Windows components.

The main functionality of a workbook is implemented within the TcxCustomSpreadSheetBook object, which is a direct descendant of the TcxControl object.  The TcxCustomSpreadSheetBook object fully implements ExpressSpreadSheetBook functionality and contains a number of methods and properties that are available in its direct descendants.

The TcxSpreadSheetBook object is derived directly from the TcxCustomSpreadSheetBook class and represents an ExpressSpreadSheetBook component that can manage several worksheets (each worksheet is represented by an individual TcxSSBookSheet object).  The TcxSpreadSheetBook object does not introduce any new functionality.  This is a ‘published’ variant of the TcxCustomSpreadSheetBook object, which fully implements ExpressSpreadSheetBook component functionality.

The TcxSpreadSheet object is also derived directly from the TcxCustomSpreadSheetBook class but represents a workbook with a single sheet - the ExpressSpreadSheet component.  The worksheet is represented by the TcxSSBookSheet object.  Unlike the TcxSpreadSheetBook object, the TcxSpreadSheet object is a scaled-down version of the TcxCustomSpreadSheetBook object.  The TcxSpreadSheet object inherits only properties and methods related to a single worksheet.

The TcxWorkBookSubControl class is the base class for spreadsheet elements such as TcxSSBookSheet and TcxSSBookPageCaptions objects.  It provides functionality to handle system events and declares a canvas object on which to draw control information.

The TcxSSBookSheet represents the actual worksheet.  It contains internal and accessible properties and methods, which provide worksheet functionality including data storage and processing.  The TcxSSBookPageCaptions class represents a panel at the bottom of the workbook window that displays worksheet names.

Interaction Among Classes

The ExpressSpreadSheet component library offers highly efficient data processing and data storage features as a result of its object structure and interaction among classes.  This topic represents a brief overview of internal data storage and class interaction and helps you better understand the relationships therein.

As a spreadsheet control, ExpressSpreadSheetBook needs to store and process the values contained within cells and cell styles for each workbook sheet.  So the ExpressSpreadSheetBook component has three main internal record types, which store cell data, cell formulas, and cell styles.  These record types are TcxSSCellRec, TcxSSFuncRec, and TcxSSCellStyleRec respectively.

The main object that internally processes all data (text, formulas, styles) entered or changed within cells of an individual worksheet is the TcxSSDataStorage object.  This object can create, change, and clear any TcxSSCellRec record that contains cell data.  Additionally, each TcxSSCellRec record contains references to the applied cell style (TcxSSCellStyleRec record) and to the contained formula (TcxSSFuncRec record), if any.

The TcxSSFormulasCache object is used for internal formula processing.  This object can be referred to as a cache that contains all calculated formulas used in a workbook at runtime.  The TcxSSFormulasCache object uses the TcxSSFunctionHandler object for internal formula calculation.  The TcxSSFormulasCache object can create, change, and clear the TcxSSFuncRec records each of which contains information about a specific cell formula (location of the corresponding cell, formula calculation tree, calculated formula result, etc).  The TcxSSFormulasCache object uses a specific PcxSSFuncRec pointer to access a particular TcxSSFuncRec record.

The TcxSSStyleCache object is used for internal cell style processing.  This object can be referred to as a cache that contains all unique cell styles used within a workbook.  The TcxSSStyleCache object uses the TcxSSCellStyle object to manage cell style.  The TcxSSStyleCache object can create, change, and clear TcxSSCellStyleRec records each of which contains information about a specific cell style (border styles, font attributes, etc).  The TcxSSStyleCache object uses a specific PcxSSCellStyleRec pointer to access a particular TcxSSCellStyleRec record.  The unique feature of our cell style storage is that any specific cell style is stored only once even if it is applied to several cells of several worksheets within a workbook.  For instance, after a workbook is created, all workbook sheets cells have a default style but this style is not duplicated for each workbook cell.  The TcxSSStyleCache object generates a single TcxSSCellStyleRec record fully describing the default style and all the cells refer to this record using the PcxSSCellStyleRec record pointer.  Every TcxSSCellStyleRec record contains a number of references to the record (reference count).  When it equals 0 (none of the cells use the style), the memory space occupied by the record is considered free.  This approach maximizes memory efficiency.

Let’s review class organization after a workbook is created.

When a TcxCustomSpreadSheetBook object is being created, it initializes its properties with default values and additionally creates instances of the TcxSSFormulasCache and TcxSSStyleCache, TcxSheetPainter and TcxSSBookPageCaptions objects.

•	Created together with the TcxCustomSpreadSheetBook object, the TcxSSStyleCache and TcxSSFormulasCache objects are used to manage styles and formulas of all workbook cells.  For the moment, there are no TcxSSFuncRec records representing cell formulas and there is a single TcxSSCellStyleRec record that represents the default cell style within the workbook.

•	The TcxSheetPainter object is used to paint a workbook sheet (represented via the TcxSSBookSheet object) in the manner specified by the PainterType property of the TcxCustomSpreadSheetBook class.  If custom worksheet painting is necessary, a developer should generate his own painting class derived from the TcxSheetPainter object.  See the About Worksheet Painting topic for more information.

•	The TcxSSBookPageCaptions object represents a panel at the bottom of the workbook window that displays worksheets names.

To add a worksheet to a workbook, the AddSheetPage method is used. It creates an instance of the TcxSSBookSheet object which represents a single worksheet.  The TcxSSBookSheet object initializes some of its properties and creates the TcxSSHeader, TcxSSDataStorage, and TcxSSheetViewInfo objects.

•	The TcxSSHeader object represents a header panel, which displays column letters at the top of a worksheet or row numbers on the left side of a worksheet.

•	The TcxSSDataStorage object is the main object that internally processes all cell data for an individual worksheet as described above.

•	The TcxSSheetViewInfo object is created for each worksheet and contains a set of properties necessary for the complete and correct drawing of a specific worksheet.  When a worksheet must be drawn (or redrawn), the TcxSheetPainter class uses the information contained in the TcxSSheetViewInfo class to perform it.

Another significant class is TcxSSCellObject.  It represents an object for a specific cell.  The TcxSSCellObject object is developed to make cell manipulations easier.  Using a cell object you can change cell contents and adjust its style.  To get a TcxSSCellObject object for an individual cell you should call the TcxSSBookSheet.GetCellObject method with a cell column and row as cell coordinates.  All changes made in a cell object are automatically written to the corresponding TcxSSCellRec record and affect the TcxSSFuncRec and TcxSSCellStyleRec records if necessary.

There is one more class used by the TcxSSCellObject object when editing cell values.  The TcxSSCustomInplaceEdit object represents a cell editor that helps a user enter data into a cell.  If the cell being edited contains a value, the TcxSSCustomInplaceEdit object receives this text value from the TcxSSDataStorage object and displays it within its edit box.  After editing is completed, the TcxSSCustomInplaceEdit object passes a new text value of the cell to the TcxSSDataStorage object.


About Workbooks
About Workbooks and Two Types of Worksheets

The ExpressSpreadSheet contains two components: ExpressSpreadSheetBook and ExpressSpreadSheet.  Each of these controls gives you the ability to introduce SpreadSheet functionality in your applications.

ExpressSpreadSheetBook component

The ExpressSpreadSheetBook component is a workbook in which you can work and store your data.  Since each workbook can contain a number of sheets, you can organize various kinds of related information with the help of a single ExpressSpreadSheetBook component.  The ExpressSpreadSheetBook component is represented by a TcxSpreadSheetBook object.  Visually, each workbook can consist of two logical parts: the first is an active worksheet (every individual worksheet is represented by the TcxSSBookSheet object), and the second is a caption bar.

The caption bar is a tab control near the bottom of a workbook that displays the names of workbook sheets.  It is used to move from sheet to sheet (make a sheet active) and to scroll through sheet tabs.

ExpressSpreadSheet component

The ExpressSpreadSheet component is designed to be a workbook, which does not have the ability to manage several worksheets.  This component represents a workbook with a single sheet (this sheet is represented by the TcxSSBookSheet object).  So the ExpressSpreadSheet component (the TcxSSBookSheet object) is a scaled-down version of the ExpressSpreadSheetBook component and is used only for single worksheet manipulations.  Thus, the ExpressSpreadSheetBook component has no caption bar.

TcxSSBookSheet object

An individual worksheet represented by the TcxSSBookSheet object is a document that you use to store and work with data.  A worksheet consists of cells that are organized into columns and rows.  A worksheet contains row and column header panels, which correspondingly display row numbers on the left side of the sheet and column letters at the top of the sheet.

A worksheet represented by the TcxSSBookSheet object is always stored in a workbook (either in the ExpressSpreadSheetBook component or in the ExpressSpreadSheet component).  Use worksheets to list and analyze data.  You can enter and edit data on several worksheets simultaneously and perform calculations based on worksheet data.  Moreover, as a descendant of the TcxControl class the TcxSSBookSheet object is considered to be an individual control that can be visually located not only within its workbook, but can also be displayed within other controls.  As a result, you can display several worksheets of the same workbook simultaneously.

Please refer to the Managing Worksheets topic for a detailed description of worksheet manipulations and code examples.


About Worksheet Headers

In this topic, we will describe the essence of SpreadSheet headers, how they can be changed, locked and hidden.

•	Double meaning of the TcxSSHeader object

•	Changing header size

•	Locking a row or a column

•	Hiding a row or a column

Double meaning of the TcxSSHeader object

Each worksheet contains a row header panel and a column header panel.  These panels contain row and column headers respectively.  The TcxSSHeader object is used to represent both kinds of header panels.  You can retrieve an instance of this class representing the column header panel via the Cols property. The TcxSSHeader class instance corresponding to the row header panel can be retrieved via the Rows property.

The manner in which header type for a row or a column is applied is determined via the Kind property of the TcxSSHeader object.  When the header is a row, the property contains a htRow value.  If the header is a column header, the Kind property contains an htCol value. The image below shows both kinds of headers.

Note that the very first cell above the first row header belongs to no specific header.

Changing header size

To change the size of a header, you must use the Size property. The purpose of this property depends upon the type to which the header currently refers.  If a TcxSSHeader class instance represents the column header panel, its Size property specifies the width of a specific header. If it represents the row header panel, it sets or gets header height.  To change other height/width of the column/row header panel you should use the ColHeaderHeight / RowHeaderWidth property of the TcxCustomSpreadSheetBook class.  These properties are inherited by both the TcxSpreadSheet and TcxSpreadSheetBook objects.

The Size property is indexed, i.e. you have to specify a row/column index to access the width/height of individual column/rows.

Locking a row or a column

If a column or a row is locked, a user is no longer able to change the contents of this column or row, its dimensions, or visibility.

To lock a column or a row, use the Lock member of a header object.  The Lock property is indexed, i.e. you have to specify a row/column index to access the ‘Lock’ status of an individual row or column.

Note: In spite of being locked, the formulas a column or a row contains remain active.

Hiding a row or a column

You can both hide a row or a column. This is useful, for instance, when there are a number of columns or rows that contain formulas which you do not want to appear on screen.

Use the Visible property of the TcxSSHeader object in order to hide a specific column or row.  The same property allows you to make columns and rows visible. The Visible property is indexed, i.e. you have to specify a row/column index to access the visibility status of an individual row or column.

You can also use the SetVisibleState method in order to hide column(s), row(s) or column(s) and row(s) together.  This method is implemented in the TcxSpreadSheet and TcxSSBookSheet objects.


About Worksheet Cells

Cell data storage concept

ExpressSpreadSheet doesn’t store information about each cell as a separate object.  Instead it provides a TcxSSDataStorage class, which manipulates data stored within worksheet (workbook) cells.  This class stores a set of pointers to TcxSSCellRec records. These records contain information about non-empty cells.  Fields of the TcxSSCellRec record include pointers to the style used by a cell and the formula used to calculate its value. It allows you to store only unique styles.  For instance, when creating a worksheet there is only one default style stored to which all cells refer.

Please refer to the Class Structure topic for details on internal data representation.

Accessing Cells

Due to the class structure of the ExpressSpreadSheet, cells are accessed via the GetCellObject method of a worksheet presented by the TcxSSBookSheet object.  The desired worksheet can be retrieved via the ActiveSheet or Pages property of a TcxSpreadSheetBook control and the Sheet property of a TcxSpreadSheet control.

The GetCellObject method retrieves a TcxSSCellObject object.  Once the TcxSSCellObject object is retrieved, you can change the contents, style and format of the corresponding cell using its properties.  When you finish working with the cell object, you have to delete it yourself in order to prevent memory leakage.

Entering Data into Cells

ExpressSpreadSheet provides two ways to enter data into cells: manually or in code.

If the ExpressSpreadSheet has focus and none of its cells are being edited, the text typed by a user is written to the active cell.  In this instance, active cell text is erased when typing the first symbol.  In order to modify a cell value without erasing its contents a user should double-click the desired cell.  This activates the cell editor and its text is not lost.

There are three ways in which a user can terminate cell editing. The TAB key stops editing, and focus moves to the next cell.  The ENTER key stops editing and moves focus one cell down.  The last method is to move focus to another cell using the mouse.

In order to enter a cell value in code, you should use the Text or DateTime property of the TcxSSCellObject object corresponding to the desired cell.  These properties are used to enter text (formula) or a date value respectively.

See the Using Formulas topic for more information on how to enter a formula.

Selecting Cells

A user can select cells in two ways.  The first one is to click a cell and drag the mouse to the cell, which will represent the opposite corner of the selection.  The second is to use the keyboard Arrows keys while holding the SHIFT key.

To manipulate selections use the SelectionRect property of the TcxSSBookSheet object.  The desired TcxSSBookSheet class instance can be retrieved via the ActiveSheet or Pages property of a TcxSpreadSheetBook control and the Sheet property of a TcxSpreadSheet control.

Hiding/Display Cells

In order to hide/display a single row or a column it is best to use the Visible property of the TcxSSHeader object.

The TcxSSBookSheet.SetVisibleState method allows you to hide/display a set of cells within a worksheet.  A worksheet can be specified either by the ActiveSheet or Pages property of a TcxSpreadSheetBook control and the Sheet property of a TcxSpreadSheet object.

Inserting/Deleting Cells

Cells can be inserted/deleted by shifting cells in columns or rows to which they belong or inserting/deleting the entire rows or columns.

To insert/delete cells use the InsertCells and DeleteCells methods implemented in the TcxSSBookSheet class.  A worksheet can be specified either by the ActiveSheet or Pages property of a TcxSpreadSheetBook control and the Sheet property of a TcxSpreadSheet object.

Formatting Cells

Formatting of cells is realized via the Style property of the TcxSSCellObject object.  This property returns a TcxSSCellStyle object.  Modify its property values in order to change the font, border style, fill pattern, text alignment etc. used to display a cell and its contents.

Clearing Cells

You can clear cells’ contents and style formatting, if needed, which means that cells’ contents (not the cells themselves) are deleted and style is reset.

The ClearCells method implemented in the TcxSSBookSheet class allows you to clear contents and optionally the style formatting for a specific cell range.  Two other methods (TcxSSBookSheet.ClearAll and TcxCustomSpreadSheetBook.ClearAll) enable you to clear all cells within a worksheet and within all worksheets of a workbook respectively.

A user can clear cells by selecting the required cell range and pressing the Del keyboard key.

Sorting Cells

Worksheet data can be sorted against multiple columns and you can define the sort order for every column.  When sorting, cell values are exchanged according to the sort order specified for each column.

Use the TcxSSBookSheet.Sort method to perform sorting of cell data within a specific range.


About Formatting Styles

Style Data Storage Concept

ExpressSpreadSheet doesn’t store information about each cell as a separate object.  Instead it provides a TcxSSDataStorage class, which manipulates data stored within worksheet (workbook) cells.  This class stores a set of pointers to TcxSSCellRec records.  These records contain information about non-empty cells.  Fields of the TcxSSCellRec record include pointers to the style used by a cell and the formula used to calculate its value.  This allows you to store only unique styles.  For instance, when creating a worksheet, there is only one default style stored to which all cells refer.

Each record representing a cell style contains fields representing text alignment, font pointer, format index, fill pattern, background and foreground color of the brush border style and reference counter.  Fonts and format strings (an index similar to MS Excel formatting style is used) applied to worksheet cells are stored separately.  Individual cells point to the desired font record and format string within corresponding collections.  Thus only unique fonts and format string settings are stored.  The reference counter specifies the number of cells that use the style.  If this field is 0, a record is removed from memory (none of the cells refers to this style).

Please refer to the Class Structure topic for details on internal data representation.

Accessing Cell Style

Due to the class structure of ExpressSpreadSheet, cell styles are accessed via the Style property of the TcxSSCellObject object.  The TcxSSCellObject class instance corresponding to a specific cell within a worksheet can be obtained via the TcxSSBookSheet.GetCellObject method.  You can read the ActiveSheet or Pages property of a TcxSpreadSheetBook control and the Sheet property of a TcxSpreadSheet control to access a desired worksheet.

When the GetCellObject method is called, the record containing information about the style of a specific cell is read.  This information is written to the properties of the TcxSSCellStyle class instance returned by the Style property of the TcxSSCellObject object.  If these property values are changed and there is no record, which stores the same style information, a new record is created and its reference counter is set to 1.  If the record containing the same style information already exists, its reference counter is incremented.  The style information record, to which a particular cell refers, is specified by the style pointer field of the TcxSSCellRec record containing information about this cell.

Styles cannot be accessed directly via corresponding records.  The reason is that it leads to style modifications of all cells referring to this style. The default style of cells can be adjusted via the DefaultStyle property of both the TcxSpreadSheet and TcxSpreadSheetBook objects.

Please refer to the Change Cell Style topic for more information on cell style modifications and code examples.


About Cell Formatting

ExpressSpreadSheet provides the built-in Format cells dialog allowing a user to adjust cell formatting at runtime.  This dialog is invoked when you call the TcxSSBookSheet.FormatCells method.  FormatCells has only one parameter and this defines the cell range to which the formatting should be applied.

Using the Format cells dialog a user can specify the content format, alignment, style of the border and background.  The dialog has four corresponding tabs:

Cell style

The Cell style page displays the range of formats supported by ExpressSpreadSheet.  They are divided into several groups according to types of values to which the format can be applied.  For instance, the Date/Time group contains the set of formats related to displaying date/time values.

Using the radio buttons at the Style type panel you can jump quickly to the required group of formats.

You can apply formatting by selecting the required format item from the Style settings panel and then clicking the Ok button.

Alignment

This page allows the user to specify the horizontal and vertical alignments of the cell contents, specify the font and set word wrapping on or off.

Horizontal text alignment

General – aligns the cell contents according to its type. Numerical values are aligned to the right, text is aligned to the left, logical values are centered.

Left – the content is left aligned

Center – the content is centered

Right – the cell data is right aligned

Fill – truncates the cell text if it is too long for the cell width.

Justify – justifies the text so that words are distributed evenly between the left and right cell edges

Vertical text alignment

Top – aligns the text to the top

Center – the cell text is centered vertically

Bottom – aligns the text to the bottom of a cell

Justify – justifies the text vertically so that lines are distributed evenly between the top and bottom edges

The page also allows you to change the font of cell text.  To activate the font dialog, click the Font button.

The Word wrap	 check box controls whether the text in a cell is displayed in several lines if it too long for the cell width.  If set to off, the text is truncated at the end of the first line, even if there is space for further lines.

The Sample panel allows you to see the results of text formatting before applying styles to worksheet data.  Whenever you change settings on the tab, the sample string is redrawn with the potential changed settings.

Border

The Border page allows the cell border style and color to be modified.

The edge styles are presented in the Line panel.

Click a specific line on the panel and then apply it to a required border.  You can perform this in two ways:

•	using the nine buttons arranged around the sample cells panel

•	clicking near the border on the sample cells panel

The None button clears all the border formatting of the selection.

The Outline button outlines the selection with the border style specified.

The Inside button applies the formatting to the internal cell edges within the selected cell.  This button is disabled if one cell only is provided to the dialog.

There are six more buttons which specify formatting of some of the borders only, namely:

•	the top border of the cell range

•	internal horizontal borders

•	the bottom border of the cell range

•	the left border of the cell range

•	internal vertical borders

•	the right border of the cell range

You can specify color of the borders via the Color popup dialog.

Patterns

The Patterns page contains control elements defining the background color and fill pattern for cells.

The Color panel displays the background colors supported by ExpressSpreadSheet.  Using the Pattern option, you can apply one of the fill patterns and can also specify the foreground color for it.


Using Formulas

In this topic, we will describe the essence of SpreadSheet formulas, how they can be constructed, cell references and how to use worksheet function.

•	What is a formula

•	Constructing a formula

•	Referring to cells

•	Using worksheet functions

What is a formula

A formula is an equation that carries out specific operations against worksheet data.  Formulas can perform mathematical operations, such as addition and multiplication, or they can compare worksheet values or join text.  Formulas can refer to other cells on the same worksheet, cells on other sheets in the same workbook.

Note: formulas cannot refer to other cells on sheets in other workbooks.

The following example adds 600 to the value in cell A1 and then divides the result by the sum of the values in cells C1 and E1.

Constructing a formula

Formulas calculate values in a specific order.  A formula in the ExpressSpreadSheet always begins with an equal sign (=).  An equal sign tells the ExpressSpreadSheet that all subsequent characters constitute a formula.  Following the equal sign are the elements to be calculated (the operands), which are separated by calculation operators.  Each element can be a function call with parameters.  The ExpressSpreadSheet calculates formulas from left to right, according to the specific order of each operator in the formula.  You can change the order of operations by using parentheses.

Note:	The symbol, which is used to separate arguments and parameters in the ExpressSpreadSheet, depends on local regional settings.  If DecimalSeparator and ListSeparator provide the same values, a semicolon is used as a separator.

Referring to cells

A formula can refer to constant values and to other cells.  A cell that contains a formula is known as a dependent cell when its value depends on other cell values.  For example, cell B2 is a dependent cell if it contains formula ‘= C2’.  There are two types of cell addressing in the ExpressSpreadSheet: relative addressing and absolute addressing.  The first assumes that if you delete a column, all addresses will be changed accordingly, its designation is ‘= C2’ (or ‘= R2C3’ if the R1C1ReferenceStyle property is set to True).  So, if column A is deleted, this address will change to ‘= B2’ (‘= R2C2’).  Absolute addressing does not change when a column is deleted, its designation is ‘= $C$2’ (or ‘= R[-2]C[-3]’ if the R1C1ReferenceStyle property is set to True).

Whenever the cell to which a formula refers changes, the dependent cell also changes by default.  If you enter a formula manually, the AutoRecalc property must be True in order to enable automatic formula calculation.  If a formula is entered in code, you should use the Recalc method to calculate its value (the AutoRecalc property must also be set to True in this instance).

If you use constant values instead of references to cells (for example, ‘= 30 + 70 + 110’), the result changes only if you modify your formula.

Formulas can also refer to a range of cells.

Using worksheet functions

The ExpressSpreadSheet contains a number of predefined or built-in formulas which are known as functions.  Functions can be used to perform simple or complex calculations.  The most frequently used function is the SUM function, which is used to add numbers in a range of cells.

The image above shows how to use the SUM function to add values in range C1:D1.


Built-in Operators and Functions

The SpreadSheet provides a number of predefined (built-in) operators and functions.  Operators perform basic operations while functions are used to perform more complex calculations.  The operators and functions can be divided into groups as follows:

•	Arithmetic Operators

•	Logical Operators

•	Arithmetic Functions

•	Logical Functions

•	Statistical Functions

•	Date and Time Functions

•	Text Functions

•	IS Functions

Arithmetic Operators

Arithmetic operators allow you to perform basic arithmetic operations.

Mnemonics	Operand Type	Example	Explanation
+	Two arguments	= 5 + B1	Adds the first argument’s value to the value of the second argument.
-	Two arguments	= A5 - B1	Subtracts the second argument’s value from the value of the first one.
*	Two arguments	= A2 * A3	Multiplies the first argument’s value by the value of the second argument.
/	Two arguments	= A1 / PI()	Divides the first argument’s value by the value of the second argument.
^	Two arguments	= B1 ^ A2	Raises the first argument’s value to the power determined by the second argument’s value.

Logical operators

Logical operators perform comparison operations and return a logical value (TRUE or FALSE) as a result.

Mnemonics	Operand Type	Example	Explanation
=	Two arguments of logical types	= A1=A2	The equality operation.  Returns TRUE if the first argument is equal to the second one.  Otherwise, returns FALSE.
<>	Two arguments of logical types	= A1<>B2	The inequality operation.  Returns TRUE if values within the list are not equal.  Otherwise, returns FALSE.
<	Two arguments of logical types	= A1<B1	The "Less than" operation.  Returns TRUE if the first argument is less than the second one.  Otherwise, returns FALSE.
>	Two arguments of logical types	= A1>100	The "Greater than" operation.  Returns TRUE if the first argument is greater than the second one.  Otherwise, returns FALSE.
<=	Two arguments of logical types	= A2<=C4	The "Less than or equal to" operation.  Returns TRUE if the first argument is less than or equal to the second one.  Otherwise, returns FALSE.
>=	Two arguments of logical types	= A2>=1.57	The "Greater than or equal to" operation.  Returns TRUE if the first argument is greater than or equal to the second one.  Otherwise, returns FALSE.

Arithmetic functions

A set of mathematic and trigonometric functions.

Mnemonics	Operand Type	Example	Explanation
ABS	One argument of double type	=ABS(B6)	Returns the absolute value.
ACOS	One argument of double type	=ACOS(B16)	Returns the arccosine.
ACOSH	One argument of double type	=ACOSH(A1)	Returns the inverse hyperbolic cosine.
ASIN	One argument of double type	=ASIN(B6)	Returns the arcsine.
ASINH	One argument of double type	=ASINH(C2)	Returns the inverse hyperbolic sine of the argument.
ATAN	One argument of double type	=ATAN(C5)	Returns the arctangent.
ATAN2	Two arguments of double type	=ATAN2(A1, A2)	Returns the arctangent using x- and y- coordinates.
ATANH	One argument of double type	=ATANH(D4)	Returns the inverse hyperbolic tangent.
CEILING	Two argument of double type	=CEILING(2.5, 1)	Rounds the first argument up to the nearest multiple based on the significance specified by the second argument.
COS	One argument of double type	=COS(A1)	Returns the cosine.
COSH	One argument of double type	=COSH(D7)	Returns the hyperbolic cosine.
COUNTIF	Two arguments: the range of cells and the condition of type string.	=COUNTIF(A1:A7,">2")	Counts the number of nonblank cells within a range which meet a given condition.
DEGREES	One argument of double type that specifies angle in radians	=DEGREES(PI()/2)	Converts radians to degrees.
EVEN	One argument of double type	=EVEN(-1)	Rounds the argument up to the nearest even integer.
EXP	One argument of double type	=EXP(C1)	Returns the exponent value of the argument.
FACT	One nonnegative argument	=FACT(2)	Returns the factorial of the argument.
FLOOR	Two arguments of double type	=FLOOR(-2.5, -2)	Rounds the first argument down, towards zero, to the nearest multiple of the significance specified by the second argument.
INT	Argument of type double	=INT(E4)	Rounds the argument down to the nearest integer.
LN	One argument of double type	=LN(C1)	Returns the natural logarithm.
LOG	Two arguments: the number and the base	=LOG(100, 10)	Returns the logarithm of a number to the specified base.
LOG10	One argument of double type	=LOG10(1000)	Returns the base-10 logarithm of the argument.
MOD	Two arguments: a number and divisor	=MOD(4,3)	Returns the remainder after the number is divided by the divisor.
ODD	One argument of double type	=ODD(3.5)	Rounds the argument up to the nearest odd integer.
PI	No arguments required	=PI()	Returns the value of Pi.
POWER	Two arguments of double type: the number and the power	=POWER(A1,4)	Raises the number to the base.
RADIANS	One argument of type double that specifies angle in degrees.	=RADIANS(180)	Converts degrees to radians.
RAND	No arguments required	=RAND()	Returns a random number between 0 and 1.
ROUND	Two arguments: the number of double type and the number of digits	=ROUND(20.57, 1)	Rounds the first argument to the specified number of digits.
ROUNDDOWN	Two arguments of double type	=ROUNDDOWN(2.75,0)	Rounds the argument toward zero.  The first argument specifies a number to round up.  The second argument defines the number of digits to which you want to round the first argument.
ROUNDUP	Two arguments of double type	=ROUNDUP(-3.42,1)	Rounds the argument toward infinity.  The first argument specifies a number to round up.  The second argument defines the number of digits to which you want to round the first argument.
SIGN	One argument of double type	=SIGN(A2)	Returns the sign.
SIN	One argument of double type	=SIN(A1)	Returns the sine.
SINH	One argument of double type	=SINH(1)	Returns the hyperbolic sine.
SQRT	One argument of double type	=SQRT(B5)	Returns the square root.
SUM	A list of arguments	=SUM(A1:C12) =SUM(A1, 3.14, 1.57)	Sums all the values in the list.
SUMSQ	A list of arguments	=SUMSQ(B1:D1) =SUM(1, 2, 3, 4)	Sums the square of values in the list
TAN	One argument of double type	=TAN(C3)	Returns the tangent.
TANH	One argument of double type	=TANH(0)	Returns the hyperbolic tangent.
TRUNC	One argument of double type	=TRUNC(PI())	Returns the integer part.  Compare this with the Int function, which returns a double

Statistical functions

Basic statistical functions.

Mnemonics	Operand Type	Example	Explanation
AVERAGE	A list of arguments	=AVERAGE(A1:A5) =AVERAGE(10.3, 9.1)	Calculates the average value of values within the list.
AVERAGEA	A list of arguments	=AVERAGEA(A1:A5)	Calculates the average value of the non-empty cells referenced. AVERAGEA(range) equals SUM(range)/COUNTA(range).
COUNT	A list of arguments	=COUNT(A1:A4) =COUNT(1, 5, 8)	Returns the number of cells in a given range.
COUNTA	A list of arguments	=COUNTA(A1:A4)	Counts the number of non-empty cells in a given range.
COUNTBLANK	A list of arguments	=COUNTBLANK(A1:E1)	Counts the number of empty cells.
MAX	A list of arguments	=MAX(A1:D1) =MAX(A1, 100, C2)	Returns the largest argument value.
MIN	A list of arguments	=MIN(A1:D1) =MIN(0, C2)	Returns the smallest argument value.
SUM	A list of arguments	=SUM(A1:C12) =SUM(A1, 3.14, 1.57)	Sums values within the list.
SUMSQ	A list of arguments	=SUMSQ(B1:D1) =SUMSQ(1, 2, 3, 4)	Sums squares of values within the list.

Logical functions

Logical functions take logical values as arguments and return a logical value as a result.

Mnemonics	Operand Type	Example	Explanation
AND	A list of logical arguments	=AND(1<B4, B4<100)	Logical AND operation. Returns TRUE if all values within the list are TRUE; returns FALSE if one or more values within the list evaluates to FALSE.
FALSE	No arguments required	=FALSE()	Returns the logical value FALSE.
IF	Three arguments: the logical expression, the value to return if the expression succeeds, the value to return the expression fails.	=IF(A10<=100, "Within budget", "Over budget")	Returns the second argument if the logical expression evaluates to TRUE and the third argument otherwise.
NOT	One argument of logical type	=NOT(1>D4)	Logical NOT operation. Reverses the value of its argument.
OR	A list of logical arguments	=OR(A1>=10, A1<=–10)	Logical OR operation. Returns TRUE if any argument is TRUE; returns FALSE if all values within the list evaluate to FALSE.
TRUE	No arguments required.	=TRUE()	Returns the logical value TRUE.

Date and Time functions

Mnemonics	Operand Type	Example	Explanation
DATE	Three operands defining the year, month and day.	=DATE(1900,1,1)	Calculates the serial number that represents a specified date.
DAY	One argument defining the serial number of the required date.	=DAY(TODAY())	Returns the day portion of a given date.
HOUR	One argument defining the serial number of the required date/time value.	=HOUR(NOW())	Returns the hour portion of a given date/time value.
MONTH	One argument defining the serial number of the required date.	=MONTH(TODAY())	Returns the month portion of a given date.
MINUTE	One argument defining the serial number of the required date/time value.	=MINUTE(NOW())	Returns the minutes portion of a given date/time value.
NOW	No arguments required.	=NOW()	Returns the current time in general format.  You can apply further formatting to the result of the function.
SECOND	One argument defining the serial number of the required date/time value.	=SECOND(NOW())	Returns the seconds portion of a given date/time value.
TIME	Three arguments defining hour, minute and second parts of a time value.	=TIME(16, 48, 10)	Returns a decimal number for a specified time.
TODAY	No arguments required.	=TODAY()	Returns the serial number of the current date.
WEEKDAY	Two arguments: the serial number of the required date, weekday base.	=WEEKDAY(TODAY()) =WEEKDAY(DATE( 2002, 12, 1),1) returns 1(Sunday)	Returns the day of the week corresponding to the specified date. The weekday base identifies the first day of the week and determines the return value type: 1 or omitted: the first day of the week is Sunday.  The function returns 1 for Sunday, 2 for Monday, etc. 2: the first day of the week is Monday.  The function returns 1 for Monday, 2 for Tuesday, etc. 3: the first day of the week is Monday.  The function returns 0 for Monday, 1 for Tuesday, etc.
YEAR	One argument defining the serial number of the required date.	=YEAR(TODAY())	Returns the year portion of a given date.

Text functions

Mnemonics	Operand Type	Example	Explanation
& (ampersand)	Two arguments of type string	= "Yellow "&"river"	Concatenates specified strings.
CONCATENATE	A list of strings	=CONCATENATE("Developer", " Express")	Joins several text strings in one text string. An alternative to "&".
DOLLAR	Two arguments defining the value and the number of digits to the right of the decimal point in the output string.	=DOLLAR(957.344, 2)	Converts the number to text using currency format $#,##0.00_);($#,##0.00), with the decimals rounded to the specified number of places.
FIXED	The first argument of type double is required.  The second argument of type integer is optional (the default value is 2).  The third argument of type Boolean is optional.	=FIXED(1234.567, 1)	Rounds the first argument to the number of decimals determined by the second argument and returns it as a string.  The third parameter specifies whether to omit commas in the output string.
LEFT	The first argument of type string is required.  The second argument of type integer is optional.	=LEFT(A1) =LEFT(A1, 3)	Returns the first character or characters in a text string.  The second parameter defines the number of characters to extract.  The default value is 1.
LEN	One argument of type string.	=LEN("ABC")	Returns the length of a given string.
LOWER	One argument of type string.	=LOWER(A1)	Converts a string to lowercase.
MID	The first argument is of type string, the second and the third arguments are of type integer.	=MID("ABC",3,1)	Returns the substring of a given text string.  The position of the substring is defined by the second parameter.  The third parameter specifies the number of characters to extract.
RIGHT	The first argument of type string is required.  The second argument of type integer is optional.	=RIGHT(B2, 3)	Returns the last character or characters in a text string.  The second parameter defines the number of characters to extract.  The default value is 1.
TRIM	One argument of string type	=TRIM("   Express Spread Sheet   ")	Removes all spaces from text except for single spaces between words.
UPPER	One argument of type string.	=UPPER(A1&A2)	Converts a string to uppercase.

IS functions

Functions which test the type of a value and return a Boolean result.

Mnemonics	Operand Type	Example	Explanation
ISBLANK	A value of any type	=ISBLANK(A1)	Returns TRUE if cell is empty.
ISERR	A value of any type	=ISERR(H1)	Returns TRUE if the cell contains any error value except #N/A.
ISERROR	A value of any type	=ISERROR(A7)	Returns TRUE if the cell contains any error value (#N/A, #VALUE!, #REF!, #DIV/0!, #NUM!, #NAME?, or #NULL!).
ISLOGICAL	A value of any type	=ISLOGICAL(C3)	Returns TRUE if the specified value refers to a logical value.
ISNA	A value of any type	=ISNA(E5)	Returns TRUE if the cell contains #N/A (value not available) error value.
ISNONTEXT	A value of any type	=ISNONTEXT(D4)	Returns TRUE if the cell does not contain text.  Returns TRUE for blank cells.
ISNUMBER	A value of any type	=ISNUMBER(A2)	Returns TRUE if the cell contains a number.
ISTEXT	A value of any type	=ISTEXT(D1)	Returns TRUE if the specified cell contains text.


About Worksheet Painting

ExpressSpreadSheet components are delivered with two predefined painting styles.  These styles implement two specific drawing styles: Office 97 and Office XP.

You can easily specify the desired painting style by setting the PainterType property of your component.

By default, the PainterType property is set to ptOffice97Style.  You can see this standard look applied to a workbook in the following image.

You can set the PainterType property to ptOfficeXPStyle value to implement Office XP drawing style.  The following image displays a workbook drawn using this style.

Additionally, the ExpressSpreadSheet allows you to implement your custom painting style to draw workbook sheets.  To perform custom workbook painting, you should generate your own painting class derived from TcxSheetPainter.  You should override some of the TcxSheetPainter protected methods, which are responsible for drawing cells, headers, and selections based on your specific needs.  In order to select a custom painting style, you should set the PainterType property to ptCustom.  If the PainterType property is ptCustom, the OnCustomPaint event occurs.  So you should write an OnCustomPaint event handler and pass a reference to your newly designed class as an event parameter in order to implement custom drawing.

The following image displays a worksheet drawn using a custom painter

See the Performing Custom Painting topic for more information regarding implementation of the custom draw feature.


History

ExpressSpreadSheet maintains a history of actions.  Every time you perform formatting, inserting, deleting, clearing cells, changing cell contents, merging/splitting cells or sorting cells a spreadsheet control saves the changes thus providing support for multiple undo/redo operations.  A user can undo and redo operations by pressing the Ctrl+Z and Ctrl+Y shortcuts respectively.

The action history is encapsulated by the TcxSpreadSheetHistory class.  You can access this history by reading the TcxCustomSpreadSheetBook.History property.  Every action you can undo or redo is stored as an item in the corresponding action list (UndoActions or RedoActions).  The length of these lists is defined by the MaxActions property, which controls the number of operations a user can undo.

The Undo and Redo methods allow you to undo the last operation and redo the operation previously undone.  When you undo an operation, the corresponding item is moved from the UndoActions list to RedoActions.  Conversely, when you redo the operation, the corresponding entry in the RedoActions list is moved to the UndoActions list.

Every operation mentioned above (formatting, inserting, deleting, clearing cells, etc.) is represented as a single item in the action list.  The TcxSpreadSheetHistory class also allows you to create a complex action consisting of several simple actions, presented as a single item in the action list.  When you undo/redo a complex action, you undo/redo all the underlying operations at once.  To create a complex action you must enclose the necessary operations within the StartComplexAction and StopComplexAction methods pair.


Managing Worksheets

This topic covers the basics of worksheet manipulation.  It includes information about deleting, inserting, hiding, making visible and renaming of worksheets.

Worksheets are used to list and analyze data.  You can enter and edit data on several worksheets simultaneously and perform calculations based on worksheet data.  The following operations are enabled when managing worksheets within a workbook.

•	Make a Specific Worksheet Active

•	Rename a Worksheet

•	Add a New Worksheet

•	Hide a Worksheet and Display a Hidden Worksheet

•	Delete a Worksheet from a Workbook

Make a Specific Worksheet Active

The names of sheets appear on tabs at the bottom of the workbook window.  A user can click them to move from sheet to sheet.

A user can also change the active page using the navigation buttons located within the caption bar.

If you need to make a worksheet active in code, you can use the ActivePage property, which specifies the index of the active worksheet.  Bear in mind that this property is zero-based (the first worksheet has an index of 0).

The following sample code illustrates the runtime setting of the ActivePage property.  Use this code to navigate forward through workbook pages.  When the last worksheet is reached, it sets the first worksheet active.

// Delphi

if cxSpreadSheetBook1.ActivePage < cxSpreadSheetBook1.PageCount - 1 then

  cxSpreadSheetBook1.ActivePage := cxSpreadSheetBook1.ActivePage + 1

else

  cxSpreadSheetBook1.ActivePage := 0;

// C++ Builder

if(cxSpreadSheetBook1->ActivePage<cxSpreadSheetBook1->PageCount - 1){

  cxSpreadSheetBook1->ActivePage++;

}

else {

  cxSpreadSheetBook1->ActivePage = 0;

}

Rename a Sheet within a Workbook

An end user can simply rename a specific worksheet by double-clicking a sheet tab within the caption bar and then type the new name over the current name.  The following image illustrates how to rename the worksheet named ‘Sheet 2’ to ‘Second Sheet’.

This can be done at runtime as well by using the Caption property of the TcxSSBookSheet object that represents a sheet within a workbook.  The TcxSSBookSheet object corresponding to a particular worksheet can be retrieved via the Pages property of the TcxSpreadSheetBook object.  The following sample code demonstrates runtime worksheet renaming.

// Delphi

cxSpreadSheetBook1.Pages[1].Caption := 'Second Sheet';

// C++ Builder

cxSpreadSheetBook1->Pages[1]->Caption = "Second Sheet";

Add a New Worksheet

In order to add a new worksheet to a workbook, you can use the AddSheetPage method of the TcxSpreadSheetBook object.  This method has an APageName parameter, which specifies the name of the newly added worksheet.  This name will be displayed within the caption bar at the bottom of the workbook window.  If no specific name is assigned to the APageName parameter, the added worksheet receives an automatically generated name.

You can also add worksheets to your workbook incrementing the PageCount property.  If worksheets are added using the PageCount property, they will have default captions.

The following sample code adds two worksheets.  ‘Added Page’ is assigned to the first sheet.  The second worksheet has a default caption (‘Sheet 5’).

// Delphi

cxSpreadSheetBook1.AddSheetPage('Added Page');

cxSpreadSheetBook1.PageCount := cxSpreadSheetBook1.PageCount + 1;

// C++ Builder

cxSpreadSheetBook1->AddSheetPage("Added Page");

cxSpreadSheetBook1->PageCount++;

The result of this code execution is displayed on the following picture.

Hide a Worksheet and Display a Hidden Worksheet

You can easily hide a specific worksheet within a workbook and then display the hidden sheet again.  Use the PageVisible property to specify whether the specified workbook sheet is visible.  This property uses the index to specify this worksheet.

When the PageVisible property is set to False, the sheet specified by the index is hidden.  The hidden sheet cannot be accessed by the end user using the caption bar, i.e. its tab is not displayed and it cannot be located using navigation buttons.

The following line of code hides the second worksheet.

// Delphi

cxSpreadSheetBook1.PageVisible[1] := False;

// C++ Builder

cxSpreadSheetBook1->PageVisible[1] = false;

If the PageVisible property is set to True, the specified sheet becomes visible.  This means that the tab with the sheet name is displayed within the caption bar at the bottom of the workbook window, and this sheet may become active by clicking this sheet tab.  This worksheet can also be accessed using navigation buttons.

Use the following code line to display the previously hidden worksheet.

// Delphi

cxSpreadSheetBook1.PageVisible[1] := True;

// C++ Builder

cxSpreadSheetBook1->PageVisible[1] = true;

Delete a Worksheet from a Workbook

To delete a worksheet from a workbook, you can use the PageCount property.  When decrementing the PageCount property, the last page within the book is deleted.  If you set the PageCount property to a value less than the total number of pages, worksheets are deleted from the workbook from its end.  The number of pages to delete is determined by the difference between the total page number and the desired page count.  Links on other pages to cells of the deleted page will be unresolved.

The following code removes the last page within a spreadsheet.

// Delphi

cxSpreadSheetBook1.PageCount := cxSpreadSheetBook1.PageCount - 1;

//C++ Builder

cxSpreadSheetBook1->PageCount = cxSpreadSheetBook1->PageCount - 1;


Managing Cells

This topic covers the basics of cell manipulation.  It includes information about deleting, inserting, clearing and sorting worksheet cells, merging cells into a single one and splitting merged cells.

Refer to one of these subtopics for more information:

•	Insert Cells

•	Delete Cells

•	Merge/Split Cells

•	Clear Cells

•	Sort Cells

Insert Cells

The four ways in which neighboring cells can be shifted are illustrated in the image below.

In order to insert cells you should use the InsertCells method implemented in the TcxSSBookSheet class.  The InsertCells method has two parameters that specify the range of cells to be inserted and the manner in which the neighboring cells are shifted.

The following sample code inserts the cell range B2:B3.  Neighboring cells are shifted right.  The appearance of the worksheet before code execution is displayed in the image below.

// Delphi

var ARect: TRect;

//...

with ARect do

begin

  Left := 1;

  Top := 1;

  Right := 1;

  Bottom := 2;

end;

cxSpreadSheetBook1.ActiveSheet.InsertCells(ARect, msShiftCol);

// C++ Builder

TRect rect;

//...

rect.Left = 1;

rect.Top = 1;

rect.Right = 1;

rect.Bottom = 2;

cxSpreadSheetBook1->ActiveSheet->InsertCells(rect, msShiftCol);

Delete Cells

The four ways in which neighboring cells can be shifted are illustrated in the image below.

In order to delete cells in code, you should use the DeleteCells method implemented in the TcxSSBookSheet class.  The DeleteCells method has two parameters that specify the range of cells to be deleted and the manner in which neighboring cells are shifted.

The following sample code deletes selected cells and entire rows, which these cells occupied.    The image below displays the worksheet before cell deletion.

// Delphi

cxSpreadSheetBook1.ActiveSheet.DeleteCells(cxSpreadSheetBook1.Selection, msAllRow);

// C++ Builder

cxSpreadSheetBook1->ActiveSheet->DeleteCells(cxSpreadSheetBook1->Selection, msAllRow, true);

The following image displays the spreadsheet after the cells have been deleted.

Merge/Split Cells

The ExpressSpreadSheet gives you the ability to merge several cells into one.  The contents of only one cell are displayed within the merged cell and all changes applied to the merged cell, are applied to this only cell.  The contents of other merged cells are not lost.  When the merged cell is split, all cells except the primary cell will contain the values they previously contained before the merge operation.  The main cell occupies the area previously occupied by several cells - and the other cells are simply hidden by the primary cell.

The SetMergedState method implemented in the TcxSSBookSheet class allows you to merge/split cells within a worksheet.  To obtain a reference to a worksheet, use the ActiveSheet or Pages properties of a TcxSpreadSheetBook control and the Sheet property of a TcxSpreadSheet control.

The next image demonstrates two spreadsheet controls before and after merging cells A1:B2

Write the following lines of code to perform this.

// Delphi

var ARect: TRect;

//...

with ARect do

begin

  Left := 0;

  Top := 0;

  Right := 1;

  Bottom := 1;

end;

cxSpreadSheetBook1.ActiveSheet.SetMergeState(ARect, True);

// C++ Builder

TRect rect;

rect.Left = 0;

rect.Top = 0;

rect.Right = 1;

rect.Bottom = 1;

cxSpreadSheetBook1->ActiveSheet->SetMergeState(rect, true);

In order to split the merged cells, you should use the code below:

// Delphi

var ARect: TRect;

//...

with ARect do

begin

  Left := 0;

  Top := 0;

  Right := 1;

  Bottom := 1;

end;

cxSpreadSheetBook1.ActiveSheet.SetMergeState(ARect, False);

// C++ Builder

TRect rect;

rect.Left = 0;

rect.Top = 0;

rect.Right = 1;

rect.Bottom = 1;

cxSpreadSheetBook1->ActiveSheet->SetMergeState(rect, false);

Clear Cells

ExpressSpreadSheet provides several methods to clear cells.  The ClearCells method implemented in the TcxSSBookSheet class allows you to clear a specific cell range.  In addition to clearing cells’ contents, you can also clear the cells’ formatting.  The first method parameter defines a cell region to clear.  The second parameter defines whether to reset cells’ formatting.  The following code demonstrates how to clear the contents and style of cells within the range specified by ARect.

//Delphi

var

  ARect: TRect;

  ResetStyle: Boolean;

//...

  ARect := Rect(0, 0, 3, 4);

  ResetStyle := True;

  cxSpreadSheetBook1.Pages[0].ClearCells(ARect, ResetStyle);

//C++ Builder

  TRect ARect = Rect(0, 0, 3, 4);

  bool ResetStyle = true;

  cxSpreadSheetBook1->Pages[0]->ClearCells(ARect, ResetStyle);

If you need to clear the entire worksheet, you can call the ClearAll method also implemented in the TcxSSBookSheet class.  The TcxCustomSpreadSheetBook.ClearAll method clears the cells within all worksheets of a workbook.  These methods clear both contents and formatting of cells.

A spreadsheet control generates the OnClearCells event when cells are about to be cleared.  You can use this event to control resetting style formatting while clearing cells.  Also, you are able to cancel the cell clearance by setting the appropriate event parameter.

Sort Cells

The TcxSSBookSheet.Sort method allows you to sort cell values against multiple columns.  Sorting by multiple columns means that you can define the sort order for each column in the specified range.  If cells in a particular column have the identical values then cells in other column(s) will be compared (if the column(s) have an order specified).

You have to identify the cell range for the sort operation, but it is not necessary to specify the sort order for every column.

The next image demonstrates a spreadsheet control with data on countries.

Suppose, you want to sort against the continent and country columns in descending and ascending orders respectively.  The following code performs such a sort of the selected range of cells.  As the values in column C relate to the data of the two previous columns, you must specify all three columns in the Sort method (in this example, it is necessary to select three columns A, B, C before executing the code).

//Delphi

with cxSpreadSheetBook1.ActiveSheet do

  Sort(SelectionRect, [stDescending, stAscending]);

//C++ Builder

const int sortTypesSize = 2;

TcxSortType sortTypes[sortTypesSize] = {stDescending, stAscending};

TcxSSBookSheet * worksheet = cxSpreadSheetBook1->ActiveSheet;

worksheet->Sort(worksheet->SelectionRect, sortTypes, sortTypesSize);

The result is displayed below:


Manipulate Cell Contents

ExpressSpreadSheet provides two ways to enter data into cells: manually or in code. If ExpressSpreadSheet has focus and none of the cells are being edited, the text entered by a user is written to the active cell.  In this instance, the text of the active cell is erased when the first symbol is entered.  In order to modify a cell value without erasing its contents, a user should double-click the desired cell.  This activates the cell editor and its text is not lost.

In order to enter a cell value in code, you should use the Text or DateTime property of the TcxSSCellObject object corresponding to the desired cell.  These properties are used to enter a text (formula) or a date value respectively.

Enter a Text Value into a Cell (including formulas)

When entering a text value or a formula either manually or in code, the input value is stored within the Text property.  The DataType property is automatically set to dtText or dtFunction depending upon cell contents.

Use the Text property to read or set a text string, which will be contained within a cell.  This text string can represent either the displayed value of the cell or an appropriate formula used to calculate the cell value.

Let's develop a simple report table to get acquainted with use of the Text property.  Setting of cell contents is performed in the SetCellText function.  You must provide the coordinates of the required cell, the worksheet which contains the cell, and the text for the cell as the method arguments.

// Delphi

procedure SetCellText(Sheet: TcxSSBookSheet; Col, Row: Integer; TextData: string);

var

  Cell: TcxSSCellObject;

begin

  Cell := Sheet.GetCellObject(Col, Row);

  with Cell do

    try

      Cell.Text := TextData;

    finally

      Free;

    end;

end;

//C++ Builder

void SetCellText(TcxSSBookSheet * Sheet, int Col, int Row, String TextData) {

  TcxSSCellObject * cell;

  cell = Sheet->GetCellObject(Col, Row);

  try {

    cell->Text = TextData;

  }

  __finally {

    delete cell;

  }

}

The following sample code assigns text captions to row and column headers of a report table.

var

  Sheet: TcxSSBookSheet;

//...

  Sheet := cxSpreadSheetBook1.ActiveSheet;

  SetCellText(Sheet, 0, 0, 'Division A'); // text for A1

  SetCellText(Sheet, 1, 0, 'Product 1');  // text for B1

  SetCellText(Sheet, 2, 0, 'Product 2');  // text for C1

  SetCellText(Sheet, 3, 0, 'Product 3');  // text for D1

  SetCellText(Sheet, 4, 0, 'Total');      // text for E1

  SetCellText(Sheet, 0, 1, 'East');       // text for A2

  SetCellText(Sheet, 0, 2, 'West');       // text for A3

  SetCellText(Sheet, 0, 3, 'Total');      // text for A4

// C++ Builder

  TcxSSBookSheet *sheet = cxSpreadSheetBook1->ActiveSheet;

  SetCellText(sheet, 0, 0, "Division A"); // text for A1

  SetCellText(sheet, 1, 0, "Product 1");  // text for B1

  SetCellText(sheet, 2, 0, "Product 2");  // text for C1

  SetCellText(sheet, 3, 0, "Product 3");  // text for D1

  SetCellText(sheet, 4, 0, "Total");      // text for E1

  SetCellText(sheet, 0, 1, "East");       // text for A2

  SetCellText(sheet, 0, 2, "West");       // text for A3

  SetCellText(sheet, 0, 3, "Total");      // text for A4

The results of this code implementation are described in the following image (cells A1:A4, B1:E1 receive their values via the Text property).

Then you can enter meaningful data into range B2:D3.  Assume that data represents a quantity of goods sold by Division A for a specific period of time.  The following code serves as an example, which illustrates how to populate the mentioned cell range with random numbers.  The entered data will be used for total amount calculation.

// Delphi

var

  I, J : Integer;

  AValue: string;

  Sheet: TcxSSBookSheet;

// ...

  Sheet := cxSpreadSheetBook1.ActiveSheet;

//...

  Randomize;

  for J := 1 to 2 do // the J variable specifies the row index

    for I := 1 to 3 do // the I variable specifies the column index

      begin

        AValue := IntToStr(Random(100));

        SetCellText(Sheet, I, J, AValue);

      end;

  cxSpreadSheetBook1.Recalc;

// C++ Builder

  int i, j;

  String value;

  TcxSSBookSheet *sheet = cxSpreadSheetBook1->ActiveSheet;

// ...

  randomize;

  for (j = 1; j <= 2; j++)  // the j variable specifies the row index

    for (i = 1; i <= 3; i++) { // the i variable specifies the column index

    value = IntToStr(random(100));

    SetCellText(sheet, i, j, value);

  }

  cxSpreadSheetBook1->Recalc();

Note: If you change cell contents in code, you should call the Recalc method in order to recalculate the values of all formulas within the workbook.  The reason is that some formulas may reference cells whose contents have changed.

The image below displays the workbook state after code implementation.

And now you can use the Text property to enter formulas, which will calculate the total amount of each product and the total amount of all products sold by the Division A department for a certain period of time.  Thus cells B4, C4, and D4 will contain formulas that return the total amount of Product 1, Product 2, and Product 3 correspondingly and cell E4 will contain a formula calculating the total amount of all products sold.

You may use the following sample code to enter these formulas at runtime.

// Delphi

var

  Sheet: TcxSSBookSheet;

//...

  Sheet := cxSpreadSheetBook1.ActiveSheet;

//...

  SetCellText(Sheet, 1, 3, '=Sum(B2:B3)');  // formula for B4

  SetCellText(Sheet, 2, 3, '=Sum(C2:C3)');  // formula for C4

  SetCellText(Sheet, 3, 3, '=Sum(D2:D3)');  // formula for D4

  SetCellText(Sheet, 4, 3, '=Sum(B4:D4)');  // formula for E4

  cxSpreadSheetBook1.Recalc;

// C++ Builder

  TcxSSBookSheet *sheet = cxSpreadSheetBook1->ActiveSheet;

// ...

  SetCellText(sheet, 1, 3, "=Sum(B2:B3)");  // formula for B4

  SetCellText(sheet, 2, 3, "=Sum(C2:C3)");  // formula for C4

  SetCellText(sheet, 3, 3, "=Sum(D2:D3)");  // formula for D4

  SetCellText(sheet, 4, 3, "=Sum(B4:D4)");  // formula for E4

  cxSpreadSheetBook1->Recalc();

Note: If you enter formulas via code, you should call the Recalc method to recalculate the values of all formulas within the workbook.

The final look of the workbook containing the report table is displayed on the following image.

You can review the Using Formulas topic for more information on how to enter a formula into a cell.

Enter Date and Time Values into a Cell

To enter a date/time value into a cell you should use the DateTime property.  The DataType property is automatically set to dtDateTime.

Since the DateTime property is of type TDateTime, the ExpressSpreadSheet treats dates and time as numbers.  Dates are stored as sequential numbers known as serial values.  Time is stored as decimal fractions because time is considered to be a portion of a day.  Dates and time are values and, therefore, can be added, subtracted, and included in other calculations.

In order to illustrate the runtime setting of the DateTime property in code, let’s add the current date and time value to the above-mentioned report table example.  The following sample code inserts the current date and time into cell C6, which has a date-time format.  You can format a cell value by applying one of the predefined formats via the Format member of the Style property.

// Delphi

var ACellObject: TcxSSCellObject;

// ...

// cell C6

ACellObject := cxSpreadSheetBook1.ActiveSheet.GetCellObject(2, 5);

with ACellObject do

  try

    Style.Format := $0e; // sets date format ‘m/d/yy’ for C6

    DateTime := Now;     // sets current date and time for C6

  finally

    Free;

  end;

// C++ Builder

TcxSSCellObject *cellObject;

// cell C6

try {

  cellObject = cxSpreadSheetBook1->ActiveSheet->GetCellObject(2, 5);

  cellObject->Style->Format = 0x0e; // sets date format ‘m/d/yy’ for C6

  cellObject->DateTime = Now();     // sets current date and time for C6

}

__finally {

  delete cellObject;

}


Change Cell Style

Specific cell style is accessed via the Style property of the TcxSSCellObject object.  The TcxSSCellObject class instance corresponding to a cell within a worksheet can be obtained via the TcxSSBookSheet.GetCellObject method and this takes a column and a row as cell coordinates.  To get the desired worksheet of the TcxSSBookSheet class, you can use the ActiveSheet or Pages properties of a TcxSpreadSheetBook control and the Sheet property of a TcxSpreadSheet control.

The Style property of the obtained TcxSSCellObject object returns a TcxSSCellStyle class instance that contains properties whose values correspond to the font, foreground and background color, and fill pattern of the cell.

See the About Formatting Styles topic for detailed information on internal styles representation.

This topic contains the following sub-topics:

•	Change Font Properties

•	Align Data within a Cell

•	Apply Borders to a Cell

•	Apply Fill Pattern to a Cell

Change Font Properties

Font properties are accessed via the Font property of the TcxSSCellStyle object.  The Font property represents a TcxSSFont object.  This object has Charset, Name, Size, Style and FontColor properties, which specify the character set, typeface, size, style and color of the font used to display a cell value respectively.  The FontColor property specifies the font color used to display a cell value.  This property is of type Word.  It identifies the indexed color in the spreadsheet palette which is supported by the Palette property of the TcxSpreadSheet and TcxSpreadSheetBook classes.

The image below demonstrates font manipulations.

Use the following code to implement the same font properties for cell B2 in the active worksheet.

// Delphi

var

  ACell: TcxSSCellObject;

//...

ACell := cxSpreadSheetBook1.ActiveSheet.GetCellObject(1, 1);

try

  with ACell.Style.Font do

  begin

    Name := 'Century Gothic';

    Size := 14;

    Style := [fsBold, fsUnderline];

    FontColor := 4; //clBlue

  end;

finally

  ACell.Free;

end;

// C++ Builder

TcxSSCellObject *cell;

TcxSSFont *font;

cell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(1, 1);

try {

  font = cell->Style->Font;

  font->Name = "Century Gothic";

  font->Size = 14;

  font->Style = TFontStyles() << fsBold << fsUnderline;

  font->FontColor = 4; //clBlue

}

__finally {

  delete cell;

}

Align Data within a Cell

Use the HorzTextAlign and VertTextAlign properties of the TcxSSCellStyle class to align data within a cell.  You can set various alignments: left, right, center or justify.  The TcxHorzTextAlign and TcxVertTextAlign enumerators determine possible horizontal and vertical alignments respectively.

By default, cell content is top aligned and the haGENERAL format is used to align it horizontally.  The haGENERAL format makes text, numbers, logical values aligned differently: text is aligned to the left, numbers are aligned to the right, and logical values are centered.

When a cell value is edited, it is aligned left top regardless of alignment set via the HorzTextAlign and VertTextAlign properties.

The following sample code sets different text alignments for cell range B2:G5.

// Delphi

var

  ACell: TcxSSCellObject;

  HAlign: TcxHorzTextAlign;

  VAlign:  TcxVertTextAlign;

  i, j: Integer;

//...

i := 1;

j := 1;

for HAlign := haGENERAL to haJUSTIFY do

begin

  for VAlign := vaTOP to vaJUSTIFY do

  begin

    ACell := cxSpreadSheetBook1.ActiveSheet.GetCellObject(i, j);

    try

      ACell.Style.HorzTextAlign := HAlign;

      ACell.Style.VertTextAlign := VAlign;

      ACell.Text := 'a bc def ghij klmn';

      ACell.Style.WordBreak := True;

    finally

      ACell.Free;

    end;

    j := j + 1;

  end;

  i := i + 1;

  j := 1;

end;

// C++ Builder

TcxSSCellObject *cell;

TcxHorzTextAlign hAlign;

TcxVertTextAlign vAlign;

int i =1, j = 1;

for (hAlign = haGENERAL; hAlign <= haJUSTIFY;

     hAlign = hAlign + 1, i++, j = 1)

  for (vAlign = vaTOP; vAlign <= vaJUSTIFY; vAlign= vAlign + 1, j++) {

    cell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(i, j);

    try {

      cell->Style->HorzTextAlign = hAlign;

      cell->Style->VertTextAlign = vAlign;

      cell->Text = "a bc def ghij klmn";

      cell->Style->WordBreak = true;

    }

    __finally {

      delete cell;

    }

  }

The image below displays the worksheet after code execution.

Apply Borders to a Cell

The ExpressSpreadSheet gives you the ability to apply cell borders.  This can be performed using the Borders property of the TcxSSCellStyle object.  This property returns a TcxSSBorderStyle class instance.  The TcxSSBorderStyle object contains Left, Top, Right and Bottom properties that specify the style of corresponding cell edges.  You can also access particular cell edge style via the Edges property of the TcxSSBorderStyle object.

The Left, Top, Right, Bottom and Edges properties of the TcxSSBorderStyle object return a reference to the TcxSSEdgeStyle object.  This object has both Color and Style properties that specify the color and style of the line used for the cell’s edge.  The Color property is of type Word. It identifies an index of a color in the SpreadSheet Palette.  The Style property is of type TcxSSEdgeLineStyle, which is the enumerator containing 14 predefined line styles.

The following image describes the manner in which edge styles for a cell are modified.

Use the following code to apply the same border style to the B2 cell of the active worksheet.

// Delphi

var ACell: TcxSSCellObject;

//...

ACell := cxSpreadSheetBook1.ActiveSheet.GetCellObject(1, 1);

try

  with ACell.Style.Borders do

  begin

    with Left do

    begin

      Color := 2; //clRed;

      Style := lsDouble;

    end;

    with Top do

    begin

      Color := 4; //clBlue;

      Style := lsHair;

    end;

    with Right do

    begin

      Color := 25; //$FF00FF;

      Style := lsThick;

    end;

    with Bottom do

    begin

      Color := 3; //clGreen;

      Style := lsMediumDashDotDot;

    end;

  end;

finally

  ACell.Free;

end;

// C++ Builder

TcxSSCellObject *cell;

TcxSSBorderStyle *borderStyle;

cell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(1, 1);

try {

  borderStyle = cell->Style->Borders;

  borderStyle->Left->Color = 2; //clRed

  borderStyle->Left->Style = lsDouble;

  borderStyle->Top->Color = 4; //clBlue

  borderStyle->Top->Style = lsHair;

  borderStyle->Right->Color = 25; //0xFF00FF

  borderStyle->Right->Style = lsThick;

  borderStyle->Bottom->Color = 3; //clGreen

  borderStyle->Bottom->Style = lsMediumDashDotDot;

}

__finally {

  delete cell;

}

The following sample code demonstrates how to use the Edges property.  It assigns the same style to all cell edges.

// Delphi

var

  ACell: TcxSSCellObject;

  AEdge: TcxSSEdgeBorder;

//...

ACell := cxSpreadSheetBook1.ActiveSheet.GetCellObject(1, 1);

try

  for AEdge := eLeft to eBottom do

    with ACell.Style.Borders.Edges[AEdge] do

    begin

      Color := 4; //clBlue

      Style := lsDouble;

    end;

finally

  ACell.Free;

end;

// C++ Builder

TcxSSCellObject *cell;

TcxSSBorderStyle *borderStyle;

TcxSSEdgeBorder edge;

cell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(1, 1);

try {

  borderStyle = cell->Style->Borders;

  for (edge = eLeft; edge <= eBottom; edge = edge + 1) {

    borderStyle->Edges[edge]->Color = 4; //clBlue

    borderStyle->Edges[edge]->Style = lsDouble;

  }

}

__finally {

  delete cell;

}

The image below shows the worksheet appearance after code execution.

Apply Fill Pattern to a Cell

The ExpressSpreadSheet allows you to apply fill patterns to individual cells.  Fill patterns are managed via the Brush property of the TcxSSCellStyle object.  This property returns a reference to the TcxSSBrush object, which contains the Style, ForegroundColor and BackgroundColor properties.

The BackgroundColor and ForegroundColor properties specify the background color of a cell and the color used to fill it.  The fill pattern is specified by the Brush property.  This property is of type TcxSSFillStyle and is the enumerator containing 18 predefined patterns.

The following image displays the manner in which fill patterns of a cell are modified.

The following sample code applies the same fill pattern to cell B2 for the active worksheet.

// Delphi

var ACell: TcxSSCellObject;

//

ACell := cxSpreadSheetBook1.ActiveSheet.GetCellObject(1, 1);

try

  with ACell.Style.Brush do

  begin

    ForegroundColor := 5; //clYellow

    BackgroundColor := 2; //clRed

    Style := fsThinDiagCrossHatch;

  end;

finally

  ACell.Free;

end;

// C++ Builder

TcxSSCellObject *cell;

TcxSSBrush *brush;

cell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(1, 1);

try {

  brush = cell->Style->Brush;

  brush->ForegroundColor = 5; //clYellow

  brush->BackgroundColor = 2; //clRed

  brush->Style = fsThinDiagCrossHatch;

}

__finally {

  delete cell;

}


Working With Headers

The ExpressSpreadSheet allows you to change the dimensions of the headers manually and via code.  In order to change the width/height of a column/row a user must drag the boundaries of the corresponding column/row header.  Refer to one of the subtopics listed below for information on changing the dimensions of columns, rows and header panels.

•	Changing the width/height or a particular column/row within the active page

•	Changing the width/height or a particular column/row within a specified page

•	Changing the default width/height of columns/rows

•	Changing the width/height of the row/column header panel

The ExpressSpreadSheet also allows you to hide/unhide and lock/unlock particular columns and rows.  A user can hide/display columns and rows using corresponding popup menu items.  You should refer to the following subtopics for information on how to perform this at runtime and how to lock a row or a column.

•	Locking a row or a column

•	Hiding a row or a column

Changing the width/height or a particular column/row within the active page

The width/height of a column/row is specified by the Size property of the TcxSSHeader object.  In order to get the TcxSSHeader object corresponding to the column/row header panel of the active page, you should use the Cols/Rows property implemented in the TcxSSBookSheet class.  You can access an active worksheet by reading the ActiveSheet property of a TcxSpreadSheetBook control and the Sheet property of a TcxSpreadSheet control.

The following sample code changes the width of the B column and the height of the 3rd row within the active page.  The image below shows the worksheet before code execution.

// Delphi

var CHeader, RHeader: TcxSSHeader;

//...

CHeader := cxSpreadSheetBook1.ActiveSheet.Cols;

RHeader := cxSpreadSheetBook1.ActiveSheet.Rows;

CHeader.Size[1] := 200;

RHeader.Size[2] := 40;

// C++ Builder

TcxSSHeader *cHeader, *rHeader;

// ...

cHeader = cxSpreadSheetBook1->ActiveSheet->Cols;

rHeader = cxSpreadSheetBook1->ActiveSheet->Rows;

cHeader->Size[1] = 200;

rHeader->Size[2] = 40;

Changing the width/height of a particular column/row within a specified page

The width/height of a column/row is specified by the Size property of the TcxSSHeader object.  In order to get the TcxSSHeader object corresponding to the column/row header panel of a particular page in a workbook, you should use the Cols and Rows members of the Pages property.

The following sample code changes the width of the A column within the first page and the height of the 2nd row within the second page.  The image below shows the worksheet before code execution.

// Delphi

var CHeader, RHeader: TcxSSHeader;

//...

CHeader := cxSpreadSheetBook1.Pages[0].Cols;

RHeader := cxSpreadSheetBook1.Pages[1].Rows;

CHeader.Size[0] := 30;

RHeader.Size[1] := 40;

// C++ Builder

TcxSSHeader *cHeader, *rHeader;

// ...

cHeader = cxSpreadSheetBook1->Pages[0]->Cols;

rHeader = cxSpreadSheetBook1->Pages[1]->Rows;

cHeader->Size[0] = 30;

rHeader->Size[1] = 40;

Changing the default width/height of columns/rows

The ExpressSpreadSheet allows you to change the default width/height of columns/rows.  You should use the DefaultColWidth and DefaultRowHeight properties for this purpose.  These properties are implemented in the TcxCustomSpreadSheetBook class and published in both TcxSpreadSheet and TcxSpreadSheetBook classes.

Column width is 85 by default.  Default row height is 20.

You can change the values of the DefaultColWidth and DefaultRowHeight properties at design-time using the Object Inspector window.  The image below shows how to set these properties to 50 and 30 respectively.

Write the following code to perform the same at runtime:

// Delphi

with cxSpreadSheetBook1 do

begin

  DefaultColWidth := 50;

  DefaultRowHeight := 30;

end;

// C++ Builder

cxSpreadSheetBook1->DefaultColWidth = 50;

cxSpreadSheetBook1->DefaultRowHeight = 30;

Note the 2 following points:

•	The DefaultColWidth and DefaultRowHeight properties affect columns and rows within all the worksheets of the workbook (if you are using the TcxSpreadSheetBook object);

•	If the width/height of a column/row was changed via the Size property or manually via drag-and-drop, the DefaultColWidth and DefaultRowHeight properties do not affect this column/row any longer.

In order to set the default width/height of columns/rows within a particular worksheet, you should use the DefaultSize property of the TcxSSHeader object.  The TcxSSHeader object corresponding to the column/row header panel of the worksheet can be obtained via the Cols/Rows properties.

The image below shows the default appearance of the first two worksheets.

The following sample code changes the default header size within different worksheets.

// Delphi

var CHeader, RHeader: TcxSSHeader;

//...

CHeader := cxSpreadSheetBook1.Pages[0].Cols;

RHeader := cxSpreadSheetBook1.Pages[1].Rows;

CHeader.DefaultSize := 50;

RHeader.DefaultSize := 15;

// C++ Builder

TcxSSHeader *cHeader, *rHeader;

cHeader = cxSpreadSheetBook1->Pages[0]->Cols;

rHeader = cxSpreadSheetBook1->Pages[1]->Rows;

cHeader->DefaultSize = 50;

rHeader->DefaultSize = 15;

Changing the width/height of the row/column header panel

In order to change the width/height of the row/column header panel you should use the RowHeaderWidth/ColHeaderHeight property.  These properties are implemented in the TcxCustomSpreadSheetBook class and published in both the TcxSpreadSheetBook and TcxSpreadSheet classes.

The width of the row header is 85 by default.  The default column header height is 20.

The image below shows how to change the width/height of the row/column header panel at design-time.  The column header panel height is set to 30.  The width of the row header panel is set to 50.

Write the following code to perform the same at runtime:

// Delphi

with cxSpreadSheetBook1 do

begin

  ColHeaderHeight := 30;

  RowHeaderWidth := 50;

end;

// C++ Builder

cxSpreadSheetBook1->ColHeaderHeight = 30;

cxSpreadSheetBook1->RowHeaderWidth = 50;

Locking a row or a column

When a column or a row is locked, a user can no longer change column dimensions.  Use the Lock property of the TcxSSHeader object to lock/unlock a row or a column.  The index specifies the column or row to be locked/unlocked.  The TcxSSHeader object corresponding to the column/row header panel of the active worksheet can be obtained via the Cols/Rows property.

Write the following line of code to lock column B of the active worksheet.

// Delphi

cxSpreadSheetBook1.ActiveSheet.Cols.Lock[1] := True;

// C++ Builder

cxSpreadSheetBook1->ActiveSheet->Cols->Lock[1] = true;

Hiding a row or a column

You can hide columns and rows in two ways.  The first is to use the Visible property of the TcxSSHeader object.  The index specifies the column/row to be hidden/displayed.  The TcxSSHeader object corresponding to the column/row header panel of the active worksheet can be obtained via the Cols/Rows property.

Write the following line of code to hide column B of the active worksheet.

// Delphi

cxSpreadSheetBook1.ActiveSheet.Cols.Visible[1] := False;

// C++ Builder

cxSpreadSheetBook1->ActiveSheet->Cols->Visible[1] = false;

You can also use the SetVisibleState method in order to hide row(s) or column(s).  This method is implemented in the TcxSSBookSheet class.  To access a desired worksheet specified by the TcxSSBookSheet object, you should use the Pages or ActiveSheet properties of a TcxSpreadSheetBook control and the Sheet property of a TcxSpreadSheet control.

The following sample code demonstrates how to hide both rows and columns, which contain the currently specified rectangular area. The appearance of the worksheet before code execution is displayed in the image below.

// Delphi

var ARect: TRect;

//...

ARect := cxSpreadSheetBook1.ActiveSheet.SelectionRect;

cxSpreadSheetBook1.ActiveSheet.SetVisibleState(ARect, True, True, False);

// C++ Builder

TRect aRect;

// ...

aRect = cxSpreadSheetBook1->ActiveSheet->SelectionRect;

cxSpreadSheetBook1->ActiveSheet->SetVisibleState(aRect, true, true, false);


Creating Formulas and Performing Calculations

In this topic we will discuss several common questions concerning formulas and their use.  We will show you how to enter a formula, edit it, and use references in formulas and functions.

•	Entering formulas

•	Editing formulas

•	Using references

•	Using functions

Entering formulas

A formula in a SpreadSheet always begins with an equal sign (=). The equal sign tells the SpreadSheet that the subsequent characters constitute a formula. Following the equal sign are the elements to be calculated (the operands), which are separated by calculation operators. The SpreadSheet calculates the formula from left to right, based upon specific order for each operator in the formula.

To enter a new formula into a cell, you must:

1.	Click the cell in which you want to enter the formula.

2.	Enter ‘=’ (an equal sign).

3.	Enter the formula.

4.	Press ENTER.

In order to enter a formula in code, you should use the Text property of the TcxSSCellObject object corresponding to the desired cell.  Remember to call the Recalc method of the TcxSpreadSheetBook or TcxSpreadSheet object in order to calculate the value of the entered formula.

The following sample code enters ‘= A1 + B2 / E1’ into the C3 cell.

// Delphi

var ACell: TcxSSCellObject;

//..

ACell := cxSpreadSheetBook1.ActiveSheet.GetCellObject(2, 2);

try

  ACell.Text := '= A1 + B2 / E1';

finally

  ACell.Free;

end;

cxSpreadSheetBook1.Recalc;

// C++ Builder

TcxSSCellObject *aCell;

// ...

aCell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(2, 2);

try {

  aCell->Text = "= A1 + B2 / E1";

}

__finally {

  delete aCell;

}

cxSpreadSheetBook1->Recalc();

Editing formulas

In order to edit a formula, you must:

1.	Double-click the cell containing the target formula.

2.	Edit the formula

3.	Press ENTER

If you want to change the formula in code, you should simply assign the new formula via the Text property of the TcxSSCellObject.  See the example of entering a formula listed above.

Using references

A formula can refer to constant values and to other cells. The cell that contains the formula is known as a dependent cell when its value depends on the values in other cells. For example, cell B2 is a dependent cell if it contains the formula ‘= C2’.  You can use the special reference operator : (semicolon) to specify a range of cells.  For instance, range A1:A4 denotes cells A1, A2, A3 and A4.  Range A1:B2 denotes cells A1, A2, B1 and B2.  Ranges are used in arithmetic functions involving multiple neighboring cells.

By default, if the cell to which a formula refers to changes, the dependent cell also changes.

Using functions

The SpreadSheet contains a number of predefined built-in functions.  They allow you to evaluate arithmetic and logical expressions, perform statistical calculations, and operate with date and time values.  Refer to the Built-in Functions topic for more information on the predefined functions.  You can register your own functions and use them the same way as the ones already provided.  Creating of custom functions is discussed in the Register Custom Functions topic.

Functions can be combined by operators and passed as arguments to other functions

To calculate the square of a sum of values in the A1:A4 range you can type the formula using the SUM function:

=SUM(A1:A4)^2

or programmatically:

// Delphi

var ACell: TcxSSCellObject;

//..

ACell := cxSpreadSheetBook1.ActiveSheet.GetCellObject(2, 2);

try

  ACell.Text := '=SUM(A1:A4)^2';

finally

  ACell.Free;

end;

cxSpreadSheetBook1.Recalc;

// C++ Builder

TcxSSCellObject *aCell;

// ...

aCell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(2, 2);

try {

  aCell->Text = "=SUM(A1:A4)^2";

}

__finally {

  delete aCell;

}

cxSpreadSheetBook1->Recalc();


Registering Custom Functions
Register Custom Functions

There is a number of built-in functions that you can use for calculations within ESS.  Though a large number of functions is supplied to satisfy the needs of most users, you can add your own custom functions at run-time.  You can place your custom functions within application code or store them in a dynamic link library in order to share them with other applications.

Below are the three ways to register a custom function:

The basics of custom function registration

Custom function is in an application module

Custom function is in a dynamic link library

The basics of custom function registration

In order to create custom functions for use in the ExpressSpreadSheet, a user has to implement several items:

1.	Write procedures handling custom functions.  Each custom function must have a corresponding procedure.  This procedure will be used for evaluating the custom function.

2.	Create a TcxFuncDefinition record for each custom function.  This record contains all necessary information for registering and evaluating the function: the function’s token used to represent a function when parsing a specific cell value, the name of the function used for accessing that function in the ExpressSpreadSheet, a procedure used to evaluate the function, and a TcxSSFuncParams value specifying the number of function arguments.

3.	Pass an array of records, created in the previous step as the RegisterFunctions function argument.

Note: Token values from 1 to 512 are reserved for MS Excel functions, so values greater than 512 must be used as custom function tokens.

RegisterFunctions function returns the number of successfully registered functions.  So, if this number does not coincide with the TcxFuncDefinition records array length, it means that some functions were not registered successfully.

Custom function in an application module

1. The following sample code demonstrates how to register functions in your application module.  The first function named CustomFunc1 returns half of the pi constant.

//Delphi

procedure CustomFunc1(Sender: TcxSSFunctionHandler);

begin

  Sender.SetFloatResult(Pi/2);

end;

//C++ Builder

void __fastcall CustomFunc1(TcxSSFunctionHandler* Sender) {

  //M_PI_2 constant is declared in the math.h header file

  Sender->SetFloatResult(M_PI_2);

}

The second function named CustomFunc2 returns the squared value of that function argument.  This function implementation includes two individual steps: writing a callback function, used for executing a function with each argument and writing the function evaluating code itself.  The second step starts with the call to the EnumParamValues method, which enumerates all parameters of a given type and passes them one by one to the callback procedure.  The type of function arguments is specified with a TcxValueTypes value.  After all parameters (in our case only one) are processed by the callback procedure, the result is returned by the SetFloatResult method.

//Deplhi

procedure CustomFunc2(Sender: TcxSSFunctionHandler);

  procedure CustomFuncCallBack(Sender: TcxSSFunctionHandler; const Value: Double);

  begin

      Sender.FloatValue := Value * Value;

  end;

begin

  Sender.EnumParamValues(@CustomFuncCallBack, [vtFloat]);

  Sender.SetFloatResult(Sender.FloatValue);

end;

//C++ Builder

void __fastcall CustomFuncCallBack(TcxSSFunctionHandler* Sender,

const double Value) {

    Sender->FloatValue = Value * Value;

}

void __fastcall CustomFunc2(TcxSSFunctionHandler* Sender) {

  Sender->EnumParamValues(CustomFuncCallBack, TcxValueTypes() << vtFloat);

  Sender->SetFloatResult(Sender->FloatValue);

}

2. After all function-evaluating procedures are ready, an array of the TcxFuncDefinition records must be composed.  The names given to custom functions are "MYFUNC1" and "MYFUNC2", their tokens are $6FFF and $6FFF - 1 correspondingly.

//Delphi

const

  ACustomFunctionDef: array [0..1] of TcxFuncDefinition =

  ((Token: $6FFF; Name: 'MYFUNC1'; Definition: CustomFunc1; Params: fpNone),

     (Token: $6FFF - 1; Name: 'MYFUNC2'; Definition: CustomFunc2; Params: fpFixed));

//C++ Builder

  TcxFuncDefinition ACustomFunctionDef[2];

    ACustomFunctionDef[0].Token = 0x6FFF;

    ACustomFunctionDef[0].Name =  "MYFUNC1";

    ACustomFunctionDef[0].Definition = CustomFunc1;

    ACustomFunctionDef[0].Params = Cxssformulas::fpNone;

    ACustomFunctionDef[0].ParamsCount = 0;

    ACustomFunctionDef[1].Token = 0x6FFF-1;

    ACustomFunctionDef[1].Name =  "MYFUNC2";

    ACustomFunctionDef[1].Definition = CustomFunc2;

    ACustomFunctionDef[1].Params = Cxssformulas::fpFixed;

    ACustomFunctionDef[1].ParamsCount = 1;

3. After the TcxFuncDefinition records array is formed, it needs to be passed to the RegisterFnctions method. This method registers all functions.

//Delphi

procedure TForm1.FormCreate(Sender: TObject);

begin

  TcxSSFunctionHandler.RegisterFunctions(ACustomFunctionDef);

end;

//C++ Builder

void __fastcall TForm1::FormCreate(TObject *Sender) {

    TcxSSFunctionHandler::RegisterFunctions( NULL ,ACustomFunctionDef, 1);

}

After these three steps, the custom functions are ready to be used in the ExpressSpreadSheet. Type the function name preceded by the ‘=’ sign and review the results.

Custom function in a dynamic link library

The following sample code demonstrates how to call a custom function from a dynamic link library.  The custom function is the first function (named "MYFUNC1" from the previous example).  The sample consists of two parts:

1.  code that is implemented in your application

2.  code that resides in the DLL file

Part of the code that is implemented in your application

//Delphi

uses

  ShareMem,

  Windows,

  SysUtils,

  cxSSFormulas,

var

  AModule: HModule;

  procedure RegisterFunc;

  var

    I: Integer;

    AProc: Pointer;

  const

    AFuncDef: TcxFuncDefinition =

       (Token: $6FFF; Name: 'MYFUNC1'; Params: fpNone);

  begin

    AModule := LoadLibrary('FuncDLL.DLL');

    AProc := GetProcAddress(AModule, PChar(AFuncDef.Name));

    if AProc <> nil then

    begin

      AFuncDef.Definition := AProc;

      I := TcxSSFunctionHandler.RegisterFunctions([AFuncDef]);

    end

    else

      raise Exception.Create('Undefined function in dll')

  end;

{$R *.res}

begin

  RegisterFunc;

  try

    Application.Initialize;

    Application.CreateForm(TForm1, Form1);

  Application.CreateForm(TForm2, Form2);

  Application.Run;

  finally

    FreeLibrary(AModule);

end;

//C++ Builder

HMODULE AModule;

void RegisterFunc() {

  TcxFuncDefinition AFuncDef;

  AFuncDef.Token = 0x6FFF;

  AFuncDef.Name = "MYFUNC1";

  AFuncDef.Params = fpNone;

  TcxSSFunction AProc;

  /* the ‘@’ symbol must precede the function name since it is

  declared in the DLL with the __fastcall modifier */

  char* funcName = "@MYFUNC1";

  AModule = LoadLibrary("FuncDLL.DLL");

  AProc = (TcxSSFunction)GetProcAddress(AModule, funcName);

  if (AProc) {

      AFuncDef.Definition = AProc;

      TcxSSFunctionHandler::RegisterFunctions(NULL, &AFuncDef, 0);

  }

    else

      throw Exception("Undefined function in dll");

}

WINAPI WinMain(HINSTANCE, HINSTANCE, LPSTR, int) {

  try {

    RegisterFunc();

    Application->Initialize();

    Application->CreateForm(__classid(TForm1), &Form1);

    Application->Run();

  }

  catch (Exception &exception) {

    Application->ShowException(&exception);

  }

  FreeLibrary(AModule);

  return 0;

}

Code that resides in the DLL file

//Delphi

procedure MYFUNC1(Sender: TcxSSFunctionHandler); export;

implementation

procedure MYFUNC1(Sender: TcxSSFunctionHandler);

begin

  Sender.SetFloatResult(Pi/2);

end;

//...

//C++ Builder

int WINAPI DllEntryPoint(HINSTANCE hinst, unsigned long reason, void* lpReserved) {

  return 1;

}

extern "C" __declspec(dllexport)

void __fastcall MYFUNC1(TcxSSFunctionHandler* Sender) {

  //M_PI_2 constant is declared in the math.h header file

  Sender->SetFloatResult(M_PI_2);

}


Performing Custom Painting

Designing a Custom Painting Class

Brief Description of the TcxSheetPainter Class

Desigining a Custom Painting Class

In order to perform custom worksheet painting, you should inherit a new class from the TcxSheetPainter class and override some of its protected methods and properties where needed.  Assume you want to change the manner in which the row and column header panels will be drawn in your application - you need to implement gradient fills for header elements.

First, you should declare your own class (let’s call it TMyPainter).  Since you are going to draw header panels, you have to override the DrawHeaderBrick method.  Additionally, the class introduces a new GradientRect procedure, which implements gradient fills.

// Delphi

TMyPainter = class(TcxSheetPainter)

  private

    procedure GradientRect(const ARect: TRect; IsHorizontal, IsSelected: Boolean);

  protected

    procedure DrawHeaderBrick(I, J: Integer); override;

end;

// C++ Builder

class TMyPainter : TcxSheetPainter {

  private:

    void __fastcall GradientRect(const TRect &ARect, bool IsHorizontal, bool IsSelected);

  protected:

    virtual void __fastcall DrawHeaderBrick(int I, int J);

};

The DrawHeaderBrick method’s arguments identify a header element within a bricks array.  This array is supported by the Bricks field of the ViewInfo property and provides internal data for all bricks visible at present.  The I argument defines a column and the J argument defines a row of a brick in the array.  To draw text within a header element, the ExDrawText method is called.  The text to output is obtained from the TextSettings field of the TcxSSInfoBrick structure.

// Delphi

procedure TMyPainter.DrawHeaderBrick(I, J: Integer);

var

  ARect: TRect;

begin

  with ViewInfo.Bricks[I, J] do

  begin

    //get the brick region

    ARect := DisplayRect;

    if (I = 1) and (J = 0) then Dec(ARect.Left);

    if (J = 1) and (I = 0) then Dec(ARect.Top);

    if (I = 0) and (J = 0) then

      //do not use gradient for the top left header panel brick

      Canvas.FillRect(ARect, fsSolid, ColorToRgb(clBtnFace),

                      ColorToRgb(clBtnFace))

    else

      GradientRect(ARect, J = 0, IsSelected and not HideSelection);

    //draw the border for a brick

    Canvas.FrameRect(ARect, Canvas.GetNativeColor(clBtnShadow),

                     IsSelected and not HideSelection);

    //draw a row or column id

    if  (I <> 0) or (J <> 0) then

    begin

      OffsetRect(ARect, 0, 2);

      Canvas.SetTextColor(ViewInfo.HeaderColor);

      Canvas.ExDrawText(ARect, TextSettings);

    end;

    //prevent a brick from being changed by subsequent calls

    //to drawing functions

    Canvas.ExcludeClipRect(DisplayRect);

  end;

end;

// C++ Builder

void __fastcall TMyPainter::DrawHeaderBrick(int I, int J) {

  TRect ARect;

  TcxSSInfoBrick brick = ViewInfo.Bricks[I][J];

  //get the brick region

  ARect = brick.DisplayRect;

  if (I == 1 && J == 0) ARect.Left--;

  if (J == 1 && I == 0) ARect.Top--;

  if (I == 0 && J == 0)

    //do not use gradient for the top left header panel brick

    Canvas->FillRect(ARect, fsSolid,

                    (TColor)Cxpainterwrapper::ColorToRGB(clBtnFace),

                    (TColor)Cxpainterwrapper::ColorToRGB(clBtnFace));

  else

    GradientRect(ARect, J == 0, brick.IsSelected && !HideSelection);

  //draw the border for a brick

  Canvas->FrameRect(ARect,

                   (TColor)Canvas->GetNativeColor(NULL, clBtnShadow),

                   brick.IsSelected && !HideSelection);

  //draw a row or column id

  if  (I != 0 || J != 0) {

    OffsetRect(&ARect, 0, 2);

    Canvas->ExDrawText(ARect, brick.TextSettings);

  }

  //prevent a brick from being changed by subsequent calls

  //to drawing functions

  Canvas->ExcludeClipRect(brick.DisplayRect);

}

GradientRect performs gradient fills in a horizontal or vertical direction based on the IsHorizontal parameter value.  The method implements a linear gradient: color gradually changes from one to another.  Different colors are applied when filling selected and non-selected header panel elements.  They are supported by the Colors array.  To implement gradient fills, a loop is used.  A new rectangle and a new fill color are calculated upon every iteration.

// Delphi

procedure TMyPainter.GradientRect(const ARect: TRect;

  IsHorizontal, IsSelected: Boolean);

  //Returns the Red, Green and Blue components of the color

  procedure ColorToRGBValues(AColor: TColor; var AR, AG, AB: Byte);

  begin

    AColor := ColorToRGB(AColor);

    AR := GetRValue(AColor);

    AG := GetGValue(AColor);

    AB := GetBValue(AColor);

  end;

var

  I, dR, dG, dB: Integer;

  R, G, B, R1, G1, B1: Byte;

  //rectangle filled previously

  PrevLine: TRect;

  //rectangle to fill currently

  LineRect: TRect;

  ABrush: HBrush;

const

  Colors: array[Boolean, 0..1] of TColor =

    ((clWhite, clBtnShadow), (clHighLight, clWhite));

begin

  //get the Red, Green and Blue components of the starting color

  //for the gradient

  ColorToRgbValues(Colors[IsSelected, 0], R1, G1, B1);

  //get the Red, Green and Blue components of the ending color

  //for the gradient

  ColorToRgbValues(Colors[IsSelected, 1], R, G, B);

  dR := R - R1;

  dG := G - G1;

  dB := B - B1;

  LineRect := ARect;

  PrevLine := ARect;

  for I := 0 to 255 do

  begin

    with ARect do

    begin

      if IsHorizontal then

      //determine rectangle boundaries for horizontal filling

      begin

        LineRect.Top := Top + MulDiv(I, Bottom - Top, $100);

        LineRect.Bottom := Top + MulDiv(I + 1, Bottom - Top, $100);

      end

      else

      //determine rectangle boundaries for vertical filling

      begin

        LineRect.Left := Left + MulDiv(I, Right - Left, $100);

        LineRect.Right := Left + MulDiv(I + 1, Right - Left, $100);

      end;

     //step over if the same rectangle was filled before

      if EqualRect(PrevLine, LineRect) then

         Continue;

      //define colors to fill

      R := R1 + MulDiv(I, dR, $FF);

      G := G1 + MulDiv(I, dG, $FF);

      B := B1 + MulDiv(I, dB, $FF);

      //create a brush to fill

      ABrush := CreateSolidBrush(RGB(R, G, B));

      try

        FillRect(Canvas.Canvas.Handle, LineRect, ABrush);

      finally

        DeleteObject(ABrush);

      end;

    end;

  end;

end;

// C++ Builder

void __fastcall TMyPainter::GradientRect(const TRect &ARect,

bool IsHorizontal, bool IsSelected) {

  int I, dR,dG, dB;

  byte R, G, B, R1, G1, B1;

  //rectangle filled previously

  TRect PrevLine;

  //rectangle to fill currently

  TRect LineRect;

  HBRUSH ABrush;

  int index;

  const TColor Colors[2][2] =

    {{clWhite, clBtnShadow}, {clHighlight, clWhite}};

  if(IsSelected)

    index = 1;

  else

    index = 0;

  //get the Red, Green and Blue components of the starting color

  //for the gradient

  ColorToRGBValues(Colors[index][0], R1, G1, B1);

  //get the Red, Green and Blue components of the ending color

  //for the gradient

  ColorToRGBValues(Colors[index][1], R, G, B);

  dR = R - R1;

  dG = G - G1;

  dB = B - B1;

  LineRect = ARect;

  PrevLine = ARect;

  for(I = 0; I<=255; I++) {

    //determine rectangle boundaries for horizontal filling

    if(IsHorizontal) {

      LineRect.Top = ARect.Top + MulDiv(I, ARect.Bottom - ARect.Top, 0x100);

      LineRect.Bottom = ARect.Top + MulDiv(I + 1, ARect.Bottom - ARect.Top, 0x100);

    }

    //determine rectangle boundaries for vertical filling

    else {

      LineRect.Left = ARect.Left + MulDiv(I, ARect.Right - ARect.Left, 0x100);

      LineRect.Right = ARect.Left + MulDiv(I + 1, ARect.Right - ARect.Left, 0x100);

    }

    //step over if the same rectangle was filled before

    if (PrevLine == LineRect) continue;

    //define colors to fill

    R = R1 + MulDiv(I, dR, 0xFF);

    G = G1 + MulDiv(I, dG, 0xFF);

    B = B1 + MulDiv(I, dB, 0xFF);

    //create a brush to fill

    ABrush = CreateSolidBrush(RGB(R, G, B));

    try {

      FillRect(Canvas->Canvas->Handle, &LineRect, ABrush);

    }

    __finally {

      DeleteObject(ABrush);

    }

  }

}

The implementation of the painting class is now finished.  In order to apply a new fill, you should set the PainterType property to ptCustom at design time or via the following code.

// Delphi

cxSpreadSheetBook1.PainterType := ptCustom;

// C++ Builder

cxSpreadSheetBook1->PainterType = ptCustom;

Then you should write an OnCustomPaint event handler and initialize its TcxSheetPainterClass parameter with the newly created class.  The following sample code demonstrates what you should do to make the control use your own painter to perform painting.

// Delphi

procedure TForm1.cxSpreadSheetBook1CustomPaint(Sender: TObject; var PainterClass: TcxSheetPainterClass);

begin

  PainterClass := TMyPainter;

end;

// C++ Builder

void __fastcall TForm1::cxSpreadSheetBook1CustomPaint(TObject *Sender, TcxSheetPainterClass &PainterClass) {

    PainterClass = __classid(TMyPainter);

}

You can see the result of this custom painting style implementation in the following image.

You can read the next topic section to obtain brief information about TcxSheetPainter class members.

Brief Description of the TcxSheetPainter Class

Below are the basic methods and properties implemented by the TcxSheetPainter class, which you may want to override or use in your painter class.

DrawCells method

DrawHeaderBrick method

DrawSelection method

Canvas property

HideSelection property

ViewInfo property

procedure DrawCells; virtual;

The DrawCells procedure is responsible for drawing cells.

procedure DrawHeaderBrick(I, J: Integer); virtual;

DrawHeaderBrick is responsible for drawing headers.  The I and J parameters are the coordinates of a particular brick’s data in the ViewInfo record.

procedure DrawSelection; virtual;

The DrawSelection procedure is responsible for the selection painting.

property Canvas: TcxCanvasWrapper;

The Canvas property of the TcxSheetPainter class determines a canvas for painting.  The TcxCanvasWrapper class provides faster drawing facilities since it uses system API functions to render a spreadsheet object.

property HideSelection: Boolean;

The HideSelection property of the TcxSheetPainter class determines whether the selection must not be displayed due to setting focus to another control.

property ViewInfo:  TcxSSViewInfoData;

The ViewInfo property of the TcxSheetPainter class returns a record of type TcxSSViewInfoData which describes all data for displaying spreadsheet cells, header panels cells, and drawing selection.

The most essential field of the TcxSSViewInfoData record is the Bricks field that returns a two-dimensional array describing all sheet cells visible at present (including row/column header panel elements).


Export and Import Data

The ExpressSpreadSheet allows you to load XLS files and save data contained within them to  XLS files - while maintaining the current visual presentation (cell data formats, cell styles, etc.).  In addition, ExpressSpreadSheet provides the ability to save workbook contents to a stream (stream out) and then load this data from a stream to another workbook (stream back).

Load from an XLS File

The ExpressSpreadSheet correctly loads not only cell values but also recognizes formulas contained within cells and performs necessary calculations.  ExpressSpreadSheet can recognize only a limited number of predefined formulas, which are known as built-in functions.  Functions are recognized by their tokens.  If a function cannot be recognized by the ExpressSpreadSheet, the corresponding cell will contain a 'Unknown formula' value (this text is displayed within all cells containing unidentified formulas if the ShowFormulas property is True).

The ExpressSpreadSheet does not load Excel macros when loading an MS Excel file – only cell contents and formatting are processed. Use the LoadFromFile method to load the contents of an MS Excel file to the ExpressSpreadSheet.  The name of the loaded XLS file (including its path) is specified via the FileName parameter of this method.

The following sample code demonstrates how to load a specific MS Excel file into the ExpressSpreadSheet.

// Delphi

//...

var AFileName: string;

//...

AFileName := 'C:\Test.xls';

cxSpreadSheetBook1.LoadFromFile(AFileName);

// C++ Builder

AnsiString fileName;

fileName = "F:\\Test.xls";

cxSpreadSheetBook1->LoadFromFile(fileName);

Save to an XLS File

The ExpressSpreadSheet correctly saves cell values and cell formulas to an MS Excel file.  Formulas (built-in or custom), which are similar to corresponding Excel functions, will be correctly saved to an XLS file.

Use the SaveToFile method to save the contents of the ExpressSpreadSheet to an MS Excel file.  The FileName parameter of this method specifies the file name in XLS format, including its path.  If the file already exists, it will be replaced without warning.

The following sample code demonstrates how to save data contained within the ExpressSpreadSheet to a specified MS Excel file.

// Delphi

//...

var AFileName: string;

//...

begin

  AFileName := 'C:\Test.xls';

  cxSpreadSheetBook1.SaveToFile(AFileName);

// C++ Builder

AnsiString fileName;

fileName = "F:\\Test.xls";

cxSpreadSheetBook1->SaveToFile(fileName);

Save To and Load From a Stream

The ExpressSpreadSheet includes methods that allow you to save the contents of a workbook to a stream and then load this data from the previously saved stream to another workbook.

Use the SaveToStream method to save all workbook settings to a stream.  These settings include information about all cell values, formulas, cell styles, fonts, etc.   Use the LoadFromStream method to load the previously saved workbook settings.  This method allows a user to load information from a stream object.

These methods have a single Stream parameter, which specifies stream objects.

The following code uses a memory stream to save to and load from spreadsheet contents.

//Delphi

var Stream : TMemoryStream;

//...

  Stream := TMemoryStream.Create;

  cxSSBook.SaveToStream(Stream);

  Stream.Position := 0;

  cxSSBook1.LoadFromStream(Stream);

  Stream.Free;

//C++ Builder

TMemoryStream * Stream = new TMemoryStream();

cxSSBook->SaveToStream(Stream);

Stream->Position = 0;

cxSSBook1->LoadFromStream(Stream);

delete Stream;


Worksheet and workbook specifications

Worksheet and workbook specifications

Feature	Maximum limit
Open workbooks	Limited by available memory and system resources.
Worksheet size	Number of rows and columns is limited by available memory and system resources.  When exporting to MS Excel, the maximum number of columns is 256, the maximum number of rows is 65536.
Column width	65536  points
Row height	65536  points
Length of cell contents (text)	limited by available memory and system resources.
Sheets in a workbook	256 max (default is 3 sheets).
Colors in a workbook	56 colors in the custom palette.
Cell styles in a workbook	Number of cells + 1.
Custom number formats	Not available in the current version.
Linked sheets	Limited by available memory
Custom functions	Only correctly registered functions that correspond to Excel functions can be exported.
Calculation specifications

Feature	Maximum limit
Number precision	15 – 16 digits
Largest allowed positive number	1.7 x 10^308
Smallest allowed negative number	-5.0 x 10^–324
Smallest allowed positive number	5.0 x 10^–324
Largest allowed negative number	-1.7 x 10^308
Length of formula contents	8024 bytes
Selected ranges	1
Arguments in a function	Depending on the Max function (= 8).
Nested levels of functions	Limited by available memory.
Number of available worksheet functions	Limited by available memory
Zero based date allowed for calculation	January 1, 1900
Largest amount of time that can be entered	9999:99:99


cxSSFormulas Unit Overview
cxSSFormulas Unit

Classes

TcxSSFunctionHandler

Other Types

TcxFloatFuncCallBack

TcxFuncDefinition

TcxSSErrorCode

TcxSSFunction

TcxStackItems

TcxStringFuncCallBack

TcxValueType

TcxValueTypes


TcxSSFunctionHandler
TcxSSFunctionHandler Object

Hierarchy          Properties          Methods

The TcxSSFunctionHandler object is used for parsing and executing both predefined MS Excel-style formulas and user-defined functions.

Unit

cxSSFormulas

TcxSSFunctionHandler = class(TObject);

Description

The TcxSSFunctionHandler class is used to register, parse and evaluate formulas.  ExpressSpreadSheet supports MS Excel-style formulas.  A user can write his/her own functions and register them for future use as well.  Each formula must have several necessary attributes: a token representing that formula in the token stack of the parsed cell’s contents, the formula name used to access that function in the ExpressSpreadSheet, a procedure used to evaluate that formula, and information about the number of formula arguments.  For additional information about registering custom functions see the Registering  Custom Functions topic in this help system.


TcxSSFunctionHandler Hierarchy
Hierarchy

TObject

     |


Properties for TcxSSFunctionHandler
TcxSSFunctionHandler Properties

TcxSSFunctionHandler          Legend

In TcxSSFunctionHandler

CallBackIndex

Col

Error

ErrorCode

FloatValue

IsValueAssigned

Page

ParamsCount

Row

StringValue


Methods for TcxSSFunctionHandler
TcxSSFunctionHandler Methods

TcxSSFunctionHandler          Legend

In TcxSSFunctionHandler

CheckCondition

EnumParamValues

ErrorCodeToStr

EvaluateExpression

FuncDefByName

FuncDefByToken

GetBooleanParameter

GetFloatParameter

GetStringParameter

RegisterFunctions

SetBooleanResult

SetError

SetFloatResult

SetStringResult

StringToTokens

TokensToExcelFormat

TokensToString


TcxSSFunctionHandler.CallBackIndex

TcxSSFunctionHandler          See Also

Returns a number of calls to a callback function.

property CallBackIndex: Integer;

Description

The CallBackIndex property allows you to know how many times a callback function has been called to evaluate a formula.  Callback functions are used for evaluating the formula which operates with a set of parameters and whose intermediate result can be overridden when calculating the formula for the next parameter in the set (for instance, the MIN function).  A callback function is called for every parameter in the formula argument list.  A callback function is invoked by the EnumParamValues method.

ReadOnly Property


TcxSSFunctionHandler.Col

TcxSSFunctionHandler

Specifies the column where the current formula is located.

property Col: Integer;

Description

Use this property to obtain the number of the column where the current formula is located.

ReadOnly Property


TcxSSFunctionHandler.Error

TcxSSFunctionHandler

Indicates that an error occurred.

property Error: Boolean;

Description

This property value is True when an error occurs; otherwise, it is False.

ReadOnly Property


TcxSSFunctionHandler.ErrorCode

TcxSSFunctionHandler

Specifies error code for the error.

property ErrorCode: TcxSSErrorCode;

Description

This property value contains the TcxSSErrorCode value specifying the error code for a specific error.

ReadOnly Property


TcxSSFunctionHandler.FloatValue

TcxSSFunctionHandler

Specifies a formula argument of type Double.

property FloatValue: Double;

Description

Use this property to specify the float value to use when calculating the current formula.


TcxSSFunctionHandler.IsValueAssigned

TcxSSFunctionHandler

Indicates whether a callback function associated with the current formula has executed at least once.

property IsValueAssigned: Boolean;

Description

Use this property to determine whether a callback function associated with the current formula has executed at least once.  This is required when calculating a formula operating with a set of parameters and whose intermediate result can be overridden when calculating the formula for the next parameter in the set (for instance, MS Excel MIN function).

ReadOnly Property


TcxSSFunctionHandler.Page

TcxSSFunctionHandler

Specifies the page where the current formula is located.

property Page: Integer;

Description

Use this property to obtain the page where the current formula is located.

ReadOnly Property


TcxSSFunctionHandler.ParamsCount

TcxSSFunctionHandler          See Also

Specifies the number of parameters to be passed into built-in functions.

property ParamsCount: Integer;

Description

Specifies the number of parameters to be passed into built-in functions.

ReadOnly Property


TcxSSFunctionHandler.Row

TcxSSFunctionHandler

Specifies the row where the current formula is located.

property Row: Integer;

Description

Use this property to obtain the row where the current formula is located.

ReadOnly Property


TcxSSFunctionHandler.StringValue

TcxSSFunctionHandler

Specifies a formula argument of type string.

property StringValue: string;

Description

Use this property to specify the string value to use when calculating the current formula.


TcxSSFunctionHandler.CheckCondition

TcxSSFunctionHandler

Checks specific Boolean expressions and sets the specified error code if unsuccessful.

function CheckCondition(ACondition: Boolean; AErrCode: TcxSSErrorCode): Boolean;

Description

Checks the Boolean expression specified via the ACondition parameter.  If its result is False, the error code specified via the AErrCode parameter is set.  This method is useful when implementing custom functions.  Since ExpressSpreadSheet formulas must return appropriate error codes if errors occur during their execution, this function is a good way of notifying a user of the error type.

The following example demonstrates how to use the CheckCondition method in the custom function implementation. This code implements the MS Excel Average function. The CheckCondition method is used to determine whether the number of arguments for counting the average value is greater than 0.

//Delphi

procedure xlfnAVERAGE(Sender: TcxSSFunctionHandler);

var

  ACount, ASum: Double;

begin

  CopyStackParamsEntry(Sender);

  with Sender do

  begin

    xlfnCount(Sender);

    ACount := GetFloatParameter;

    xlfnSum(Sender);

    ASum := GetFloatParameter;

    if CheckCondition(ACount > 0, ecDivZero) then

      FloatValue := ASum/ACount

    else

      FloatValue := 0;

    SetFloatResult(FloatValue);

  end;

end;


TcxSSFunctionHandler.EnumParamValues

TcxSSFunctionHandler

Enumerates parameters for the function represented via the AFunc parameter.

procedure EnumParamValues(AFunc: Pointer; AValueTypes: TcxValueTypes); virtual;

Description

Use this method to enumerate parameters for the function represented by the corresponding callback function.  The callback function’s pointer is specified by the AFunc parameter.


TcxSSFunctionHandler.ErrorCodeToStr

TcxSSFunctionHandler

Returns a string value representing the TcxSSErrorCode value specified by the ACode parameter.

function ErrorCodeToStr(ACode: TcxSSErrorCode): string;

Description

Use this method to obtain string representation of a specific error code.


TcxSSFunctionHandler.EvaluateExpression

TcxSSFunctionHandler

Evaluates the parsed formula whose location within the parsed formula stack is specified by the AFormulaPtr parameter.

type

  PcxSSFormulaRec = PcxSSFuncRec;

  PcxSSFuncRec = ^TcxSSFuncRec;

procedure EvaluateExpression(AFormulaPtr: PcxSSFormulaRec); virtual;

Description

Use this method to evaluate a parsed expression. The location of the formula to evaluate within the formula stack is specified via the AFormulaPtr parameter.


TcxSSFunctionHandler.FuncDefByName

TcxSSFunctionHandler

Locates the function with a specified name within the list of registered functions.

function FuncDefByName(const AName: string; var ADef: TcxFuncDefinition): Boolean;

Description

Use this method to locate a function with the specified name within the list of registered functions.  The name of the located function is specified via the AName parameter.  If a specific function is found, then this method returns True and the ADef parameter contains the TcxFuncDefinition object representing the located function.


TcxSSFunctionHandler.FuncDefByToken

TcxSSFunctionHandler

Locates the function with the specified token within the list of registered functions.

function FuncDefByToken(const AToken: Word; var ADef: TcxFuncDefinition): Boolean;

Description

Use this method to locate a function with the specified token within the list of registered functions.  The token of the located function is specified via the AToken parameter.  If a specific function is found, this method returns True and the ADef parameter contains the TcxFuncDefinition object representing the located function.


TcxSSFunctionHandler.GetBooleanParameter

TcxSSFunctionHandler

Accesses a Boolean parameter from the formula stack.

function GetBooleanParameter: Boolean; virtual;

Description

Use this method to obtain a required parameter type when performing formula calculations.


TcxSSFunctionHandler.GetFloatParameter

TcxSSFunctionHandler

Accesses a float parameter from the formula stack.

function GetFloatParameter: Double; virtual;

Description

Use this method to obtain a required parameter type when performing formula calculations.


TcxSSFunctionHandler.GetStringParameter

TcxSSFunctionHandler

Accesses a string parameter from the formula stack.

function GetStringParameter: string; virtual;

Description

Use this method to obtain a required parameter type when performing formula calculations.


TcxSSFunctionHandler.RegisterFunctions

TcxSSFunctionHandler

Registers a set of functions.

function RegisterFunctions(const AFuncList: array of TcxFuncDefinition): Integer;

Description

Use this method to register a set of custom functions. Each function to register must be represented by the TcxFuncDefinition object.


TcxSSFunctionHandler.SetBooleanResult

TcxSSFunctionHandler

Creates a stack item representing an expression result of type Boolean.

procedure SetBooleanResult(const Value: Boolean);

Description

Use this method to create a stack item representing an expression result of type Boolean.  The result value is specified via the Value parameter.


TcxSSFunctionHandler.SetError

TcxSSFunctionHandler

Returns a TcxSSErrorCode value representing a specific error code.

procedure SetError(ACode: TcxSSErrorCode);

Description

Use this method to return a specific error code representing the error that occurs during formula execution.  The error code to return is specified via the ACode parameter.


TcxSSFunctionHandler.SetFloatResult

TcxSSFunctionHandler

Creates a stack item representing an expression result of type Double.

procedure SetFloatResult(const Value: Double);

Description

Use this method to create a stack item representing an expression result of type Double.  The result value is specified via the Value parameter.


TcxSSFunctionHandler.SetStringResult

TcxSSFunctionHandler

Creates a stack item representing an expression result of type string.

procedure SetStringResult(const Value: string);

Description

Use this method to create a stack item representing an expression result of type string.  The result value is specified via the Value parameter.


TcxSSFunctionHandler.StringToTokens

TcxSSFunctionHandler

Parses a string specified via the AExpression into tokens and stores the parsed expression at the position within the tokens stack specified via the AFormulaPtr parameter.

type

  PcxSSFormulaRec = PcxSSFuncRec;

  PcxSSFuncRec = ^TcxSSFuncRec;

procedure StringToTokens(const AExpression: string; AFormulaPtr: PcxSSFormulaRec); virtual;

Description

Use this method to parse specific cell text into tokens.  The tokens sequence is stored in the tokens stack in the PcxSSFormulaRec object.


TcxSSFunctionHandler.TokensToExcelFormat

TcxSSFunctionHandler

Converts tokens at the token stack position specified via the AFormulaPtr parameter to MS Excel-format tokens.

type

  PcxSSFormulaRec = PcxSSFuncRec;

  PcxSSFuncRec = ^TcxSSFuncRec;

function TokensToExcelFormat(AFormulaPtr: PcxSSFormulaRec): TcxStackItem; virtual;

Description

Use this method to convert tokens representing a single formula in the stack to MS Excel-format tokens.  The formula’s tokens are obtained from the stack position specified via the AFormulaPtr parameter.


TcxSSFunctionHandler.TokensToString

TcxSSFunctionHandler

Converts tokens at the token stack position specified via the AFormulaPtr parameter to a text string.

type

  PcxSSFormulaRec = PcxSSFuncRec;

  PcxSSFuncRec = ^TcxSSFuncRec;

function TokensToString(AFormulaPtr: PcxSSFormulaRec): string; virtual;

Description

Use this method to convert tokens representing a single formula in the stack to a text string.  The formula’s tokens are obtained from the stack position specified via the AFormulaPtr parameter.


TcxFloatFuncCallBack
TcxFloatFuncCallBack type

Calls the function specified via the Sender parameter, passing Value as its argument.

Unit

cxSSFormulas

TcxFloatFuncCallBack = procedure(Sender: TcxSSFunctionHandler; const Value: Double);

Description

This type value is used to evaluate a specific formula with a specific parameter.


TcxFuncDefinition
TcxFuncDefinition type

Represents a function definition.

Unit

cxSSFormulas

TcxFuncDefinition = packed record

    Token: Word;

    Name: string;

    Definition: TcxSSFunction;

    case Params: TcxSSFuncParams of fpVariable, fpFixed:(ParamsCount: Byte);

end;

Description

Each ExpressSpreadSheet formula must be represented by a TcxFuncDefinition record regardless of whether it is built-in or user-defined.  A TcxFuncDefinition record contains all necessary information for parsing and evaluating a specific formula: a token, representing this formula, a function name, a TcxSSFunction object, used for calculating this formula and information about the number of formula parameters.


TcxSSErrorCode
TcxSSErrorCode type

Contains values returned as error codes of a specific formula’s calculation errors.

Unit

cxSSFormulas

TcxSSErrorCode = (ecNone, ecNull, ecDivZero, ecValue, ecRefErr, ecName, ecNUM, ecNA);

Description

Error codes are used when calculating formulas. They represent different types of errors that raise when evaluating a formula.

Value	Description	Mapping To MS Excel
ecNone	No error exists	No corresponding values
ecNull	Raises if an intersection of two areas is specified that do not intersect	Corresponds to MS Excel error type #NULL!
ecDivZero	Raises when a formula divides by 0 (zero)	Corresponds to MS Excel error type #DIV/0!
ecValue	Raises when the wrong type of argument or operand is used	Corresponds to MS Excel error type #VALUE!
ecRefErr	Raises when a cell reference is not valid	Corresponds to MS Excel error type #REF!
ecName	Raises when text in a formula is not recognized	Corresponds to MS Excel error type #NAME?
ecNUM	Raises when a numeric value is not correct for calculations in a current formula (see Calculation specifications)	Corresponds to MS Excel error type #NUM!
ecNA	Raises if no value is available for calculations	Corresponds to MS Excel error code #N/A


TcxSSFunction
TcxSSFunction type

Specifies a procedure used when evaluating a specific formula.

Unit

cxSSFormulas

TcxSSFunction = procedure(Sender: TcxSSFunctionHandler);

Description

TcxSSFunction specifies the procedure that handles execution of a specific formula.  This value is used when registering this formula in the TcxFuncDefinition structure representing it.


TcxStackItems
TcxStackItems type

Represents an array of token stack items.

Unit

cxSSFormulas

TcxStackItems = array of TcxStackItem;

Description

This type of value represents an array of tokens corresponding to a specific parsed formula.


TcxStringFuncCallBack
TcxStringFuncCallBack type

Calls a function specified via the Sender parameter, passing Value as its argument.

Unit

cxSSFormulas

TcxStringFuncCallBack = procedure(Sender: TcxSSFunctionHandler; const Value: string);

Description

This value type is used to evaluate a specific formula with a specific parameter.


TcxValueType
TcxValueType type

Contains values representing formula parameter types.

Unit

cxSSFormulas

TcxValueType = (vtString, vtFloat, vtBoolean);

Description

Formulas, supported by the ExpressSpreadSheet can have three types of arguments: string, Double and Boolean.  When a formula in a specific cell is being parsed, all formula parameters are replaced with tokens representing those parameter types.  All possible tokens for parameter types are stored in TcxValueType.

Value	Description
vtString	Represents a string type.
vtFloat	Represents a Double type.
vtBoolean	Represents a Boolean type.


TcxValueTypes
TcxValueTypes type

Represents a set of TcxValueType values.

Unit

cxSSFormulas

TcxValueTypes = set of TcxValueType;

Description

This type represents a set of TcxValueType values.  These types of values are used to pass the list of required parameter types to a specific procedure handling the corresponding formula.


cxSSPainters Unit Overview
cxSSPainters Unit

Classes

TcxSheetPainter

Other Types

TcxSheetPainterClass


TcxSheetPainter
TcxSheetPainter Object

Hierarchy        Properties          Methods

Represents a base class for drawing a spreadsheet.

Unit

cxSSPainters

TcxSheetPainter = class(TObject);

Description

The TcxSheetPainter class has several properties and methods which can be overridden to provide custom worksheet painting.  For instance, to draw custom header panels you should override the DrawHeaderBrick method.  The DrawCells method allows you to customize sheet cell drawing.

Bricks are rectangular areas which constitute the spreadsheet. Cells, header panel cells are bricks. To apply your own painter class to a spreadsheet you must set the PainterType property to ptCustom and handle the OnCustomPaint event.

See the Custom painting class designing topic for an example of creating a custom painting class.


TcxSheetPainter Hierarchy
Hierarchy

TObject


Properties of TcxSheetPainter
TcxSheetPainter Properties

TcxSheetPainter          Legend

In TcxSheetPainter

 	Canvas

HideSelection

 	Palette

 	ViewInfo


Methods for TcxSheetPainter
TcxSheetPainter Methods

TcxSheetPainter          Legend

In TcxSheetPainter

Create

Destroy

DrawCells

DrawHeaderBrick

DrawSelection

Paint


TcxSheetPainter.Canvas

TcxSheetPainter

Specifies the canvas for drawing spreadsheet elements.

property Canvas: TcxCanvasWrapper;

Description

The property specifies a graphic surface on which a spreadsheet is drawn.  The TcxCanvasWrapper class provides a number of methods to draw borders, selected regions, to fill cells, to render text, etc.

Property Readonly


TcxSheetPainter.HideSelection

TcxSheetPainter

Specifies whether to draw the selection when focus is moved to another control.

property HideSelection: Boolean;

Description

The selection is not drawn when the focus is moved to another control.  HideSelection is True if the selection must not be drawn, otherwise selected cells are filled with the color defined by the SelectionColor property of the Canvas object.


TcxSheetPainter.Palette

TcxSheetPainter

Specifies a palette which contains colors to draw spreadsheet elements.

type

  PcxExcelPalette = ^TcxExcelPalette;

property Palette: PcxExcelPalette;

Description

The Palette property points to an array of colors used to draw spreadsheet elements.  Only a limited number of colors is used to draw spreadsheet. You can access a specific color by its index.

Property Readonly


TcxSheetPainter.ViewInfo

TcxSheetPainter

Describes all necessary information to draw spreadsheet cells including header panel cells.

property ViewInfo:  TcxSSViewInfoData;

Description

The TcxSSViewInfoData structure describes all necessary information on drawing all spreadsheet bricks.

Property Readonly


TcxSheetPainter.Create

TcxSheetPainter

Creates a new TcxSheetPainter class instance.

type

  PcxExcelPalette = ^TcxExcelPalette;

constructor Create(APalette: PcxExcelPalette); virtual;

Description

The Create method creates a new instance of the TcxSheetPainter class and initializes the Palette property with the specified APalette parameter.


TcxSheetPainter.Destroy

TcxSheetPainter

Destroys a TcxSheetPainter object instance.

procedure Destroy; override;

Description

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


TcxSheetPainter.DrawCells

TcxSheetPainter

Draws spreadsheet cells.

procedure DrawCells; virtual;

Description

The DrawCells method draws spreadsheet cells.  All necessary information about cells is obtained from the ViewInfo property.


TcxSheetPainter.DrawHeaderBrick

TcxSheetPainter

Draws spreadsheet header panels.

procedure DrawHeaderBrick(I, J: Integer); virtual;

Description

The DrawHeaderBrick method draws header panel bricks. All bricks are accessible via the Bricks field of the ViewInfo property. The I, J indexes identifies the brick being painted.

See the Custom painting class designing topic for an example of creating a custom painting class.


TcxSheetPainter.DrawSelection

TcxSheetPainter

Draws a border for the selection area.

procedure DrawSelection; virtual;

Description

The DrawSelection method draws a border around the selection area.


TcxSheetPainter.Paint

TcxSheetPainter

Draws a spreadsheet.

procedure Paint(ACanvas: TcxCanvasWrapper; AInfoData: TcxSSViewInfoData); virtual;

Description

The Paint method is called whenever a spreadsheet must be drawn.  The method makes subsequent calls to the DrawCells and DrawSelection methods which draw visible spreadsheet cells and header panel cells.


TcxSheetPainterClass
TcxSheetPainterClass type

Specifies the class-reference type for the TcxSheetPainter class.

Unit

cxSSPainters

TcxSheetPainterClass = class of TcxSheetPainter;

Description

The TcxSheetPainterClass class reference is used in the OnCustomPaint event where a user may specify a custom painter class derived from the TcxSheetPainter class.


TcxExcelPalette

Declares a type to store colors for a spreadsheet.

Unit

cxExcelConst

type

  TcxExcelPalette = packed array[0..58] of TColor;

Description

A TcxExcelPalette object defines a palette to draw spreadsheet elements.  Only colors from the palette can be used.  Other methods and properties use colors from the palette by specifying their indexes.  For instance, the TcxSSFont.FontColor property identifies a color by its index in the palette.  The spreadsheet palette is supported by the Palette property of the TcxSpreadSheetBook and TcxSpreadSheet classes.

The palette is also passed as a parameter to the constructor of the TcxSheetPainter class.


TcxSSViewInfoData

Describes information on all bricks in a spreadsheet, cell unions, and their selection state.

Unit

cxSSViewInfo

type

  TcxSSViewInfoData = record

    DisplayRect   : TRect;

    Bounds        : TRect;

    DrawHeaders   : Boolean;

    Selection     : TRect;

    SelectedBricks: TRect;

    UnionBricks   : array of TcxSSUnionInfoBrick;

    Bricks        : array of array of TcxSSInfoBrick;

  end;

Description

Bricks are rectangular areas which constitute the spreadsheet.  Cells, header panel cells are bricks.  The TcxSSViewInfoData record contains all necessary data to draw a spreadsheet.  The TcxSheetPainter class has a TcxSheetPainter.ViewInfo property of type TcxSSViewInfoData that provides necessary information about bricks for drawing functions.

The following explains TcxSSViewInfoData fields:

Field	Description
DisplayRect	Specifies a rectangular region in pixels which the spreadsheet occupies on screen. The region does not include the area occupied by the CaptionBar panel.
Bounds	Identifies the top left and bottom right cells of the spreadsheet which are currently visible.  The Bounds property stores absolute coordinates for these cells.  Absolute coordinates are relative to cell A1, which is identified by a (0,0) pair.  Cell B2’s coordinates are (1,1) - etc.
DrawHeaders	Specifies whether header panels are visible.  The field is set to True if the ShowHeaders property is also set to True.  Otherwise DrawHeaders specifies False.
Selection	Identifies the bounds of the selection area.  A selection area includes cells which are selected at any moment in time.  Due to scrolling, certain selected cells may not be visible on-screen.  The Selection field specifies the top left and bottom right cells of a selection area regardless of whether they are visible.  Cell coordinates in the Selection field are relative to cell A1.  The A1 cell is identified by (0,0) coordinates, B2 is identified by (1,1) coordinates - etc.. The next image displays coordinates specified by the Selection field:
SelectedBricks	Identifies a visible portion of the selection area.  The SelectedBricks property stores coordinates for the top left and bottom right cells of this portion relative to the top left visible cell of a spreadsheet.  The top left visible cell of a spreadsheet has (1,1) relative coordinates. The next image displays coordinates specified by the SelectedBricks field:
UnionBricks	Specifies an array of visible cell unions.  A cell union is a set of cells that were merged.  It is represented by the TcxSSUnionInfoBrick record.
Bricks	Specifies an array of all visible bricks in the spreadsheet.  Bricks at row 0 identify horizontal header panel cells.  Bricks at column 0 identify vertical header panel cells.  The top left visible spreadsheet cell which might contain data is described by the element Bricks[1,1].


TcxSSUnionInfoBrick

A structure that represents a cell union.

Unit

cxSSViewInfo

type

  TcxSSUnionInfoBrick =  record

    UnionRange   : TRect;

    BrushStyle   : TcxSSFillStyle;

    BrushBkColor : TColor;

    BrushFGColor : TColor;

    TextRect     : TRect;

    DisplayRect  : TRect;

    IsSelected   : Boolean;

    TextSettings : TcxTextParameters;

  end;

Description

The TcxSSUnionInfoBrick record contains information on drawing a cell union.  A cell union is a set of cells which were merged.  The TcxSSViewInfoData.UnionBricks field describes all cell unions in a spreadsheet.  The TcxSSViewInfoData structure is provided by the TcxSheetPainter.ViewInfo property and contains all information to draw a spreadsheet.

The following explains TcxSSUnionInfoBrick fields:

Field	Description
UnionRange	Identifies the top left and bottom right cells coordinates of the union.  The coordinates of the UnionRange field are relative to the top left visible cell of a spreadsheet.  The top left visible cell of a spreadsheet has (1,1) relative coordinates. The image below demonstrates a cell union.
BrushStyle	A brush style from the TcxSSFillStyle enumerator to draw the cell’s background.
BrushBkColor	A background color used to draw a brush pattern.
BrushFGColor	A foreground color used to draw a brush pattern.
TextRect	A region which the cell’s text occupies.
DisplayRect	Specifies a rectangular region in pixels which the union occupies.
IsSelected	The flag that shows whether the cell union was selected.
TextSettings	Represents text and properties to draw it in the cell: such as horizontal and vertical alignments, font and others.


TcxSSInfoBrick

A structure that represents a spreadsheet brick.

Unit

cxSSViewInfo

type

  TcxSSInfoBrick = record

    Col, Row      : Integer;

    DisplayRect   : TRect;

    TextRect      : TRect;

    BrushStyle    : TcxSSFillStyle;

    BrushBkColor  : TColor;

    BrushFGColor  : TColor;

    Edges         : TcxEdgesInfo;

    TopEdgeVertex : TcxEdgeVertex;

    LeftEdgeVertex: TcxEdgeVertex;

    TextSettings  : TcxTextParameters;

    IsSelected    : Boolean;

    case IsMerge  : Boolean of

      True  : (UnionIndex: Integer);

      False : ();

  end;

Description

The TcxSSInfoBrick record contains information on a spreadsheet brick.  Bricks are standard spreadsheet cells and cells that constitute header panels.  The TcxSSViewInfoData.Bricks field describes all spreadsheet bricks.  The TcxSSViewInfoData structure is provided by the TcxSheetPainter.ViewInfo property and contains all information to draw a spreadsheet.

The following explains TcxSSInfoBrick fields:

Field	Description
Col, Row	Specifies a column and a row for the current brick.  They define absolute coordinates of a brick.  The A1 cell has coordinates (0,0), the B2 cell  (1,1) - etc.  The Row field of the horizontal header panel and the Col field of the vertical header panel specify (-1).
DisplayRect	A rectangular region in pixels that a brick occupies.
TextRect	The region which the brick text occupies.
BrushStyle	A brush style from the TcxSSFillStyle enumerator to draw the cell’s background.
BrushBkColor	A background color used to draw a brush pattern.
BrushFGColor	A foreground color used to draw a brush pattern.
Edges	Specifies a line style and color for the top, right, bottom, and left cell edges.
TopEdgeVertex	An array of rectangular regions which represent a top cell edge.  A cell edge comprises up to three rectangles.
LeftEdgeVertex	An array of rectangular regions which represent a left cell edge.  A cell edge comprises up to three rectangles.
TextSettings	Represents text and properties to draw it in the cell: such as horizontal and vertical alignments, font and others.
IsSelected	Determines whether a brick is selected.
IsMerge	Identifies whether a brick is merged and is included into a cell union, If that’s the case, the UnionIndex property specifies an index for this brick in the union.
UnionIndex	Specifies an index of a cell in the cell union, if it was merged with other cells.


TcxEdgesInfo

Contains information on the style and color of four cell edges.

Unit

cxSSViewInfo

type

TcxEdgesInfo = array[TcxSSEdgeBorder] of TcxEdgeInfo;

Description

Use the values of the TcxSSEdgeBorder class as indexes to access a specific cell edge.


TcxEdgeInfo

Describes line style and color to draw a cell edge.

Unit

cxSSViewInfo

type

  TcxEdgeInfo = packed record

    Style: TcxSSEdgeLineStyle;

    Color: TColor;

  end;

Description

The TcxEdgeInfo structure describes the style and color to draw a cell edge.  The TcxSSEdgeLineStyle class enumerates possible styles for a cell border.


TcxEdgeVertex

An array of rectangular regions which represent a cell edge.

Unit

cxSSViewInfo

type

TcxEdgeVertex = array[0..2] of TRect;

Description

A cell edge can be presented up to three rectangular regions. Each of the TcxEdgeVertex elements represents such a rectangle.


cxPainterWrapper Unit Overview

Classes

TcxCanvasWrapper

Types

TcxBackgroundMode

TcxOrientation

TcxPaintObjects

Functions

ColorToRGB


TcxCanvasWrapper

Hierarchy          Properties          Methods

Represents a canvas with a set of methods to render the ExpressSpreadSheet object.

Unit

cxPainterWrapper

TcxCanvasWrapper = class;

Description

The TcxCanvasWrapper class is a wrapper for the canvas object on which to draw spreadsheet information.  The class is used to render all spreadsheet elements: a sheet object itself, header panels and a caption bar.  The TcxCanvasWrapper object provides fast methods to draw graphics since it employs the system API - Though it is possible to use the Canvas property of the standard TCanvas class.

The class implements the ability to draw selected regions.  When a user selects specific spreadsheet cells they are displayed using mixed color.  This color is determined by the MixColors class function which mixes the specific color with the selection color.  The selection color is defined by the SelectionColor property.

To provide faster select operations, the class contains an internal array of mixed colors.  Therefore each time colors in the main palette are changed you should call the PaletteChanged method.


TcxCanvasWrapper Hierarchy
Hierarchy

TObject


Properties for TcxCanvasWrapper
TcxCanvasWrapper Properties

TcxCanvasWrapper	Legend

In TcxCanvasWrapper

BorderColor

Canvas

SelectionColor

TextColor

WindowColor


Methods for TcxCanvasWrapper
TcxCanvasWrapper Methods

TcxCanvasWrapper	Legend

In TcxCanvasWrapper

BeginPaint

CalculateTextExtents

Create

Destroy

DrawText

DrawTriangleGlyph

EndPaint

ExcludeClipRect

ExDrawText

FillRect

FrameRect

        GetNativeColor

GetTextExtent

InvertRect

Line

MixColors

PaletteChanged

Polygon

Rectangle

SelectFont

SetBkColor

SetBkMode

SetSingleText

SetTextColor

TextWidth

TextHeight


TcxCanvasWrapper.BorderColor

TcxCanvasWrapper
Specifies a default color to draw borders for spreadsheet cells.

property BorderColor: TColor;

Description

The BorderColor property specifies the color used to draw a grid – borders between spreadsheet cells.  It also identifies a default color when drawing with a pen.


TcxCanvasWrapper.Canvas

TcxCanvasWrapper	See also
Specifies a drawing surface to render spreadsheet elements.

property Canvas: TCanvas;

Description

The Canvas property provides access to methods and properties of the TCanvas class and thus allows you to draw graphical elements.  Note, however, that performance of such rendering is slower than using methods of the TcxCanvasWrapper class.  The TcxCanvasWrapper class exploits the API interface and eliminates unnecessary operations of canvas settings such as fonts, brushes, pens.


TcxCanvasWrapper.SelectionColor

TcxCanvasWrapper	See also
Specifies a color with which the selected regions are painted.

property SelectionColor: TColor;

Description

Use the SelectionColor property to set the color with which selected regions are drawn.  When it is necessary to draw a selected spreadsheet region, actual colors are defined by the MixColors function that produces a new mixed color.


TcxCanvasWrapper.TextColor

TcxCanvasWrapper	See also
Specifies a default color to draw text on the canvas.

property TextColor: TColor;

Description

The TextColor property specifies a default color to draw text on the canvas.


TcxCanvasWrapper.WindowColor

TcxCanvasWrapper	See also
Specifies a default color to draw a cell’s background in a spreadsheet.

property WindowColor: TColor;

Description

Use the WindowColor property to determine the color used to fill a cell’s background.  It also identifies the default color when drawing with the brush.


TcxCanvasWrapper.Create

TcxCanvasWrapper
Creates a TcxCanvasWrapper object and initializes its palette.

type

  PcxExcelPalette = ^TcxExcelPalette;

constructor Create(APalette: PcxExcelPalette); virtual;

Description

The constructor creates a TcxCanvasWrapper object and initializes necessary properties to their default values.  The APalette argument passed as a parameter identifies a palette of colors to render a spreadsheet surface.  Some methods of the TcxCanvasWrapper class provides two overloaded versions: using colors of type TColor and the indexed colors from the palette.


TcxCanvasWrapper.Destroy

TcxCanvasWrapper
Destroys a TcxCanvasWrapper object and frees memory allocated for it.

destructor Destroy; override;

Description

The destructor destroys an instance of the TcxCanvasWrapper object and releases memory allocated for it.


TcxCanvasWrapper.BeginPaint

TcxCanvasWrapper	See also
Initiates the painting operation for the given canvas.

procedure BeginPaint(ACanvas: TCanvas);

Description

Before you paint with the TcxCanvasWrapper object, the BeginPaint method should be called.  The specified ACanvas parameter indicates a canvas object on which to draw spreadsheet information.


TcxCanvasWrapper.CalculateTextExtents

TcxCanvasWrapper	See also
Fills the internal structure with the extent parameters to draw multiline text within a rectangular region.

procedure CalculateTextExtents(const AText: string; ATextRect: TRect;
    AHorzAlign: TcxHorzTextAlign; AVertAlign: TcxVertTextAlign;
    AWordBreak: Boolean; var ATextParams: TcxTextParameters);

Description

The CalculateTextExtents method fills the ATextParams structure with necessary information to draw AText within the rectangular region specified by the ATextRect parameter.   This information includes positions of individual words of text in the rectangle.  The ExDrawText method draws text using the filled structure.  The AHorzAlign and AVertAlign arguments define horizontal and vertical alignment within the rectangle respectively.

The CalculateTextExtents method wraps the text if it is too wide for the ATextRect width.  To prevent text from wrapping, use the SetSingleText method.


TcxCanvasWrapper.DrawText

TcxCanvasWrapper	See Also
Draws the specified text inside the clipping rectangle.

procedure DrawText(const AText: string; ARect: TRect);

Description

Use the DrawText method to draw the text using the current font inside the clipping rectangle specified by the ARect argument.  Before text is drawn, transparent background mode is set which ensures that the background remains untouched.  The text is aligned to the bottom and is centered horizontally.  If text is too wide, it is clipped to the rectangle.


TcxCanvasWrapper.DrawTriangleGlyph

TcxCanvasWrapper
Draws and fills a triangle within a specified rectangular region.

procedure DrawTriangleGlyph(const ARect: TRect; AColor: TColor;
    ALeftToRight: Boolean; IsDrawLine: Boolean);

Description

The DrawTriangleGlyph method draws a horizontal arrow within the rectangle specified by the ARect parameter.  It is drawn and filled with AColor.  The direction of an arrow is defined by the IsDrawLine parameter.  IsDrawLine indicates whether to draw additional vertical line along with the triangle.

The method is used to draw images on navigation buttons. The following table demonstrates the resulting images for different values for the ALeftToRight and IsDrawLine arguments.

ALeftToRight	IsDrawLine	Glyph
True	True
True	False
False	True
False	False


TcxCanvasWrapper.EndPaint

TcxCanvasWrapper	See also
Indicates the end of drawing on the canvas passed to the BeginPaint method.

procedure EndPaint; virtual;

Description

The EndPaint method should be called when rendering on the canvas is finished.  It sets the internal canvas pointer to NIL and thus prevents it from further changes.


TcxCanvasWrapper.ExcludeClipRect

TcxCanvasWrapper	See also
Excludes the specified rectangle from the existing clipping region.

procedure ExcludeClipRect(const ARect: TRect); overload;

procedure ExcludeClipRect(X1, Y1, X2, Y2: Integer); overload;

Description

Two overloaded methods exclude the rectangular region from the existing clipping region.  As a result they create a new clipping region only within which drawing is allowed.  The first method uses the TRect object to identify a rectangle to exclude.  In the second method, the rectangle is defined by coordinates of the left top and right bottom points.  To exclude a polygon from the clipping region, use the ExcludeClipRgn method.


TcxCanvasWrapper.ExcludeClipRgn

TcxCanvasWrapper	See also
Excludes the specified polygon from the existing clipping region.

procedure ExcludeClipRgn(const APoints: array of TPoint);

Description

The APoints parameter identifies an array of coordinates of a polygon region which should be excluded from the existing clipping region.  Use the ExcludeClipRect method to exclude a rectangle from the clipping region.


TcxCanvasWrapper.ExDrawText

TcxCanvasWrapper	See also
Draws a text within a clipping region.

procedure ExDrawText(const AClipRect: TRect;
    const AextTextParams: TcxTextParameters); virtual;

Description

ExDrawText draws a text which was processed by the CalculateTextExtents or SetSingleText methods.  The ATextRect parameter passed to the CalculateTextExtents or SetSingleText methods indicates the rectangular region within which the text should be drawn.  These methods fill the structure of the TcxTextParameters type with the information about each word position and this structure must be passed to the ExDrawText method.  The AClipRect parameter defines a clipping region within the ATextRect rectangle.  Only the portion of the text that falls into the AClipRect region will be drawn.


TcxCanvasWrapper.FillRect

TcxCanvasWrapper	See also
Fills the rectangle using the specified style pattern, background and foreground colors.

procedure FillRect(const ARect: TRect; AStyle: TcxSSFillStyle;
    ABkColor, AFgColor: TColor); overload;

procedure FillRect(const ARect: TRect; AStyle: TcxSSFillStyle;
    ABkColor, AFgColor: Word; IsSelected: Boolean); overload;

Description

The ARect parameter identifies a rectangle to fill.  The fill pattern is defined by the AStyle value.  Possible fill patterns are described by the TcxSSFillStyle enumerator.  ABkColor and AFgColor are the background and foreground colors respectively.  The first overloaded version uses the colors of type TColor while the second version uses colors from the palette whose pointer was passed in the TcxCanvasWrapper constructor.

The IsSelected flag shows whether the specified rectangle is selected by a user.  If this parameter value is True, the actual fill color is determined by the MixColors function which mixes the specified fill colors with the selection color (the SelectionColor property).

The image below demonstrates the spreadsheet cells rendered with the fill colors, selection color and the mixture of these colors.


TcxCanvasWrapper.FrameRect

TcxCanvasWrapper	See also
Draws a border around the specified rectangle.

procedure FrameRect(const ARect: TRect; AColor: TColor;
  IsSelected: Boolean = False); overload;

procedure FrameRect(const ARect: TRect;
  ATopColor,  ABottomColor: TColor;
  IsSelected: Boolean = False); overload;

Description

The ARect parameter identifies a rectangular region around which to draw a border.  The color of the border is defined by AColor value.  The second overloaded method allows you to set a color for the left, top and for the right, bottom edges generating the 3D-effect.  The IsSelected flag specifies True if the ARect region is selected by a user.  In this instance, the actual color to draw the border is determined by the MixColors function which mixes the passed colors with the selection color.  The selection color is defined by the SelectionColor property.


TcxCanvasWrapper.GetTextExtent

TcxCanvasWrapper	See also
Determines the width and height, in pixels, of a string drawn with the current font.

function GetTextExtent(const AText: string): TPoint;

Description

The AText parameter specifies the text for which to determine height and width.  The GetTextExtent function returns a TPoint structure.  Its X field identifies the width of the text to draw with the current font and the Y field identifies text height.


TcxCanvasWrapper.InvertRect

TcxCanvasWrapper
Inverts a rectangle in a canvas by performing a logical NOT operation on the color values for each pixel in the specified rectangle's interior.

procedure InvertRect(const ARect: TRect);

Description

The ARect parameter identifies a rectangle for which to perform a logical NOT operation on the color values for each pixel.  Calling InvertRect twice for the same rectangle restores the display to its previous colors.


TcxCanvasWrapper.Line

TcxCanvasWrapper	See also
Draws a line with the specified style.

procedure Line(const AVertex: TRect; AStyle: TcxSSEdgeLineStyle;
    AOrientation: TcxOrientation;
    ABkColor, AFgColor: TColor); overload;

procedure Line(const AVertex: array of TRect;
    AStyle: TcxSSEdgeLineStyle; AOrientation: TcxOrientation;
    ABkColor, AFgColor: Word; IsSelected: Boolean); overload;

Description

The methods allow drawing a line using only limited orientations which the TcxOrientation type enumerates.  The line style is defined by the AStyle parameter.  You should provide colors via the ABkColor and AFgColor arguments to draw empty and non-empty line sections.  In the first overloaded method, the colors are of type TColor and in the second, the colors are defined by the indexes in the palette.

In the first method, the AVertex parameter identifies the beginning and the ending points of the line.  In the case of horizontal orientation, the line is drawn from the (AVertex.Left; AVertex.Top) point to the (AVertex.Right; AVertex.Top) point.  If vertical orientation is used, the line will be drawn from the (AVertex.Left; AVertex.Top) point to the (AVertex.Left; AVertex.Bottom) point.

In the second overloaded Line method, the AVertex parameter identifies an array of rectangles.  The lines will be drawn for each rectangle as described for the first method.

The IsSelected flag determines whether the region occupied by the line is selected by a user.  If it is True, the actual colors used to draw a line are determined by the MixColors function which mixes the passed colors with the selection color.  The selection color is defined by the SelectionColor property.


TcxCanvasWrapper.PaletteChanged

TcxCanvasWrapper
Makes necessary initializations when palette colors change.

procedure PaletteChanged; virtual;

Description

Call the PaletteChanged method if any of the palette colors have changed.  The method reinitializes internal palette of mixed colors to provide faster rendering.


TcxCanvasWrapper.Polygon

TcxCanvasWrapper
Draws a series of lines connecting the specified points.

procedure Polygon(const APoints: array of TPoint; AColor: TColor);

Description

The Polygon method draws a series of lines connecting the points passed in and closing the shape by drawing a line from the last point to the first point.  The AColor parameter defines a color to draw a polygon.


TcxCanvasWrapper.Rectangle

TcxCanvasWrapper
Fills a rectangle with the specified brush.

type

{$IFDEF WINDOWS}

  TcxFillBrushHandle = HBrush;

{$ELSE}

  TcxFillBrushHandle = QBrushH;

{$ENDIF}

procedure Rectangle(ARect: TRect; ABrush: TcxFillBrushHandle);

Description

The Rectangle method fills a rectangle using the brush handle specified by the ABrush parameter.


TcxCanvasWrapper.SelectFont

TcxCanvasWrapper	See also
Selects a font for the canvas.

type

{$IFDEF WINDOWS}

  TcxFontHandle = HFont;

{$ELSE}

  TcxFontHandle = TcxSSFontRec;

{$ENDIF}

procedure SelectFont(const AFont: TcxFontHandle;
    ACheckSettings: Boolean = True); overload;

procedure SelectFont(const AFont: TcxFontHandle;
    AColor: Word); overload;

procedure SelectFont(AFont: TFont); overload;

{$IFDEF WINCLX}

procedure SelectFont(const AFont: TcxFontHandle); overload;

{$ENDIF}

Description

The SelectFont method selects a font for the canvas.  The font is specified by a font handler via the AFont parameter.  The ACheckSettings flag is used to eliminate unnecessary font setting if the same font is already set in the canvas.  If the ACheckSettings flag is True and the same font is already set in the canvas, then the procedure does nothing.  Otherwise it sets a new font for the canvas.

The AColor property specifies an index of the color in the palette.  If it does not identify an index in the color palette (greater than the number of colors in the palette), the value of the TextColor property is used.


TcxCanvasWrapper.SetBkColor

TcxCanvasWrapper	See also
Sets the current background color for the canvas.

procedure SetBkColor(AColor: TColor); overload;

procedure SetBkColor(AColor: Word; IsSelected: Boolean;
    AObject: TcxPaintObjects); overload;

Description

The first overloaded method sets the background color for the canvas to the value of TColor.

If IsSelected flag is True, a mixed color is set.  This color is defined by the MixColors function which mixes the value of the AColor parameter and the value of the SelectionColor property.

If the AColor value does not define an index in the palette, a default color is set.  In this instance, the default color is defined based upon the value of the AObject argument.  The following lists which default colors are obtained.

AObject value	The property whose value is used to set the current background color.
poBrush	WindowColor
poFont	TextColor
poPen	BorderColor


TcxCanvasWrapper.SetBkMode

TcxCanvasWrapper	See also
Sets the background mix mode of the canvas. The background mix mode is used with text, hatched brushes, and pen styles that are not solid lines.

procedure SetBkMode(AMode: TcxBackgroundMode);

Description

The background mix mode is defined by the TcxBackgroundMode enumerator.


TcxCanvasWrapper.SetSingleText

TcxCanvasWrapper	See also
Fills the internal structure with the extent parameters to draw a text in a single line within a rectangular region.

procedure SetSingleText(const AText: string; const ATextRect: TRect;
    var ATextSettings: TcxTextParameters;
    AVertCenterAlign: Boolean = True); virtual;

Description

The SetSingleText method fills the ATextParams structure with necessary information to draw AText within the rectangular region specified by the ATextRect parameter.   This information includes positions of individual words of the text in the rectangle.  The ExDrawText method draws the text using the filled structure.  The AVertCenterAlign argument defines whether the text is centered vertically.  If the flag is True the text is centered vertically.  Otherwise the text is aligned to the bottom.

The SetSingleText method does not wrap text if it is too wide for ATextRect width.  To enable word wrapping, use the CalculateTextExtents method.


TcxCanvasWrapper.SetTextColor

TcxCanvasWrapper	See also
Sets the current text color for the canvas.

procedure SetTextColor(AColor: TColor); overload;

procedure SetTextColor(AColor: Word; IsSelected: Boolean;
    AObject: TcxPaintObjects); overload;

Description

The first overloaded method sets the text color for the canvas to the value of TColor.

If IsSelected flag is True, a mixed color is set.  This color is defined by the MixColors function which mixes the value of the AColor parameter and the value of the SelectionColor property.

If the AColor value does not define an index in the palette, a default color is set.  In this instance, the default color is defined based upon the value of the AObject argument.  The following lists what default colors are obtained.

AObject value	The property whose value is used to set the current text color.
poBrush	WindowColor
poFont	TextColor
poPen	BorderColor


TcxCanvasWrapper.TextWidth

TcxCanvasWrapper	See also
Determines the width, in pixels, of the text drawn with the current font.

function TextWidth(const AText: string): Integer;

Description

The TextWidth functions returns a width, in pixels, of the text specified by the AText parameter.


TcxCanvasWrapper.TextHeight

TcxCanvasWrapper	See also
Determines the height, in pixels, of the text drawn with the current font.

function TextHeight(const AText: string): Integer;

Description

The TextHeight functions returns a height, in pixels, of the text specified by the AText parameter.


TcxCanvasWrapper.GetNativeColor

TcxCanvasWrapper
Converts a color to platform specific format.

class function GetNativeColor(AColor: TColor): Integer;

Description

The method returns an RGB or BGR representations of the specified color according to the type of library and platform used.  For Windows VCL and CLX libraries, the color is returned in RGB format.  In Kylix applications, BGR representation is used.


TcxCanvasWrapper.MixColors

TcxCanvasWrapper	See also
Returns a mixture of two specified colors.

class function MixColors(ASelColor, ASrcColor: TColor): TColor;

Description

The MixColors function returns a new color calculated from the two colors specified by the ASelColor and ASrcColor parameters.  This function is used to create a new color during spreadsheet region selection.


ColorToRGB

Converts a TColor value into an RGB representation of the color.

function ColorToRGB(AColor: TColor): Integer;

Description

Call the ColorToRGB method to return an RGB representation of the color specified by the AColor parameter.


TcxOrientation

Specifies the orientation of a line to draw by the TcxCanvasWrapper.Line method.

Unit

cxPainterWrapper

type

  TcxOrientation = (oHorz, oVert);

Description

The TcxOrientation type enumerates possible orientations of lines to draw by the TcxCanvasWrapper.Line method.

Value	Meaning
oHorz	Horizontal orientation.
overt	Vertical orientation.


TcxPaintObjects

Represents an enumeration to identify which color to set as a background or text color for the canvas.

Unit

cxPainterWrapper

type

  TcxPaintObjects = (poBrush, poFont, poPen);

Description

TcxPaintObjects values are used in the TcxCanvasWrapper.SetBkColor and TcxCanvasWrapper.SetTextColor methods.  These methods set the current background color and text color for the canvas respectively.  See reference topics for these methods for more information.


TcxBackgroundMode

Enumerates possible background mix modes for the canvas.

Unit

cxPainterWrapper

type

TcxBackgroundMode = (bmTransparent, bmOpaque);

Description

The background mix mode affects the manner in which text, hatched brushes, and pen are drawn.  To set the desired background mix mode, use the TcxCanvasWrapper.SetBkMode method.

Value	Meaning
bmTransparent	Background is filled with the current background color before the text, hatched brush, or pen is drawn.
bmOpaque	Background remains untouched.


cxSSStyles Unit Overview
cxSSStyles Unit

Classes

EStyleError

TcxSSBorderStyle

TcxSSBrush

TcxSSCellStyle

TcxSSEdgeStyle

TcxSSFont

TcxSSStyle


EStyleError
EStyleError Object

Hierarchy

The EStyleError object is an exception class for header manipulation errors.

Unit

cxSSStyles

EStyleError = class(Exception)

Description

The EStyleError exception is raised if an error occurs while your application is working with styles.  When the exception is raised, an error-message is displayed.  Message text is stored as a constant within the cxSSStrs.pas resource strings file and this constant name is passed as a parameter to the exception constructor.

This error is raised when setting invalid color, format or trying to access a cell with invalid column or row indexes.


EStyleError Hierarchy
Hierarchy

Exception


TcxSSBorderStyle
TcxSSBorderStyle Object

Hierarchy          Properties

Contains information about cell edge style.

Unit

cxSSStyles

TcxSSBorderStyle = class(TcxSSStyle)

Description

This object provides properties and methods that allow you to manage the border style of a cell.  It gives you the ability to manipulate the color and line style of cell edges.  This object is referenced by the Borders property of the TcxSSCellStyle object.


TcxSSBorderStyle Hierarchy
Hierarchy

TObject

     |

TcxSSStyle


Properties for TcxSSBorderStyle
TcxSSBorderStyle Properties

TcxSSBorderStyle          Legend

In TcxSSBorderStyle

Bottom

Edges

Left

Right

Top

Derived from TcxSSStyle

LockUpdate


TcxSSBorderStyle.Bottom

TcxSSBorderStyle          See Also

Represents the cell‘s bottom edge style.

property Bottom: TcxSSEdgeStyle;

Description

This property returns a TcxSSEdgeStyle class instance that specifies the style of the cell’s bottom edge.  Properties of this class instance allow you to change the color and line style of the edge.

The line style and the color of the edge are set via the Style and Color properties of the corresponding TcxSSEdgeStyle class instance.

The following sample code specifies the style for the bottom edge of cell B2.

// Delphi

var

  ACell: TcxSSCellObject;

  ABorderStyle: TcxSSBorderStyle;

//...

ACell := cxSpreadSheetBook1.ActiveSheet.GetCellObject(1, 1);

try

  ABorderStyle := ACell.Style.Borders;

  with ABorderStyle.Bottom do

  begin

    Style := lsMediumDashDot;

    Color := 0; //clBlack

  end;

finally

  ACell.Free;

end;

// C++ Builder

TcxSSCellObject *cell;

TcxSSBorderStyle *borderStyle;

cell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(1, 1);

try {

  borderStyle = cell->Style->Borders;

  borderStyle->Bottom->Color = 0; //clBlack

  borderStyle->Bottom->Style = lsMediumDashDot;

}

__finally {

  delete cell;

}

ReadOnly Property


TcxSSBorderStyle.Edges

TcxSSBorderStyle          See Also

Represents the style of a cell edge.

property Edges[Index:TcxSSEdgeBorder]: TcxSSEdgeStyle;

Description

This property returns a TcxSSEdgeStyle class instance that represents the style of the cell edge specified by the Index parameter.  Properties of this class instance allow you to change the color and line style of the edge. The line style and the color of the edge are set via the Style and Color properties of the corresponding TcxSSEdgeStyle class instance.

The following sample code sets the same style for all cell edges.

// Delphi

var

  ACell: TcxSSCellObject;

  ABorderStyle: TcxSSBorderStyle;

  i: TcxSSEdgeBorder;

//...

ACell := cxSpreadSheetBook1.ActiveSheet.GetCellObject(1, 1);

try

  ABorderStyle := ACell.Style.Borders;

  for i := eLeft to eBottom do

    with ABorderStyle.Edges[i] do

    begin

      Style := lsDouble;

      Color := 3; //clGreen

    end;

finally

  ACell.Free;

end;

// C++ Builder

TcxSSCellObject *cell;

TcxSSBorderStyle *borderStyle;

TcxSSEdgeBorder i;

cell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(1, 1);

try {

  borderStyle = cell->Style->Borders;

  for (i = eLeft; i <= eBottom; i = i + 1) {

    borderStyle->Edges[i]->Style = lsDouble;

    borderStyle->Edges[i]->Color = 3; //clGreen

  }

}

__finally {

  delete cell;

}

ReadOnly Property


TcxSSBorderStyle.Left

TcxSSBorderStyle          See Also

Represents the style of the cell’s left edge.

property Left: TcxSSEdgeStyle;

Description

This property returns a TcxSSEdgeStyle class instance that specifies the style of the cell’s left edge.  Properties of this class instance allow you to change the color and line style of the edge. The line style and the color of the edge are set via the Style and Color properties of the corresponding TcxSSEdgeStyle class instance.

The following sample code specifies the style for the left edge of cell B2.

// Delphi

var

  ACell: TcxSSCellObject;

  ABorderStyle: TcxSSBorderStyle;

//...

ACell := cxSpreadSheetBook1.ActiveSheet.GetCellObject(1, 1);

try

  ABorderStyle := ACell.Style.Borders;

  with ABorderStyle.Left do

  begin

    Style := lsDouble;

    Color := 2; //clRed

  end;

finally

  ACell.Free;

end;

// C++ Builder

TcxSSCellObject *cell;

TcxSSBorderStyle *borderStyle;

cell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(1, 1);

try {

  borderStyle = cell->Style->Borders;

  borderStyle->Left->Style = lsDouble;

  borderStyle->Left->Color = 2; //clRed

}

__finally {

  delete cell;

}

ReadOnly Property


TcxSSBorderStyle.Right

TcxSSBorderStyle          See Also

Represents the style of the cell’s right edge.

property Right: TcxSSEdgeStyle;

Description

This property returns a TcxSSEdgeStyle class instance that specifies the style of the cell’s right edge.  The properties of this class instance allow you to change the color and line style of the edge. The line style and the color of the edge are set via the Style and Color properties of the corresponding TcxSSEdgeStyle class instance.

The following sample code specifies the edge for the right edge of cell B2.

// Delphi

var

  ACell: TcxSSCellObject;

  ABorderStyle: TcxSSBorderStyle;

//...

ACell := cxSpreadSheetBook1.ActiveSheet.GetCellObject(1, 1);

try

  ABorderStyle := ACell.Style.Borders;

  with ABorderStyle.Right do

  begin

    Style := lsMedium;

    Color := 3; //clGreen

  end;

finally

  ACell.Free;

end;

// C++ Builder

TcxSSCellObject *cell;

TcxSSBorderStyle *borderStyle;

cell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(1, 1);

try {

  borderStyle = cell->Style->Borders;

  borderStyle->Right->Style = lsMedium;

  borderStyle->Right->Color = 3; //clGreen

}

__finally {

  delete cell;

}

ReadOnly Property


TcxSSBorderStyle.Top

TcxSSBorderStyle          See Also

Represents the style of the cell’s top edge.

property Top: TcxSSEdgeStyle;

Description

This property returns a TcxSSEdgeStyle class instance that specifies the style of the cell’s top edge.  Properties of this class instance allow you to change the color and line style of the edge. The line style and the color of the edge are set via the Style and Color properties of the corresponding TcxSSEdgeStyle class instance.

The following sample code specifies the style for the top edge of cell B2.

// Delphi

var

  ACell: TcxSSCellObject;

  ABorderStyle: TcxSSBorderStyle;

//...

ACell := cxSpreadSheetBook1.ActiveSheet.GetCellObject(1, 1);

try

  ABorderStyle := ACell.Style.Borders;

  with ABorderStyle.Top do

  begin

    Style := lsDotted;

    Color := 4; //clBlue

  end;

finally

  ACell.Free;

end;

// C++ Builder

TcxSSCellObject *cell;

TcxSSBorderStyle *borderStyle;

cell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(1, 1);

try {

  borderStyle = cell->Style->Borders;

  borderStyle->Top->Style = lsDotted;

  borderStyle->Top->Color = 4; //clBlue

}

__finally {

  delete cell;

}

ReadOnly Property


TcxSSBrush
TcxSSBrush Object

Hierarchy          Properties          Methods

Represents the brush used to fill the background of a cell.

Unit

cxSSStyles

TcxSSBrush = class(TcxSSStyle)

Description

The ExpressSpreadSheet control allows you to customize the background of cells.  The TcxSSBrush object contains the properties used to set fill pattern and the color of cell background. This object is referenced by the Brush property of the TcxSSCellStyle object.


TcxSSBrush Hierarchy
Hierarchy

TObject

     |

TcxSSStyle

     |


Properties for TcxSSBrush
TcxSSBrush Properties

TcxSSBrush          Legend

In TcxSSBrush

BackgroundColor

ForegroundColor

Style

Derived from TcxSSStyle

LockUpdate


Methods for TcxSSBrush
TcxSSBrush Methods

TcxSSBrush          Legend

In TcxSSBrush

AssignInfo


TcxSSBrush.BackgroundColor

TcxSSBrush          See Also

Specifies the background color of a cell.

property BackgroundColor: Word;

Description

Use this property to set the background color of a cell.  The BackgroundColor property specifies the index of the background color in the spreadsheet palette supported by the Palette property.  The pattern used to populate a cell is specified by the Style property of the TcxSSBrush object.  The color used to populate a cell with a specific pattern is specified by the ForegroundColor property.

The following sample code demonstrates how to set different background and foreground colors for a cell.

// Delphi

var

  ACell: TcxSSCellObject;

  ABrush: TcxSSBrush;

  i: Integer;

const

  AFillStyles: array [0..3] of TcxSSFillStyle = (fsSolid, fsDiagonalStrip,

     fsThinDiagCrossHatch, fsVertStrip);

  ABackColors: array [0..3] of Word = (4, 2, 5, 3);

  AForeColors: array [0..3] of Word = (1, 5, 4, 7);

//...

for i := 0 to 3 do

begin

  ACell := cxSpreadSheetBook1.ActiveSheet.GetCellObject(0, i);

  try

    ABrush := ACell.Style.Brush;

    ABrush.ForegroundColor := AForeColors[i];

    ABrush.BackgroundColor := ABackColors[i];

    ABrush.Style := AFillStyles[i];

  finally

    ACell.Free;

  end;

end;

// C++ Builder

TcxSSCellObject *cell;

TcxSSBrush *brush;

int i;

TcxSSFillStyle fillStyles[]  = {fsSolid, fsDiagonalStrip, fsThinDiagCrossHatch, fsVertStrip};

unsigned short backColors[] = {4, 2, 5, 3};

unsigned short foreColors[] = {1, 5, 4, 7};

for (i = 0; i < 4; i++) {

  cell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(0, i);

  try {

    brush = cell->Style->Brush;

    brush->ForegroundColor = foreColors[i];

    brush->BackgroundColor = backColors[i];

    brush->Style = fillStyles[i];

  }

  __finally {

    delete cell;

  }

}


TcxSSBrush.ForegroundColor

TcxSSBrush          See Also

Specifies the fill color of a cell.

property ForegroundColor: Word;

Description

Use this property to set the fill color of a cell.  The ForegroundColor property specifies the index of the fill color in the spreadsheet palette supported by the Palette property.  The pattern used to fill a cell is specified by the Style property of the TcxSSBrush object.  The background color of a cell is specified via the BackgroundColor property.

The ForegroundColor property is not in effect if the Style property is fsSolid.

The following sample code demonstrates how to set different background and foreground colors of a cell.

// Delphi

var

  ACell: TcxSSCellObject;

  ABrush: TcxSSBrush;

  i: Integer;

const

  AFillStyles: array [0..3] of TcxSSFillStyle = (fsSolid, fsDiagonalStrip,

     fsThinDiagCrossHatch, fsVertStrip);

  ABackColors: array [0..3] of Word = (4, 2, 5, 3);

  AForeColors: array [0..3] of Word = (1, 5, 4, 7);

//...

for i := 0 to 3 do

begin

  ACell := cxSpreadSheetBook1.ActiveSheet.GetCellObject(0, i);

  try

    ABrush := ACell.Style.Brush;

    ABrush.ForegroundColor := AForeColors[i];

    ABrush.BackgroundColor := ABackColors[i];

    ABrush.Style := AFillStyles[i];

  finally

    ACell.Free;

  end;

end;

// C++ Builder

TcxSSCellObject *cell;

TcxSSBrush *brush;

int i;

TcxSSFillStyle fillStyles[]  = {fsSolid, fsDiagonalStrip, fsThinDiagCrossHatch, fsVertStrip};

unsigned short backColors[] = {4, 2, 5, 3};

unsigned short foreColors[] = {1, 5, 4, 7};

for (i = 0; i < 4; i++) {

  cell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(0, i);

  try {

    brush = cell->Style->Brush;

    brush->ForegroundColor = foreColors[i];

    brush->BackgroundColor = backColors[i];

    brush->Style = fillStyles[i];

  }

  __finally {

    delete cell;

  }

}


TcxSSBrush.Style

TcxSSBrush          See Also

Specifies the background fill pattern of a cell.

property Style: TcxSSFillStyle;

Description

Use this property to specify the pattern used to fill the background of a cell.  The color used to fill the background is specified by the BackgroundColor property of the TcxSSBrush object.  The color of the brush is set via the ForegroundColor property.

The following sample code demonstrates fill pattern types.

// Delphi

var

  ACell: TcxSSCellObject;

  ABrush: TcxSSBrush;

  AFillStyle: TcxSSFillStyle;

  i: Integer;

//...

i := 0;

for AFillStyle := fsSolid to fsThinThickCrossHatch do

begin

  ACell := cxSpreadSheetBook1.ActiveSheet.GetCellObject(0, i);

  try

    ABrush := ACell.Style.Brush;

    ABrush.BackgroundColor := 2; //clRed

    ABrush.ForegroundColor := 5; //clYellow

    ABrush.Style := AFillStyle;

    i := i + 1;

  finally

    ACell.Free;

  end;

end;

// C++ Builder

TcxSSCellObject *cell;

TcxSSBrush *brush;

TcxSSFillStyle fillStyle;

int i = 0;

for (fillStyle = fsSolid; fillStyle <= fsThinThickCrossHatch; fillStyle = fillStyle + 1) {

  cell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(0, i++);

  try {

    brush = cell->Style->Brush;

    brush->BackgroundColor = 2; //clRed

    brush->ForegroundColor = 5; //clYellow

    brush->Style = fillStyle;

  }

  __finally {

    delete cell;

  }

}


TcxSSBrush.AssignInfo

TcxSSBrush          See Also

Initializes the properties of a TcxSSBrush object with parameter values.

procedure AssignInfo(AStyle: TcxSSFillStyle; const ABackgroundColor, AForegroundColor: Word); virtual;

Description

Use this method to initialize the properties of a TcxSSBrush class instance with parameter values.  The AStyle parameter sets the Style property value.  The ABackgroundColor and AForegroundColor properties set the BackgroundColor and ForegroundColor property values respectively.  They identify color indexes in the spreadsheet palette (the Palette property of the TcxSpreadSheetBook and TcxSpreadSheet classes).

The following sample code sets the fill pattern, background and foreground colors of cell B2.

// Delphi

var

  ACell: TcxSSCellObject;

  ABrush: TcxSSBrush;

//...

ACell := cxSpreadSheetBook1.ActiveSheet.GetCellObject(1, 1);

try

  ABrush := ACell.Style.Brush;

  ABrush.AssignInfo(fsThinDiagCrossHatch, 2, 5);

finally

  ACell.Free;

end;

// C++ Builder

TcxSSCellObject *cell;

TcxSSBrush *brush;

cell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(1, 1);

try {

  brush = cell->Style->Brush;

  brush->AssignInfo(fsThinDiagCrossHatch, 2, 5);

}

__finally {

  delete cell;

}


TcxSSCellStyle
TcxSSCellStyle Object

Hierarchy          Properties          Methods

Represents the style of a cell.

Unit

cxSSStyles

TcxSSCellStyle = class(TObject)

Description

A reference to this object can be obtained via the Style property of the TcxSSCellObject object.  It is used to manage cell style.  You can manipulate the font used to display cell values, its border style, the format of the displayed value, read-only status etc.

Note: Cell text is formatted using default settings during editing.


TcxSSCellStyle Hierarchy
Hierarchy

TObject


Properties for TcxSSCellStyle
TcxSSCellStyle Properties

TcxSSCellStyle          Legend

In TcxSSCellStyle

Borders

Brush

Col

Font

Format

HorzTextAlign

IsMain

IsMerge

Locked

ReadOnly

Row

VertTextAlign

WordBreak


Methods for TcxSSCellStyle
TcxSSCellStyle Methods

TcxSSCellStyle          Legend

In TcxSSCellStyle

Assign

Create

Destroy


TcxSSCellStyle.Borders

TcxSSCellStyle          See Also

Specifies the style of cell edges.

property Borders: TcxSSBorderStyle;

Description

Use this property to access cell edge styles.  It allows you to manipulate the color and line style of the top, bottom, left and right edges separately.

The following sample code applies the same style to all edges of cell B2.

// Delphi

var

  ACell: TcxSSCellObject;

  i: TcxSSEdgeBorder;

// ...

ACell := cxSpreadSheetBook1.ActiveSheet.GetCellObject(1, 1);

try

  with ACell.Style.Borders do

    for i := eLeft to eBottom do

    begin

      Edges[i].Color := 4; //clBlue

      Edges[i].Style := lsMediumDashDotDot;

    end;

finally

  ACell.Free;

end;

// C++ Builder

TcxSSCellObject *cell;

TcxSSBorderStyle *borderStyle;

TcxSSEdgeBorder i;

cell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(1, 1);

try {

  borderStyle = cell->Style->Borders;

  for (i = eLeft; i <= eBottom; i = i + 1) {

    borderStyle->Edges[i]->Color = 4; //clBlue

    borderStyle->Edges[i]->Style = lsMediumDashDotDot;

  }

}

__finally {

  delete cell;

}

ReadOnly Property


TcxSSCellStyle.Brush

TcxSSCellStyle          See Also

Specifies the background appearance of a cell.

property Brush: TcxSSBrush;

Description

Use this property to adjust the background of a cell.  This property references the TcxSSBrush object, which contains Style, ForegroundColor and BackgroundColor properties.  These properties allow you to set the fill pattern and the colors used to fill a cell respectively.

The following sample code sets the fill pattern, background and foreground color of cell B2.

// Delphi

var

  ACell: TcxSSCellObject;

  ABrush: TcxSSBrush;

//...

ACell := cxSpreadSheetBook1.ActiveSheet.GetCellObject(1, 1);

try

  ABrush := ACell.Style.Brush;

  ABrush.AssignInfo(fsThinDiagCrossHatch, 2, 5);

finally

  ACell.Free;

end;

// C++ Builder

TcxSSCellObject *cell;

TcxSSBrush *brush;

cell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(1, 1);

try {

  brush = cell->Style->Brush;

  brush->AssignInfo(fsThinDiagCrossHatch, 2, 5);

}

__finally {

  delete cell;

}

ReadOnly Property


TcxSSCellStyle.Col

TcxSSCellStyle          See Also

Returns the zero-based index of the column to which a cell belongs.

property Col: Integer;

Description

Use this property to get the zero-based index of the column to which a cell belongs.  The row index that contains the cell can be obtained via the Row property.

ReadOnly Property


TcxSSCellStyle.Font

TcxSSCellStyle          See Also

Specifies the font used to display a cell value.

property Font: TcxSSFont;

Description

Use this property to customize the font used to display a cell value.  This property returns a reference to the TcxSSFont object.  This object allows you to manage font type, its size, style and character set.

The following code changes the typeface, size and color of the font used to display cell B2 and makes it bold and underlined.

// Delphi

var ACell: TcxSSCellObject;

//...

ACell := cxSpreadSheetBook1.ActiveSheet.GetCellObject(1, 1);

try

  ACell.Text := 'Cell B2';

  with ACell.Style.Font do

  begin

    Name := 'Verdana';

    Size := 12;

    Style := [fsBold, fsUnderline];

    FontColor := 4; //clBlue

  end;

finally

  ACell.Free;

end;

// C++ Builder

TcxSSCellObject *cell;

TcxSSFont *font;

cell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(1, 1);

try {

  cell->Text = "Cell B2";

  font = cell->Style->Font;

  font->Name = "Verdana";

  font->Size = 12;

  font->Style = TFontStyles() << fsBold << fsUnderline;

  font->FontColor = 4; //clBlue

}

__finally {

  delete cell;

}

ReadOnly Property


TcxSSCellStyle.Format

TcxSSCellStyle          See Also

Specifies the format of a cell value.

type

  TxlsDataFormat = 0..$23;

property Format: TxlsDataFormat;

Description

The Format property allows you to specify a predefined number format for a cell.  The TxlsDataFormat type defines standard formats that can be applied to cell numbers.  The format strings are like those found in MS Excel®. The following table lists available format strings:

Index	Format
$00	Default
$01	0
$02	0.00
$03	#,##0
$04	#,##0.00
$05	_($#,##0_);($#,##0)
$06	_($#,##0_);[Red]($#,##0)
$07	_($#,##0.00_);($#,##0.00)
$08	_($#,##0.00_);[Red]($#,##0.00)
$09	0%
$0A	0.00%
$0B	0.00E+00
$0C	# ?/?
$0D	# ??/??
$0E	m/d/yy
$0F	d-mmm-yy
$10	d-mmm
$11	mmmm-yy
$12	h:mm AM/PM
$13	h:mm:ss AM/PM
$14	h:mm
$15	h:mm:ss
$16	m/d/yy h:mm
$17	(#,##0_);(#,##0)
$18	(#,##0_);[Red](#,##0)
$19	(#,##0.00_);(#,##0.00)
$1A	(#,##0.00_);[Red](#,##0.00)
$1B	_(* #,##0_);_(* (#,##0);_(* "-"_);_(@_)
$1C	_($* #,##0_);_($* (#,##0);_($* "-"_);_(@_)
$1D	_(* #,##0.00_);_(* (#,##0.00);_(* "-"??_);_(@_)
$1E	_($* #,##0.00_);_($* (#,##0.00);_($* "-"??_);_(@_)
$1F	mm:ss
$20	[h]:mm:ss
$21	mm:ss.0
$22	# #0.0E+0
$23	text


TcxSSCellStyle.HorzTextAlign

TcxSSCellStyle           See also

Specifies the horizontal alignment of cell contents.

property HorzTextAlign: TcxHorzTextAlign;

Description

Horizontal alignment is defined by values of the TcxHorzTextAlign enumerator. The following refers to displayed text which is too wide for cell width.

If the WordBreak property is set to True, text wraps and it is displayed across several lines of a cell.  Otherwise text can span several cells but only if neighboring ones are empty.  If neighboring cells are not empty, text is truncated within a cell.

The following image demonstrates two cells with wide text.  The WordBreak property is set to False.  The text in cell A1 is displayed truncated since the neighboring B1 cell is not empty.  But the text of cell B1 is displayed fully because cell C1 contains nothing.

The image below describes the same cells with the WordBreak property set to True.

The following sample code sets the bottom-right alignment of text within cell A1.

// Delphi

var

  ACell: TcxSSCellObject;

//...

ACell := cxSpreadSheetBook1.ActiveSheet.GetCellObject(0, 0);

try

  ACell.Text := 'Bottom-right aligned text';

  ACell.Style.HorzTextAlign := haRIGHT;

  ACell.Style.VertTextAlign := vaBOTTOM;

finally

  ACell.Free;

end;

// C++ Builder

TcxSSCellObject *cell;

cell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(0, 0);

try {

  cell->Text = "Bottom-right aligned text";

  cell->Style->HorzTextAlign = haRIGHT;

  cell->Style->VertTextAlign = vaBOTTOM;

}

__finally {

  delete cell;

}


TcxSSCellStyle.IsMain

TcxSSCellStyle          See Also

Gets a value indicating whether the cell is the main cell within the merged set.

property IsMain: Boolean;

Description

When several cells are merged, the area they occupy represents a single cell.  This cell will contain data of one of the cell within the merged cells set.  You can also split merged cells.  Use the IsMain property to determine whether the cell is main cell.

Cells can be merged and split via the SetMergedState method of a TcxSSBookSheet object.

ReadOnly Property


TcxSSCellStyle.IsMerge

TcxSSCellStyle          See Also

Specifies whether a cell belongs to a merged set.

property IsMerge: Boolean;

Description

You can use the IsMerge property to determine whether a cell belongs to a merged set.  Cells can be merged via the SetMergedState method of a TcxSSBookSheet object.  When several cells are merged, the area they occupy represents a single cell.  The top left cell of a merged set is the main cell.  The merged cell displays the data of the main cell.  See the IsMain property to define whether the cell is the main one.

ReadOnly Property


TcxSSCellStyle.Locked

TcxSSCellStyle

Prevents changes to the current cell.

property Locked: Boolean;

Description

Prevents changes to the current cell.

The default value of the Locked property is True.


TcxSSCellStyle.Row

TcxSSCellStyle          See Also

Gets the zero-based index of the row to which a cell belongs.

property Row: Integer;

Description

Use this property to get the zero-based index of the row to which a cell belongs.  The index of the column containing the cell can be obtained via the Col property.

ReadOnly Property


TcxSSCellStyle.ReadOnly

TcxSSCellStyle          See Also

Specifies whether cell style and contents can be modified.

property ReadOnly: Boolean;

Description

Set this property to True to prevent cell style and content from modification.  When the ReadOnly property is True, a user cannot change the cell style and contents.

The following code sets the read-only status of the active cell to True:

//Delphi

var Sheet: TcxSSBookSheet;

//...

Sheet := cxSpreadSheetBook1.ActiveSheet;

with Sheet.GetCellObject(Sheet.Col, Sheet.Row) do

try

  Style.ReadOnly := True;

finally

  Free;

end;

//C++ Builder

TcxSSBookSheet * sheet = cxSpreadSheetBook1->ActiveSheet;

TcxSSCellObject * cell = sheet->GetCellObject(sheet->Col, sheet->Row);

try {

  cell->Style->ReadOnly = true;

}

__finally {

  delete cell;

}

You can set the read-only status for an individual worksheet, or all worksheets within a spreadsheet control via the worksheet’s ReadOnly property, or the spreadsheet control’s ReadOnly property, respectively.

Note:	The ReadOnly properties are in effect only if the spreadsheet control’s ExcelProtectionStyle property is set to False.


TcxSSCellStyle.VertTextAlign

TcxSSCellStyle           See also

Specifies the vertical alignment of cell contents.

property VertTextAlign: TcxVertTextAlign;

Description

The vertical alignment of cell contents is determined by values of the TcxVertTextAlign enumerator. The following sample code sets the bottom-right alignment of the text within cell A1.

// Delphi

var

  ACell: TcxSSCellObject;

//...

ACell := cxSpreadSheetBook1.ActiveSheet.GetCellObject(0, 0);

try

  ACell.Text := 'Bottom-right aligned text';

  ACell.Style.HorzTextAlign := haRIGHT;

  ACell.Style.VertTextAlign := vaBOTTOM;

finally

  ACell.Free;

end;

// C++ Builder

TcxSSCellObject *cell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(0, 0);

try {

  cell->Text = "Bottom-right aligned text";

  cell->Style->HorzTextAlign = haRIGHT;

  cell->Style->VertTextAlign = vaBOTTOM;

}

__finally {

  delete cell;

}


TcxSSCellStyle.WordBreak

TcxSSCellStyle           See also

Determines whether cell text wraps when it is too long for the width of the cell.

property WordBreak: Boolean;

Description

Set this property to True to enable text wrapping when it is too long for the width of the cell.  If the WordBreak property is set to False, text is displayed in a single line.  The manner in which text is displayed is defined by the HorzTextAlign property.  Text wraps only if the HorzTextAlign property is not set to haJUSTIFY.

The following image demonstrates two cells with the WordBreak property set to True.


TcxSSCellStyle.Assign

TcxSSCellStyle          See Also

Assigns the contents of one class instance to another.

procedure Assign(Source: TcxSSCellStyle); virtual;

Description

Use this method to assign property values of an existing TcxSSCellStyle class instance to another.  This allows you to set the same predefined style to several cells.  Create an instance of the TcxSSCellStyle class, adjust its properties and assign it to the desired cells.

The following sample code sets the font style and alignment of cell A1 and assigns its style to cell range B1:D1.

// Delphi

var

  ACell: TcxSSCellObject;

  ACellStyle: TcxSSCellStyle;

  i: Integer;

//...

ACell := cxSpreadSheetBook1.ActiveSheet.GetCellObject(0, 0);

try

  ACell.Text := 'Cell 0:0';

  ACell.Style.Font.Style := [fsBold, fsUnderline];

  ACell.Style.HorzTextAlign := haCENTER;

  ACell.Style.VertTextAlign := vaCENTER;

  ACellStyle := ACell.Style;

finally

  ACell.Free;

end;

for i := 1 to 3 do

begin

  ACell := cxSpreadSheetBook1.ActiveSheet.GetCellObject(i, 0);

  try

    ACell.Text := 'Cell ' + IntToStr(i) + ':0';

    ACell.Style.Assign(ACellStyle);

  finally

    ACell.Free;

  end;

end;

// C++ Builder

TcxSSCellObject *cell;

TcxSSCellStyle *cellStyle;

cell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(0, 0);

try {

  cell->Text = "Cell 0:0";

  cell->Style->Font->Style = TFontStyles() << fsBold << fsUnderline;

  cell->Style->HorzTextAlign = haCENTER;

  cell->Style->VertTextAlign = vaCENTER;

  cellStyle = cell->Style;

}

__finally {

  delete cell;

}

for (int i = 1; i < 4; i++) {

  cell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(i, 0);

  try {

    cell->Text = "Cell " + IntToStr(i) + ":0";

    cell->Style->Assign(cellStyle);

  }

  __finally {

    delete cell;

  }

}


TcxSSCellStyle.Create

TcxSSCellStyle

Initializes a new TcxSSCellStyle class instance.

procedure Create(AParent: TcxSSStyleCache; AOwner: TObject; ACol, ARow: Integer); virtual;

Description

This constructor creates a new instance of the TcxSSCellStyle class corresponding to a specified cell.  The AParent parameter specifies the TcxSSStyleCache class instance that represents the collection of styles applied to the ExpressSpreadSheet.  The AOwner parameter specifies the owner of the generated TcxSSCellStyle instance.  The coordinates of the cell to which the generated TcxSSCellStyle class instance corresponds are specified by the ACol and ARow parameters.


TcxSSCellStyle.Destroy

TcxSSCellStyle

Destroys a TcxSSCellStyle class instance.

procedure Destroy; override;

Description

Use this method to destroy an instance of the TcxSSCellStyle class.  It frees all resources that it occupied.


TcxSSEdgeStyle
TcxSSEdgeStyle Object

Hierarchy          Properties          Methods

Represents cell edge style.

Unit

cxSSStyles

TcxSSEdgeStyle = class(TcxSSStyle)

Description

This object represents cell edge style.  It is referenced by the Left, Right, Top, Bottom and Edges properties of the TcxSSBorderStyle object.  These properties are used to set styles for corresponding cell edges.  Cell edge style is specified by line style and color.  The Style and Color properties are used to set these parameters.


TcxSSEdgeStyle Hierarchy
Hierarchy

TObject

     |

TcxSSStyle


Properties for TcxSSEdgeStyle
TcxSSEdgeStyle Properties

TcxSSEdgeStyle          Legend

In TcxSSEdgeStyle

Color

Kind

Style

Derived from TcxSSStyle

LockUpdate


Methods for TcxSSEdgeStyle
TcxSSEdgeStyle Methods

TcxSSEdgeStyle          Legend

In TcxSSEdgeStyle

AssignInfo

AssignRec


TcxSSEdgeStyle.Color

TcxSSEdgeStyle          See Also

Specifies the color of a cell edge.

property Color: Word;

Description

Use this property to set the color of a cell edge.  This property is not in effect if the Style property of the TcxSSEdgeStyle object is lsNone or lsDefault.  When the Style property is set to lsDefault, the color of a cell edge is defined by the GridColor property.

The color is defined by an index in the ExpressSpreadSheet color palette. The color palette is supported by the Palette property of the TcxSpreadSheetBook and TcxSpreadSheet classes.

The following sample code sets edge color of cell B2 to red.

// Delphi

var

  ACell: TcxSSCellObject;

  AEdgeStyle: TcxSSEdgeStyle;

  i: TcxSSEdgeBorder;

//...

ACell := cxSpreadSheetBook1.ActiveSheet.GetCellObject(1, 1);

try

  for i := eLeft to eBottom do

  begin

    AEdgeStyle := ACell.Style.Borders.Edges[i];

    AEdgeStyle.Style := lsThin;

    AEdgeStyle.Color := 2; //clRed

  end;

finally

  ACell.Free;

end;

// C++ Builder

TcxSSCellObject *cell;

TcxSSEdgeStyle *edgeStyle;

TcxSSEdgeBorder i;

cell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(1, 1);

try {

  for (i = eLeft; i <= eBottom; i = i + 1) {

    edgeStyle = cell->Style->Borders->Edges[i];

    edgeStyle->Style = lsThin;

    edgeStyle->Color = 2; //clRed

  }

}

__finally {

  delete cell;

}


TcxSSEdgeStyle.Kind

TcxSSEdgeStyle          See Also

Gets a value specifying cell edge kind.

property Kind: TcxSSEdgeBorder;

Description

Use this property to determine whether a TcxSSEdgeStyle class instance corresponds to the left, top, right or bottom cell edge.

ReadOnly Property


TcxSSEdgeStyle.Style

TcxSSEdgeStyle          See Also

Specifies the line style of a cell edge.

property Style: TcxSSEdgeLineStyle;

Description

Use this property to specify the line style of a cell edge.  There are 14 line styles provided by the ExpressSpreadSheet.  lsNone is used internally.  It is needed to display merged cells and hide edges when cell contents exceed their size.  When exported to MS Excel, lsNone is converted to lsDefault.

The color of a cell edge is specified by the Color property of the TcxSSEdgeStyle object.X

The following sample code demonstrates possible edge line styles.

// Delphi

var

  ACell: TcxSSCellObject;

  AEdgeStyle: TcxSSEdgeStyle;

  i: Integer;

  ALineStyle: TcxSSEdgeLineStyle;

//...

i := 0;

for ALineStyle := lsDefault to lsNone do

begin

    ACell := cxSpreadSheetBook1.ActiveSheet.GetCellObject(i, 0);

  try

    AEdgeStyle := ACell.Style.Borders.Right;

    AEdgeStyle.Style := ALineStyle;

    AEdgeStyle.Color := 0; //clBlack

    AEdgeStyle.AssignInfo(ALineStyle, 0);

    i := i + 1;

  finally

    ACell.Free;

  end;

end;

// C++ Builder

TcxSSCellObject *cell;

TcxSSEdgeStyle *edgeStyle;

int i = 0;

TcxSSEdgeLineStyle lineStyle;

for (lineStyle = lsDefault; lineStyle <= lsNone; lineStyle = lineStyle + 1) {

  cell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(i++, 0);

  try {

    edgeStyle = cell->Style->Borders->Right;

    edgeStyle->Style = lineStyle;

    edgeStyle->Color = 0; //clBlack

    edgeStyle->AssignInfo(lineStyle, 0);

  }

  __finally {

    delete cell;

  }

}


TcxSSEdgeStyle.AssignInfo

TcxSSEdgeStyle          See Also

Initializes the properties of a TcxSSEdgeStyle object with parameter values.

procedure AssignInfo(AStyle: TcxSSEdgeLineStyle; AColor: Word); virtual;

Description

Use the AssignInfo method to initialize Style and Color property values of the current TcxSSEdgeStyle class instance.  This allows you to set the same predefined style to several cell edges.  You can also use the AssignRec method to initialize the properties of a TcxSSEdgeStyle object.

The following sample code demonstrates the use of the AssignRec and AssignInfo methods:

// Delphi

var

  ACell: TcxSSCellObject;

  AEdgeStyle: TcxSSEdgeStyle;

  AEdgeStyleRec: TcxSSEdgeStyleRec;

//...

ACell := cxSpreadSheetBook1.ActiveSheet.GetCellObject(1, 1);

try

  AEdgeStyle := ACell.Style.Borders.Top;

  AEdgeStyleRec.Style := lsDouble;

  AEdgeStyleRec.Color := 4; //clBlue

  AEdgeStyle.AssignRec(AEdgeStyleRec);

  AEdgeStyle := ACell.Style.Borders.Bottom;

  AEdgeStyle.AssignInfo(lsThick, 2); //clRed

finally

  ACell.Free;

end;

// C++ Builder

TcxSSCellObject *cell;

TcxSSEdgeStyle *edgeStyle;

TcxSSEdgeStyleRec edgeStyleRec;

cell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(1, 1);

try {

  edgeStyle = cell->Style->Borders->Top;

  edgeStyleRec.Style = lsDouble;

  edgeStyleRec.Color = 4; //clBlue

  edgeStyle->AssignRec(edgeStyleRec);

  edgeStyle = cell->Style->Borders->Bottom;

  edgeStyle->AssignInfo(lsThick, 2); //clRed

}

__finally {

  delete cell;

}


TcxSSEdgeStyle.AssignRec

TcxSSEdgeStyle          See Also

Initializes the properties of a TcxSSEdgeStyle object with the specified record fields.

procedure AssignRec(AData: TcxSSEdgeStyleRec); virtual;

Description

Use the AssignRec method to initialize the Style and Color properties of the current TcxSSEdgeStyle class instance with values from the AData record.  The TcxSSEdgeStyleRec type declares two fields representing the color and the edge style values to be set.

This allows you to assign the same predefined style to several cell edges.  You can also use the AssignInfo method to initialize the properties of a TcxSSEdgeStyle object.

The following sample code demonstrates the use of the AssignRec and AssignInfo methods:

// Delphi

var

  ACell: TcxSSCellObject;

  AEdgeStyle: TcxSSEdgeStyle;

  AEdgeStyleRec: TcxSSEdgeStyleRec;

//...

ACell := cxSpreadSheetBook1.ActiveSheet.GetCellObject(1, 1);

try

  AEdgeStyle := ACell.Style.Borders.Top;

  AEdgeStyleRec.Style := lsDouble;

  AEdgeStyleRec.Color := 4; //clBlue

  AEdgeStyle.AssignRec(AEdgeStyleRec);

  AEdgeStyle := ACell.Style.Borders.Bottom;

  AEdgeStyle.AssignInfo(lsThick, 2); //clRed

finally

  ACell.Free;

end;

// C++ Builder

TcxSSCellObject *cell;

TcxSSEdgeStyle *edgeStyle;

TcxSSEdgeStyleRec edgeStyleRec;

cell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(1, 1);

try {

  edgeStyle = cell->Style->Borders->Top;

  edgeStyleRec.Style = lsDouble;

  edgeStyleRec.Color = 4; //clBlue

  edgeStyle->AssignRec(edgeStyleRec);

  edgeStyle = cell->Style->Borders->Bottom;

  edgeStyle->AssignInfo(lsThick, 2); //clRed

}

__finally {

  delete cell;

}


TcxSSFont
TcxSSFont Object

Hierarchy          Properties          Methods

Represents the font used to display a cell value.

Unit

cxSSStyles

TcxSSFont = class(TcxSSStyle)

Description

The ExpressSpreadSheet control allows you to customize the font used to display a cell’s value.  Properties of the TcxSSFont object are used for this purpose.  This object is referenced by the Font property of the TcxSSCellStyle class.


TcxSSFont Hierarchy
Hierarchy

TObject

     |

TcxSSStyle


Properties for TcxSSFont
TcxSSFont Properties

TcxSSFont          Legend

In TcxSSFont

Charset

FontColor

Name

Size

Style

Derived from TcxSSStyle

LockUpdate


Methods for TcxSSFont
TcxSSFont Methods

TcxSSFont          Legend

In TcxSSFont

AssignInfo


TcxSSFont.Charset

TcxSSFont          See Also

Specifies the character set of the font.

property Charset: TFontCharset;

Description

Each typeface supports one or more character sets, which indicate which characters can be written using the font.  For example, most fonts that can represent Japanese characters use a particular multi-byte character set.  The Charset property specifies the character set used to represent a cell’s value.

Note: Each font supports its own, unique set of character sets. Check with the font vendor to determine which character sets are supported.


TcxSSFont.FontColor

TcxSSFont           See also

Specifies font color.

property FontColor: Word;

Description

The font color is defined by the index in the ExpressSpreadSheet color palette. The color palette is supported by the Palette property of TcxSpreadSheetBook and TcxSpreadSheet classes.

The following image describes the default palette:

// Delphi

var ACell: TcxSSCellObject;

//...

ACell := cxSpreadSheetBook1.ActiveSheet.GetCellObject(0, 0);

try

  ACell.Text := 'Blue text';

  ACell.Style.Font.FontColor := 4;

finally

  ACell.Free;

end;

// C++ Builder

TcxSSCellObject *cell;

cell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(0, 0);

try {

  cell->Text = "Blue text";

  cell->Style->Font->FontColor = 4;

}

__finally {

  delete cell;

}


TcxSSFont.Name

TcxSSFont          See Also

Specifies the typeface of the font used to display a cell’s value.

property Name: string;

Description

Use the Name property to specify font typeface. If the font family described by this property includes multiple character sets, be sure to set the Charset property as well.

Note: If a specified typeface is not available on your system, a substitute is used.

The following sample code demonstrates how to use the Name property.

// Delphi

var

  ACell: TcxSSCellObject;

  AFont: TcxSSFont;

  i: Integer;

const

  AFontNames: array [0..3] of string = ('Impact',

     'Courier New','Comic Sans MS', 'Bookman Old Style');

//...

for i := 0 to 3 do

begin

  ACell := cxSpreadSheetBook1.ActiveSheet.GetCellObject(0, i);

  try

    ACell.Text := AFontNames[i];

    AFont := ACell.Style.Font;

    AFont.Name := AFontNames[i];

    AFont.Size := 12;

  finally

    ACell.Free;

  end;

end;

// C++ Builder

TcxSSCellObject *cell;

TcxSSFont *font;

int i;

String fontNames[] = {"Impact", "Courier New",

   "Comic Sans MS", "Bookman Old Style"};

for (i = 0; i < 4; i++) {

  cell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(0, i);

  try {

    cell->Text = fontNames[i];

    font = cell->Style->Font;

    font->Name = fontNames[i];

    font->Size = 12;

  }

  __finally {

    delete cell;

  }

}


TcxSSFont.Size

TcxSSFont          See Also

Specifies the font size used to display a cell’s value.

property Size: Integer;

Description

Use the Size to specify the point size of the font.

The following sample code applies incrementing sizes to cell range A1:A5.

// Delphi

var

  ACell: TcxSSCellObject;

  AFont: TcxSSFont;

  i, ASize: Integer;

//...

for i := 0 to 4 do

begin

  ACell := cxSpreadSheetBook1.ActiveSheet.GetCellObject(0, i);

  try

    ASize := (i + 2) * 5;

    ACell.Text := 'Font size = ' + IntToStr(ASize);

    AFont := ACell.Style.Font;

    AFont.Size := ASize;

  finally

    ACell.Free;

  end;

end;

// C++ Builder

TcxSSCellObject *cell;

TcxSSFont *font;

int i, size;

for (i = 0; i < 5; i++) {

  cell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(0, i);

  try {

    size = (i + 2) * 5;

    cell->Text = "Font size = " + IntToStr(size);

    font = cell->Style->Font;

    font->Size = size;

  }

  __finally {

    delete cell;

  }

}


TcxSSFont.Style

TcxSSFont          See Also

Used to apply bold, italic, underline and strikeout font styles.

property Style: TFontStyles;

Description

The following sample code demonstrates different font styles.

// Delphi

var

  ACell: TcxSSCellObject;

  AFont: TcxSSFont;

  i: Integer;

const

  AFontStylesArr: array [0..4] of TFontStyles = ([], [fsBold], [fsItalic],

     [fsBold, fsUnderline], [fsBold, fsItalic, fsStrikeOut]);

  AFontStylesStrs: array [0..4] of string = ('Empty set', '[fsBold]',

     '[fsItalic]', '[fsBold, fsUnderline]', '[fsBold, fsItalic, fsStrikeOut]');

//...

for i := 0 to 4 do

begin

  ACell := cxSpreadSheetBook1.ActiveSheet.GetCellObject(0, i);

  try

    ACell.Text := AFontStylesStrs[i];

    AFont := ACell.Style.Font;

    AFont.Style := AFontStylesArr[i];

  finally

    ACell.Free;

  end;

end;

// C++ Builder

TcxSSCellObject *cell;

TcxSSFont *font;

int i;

TFontStyles fontStylesArr[] = {

   TFontStyles(), TFontStyles() << fsBold, TFontStyles() << fsItalic,

   TFontStyles() << fsBold << fsUnderline,

   TFontStyles() << fsBold << fsItalic << fsStrikeOut};

String fontStylesStrs[] = {"Empty set", "[fsBold]",

     "[fsItalic]", "[fsBold, fsUnderline]", "[fsBold, fsItalic, fsStrikeOut]"};

for (i = 0; i < 5; i++) {

  cell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(0, i);

  try {

    cell->Text = fontStylesStrs[i];

    font = cell->Style->Font;

    font->Style = fontStylesArr[i];

  }

  __finally {

    delete cell;

  }

}


TcxSSFont.AssignInfo

TcxSSFont          See Also

Assigns parameter values to TcxSSFont object properties.

procedure AssignInfo(AName: string; ASize: Integer; AStyle: TFontStyles; ACharset: TFontCharset; AFontColor: Word); virtual;

Description

Use this method to initialize property values for the TcxSSFont object with the values of the method parameters.

The AName parameter sets the Name property value.

The ASize parameter sets the Size property value.

The AStyle parameter sets the Style property value.

The ACharset parameter sets the Charset property value.

The AFontColor parameter sets the FontColor property value.

The following sample code formats the font of cell B2.

// Delphi

var

  ACell: TcxSSCellObject;

  AFont: TcxSSFont;

//...

ACell := cxSpreadSheetBook1.ActiveSheet.GetCellObject(0, 0);

try

  ACell.Text := 'ExpressSpreadSheet';

  AFont := ACell.Style.Font;

  AFont.AssignInfo('Comic Sans MS', 12, [fsBold, fsUnderline], DEFAULT_CHARSET, 0);

finally

  ACell.Free;

end;

// C++ Builder

TcxSSCellObject *cell;

TcxSSFont *font;

cell = cxSpreadSheetBook1->ActiveSheet->GetCellObject(0, 0);

try {

  cell->Text = "ExpressSpreadSheet";

  font = cell->Style->Font;

  font->AssignInfo("Comic Sans MS", 12, TFontStyles() << fsBold << fsUnderline, DEFAULT_CHARSET, 0);

}

__finally {

  delete cell;

}


TcxSSStyle
TcxSSStyle Object

Hierarchy          Properties          Methods

Serves as a base for object manipulation styles.

Unit

cxSSStyles

TcxSSStyle = class(TObject)

Description

This object provides a base for all class manipulation styles.  These objects are TcxSSBorderStyle, TcxSSEdgeStyle, TcxSSBrush and TcxSSFont.  The TcxSSStyle class contains a LockUpdate property.


TcxSSStyle Hierarchy
Hierarchy

TObject


Properties for TcxSSStyle
TcxSSStyle Properties

TcxSSStyle          Legend

In TcxSSStyle

LockUpdate


Methods for TcxSSStyle
TcxSSStyle Methods

TcxSSStyle          Legend

In TcxSSStyle

Create

Destroy


TcxSSStyle.LockUpdate

TcxSSStyle

Specifies whether a style can be updated.

property LockUpdate: Boolean;

Description

Set this property to True to prohibit style updates.  Once done, changes to property values are not in effect.  Set the LockUpdate property to False to allow style updates.  Styles are updateable by default.


TcxSSStyle.Create

TcxSSStyle

Initializes a new instance of the TcxSSStyle class.

procedure Create(AOwner: TcxSSCellStyle); virtual;

Description

Do not create instances of the TcxSSStyle class directly.  Create instances of its descendants instead.  Its descendants are TcxSSBorderStyle, TcxSSEdgeStyle, TcxSSBrush and TcxSSFont.


TcxSSStyle.Destroy

TcxSSStyle

Destroys a TcxSSStyle class instance.

procedure Destroy; override;

Description

Use this method to destroy an instance of the TcxSSStyle class.  It frees all resources that it occupied.


cxSSHistory Unit Overview
cxSSHistory Unit

Classes

TcxActionList

TcxCustomAction

TcxCustomHistory

TcxSpreadSheetHistory

Global Constants

MaximumActionsCount


TcxActionList
TcxActionList Object

Hierarchy          Properties          See Also

Contains a list of actions available for undo or redo.

Unit

cxSSHistory

TcxActionList = class(TcxCustomAction);

Description

The TcxActionList class represents the list of actions which you can undo or redo.  The TcxCustomHistory object has two lists for the TcxActionList class which store ‘undo’ and ‘redo’ actions respectively (via protected RedoActions and UndoActions properties).  The Count member defines the number of actions in the list.  The Item property allows you to iterate through all actions of the TcxCustomAction class.


TcxActionList Hierarchy
Hierarchy

TObject

     |

TcxCustomAction

     |


Properties for TcxActionList
TcxActionList Properties

TcxActionList          Legend

In TcxActionList

Count

Item

Derived from TcxCustomAction

Description


TcxActionList.Count

TcxActionList          See Also

Specifies the number of actions in the current list.

property Count: Integer;

Description

Use the Count property to determine the number of actions in the current list.  Properties of a specific action are accessible via the indexed Item property.

ReadOnly Property


TcxActionList.Item

TcxActionList          See Also

Returns a specific action by its index in the current list.

property Item[AIndex:Integer]: TcxCustomAction;

Description

The Item property allows you to get a reference to an action at the specified position within the TcxActionList list.  The Count property defines the number of actions.

ReadOnly Property


TcxCustomAction
TcxCustomAction Object

Hierarchy          Properties          See Also

Represents an abstract action in the history list.

Unit

cxSSHistory

TcxCustomAction = class(TObject);

Description

The TcxCustomAction class represents the action which you can undo and redo.  Actions are stored in a list of the TcxActionList class.  There are two types of action: single and complex.  Complex actions (such as deleting multiple cells) include several single actions.  When you undo a complex action, you perform the undo operation for all its constituent actions.

You can get the description of an action by reading the Description property.


TcxCustomAction Hierarchy
Hierarchy

TObject

     |


Properties for TcxCustomAction
TcxCustomAction Properties

TcxCustomAction          Legend

In TcxCustomAction

Description


TcxCustomAction.Description

TcxCustomAction          See Also

Gets the text representation for the current action.

property Description: string;

Description

Use the Description property to get the text representation of the current action.  Default action names are declared in the cxSSRes.pas unit.  When recording actions via the TcxCustomHistory.StartComplexAction method, you pass the description as a parameter to this method.

ReadOnly Property


TcxCustomHistory
TcxCustomHistory Object

Hierarchy          Properties          Methods          See Also

Provides the base class encapsulating the history functionality for a spreadsheet control.

Unit

cxSSHistory

TcxCustomHistory = class(TObject);

Description

A spreadsheet control stores the history of actions which a user has performed on spreadsheet cells.  TcxCustomHistory encapsulates the history of performed actions.  It allows the recording of user actions and the changes performed programmatically.  You can undo actions and also redo actions previously undone.

The TcxCustomHistory class stores two lists with the actions which you can undo and redo.  The maximum number of actions is determined by the MaxActions property.  To record cell changes programmatically use the StartComplexAction and StopComplexAction methods.  These methods allow the recording of several actions presented as a single complex action.  When the Undo method is called, the spreadsheet control undoes all actions represented by a complex action.  The Redo method can repeat the complex action previously undone.


TcxCustomHistory Hierarchy
Hierarchy

TObject

     |


Properties for TcxCustomHistory
TcxCustomHistory Properties

TcxCustomHistory          Legend

In TcxCustomHistory

MaxActions

RedoActions

UndoActions


Methods for TcxCustomHistory
TcxCustomHistory Methods

TcxCustomHistory          Legend

In TcxCustomHistory

 Clear

 Redo

 StartComplexAction

 StopComplexAction

 Undo


TcxCustomHistory.MaxActions

TcxCustomHistory          See Also

Specifies the maximum number of actions which can be undone.

property MaxActions: Integer;

Description

Use the MaxActions property to determine the maximum number of actions stored in the UndoActions list.  It determines the number of actions which can be undone.  The default value for this property is defined by the MaximumActionsCount global constant.


TcxCustomHistory.RedoActions

TcxCustomHistory          See Also

Returns the list of ‘redo’ actions in the current history object.

property RedoActions: TcxActionList;

Description

Use the RedoActions property to gain access to the actions which you can redo.  When some actions are undone they are automatically moved from the UndoActions list to the RedoActions list.  After a user performs any action other than ‘undo’ or ‘redo’, the ‘redo’ list is cleared.

ReadOnly Property


TcxCustomHistory.UndoActions

TcxCustomHistory          See Also

Returns the list of ‘undo’ actions in the current history object.

property UndoActions: TcxActionList;

Description

Use the UndoActions property to gain access to the actions which you can undo.  When actions are undone, they are automatically moved from the UndoActions list to the RedoActions list.  After a user performs any action other than ‘undo’ or ‘redo’, the ‘redo’ list is cleared.

ReadOnly Property


TcxCustomHistory.Clear

TcxCustomHistory          See Also

Deletes the history of actions from the ‘undo’ and ‘redo’ lists.

procedure Clear;

Description

Use the Clear method to remove all actions from the ‘undo’ and ‘redo’ lists.  These lists are supported by the UndoActions and RedoActions properties.


TcxCustomHistory.Redo

TcxCustomHistory          See Also

Redoes the last undone actions.

procedure Redo(const ACount: Integer = -1); dynamic;

Description

Use the Redo method to redo the actions, which were undone.  The ACount parameter defines the number of actions to redo.  The default value for this parameter is –1, this means that there are no any actions to redo.  To undo an action call the Undo method.


TcxCustomHistory.StartComplexAction

TcxCustomHistory          See Also

Starts recording a complex action.

function StartComplexAction(const ADescription: string): Boolean;

Description

The StartComplexAction method allows you to record subsequent actions and present them as a single complex action in the ‘undo’ list.  A complex action gets the name defined by the ADescription parameter.  Call the StopComplexAction method to finish recording.  All operations performed between the StartComplexAction and StopComplexAction methods, constitute a single complex action.  If the latest action is complex, calling the Undo method undoes all actions held within the complex action consists.

The StartComplexAction function returns True if recording starts successfully, otherwise, it returns False.

The following code demonstrates how to create a complex action consisting of setting the background color of two cells and then merging them.  The new complex action is given the name ‘Merging green cells’.

//Delphi

if  cxSpreadSheet1.History.StartComplexAction('Merging green cells') then

try

  with cxSpreadSheet1.Sheet.GetCellObject(0,0) do

    try

      Style.Brush.BackgroundColor := 3;

      Text := 'Cell A1'

    finally

      Free;

    end;

  with cxSpreadSheet1.Sheet.GetCellObject(0,1) do

    try

      Style.Brush.BackgroundColor := 3;

    finally

      Free;

    end;

  cxSpreadSheet1.Sheet.SetMergedState(Rect(0,0,0,1), True);

finally

  cxSpreadSheet1.History.StopComplexAction;

end;

//C++ Builder

  TcxSSCellObject* cell;

  cxSpreadSheet1->History->StartComplexAction("Merging green cells");

  cell = cxSpreadSheet1->Sheet->GetCellObject(0,0);

  try {

    cell->Style->Brush->BackgroundColor = 3;

    cell->Text = "Cell A1";

  }

  __finally {

    delete cell;

  }

  cell = cxSpreadSheet1->Sheet->GetCellObject(0,1);

  try {

    cell->Style->Brush->BackgroundColor = 3;

  }

  __finally {

    delete cell;

  }

  cxSpreadSheet1->Sheet->SetMergedState(Rect(0,0,0,1), True);

  cxSpreadSheet1->History->StopComplexAction();


TcxCustomHistory.StopComplexAction

TcxCustomHistory          See Also

Stops recording a complex action.

procedure StopComplexAction;

Description

The StopComplexAction method finishes recording a complex action started by the StartComplexAction function.  All actions performed after StartComplexAction and before the StopComplexAction method are represented as a single complex action.  You can undo/redo a complex action by making one call to the Undo or Redo method.


TcxCustomHistory.Undo

TcxCustomHistory          See Also

Undoes last actions.

procedure Undo(const ACount: Integer = -1); dynamic;

Description

Use the Undo method to undo the latest action(s).  The ACount parameter defines the number of actions to undo.  The default value for this parameter is –1, this means that all actions are undone.  If this parameter equals to 0 nothing happens.  To redo operations previously, undone call the Redo method.


TcxSpreadSheetHistory
TcxSpreadSheetHistory Object

Hierarchy          Properties          Methods          See Also

Implements the history functionality for a spreadsheet control.

Unit

cxSSHistory

TcxSpreadSheetHistory = class(TcxCustomHistory);

Description

Spreadsheet controls store the history of actions a user performed on spreadsheet cells.  TcxSpreadSheetHistory does not introduce any new behavior but publishes the necessary properties and events inherited from the TcxCustomHistory class.  When a user edits, formats or clears cells, a spreadsheet records these actions in a TcxCustomSpreadSheetBook.History object.  Later you can undo these actions and redo actions which were undone.  The capacity of the list which stores the ‘undo’ actions is determined by the MaxActions property.  You can use the UndoActions and RedoActions properties to access the corresponding action lists.

To record cell changes programmatically use the StartComplexAction and StopComplexAction methods.  These methods allow the recording of several actions to present them as a single complex action.  When the Undo method is called a spreadsheet undoes all actions relating to a complex action.  The Redo method can repeat the complex action previously undone.

At runtime it is possible to undo the last action by pressing the Ctrl+Z shortcut.  The Ctrl-Y shortcut allows you to redo undone actions.

Spreadsheet controls enable you to undo and redo the following operations: formatting, inserting, deleting, clearing cells, changing cell contents, merging/splitting cells and sorting cells.


TcxSpreadSheetHistory Hierarchy
Hierarchy

TObject

     |

TcxCustomHistory

     |


Properties for TcxSpreadSheetHistory
TcxSpreadSheetHistory Properties

TcxSpreadSheetHistory          Legend

Derived from TcxCustomHistory

MaxActions

RedoActions

UndoActions


Methods for TcxSpreadSheetHistory
TcxSpreadSheetHistory Methods

TcxSpreadSheetHistory          Legend

Derived from TcxCustomHistory

 Clear

 Redo

 StartComplexAction

 StopComplexAction

 Undo


MaximumActionsCount constant
MaximumActionsCount global constant

Specifies the default value of the TcxCustomHistory.MaxActions property.

Unit

cxSSHistory

MaximumActionsCount : Integer = 15;

Description

The MaximumActionsCount constant defines the default value of the TcxCustomHistory.MaxActions property specifying the maximum number of actions which can be undone.


TcxCustomSpreadSheetBook.DefineName

TcxCustomSpreadSheetBook          See Also

Defines a valid name for a cell or a group of cells.

function DefineName(const AName: string; APage: Word; const ARect: TRect); Integer; virtual;

Description

Calling this function is the same as calling the DefineNameEx function with True passed as the Validate parameter.

The following code demonstrates how to use the defined names.

//Delphi

  //Giving a name to a cell group with bounds 0,0;0,9.

  cxSpreadSheet1.DefineName('sumrect', 0, Rect(0, 0, 0, 9));

  //Implementing a formula into a cell with coordinates 0,10. Formula calculates the sum of the cell values by the defined name.

  cxSpreadSheet1.Sheet.GetCellObject(0, 10).Text := '=SUM(sumrect)';

  cxSpreadSheet1.UpdateControl;

//C++Builder

  //Giving a name to a cell with coordinates bounds 0,0;0,9.

  cxSpreadSheet1->DefineName("sumrect", 0, Rect(0, 0, 0, 9));

  //Implementing a formula into a cell with coordinates 0,10. Formula calculates the sum of the cell values by the defined name.

  cxSpreadSheet1->Sheet->GetCellObject(0, 10)->Text = "=SUM(sumrect)";

  cxSpreadSheet1->UpdateControl();


TcxCustomSpreadSheetBook.DefineNameEx

TcxCustomSpreadSheetBook          See Also

Defines a name for a cell or a group of cells and validates the name.

function DefineNameEx(const AName: string; APage: Word; const ARect: TRect, Validate: Boolean = True); Integer; virtual;

Description

You can use the defined name in formulas.

The AName parameter specifies the name of a cell or a group of cells.

The APage parameter determines the page where the cell or the group of cells is located.

The ARect parameter defines the cell or the group of cells to name.

The name is valid if none of the following is true:

•	It contains spaces and the following symbols: (&)@#%^+-*/\|,.;{}[]''"?.

•	It matches a sheet name.

•	The DefinedNames collection already contains the same name.

If validation fails for a certain name, this name is not added to the DefinedNames collection, and cannot be used.  If validation succeeds, the DefineNameEx function returns the position of the defined name in this collection.  To suppress name validation, pass False as the Validate parameter.

Calling the DefineName function is the same as calling the DefineNameEx function with forced validation (the Validate parameter is set to True).

Refer to the DefineName function description for an example on how to use the defined names.


TcxSpreadSheetBook.ExchangeSheets

TcxSpreadSheetBook

Swaps two book sheets.

procedure ExchangeSheets(const ASheet1, ASheet2: Integer); virtual;

Description

The ExchangeSheets method swaps two sheets and the ASheet1 and ASheet2 parameters represent zero-based indexes of the book sheets to swap.

The following code demonstrates how to swap the first and the second book sheets:

//Delphi

  cxSpreadSheetBook1.ExchangeSheets(0, 1);

//C++Builder

  cxSpreadSheetBook1->ExchangeSheets(0, 1);


TcxSpreadSheetBook.DeleteSheet

TcxSpreadSheetBook

procedure DeleteSheet(const ASheet: Integer); virtual;

Description

The DeleteSheet method deletes the book sheet with the specific index. The ASheet parameter specifies the zero-based index of the sheet to delete.

The following code demonstrates how to delete the first book sheet:

//Delphi

  cxSpreadSheetBook1.DeleteSheet(0);

//C++Builder

  cxSpreadSheetBook1->DeleteSheet(0);


TcxSpreadSheetBook.OnDeleteSheet

TcxSpreadSheetBook

Occurs on book sheet deleting.

type

  TcxSSDeleteSheetEvent = procedure(const ASheet: Integer; var CanDelete: Boolean) of object;

property OnDeleteSheet: TcxSSDeleteSheetEvent;

Description

Write an OnDeleteSheet event handler to perform specific actions when a book sheet is about to be deleted.

The ASheet parameter provides the index of the sheet to be deleted.  The CanDelete parameter determines whether a book sheet can be deleted.  This parameter will be True as the event is entered but you can set it to False to prevent the deletion.


TcxSpreadSheetBook.OnExchangeSheets

TcxSpreadSheetBook

Occurs on book sheets swapping.

type

  TcxSSExchangeSheetsEvent  = procedure(const ASheet1, ASheet2: Integer; var CanExchange: Boolean) of object;

property OnExchangeSheets: TcxSSExchangeSheetsEvent;

Description

Write an OnDeleteSheets event handler to perform specific actions when book sheets are about to be swapped.

The ASheet1 and ASheet2 parameters provide the indexes of the sheets about to be swapped.  The CanExchange parameter determines whether a book sheet can be swapped.  This parameter will be True as the event is entered but you can set it to False to prevent the exchange.


TcxSpreadSheetBook.EditActiveSheetCaption

TcxSpreadSheetBook

Sets active book sheet caption to edit mode.

procedure EditActiveSheetCaption;

Description

Call this method whenever you need to change the active book sheet caption at runtime.  This method is equivalent to double clicking the active book sheet caption.

Suppose that the active book sheet is the first one:

After calling the EditActiveSheetCaption method the caption will be in edit mode:

Now you can operate on the caption using a single line text editor.  Pressing [Esc] will cancel any changes and exit edit mode, while pressing [Tab] or [Enter] will accept the change and also exit edit mode.  Changing focus will do the same as pressing [Tab] or [Enter].

You can type "First Sheet" over the top of "Sheet1" for instance, and having accepted the changes, you will see:


TcxCustomSpreadSheetBook.DeleteName

TcxCustomSpreadSheetBook          See Also

Marks the specified name as deleted in the DefinedNames collection.

function DeleteName(const AName: string): Boolean; dynamic;

Description

The name passed as the AName parameter is not removed from the DefinedNames collection; it’s simply marked as deleted.  Such names are ignored when this collection is searched for specific names (for instance, when the CellsNameByRef function is called).  For names marked as deleted, the name’s IsDeleted field returns True.

If the specified name is found within the DefinedNames collection and successfully deleted, the DeleteName function returns True.  Otherwise, False is returned.


TcxCustomSpreadSheetBook.HasRectName

TcxCustomSpreadSheetBook

Determines whether a cell or a group of cells has a name.

function HasRectName(ASheet: Integer; const ARect: TRect): Integer;

Description

The ASheet parameter specifies the book sheet where the cell or the group of cells is located. The ARect parameter specifies the cell or the group of cells to inspect. If the specified cell or group of cells has name, the method returns its zero-based index within the DefinedNames list. Otherwise it returns –1.

The HasRectName function ignores names marked as deleted.


cxExcelConst Unit Overview

Other Types

TcxSSFuncParams


TcxSSFuncParams
TcxSSFuncParams type

Contains values determining the number of formula parameters.

Unit

cxExcelConst

TcxSSFuncParams = (fpVariable, fpFixed, fpNone);

Description

Information about the number of formula parameters is required when performing formula calculations.

Value	Description
fpVariable	Indicates that the current formula has a variable number of parameters.
fpFixed	Indicates that the current formula has a fixed number of parameters.
fpNone	Indicates that the current formula has no parameters.