<?xml version="1.0" encoding="UTF-8"?>
<!--

Documentation for LCL (Lazarus Component Library) and LazUtils (Lazarus 
Utilities) are published under the Creative Commons Attribution-ShareAlike 4.0 
International public license.

https://creativecommons.org/licenses/by-sa/4.0/legalcode.txt
https://gitlab.com/freepascal.org/lazarus/lazarus/-/blob/main/docs/cc-by-sa-4-0.txt

Copyright (c) 1997-2025, by the Lazarus Development Team.

-->
<fpdoc-descriptions>
<package name="lcl">

<!--
====================================================================
ImageListCache
====================================================================
-->

<module name="ImageListCache">
<short>
Implements a caching mechanism for TCustomImageList (TImageList) instances.
</short>
<descr>
<p>
<file>imagelistcache.pas</file> contains classes, types, and routines used to
implement a cache for <var>TCustomImageList</var> instances. It is used mainly
to cache image lists with the glyphs used on button controls.
</p>
<p>
<file>imagelistcache.pas</file> is part of the Lazarus Component Library 
(<b>LCL</b>).
</p>
</descr>

<!-- unresolved type references -->
<element name="Classes"/>
<element name="SysUtils"/>
<element name="Graphics"/>
<element name="ImgList"/>
<element name="LCLProc"/>
<element name="Forms"/>

<!-- object Visibility: default -->
<element name="IImageCacheListener">
<short>
Interface that cache user should have to listen for cache changes.
</short>
<descr/>
<seealso>
<link id="TImageCacheItem"/>
<link id="TImageListCache.RegisterListener"/>
<link id="TImageListCache.UnregisterListener"/>
<link id="TImageListCache.RegisterBitmap"/>
</seealso>
</element>

<!-- procedure Visibility: default -->
<element name="IImageCacheListener.CacheSetImageList">
<short>Sets the image list for the cache listener.</short>
<descr/>
<seealso/>
</element>

<!-- argument Visibility: default -->
<element name="IImageCacheListener.CacheSetImageList.AImageList">
<short>TCustomImageList instance for the listener.</short>
</element>

<!-- procedure Visibility: default -->
<element name="IImageCacheListener.CacheSetImageIndex">
<short>Sets the new image index for an image in the list.</short>
<descr/>
<seealso/>
</element>

<!-- argument Visibility: default -->
<element name="IImageCacheListener.CacheSetImageIndex.AIndex">
<short>Old image index in the listener.</short>
</element>

<!-- argument Visibility: default -->
<element name="IImageCacheListener.CacheSetImageIndex.AImageIndex">
<short>New image index in the listener.</short>
</element>

<!-- record type Visibility: default -->
<element name="TImageCacheItem">
<short>Represents an item in the cache.</short>
<descr/>
<seealso>
<link id="TImageCacheItems"/>
<link id="TImageListCache"/>
</seealso>
</element>

<!-- variable Visibility: default -->
<element name="TImageCacheItem.FImageList">
<short>Reference to the image list.</short>
</element>

<!-- variable Visibility: default -->
<element name="TImageCacheItem.FListener">
<short>Reference to the listener interface.</short>
</element>

<!-- variable Visibility: default -->
<element name="TImageCacheItem.FImageIndexes">
<short>Indices in the image list that the listener has reserved.</short>
</element>

<!-- pointer type Visibility: default -->
<element name="PImageCacheItem">
<short>Pointer to a TImageCacheItem type.</short>
</element>

<!-- object Visibility: default -->
<element name="TImageCacheItems">
<short>Implements a container for cached image lists.</short>
<descr>
<p>
<var>TImageCacheItems</var> is a <var>TList</var> descendant which implements
a container for cached image lists. It allows indexed access to the image 
lists
in the container by their ordinal position. It also provides a method used to
create the image list references stored in the container.
</p>
<p>
TImageCacheItems is used in the implementation of the
<var>TImageListCache</var> class.
</p>
</descr>
<seealso>
<link id="TImageListCache"/>
</seealso>
</element>

<!-- private -->
<element name="TImageCacheItems.GetItem"/>
<element name="TImageCacheItems.GetItem.Result"/>
<element name="TImageCacheItems.GetItem.AIndex"/>
<element name="TImageCacheItems.GetItemForListener"/>
<element name="TImageCacheItems.GetItemForListener.Result"/>
<element name="TImageCacheItems.GetItemForListener.AListener"/>
<element name="TImageCacheItems.SetItem"/>
<element name="TImageCacheItems.SetItem.AIndex"/>
<element name="TImageCacheItems.SetItem.AValue"/>

