Contains classes and types used in TCustomImageList, the base class for TImageList.

imglist.pp implements TImageList and TChangelink in the Lazarus Component Library (LCL).

Orginal author: Marc Weustink

Type used for an image list index (integer).
Not used in the current implementation. Exists for Delphi compatibility only, but is unused there as well.
Specifies an event handler signalled when images are removed from TImageList.

TDestroyResolutionHandleEvent specifies an event handler signalled when images in a TImageList instance with a specific width are removed. TDestroyResolutionHandleEvent is the type used to implement the OnDestroyResolutionHandle in TChangeLink.

Image list generating the event notification.
Width of the image being removed.
Handle for the image list updated in the method.
Performs notifications when images are added or deleted in TImageList.

TChangeLink is a class used to perform notifications when images are added or deleted in TImageList. TChangelink provides event handlers that are signalled when the image list performs actions requiring the notification. TImageList allows multiple objects to subscribe to the change notifications, and each subscriber is represented by a TChangeLink class instance.

TChangeLink instances are passed to TCustomImageList (and descendants) in the RegisterChanges method.

Destructor for the class instance.

Destroy is the overridden destructor for the class instance. Destroy ensures that the image list in the Sender property calls its UnRegisterChanges method before freeing the class instance. When Sender is unassigned (contains Nil), no actions are performed. Destroy calls the inherited destructor prior to exiting from the method.

Signals the OnChange event handler.

Change is a procedure used to fire the OnChange event handler. Change requires a TNotifyEvent event handler procedure to be assigned to the OnChange property to perform the event notification. When OnChange is assigned, it is called using Sender as the image list for the notification. No actions are performed in the method when OnChange is unassigned (contains Nil).

Event handler signalled for a change in the image list.

OnChange is a TNotifyEvent property that represents the event handler signalled for a change in the image list. OnChange is signalled from the Change method.

Event handler signalled when the handle for an image resolution is freed.
The Image list for change notifications in the class.
Defines drawing styles for images.

TDrawingStyle is an enumerated type with values that control the drawing style used for images in TCustomImageList. TDrawingStyle affects the blending of the image with its background color when a mask is used in the image. These values have no significance when a mask is not present in the image. TDrawingStyle corresponds to the style values used in the WIN ImageList_Draw API.

Draws the image background using its focused color.
Draws the image background using its selected color.
Draw using BkColor for the background, or transparent if BkColor is clNone.
Always draw transparently, ignore BkColor and BlendColor.
Indicates if an image contains display data or a mask for its transparent parts.

TImageType indicates if an image contains contains the display data from an image or the mask for its transparent parts. The mask controls the parts of the image drawn using transparency. TImageType is the type used for the TCustomImageList.ImageType property.

Does not represent a mask.
Contains a mask.
Represents the valid index positions used to access overlay image assignments.

TOverlay is a range type with values in the range 0..14. TOverlay represents the valid indices that can be used to access images in the list that are used as Overlays. The range type mirrors the values available in the WIN ImageList_SetOverlayImage API. 0 is normally used when an overlay is not needed.

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

TCustomImageListResolution is a TLCLReferenceComponent descendant that implements an image resolution (or size) used in TCustomImageList. TCustomImageListResolution (along with TCustomImageListResolutions) is the mechanism which makes multiple resolutions possible in TCustomImageList.

TCustomImageListResolution provides properties that indicate the Height and Width of images stored in the resolution. It also contains the 32-bit RGBA raw image data for its images, the handle for its image list, and whether the resolution was created at design-time. Methods are provided to access and maintain the bitmap images (or their masks) used in the resolution. Other methods can be used to get the images as bitmaps, icons, or raw image data.

TCustomImageListResolution instances are created and stored in a TCustomImageListResolutions container. TCustomImageListResolution is the type used for the Resolution and ResolutionByIndex properties in TCustomImageList.

Allocates storage for the specified number of images in the resolution.

AllocData is a procedure used to allocate storage for the specified number of images in the resolution. AllocData ensures that the internal allocation count is large enough to accommodate the number of images in ACount. No actions are performed in the method when sufficient storage is available for the image count.

AllocData ensures that sufficient data storage blocks are allocated using the internal AllocBy value for the image list to store the number of images in ACount. AllocData is used in the implementation of the AddImages, InternalInsert, and ReadData methods. It is also called from the Assign method in TCustomImageList.

Number of images that require data storage.
Gets the value for the Reference property.
Value for the Reference property.
Adds an image with an optional mask to the resolution.

Add is used to append an image to the items stored in the resolution. The return value contains the ordinal position in the image list where the new image was stored.

Image contains the bitmap data for the image. Mask is an optional bitmap that defines the transparent areas for the image. When Image has not been assigned (contains Nil), no actions are performed in the method and the return value is set to -1.

Add ensures that both Image and Mask are the correct size for the resolution by calling the TCustomImageList.ScaleImage method. The values in the Height and Width properties are used as the dimensions for the scaled image. The 32-bit RGBA raw image data for the scaled image is stored using the InternalInsert method.

Use the AddImages method to add images from another image resolution to the current image resolution.

Ordinal position for the image added in the method.
Bitmap image added in the method.
Optional bitmap mask for the image.
Performs actions to insert raw image data at the specified position.
Position where image data is inserted in the list.
Bitmap data to insert at the specified position.
Performs actions to move the storage position for image data.
Current position of the image moved in the method.
New position for the image.
Indicates if memory in the current index position is updated after moving the image data.
Performs actions to replace image data at the specified position.
Position in the list where the image data is stored.
Image data stored in the method.
Performs actions to store raw image data at the specified position.
Pointer to the 32-bit RGBA raw image data stored in the method.
Position in the list where image data is stored.
Image data stored in the method.
Ensures an index position is valid for the specified operation.

CheckIndex is a procedure used to ensure that the value in AValue is a valid index position for the operations in the class.

AForInsert indicates if AValue is constrained to the existing range of ordinal positions in the list. When AForInsert contains True, AValue must be less than the Count property. When AForInsert is False, the index value is for an append operation and can contain a value less than or equal to the Count property.

An EInvalidOperation exception is raised when AValue is not in the required range for the specified operation.

CheckIndex is used in the implementation of various methods in the class.

Raises an EInvalidOperation exception if the index value is not in range. Raised with the message in SInvalidIndex.
Ordinal position in the list to validate in the method.
Indicates if the index position is for an insert operation.
Removes all image data for the current resolution.

Clear is a procedure used to remove the 32-bit RGBA raw image data stored in the class instance. No actions are performed in the method when images have not been stored using the resolution.

For widgetsets that allocate a handle for an image list, the Reference class is used to call its Clear method for the current class instance.

Clear sets the length of the internal storage for image data and the allocation count to 0 (zero).

Deletes the image at the specified position in the resolution.

Delete is a procedure used to delete the image at the specified position in the resolution.

AIndex contains the ordinal position in the list for the image deleted in the method. When AIndex contains -1, all images in the list are removed by calling the Clear method. Delete calls the CheckIndex method to ensure that AIndex contains a valid ordinal position in the list. When AIndex is not the last item in the list, any following images are shifted to fill the deleted position.

Delete decrements the value in the Count property to reflect the new length of the list.

For widgetsets that allocate a handle for its image list, the Reference class is used to call its Delete method for the specified index position.

The current implementation does not adjust the number of allocated data blocks for the resolution after an image is deleted.
Ordinal position for the image deleted in the method.
Stores raw image data for all images in the resolution to a bitmap.

GetFullRawImage is a procedure used to store raw image data for all images in the resolution to the specified raw image.

Image is the TRawImage output parameter where the raw image data is stored. GetFullRawImage calls the Init method in Image to set the default values used in the Description, Data, Mask, and Palette for the object instance.

No additional actions are performed in the method when the Count property contains 0 (zero).

GetFullRawImage calls the FillDescription method to set the TRawImageDescription values that describe the processing needed to display the raw image data. It also stores the values in the Height and Width properties to the image description data. The Data property in Image is set to a pointer to the raw image data for the resolution.

GetFullRawImage is used in the GetFullBitmap method, and in the TCustomImageList.GetFullRawImage method.

TRawImage
Raw image data for all images in the resolution.
Stores the raw image data for the resolution to a Stream.

WriteData is a procedure used to write the raw image data for all images in the resolution to the specified stream.

AStream contains the TStream class instance where raw image data is stored in the method. The current position in AStream is used when values are written in the method.

ACompress indicates if compression is applied to raw image data before it is written to the stream. When ACompress is True, a temporary TCompressionStream class instance is used to get the compressed values written to the stream. ACompress also determines the image list signature written at the start of AStream. When ACompress is False, the value in SIG_LAZ3 is written as the image list signature. When ACompressed is True, the value in SIG_LAZ4 is used.

WriteData writes a signature and header to the stream in AStream. First, the image list signature is written as described in the preceding paragraph. Second, a header is written that contains Integer values for the Count, Width, and Height properties (in that order). Finally, the raw image data is written to the stream (using optional compression when ACompress is True). The uncompressed values represent the 32-bit RGBA raw image data for the entire resolution. Raw image data is not written if the Count property contains 0 (zero).

WriteData is used in the implementation of the TCustomImageList.WriteData method.

Stream where raw image data for the resolution is stored.
Indicates if compression is applied to raw image data.
Reads raw image data from the specified Stream.

ReadData is a procedure used to read the raw image data for all images in the resolution from the specified stream.

AStream contains the TStream class instance with the raw image data read in the method. The current position in AStream is used when values are read in the method. The stream is positioned immediately after the raw image values when values are read in the method.

ReadData calls the Clear method to remove any existing image data stored in the resolution.

ReadData reads the signature for the image list from the stream. The signature identifies whether image data was written by various versions of the Lazarus or Delphi IDEs, and defines the header information expected in the stream. Methods are provided to read header and image data for the following image list signatures:

SIG_LAZ1
  Earlier versions of the Lazarus IDE
SIG_LAZ2
  Lazarus versions that included header data for each image
SIG_LAZ3
  Current Lazarus image list format using uncompressed image data
SIG_LAZ4
  Current Lazarus image list format using compression for image data
SIG_D3
  Delphi 3 image list format

If an image list signature is not found, it was created using the Delphi 2 image list format which did not include a signature. In this scenario, the stream in AStream is moved to its original position prior to reading image data from the stream.

ReadData is used in the implementation of the TCustomImageList.ReadData method.

Stream which contains the raw image data read in the method.
Gets the Handle for the Reference image list.

GetReferenceHandle is an overridden method used to get the handle for the TWSCustomImageListReference class for the widgetset. Some (all?) platforms / widgetsets require a handle when manipulating an image list. GetReferenceHandle uses the value in the Reference property to supply the value for the Handle.

Handle for the Reference class in the image list.
Creates the Reference image list using the facilities for the widgetset.
Class instance for the reference class.
Parameters used to create the reference class.
Registers the class type used to create references for the widgetset.
Notifies an image list list when the handle for the resolution is freed.

ReferenceDestroying is an overridden method used to perform a notification when the handle for the Reference class is freed. ReferenceDestroying calls the inherited method, and notifies the image list that the handle for the resolution is being freed.

Destructor for the class instance.
Get the coordinates for the HotSpot in an image in the list.

GetHotSpot is a TPoint function used to get the HotSpot for an image stored in the resolution. The HotSpot is an offset from the drawing position to the image origin. A HotSpot is used only in TDragImageList. In TCustomImageList, its position is always (0,0).

Point with the horizontal and vertical offset for the image hot spot.
Stores the image description for the raw image data for the resolution.

FillDescription is a procedure used to store descriptive information about the raw image data in the resolution. FillDescription provides metadata about the image, similar to the metadata in TIFF (Tagged Image File Format). It provides information needed to process and render images from their raw image data.

ADesc is the TRawImageDescription output parameter where the information is stored in the method. FillDescription calls the Init method in ADesc to reset the values in the class instance to their defaults.

FillDescription sets the value for the following properties in ADesc:

Format
  ricfRGBA
PaletteColorCount
  0
MaskBitsPerPixel
  0
Depth
  32
Width
  Value stored in the Width property
Height
  Value stored in the Height property
BitOrder
  riboBitsInOrder
ByteOrder
  riboMSBFirst
LineOrder
  riloTopToBottom
BitsPerPixel
  32
LineEnd
  rileDWordBoundary
RedPrec
  8
RedShift
  8
GreenPrec
  8
GreenShift
  16
BluePrec
  8
BlueShift
  24
AlphaPrec
  8
AlphaShift
  0

FillDescription is used in the implementation of the GetFullRawImage and GetRawImage methods.

TRawImageDescription
Stores values updated in the method.
Gets the bitmap for an image drawn using the specified drawing effect.

GetBitmap is an overloaded procedure used to a bitmap for the specified image in the resolution.

Index contains the ordinal position for the image requested in the method.

Image is the TCustomBitmap class instance where the bitmap for the image is stored.

AEffect contains a value from the TGraphicsDrawEffect enumeration that indicates a drawing effect applied to the raw image data, and stored in the bitmap. Values in AEffect determine whether the image is rendered normally, as a disabled (or grayed) image, highlighted, shadowed, or as a monochrome bitmap mask.

