HotXLS-dokumentation Indhold Startside Oversigt IXLSWorkbook TXLSWorksheets Startside Indhold Oversigt

AddChartSheet metode

Programmatically appends a BIFF8 chart sheet to the workbook, returning the new TXLSWorksheet tab. Previously, chart sheets could only be preserved opaquely on a load-save round-trip via TXLSCustomChart; this method writes a complete chart substream directly into SaveAs(xlExcel97). Excel opens the result as a chart tab of the requested kind. Available since v2.41.0 (Roadmap #10 Phase 1); the array-of-series overload follows in v2.42.0

TXLSChartType enumeration

Selects the chart kind. Re-exported from lxHandle so user code does not need to import the chart-builder unit directly type TXLSChartType = ( xlsChartTypeColumn, xlsChartTypeBar, xlsChartTypeLine, xlsChartTypePie);

TXLSChartSeriesInfo record

Carries a single series declaration for the 6-parameter overload. Categories and Values are A1-range strings (e.g. 'Sheet1!$B$2:$B$5') type TXLSChartSeriesInfo = record Name : WideString; Categories : WideString; Values : WideString; end;

Syntaks

Five overloads cover progressively richer chart-sheet definitions: // 1) v2.41.0 — name only; default column chart, no titles, no series. function AddChartSheet(const Name: WideString): TXLSWorksheet; // 2) v2.41.0 — name + chart type. function AddChartSheet( const Name : WideString; ChartType : TXLSChartType): TXLSWorksheet; // 3) v2.41.0 — + chart title. function AddChartSheet( const Name : WideString; ChartType : TXLSChartType; const Title: WideString): TXLSWorksheet; // 4) v2.41.0 — + category-axis title + value-axis title. function AddChartSheet( const Name : WideString; ChartType : TXLSChartType; const Title : WideString; const CatAxisTitle: WideString; const ValAxisTitle: WideString): TXLSWorksheet; // 5) v2.42.0 — + array of series (Name + Categories range + Values range). function AddChartSheet( const Name : WideString; ChartType : TXLSChartType; const Title : WideString; const CatAxisTitle: WideString; const ValAxisTitle: WideString; const Series : array of TXLSChartSeriesInfo): TXLSWorksheet;

Bemærkninger

The emitted chart substream covers the BIFF8 framing the spec calls for — BOF (dt=$0020), Chart / PlotGrowth / Frame / Series / SheetProperties / AxesUsed / AxisParent (POS + category axis + value axis + PlotArea + Frame + ChartFormat + chart-kind record + ChartFormatLink + Legend), EOF. Existing chart-sheet round-trip via TXLSCustomChart is unchanged
Series name binding (v2.42.0): each non-empty Series[i].Name is written into the chart substream as a literal series label via a tStr PTG token on the series-name BRAI (id=2). Excel uses this label in the legend and series selector, so multi-series charts show proper captions instead of the default "Series1 / Series2" placeholders
Series range binding (v2.47.0): starting in v2.47.0, the Categories and Values A1-range strings are compiled into real tArea3D cell-range references inside the BRAI, going through the formula compiler and the workbook EXTERNSHEET reference table. Before v2.47.0 these two fields were accepted on the API but emitted as cce=0 placeholders, so the rendered chart was empty. Existing v2.42.0 callers that left Categories / Values empty are unaffected
The returned TXLSWorksheet appears in the Sheets collection and gets a chart-sheet boundsheet entry written on save. Cell-level methods on the result are unsupported — the host worksheet is a chart container, not a data sheet

Eksempel

This example builds a workbook with a data sheet and a column chart bound to two columns of that data sheet
var Series: array of TXLSChartSeriesInfo; begin // Populate cells on Sheet1. Workbook.Sheets[1].Name := 'Data'; // ... fill A1:B5 with categories + values ... SetLength(Series, 1); Series[0].Name := 'Quarterly Revenue'; Series[0].Categories := 'Data!$A$2:$A$5'; Series[0].Values := 'Data!$B$2:$B$5'; Workbook.Sheets.AddChartSheet( 'Revenue', xlsChartTypeColumn, 'Quarterly Revenue', 'Quarter', 'USD', Series); Workbook.SaveAs('Revenue.xls', xlExcel97); end;

Limitations

Per-chart-type formatting details (gap width, bar overlap, pie hole size, marker style) are still emitted at the chart-builder defaults — not yet exposed on the API. Save-and-reopen with Excel preserves the chart sheet's presence, kind, title, axis titles, series captions, and (from v2.47.0) the series data binding