diff --git a/docs/xml/lcl/imglist.xml b/docs/xml/lcl/imglist.xml index a0815eaebf..7472be65ed 100644 --- a/docs/xml/lcl/imglist.xml +++ b/docs/xml/lcl/imglist.xml @@ -11,17 +11,17 @@ - [?] - + Type of an ImageList index (integer), unused! + Exists for Delphi compatibility only, but is unused there as well. - TChangeLink - class to notify when an Imagelist changes + Use a TChangelink to get notified of imagelist changes. - + @@ -52,35 +52,39 @@ - [?] - + Defines transparency and blending of rendered images. + [What's "blending"?] + Blending means that the BlendColor is applied to the image foreground, + to a certain degree (dithering). [right?] + - [?] + Applies 25% of BlendColor. - [?] + Applies 50% of BlendColor. - [?] + Draw using BkColor for the background, transparent if BkColor is clNone. - [?] + Always draw transparently, ignore BkColor and BlendColor. - [?] - + Indicates whether a mask shall be used in rendering an image. + [What's the effect of applying a mask?] + The mask specifies the transparent part of the image [right?] - [?] + Don't apply a mask. - [?] + Apply the mask. @@ -101,10 +105,20 @@

NOTE: A TCustomImageList is not a TBitmap collection. If a storage of distinct bitmaps is needed, create your own list of TBitMaps (array or TList). -

[What about Mask and ShareImages?] +

+ Please note also that inserting or moving images will affect the index of all following images, + what can cause trouble with index constants. In such cases a bitmap collection may better fit your needs. +

+ [What about Mask, HotSpot and ShareImages?]

+ Windows ImgageLists can contain a list of monochrome mask bitmaps, present when Masked=True. + [Does the LCL support this feature, or is only the TransparentColor used to make images transparent?] + - Currently only the insertion of Bitmaps is supported. Other image types should be rendered as bitmaps of Width and Height, which then can be inserted. + +

Currently only the insertion of Bitmaps is supported. Other image types should be rendered as bitmaps of Width and Height, which then can be inserted.

+

Image overlays also are unsupported.

+ @@ -122,61 +136,50 @@ - - - + The size of the allocated Data list, in number of images. - - - + Change flag, remembers changes while update notifications are locked (FUpdateCount > 0). - - - + List of TChangeLinks which are notified of changes. - - - - - + Holds the pixel data of all images. + + + + Counter for BeginUpdate/EndUpdate calls. - Allocates data for ACount images - - - - - - + Allocates data for ACount images, rounded up by AllocBy. - the number of images + The number of images to allocate room for. + The list only can increase. Use Clear to reduce it to the empty list. Insert bitmap (with split if necessary) into position AIndex with shifting other images. - Index to insert images + Where to insert the images. - Image handle + The image (BitMap) handle. - Mask handle + The mask (BitMap) handle. - Width in pixels + Width [of?] in pixels - Height in pixels + Height of all images in pixels. [?] @@ -240,7 +243,7 @@ - Internal function to notify the subscribed objects of a change of the imagelist. + Notifies all subscribed objects of a change in the imagelist. @@ -280,12 +283,6 @@ - - - - - - @@ -298,21 +295,15 @@ - - - DefineProperties - defines the properties of the ImageList (stored in a file) - - - - + - SetWidthHeight - set Width and Height of the images. - Writing clears the entire list. + Sets both the Width and Height of all images. + Changed values clear the entire list. @@ -339,7 +330,7 @@ - Writes the ImageList data into the stream + Writes the ImageList data into the stream. @@ -349,7 +340,7 @@ - Restores the ImageList data from the stream + Restores the ImageList data from the stream. @@ -384,7 +375,7 @@ - Add an Image and Mask bitmap to the list. Returns the index of the added image or -1 if unsucessful + Adds an Image and Mask bitmap to the list. Returns the index of the added image or -1 if unsucessful. 
   Adds one or more (bitmap width / imagelist width) bitmaps to the list.
@@ -405,91 +396,96 @@
       
       
       
-        Adds an icon to the list [not yet!?], returning the index of the icon or -1 if not successful
+        Adds an icon to the list, returning the index of the icon or -1 if not successful.
         Adding graphics other than bitmaps can be implemented by converting the graphics item into a bitmap, which then can be added to the image list.
           Most graphics classes support such a conversion, so that specialized methods are redundant.
         
-        
+        
       
       
         The index of the added icon, -1 if unsuccesful.
       
       
-        the Icon to be added.
+        The Icon to be added.
       
       
       
         
-          AddImages - adds images from another imagelist to the list
+          Adds images from another imagelist to the list.
         Both lists must have the same image Width and Height, else the old images are discarded.
         
         
       
       
         