<element name="TImageCacheItems.Notify">
<short>
Notifies observers when a value in the container has been changed.
</short>
<descr/>
<seealso>
<link id="#rtl.classes.TList">TList</link>
</seealso>
</element>

<!-- argument Visibility: default -->
<element name="TImageCacheItems.Notify.Ptr">
<short>Untyped Pointer to the value for the change notification.</short>
</element>

<!-- argument Visibility: default -->
<element name="TImageCacheItems.Notify.Action">
<short>Action for the notification (Add, Extract, Delete).</short>
</element>

<!-- function Visibility: public -->
<element name="TImageCacheItems.GetNew">
<short>
Allocates and stores a new image list reference in the container.
</short>
<descr>
<p>
<var>GetNew</var> is a <var>PImageCacheItem</var> function used to allocate 
and
store a new reference to an image list in the container. GetNew calls
<var>New</var> to allocate the storage needed for the return value. The
<var>Add</var> method is called to append the reference to the storage for
the container.
</p>
</descr>
<seealso>
<link id="#rtl.classes.TList.Add">TList.Add</link>
</seealso>
</element>

<!-- function result Visibility: default -->
<element name="TImageCacheItems.GetNew.Result">
<short>Reference for an image list stored in the container.</short>
</element>

<!-- property Visibility: public -->
<element name="TImageCacheItems.Items">
<short>
Provides indexed access to image list references in the container.
</short>
<descr>
<p>
<var>Items</var> is an indexed <var>PImageCacheItem</var> property which
provides access to an image list reference in the container by its ordinal
position. Read and write access to the property value are redirected to
methods in the ancestor.
</p>
<p>
Items is the default property for the container.
</p>
</descr>
<seealso>
<link id="#rtl.classes.TList">TList</link>
</seealso>
</element>

<!-- argument Visibility: default -->
<element name="TImageCacheItems.Items.AIndex">
<short>Ordinal position in the container for the requested image list.</short>
</element>

<!-- object Visibility: default -->
<element name="TImageListCache">
<short>Implements a caching mechanism for image lists.</short>
<descr>
<p>
<var>TImageListCache</var> is a class which implements a caching mechanism for
<var>TCustomImageList</var> instances. It is used primarily to cache image
lists and images used for <var>Glyphs</var> in <var>TButtonGlyph</var>.
</p>
<p>
TImageListCache contains internal members that are used for the cache storage
and cache listener interfaces. The <var>RegisterBitmap</var> method is used to
initiate actions affecting the cache storage.
</p>
</descr>
<seealso>
<link id="#lcl.buttons.TButtonGlyph">TButtonGlyph</link>
</seealso>
</element>

<!-- private -->
<element name="TImageListCache.FItems"/>
<element name="TImageListCache.FImages"/>
<element name="TImageListCache.FListeners"/>
<element name="TImageListCache.FObsoletedCount"/>

<element name="TImageListCache.CheckRebuildNeed">
<short>
Determines if the cache storage needs to be rebuilt when the change
threshold is exceeded.
</short>
</element>

<element name="TImageListCache.GetImageListFor">
<short>
Gets a TCustomImageList instance with the specified image size.
</short>
<descr>
<p>
Called from the RegisterBitmap method when the cache item is retrieved for a 
registered cached listener.
</p>
</descr>
</element>
<element name="TImageListCache.GetImageListFor.Result">
<short>
Image list using the specified image size retrieved from the cache or created 
on demand.
</short>
</element>
<element name="TImageListCache.GetImageListFor.AWidth">
<short>Width for the images in the image list.</short>
</element>
<element name="TImageListCache.GetImageListFor.AHeight">
<short>Height for the images in the image list.</short>
</element>

<element name="TImageListCache.UnregisterBitmaps">
<short>
Marks an image list and its images as unused for the specified cache listener.
</short>
</element>
<element name="TImageListCache.UnregisterBitmaps.AListener">
<short>Cache listener removed in the method.</short>
</element>

<!-- constructor Visibility: public -->
<element name="TImageListCache.Create">
<short>Constructor for the class instance.</short>
<descr>
<p>
Allocates resources needed for internal members in the class instance.
</p>
</descr>
<seealso/>
</element>