GetBitmap creates a temporary TRawImage class instance that is used to get the 32-bit RGBA raw image data, and to apply the drawing effect in AEffect. For platforms or widgetsets that do not support 32-bit image data, a device image is used to get the pixel content for the image.

An overloaded variant of the method is provided which omits the drawing effect argument, and assumes the image is rendered in the "normal" display state.

No actions are performed in the method when Index contains an invalid position in the list of images, or when Image has not been assigned (contains Nil).

Ordinal position for the image in the list.
Bitmap updated in the method.
Drawing effect applied to the bitmap.
Gets an Icon rendered using the specified drawing effect.

GetIcon is an overloaded procedure used to get an image in TIcon format stored at the specified position in the resolution.

Index contains the ordinal position of the image retrieved in the method.

Image is a TIcon class instance where image data is stored in the method.

AEffect contains a value from the TGraphicsDrawEffect enumeration that indicates a drawing effect applied to the raw image data, and stored in the icon. Values in AEffect determine whether the image is rendered normally, as a disabled (or grayed) image, highlighted, shadowed, or as a monochrome bitmap mask.

GetIcon creates a temporary TRawImage class instance that is used to get the 32-bit RGBA raw image data, and to apply the drawing effect in AEffect. For platforms or widgetsets that do not support 32-bit image data, a device image is used to get the pixel content for the image.

An overloaded variant of the method is provided which omits the drawing effect argument, and assumes the image is rendered in the "normal" display state.

No actions are performed in the method when Count contains 0 (zero), or when Image has not been assigned (contains Nil).

Ordinal position for the image requested in the method.
TIcon class where the image data is stored.
Drawing effect applied to the rendered image.
Gets a bitmap representing all images in the resolution.

GetFullBitmap is a procedure used to get a bitmap that contains all of the images stored in the resolution.

Image is a TCustomBitmap descendant where image data is stored in the method.

AEffect contains a value from the TGraphicsDrawEffect enumeration that indicates a drawing effect applied to the raw image data, and stored in the bitmap. Values in AEffect determine whether the images are rendered normally, as a disabled (or grayed) image, highlighted, shadowed, or as a monochrome bitmap mask.

GetFullBitmap creates a temporary TRawImage class instance that is used to get the 32-bit RGBA raw image data, and to apply the drawing effect in AEffect. For platforms or widgetsets that do not support 32-bit image data, a device image is used to get the pixel content for the image.

The vertical size in Image is determined by the Height property. The horizontal size in Image is set to Width * Count.

No actions are performed in the method when Count contains 0 (zero), or Image has not been assigned (contains Nil).

Bitmap image with the combined images for the resolution.
Drawing effect applied to images and stored in the bitmap.
Gets the 32-bit RGBA raw image data for the specified image.

GetRawImage is a procedure used to get the 32-bit RGBA raw image data for the specified image in the resolution.

Index is the ordinal position for the image in the list.

Image is a TRawImage class instance used to store the raw image data for the specified image.

GetRawImage calls CheckIndex to ensure that Index contains a valid position in the image resolution. An exception is raised in CheckIndex if the requested position is invalid. No actions are performed in the method when Count contains 0 (zero).

GetRawImage stores image metadata in Image by calling the FillDescription method. The 32-bit RGBA raw image data at the specified Index in the resolution is stored in Image. Its DataSize property is updated to reflect the number of pixels (Width * Height * 32b) stored in the class instance.

GetRawImage is used in the implementation of the GetBitmap, GetFullBitmap, GetIcon, and ReadData methods. It is also used in the AddImages and GetRawImage methods in TCustomImageList.

Ordinal position for the image in the list.
TRawImage instance where image data is stored in the method.
Renders an image to the specified canvas.

Draw is an overloaded method used to render an image to the specified canvas. Overloaded variants allow the use of a drawing effect or style for the rendered image.

ACanvas contains the TCanvas instance used to render the requested image.

AX and AY contain Integer values representing the horizontal and vertical offsets from the canvas origin where the image is drawn.

AIndex contains the ordinal position for the requested image in the resolution.

AEnabled indicates if the image is drawn in the enabled state. When AEnabled is False, the gdeDisabled drawing effect is used to render the image to the canvas.

ADrawEffect is a value from the TGraphicsDrawEffect enumeration that indicates the drawing effect applied to the raw image data, and stored in the bitmap. Values in AEffect determine whether the image is rendered normally, as a disabled (or grayed) image, highlighted, shadowed, or as a monochrome bitmap mask.

ADrawingStyle contains a value from the TDrawingStyle enumeration that indicates the image list drawing style used for the rendered image. ADrawingStyle determines how the image is blended with its background color when a mask is used in the image. It has no significance when a mask is not present in the image.

AImageType contains a value from the TImageType enumeration, and indicates whether the image uses a mask.

The Draw method requires a valid TWSCustomImageListReference class instance to access the handle for its image list. The widgetset class is used to call its Draw method using the specified parameter values as arguments. The values in the BkColor and BlendColor properties for the ImageList are also passed in the arguments to the widgetset class.

No actions are performed in the method when AIndex contains a value that is an invalid position for the images in the resolution.

Canvas where the image is drawn.
Horizontal offset for the image on the canvas.
Vertical offset for the image on the canvas.
Position of the image drawn in the method.
Indicates if the image is drawn in an Enabled state.
Drawing effect applied to the rendered image.
Drawing style applied to the rendered image.
Indicates if the image contains a mask or source data.
Draws an image stretched to the dimensions for the target rectangle.

StretchDraw is a procedure used to render an image stretched to the required dimensions on the specified canvas.

Canvas is the TCanvas instance where the image is rendered using the dimensions in the target rectangle.

Index contains the ordinal position for the image drawn in the method.

ARect is a TRect instance that contains the Top, Left, Bottom, and Right coordinates for the canvas. The rendered image must fit with in these boundaries on the canvas.

Enabled indicates if the image is drawn using its "enabled" state. When Enabled is True, the gdeEnabled drawing effect is used for the rendered image. When Enabled is False, the gdeDisabled drawing effect is used.

StretchDraw compares the image size (using the Height and Width properties) to the size of the target rectangle in ARect. When they are the same size, the Draw method is used to render the specified image. When the sizes are different, the StretchDraw method in ACanvas is used to render the image bitmap expanded or contracted to fit within the specified boundaries.

StretchDraw is used in the implementation of the Draw and DrawOverlay methods in TScaledImageListResolution.

Canvas used for the drawing operation.
Ordinal position for the image drawn in the method.
Rectangle coordinates used for the draw operation.
Indicates if the image is drawn using the enabled display state.
Draws the specified image with the given overlay.

DrawOverlay is an overloaded procedure used to draw the specified image with an overlay. An overlay is an masked image drawn transparently over another image. The overlay image is generally used to convey state or status information about the image it adorns. The overlay images are stored in the image list resolution just like the images they decorate.

ACanvas is the TCanvas instance where the image and the overlay are rendered.

AX and AY contain the canvas offsets (horizontal and vertical) where the overlay image is drawn.

AIndex contains the ordinal position for the base image drawn in the method.

AOverlay contains the position where the index for an overlay image was stored using Overlay. The value in AOverlay must be in the range 0..14 (the range defined in TOverlay).

ADrawingStyle contains the TDrawingStyle enumeration value applied to the rendered image.

AImageType contains a TImageType enumeration value that indicates if the content is an image or contains a mask.

ADrawEffect contains a TGraphicsDrawEffect enumeration value that indicates the drawing effect applied to the rendered image.

Overloaded variants of the method are provided which use the BlendColor, BkColor, DrawingStyle, and ImageType properties in ImageList as default values in the methods.

No actions are performed in the method when AIndex does not contain a valid index position in the resolution.

DrawOverlay requires a valid Reference instance to access the handles used for the image list and the resolution. The reference class calls its Draw method to render the base image represented by the value in AIndex to the specified canvas. Arguments passed to the method determine the drawing style or drawing effect applied to the rendered image.

The reference class is also used to render an overlay image indicated by the AOverlay parameter. The overlay image is drawn to the canvas at the offsets in AX and AY using the Width and Height for images in the resolution. The overlay image is not drawn if AOverlay contains a value outside the range allowed in TOverlay, or does not map to a valid image index in the image list.

Canvas where the image and its overlay are rendered.
Horizontal offset for the overlay image.
Vertical offset for the overlay image.
Ordinal position for the base image drawn in the method.
Position in the internal array with the index for an overlay image.
Indicates if the image is drawn in the enabled state.
Drawing effect applied to the image and its overlay.
Drawing style applied to the image and its overlay.
Image type for the requested image.
Image list which owns the resolution.

ImageList is a read-only TCustomImageList property that represents the image list which owns the resolution. The value in the ImageList property is provided as an argument to the Create constructor.

ImageList allows the image resolution to have access to the properties and methods in TCustomImageList in the implementation of its methods.

Width of the images stored in the resolution.

Width is a read-only Integer property that indicates the width of images stored in the resolution. Width is used along with Height and Count to determine the internal storage allocated for 32-bit RGBA raw image data in the resolution.

The value in Width is assigned when raw image data is loaded using the ReadData method, or when an image resolution is dynamically created when reading the Resolution property or using the GetResolution method in ImageList.

Use Height to get the vertical size of the images stored in the resolution. Use Count to determine the number of images stored in the resolution.

Height of the images stored in the resolution.

Height is a read-only Integer property that indicates the height of images stored in the resolution. Height is used along with Width and Count to determine the internal storage allocated for 32-bit RGBA raw image data in the resolution.

The value in Height is assigned when raw image data is loaded using the ReadData method, or when an image resolution is dynamically created using the Resolution property or the GetResolution method in ImageList.

Use Width to get the horizontal size of the images stored in the resolution. Use Count to determine the number of images stored in the resolution.

Number of images stored in the resolution.

Count is a read-only Integer property that indicates the number of images stored in the resolution. Count is used along with Width and Height to determine the storage allocated for 32-bit RGBA raw image data in the resolution.

The value in Count is updated when raw image data is loaded using the ReadData method, and when the images in the resolution are updated using the Add, Delete, or Clear methods.

Count determines the upper boundary for index positions used to access bitmaps, icons, or raw images in the resolution (Count - 1). The lower boundary is always 0 (zero).

Indicates if the Resolution was auto-created at design-time.

AutoCreatedInDesignTime is a Boolean property which indicates if the image resolution was automatically created at design-time. The value in AutoCreatedInDesignTime is set to True when the Lazarus IDE creates an image resolution in its ImageListEditor dialog using the Resolutions container for the ImageList. It is set to False when the TCustomImageList.RegisterResolutions method is called at run-time.

AutoCreatedInDesignTime is used in the TCustomImageList.DefineProperties method to determine the values read and written using the LCL component streaming mechanism.

Reference to the widgetset image list using this resolution.

Reference is a read-only TWSCustomImageListReference property that represents the reference class for an image list implementation in the current widgetset. Reading the value in the property causes the reference class for the resolution to be created if it has not already been allocated.

Reference is used get access to the handle for the image list used in the resolution. The handle is a required argument in TWSCustomImageListResolutionClass methods.

Implements a scaled image resolution (size).

TScaledImageListResolution is a record type that represents a scaled image resolution created in TCustomImageList. TScaledImageListResolution contains images dynamically scaled from a source image Resolution using a scaling factor.

TScaledImageListResolution contains methods and properties that mirror those available in TCustomImageListResolution. This allows TCustomImageList to use the methods and properties in TCustomImageListResolution when working with the dynamically scaled image content. Methods like Draw, DrawOverlay, and StretchDraw are redirected to the corresponding method in Resolution.

TScaledImageListResolution is transient in nature; it is not stored as part of an image list or its static resolutions.

TScaledImageListResolution is used in the implementation of the GetResolutionForPPI and DrawForPPI methods in TCustomImageList.

Gets the value for the Count property.
Value for the Count property.
Gets the value for the Size property.
Value for the Size property.
Gets the value for the Valid property.
Value for the the Valid property.
Allocates a new record instance.

Create is a class function used to allocate a new TScaledImageListResolution record instance using the specified image resolution and scaling factor. The return value is the TScaledImageListResolution record instance allocated in the class function.

AResolution contains the TCustomImageListResolution instance with image data used as the source for the scaled images. AResolution is stored in the Resolution property to provide access to its properties and methods in the scaled image resolution.

AScaleFactor is a Double value that contains the scaling factor applied to the source images in Resolution.

Create sets the value in the Width and Height properties to the scaled sizes from the Resolution; i. e. (Resolution.Width / AScaleFactor) and (Resolution.Height / AScaleFactor). If Resolution has not been assigned (contains Nil), the value in both Height and Width are set to 0 (zero).

Record instance allocated in the class function.
Resolution used as the basis for the scaled images.
Scale factor applied to the scaled images.
Gets the scaled bitmap for the specified image.
Ordinal position for the bitmap requested in the method.
Bitmap used to store the requested image.
Drawing effect applied to the image.
Draws the scaled image to the specified canvas.
Canvas used to render the image.
Horizontal canvas offset for the rendered image.
Vertical canvas offset for the rendered image.
Ordinal position for the image rendered in the method.
Indicates if the image is drawn in the enabled state.
Drawing effect applied to the rendered image.
Drawing style applied to the rendered image.
Image type for the rendered image.
Draws the scaled image sized to the target rectangle.
Draws an image with an overlay at the specified canvas position.