-          AValue - the ImageList containing images to add
+          The ImageList containing the images to add.
       
       
       
         
-          AddMasked - adds one or more bitmaps to the list
+          Adds one or more (bitmap width / imagelist width) transparent bitmaps to the list.
         
-
-Every pixel of MaskColor will become transparent.
-
-Image can contain multiple images of the same Width and Height.
-
-Returns the index of the first added bitmap, or -1 if unsuccessful.
-

+          

+            Every pixel of MaskColor will become transparent.
+          

+            Image can contain multiple images of the same Width and Height.
+            The image width must be a multiple of Width, and the image height must equal Height,
+            else all old images in the list are discarded.
+          

         
         
         
       
       
-        The index of the [last?] added icon, -1 if unsuccesful.
+        The index of the first added image, -1 if unsuccesful.
       
       
-        A bitmap to be added
+        The bitmap to be added.
       
       
-        The color acting as transparant color
+        The color acting as transparant color.
       
       
       
         
-          AddLazarusResource - load TBitmap from lazarus resources and add it
+          Loads a bitmap from a lazarus resources and adds it.
       
       
-        [?]
+        Index of the first added image.
       
       
-        [?]
+        The name of the Lazarus resource.
       
       
-        [?]
+        The mask color for transparent images, clNone for solid (opaque) images.
       
       
       
         
-          Change - send change notifications.
+          Send change notifications, if the list has changed and updates are not locked.
         Notifies all members of the ChangeLinkList, and calls the OnChange handler.
         
         
       
       
       
-        
-          Clear - removes all images from the list.
+        Removes all images from the list.
         
         
         
       
       
       
-        Initialize the list for image(s) with the given height and width
-        The Width and Height is reset with every[? first only?] insertion of a bitmap.
-          It may be useful, however, to initialize a list for the insertion of graphics other than bitmaps,
-          so that the images can be rendered as bitmaps of the intended width and height, before they are inserted.
+        Initialize the list for image(s) with the given height and width.
+        
+          

+            This constructor overrides the default initial size of the images (16x16 pixels).
+          

+          
The Width and Height is reset with every insertion of a bitmap.
+          It may be useful, however, to initialize a list for the insertion of graphics other than bitmaps,
+          so that the images can be rendered as bitmaps of the intended width and height, before they are inserted.
+          

+        
         
         
       
@@ -501,7 +497,7 @@ Returns the index of the first added bitmap, or -1 if unsuccessful.
       
       
       
-        Delete the specified image(s)
+        Delete the specified image.
         
         
         
@@ -531,16 +527,16 @@ Returns the index of the first added bitmap, or -1 if unsuccessful.
         The image index.
       
       
-         If False, draw the image disabled.
+         If False, draw the image disabled (dithered).
      
       
-        
+        [?]
       
       
-        
+        [?]
       
       
-        
+        [?]
       
       
       
@@ -561,8 +557,8 @@ Returns the index of the first added bitmap, or -1 if unsuccessful.
       
       
         
-          GetHotSpot - returns the offset from the drawing[?] position to the image origin.
-        
+          Returns the offset from the drawing position to the image origin.
+        A HotSpot is used only in a TDragImageList, here it is (0,0).
         
         
       
@@ -578,12 +574,18 @@ Returns the index of the first added bitmap, or -1 if unsuccessful.
       
       
         
-          Insert one or more images into the list at the index position.
-        The insterted bitmap can consist of multiple images, of the same width and height, which become accessible as distinct images in the ImageList.
-
-The height of the inserted images must match the ImageList height, else the ImageList content is replaced by the added images. The width must be a multiple of the ImageList width, so that the list always contains an integral number of images.
-
-If Mask is nil, the inserted images have no transparent parts.
+          Inserts one or more images into the list at the index position.
+        
+          

+          The inserted bitmap can consist of multiple images, of the same width and height, which become accessible as distinct images in the ImageList.
+          

+            The height of the inserted images must match the ImageList height, else the ImageList content is replaced by the added images.
+            The width must be a multiple of the ImageList width, so that the list always contains an integral number of images.
+          

+            If Mask is nil, the inserted images have no transparent parts.
+            Use InsertMasked to insert bitmaps with a specific transparent color.
+          

+        
         
         
       
@@ -612,7 +614,7 @@ If Mask is nil, the inserted images have no transparent parts.
       
       
         
-          InsertMasked - adds one or more transparent bitmaps to the list.
+          Adds one or more transparent bitmaps to the list.
         MaskColor is the RGB color of the transparent pixels. Every occurence of a MaskColor pixel will be converted into a transparent pixel.
         
         
@@ -620,18 +622,18 @@ If Mask is nil, the inserted images have no transparent parts.
         
       
       
