TdxChartUserPalette Class

A custom Chart palette.

Declaration

TdxChartUserPalette = class(
    TdxChartPalette
)

Remarks

A user palette stores a set of custom colors you can apply to series and series points in a Chart control. You can apply a user palette in the same way as any predefined palette.

Use a TdxChartPaletteRepository component to store and manage a collection of user palettes. You can double-click the component at design time to invoke the Palette Repository Dialog dialog.

This dialog allows you to create, populate, customize, export, and import user palettes.

Main API Members

The list below outlines key members of the TdxChartUserPalette class. These members allow you to manage palette colors and store them in a file or stream.

Palette Item Access and Management APIs

The number of elements that require different colors may exceed the palette size. In such cases, a palette can generate interpolated items based on stored colors.

Count

Specifies the number of stored palette items.

You can use this property to change the number of stored palette items.

GetColorsForIndex

Returns a stored or extrapolated palette item by the specified index.

The specified index may exceed the maximum stored item index (Count - 1). In this case, the function returns a palette item with an extrapolated color. The extrapolation algorithm uses colors from items you added to the collection.

Note

As the specified index increases, the difference between two adjacent interpolated colors becomes less distinguishable.

Items

Provides indexed access to stored user palette items and allows you to manage them.

Palette Save and Load Methods

You can store custom palette colors in an internal XML-like format.

LoadFromFile | LoadFromStream

Load previously saved palette colors from a file or stream.

SaveToFile | SaveToStream

Save all palette items to a file or stream.

General-Purpose API Members

Name

Specifies the unique user palette name.

An exception occurs if you assign a name that matches the name of an existing standard palette or another palette stored in the same repository.

Repository

Provides access to the parent palette repository component.

Code Example: Create and Populate a User Palette

The code example below creates a user palette, populates it with three sets of different primary and secondary colors, and applies the created palette to a Chart control with three simple Bar series. All series bars are filled with vertical linear gradients.

Delphi

var
  AChartPalette: TdxChartUserPalette;
begin
  AChartPalette := dxChartPaletteRepository1.CreateItem('My Palette 1');
  AChartPalette.Count := 3;  // Sets the size of the palette item array
  AChartPalette.Items[0] := TdxChartPaletteItem.Create(TdxAlphaColors.RosyBrown, TdxAlphaColors.Red);
  AChartPalette.Items[1] := TdxChartPaletteItem.Create(TdxAlphaColors.LightGreen, TdxAlphaColors.Green);
  AChartPalette.Items[2] := TdxChartPaletteItem.Create(TdxAlphaColors.LightBlue, TdxAlphaColors.Blue);
  dxChartControl1.Palette := AChartPalette; // Applies the created palette to a Chart control
end;

C++

  // ...
  TdxChartUserPalette *AChartPalette;
  // ...
  AChartPalette = dxChartPaletteRepository1->CreateItem("My Palette 1");
  AChartPalette->Count = 3;  // Sets the size of the palette item array
  AChartPalette->Items[0] = TdxChartPaletteItem(TdxAlphaColors::RosyBrown, TdxAlphaColors::Red);
  AChartPalette->Items[1] = TdxChartPaletteItem(TdxAlphaColors::LightGreen, TdxAlphaColors::Green);
  AChartPalette->Items[2] = TdxChartPaletteItem(TdxAlphaColors::LightBlue, TdxAlphaColors::Blue);
  dxChartControl1->Palette = AChartPalette;  // Applies the created palette to a Chart control

Inheritance

TObject

TdxChartPalette

TdxChartUserPalette