DrawOverlay is an overloaded method used to draw an image with an overlay at the given position on a canvas. The overloaded variants allow the enabled state, drawing effect, or drawing style for the image(s) to be specified.

DrawOverlay scales both the image and the overlay (when needed) using the internal scaling factor stored in the image Resolution.

Image scaling is not performed when the scaling factor is 1.0. In this case the Draw method in Resolution is called to draw the image. When a valid image index has been assigned in AOverlay, The Draw method is called to draw the overlay image.

When image scaling is needed, the StretchDraw method in Resolution is called to draw both the image and a valid overlay. The images are resized to the Width and Height for the image Resolution. StretchDraw uses the enabled state for the images when ADrawEffect contains any value other than gdeDisabled.

Use the Draw or StretchDraw methods when an overlay image is not needed.

Canvas where the image and overlay are drawn.
Horizontal coordinate on the canvas where the image is drawn.
Vertical coordinate on the canvas where the image is drawn.
Ordinal position for the image drawn in the method.
Position for the overlay image applied in the method.
True when the image is drawn in the enabled state (default).
TGraphicsDrawEffect value applied to the image.
TDrawingStyle value applied to the image.
Indicates if the content is the image or a mask.
Width of the images stored in the scaled image resolution.
Height of the images stored in the scaled image resolution.
Size of an image stored in the scaled resolution.
Resolution used as the bases for scaled images.
Number of images stored in the scaled image list.
Indicates if the source resolution is assigned for the class instance.

Valid is a read-only Boolean property that indicates if the source image resolution for the class instance has been assigned. Valid ensures that the TCustomImageListResolution instance passed to the class constructor contains an assigned class instance and not the value Nil.

Class type used to create instances of TCustomImageListResolution.
Provides multiple image resolutions in TCustomImageList.

TCustomImageListResolutions is a class used to implement support for multiple image sizes (or resolutions) in TCustomImageList. TCustomImageListResolutions maintains an internal list with TCustomImageListResolution class instances representing each of the image sizes (and the raw image data for the size) available in the TCustomImageList instance. In essence, it allows TCustomImageList to treat each image resolution as a distinct parallel image list.

The ImageLists property provides access to the image list for a specific image width (or resolution), and performs image scaling when needed. New image resolutions are dynamically created and added to the container when a size is requested that is not already present.

Use the Items property to access the TCustomImageListResolution class instances stored in the container. Use the Count property to determine the number of image resolutions stored in the container. Use the Clear and Delete methods to maintain image resolutions in the container.

TCustomImageListResolutions is used in the implementation of TCustomImageList.

Checks for an existing image resolution in the Items property.

Find is a Boolean function used to locate an image resolution in the container using the specified image width. Find performs a binary (or half-interval) search of the image resolutions in the Items property, and compares the value specified in AImageWidthWidth to the Width property for the image resolutions. The search is halted when an image resolution is found using the value in AImageWidth.

The return Value is True when an image resolution is located with the value specified in AImageWidth. The return value is False if an image resolution is not found using the specified image width.

Index is an output parameter used to store the ordinal position of the image resolution that uses the specified image width. Index contains the closest (but larger) resolution when the return value is False.

True when the image resolution exists in the Items property.
Image width desired from the Items property.
Ordinal position for the image resolution in the Items property.
Gets the value for the Image Lists property.

GetImageLists is an overloaded TCustomImageListResolution function. The variant with only an image width argument is used to get the value for the indexed ImageLists property. The other variant is called from the read access specifier.

The return value contains the TCustomImageListResolution class instance which represents images with the specified width. If an image resolution with the requested size does not already exist, it is created and populated with resized images for the resolution.

Use the ImageLists property to access a specific image resolution available in the container. Use the Items property to access existing resolutions by their ordinal position in the container.

Value for the ImageLists property.
Image width desired in the image list.
Indicates if a missing resolution can be scaled from another resolution.
Indicates if the image resolution was auto-created at design-time.
Gets the value for the indexed Items property.
Value for the Items property.
Ordinal position for the requested item.
Gets the value for the Count property.
Value for the Count property.
Finds the resolution that is the best candidate for scaling to the target width.

FindBestToCopyFrom is an Integer function used to find the image resolution that is the best candidate for scaling images to the specified target width. The return value contains the ordinal position for the image resolution selected for the value in ATargetWidth.

AIgnoreIndex contains the ordinal position for an image resolution that can be disregarded when comparing image widths in the container.

FindBestToCopyFrom looks for an image resolution that contains image widths that are the next size larger than the value in ATargetWidth. The premise is that images that are scaled down contain fewer artifacts than those that are scaled up. When no image resolution is found using larger image widths, the last item in the container is used as the candidate image resolution.

FindBestToCopyFrom is used in the implementation of the FindBestToScaleFrom method.

Ordinal position of the image resolution selected in the method.
Image width desired in the resolution.
Ordinal position of an image resolution ignored in the method.
Constructor for the class instance.

Create is the constructor for the class instance. Create calls the inherited constructor. Create allocates resources needed for the internal object list which stores the image resolutions in the container. Create sets the value for the ImageList property to AImageList. Create stores the class type in AResolutionClass to an internal member used in the container.

Image list that owns the container.
Class type used to create resolution class instances in the container.
Destructor for the class instance.

Destroy is the destructor for the class instance. Destroy frees resources allocated to the internal list used to store image resolutions in the container. Destroy calls the inherited destructor prior to exiting from the method.

Finds the image resolution with the best size for scaling to the target width.

FindBestToScaleFrom is an Integer function used to find the image resolution that is the best candidate for scaling images to the specified target width.

ATargetWidth contains the image width to locate in the resolutions stored in the container.

The return value contains the ordinal position for the image resolution selected as the source for images.

FindBestToScaleFrom calls the Find method to locate an existing image resolution that matches the value in ATargetWidth. If an existing image resolution is not found that uses the image width in ATargetWidth, the FindBestToCopyFrom method is called to search all resolutions for the best candidate for the target image width.

FindBestToScaleFrom is used in the implementation of the StretchDraw method in TCustomImageList.

Source image resolution to use for scaling to the target width.
Target width for the scaled image resolution.
Deletes the image resolution stored at the specified position in the container.

Delete is a procedure used to remove the image resolution stored at the specified position in the container. Delete calls the Delete method in the internal TObjectList member which stores the image resolutions for the container.

AIndex contains the ordinal position of the object instance deleted in the method.

Use the Clear method to remove all image resolutions stored in the container.

Ordinal position of the image resolution to delete from the container.
Clears all image resolutions stored in the container.

Clear is a procedure used to remove all image resolutions stored in the container. Clear calls the Clear method in the internal TObjectList member which stores the image resolutions in the container.

Use the Delete method to remove an image resolution stored at a specific position in the container.

Provides access to an image list which uses the specified image width.

ImageLists is a read-only indexed TCustomImageListResolution property which provides access to the image resolution which uses the image width in AImageWidth.

GetImageLists is the read access specifier for the property value. An overloaded variant of the method is used to Find an existing image resolution that uses the requested image size. If an image resolution with the requested size does not already exist, a new resolution class instance is created and populated with images scaled to the required size. The new image resolution is inserted in the container at the position where the image size should be located. This ensures that the image resolutions are ordered in ascending image size order as expected in TCustomImageList methods.

Use the Items property to access existing resolutions by their ordinal position in the container.

Image list with images using the specified width.
Image width requested in the image list.
Provides indexed access to existing image resolutions in the container.

Items is an indexed read-only TCustomImageListResolution property which provides access to existing image resolutions in the container. The TCustomImageListResolution instances in the Items property are stored in an internal TObjectList member, and retrieved in the read access specifier.

AIndex contains the ordinal position in the container for the requested image resolution.

Items is the default property for the container.

Use the ImageLists property to access or create an image resolution using a specified image width.

The image resolution class instance at the specified position.
Ordinal position for the requested image resolution.
Number of image resolutions stored in the container.

Count is a read-only Integer property that indicates the number of image resolutions stored in the container. Count returns the number of items in the internal TObjectList member which stores the image resolutions for the container.

Count determines the upper range boundary (Count - 1) available when accessing the image resolutions in the container. The lower range boundary is always 0 (zero).

Implements an enumerator for image resolutions in TCustomImageList.

TCustomImageListResolutionEnumerator is a class which implements an enumerator for image resolutions in TCustomImageList. Methods and properties are provided to implement the IEnumerator interface for TCustomImageListResolution class instances.

TCustomImageListResolutionEnumerator includes a an internal TCustomImageList member which represents the image list for the enumerator class instance. The constructor for the class includes an argument that determines whether enumerator navigation is performed in ascending or descending order.

TCustomImageListResolutionEnumerator is the type returned from the Resolutions and ResolutionsDesc methods in TCustomImageList.

Gets the value for the Current property.
Value for the Current property.
Gets the enumerator for the class instance.

GetEnumerator is a TCustomImageListResolutionEnumerator function used to get the enumerator for image resolutions in an image list. GetEnumerator implements the method defined in the IEnumerator interface. GetEnumerator provides access to the TCustomImageListResolution classes stored in a TCustomImageList class instance.

Use MoveNext to navigate to each image resolution for the enumerator.

Use Current to access the current image resolution in the enumerator.

Enumerator for the image resolutions in the image list.
Constructor for the class instance.

Create is the constructor for the class instance. Create calls the inherited constructor.

AImgList contains the TCustomImageList instance which contains the image resolutions visited in the enumerator.

ADesc determines the navigation order for image resolutions in the enumerator. When ADesc is True, the enumerator is navigated in reverse (descending) order for the image resolutions. When ADesc is False, the enumerator is navigated in ascending image size order.

Create sets the initial value in the Current property to reflect the navigation order specified in ADesc. The initial value indicates that Current is positioned just prior to the first item for the navigation order; TCustomImageListResolutions.Count for descending navigation order, -1 for ascending navigation order.

Use MoveNext to navigate to the first and subsequent image resolution for the enumerator.

Use Current to access the current image resolution in the enumerator.

Image list that owns the image resolutions in the enumerator.
Indicates if the enumerator navigates in descending order.
Moves to the next image resolution for the enumerator.

MoveNext is a Boolean function used to move to the next image resolution in the navigation order for the enumerator. MoveNext implements the method defined in the IEnumerator interface.

MoveNext uses the navigation order specified in the Create method to determine the index position for the next image resolution accessed in the enumerator. When reverse order was specified, the value in Current is decremented. When ascending order was specified, the value in Current is incremented.

The return value for the method is True when the new value for Current is a valid index position for the specified navigation order (in the range 0..Count-1).

True when another image resolution is available in the enumerator.
The current image resolution for the enumerator.

Current is a read-only TCustomImageListResolution property that represents the current image resolution for the enumerator. Current implements the property defined in the IEnumerator interface.

Image resolutions are read from the image list passed as an argument to the constructor. An internal member is used to track the index position for the current image resolution. Use the MoveNext method to get the next index position used in the enumerator.

Specifies an event handler used to get image widths for a display density (PPI).

TCustomImageListGetWidthForPPI is an object procedure which specifies an event handler used to get image widths for a specific display density (PPI). TCustomImageListGetWidthForPPI allows an application to override the value returned in the WidthForPPI property (or when calling the GetWidthForPPI method) in TCustomImageList.

Sender contains the TCustomImageList instance triggering the event notification.

AImageWidth contains the image width used as the basis for the calculation.

APPI contains the display density (Pixels per Inch) for the derived image width.

AResultWidth is a variable parameter used to store the image width derived in the event handler for the specified display density.

TCustomImageListGetWidthForPPI is the type used to implement the OnGetWidthForPPI property in TCustomImageList.

Image list generating the event notification.
Initial image width used in the event handler.
Display density (Pixels per Inch).
Imaged width calculated in the event handler for the display density.
The base class for TImageList.

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 1versions 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.
Stores the TCustomImageListResolutions container used in the image list.
List of TChangeLinks which are notified of changes.
Used to remember changes that occur while update notifications are locked (FUpdateCount > 0).
Counter for BeginUpdate/EndUpdate method calls.
Notifies all subscribed objects of a change in the image list.
Sets the value for the BkColor property.
New value for the BkColor property.
Sets the value for the DrawingStyle property.
New value for the DrawingStyle property.
Sets the value for the Height property.
New value for the Height property.
Sets the value for the Masked property.
New value for the Masked property.
Sets the value for the ShareImages property.
New value for the ShareImages property.
Sets the value for the Width property.
New value for the Width property.
Gets the value for the Reference property.
Value for the Reference property.
Gets an image list with images resized for the specified display density.

GetResolutionForPPI is a TScaledImageListResolution function used to get an image list with images suitable for use at the specified display density (PPI).

AImageWidth is the width of the images used as the source for the resized images. AImageWidth determines the Resolution selected as the source image list.