-        The index of the inserted image
+        The index of the inserted image.
       
       
-        The bitmap to be inserted
+        The bitmap to be inserted.
       
       
-        The color acting as transparant color
+        The color acting as transparant color.
       
       
       
         
-          Move an image from index CurIndex to NewIndex
+          Move an image from index CurIndex to NewIndex.
         
         
         
@@ -666,24 +668,25 @@ If Mask is nil, the inserted images have no transparent parts.
       
         
           ReplaceMasked - replaces the indexed image with the image given.
-        Every pixel of MaskColor will be converted to transparent
+        Every pixel of MaskColor will be converted to transparent.
         
         
           
+          
         
       
       
-        the index of the replaceded image
+        The index of the replaced image.
       
       
-        A bitmap image
+        A bitmap image.
       
       
-        The color acting as transparant color
+        The color acting as transparant color.
       
       
       
-        Registers an object to get notified of a change of the imagelist
+        Registers an TChangeLink object to get notified of a change of the imagelist.
         
         
         
@@ -705,50 +708,56 @@ If Mask is nil, the inserted images have no transparent parts.
       
       
         
-          AllocBy - the number of images in every allocated block.
-        
+          The length of the image list is increased in multiples of AllocBy images. Default is 4.
+        Other list types allow to set the list Capacity directly - not so for an ImageList.
         
       
       
       
         
-          BlendColor - the colour for a blend[???]
+          The color for used in blending (dithering) an image.
         
-        
+        
       
       
       
         
-          The background color for transparent parts.
-        
+          The background color to use for transparent parts.
+        
+          
BkColor is intended to speed up drawing of transparent images,
+          on a background of known color (=BkColor). In this case the image can be drawn opaque,
+          eliminating the need for really masking out and merging with existing background.
+          
[does this really apply? depending on the widgetset?]
+          

+        
         
       
       
       
         
-          Count - number of images in the list
+          The number of images in the list
         
         
       
       
       
         
-          DrawingStyle - focus, selected, normal or transparent
+          The default drawing style - focussed, selected, normal or transparent.
         
         
       
       
       
         
-          Height of the images in the list.
-        Writing clears the entire list.
+          The unique height of all images in the list.
+        Setting to an different value clears the entire list!
         
       
       
       
         
-          Width of all images in the list
-        Writing clears the entire list.
+          The unique width of all images in the list.
+        Setting to an different value clears the entire list!
         
       
       
@@ -761,22 +770,24 @@ If Mask is nil, the inserted images have no transparent parts.
       
       
         
-          Masked - if True, a mask [what's this?] is applied to the bitmap.
-        
+          True when mask images are stored with every image (unused!).
+        This property exists only for Delphi compatibility[?]
         
       
       
       
         
-          ShareImages - if True, images are allowed to be shared[???]
-        
+          True when this image list is shared. Unused!
+        This property exists only for Delphi compatibility.
+          True means that the imagelist widget is freed together with the ImageList[?]
+        
         
       
       
       
         
-          ImageType - an image or a mask
-        
+          Unused!
+        This property exists only for Delphi compatibility[?]
         
       
       
@@ -784,7 +795,7 @@ If Mask is nil, the inserted images have no transparent parts.
           FillDescription - fills the description with the default info of the imagedata
       
       
-        the description to fill
+        the description to copy
       
       
       
@@ -802,15 +813,17 @@ If Mask is nil, the inserted images have no transparent parts.
       
         how to copy
       
+      
       
-        Copies the image description and the data pointer
+        Exports the entire internal image (color array) and description.
       
       
         
       
+      
       
         
-          GetRawImage - primitive method for loading an image: you have to fill in all the description fields yourself
+          Exports an image as TRawImage.
       
       
         the index of the image to copy
@@ -818,33 +831,40 @@ If Mask is nil, the inserted images have no transparent parts.
       
         the target bitmap
       
+      
       
         
           Reference to the imagelist
       
+      
       
         
-          CheckIndex - method for checking whether the indexed item is supposed to be inserted (default condition is False)
+          Assures that Index is not out of the list bound.
+        
+          Raises an EInvalidOperation exception when the index is out of bounds.
+        
       
       
-        
+        The index to check.
       
       
-        
+        Set to True when the index is used for insertion (default is False).
       
+      
       
         
-          GetReferenceHandle - returns a handle for the reference
+          Returns the Handle of the Reference.
       
       
-        
+        The widget handle.
       
+      
       
         
           Instructs the widgtset to create an imagelist.
       
       
-        Handle to created imagelist
+        Reference object for the created widget.
       
       
         ignored
@@ -870,10 +890,10 @@ If Mask is nil, the inserted images have no transparent parts.
         This is an expensive operation, since both imagelists are written into memory streams, which then are compared bytewise.
       
       
-        
+        True when the image lists are equal.
       
       
-        
+        The object (ImageList) to compare with.