TCustomImageList class

In unit ImgList

The base class for TImageList.

Declaration

pascal

TCustomImageList = class(TLCLComponent)

Inheritance

Descends from it: TDragImageList TLCLGlyphs

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:

TBitmap
TIcon
TPortableNetworkGraphic
TPortableAnyMapGraphic
TJpegImage
TGIFImage
TTiffImage
TPixMap

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.

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.

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

Properties

`HasOverlays`	public	Indicates if any images in the list have been used as an overlay image.
`AllocBy`	public	Size used to increment the allocated data count.
`BlendColor`	public	Color used when blending (dithering) an image.
`BkColor`	public	Specifies the background color used for transparent parts of images.
`Count`	public	Number of images stored in the default resolution for the image list.
`DrawingStyle`	public	The default drawing style for images in the image list.
`Handle`	public	Contains the handle for the default image resolution in the image list.
`Height`	public	Height of images in the default resolution for the image list.
`HeightForPPI`	public	Height for images at the specified display density.
`HeightForWidth`	public	Height used for images with the width specified width.
`Width`	public	Width of images in the default resolution for the image list.
`WidthForPPI`	public	Image width needed for the specified display density (PPI).
`SizeForPPI`	public	Size used for images with the specified image width at the given display density.
`Masked`	public	Indicates if an image mask is used for images in the list.
`Reference`	public	Provides access to the reference class for the specified resolution.
`ReferenceForPPI`	public	Reference class using the specified image width and display density.
`Resolution`	public	Provides indexed access to an image resolution with the specified image width.
`ResolutionByIndex`	public	Provides access to an image resolution by its ordinal position in the image list.
`ResolutionForPPI`	public	Gets a scaled resolution with the specified width, display density, and scaling factor.
`ResolutionCount`	public	Number of image resolutions available in the image list.
`Overlays`	public	Provides access to images used as overlays in the image list.
`Scaled`	public	Controls whether image sizes are automatically scaled for different display density (Pixels per Inch) settings.
`ShareImages`	public	True when the handle for the image list is shared.
`ImageType`	public	Controls whether images are drawn with or without a mask.

Methods

`GetResolution`	protected	Gets the value for the indexed Resolution property.
`GetResolutionClass`	protected	Gets the class type used to create image resolutions in the list.
`CheckIndex`	protected	Ensures that an Index position is valid for the bounds of the image list.
`Initialize`	protected	Performs the initial set up for the image list.
`DefineProperties`	protected	Defines properties used in the LCL component streaming mechanism.
`SetWidthHeight`	protected	Sets the Width and Height for images in the default resolution.
`ClearOverlays`	protected	Clears images indexes assigned as overlay images in the image list.
`MarkAsChanged`	protected	Sets the value in the internal Changed flag to True.
`DoAfterUpdateStarted`	protected	Performs actions needed after the BeginUpdate method is started.
`DoBeforeUpdateEnded`	protected	Performs actions needed before the EndUpdate method is completed.
`Create`	public	Constructor for the class instance.
`CreateSize`	public	Initializes the image list using the specified height and width.
`Destroy`	public	Destructor for the class instance.
`ScaleImage`	public	Scales an image and its optional mask to the specified target size.
`AssignTo`	public	Assigns properties in an image list to another instance of the class.
`Assign`	public	Stores properties from the specified image list to the current class instance.
`WriteData`	public	Writes image data for the default resolution to a stream.
`ReadData`	public	Reads image data for the default resolution from a stream.
`WriteAdvData`	public	Writes the image content for multiple resolutions to the specified stream.
`ReadAdvData`	public	Reads the image content for multiple resolutions from a stream.
`Equals`	public	Compares the contents of the image lists.
`BeginUpdate`	public	Starts an update to the image list, and controls execution of the OnChange event.
`EndUpdate`	public	Finishes an update to the image list, and calls Change.
`Add`	public	Adds an image to the list using its source data and optional mask.
`AddMultipleResolutions`	public	Adds images with varying sizes to the corresponding image resolution.
`AddSliced`	public	Adds images to the image list from image data stored as adjacent columns and rows.
`AddSlice`	public	Adds a portion of an image to each of the resolutions in the image list.
`AddSliceCentered`	public	Adds an image centered in the height and width for the image resolutions.
`AddIcon`	public	Adds an icon to the image list.
`AddImages`	public	Adds images from another image list to the current class instance.
`AddMasked`	public	Adds an image(s) to the list using the MaskColor for transparent pixels.
`AddLazarusResource`	public	Gets a bitmap from a Lazarus resource and stores it in the image list.
`AddResourceName`	public	Adds a graphic from a resource with the specified resource name.
`Change`	public	Sends change notifications when the image list is updated.
`Clear`	public	Removes all images store in the image list.
`Delete`	public	Deletes the image at the specified position from all image resolutions.
`Draw`	public	Renders an image to the specified canvas using a drawing style or effect.
`DrawForPPI`	public	Renders an image to a canvas scaled to a specified display density.
`DrawOverlay`	public	Renders an image with an overlay to the specified canvas.
`GetBitmap`	public	Gets image data at the specified position as a bitmap.
`GetFullBitmap`	public	Gets a bitmap with all of the images in the default resolution.
`GetFullRawImage`	public	Gets the raw image data for all images in the default resolution.
`GetIcon`	public	Gets the icon at the specified index and applies an image effect.
`GetRawImage`	public	Gets the raw image data at the specified position from the default image resolution (Width).
`GetHotSpot`	public	Returns the offset from the drawing position to the image origin.
`Insert`	public	Inserts an image into each image resolution at the specified position.
`InsertIcon`	public	Inserts an Icon into each of the resolutions for the image list.
`InsertMasked`	public	Inserts a transparent image into the image resolutions at the specified position.
`Move`	public	Moves an image from the position at CurIndex to NewIndex.
`Overlay`	public	Assigns the specified image to the given overlay position for the image list.
`Replace`	public	Replaces an image at the specified position with the given bitmap.
`ReplaceSlice`	public	Replace an image at the specified position with a slice from the specified image.
`ReplaceSliceCentered`	public	Replaces the image at the specified position from image data stored as adjacent columns and rows.
`ReplaceIcon`	public	Replaces the icon at the specified position in all resolutions for the image list.
`ReplaceMasked`	public	Replaces the image at the specified position with a masked image.
`RegisterChanges`	public	Registers a TChangeLink object for notifications when the image list is changed.
`StretchDraw`	public	Draws an image stretched to the dimensions for the target rectangle.
`UnRegisterChanges`	public	Unregisters a ChangeLink object for change notifications.
`RegisterResolutions`	public	Registers image resolutions (sizes) to use in the image list.
`DeleteResolution`	public	Deletes the image resolution which uses the specified image width.
`FindResolution`	public	Finds the image resolution which uses the specified image width.
`SetSize`	public
`Resolutions`	public	Provides access to the image resolutions (or sizes) used in the image lists.
`ResolutionsDesc`	public	Provides access to the descending enumerator for image resolutions in the list.

Events

`OnChange`	public	Event handler signalled when one or more of the images in the image list has been changed.
`OnGetWidthForPPI`	public	Event handler used to override the scaled width for a display density.