APPI indicates the display density (pixels per inch) for the resized images.

ACanvasScaleFactor contains the value used to adjust the image sizes when Scaled is set to True. The value in ACanvasScaleFactor is not used when Scaled is set to False.

The return value is a TScaledImageListResolution class instance that contains images resized using the constraints in the parameter values.

GetResolutionForPPI calls GetWidthForPPI to calculate the image width used at the target PPI value. When Scaled is True, ACanvasScaleFactor is used as a multiplier for the APPI value. When Scaled is False, the value 1.0 is used as the multiplier. GetResolutionForPPI calls GetResolution to retrieve the image list passed to the constructor for the TScaledImageListResolution class.

GetResolutionForPPI is used in the implementation of the DrawForPPI method.

Image list with the resized images.
Image width for source images in the operation.
Display density (pixels per inch) for the resized images.
Scaling factor used for the target canvas.
Gets the value for the WidthForPPI property.
Image width derived for the specified display density.
Initial image width used in the method.
Display density (PPI) for the calculation.
Gets the value for the HeightForPPI property.
Image height derived for the specified display density.
Image width used to derive the value.
Display density (PPI) used in the calculation.
Gets the height for images using the specified width.

GetHeightForWidth is an Integer function used to get the vertical size for images using the image width specified in AWidth. When AWidth contains a non-zero value, it is used to calculate the proportional image height using the values in the Height and Width properties.

The return value contains the image height required for the specified image width, or 0 (zero) when AWidth contain 0 (zero).

GetHeightForWidth is used in the implementation of the GetHeightForPPI method, and in the GetImageLists method in TCustomImageListResolutions.

Image height calculated for the specified image width.
Image width used to derive the proportional image height.
Gets the value for the Count property.
Value for the Count property.
Gets the image size for the specified image width and display density (PPI).

GetSizeForPPI is a TSize function used to get the image size for the specified image width and display density (PPI).

AImageWidth contains the initial image width used to calculate the proportional image width and height for a given display density.

APPI contains the display density (Pixels per Inch) to use in the sizing calculation.

GetSizeForPPI calls the GetWidthForPPI method to get the image width used for the specified display density. The GetResolution method is called to get the image resolution with images using the derived image width.

The return value is a TSize type where the calculated image width and height for the display density are stored in the cx and cy members (respectively).

GetSizeForPPI is the read access specifier for the SizeForPPI property.

The calculated size for images at the specified display density.
Image width used as the basis for the calculated image size.
Display density (PPI) for the calculated image size.
Gets the index position for an icon with a suitable size.

GetBestIconIndexForSize is an Integer function used to locate the index position for an icon with the size specified in AWidth. If an exact match is not found for the specified width, the next largest value in AIcon is used. If an icon size larger than AWidth is not found, the largest icon size available is used.

The return value contains the ordinal position for the icon size selected in the method.

This methods requires the icons in AIcon to be sorted in ascending icon size order. The selection logic will fail if the icon sizes are not sorted.

GetBestIconIndexForSize is used in the implementation of the InsertIcon and ReplaceIcon methods.

Position of the candidate icon.
Icon examined in the method.
Icon width requested in the method.
Gets the value for the ResolutionByIndex property.
Value for the ResolutionByIndex property.
Index position for the requested image resolution.
Gets the value for the ResolutionCount property.
Value for the ResolutionCount property.
Creates the default resolution (size) for the image list.

CreateDefaultResolution is a procedure used to create the default image resolution (or size) used in the image list. CreateDefaultResolution ensures that at least one TCustomImageListResolution instance has been created in the resolutions for the image list. The Resolution uses the value in the Width property as its image width.

CreateDefaultResolution uses the value in the ResolutionCount property to determine if the default resolution already exists in the image list. When ResolutionCount contains 0 (zero), the GetResolution method is called using the value in Width to automatically create the default image resolution.

CreateDefaultResolution is used in the implementation of methods including:

- AddMultipleResolutions
- AddSlice
- AddSliced
- Insert
- InsertIcon
- InsertMasked

Performs actions when the reference class for a resolution is freed.

DoDestroyResolutionReference is a procedure used to perform actions needed when the reference class for an image resolution is freed. DoDestroyResolutionReference ensures that objects which have subscribed to change notifications for the image list are notified when the reference class (and its handle) are freed.

DoDestroyResolutionReference calls the DoDestroyResolutionReference method in each of the TChangeLink instances added using the RegisterChanges method. Use UnRegisterChanges to unsubscribe an image list from the change notifications.

Image width for the resolution being freed.
Reference class for the resolution being freed.
Gets the value for the indexed Resolution property.

GetResolution is a TCustomImageListResolution function used to get the image resolution which uses the image width specified in AImageWidth. When AImageWidth contains 0 (zero) or a negative value, the value in the Width property is used in the argument.

GetResolution uses the internal TCustomImageListResolutions member in the class to access its ImageLists property. If an image list using the request image width does not exist, it is created and populated by copying the images from the best candidate resolution.

GetResolution is used as the read access specifier for the indexed Resolution property.

Value for the Resolution property.
Image width for the requested resolution.
Gets the class type used to create image resolutions in the list.

GetResolutionClass is a TCustomImageListResolutionClass function which gets the class type used to create image resolutions in the image list. GetResolutionClass always returns the TCustomImageListResolution type in TCustomImageList.

GetResolutionClass is used to get the class type for items added to the TCustomImageListResolutions container, and passed as an argument when the container is created in the Initialize method.

Class type used to create resolutions in the image list.
Ensures that an Index position is valid for the bounds of the image list.

CheckIndex is a procedure used to ensure that the value in AValue is a valid index position for the operations in the class.

AForInsert indicates if AValue is constrained to the existing range of ordinal positions in the list. When AForInsert contains True, AValue must be less than the Count property. When AForInsert is False, the index value is for an append operation and can contain a value less than or equal to the Count property.

An EInvalidOperation exception is raised when AValue is not in the required range for the specified operation.

CheckIndex is used in the implementation of various methods in the class.

Raises an EInvalidOperation exception when the index is out of bounds. Raised with the message in SInvalidIndex.
Index position validated in the method.
True when the index position is used for insertion (default is False).
Performs the initial set up for the image list.

Initialize is a procedure used to perform the in ital set up for the image list. Initialize creates the internal TCustomImageListResolutions class instance used to store image resolutions in the image list. The internal list used for TChangeLink notifications is also created. The internal allocation block count is set to 4.

Initialize sets the default values for the following properties:

BlendColor
  clNone
BkColor
  clNone
DrawingStyle
  dsNormal

The ClearOverlays method is called to reset any images assigned as overlay images in the image list.

Initialize is used in the Create and CreateSize constructors. Create sets the default values for the Height and Width properties to 16. CreateSize uses the arguments passed to the constructor as the value for the properties.

Initialize raises an EInvalidOperation exception if the value in the Height or Width property is invalid. Height must be in the range 1..32768, and Width must be a positive non-zero Integer value. Raised with the message in SInvalidImageSize.

Defines properties used in the LCL component streaming mechanism.

DefineProperties is an overridden method used to defined which unpublished properties in TCustomImageList are included in the LCL component streaming mechanism.

Filer is the TFiler class instance used to read and write the component during component streaming. DefineProperties defines the following properties for use during component streaming:

Property Name | Property Type | Description
Bitmap | Binary | Written when Count is non-zero
BitmapAdv | Binary | Written when a resolution exists that was explicitly created at design-time

TFiler class used to read and write the component.
Sets the Width and Height for images in the default resolution.

SetWidthHeight is a a procedure used to set the values in the Width and Height properties to the values in the NewWidth and NewHeight parameters. Width and Height establish the default resolution (or image size) used in the image list. Changing either of the values in the method causes the image list, its Resolutions, and assigned Overlay images to be discarded by calling the Clear method.

Set the values in the Height and Width properties prior to adding images to the image list. Or, use the CreateSize constructor to specify the default resolution when the image list is created.

SetWidthHeight is used in the implementation of the Assign, SetHeight, and SetWidth methods.

New value for the Width property.
New value for the Height property.
Clears images indexes assigned as overlay images in the image list.

ClearOverlays is a procedure used to reset the image indexes assigned in the internal array for use as an overlay images. ClearOverlays sets each TOverlay index position to the value -1 to indicate that it does not point to an overlay image in the image list.

ClearOverlays is used in the implementation of the Clear and Initialize methods.

Constructor for the class instance.

Create is the constructor for the class instance. Create calls the inherited constructor, and sets the default values for the following properties:

Height
  16 (pixels)
Width
  16 (pixels)

Create calls the Initialize method to allocate resources and to set the default value for properties used in the image list.

Use the alternate CreateSize constructor to create an image list using specific values in its Width and Height properties.

Owner of the class instance.
Initializes the image list using the specified height and width.

CreateSize is an alternate constructor for the class instance. CreateSize calls the inherited constructor. CreateSize sets the image size used in the default resolution to the values specified in the AWidth and AHeight parameters.

Create calls the Initialize method to allocate resources and to set the default value for properties used in the image list.

Please note: CreateSize does not assign a value for the Owner property; it will not receive Notify events when the Application, Form, or Component where it is used is freed.
The width of images in the default resolution.
The height of images in the default resolution.
Destructor for the class instance.

Destroy is the overridden destructor for the class instance. Destroy ensures that resources allocated to the internal TCustomImageListResolutions instance in the class are freed, and calls the inherited destructor. Destroy calls UnRegisterChanges to remove the TChangeLink items in the internal list of change links for the class, and frees resources allocated to the list.

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

ScaleImage is an overloaded class procedure used to scale an image and its optional mask to the specified target size.

ABitmap is the TCustomBitmap with the original image scaled in the method.

AMask is the optional mask that defines the transparent areas in ABitmap. When AMask is a valid TCustomBitmap instance, the handle to its bitmap is used in the scaling operation. When AMask has not been assigned (contains Nil), the handle to the mask in ABitmap is used for the transparent areas in the image.

TargetWidth and TargetHeight contain the size requested for the scaled image.

AData is a variable TRGBAQuadArray parameter where the 32-bit RGBA raw image data for the scaled image is stored.

An overloaded variant of the method provides the SourceRect parameter which defines the area in ABitmap that is scaled in the method.

ScaleImage sets the size of AData to the number of bytes needed for the target image size (TargetHeight * TargetWidth * 32).

ScaleImage tries to load a bitmap that uses the image and mask specified in ABitmap and AMask. If they cannot be combined and loaded, no additional actions are performed in method. If they are loaded successfully, their pixel data is examined and used to set the alpha channel and transparency for each pixel. The adjusted image is rendered for the target image size using TFPImageCanvas. The pixel data for the rendered image is stored in AData using the RGBA attributes for the scaled image.

ScaleImage is used in the implementation of several methods, including:

- TCustomImageList.AddMultipleResolutions
- TCustomImageList.AddSlice
- TCustomImageList.AddSliced
- TCustomImageList.Insert
- TCustomImageList.InsertIcon
- TCustomImageList.InsertMasked
- TCustomImageList.Replace
- TCustomImageList.ReplaceIcon
- TCustomImageList.ReplaceMasked
- TCustomImageListResolution.Add
- TCustomImageListResolution.AddImages

Bitmap with the image scaled in the method.
Optional mask that defines the transparent areas of the image.
Target width for the scaled image.
Target Height for the scaled image.
32-bit RGBA raw image data for the scaled image.
Defines the area in the original image scaled in the method.
Assigns properties in an image list to another instance of the class.

AssignTo is an overridden method which allows assigning properties in the image list to another instance of the class. AssignTo re-implements the method defined in TPersistent to include the properties available in TCustomImageList.

Dest is the persistent object where properties values from the current class instance are stored.

AssignTo checks the Dest argument to ensure that its is a TCustomImageList descendant. When it is derived from TCustomImageList, its Assign method is used to store the values in the current object instance. If it is not a TCustomImageList descendant, the inherited AssignTo method is called using Dest as an argument.

Image list to receive the values for the class instance.
Stores properties from the specified image list to the current class instance.

Assign is an overridden method used to store properties from the specified image list to the current class instance. Assign re-implements the method defined in TPersistent to include properties from TCustomImageList.

Source contains the TCustomImageList instance with the properties stored in the current class instance. No actions are performed in the method when Source is the same as the current class instance (Self).

Assign checks the class instance in Source to determine if it is derived from TCustomImageList. When it is a TCustomImageList descendant, existing resolutions and images in the current class instance are discarded. The following property value are copied from Source to the current image list instance:

- Height
- Width
- Resolutions

The Resolutions enumerator in Source is used to get images for each image resolution and to reallocate the storage used for its raw image data. System.Move is called to copy the raw image data for the resolution from Source to the current class instance.

When Source is not derived from TCustomImageList, the inherited Assign method is called using Source as an argument.

Image list with properties stored in the current class instance.
Writes image data for the default resolution to a stream.

WriteData is a procedure used to write the image data for the default resolution to the stream specified in AStream. WriteData calls GetResolution using the value in Width to retrieve the default image resolution. The WriteData method in TCustomImageListResolution is called to perform the write operation using the specified stream.

