paweld/lazarus
1
0
Fork 0
mirror of https://gitlab.com/freepascal.org/lazarus/lazarus.git synced 2025-04-21 14:39:27 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: update ImageList

Browse Source 
git-svn-id: trunk@23398 -
This commit is contained in:
dodi 2010-01-07 13:49:10 +00:00
parent 250ca33f7b
commit 0ffd8bc17f
4 changed files with 127 additions and 91 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
docs/xml/lcl/controls.xml
View File

@ -1072,7 +1072,19 @@ mrLast=mrYesToAll=10</descr>
<element name="TDragImageList">
<short>
<var>TDragImageList</var> - a list of Images to be dragged</short>
<descr/>
<descr>A drag image is shown when a DragImageList is supplied at all, <b>and</b> when no accepting target is under the mouse, or the source control style includes csDisplayDragImage, or AlwaysShowDragImage is set in the DragObject.
In drag-dock operations typically no drag image is shown, since the DockRect frame already gives all required visual feedback.
This is a vague idea of the usage of this class:
SetDragImage selects an image from the list, and establishes an hotspot (of the image)
DragLock specifies a window (handle), to which the image should be attached (what exactly does this mean?)
ShowDragImage shows the image, combined with the mouse cursor. The HotSpot indicates the shift of the image, relative to the current mouse position.
HideDragImage hides the image, shown at its last position.</descr>
<errors/>
<seealso/>
</element>
@ -1483,8 +1495,18 @@ All messages are sent to the target control, except dmDragDrop and dmDragCancel
</element>
<!-- object Visibility: default -->
<element name="TDragObject">
<short>
<var>TDragObject</var> - the base class for many objects that are designed to be dragged and dropped</short>
<short>Base class for managing drag operations and feedback</short>
<descr>Every dragging operation has an associated DragObject, holding references to the source and target controls, and other parameters for the customization of the visual user feedback.
A default DragObject is created automatically when a dragging operation starts, and is destroyed when the operation has ended, so that you must not take special care on it. But an application can provide a customized DragObject in the <link id="TControl.OnStartDrag"/> or <link id="TControl.OnStartDock"/> an OnStartDrag handler of the source control (being dragged).
TDragObject is the ancestor of an whole tree of dragging objects, with the main branches supporting either drag-drop or dock-drop operations. The type of the operation is determined from the <link id="TControl.DragKind"/> property of the source control. In contrast to the Delphi implementation, Lazarus has moved a couple of methods into the drag performers, so that these are no more available for customization.
A Lazarus DragObject mainly supplies the cursor and images, used in visual user feedback. Drag-drop operations typically signal acceptance of an possible drop by variations of the mouse cursor, and optionally can attach to it shapes of the dragged object(s). Dock-drop operations instead show a docking rectangle, that snaps to possible target locations when the mouse moves over docksites.</descr>
<seealso>
<link id="TDragControlObject"/>
<link id="TDragDockObject"/>
</seealso>
</element>
<!-- variable Visibility: private -->
<element name="TDragObject.FDragTarget">
@ -1567,8 +1589,8 @@ All messages are sent to the target control, except dmDragDrop and dmDragCancel
<!-- function Visibility: protected -->
<element name="TDragObject.GetDragCursor">
<short>
<var>GetDragCursor</var> - returns the cursor for use during dragging</short>
<descr/>
<var>GetDragCursor</var> - returns the current cursor type while dragging</short>
<descr>In drag-drop operations the cursor signals acceptance or rejection of an drop, depending on Accepted.</descr>
<errors/>
<seealso/>
</element>
@ -1592,7 +1614,7 @@ All messages are sent to the target control, except dmDragDrop and dmDragCancel
<element name="TDragObject.GetDragImages">
<short>
<var>GetDragImages</var> - returns a list of images for dragging</short>
<descr/>
<descr>The returned <link id="TDragImageList"/> provides methods for the selection and display of an image, shown while dragging.</descr>
<errors/>
<seealso/>
</element>
@ -1729,7 +1751,7 @@ All messages are sent to the target control, except dmDragDrop and dmDragCancel
</element>
<!-- procedure Visibility: public -->
<element name="TDragObject.HideDragImage">
<short>Procedure for hiding the drag image during movement</short>
<short>Hides the drag image</short>
<seealso>
<link id="#lcl.Controls.TDragObject.ShowDragImage">ShowDragImage</link>
</seealso>
@ -1744,7 +1766,7 @@ All messages are sent to the target control, except dmDragDrop and dmDragCancel
</element>
<!-- procedure Visibility: public -->
<element name="TDragObject.ShowDragImage">
<short>Procedure for keeping the image visible during movement</short>
<short>Shows the drag image</short>
<seealso>
<link id="#lcl.Controls.TDragObject.HideDragImage">HideDragImage</link>
</seealso>
@ -1771,13 +1793,13 @@ All messages are sent to the target control, except dmDragDrop and dmDragCancel
</element>
<!-- property Visibility: public -->
<element name="TDragObject.DragTarget">
<short>The control object to which the current object is to be dragged (target)</short>
<short>The control to which the current object is dragged (target)</short>
<descr>Reads or writes flag with identity of the target control object to which the currect object is to be dragged</descr>
</element>
<!-- property Visibility: public -->
<element name="TDragObject.Dropped">
<short>Has the drag object been dropped yet?</short>
<descr>Boolean property, true if the object has been dropped; reads or writes a flag with this information</descr>
<short>Indicates whether the drag object has been dropped yet</short>
<descr>False while dragging is in progress or has been aborted.</descr>
</element>
<!-- property Visibility: public -->
<element name="TDragObject.MouseDeltaX">
@ -5717,7 +5739,7 @@ On dmDragDrop: invokes DragDrop or, if docking, the target.DockDrop. Returns not
</element>
<!-- procedure Visibility: protected -->
<element name="TControl.DoEndDrag">
<short>End the dragging process</short>
<short>Invokes the OnEndDrag handler</short>
<descr/>
<errors/>
<seealso/>
@ -14108,8 +14130,7 @@ One value of InsertAt (alCustom) is reserved for notebook docking, where DropCtl
</element>
<!-- function Visibility: public -->
<element name="TDragImageList.SetDragImage">
<short>
<var>SetDragImage</var> - place the indexed drag image at the specified location, returning True if successful</short>
<short>Determines the image to be shown</short>
<descr/>
<errors/>
<seealso/>
@ -14214,12 +14235,13 @@ One value of InsertAt (alCustom) is reserved for notebook docking, where DropCtl
<!-- property Visibility: public -->
<element name="TDragObject.AlwaysShowDragImages">
<short>Should the image of dragged objects always be shown?</short>
<descr/>
<descr>This is another chance for enforcing the display of a drag image, even if a drop is acceptable.
[where to describe the various conditions?]</descr>
<seealso/>
</element>
<!-- property Visibility: public -->
<element name="TDragObject.Control">
<short>The control that is to be dragged</short>
<short>The control that is dragged (source)</short>
<descr/>
<seealso/>
</element>
@ -16473,11 +16495,12 @@ The Result is always True (unless overridden).</descr>
</element>
<element name="TDragObject.AutoCreated">
<short>
<var>AutoCreated</var> - if True, the drag object is automatically created</short>
<var>AutoCreated</var> - if True, the drag object was created automatically</short>
<descr>This property is of little use, more important is the AutoFree property.</descr>
</element>
<element name="TDragObject.EndDrag">
<short>
<var>EndDrag</var> - method for terminating drag of nominated object at specified location</short>
<short>Called when a dragging operation ends.</short>
<descr>The default implementation calls source.DoEndDrag, which in turn invokes an OnEndDrag handler.</descr>
</element>
<element name="TDragDockObject.DockOffset">
<short>
@ -16867,6 +16890,14 @@ Handling mouse messages while dragging is not required. Painting of the docksite
<link id="TDockManager.PaintSite"/>
</seealso>
</element>
<element name="TDragObject.AutoCreate">
<short>Special constructor, enforcing the destruction of the object at the end of the dragging operation</short>
<descr>This constructor sets the AutoCreated and AutoFree flags. AutoFree is tested by the DragManager at the end of the dragging operation.</descr>
</element>
<element name="TDragObject.AutoFree">
<short>Indicates whether the object shall be destroyed at the end of the dragging operation</short>
<descr>This is a Lazarus specific property, introduced to get rid of the special Delphi TDrag...Ex classes.</descr>
</element>
</module>
<!-- Controls -->
</package>