<!-- destructor Visibility: public -->
<element name="TImageListCache.Destroy">
<short>Destructor for the class instance.</short>
<descr>
<p>
Frees resources allocated to internal members in the class instance,
including any stored images requested by cache listeners.
</p>
</descr>
<seealso/>
</element>

<!-- function Visibility: public -->
<element name="TImageListCache.RegisterListener">
<short>
Adds a listener for an image list stored in the cache.
</short>
<descr>
<p>
<var>RegisterListener</var> is a method used to add the specified cache
listener in <var>AListener</var> to the internal list of listener
interfaces. If AListener does not already exist in the list, it is added.
</p>
<p>
RegisterListener is called from the <var>RegisterBitmap</var> method.
</p>
</descr>
<seealso>
<link id="IImageCacheListener"/>
<link id="#rtl.classes.TInterfaceList">TInterfaceList</link>
</seealso>
</element>

<!-- function result Visibility: default -->
<element name="TImageListCache.RegisterListener.Result">
<short>
Position where the specified listener was stored in the internal list.
</short>
</element>

<!-- argument Visibility: default -->
<element name="TImageListCache.RegisterListener.AListener">
<short>
Listener interface added to the internal list.
</short>
</element>

<!-- procedure Visibility: public -->
<element name="TImageListCache.UnregisterListener">
<short>
Removes the specified cache listener from the internal list.
</short>
<descr>
<p>
<var>UnregisterListener</var> is a method used to remove the specified cache
listener from the internal list in the class instance. If <var>AListener</var>
exists in the interface list, the <var>UnregisterBitmaps</var> method is 
called
and the listener is removed from the list.
</p>
<p>
When the number of listeners in the list reaches <b>0</b>, the TImageListCache
singleton used for the image list cache is set to <b>Nil</b>.
</p>
</descr>
<seealso>
<link id="IImageCacheListener"/>
<link id="#rtl.classes.TInterfaceList">TInterfaceList</link>
</seealso>
</element>

<!-- argument Visibility: default -->
<element name="TImageListCache.UnregisterListener.AListener">
<short>Cache listener removed from the list.</short>
</element>

<!-- procedure Visibility: public -->
<element name="TImageListCache.RegisterBitmap">
<short>
Adds the specified bitmap to the image list for a cache listener.
</short>
<descr>
<p>
<var>RegisterBitmap</var> is a method used to register use the image in
<var>ABitmap</var> for the cache listener specified in <var>AListener</var>.
RegisterBitmap ensures that the cache listener and an image list exist in the
cache. The <var>RegisterListener</var> method is called is the listener is not
found in the cache. If an image list does not already exist in the cache, a
new cache item is allocated.
</p>
<p>
<var>ABitmap</var> can contain a "sliced" image, which has multiple adjacent
images each using the height for the bitmap. The image list in the cache is
configured to use the number of images indicated in the 
<var>ABitmapCount</var>
argument. Each image has the same height and width.
</p>
<p>
The cache listener in AListener is notified if an action caused a change to
the index positions used in the image list.
</p>
</descr>
<seealso>
<link id="#lcl.buttons.TButtonGlyph.Glyph">TButtonGlyph.Glyph</link>
<link id="#lcl.buttons.TButtonGlyph.Refresh">TButtonGlyph.Refresh</link>
</seealso>
</element>

<!-- argument Visibility: default -->
<element name="TImageListCache.RegisterBitmap.AListener">
<short>Interface for the cache listener for the bitmap.</short>
</element>

<!-- argument Visibility: default -->
<element name="TImageListCache.RegisterBitmap.ABitmap">
<short>Bitmap registered in the method.</short>
</element>

<!-- argument Visibility: default -->
<element name="TImageListCache.RegisterBitmap.ABitmapCount">
<short>Number of image "slices" in the bitmap.</short>
</element>

<!-- procedure Visibility: public -->
<element name="TImageListCache.Rebuild">
<short>Rebuilds the cache storage.</short>
<descr>
<p>
Removes unused image lists in the cache where the cache listener is no
longer registered. Deletes any cached images no longer needed for a
given cached image list. Notifies listeners of changes to cached image
indexes.
</p>
</descr>
<seealso/>
</element>

<!-- function Visibility: default -->
<element name="GetImageListCache">
<short>
Provides access to the TImageListCache singleton in the implementation.
</short>
<descr/>
<seealso/>
</element>

<!-- function result Visibility: default -->
<element name="GetImageListCache.Result">
<short>TImageListCache instance for the implementation.</short>
</element>

</module>
<!-- ImageListCache -->
</package>
</fpdoc-descriptions>