Please note: Data compression is enabled when writing image data for the resolution. Data compression was not enabled in previous LCL versions to maintain compatibility with earlier versions of Lazarus. That backward compatibility is no longer possible with image compression enabled.

Use WriteAdvData to write image data for all resolutions in the image list.

Use ReadData to read image data from a stream.

Image compression was enabled as a default in revision 62583, and will be included in Lazarus versions after 2.0.6.
Stream used to store the image data.
Reads image data for the default resolution from a stream.

ReadData is a procedure used to read image data for the default resolution from the stream specified in AStream. ReadData allows image data written using the WriteData method to be stored in the image list.

ReadData calls BeginUpdate to suspend OnChange notifications when loading the image data from the stream. EndUpdate is called when the image data has been loaded from the stream.

ReadData calls the GetResolution method to locate the TCustomImageListResolution class instance which uses the image width in the Width property. The ReadData method in TCustomImageListResolution is used to read image data from the stream in AStream.

ReadData updates the internal Changed flag for the image list, and calls the Change method to perform change notifications.

Stream with the image data read in the method.
Writes the image content for multiple resolutions to the specified stream.

WriteAdvData is procedure used to write image data for multiple resolutions to the stream specified in AStream. WriteAdvData is similar to the WriteData method, but writes only the image resolutions other than the default resolution for the image list. Like the default resolution, image resolutions that were automatically created at design-time are also ignored in the method.

WriteAdvData uses the Resolutions enumerator to gather the image resolutions handled in the method. WriteAdvData writes an image list signature that identifies the storage format used in the stream. WriteAdvData writes an Integer value that indicates the number of resolutions included in the stream.

The WriteData method in TCustomImageListResolution is used to write the image content for each of the resolutions handled in the method. Data compression is enabled for each of the resolutions written to the stream.

WriteAdvData is used in the implementation of the DefineProperties and Equals methods.

Use WriteData to store the image content for the default resolution to a stream.

Use ReadAdvData to read the values written using the WriteAdvData method.

Stream where the content for the image resolutions is stored.
Reads the image content for multiple resolutions from a stream.

ReadAdvData is a procedure used to read the content for multiple image resolutions from the stream specified in AStream. ReadAdvData is the complement to the WriteAdvData method, and handles reading multiple image resolutions for the image list.

ReadAdvData calls BeginUpdate to block OnChange notifications in the method. The EndUpdate method is called when all image resolutions in the stream have been loaded.

ReadAdvData reads the image list signature from AStream, and checks the value to ensure that it supports use of BitmapAdv in its properties. If it does not contain the value SIG_LAZ3, an Exception is raised.

ReadAdvData reads the Integer value that indicates the number of image resolutions stored in the stream, and processes each resolution by reading the following values:

Value | Size
Resolution signature | SizeOf(TImageListSignature)
Image count | Cardinal
Image width | Cardinal
Image height | Cardinal

An exception is raised if an image resolution does not support BitmapAdv in its properties (requires SIG_LAZ3 or SIG_LAZ4 in the resolution signature).

ReadAdvData gets a TCustomImageListResolution instance from the internal TCustomImageListResolutions container that uses the image width for each of the resolutions. An image resolution is created if it does not already exist. Each resolution class instance calls its ReadData method to load image data from the stream in AStream.

ReadAdvData updates the internal Changed member for the image list, and calls Change prior to exiting from the method.

Raises an exception if the image list signature is not SIG_LAZ3.

Raises an exception if an image resolution signature is not SIG_LAZ3 or SIG_LAZ4.

ReadLRSCardinal
Stream with the image resolutions loaded in the method.
Compares the contents of the image lists.

Equals is an overridden Boolean function used to compare the content in the image list to another TCustomImageList class instance. Equals re-implements the method defined in TObject to determine object equivalence.

Obj is a TObject instance used in the comparison. Obj must be a TCustomImageList descendant in the method; the inherited method is called when it is not derived from TCustomImageList.

This is an expensive operation. Both image lists are written to memory streams using WriteData and WriteAdvData, and the streams are then compared on a byte-by-byte basis.

The return value is True when the memory used in both streams has identical content.

True when the image lists are equivalent.
The image list object used for the comparison.
Starts an update to the image list, and blocks execution of the OnChange event.

Use BeginUpdate when an update to the image list is started to block execution of the OnChange event handler.

BeginUpdate is used, along with EndUpdate, to speed up the insertion of images in an image list. Every call to BeginUpdate must be matched by a call to EndUpdate; i. e. update operations can be nested.

BeginUpdate increments an internal counter in the class instance each time the method is called. EndUpdate decrements the internal counter when called. When the counter contains a positive non-zero value, the OnChange event handler is not executed when the image list is changed.

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

EndUpdate is used to finish an update to images in the list. EndUpdate is used, along with BeginUpdate, to speed up image list updates by blocking execution of the OnChange event handler.

BeginUpdate increments an internal counter in the class instance each time the method is called. EndUpdate decrements the internal counter when called. When the counter contains a positive non-zero value, the OnChange event handler is not executed when the image list is changed. When the counter reaches zero (0), the Change method is called to perform OnChange notifications.

EndUpdate cannot be called more often than the BeginUpdate method. If the method would cause the internal counter to contain a negative value, the RaiseGDBException method is called to raise an exception for the condition.

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

Add is an Integer function used to to add the specified Image and its optional Mask to the image list.

Image is the TCustomBitmap instance with image data added in the method.

Mask is a TCustomBitmap instance which contains a monochrome bitmap which defines the transparent areas for the image. When Mask contains a valid bitmap, it is combined with the source data in Image before it is stored in the image list. When Mask contains Nil, the Image has no defined transparent areas.

The return values contains the ordinal position in the image list for the newly added image.

Add calls the Insert method to store Image and Mask in the image list. The Image and optional Mask are scaled and added to each of the defined Resolutions in the image list. No actions are performed in the method when Image has not been assigned (contains Nil).

Use AddMasked to add a masked image where MaskColor defines the transparent areas in the image.

Use the AddSlice method to store an image from source data in the image list storage format. Use the AddSliced method to store all images from source data in the image list storage format.

The index of the added image.
Bitmap image data added in the method.
A bitmap mask which defines the transparent parts of Image.
Adds images with varying sizes to the corresponding image resolution.

AddMultipleResolutions is an Integer function used to add images of varying sizes to the corresponding resolution in the image list.

AImages is an array of TCustomBitmap type with the images added in the method. Each image has a unique width that determines the image resolution where the image is stored. AImages must be sorted in ascending image width order before it is passed as an argument to the method.

The return value contains the ordinal position where the images were stored in the image resolutions. It should contain the value corresponding to Count-1 when the method is completed.

AddMultipleResolutions calls the CreateDefaultResolution method to ensure that the default image resolution has been created before adding images to the list.

The Resolutions enumerator is used to visit each of the TCustomImageListResolution instances used in the image list. Each image in AImages is compared to the image resolutions to determine if the width is already in use. If no exact match is found, the next larger image resolution is used. If no resolution is larger than the image width, the largest image resolution is used.

The ScaleImage method is called to resize the image in AImages to the height and width required for the target image resolution. The image is appended using the InternalInsert method in the image resolution to store the scaled raw image data.

Ordinal position where images were stored in the various resolutions.
Array of images stored in the method.
Adds images to the image list from image data stored as adjacent columns and rows.

AddSliced is an Integer function used to add one or more images from image data stored as adjacent images in grid format.

Image is a TCustomBitmap descendant that contains the image data used for the operation. No actions are performed in the method when Image has not been assigned (contains Nil). The return value is set to -1 when Image has not been assigned.

AHorizontalCount is an Integer value that indicates the number of adjacent images stored in Image on the horizontal plane (in a row). The Width of the Image must (should?) be a multiple of the value in AHorizontalCount.

AVerticalCount is an Integer value that indicates the number of adjacent images stored in Image on the vertical plane (in a column). The Height of the Image must (should?) be a multiple of the value in AVerticalCount.

The return value contains the ordinal position in the image list where the first image is stored in the method. It contains the value in the Count property prior to adding any images to the list.

AddSliced calls the CreateDefaultResolution method to ensure that the default resolution exists in the image list prior to adding images in the method.

AddSliced uses the values in AVerticalCount and AHorizontalCount to process the partial images stored in Image. Each image portion (or slice) is added to all of the resolutions available in the image list. The image slice is resized to the height and width required for an image resolution by calling ScaleImage for the current image rectangle. The image resolution calls its InternalInsert method to store the scaled 32-bit RGBA raw image data for the partial image. The process is repeated until all partial images defined by AVerticalCount and AHorizontalCount have been added to the image resolutions.

Ordinal position where the first image was stored in the image list.
Image data stored as a row(s) and columns(s) of adjacent images.
Number of adjacent horizontal images (columns).
Number of adjacent vertical images (rows).
Adds a portion of an image to each of the resolutions in the image list.

AddSlice is an Integer function used to add a portion of an image to each of the resolutions in the image list.

Image is a TCustomBitmap instance which contains the image added in the method. Image can contain a single image, or multiple combined images like the format returned from GetFullBitmap. No actions are performed in the method when Image has not been assigned (contains Nil), and the return value is set to -1.

AImageRect is a TRect type that specifies the area in Image added to the resolutions in the image list. When Image contains a single image, the image rectangle should match the dimensions for the entire image. When Image consists of multiple images, the image rectangle defines the portion (or slice) added to the image list.

The Count property is used as the position where the new image is stored in each of the image resolutions. It is also used as the return value for the method.

AddSlice calls CreateDefaultResolution to ensure that the default resolution for the image list exists before images are added in the method. AddSlice visits each of the image resolutions in the image list. The Width and Height properties in the image resolution are used to resize the image rectangle using the ScaleImage method. The InternalInsert method in the image resolution is called to store the scaled 32-bit RGBA raw image data to the position in the return value.

Use AddSliced to add multiple images to the image list from an image stored as adjacent images in row and column format.

AddSlice is used in the implementation of the AddSliceCentered method.

Ordinal position where the new image was stored in each of the image resolutions.
Image added in the method.
Area from the source image added in the method.
Adds an image centered in the height and width for the image resolutions.

AddSliceCentered is an Integer function used to add the specified image to each of the resolutions in the image list.

Image is a TCustomBitmap instance that contains the image data used in the operation. A TRect instance is created which uses the values in the Height and Width properties for the default resolution. The image rectangle is used to center the image content using the height and width for the image.

AddSliceCentered calls the AddSlice method using Image and the calculated image rectangle as arguments. AddSlice scales the image to the dimensions needed for each image resolution, and stores the scaled image data.

The return value contains the ordinal position where the image was stored in each of the images resolutions for the image list.

Ordinal position where the image was stored in the image resolutions.
Image content added in the method.
Adds an icon to the image list.

AddIcon is used to add the TIcon instance in the Image parameter to the image list. AddIcon calls InsertIcon to store the Image at the ordinal position represented by the Count property. The return value contains the index of the newly added icon, or -1 if the icon could not be added to the list.

Use the Add or AddMasked method to store a TCustomBitmap descendant in the image list.

The index of the added icon, -1 if unsuccessful.
The Icon to be added.
Adds images from another image list to the current class instance.

AddImages is a procedure used to add images from the image list in AValue to the current class instance. No actions are performed in the method when any of the following conditions are encountered:

- AValue is unassigned (contains Nil)
- AValue and the current class are the same class instance
- AValue has a Count property that contains 0 (zero)

AddImages uses the ResolutionsDesc enumerator in AValue to process images resolutions stored in the source image list. AddImages assumes that the first Resolution in the descending enumerator contains the largest image sizes.

For this resolution, all images are copied and added to the current class instance using their TBitmap image data. For the remaining resolutions (if any), the TCustomImageListResolutions.Find method is used to locate the resolution in the current class with compatible images (similar width and height values) as the resolution in AValue. Each of the source images for the resolution are stored in the current class instance using their raw image data.

The image list with the source images to add in the method.
Adds an image(s) to the list using the MaskColor for transparent pixels.

AddMasked is an Integer function used to add one or more images specified in Image to the image list. Image can contain multiple images of the same width and height. The total image width must be a multiple of the Width property, and the image height must be the same as the Height property.

Every pixel in the image(s) with the color in MaskColor will become transparent in the stored image(s).

The index of the first added image, -1 if unsuccessful.
The bitmap to be added to the image list.
The color used as the transparent pixels in the image(s).
Gets a bitmap from a Lazarus resource and stores it in the image list.

AddLazarusResource is an Integer function used to load and store a bitmap from a Lazarus resource.

ResourceName contains the Lazarus resource loaded in the method.

MaskColor is a TColor value used as the transparency color in masked images. The default value for the parameter is clNone, and indicates that the image should be rendered as an opaque (solid) image.

AddLazarusResource calls the CreateBitmapFromLazarusResource routine to get the TCustomBitmap for the specified ResourceName. When MaskColor contains a value other that clNone, it is set as the transparent color in the bitmap and transparency is enable for the image.

AddLazarusResource calls the Add method to store the bitmap in the image list. The return value contains the ordinal position in the image list where the bitmap was stored.