11
docs/xml/lcl/graphics.xml
View File

@ -7773,14 +7773,13 @@ Checks for the presence of a valid Lazarus Resource, then uses
<!-- object Visibility: default -->
<element name="TIcon">
<short>
<var>TIcon</var> - icons, small images typically associated with applications, controls, etc. Stored in files with .ico extension</short>
<var>TIcon</var> - icons, small images typically associated with applications, controls, etc.</short>
<descr>
<p>
<var>TIcon</var> reads and writes .ICO file format.</p>
<p>A .ico file typically contains several versions of the same image. </p>
<p>When loading, the largest/most colourful image is loaded as the <var>TBitmap</var> and so can be handled as any other bitmap. Any other versions of the images are available via the <var>Bitmaps</var> property</p>
<p>Writing is not (yet) implemented.</p>
<p>Icons can be loaded from .ICO files, or from Lazarus resources.</p>
<p>An icon resource typically contains several versions of the same image, in multiple resolutions and color depths. </p>
<p>When loading, the largest/most colourful image is loaded as the <var>Bitmap</var> property, and so can be handled as any other bitmap.</p>
</descr>
<errors>Writing to icon files is not (yet) implemented.</errors>
</element>
<!-- variable Visibility: private -->
<element name="TIcon.FBitmaps">

