TcxButtonImageOptions.ImageIndex Property

Specifies the target image within an associated image list.

Declaration

property ImageIndex: TcxImageIndex read; write; default -1;

Property Value

Type	Description
TcxImageIndex	The target index within the image list assigned to the Images property.

Remarks

You can use ImageIndex/Images or Glyph to display a glyph within the button if its PaintStyle property is set to bpsDefault or bpsGlyph.

Note

The Glyph property has higher priority than ImageIndex and Images.

Source Image List Options

The ImageIndex property allows you to display an image from an image list assigned to the Images property. If the Images property is unspecified, the ImageIndex property allows you to display a glyph stored within the image list of the action associated with the button.

Vector Image Options

If you use an image list populated with SVG images as a single glyph source for all UI elements in your project, you can define individual dimensions for the button glyph using Images and ImageIndex properties.

Use the SVGOptions.LargeSize property to specify required glyph dimensions for the button. To apply new SVG glyph dimensions to the button, enable the SVGOptions.UseRegularAsLarge option.

Refer to the SVGOptions property description for additional information.

Button Layout Customization

You can use the following properties to modify caption and glyph positions within the button:

Layout

Allows you to switch between four predefined button content layouts (horizontal and vertical).

Margin

Specifies the distance between the displayed glyph and the nearest button border (depending on the current Layout property value).

Spacing

Allows you to adjust the distance between the glyph and the caption (regardless of the current Layout property value).

Code Example: Create Buttons with Different-Sized SVG Glyphs

The following code example creates five buttons with different-sized SVG glyphs using a single image list as a glyph source:

Delphi

uses
  cxButtons,  // Declares the TcxButton class and related types
  cxGraphics;  // Declares the TcxImageList class and related types
// ...

procedure TMyForm.FormCreate(Sender: TObject);
var
  AButton: TcxButton;
  ALargeGlyphSettings: TcxButtonImageOptions;
begin
  AButton := TcxButton.Create(Self);  // Creates the large "Apply" button
  AButton.Parent := Self;  // Associates the created button with the form
  AButton.Caption := 'Apply';
  AButton.Font.Size := 20;
  // Position the button
  AButton.Top := 40;
  AButton.Left := 40;
  AButton.Height := 60;
  AButton.Width := 140;
  // Assign a glyph and configure related settings
  ALargeGlyphSettings := AButton.OptionsImage;
  ALargeGlyphSettings.Images := cxImageList1;
  ALargeGlyphSettings.ImageIndex := 0;
  ALargeGlyphSettings.SVGOptions.UseRegularAsLarge := True;
  ALargeGlyphSettings.SVGOptions.LargeSize.Width := 48;
  ALargeGlyphSettings.SVGOptions.LargeSize.Height := 48;
  AButton := TcxButton.Create(Self);  // Creates the large "Cancel" button
  AButton.Parent := Self; // Associates the created button with the form
  // Position the button
  AButton.Top := 40;
  AButton.Left := 200;
  AButton.Height := 60;
  AButton.Width := 60;
  AButton.PaintStyle := bpsGlyph;
  // Assign a glyph and configure related settings
  AButton.OptionsImage.Assign(ALargeGlyphSettings);  // Copies common settings from the "Apply" button
  AButton.OptionsImage.ImageIndex := 1;  // Assigns a different glyph from the source image list
  AButton := TcxButton.Create(Self);  // Creates the small "Refresh" button
  AButton.Parent := Self;  // Associates the created button with the form
  AButton.Caption := 'Refresh';
  AButton.Left := 40;  // Positions the button
  AButton.OptionsImage.Images := cxImageList1;
  AButton.OptionsImage.ImageIndex := 2;
  AButton := TcxButton.Create(Self);  // Creates the small "Add" button
  AButton.Parent := Self;  // Associates the created button with the form
  AButton.Caption := 'Add';
  AButton.Left := 115;  // Positions the button
  AButton.OptionsImage.Images := cxImageList1;
  AButton.OptionsImage.ImageIndex := 3;
  AButton := TcxButton.Create(Self); // Creates the small "Remove" button
  AButton.Parent := Self;  // Associates the created button with the form
  AButton.Caption := 'Remove';
  AButton.Left := 190;  // Positions the button
  AButton.OptionsImage.Images := cxImageList1;
  AButton.OptionsImage.ImageIndex := 4;
end;

C++

#include "cxButtons.hpp"  // Declares the TcxButton class and related types
#include "cxGraphics.hpp"  // Declares the TcxImageList class and related types

// Add the following linker directives to the corresponding CPP source file:
#pragma link "cxButtons"  // Required to use cxButtons.hpp declarations
#pragma link "cxGraphics"  // Required to use cxGraphics.hpp declarations
// ...

void __fastcall TMyForm::FormCreate(TObject *Sender)
{
  TcxButton *AButton;
  TcxButtonImageOptions *ALargeGlyphSettings;
  AButton = new TcxButton(this);  // Creates the large "Apply" button
  AButton->Parent = this;  // Associates the created button with the form
  AButton->Caption = "Apply";
  AButton->Font->Size = 20;
  // Resize and position the button
  AButton->Top = 40;
  AButton->Left = 40;
  AButton->Height = 60;
  AButton->Width = 140;
  // Assign a glyph and configure related settings
  ALargeGlyphSettings = AButton->OptionsImage;
  ALargeGlyphSettings->Images = cxImageList1;
  ALargeGlyphSettings->ImageIndex = 0;
  ALargeGlyphSettings->SVGOptions->UseRegularAsLarge = true;
  ALargeGlyphSettings->SVGOptions->LargeSize->Width = 48;
  ALargeGlyphSettings->SVGOptions->LargeSize->Height = 48;
  AButton = new TcxButton(this);  // Creates the large "Cancel" button
  AButton->Parent = this;  // Associates the created button with the form
  // Resize and position the button
  AButton->Top = 40;
  AButton->Left = 200;
  AButton->Height = 60;
  AButton->Width = 60;
  AButton->PaintStyle = bpsGlyph;
  // Assign a glyph and configure related settings
  AButton->OptionsImage->Assign(ALargeGlyphSettings);  // Copies common settings from the "Apply" button
  AButton->OptionsImage->ImageIndex = 1;  // Assigns a different glyph within the source image list
  AButton = new TcxButton(this);  // Creates the small "Refresh" button
  AButton->Parent = this;  // Associates the created button with the form
  AButton->Caption = "Refresh";
  AButton->Left = 40;  // Positions the button
  AButton->OptionsImage->Images = cxImageList1;
  AButton->OptionsImage->ImageIndex = 2;
  AButton = new TcxButton(this);  // Creates the small "Add" button
  AButton->Parent = this;  // Associates the created button with the form
  AButton->Caption = "Add";
  AButton->Left = 115; // Positions the button
  AButton->OptionsImage->Images = cxImageList1;
  AButton->OptionsImage->ImageIndex = 3;
  AButton = new TcxButton(this);  // Creates the small "Remove" button
  AButton->Parent = this;  // Associates the created button with the form
  AButton->Caption = "Remove";
  AButton->Left = 190;  // Positions the button
  AButton->OptionsImage->Images = cxImageList1;
  AButton->OptionsImage->ImageIndex = 4;
}

Limitations and Considerations

The glyph selected using the ImageIndex property is displayed in all button states. If you need individual glyphs for different button states, use Glyph and NumGlyphs properties instead.

Default Value

The ImageIndex property’s default value is -1.

The default ImageIndex property value indicates that no image from the associated image list is associated with the button.