CreateBitmapFromLazarusResource
Position where the image was stored.
The name of the Lazarus resource.
The mask color for transparent images. clNone for solid (opaque) images.
Adds a graphic from a resource with the specified resource name.

AddResourceName is an Integer function used to load and store a TGraphic for the specified resource name.

Instance is a THandle value for the resource.

ResourceName is a String value that contains the name for the resource loaded in the method.

MaskColor is a TColor value used transparent areas in the graphic. The default value for the property is clNone, and indicates the graphic is rendered as an opaque (solid) image.

AddResourceName calls the CreateGraphicFromResourceName routine to get the image for the resource name specified in ResourceName. The return value may be either a TGraphic or a TCustomBitmap class instance.

When the image is a TCustomBitmap, the value in MaskColor is stored in the bitmap and transparency is enabled when the color is not clNone. MaskColor is not used when the return value is a TGraphic instance; TGraphic does not support transparency.

AddResourceName calls the appropriate method to store the image type in the image list. When TCustomBitmap is used, the Add method is called. When TGraphic is used, the AddIcon method is called. The return value contains the ordinal position in the image list where the image was stored.

CreateGraphicFromResourceName
Ordinal position where the image was stored.
Handle for the resource.
Name of the resource loaded in the method.
Color for transparent areas in the image, clNone for an opaque image.
Sends change notifications when the image list is updated.

Change is a procedure used to send change notifications when the image list is updated. Change uses internal members in the class instance which track changes to the image list. No actions are performed in the method when the image list has not been changed, or when a call to BeginUpdate has not been followed by a matching call to EndUpdate.

Change calls the NotifyChangeLink method to notify subscribers in its ChangeLinkList, and executes the OnChange handler when it has been assigned.

The internal member used to track changes in the image list is reset prior to exiting from the method.

Change is called from methods which update the content in the image list, such as:

- Clear
- Delete
- Move
- EndUpdate
- ReadData
- ReadAdvData
- SetBkColor (write access specifier for the BkColor property)

Removes all images store in the the image list.

Clear is a procedure used to remove all images stored in the image list.

Clear ensures that the content for all of the image resolutions is removed from the list, and calls ClearOverlays to reset any index positions used in the Overlays property. Clear sets the internal Changed flag for the class instance to True, and calls the Change method to perform change notifications.

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

Delete is a procedure used to delete the image stored at the specified position from all resolutions for the image list.

AIndex contains the ordinal position for the image deleted in the method. When AIndex contains the value -1, all images in the resolution are deleted.

Delete uses the Resolutions enumerator to call the Delete method in the TCustomImageListResolution instance returned by the enumerator. Deletes sets the internal Changed flag for the class instance to True, and calls the Change method.

The index of the image deleted in the method, or -1 to delete all images.
Renders an image to the specified canvas using a drawing style or effect.

Draw is an overloaded method used to render an image to the specified canvas. Draw uses the default resolution (as in indicated by the Width property) as the image size rendered in the method. Overloaded variants allow the use of a drawing effect or drawing style for the rendered image.

ACanvas contains the TCanvas instance used to render the requested image.

AX and AY contain Integer values representing the horizontal and vertical offsets from the canvas origin where the image is drawn.

AIndex contains the ordinal position for the requested image in the image list. No actions are performed in the method when AIndex contains a value that is an invalid position for images in the image list.

AEnabled indicates if the image is drawn in the enabled state. When AEnabled is False, the gdeDisabled drawing effect is used to render the image to the canvas.

ADrawEffect is a value from the TGraphicsDrawEffect enumeration that indicates the drawing effect applied to the raw image data, and stored in the bitmap. Values in AEffect determine whether the image is rendered normally, as a disabled (or grayed) image, highlighted, shadowed, or as a monochrome bitmap mask.

ADrawingStyle contains a value from the TDrawingStyle enumeration that indicates the image list drawing style used for the rendered image. ADrawingStyle determines how the image is blended with its background color when a mask is used in the image. It has no significance when a mask is not present in the image.

AImageType contains a value from the TImageType enumeration, and indicates whether the image uses a mask.

Draw calls GetResolution to retrieve the default resolution for the image list using the value in the Width property. The Draw method in the TCustomImageListResolution instance is called to render the image using the parameters specified in the method as arguments.

Canvas used for the draw operation.
Horizontal offset on the canvas for the image.
Vertical offset on the canvas for the image.
Position in the list for the image drawn to the canvas.
If False, the image is drawn disabled (dithered).
Drawing effect applied to the rendered image.
Drawing style applied to the rendered image.
Indicates if the image contains a mask or source data.
Renders an image to a canvas scaled to a specified display density.

DrawForPPI is an overloaded procedure used to render an image at the specified position to a canvas scaled to the specified display density.

ACanvas is a TCanvas instance where the image is rendered.

AX and AY contains the offsets on the canvas where the image is drawn.

AIndex is the position in the image list for the image rendered in the method.

AImageWidthAt96PPI is the width of the image using the default resolution.

ATargetPPI is the display density (Pixels per Inch) requested in the method.

ACanvasFactor is a Double value that indicates the canvas scaling factor applied to the rendered image.

ADrawEffect indicate the drawing effect used for the rendered image.

AEnabled indicates that the image drawn in the "enabled" state.

DrawForPPI calls the GetResolutionForPPI method to locate the image resolution for the target display density. The TCustomImageListResolution instance calls its Draw method to render the image to the canvas with the requested drawing effect.

Canvas where the image is rendered.
Horizontal offset on the canvas where the image is drawn.
Vertical offset on the canvas where the image is drawn.
Ordinal position for the image drawn in the method.
Width of the image in the default resolution.
Target display density (PPI) for the rendered image.
Canvas scaling factor applied in the method.
Indicates if the image is rendered in the enabled state.
Drawing effect applied to the rendered image.
Renders an image with an overlay to the specified canvas.

DrawOverlay is an overloaded procedure used to draw the specified image with an overlay. An overlay is an masked image drawn transparently over another image. The overlay image is generally used to convey state or status information about the image it adorns. The overlay images are stored in the image list (or the resolution) just like the images they decorate.

ACanvas is the TCanvas instance where the image and the overlay are rendered.

AX and AY contain the canvas offsets (horizontal and vertical) where the overlay image is drawn.

AIndex contains the ordinal position for the base image drawn in the method.

AOverlay contains the position in the Overlays property where the index position for the overlay image is stored. The value in AOverlay must be in the range 0..14 (the range defined in TOverlay).

ADrawingStyle contains the TDrawingStyle enumeration value applied to the rendered image.

AImageType contains a TImageType enumeration value that indicates if the image contains a mask.

ADrawEffect contains a TGraphicsDrawEffect enumeration value that indicates the drawing effect applied to the rendered image.

Overloaded variants of the method are provided which use a drawing effect, drawing style, and image type arguments.

DrawOverlay uses the value in the Width property to retrieve the default image resolution used in the method. The TCustomImageListResolution instance calls its DrawOverlay method to render the image and overlay using the parameter values as arguments.

No actions are performed in the method when AIndex does not contain a valid index position in the image list.

TGraphicsDrawEffect
Canvas where the image and its overlay are drawn.
Horizontal offset for the image on the canvas.
Vertical offset for the image on the canvas.
Ordinal position for the image drawn in the method.
Position for the overlay image drawn in the method.
Indicates if the image and overlay are drawn in the enabled state.
Drawing effect applied to the image and the overlay.
Drawing style used for the image and overlay.
Indicates the image type (masked or unmasked).
Gets image data at the specified position as a bitmap.

GetBitmap is an overloaded procedure used to get the image stored at the specified position in the image list as a bitmap image.

Index contains the ordinal position in the image list where the image is stored.

Image is the TCustomBitmap class instance where the requested image data is stored in the method.

An overloaded variant of the method includes the AEffect parameter which specifies the drawing effect applied to the image data and stored in Image. The default value for AEffect is gdeNormal and cause the image to be rendered using the normal enabled style for the widgetset.

GetBitmap calls GetResolution to locate the default image resolution which uses the width specified in the Width property. The TCustomImageListResolution class instance is used to call its GetBitmap method using the parameters supplied to the method.

TGraphicsDrawEffect
Ordinal position of the requested image.
Bitmap used to store the image data.
Drawing effect applied to the image.
Gets a bitmap with all of the images in the default resolution.

GetFullBitmap is a procedure used to get a bitmap with all of the images stored in the default resolution. GetFullBitmap mimics the image list storage format used in previous versions of TCustomImageList. This means that the combined image data for the resolution uses the value in the Height property as its vertical size, and the horizontal size is determined by the value from Width * Count.

Image is the TCustomBitmap instance where the image data is stored in the method.

AEffect is a value from the TGraphicsDrawEffect enumeration that indicates the drawing effect applied to the rendered images and stored in Image. The default value for the parameter is gdeNormal and causes the normal enabled drawing effect for the widgetset to be used.

GetFullBitmap calls the GetResolution method to retrieve the image resolution which uses the value in the Width property. The TCustomImageListResolution class instance is used to call its GetFullBitmap method passing Image and AEffect as arguments.

Use GetBitmap to retrieve a single image in the default resolution. Use GetRawImage or GetFullRawImage to retrieve raw image data for the default resolution.

Bitmap where image data is stored.
Drawing effect applied to the rendered images.
Gets the raw image data for all images in the default resolution.

GetFullRawImage is a procedure used to get the 32-bit RGBA raw image data for all images in the default resolution. Image is a TRawImage output parameter where the raw image data is stored in the method.

GetFullRawImage calls the GetResolution method to get the image resolution that uses the image size in the Width property. The GetFullRawImage method in the TCustomImageListResolution instance is called to store the raw image data for the resolution.

TRawImage
Image used to store the 32-bit raw image data for the default resolution.
Gets the icon at the specified index and applies an image effect.
Ordinal position in the imagelist with the icon image data.
TIcon instance where the image data is stored.
Drawing effect applied to the image data. gdeNormal when not specified.
Gets the raw image data at the specified position from the default image resolution (Width).

Calls GetResolution to get the image resolution for the value in the Width property. Calls GetRawImage in the image resolution to re-initialize and populate the Image output variable.

Ordinal position in the image list for the raw image data.
TRawImage instance where the image data is stored.
Returns the offset from the drawing position to the image origin.

GetHotSpot is a TPoint function used to get the HotSpot for an image stored in the image list. The HotSpot is an offset from the drawing position to the image origin. A HotSpot is used only in TDragImageList. In TCustomImageList, its position is always (0,0).

TPoint with the coordinates for the image hot spot.
Inserts an image into each image resolution at the specified position.

Insert is a procedure used to insert an image into each of the resolutions for the image list at the ordinal position specified in AIndex.

AImage is a TCustomBitmap instance that contains the image data stored in the image list. No actions are performed in the method when AImage is unassigned (contain Nil).

AMask is a TCustomBitmap instance that contains the mask that defines the transparent areas in the image. When AMask is Nil, no transparent areas are defined in AImage. Use InsertMasked to insert bitmaps with a specific transparent color.

Insert calls the CreateDefaultResolution method to ensure that the default image resolution has been created using the value in the Width property.

Insert uses the Resolutions enumerator to visit each of the TCustomImageListResolution instances used in the image list. The ScaleImage method is called to resize the bitmaps in AImage and Mask to the image width for the resolution. The InternalInsert method for the image resolution is called to store the scaled raw image data at the position in AIndex.

Ordinal position where the image is stored.
Bitmap image stored in the method.
Transparency mask, Nil for opaque.
Inserts an Icon into each of the resolutions for the image list.

InsertIcon is a procedure used to insert an icon at the specified position in each of the resolutions for the image list.

AIndex contains the ordinal position in the image list where the icon is stored.

AIcon is the TCustomIcon instance stored in the method. AIcon allows multiple icon sizes to be available in the class instance. No actions are performed in the method when AIcon is unassigned (contains Nil). To ensure that the icon sizes in AIcon are in ascending size order, a temporary TIcon instance is created and its Sort method is called.

InsertIcon uses the Resolutions enumerator to visit each of the image resolutions used in the image list. GetBestIconIndexForSize is called for each image resolution to get the icon size for the width in the resolution. ScaleImage is called to resize the icon bitmap and mask (when present) to the height and width required for the image resolution. The InternalInsert method in the image resolution is called to store the scaled raw image data for the icon at the position in AIndex.

TCustomIcon
Position in the image list where the icon is inserted.
The Icon to insert into the image list.
Inserts a transparent image into the image resolutions at the specified position.

InsertMasked is a procedure used to insert a transparent image into each of the resolutions for the image list.

Index contains the position in the image list where the transparent image is stored in each of the image resolutions.

AImage is a TCustomBitmap instance which contains the image inserted into the image list. No actions are performed in the method when AImage has not been assigned (contains Nil).

MaskColor is a TColor value which represents the transparent pixels in the image. Every pixel using the color in MaskColor is converted into a transparent pixel. InsertMasked creates a temporary TBitmap instance that is used to set the TransparentColor, TransparentMode, and Transparent properties in the image.

