Unit 'ImgList' Package
[Overview][Types][Classes][Procedures and functions][Index] [#lcl]

TCustomImageList

[Properties (by Name)] [Methods (by Name)] [Events (by Name)]

The base class for TImageList.

Declaration

Source position: imglist.pp line 266

type TCustomImageList = class(TLCLComponent)

protected

  function GetResolution();

  

Gets the value for the indexed Resolution property.

  function GetResolutionClass; virtual;

  

Gets the class type used to create image resolutions in the list.

  procedure CheckIndex();

  

Ensures that an Index position is valid for the bounds of the image list.

  procedure Initialize; virtual;

  

Performs the initial set up for the image list.

  procedure DefineProperties(); override;

  

Defines properties used in the LCL component streaming mechanism.

  procedure SetWidthHeight();

  

Sets the Width and Height for images in the default resolution.

  procedure ClearOverlays;

  

Clears images indexes assigned as overlay images in the image list.

  procedure MarkAsChanged;

  

Sets the value in the internal Changed flag to True.

  procedure DoAfterUpdateStarted; virtual;

  

Performs actions needed after the BeginUpdate method is started.

  procedure DoBeforeUpdateEnded; virtual;

  

Performs actions needed before the EndUpdate method is completed.

public

  constructor Create(); override;

  

Constructor for the class instance.

  constructor CreateSize();

  

Initializes the image list using the specified height and width.

  destructor Destroy; override;

  

Destructor for the class instance.

  class procedure ScaleImage();

  

Scales an image and its optional mask to the specified target size.

  procedure AssignTo(); override;

  

Assigns properties in an image list to another instance of the class.

  procedure Assign(); override;

  

Stores properties from the specified image list to the current class instance.

  procedure WriteData(); virtual;

  

Writes image data for the default resolution to a stream.

  procedure ReadData(); virtual;

  

Reads image data for the default resolution from a stream.

  procedure WriteAdvData(); virtual;

  

Writes the image content for multiple resolutions to the specified stream.

  procedure ReadAdvData(); virtual;

  

Reads the image content for multiple resolutions from a stream.

  function Equals(); override;

  

Compares the contents of the image lists.

  procedure BeginUpdate;

  

Starts an update to the image list, and controls execution of the OnChange event.

  procedure EndUpdate;

  

Finishes an update to the image list, and calls Change.

  function Add();

  

Adds an image to the list using its source data and optional mask.

  function AddMultipleResolutions();

  

Adds images with varying sizes to the corresponding image resolution.

  function AddSliced();

  

Adds images to the image list from image data stored as adjacent columns and rows.

  function AddSlice();

  

Adds a portion of an image to each of the resolutions in the image list.

  function AddSliceCentered();

  

Adds an image centered in the height and width for the image resolutions.

  function AddIcon();

  

Adds an icon to the image list.

  procedure AddImages();

  

Adds images from another image list to the current class instance.

  function AddMasked();

  

Adds an image(s) to the list using the MaskColor for transparent pixels.

  function AddLazarusResource();

  

Gets a bitmap from a Lazarus resource and stores it in the image list.

  function AddResourceName();

  

Adds a graphic from a resource with the specified resource name.

  procedure Change;

  

Sends change notifications when the image list is updated.

  procedure Clear;

  

Removes all images store in the the image list.

  procedure Delete();

  

Deletes the image at the specified position from all image resolutions.

  procedure Draw();

  

Renders an image to the specified canvas using a drawing style or effect.

  procedure DrawForPPI();

  

Renders an image to a canvas scaled to a specified display density.

  procedure DrawOverlay();

  

Renders an image with an overlay to the specified canvas.

  procedure GetBitmap();

  

Gets image data at the specified position as a bitmap.

  procedure GetFullBitmap();

  

Gets a bitmap with all of the images in the default resolution.

  procedure GetFullRawImage();

  

Gets the raw image data for all images in the default resolution.

  procedure GetIcon();

  

Gets the icon at the specified index and applies an image effect.

  procedure GetRawImage();

  

Gets the raw image data at the specified position from the default image resolution (Width).

  function GetHotSpot;

  

Returns the offset from the drawing position to the image origin.

  procedure Insert();

  

Inserts an image into each image resolution at the specified position.

  procedure InsertIcon();

  

Inserts an Icon into each of the resolutions for the image list.

  procedure InsertMasked();

  

Inserts a transparent image into the image resolutions at the specified position.

  procedure Move();

  

Moves an image from the position at CurIndex to NewIndex.

  procedure Overlay();

  

Assigns an overlay index for the specified image in the image list.

  property HasOverlays: Boolean; [r]

  

Indicates if any images in the list have been used as an overlay image.

  procedure Replace();

  

Replaces an image at the specified position with the given bitmap.

  procedure ReplaceSlice();

  

Replace an image at the specified position with a slice from the specified image.

  procedure ReplaceSliceCentered();

  

Replaces the image at the specified position from image data stored as adjacent columns and rows.

  procedure ReplaceIcon();

  

Replaces the icon at the specified position in all resolutions for the image list.

  procedure ReplaceMasked();

  

Replaces the image at the specified position with a masked image.

  procedure RegisterChanges();

  

Registers a TChangeLink object for notifications when the image list is changed.

  procedure StretchDraw();

  

Draws an image stretched to the dimensions for the target rectangle.

  procedure UnRegisterChanges();

  

Unregisters a ChangeLink object for change notifications.

  procedure RegisterResolutions(); virtual;

  

Registers image resolutions (sizes) to use in the image list.

  procedure DeleteResolution();

  

Deletes the image resolution which uses the specified image width.

  function FindResolution();

  

Finds the image resolution which uses the specified image width.

  property AllocBy: Integer; [rw]

  

Size used to increment the allocated data count.

  property BlendColor: TColor; [rw]

  

Color used when blending (dithering) an image.

  property BkColor: TColor; [rw]

  

Specifies the background color used for transparent parts of images.

  property Count: Integer; [r]

  

Number of images stored in the default resolution for the image list.

  property DrawingStyle: TDrawingStyle; [rw]

  

The default drawing style for images in the image list.

  property Handle: TLCLHandle; [r]

  

Contains the handle for the default image resolution in the image list.

  property Height: Integer; [rw]

  

Height of images in the default resolution for the image list.

  property HeightForPPI []: Integer; [r]

  

Height for images at the specified display density.

  property HeightForWidth []: Integer; [r]

  

Height used for images with the width specified width.

  property Width: Integer; [rw]

  

Width of images in the default resolution for the image list.

  property WidthForPPI []: Integer; [r]

  

Image width needed for the specified display density (PPI).

  property SizeForPPI []: TSize; [r]

  

Size used for images with the specified image width at the given display density.

  property OnChange: TNotifyEvent; [rw]

  

Event handler signalled when the image list is changed.

  property Masked: Boolean; [rw]

  

Indicates if an image mask is used for images in the list.

  property Reference []: TWSCustomImageListReference; [r]

  

Provides access to the reference class for the specified resolution.

  property ReferenceForPPI []: TWSCustomImageListReference; [r]

  

Reference class using the specified image width and display density.

  property Resolution []: TCustomImageListResolution; [r]

  

Provides indexed access to an image resolution with the specified image width.

  property ResolutionByIndex []: TCustomImageListResolution; [r]

  

Provides access to an image resolution by its ordinal position in the image list.

  property ResolutionForPPI []: TScaledImageListResolution; [r]

  

Gets a scaled resolution with the specified width, display density, and scaling factor.

  property ResolutionCount: Integer; [r]

  

Number of image resolutions available in the image list.

  function Resolutions;

  

Provides access to the image resolutions (or sizes) used in the image lists.

  function ResolutionsDesc;

  

Provides access to the descending enumerator for image resolutions in the list.

  property Scaled: Boolean; [rw]

  

Controls whether image sizes are automatically scaled for different display density (Pixels per Inch) settings.

  property ShareImages: Boolean; [rw]

  

True when the handle for the image list is shared.

  property ImageType: TImageType; [rw]

  

Controls whether images are drawn with or without a mask.

  property OnGetWidthForPPI: TCustomImageListGetWidthForPPI; [rw]

  

Event handler used to override the scaled width for a display density.

end;

Inheritance

TCustomImageList

  

The base class for TImageList.

|

TLCLComponent

  

The base class for LCL components which have an associated widget.

|

TComponent
|

TPersistent,IUnknown,IInterfaceComponentReference
|

TObject,IFPObserved

Description

TCustomImageList is a TLCLComponent descendant that implements the base class for TImageList. Image lists are used to provide images, icons, and overlays in controls like TMenu, TToolBar, TCoolBar, TActionList, TComboEx, TTabControl, TDBNav, TListView, TTreeView, and others.

Historically, TCustomImageList was based on the Win32 image list implemented in Delphi. Internally, the image list contained images (bitmaps or icons) of the same Width and Height. The images were stored in one big bitmap, whose total width was Width * Count pixels. This reduced the number of handles allocated when images in the image list were accessed.

Starting with LCL version 1.9, the concept of multiple image resolutions (or sizes) was introduced in TCustomImageList. This allowed the image list to contain multiple sizes for a given image. Multiple resolutions are implemented as parallel image lists, with images of the same size stored in a single image list. Image scaling was also introduced in TCustomImageList using its new support classes, and allowed resizing of images for high PPI (pixels per inch) displays.

Images stored in TCustomImageList are represented using 32-bit RGBA (Red Green Blue Alpha) raw image data. Transparency is implemented using the Alpha channel in the raw image data, but not all platforms/widgetsets support an 8-bit Alpha channel. Any image type descended from TCustomBitmap can be added to an image list, including:

Remark: Starting with Lazarus 2.2, binary bitmap data stored for the image list in an LFM file uses ZLib compression. While this makes both the LFM and the EXE smaller, it also prevents Lazarus versions prior to 2.0 from opening the LFM file. If you need to maintain a Version 2.X project in an older Lazarus version, you first have to open it in Lazarus 2.0 and resave any forms with a TImageList. Then you can open these resaved LFMs in Lazarus versions prior to 2.0.

Use the Width and Height properties to set the default resolution (or size) used for images in the image list. If an image with a size different than the values in Width and Height is added to the default resolution, it is scaled the dimensions required for the resolution. The Width and Height properties also establish the image size used at the 100% scaling level on a 96 PPI display.

Changing the value in the Width or Height properties causes the image list and all of its resolutions to be cleared. Set the values in Width and Height prior to adding images to the default resolution.

TCustomImageList implements an internal container for each Resolution (or size) supported in the image list. This TCustomImageListResolutions class instance maintains separate parallel image lists where each list contains images for a given height and width.

Use the Resolutions or ResolutionsDesc methods to access enumerators (ascending and descending respectively) for the image resolutions stored in the container.

Each image Resolution (or size) is represented using a TCustomImageListResolution class instance. Like previous versions of TCustomImageList, it provides properties and methods needed to access and maintain images using a common height and width. It also provides access to the 32-bit RGBA raw image data for images in the resolution. The Draw, StretchDraw, and DrawOverlay methods are provided to render an image to a TCanvas instance.

Use the indexed Resolution property to access the image list with a specific image width. Use ResolutionByIndex to get an image resolution using its position in the image resolutions container. Use ResolutionForPPI to get a dynamically scaled image resolution using a specific image width, display density, and scaling factor.

The FindResolution method can be used to locate the image list which uses a specific image width. Use the RegisterResolutions method to pre-define the image sizes supported in the image list.

Use the Scaled property to indicate if images are automatically scaled to a Resolution not stored in the image list. Setting Scaled to True enables the automatic scaling features in TCustomImageList, and allows images to be scaled for use on high PPI displays. When an image list is selected using the Resolution property, or by calling GetResolutionForPPI, images will automatically be scaled from a suitable candidate resolution to the requested value. Set Scaled to False to use the closest image size in the list. Use the OnGetWidthForPPI event handler to perform image size substitution based on pixel display density.

Use the Masked property to determine if images in the list have a mask applied to define the transparent areas in images. Use the Add method to store an image with the combined values from its source data and optional mask. Use AddMasked to store an image using MaskColor to represent its transparent areas. Use AddMultipleResolutions to scale and store an array of bitmaps to each of the Resolutions defined for the image list. Use AddSlice and AddSliced to store one or many images using the native image list storage format. Use ImageType to indicate whether the image list contains images or image masks.

Please note that inserting or moving images will affect the index position for all following images in the resolution, and may cause problems when constant index positions are expected. In such cases a bitmap collection may better fit your needs.

Remark: Due to its use of multiple resolutions and dynamic scaling, TCustomImageList is not suitable for use as a generic TBitmap collection. If fast storage of bitmaps is needed, you can create your own container using an array or TList class instance.

Version info

Multiple image resolutions, and scaling were added in LCL version 1.9.

See also

TCustomImageListResolutions

  

Provides multiple image resolutions in TCustomImageList.

TCustomImageListResolution

  

Implements an image resolution (or size) used in TCustomImageList.

TScaledImageListResolution

  

Implements a scaled image resolution (size).

Lazarus Component Library (LCL) Version 3.99-1d79f9e4df (2024-03-21) Home