6
docs/xml/lcl/graphtype.xml
View File

@ -235,9 +235,9 @@
</element>
<!-- variable Visibility: default -->
<element name="TRawImageDescription.BitsPerPixel">
<short>
<var>BitsPerPixel</var> - can be greater than Depth</short>
<descr/>
<short>Bits stored per pixel</short>
<descr>
<var>BitsPerPixel</var> can be greater than the logical (used) <var>Depth</var>.</descr>
<seealso/>
</element>
<!-- variable Visibility: default -->

132
docs/xml/lcl/imglist.xml
View File

@ -182,31 +182,17 @@
<element name="TCustomImageList">
<short>
<var>TCustomImageList</var> - base class for <var>TImageList</var> (not the same as a <var>TBitmap</var> collection)</short>
<descr>
<p>
<printshort id="TCustomImageList"/>
</p>
<p>Ancestor of <var>TDragImageList</var> which is base class for <var>TImageList</var> in Unit <var>Controls</var>
</p>
<pre>Delphi's TCustomImageList is based on the Win32 imagelists which has
internally only one bitmap to hold all images. This reduces handle
allocation.
The original Lazarus TCustomImageList implementation was LCL only based, so for
other platforms the single bitmap implementation had some speed drawbacks.
Therefore it was implemented as a list of bitmaps, however it doesn't reduce
handle allocation.
In its current form, the imagelist is again based on a 32bit RGBA raw
imagedata and the widgetset is notified when images are added or removed,
so the widgetset can create its own optimal storage. The LCL keeps only the
data, so all transparency info will be stored cross platform. (not all
platforms have an 8bit alpha channel).
<descr>An ImageList contains images (bitmaps or icons) of the same Width and Height, accessible by index. The images are stored in one big (wide) bitmap, whose width is Width*Count. When an image of a different Width or Height is inserted, the previous contents of the list are discarded!
NOTE: due to its implementation, the TCustomImageList is not a TBitmap
collection. If a fast storage of bitmaps is needed, create your own list!
</pre>
<p/>
</descr>
<errors/>
It's okay, however, to insert an imagelist-like bitmap, that contains multiple bitmaps of the same Width and Height as used by the ImageList. This allows to insert e.g. other (compatible) ImageLists, or bitmaps for multiple states of essentially the same image (button pressed, released and disabled).
Transparency is implemented in the alpha channel of the raw 32 bit RGBA imagedata array - but not all platforms support such an alpha channel. [What exactly does this mean to the user?]
The painting of an image from the list is handled by the widgetset, no bitmap or icon component is involved. The widgetset can use a different internal organization of the data, optimized for immediate painting of an image.
<b>NOTE:</b> A TCustomImageList is <b>not</b> a TBitmap collection.
If a storage of distinct bitmaps is needed, create your own list of TBitMaps (array or TList).</descr>
<errors>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.</errors>
<seealso/>
</element>
<!-- variable Visibility: private -->
@ -533,8 +519,7 @@
</element>
<!-- procedure Visibility: public -->
<element name="TCustomImageList.WriteData">
<short>
<var>WriteData</var> to a stream</short>
<short>Writes the ImageList data into the stream</short>
<descr/>
<errors/>
<seealso/>
@ -545,8 +530,7 @@
</element>
<!-- procedure Visibility: public -->
<element name="TCustomImageList.ReadData">
<short>
<var>ReadData</var> from a stream</short>
<short>Restores the ImageList data from the stream</short>
<descr/>
<errors/>
<seealso/>
@ -559,7 +543,10 @@
<element name="TCustomImageList.BeginUpdate">
<short>
<var>BeginUpdate</var> - start updating the data</short>
<descr/>
<descr>Use together with EndUpdate to speed up the insertion of multiple images.
Every BeginUpdate must be matched by an EndUpdate, i.e. update operations can be nested.
</descr>
<errors/>
<seealso/>
</element>
@ -567,14 +554,17 @@
<element name="TCustomImageList.EndUpdate">
<short>
<var>EndUpdate</var> - finish updating the data</short>
<descr/>
<descr>Decrements the internal UpdateCount and, when it reaches zero, does whatever is required to reflect the new content.
</descr>
<errors/>
<seealso/>
<seealso>
<link id="TCustomImageList.Change"/>
</seealso>
</element>
<!-- function Visibility: public -->
<element name="TCustomImageList.Add">
<short>
<var>Add</var> an Image and Mask to the list. Returns the index of the added image or -1 if unsucessful</short>
<var>Add</var> an Image and Mask bitmap to the list. Returns the index of the added image or -1 if unsucessful</short>
<descr/>
<errors/>
<seealso/>
@ -631,9 +621,8 @@
</element>
<!-- function Visibility: public -->
<element name="TCustomImageList.AddIcon">
<short>
<var>AddIcon</var> - add an icon to the list, returning the index of the icon or -1 if not successful (not yet supported)</short>
<descr/>
<short>Adds an icon to the list (not yet!), returning the index of the icon or -1 if not successful</short>
<descr>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.</descr>
<errors/>
<seealso/>
</element>
@ -649,7 +638,7 @@
<element name="TCustomImageList.AddImages">
<short>
<var>AddImages</var> - adds images from another imagelist to the list</short>
<descr/>
<descr>Both lists must have the same image Width and Height, else the old images are discarded.</descr>
<errors/>
<seealso/>
</element>
@ -660,8 +649,12 @@
<!-- function Visibility: public -->
<element name="TCustomImageList.AddMasked">
<short>
<var>AddMasked</var> - adds one or more bitmaps to the list. Every instance of MaskColor will be converted to transparent. Returns index of added bitmap, or -1 if unsuccessful</short>
<descr/>
<var>AddMasked</var> - adds one or more bitmaps to the list</short>
<descr>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.</descr>
<errors/>
<seealso/>
</element>
@ -695,8 +688,8 @@
<!-- procedure Visibility: public -->
<element name="TCustomImageList.Change">
<short>
<var>Change</var> - software method to force <var>OnChange</var> event</short>
<descr/>
<var>Change</var> - send change notifications</short>
<descr>Notifies all members of the ChangeLinkList, and calls the <var>OnChange</var> handler.</descr>
<errors/>
<seealso/>
</element>
@ -710,9 +703,8 @@
</element>
<!-- constructor Visibility: public -->
<element name="TCustomImageList.CreateSize">
<short>
<var>CreateSize</var> - runtime constructor for image(s) with given height and width</short>
<descr/>
<short>Initialize the list for image(s) with the given height and width</short>
<descr>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.</descr>
<errors/>
<seealso/>
</element>
@ -726,9 +718,7 @@
</element>
<!-- procedure Visibility: public -->
<element name="TCustomImageList.Delete">
<short>
<var>Delete</var> the image specified by <var>AIndex</var>
</short>
<short>Delete the specified image</short>
<descr/>
<errors/>
<seealso/>
@ -746,10 +736,8 @@
</element>
<!-- procedure Visibility: public -->
<element name="TCustomImageList.Draw">
<short>
<var>Draw</var> the image specified by <var>AIndex</var> on the specified <var>canvas</var> at position <var>AX, AY</var>
</short>
<descr/>
<short>Paint an image</short>
<descr>Paints the image specified by <var>AIndex</var> on <var>Canvas</var> at position <var>AX, AY</var>.</descr>
<errors/>
<seealso/>
</element>
@ -775,8 +763,7 @@
</element>
<!-- procedure Visibility: public -->
<element name="TCustomImageList.GetBitmap">
<short>
<var>GetBitmap</var> - creates a copy of the indexed image</short>
<short>Copies the selected image into the given bitmap</short>
<descr/>
<errors/>
<seealso/>
@ -853,8 +840,12 @@
<!-- procedure Visibility: public -->
<element name="TCustomImageList.Insert">
<short>
<var>Insert</var> one or more bitmaps into the list at the index position. If Mask is nil, the image has no transparent parts</short>
<descr/>
<var>Insert</var> one or more images into the list at the index position.</short>
<descr>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 <b>replaced</b> 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.</descr>
<errors/>
<seealso/>
</element>
@ -888,10 +879,12 @@
<!-- procedure Visibility: public -->
<element name="TCustomImageList.InsertMasked">
<short>
<var>InsertMasked</var> - adds one or more bitmaps to the list. Every instance of MaskColor will be converted to transparent</short>
<descr/>
<var>InsertMasked</var> - adds one or more transparent bitmaps to the list.</short>
<descr>MaskColor is the RGB color of the transparent pixels. Every occurence of a MaskColor pixel will be converted into a transparent pixel.</descr>
<errors/>
<seealso/>
<seealso>
<link id="TCustomImageList.Insert"/>
</seealso>
</element>
<!-- argument Visibility: default -->
<element name="TCustomImageList.InsertMasked.Index">
@ -908,10 +901,13 @@
<!-- procedure Visibility: public -->
<element name="TCustomImageList.Move">
<short>
<var>Move</var> an image from the <var>CurIndex </var>location to <var>NewIndex</var> location</short>
<var>Move</var> an image from index <var>CurIndex</var> to <var>NewIndex</var>
</short>
<descr/>
<errors/>
<seealso/>
<seealso>
<link id="TCustomImageList"/>
</seealso>
</element>
<!-- argument Visibility: default -->
<element name="TCustomImageList.Move.CurIndex">
@ -925,7 +921,7 @@
<element name="TCustomImageList.Replace">
<short>
<var>Replace</var> an indexed image with the Bitmap given</short>
<descr/>
<descr>AMask can be nil, if the image has no transparent parts.</descr>
<errors/>
<seealso/>
</element>
@ -959,10 +955,12 @@
<!-- procedure Visibility: public -->
<element name="TCustomImageList.ReplaceMasked">
<short>
<var>ReplaceMasked</var> - replaces the indexed image with the image given. Every instance of MaskColor will be converted to transparent</short>
<descr/>
<var>ReplaceMasked</var> - replaces the indexed image with the image given.</short>
<descr>Every instance of MaskColor will be converted to transparent</descr>
<errors/>
<seealso/>
<seealso>
<link id="TCustomImageList.InsertMasked"/>
</seealso>
</element>
<!-- argument Visibility: default -->
<element name="TCustomImageList.ReplaceMasked.Index">
@ -1131,6 +1129,14 @@
<var>StretchDraw</var> - draw the image to fill the canvas</short>
</element>
<element name="TCustomImageList.WSRegisterClass" link="#LCL.LCLClasses.TLCLComponent.WSRegisterClass"/>
<element name="TCustomImageList.InternalInsert"/>
<element name="TCustomImageList.Equals">
<short>Check for equivalence with another ImageList</short>
<descr>This is an expensive operation, since both imagelists are written into memory streams, which then are compared bytewise.</descr>
</element>
<element name="TCustomImageList.GetFullRawImage">
<short>Copies the image description and the data pointer</short>
</element>
</module>
<!-- ImgList -->
</package>