InsertMasked calls the CreateDefaultResolution method to ensure that the default resolution exists before inserting the image into the image list. The Resolutions enumerator is used to update each of the TCustomImageListResolution instances in the image list. The ScaleImage method is called to resize both the original image and the temporary mask to the Width and Height needed for the image resolution. The InternalInsert method in the image resolution is called to store the scaled 32-bit RGBA raw image data for the masked image.

The index for the inserted image.
The bitmap to be inserted.
The color used transparent areas in the image.
Moves an image from the position at CurIndex to NewIndex.

Move is a procedure used to relocate images stored at the position in CurIndex to the position in NewIndex for each of the resolutions in the image list. No actions are performed in the method when ACurIndex and ANewIndex contain the same value.

Move calls CheckIndex to verify that the values in ANewIndex and ACurIndex are valid index positions in the image list. An exception is raised in CheckIndex if either value is invalid for the bounds in the image list.

Move uses the Resolutions enumerator to visit each of the image resolutions in the image list. The InternalMove method in the TCustomImageListResolution instance is called to relocate image data using the specified positions. If the handle for the image resolution has been allocated, the widgetset class calls its Move method to mirror the change to the image list.

Move sets the value in the internal Changed flag to True, and calls the Change method to perform notifications for the change event.

Current Index position for the image(s) to be moved.
New index position for the image(s).
Assigns an overlay index for the specified image in the image list.

Overlay is a procedure which makes an image in the image list an overlay. An overlay image is drawn transparently over another image. An image list can have up 15 images designated as overlay images (0 is reserved for none).

AIndex contains the position in the image list for the image to use as an overlay image.

Overlay is a TOverlay value that indicates the position in the internal array of overlay indexes where the value in AIndex is stored. The overlay indexes are essentially one-based because an overlay index of zero means that no overlay image is needed.

The Overlay method tells the image list that the image in AIndex is an overlay image referenced using the value in the Overlay parameter instead of the ordinal position in the image list.

Overlay sets the value in the HasOverlays property to True when AIndex contains a valid index position in the image list. Otherwise, the image indexes in each of the internal overlay positions are re-examined to determine the value for HasOverlays.

Use the DrawOverlay method to draw an image along with a specific overlay image.

Use ClearOverlays to reset the image indexes stored in the internal member to the unused value (-1).

Ordinal position of the image used as an overlay.
Ordinal position in the internal array where the image index is stored.
Indicates if any images in the list have been used as an overlay image.

HasOverlays is a read-only Boolean property that indicates if any images in the list have been designated as an overlay image. The value in HasOverlays is updated when the Overlay method is used to store an image index to a position the internal overlays array.

The value in HasOverlays can be used to determine the correct drawing method to call when drawing an image in the image list; Draw when HasOverlays is False, DrawOverlay when HasOverlays is True.

Use ClearOverlays to reset the image assignments made in the Overlay method.

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

Replace is a procedure used to replace an image stored at the position specified in AIndex.

AImage is a TCustomBitmap type that contains the image stored in the method.

AMask is a TCustomBitmap type that contains the image mask which defines the transparent areas in the image. When AMask is omitted, the image is drawn opaque.

AllResolutions indicates if the image at the specified position is replaced in all resolutions for the image list. When AllResolutions is False, the only resolution updated is the one which uses the width in AImage. When AllResolutions is True, the Resolutions enumerator is used to update each of the TCustomImageListResolution instances in the image list.

The ScaleImage method is called to resize the image and its mask to the width required for an image resolution. The InternalReplace method in the image resolution is called to update the scaled 32-bit raw image data stored at the position in AIndex.

Ordinal position for the image replace in the method.
The bitmap image stored in the method.
The bitmap which defines the transparent parts of the image.
Replace an image at the specified position with a slice from the specified image.

ReplaceSlice is a procedure used to replace an image at the specified index position with a portion (or slice) from the specified image.

AIndex contains the ordinal position of the image updated in the method.

Image is a TCustomBitmap type that contains image data stored in the method. No actions are performed in the method when Image has not been assigned (contains Nil).

AImageRect is a TRect type that defined the top, left, bottom, and right coordinates for the image data used in the method.

AllResolutions indicates if the image stored at the specified position is updated in all of the image resolutions for the image list. When AllResolutions contains False, only the image resolution using the width defined in ARect is updated in the method. When AllResolutions is True, the Resolutions enumerator is used to update each of the image resolutions used in the image list.

The ScaleImage method is called to resize the Image rectangle to the height and width required for the image resolution(s). The InternalReplace method in each image resolution is called to store the scaled 32-bit RGBA raw image data.

Ordinal position for the image updated in the method.
Image with data stored in the method.
Defines the coordinates for the image stored in the method.
Indicates if all image resolutions are updated in the method.
Replaces the image at the specified position from image data stored as adjacent columns and rows.

ReplaceSliceCentered is a procedure used to replace the image at the specified position from the specified image data.

AIndex contains the index position for the image replace in the method.

AImageWidth contains the width for the image resolution updated in the method. No actions are performed in the method when an image resolution using the specified width is not found.

Image is a TCustomBitmap instance that contains the image data store in the image list.

AllResolutions indicates if all image resolutions are updated in the method. When AllResolutions is False, only the image resolution using the image width in AImageWidth is updated in the method. When AllResolutions is True, the image stored at the specified position is updates in all Resolutions for the image list.

ReplaceSliceCentered calls the ReplaceSlice method to update the image at the specified position using the parameters passed to the method.

Ordinal position for the image replaced in the method.
Image width for the resolution updated in the method.
Image data stored in the method.
Indicates if all image resolutions are updated in the method.
Replaces the icon at the specified position in all resolutions for the image list.

ReplaceIcon is a procedure used to replace the icon stored at the position specified in AIndex in all resolutions for the image list.

AIcon is a TCustomIcon type that contains the graphic image stored in the method. No actions are performed in the method when AIcon has not been assigned (contains Nil).

Icons can contain multiple sizes, and must be in ascending size order to ensure they are applied correctly to image resolutions. ReplaceIcon create a temporary TIcon instance that is used to sort the icons prior to updating the resolutions in the image list.

ReplaceIcon uses the Resolutions enumerator to update each of the image resolutions used in the image list. The GetBestIconIndexForSize method is called to determine the icon size used for each image resolution. The ScaleImage method is called to resize the icon to the width required for each image resolution. If the icon is Masked (has transparent areas), the handle for the bitmap mask is included in the image scaling process. The InternalReplace method in the image resolution is called to store the scaled 32-bit RGBA raw image data.

Ordinal position for the icon replaced in the method.
Icon stored in the method.
Replaces the image at the specified position with a masked image.

ReplaceMasked is a procedure used to replace the image stored at the specified position with a masked image.

Index is an Integer value that contains the ordinal position in the image list for the image replaced in the method.

NewImage is a TCustomBitmap instance that contains the image data used in the method. No actions are performed in the method when NewImage has not been assigned (contains Nil).

MaskColor contains a TColor value that represents transparent pixels in the image. Every pixel in the image using the color in MaskColor is converted to a transparent pixel.

AllResolutions indicates if all resolutions in the image list are affected in the method. When AllResolutions contains False, only the resolution using the Width in NewImage is updated with the new image data. When AllResolutions contains True, the Resolutions enumerator is used to scale and store the image for each TCustomImageListResolution instance.

ReplaceMasked creates a temporary TBitmap instance that is used to update the TransparentColor and Transparent properties for the image. It is also used when the image is scaled for the various image resolutions.

Ordinal position for the image replaced in the method.
Bitmap image stored in the method.
The color used for transparent pixels the image.
Registers a TChangeLink object for notifications when the image list is changed.

RegisterChanges is a procedure used to register the specified change link object to receive change notifications when the image list is changed.

Value contains a TChangeLink instance that represents the class subscribing to the event notifications. When AValue is assigned, but not yet stored in the internal change link list, the current class instance is assigned as the Sender for change notifications. Value is added to the internal list of subscribers.

No actions are performed when Value is unassigned (contains Nil) or when it has already been added to the internal list of subscribers.

Value, and other subscribers the internal list, receive change notifications when the Reference class for an image resolution is freed and when the private NotifyChangeLink method is called.

Use UnRegisterChanges to remove a TChangeLink instance from the internal list of subscribers.

NotifyChangeLink is called from the implementation of the Change method.

Reference to the ChangeLink object.
Unregisters a ChangeLink object for change notifications.

UnRegisterChanges is a procedure used to remove the specified change link object from the internal list of subscribers for the image list.

Value contains the TChangeLink instance removed in the method when subscribers have been stored in the internal list. UnRegisterChanges causes change notifications to not be sent to the linked object by clearing the value it Sender property and removing it from the internal list.

UnRegisterChanges is used in the Destroy method, and when a TChangeLink class instance is freed.

Reference to the changelink object to remove.
Draws an image stretched to the dimensions for the target rectangle.

StretchDraw is a procedure used to render an image stretched to the required dimensions on the specified canvas.

Canvas is the TCanvas instance where the image is rendered using the dimensions in the target rectangle.

Index contains the ordinal position for the image drawn in the method.

ARect is a TRect instance that contains the Top, Left, Bottom, and Right coordinates for the canvas. The rendered image must fit with in these boundaries on the canvas.

Enabled indicates if the image is drawn using its "enabled" state. When Enabled is True, the gdeEnabled drawing effect is used for the rendered image. When Enabled is False, the gdeDisabled drawing effect is used.

StretchDraw searches the images resolutions in the image list to locate the best scaling candidate for the width represented in ARect. If a suitable TCustomImageListResolution is located for the operation, its StretchDraw method is called using the parameter values as arguments. No actions are performed in the method if a suitable scaling candidate resolution is not found.

Canvas used for the drawing operation.
Ordinal position for the image drawn in the method.
Rectangle coordinates used for the draw operation.
Indicates if the image is drawn using the enabled display state.
Registers image resolutions (sizes) to use in the image list.

RegisterResolutions is a procedure used to register image resolutions (or sizes) used in the image list. RegisterResolutions allows TCustomImageListResolution instances to be created and stored in the image resolution container for the image list.

AResolutionWidths is an array of Integer values that contains the icon widths for the image resolutions used in the image list. Each image width is passed as an argument to the GetResolution method. This locates the image resolution class instance if it already exists, or creates a new one when needed. The AutoCreatedInDesignTime property in the image resolution is set to False to show that the resolution was created at run-time.

Use RegisterResolutions prior to adding images to the image list at run-time.

Array of image resolutions to allocate in the image list.
Deletes the image resolution which uses the specified image width.

DeleteResolution is a procedure used to delete the image resolution which uses the image width specified in AWidth.

DeleteResolution uses the internal TCustomImageListResolutions container to get the position for the resolution using the requested image width. If an image resolution is found, it is removed using the Delete method for the container. No actions are performed in the method if the image width is not used in an image resolution.

Image width for the resolution removed in the method.
Finds the image resolution which uses the specified image width.

FindResolution is a Boolean function used to find the image resolution with the image width specified in AImageWidth.

AResolution is a TCustomImageListResolution output parameter used to return the image resolution using the specified image width. AResolution contains Nil when the image width is not used in the resolutions for the image list.

FindResolution calls the Find method for the internal TCustomImageListResolutions container. The return value is True when an image resolution using the specified image width is found in the resolutions for the image list. The ResolutionByIndex property is used to get the class instance for AResolution when the return value is True.

FindResolution is used in the implementation of the Replace, ReplaceMasked, ReplaceSlice, and ReplaceSliceCentered methods.

True when an image resolution using the specified width is found.
Image width for the resolution requested in the method.
Image resolution class located in the method.
Size used to increment the allocated data count.

AllocBy is a read-only Integer property that indicates the increment used when increasing the number of allocated data blocks for images in the image list. The number of allocated data blocks is always increased in multiples of the AllocBy value. The default value is 4, as assigned in the Initialize method.

AllocBy is used in the implementation of the AllocData and WSCreateReference methods in TCustomImageListResolution.

Color used when blending (dithering) an image.

BlendColor is a TColor property that indicates the color combined with an image to achieve the DrawingStyle for the image list. The default value for the property is clNone.

Set BlendColor to cause the images in the list to be combined with the specified color when the DrawingStyle is dsFocus or dsSelected. More of BlendColor is combined with the images when DrawingStyle is dsSelected. clNone specifies no blend color while clDefault specifies the system highlight.

The value in BlendColor is used in TCustomImageListResolution methods like Draw and DrawOverlay.

Specifies the background color used for transparent parts of images.

BkColor is a TColor property that specifies the background color used for transparent parts of images in the image list. The default value for the property is clNone. Changing the value in BkColor causes the internal Changed flag to be set, and the Change method is called to perform change notifications.

BkColor is intended to speed up drawing of transparent images using a background of known color (BkColor). In this case the image can be drawn opaque, eliminating the need for masking out and merging image data.

The value in BkColor is used in TCustomImageListResolution methods like Draw and DrawOverlay.

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

Count is a read-only Integer property that indicates the number of images stored in the default resolution for the image list. Reading the value in the property causes the image resolution for Width to be selected, and its Count property is used as the property value.

The default drawing style for images in the image list.
DrawingStyle
is a TDrawingStyle property that indicates the default drawing style for images in the image list.
Height of images in the default resolution for the image list.

Height is an Integer property that contains the vertical size in pixels for images in the default resolution for the image list. The default value for the property is 16.

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

Height for images at the specified display density.

HeightForPPI is an indexed read-only Integer property that contains the image height used for images at the specified display density (Pixels per Inch). HeightForPPI allows the image height to be calculated for high density displays based on an initial image width.

AImageWidth is an Integer value that contains the initial image width used in the calculation.

APPI is an Integer value that contains the display density (Pixels per Inch) used in the calculation.

The image width for the requested display density is calculated by calling GetWidthForPPI. The image resolutions in the list are searched for the derived image width. If the resolution already exists, the Height property in the resolution is used as the property value. If the resolution is not found, the GetHeightForWidth method is used to get the value for the property.

Initial image width used to calculate the property value.
Display density used to calculate the property value.
Height used for images with the width specified width.

HeightForWidth is an indexed read-only Integer property which returns the height used for images with the width specified width in AWidth. The read access specifier for the property uses the values in the Width and Height properties to determine the aspect ratio used for images in the default resolution.

The property value is set to the product of AWidth and the calculated aspect ratio. The property value is 0 (zero) when the Width property has not been assigned for the image list.

HeightForWidth is used in the implementation of the following classes and methods:

- TCustomImageList.GetHeightForPPI
- TCustomImageListResolutions.GetImageLists

Image width used as the basis for the calculated image height.
Width of images in the default resolution for the image list.

Width is an Integer property that contains the horizontal size in pixels for images in the default resolution for the image list. The default value for the property is 16.

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

Image width needed for the specified display density.

WidthForPPI is an indexed read-only Integer property that contains the image width needed for images using the specified display density (Pixels per Inch).

AImageWidth is an Integer value that contains the initial image width used for the calculated width at the specified display density.

APPI is an Integer value that contains the display density used to calculate the width of images.

Reading the value for the property causes the image width to be calculated using the specified parameter values. If AWidth is 0 (zero) or a negative number, the value in the Width property is used as the initial image width. When Scaled contains True, the image width is calculated using the following formula:

(AImageWidth * APPI) / 96

If an image resolution does not already exist which uses the derived image width, the display density in APPI is used as a threshold for scaling using the following criteria:

Display Density (PPI) | Scaling Factor (%)
96-120 | 100%
121-168 | 150%
169 and higher | Calculated using (APPI / 96) * 100

The property value contains the image width derived using the formula:

AImageWidth * Factor div 100

When Scaled is False, image width scaling is not performed and the value in AImageWidth is used as the property value.

The OnGetWidthForPPI event handler is signalled (when assigned) to allow overriding the calculated image width. Applications can provide a TCustomImageListGetWidthForPPI procedure which uses custom scaling logic, or performs simple image width substitution for given display densities.

Initial image width used for the derived value.
Display density for the the derived image width.
Size used for images with the specified image width at the given display density.

SizeForPPI is a read-only TSize property which contains the size used for images with the specified image width at the given display density.

AImageWidth is an Integer value that contains the image width to use as the basis for the calculated size.

APPI is an Integer value that contains the display density (Pixels per Inch) used for the calculated size.

The property value is a TSize type with the image width and height stored in the CX and CY members (respectively).

The image size is derived by calling GetWidthForPPI to determine the best candidate image resolution at the specified display density. GetResolution is called for the candidate resolution and its Height and Width properties are stored in the return value.

Initial image width used to calculate the image size.
Display density for the calculated image size.
Event handler signalled when the image list is changed.

OnChange is a TNotifyEvent property that implements an event handler signalled when the image list is changed. Applications must assign an object procedure which performs actions required for the event notification.

OnChange is signalled from the Change method when a procedure has been assigned to the event handler.

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

Masked is a Boolean property which indicates if images in the image list contain an image mask that defines the transparent areas in the image. The default value for the property is False.

Set the value in Masked to True if the AddMasked or ReplaceMasked method was used to store a masked bitmap image to the image list.

Provides access to the reference class for the specified resolution.

Reference is an indexed read-only TWSCustomImageListReference property which provides access to the class instance for a resolution using the specified image width. Reading the value in the property causes the image resolution and its reference class to be created if it has not already been allocated.

Reference is used get access to the handle for the image list used in the resolution. The handle is a required argument in TWSCustomImageListResolutionClass methods.

Reference class using the specified image width and display density.

ReferenceForPPI is an indexed read-only TWSCustomImageListReference property used to get the class instance for an image resolution using the specified image width and display density. The reference class allows access to the widgetset implementation for an image list. It is used mainly in situations that need the handle for an image list.

AImageWidth is an Integer value that contains the image width for the requested reference class.

APPI is an Integer value that contains the display density (Pixels per Inch) for the requested reference class.

Reading the value in the property causes the GetWidthForPPI method to be called to determine the actual image width needed for the specified display density. The GetReference method is called to retrieve the reference class using the derived image width.

Image width for the requested property value.
Display density for the requested property value.
Provides indexed access to an image resolution with the specified image width.

Resolution is an indexed read-only TCustomImageListResolution property which provides access to an image resolution using the image width specified in AImageWidth.

GetResolution is the read access specifier for the Resolution property. It retrieves an image list using the specified image width. When AImageWidth is 0 (zero) or a negative value, the value in the Width property is used to locate the image resolution.

Use ResolutionByIndex to get a resolution using its ordinal position in the resolutions for the image list.

Use ResolutionCount to get the number of image resolutions used in the image list.

Use Resolutions or ResolutionsDesc to get an ascending or descending enumerator for images resolutions in the image list.

Image width to locate in the resolutions for the image list.
Provides access to an image resolution by its ordinal position in the image list.

ResolutionByIndex is an indexed read-only TCustomImageListResolution property which provides access to a resolution in the image list by the ordinal position specified in AIndex. ResolutionByIndex accesses the internal TCustomImageListResolutions member where the image resolutions are stored in the image list.

Use Resolution to get an image resolution using the specified image width.

Use Resolutions or ResolutionsDesc to access the ascending and descending enumerators for the resolutions container.

Use ResolutionCount to determine the number of image resolutions used in the image list.

Use ResolutionForPPI to get a temporary scaled image resolution using the specified display density.

Ordinal position for the requested image resolution.
Gets a scaled resolution with the specified width, display density, and scaling factor.

ResolutionForPPI is a read-only property used to get an image list with scaled images suitable for the specified width, display density (PPI), and scaling factor.

AImageWidth is the width of the images used as the source for the resized images. AImageWidth determines the Resolution selected as the source image list.

APPI indicates the display density (pixels per inch) for the resized images.

ACanvasScaleFactor contains the value used to adjust the image sizes when Scaled is set to True. The value in ACanvasScaleFactor is not used when Scaled is set to False.

The return value contains the TScaledImageListResolution instance created using the requested values. It is constructed dynamically in GetResolutionForPPI (the read access specifier for the property).

Image width requested in the list of image resolutions.
Display density (PPI) for the scaled images.
Canvas scaling factor for the scaled images.
Number of image resolutions available in the image list.

ResolutionCount is a read-only Integer property that provides access to the number of image Resolutions available in the image list. ResolutionCount returns the length of the internal TCustomImageListResolutions container used in the class instance.

Use the Resolutions or ResolutionsDesc methods to access an enumerator with the TCustomImageListResolution instances for the image list. Use the Resolution property to access a TCustomImageListResolution using a specified image width. Use the ResolutionsByIndex property to access an image resolution by its ordinal position in the image list.

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

Resolutions is a read-only TCustomImageListResolutionEnumerator function that provides access to the enumerator for image resolutions in the image list. Images resolutions are accessed in ascending image size order in the enumerator.

Container for the images resolutions used in the class instance.
Provides access to the descending enumerator for image resolutions in the list.

ResolutionsDesc is a TCustomImageListResolutionEnumerator function that provides access to the descending enumerator for image resolutions in the image list. Images resolutions are accessed in descending image size order in the enumerator.

Descending Resolutions enumerator for the class instance.
Indicates if images are automatically scaled for missing resolutions.

Scaled is a Boolean property that indicates if images are automatically scaled for missing resolutions requested in the image list. The default value for the property is False.

When Scaled contains True, images in the list are dynamically scaled to the required width for a given display density (PPI). If the resolution already exists in the image list, it is used to retrieve images. If it does not already exist, an existing resolution is used as the basis for scaling images to the required width. When Scaled contains False, dynamic scaling is not performed for image resolutions. Instead, the closest resolution that matches the desired width is used as the source for images.

Use the OnGetWidthForPPI event handler to perform image size overrides or substitution for a given display density (PPI).

Scaled is used in the implementation of the GetResolutionForPPI and GetWidthForPPI methods.

True when the handle for the image list is shared.

ShareImages is a Boolean property that indicates if the handle for an image list is shared. When ShareImages contains False, the handle to the image list is freed when the the image list is destroyed.

This property exists only for Delphi compatibility. ShareImages is not used in the current implementation of TCustomImageList.

Controls whether images are drawn with or without a mask.

ImageType is a TImageType property that controls whether images are drawn with or without a mask. The value in ImageType is used as the default value for arguments passed to widgetset classes in the Draw, DrawOverlay, and StretchDraw methods.

Set the value in ImageType to itMask when a mask that defines the transparent areas in an image is stored in the raw image data. The default value for the property is itImage.

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

OnGetWidthForPPI is a TCustomImageListGetWidthForPPI property that implements the event handler signalled to get the width for images using a specified display density (Pixels per Inch). OnGetWidthForPPI allows an application to override image width values derived using the automatic scaling features in TCustomImageList.

OnGetWidthForPPI is signalled when the GetWidthForPPI method is called, and when reading the value for the WidthForPPI property. The event is the last action performed (when assigned) in the GetWidthForPPI method. It can be used in situations where automatic image scaling is not enable using the Scaled property. It can also be used when the automatic scaling algorithm in GetWidthForPPI produces undesirable results (or performance) for certain high density displays.

Assign an object procedure using the TCustomImageListGetWidthForPPI type to the event handler which handles image width calculations or substitutions. The image width is returned in the AResultWidth parameter for the event handler.

Indicates the actions performed for resources with missing image sizes.
Show an exception if any image resolution is missing for a resource.
Show an exception if no default image resolution is found. Missing resolutions will be auto-generated by scaling the largest image size.
Ignore all missing image resolutions. No image will be added and TLCLGlyphs.GetImageIndex result is -1 if the image resolution is found.
Represents glyphs for buttons or icons used in LCL controls.
Record representing glyph names.
Glyph name for the entry key.
Pointer to a TEntryKey type.
Represents the key/value pair for glyph name and index position.
Glyph name for the entry.
Ordinal position for the image using the specified glyph name.
Record used to track width and scale suffix values used for glyphs.
Width of the glyphs for the resolution.
Scaling level for glyphs using the resolution.
Gets the position of the specified resource.
Ordinal position for the specified resource name.
Resource name to locate.
Register a list of resolutions using the specified suffixes.
List of image widths to register.
List of suffixes used for images using the corresponding width.
Sets the suffix used for images at the 100% scaling level.
Suffix for the scaling level.
Constructor for the class instance.
Owner of the class instance.
Destructor for the class instance.
Indicates the action performed for missing resources.
Provides access to the TLCLGlyphs instance in the implementation.

LCLGlyphs is a TLCLGlyphs function used to provide access to the TLCLGlyphs instance in the implementation section for the unit. LCLGlyphs ensures that the unit variable has been instantiated, and resolutions are registered using 16, 24, and 32 pixel sizes. The unit variable is freed in the finalization section for the unit.

LCLGlyphs is used to get the TButtonGlyph icons displayed using TButton and TBitBtn, and in the implementation of the Lazarus IDE.

The TLCLGlyphs instance in the implementation.
Gets a glyph with the specified name from the default resource file.

GetDefaultGlyph is a TCustomBitmap function used to get a glyph with the specified name from the default resource file.

ResourceName contains the name for the resource to locate in the resource file.

ScalePercent contains the scaling level requested for the glyph, and may be used as the suffix for the resource name. ScalePercent generally contains a value like 100, 150 or 200. When its value is not 100, it is appended to the resource name in the format: paste_150 or copy_200.

IgnoreMissingResource indicates if a missing resource can be silently ignored in the routine. When IgnoreMissingResource contains False, a missing resource causes an EResNotFound exception to be raised.

The return value contains the bitmap for the requested glyph. It is created by calling CreateBitmapFromResourceName routine. If no resource file is assigned for the current instance handle (HINSTANCE), the Lazarus resource file is searched as well. When a valid TBitmap image is found, its Transparent is updated to use the pixel at the bottom-left of the image as the fixed transparency color. The return value is Nil when a resource with the requested name and scaling level is not found.

GetDefaultGlyph is used in the implementation of the TLCLGlyphs.GetImageIndex method.

Raises an EResNotFound exception for a missing resource when IgnoreMissingResource contains False. Raised with the message in SResNotFound.

Bitmap for the requested resource name and scaling level.
Resource name for the glyph
Scaling level for the bitmap image.
Indicates if a missing resource can be ignored.