Contains classes, types, and routines used in graphics applications.

graphics.pp contains classes, types, and routines used to represent graphic images in a Lazarus Component Library (LCL) application. The following classes are added to the registered class list used by the Run-time Library (RTL):

- TBitmap
- TPixmap
- TPortableNetworkGraphic
- TPortableAnyMapGraphic (when not explicitly disabled)
- TJpegImage (when not explicitly disabled)
- TGIFImage (when not explicitly disabled)
- TPicture
- TFont
- TPen
- TBrush
- TRegion

This file is part of the Lazarus Component Library (LCL).

Pointer to the TColor type.

The base type used for the definition is dependent on the FPC compiler version used to build the LCL. Starting in FPC version 3.2.3, the base type is the type defined in the System.UITypes namespace in the FPC run-time library (RTL). For previous compiler versions, the base type is a pointer to TColor.

This is done to prevent type conflicts when both System.UITypes and LCL units are used.

Color type used by most LCL drawing functions.

TColor is an alias for the TGraphicsColor type in GraphType.pp from the LazUtils package. TColor allows hexadecimal values in the range -$7FFFFFFF-1..$7FFFFFFF and represent the minimum and maximum values for the Long data type.

Bytes in the hexadecimal value are used as follows:

$OOBBGGRR

OO
  Opacity values are not used for standard LCL colors. $1F is reserved for clNone. $20 is reserved for clDefault.
BB
  Blue color level. $00 is none. $FF is full.
GG
  Green color level. $00 is none. $FF is full.
RR
  Red color level. $00 is none. $FF is full.

There are predefined color constants like those in Delphi, such as: clBlack, clRed, clGreen, and clBlue. There are extended color constants, like: clMoneyGreen and clMedGray. There are special color constants like: clDefault and clNone.

Additionally, there are system color constants like: clWindowText and clForm. These constants have a color and/or pattern depending on the users theme, the LCL control, or the drawing tool (Pen, Brush, Font).

See ColorToRGB and RGBToColor.

TGraphicsColor
Represents pitches (or spacings) used in typefaces.

Used to implement the Pitch member in TFontData and TFont.

Font uses the default spacing defined for the typeface.
Font uses variable pitch (or proportional spacing).
Font uses fixed pitch (or mono-spacing).
Alias for the String type.

TFontName is an alias for the String type. Not used in the current LCL implementation.

Short String type used for typeface names.

TFontDataName is a Short String type used to represent typeface names, and is used to implement the Name member in TFontData. TFontData is defined with a maximum length of LF_FACESIZE-1.

Be aware that the definition can result in truncation of typeface names longer than 31 characters.
LF_FACESIZE
Represents font styles or variants.
TFontStyle
is an enumerated type with values used to represent a style or variant for a typeface. Value(s) from TFontStyle are stored in the TFontStyles and TFontStylesBase set types, and used to implement the Style members in TFontData and TFont.
Bold font style.
Italic font style.
Strike-out (or strike-through) font style.
Underline font style.
Set type used to store TFontStyle value(s).

TFontStyles is a set type used to store 0 (zero) or more values from the TFontStyle enumeration.

Set type used to store TFontStyle value(s).

TFontStylesBase is a set type used to store 0 (zero) or more values from the TFontStyle enumeration. It is used to implement the Style member in TFontData and TFont.

Represents a font character set as a numeric value.

TFontCharSet is a range type with values representing font character sets. TFontCharSet is limited to integer values in the range 0..255, and correspond to the character set identifiers as used in the Win32 GDI LogFont structure. For other platforms, or widgetsets, the values used refer to constants defined in the widgetset interface.

TFontCharSet is the type used to implement the CharSet member in TFontData and TFont.

Font output quality, like anti-aliasing.

TFontQuality is an enumerated type with values that represent the output quality for fonts. Values in the enumeration control how carefully font attributes are applied to output using a font.

There are situations where an enumeration value may not produce the desired result. ClearType and ClearType Natural anti-aliasing algorithms are oriented to display usage. They cannot be applied to printed output in general. They are ignored for fonts that are not TrueType or OpenType fonts with TrueType outlines. Postscript Type 1 fonts, and Postscript OpenType fonts without TrueType outlines, do not use ClearType anti-aliasing. Bitmap, vector, and device fonts cannot use ClearType anti-aliasing. Fonts which contain embedded bitmaps, like most East Asian fonts, do not use ClearType anti-aliasing.

TFontQuality is the type used to implement the Quality member in TFontData and TFont.

Default font quality; used when appearance is not important.
Prefer other font features (size, style) against output quality.
Appearance of the font is less important than when fqProof is used. Generally offers lower quality than fqProof or fqDefault.
Prefer output quality against other font features (size, style).
Font quality is more important exactly reproducing the size or style for the font.
Disable font anti-aliasing.
Use font anti-aliasing.
The font is always anti-aliased when supported, and the font size is not too small or too large.
Use ClearType font anti-aliasing when available.
Use Clear Type Natural font anti-aliasing when available.
Contains information about a font used in an application.

TFontData is a record type used to hold information about a font in an application. It provides access to the system handle for the font, as well as attributes for the font. Values in the record are read from the font file when its handle is assigned, or when the default font from the widgetset interface is assigned.

TFontData is the type used to implement the FontData property in TFont.

The Operating System Handle for the Font.
The Height (in pixels) for the Font.
The Pitch (layout style) for the Font.
The Style (or variant) for the Font.

Style is a TFontStylesBase member which contains the style or variant for the typeface in a font. See TFontStyle for more information about the enumeration values and their meanings.

The character set for a Font as an Integer value.

CharSet is a TFontCharSet member which stores an Integer identifier for a font character set. Its value identifies the character set or encoding supported in the font.

The actual value is specific to the Operating System and/or widgetset for the application. For the Windows platform, it corresponds to the value in TLogFont as retrieved from the Win32 GDI LogFont routine. Other platforms and widgetsets rely on the mechanism native to the interface like: X-Fonts, device contexts, or whatever API weirdness the Mac developers could dream up. The native values are translated to to the value represented in the member as an Integer.

Output quality for the font.

Quality is a TFontQuality member which contains an enumeration value which indicates the output quality for the font. The output quality determines how carefully font attributes are applied to output using the font.

See TFontQuality for more information about the enumeration values and their meanings.

The Name (as a string) of the current Font.
Default font data used for new TFont instances.

New TFont instances are initialized with the values in this structure.

The default font is chosen by the interfaces depending on the context. For example, there can be a different default font for a button and a group box.

Represents the text layout used to render text in its rectangle.

TTextLayout is an enumerated type with values that indicate the layout used for text in its rectangle. TTextLayout is the type used to implement the Layout member in TTextStyle.

Text is aligned to the top of the text rectangle.
Text is aligned to the center of the text rectangle.
Text is aligned to the bottom of the text rectangle.
The Style of the Text to be drawn in a rectangle.
TTextStyle is a packed record type which contains setting used when a control draws text using TextOut or TextRect. It is used to save, restore and configure values needed for the canvas which renders a control.
Horizontal alignment in the text rectangle.
Vertical alignment in the text rectangle.
Indicates if the text is rendered as a single line.

When set to True and WordBreak is False, CR (#13) and LF (#10) are handled as standard characters and do not result in line breaks.

Causes text to be clipped to the text rectangle.
Causes Tab characters to be replaced with spaces.

When set to True, occurrences of Tab (#9) characters are replaced with the appropriate number of space characters. The default value is 8.

Draws a single Ampersand characters as an accelerator key decoration.

When set to True, the first Ampersand (&) character on a line is drawn as the decoration used for an accelerator key. The character after the Ampersand contains the key for the accelerator. When True, double Ampersand (&&) characters are required to draw an Ampersand character in the text.

Causes a long line of text to be word-wrapped.

When set to True, a line of text that is larger than the available width in the rectangle is word-wrapped into multiple lines at word boundaries.

Causes the output to be drawn with full opacity.
Causes the system font to be used instead of the canvas font.
For RightToLeft text reading (text direction).
Indicates if text is "ellipsified" when too long for its rectangle.

If a line of text is too long to fit between left and right boundaries for the text rectangle, the text is shortened and an Ellipsis (...) is added to the end of the text value. Preference is given to WordBreak when set.

Represents the solid pen style.

Alias for the FPCanvas.psSolid enumeration value in the FCL.

Represents the dashed pen style.

Alias for the FPCanvas.psDash enumeration value in the FCL.

Represents the dotted pen style.

Alias for the FPCanvas.psDot enumeration value in the FCL.

Represents the dash-dot pattern pen style.

Alias for the FPCanvas.psDashDot enumeration value in the FCL.

Represents the dash-dot-dot pattern pen style.

Alias for the FPCanvas.psDashDotDot enumeration value in the FCL.

Represents the clear pen style.

Alias for the FPCanvas.psClear enumeration value in the FCL.

Represents the pen style used for an inside frame.

Alias for the FPCanvas.psInsideframe enumeration value in the FCL.

Represents a pattern pen style.

Alias for the FPCanvas.psPattern enumeration value in the FCL.

Represents the Black pen mode.

Alias for the FPCanvas.pmBlack enumeration value in the FCL. Pixels affected by the pen are always set to black.

Represents the White pen mode.

Alias for the FPCanvas.pmWhite enumeration value in the FCL. Pixels affected by the pen are always set to white.

Represents the No OP pen mode.

Alias for the FPCanvas.pmNop enumeration value in the FCL. Pixels affected by the pen are unchanged.

Represents the NOT pen mode.

Alias for the FPCanvas.pmNot enumeration value in the FCL. Pixels affected by the pen are set to the inverse for the current color.

Represents the Copy pen mode.

Alias for the FPCanvas.pmCopy enumeration value in the FCL. Pixels affected by the pen are set to the pen color.

Represents the Not Copy pen mode.

Alias for the FPCanvas.pmNotCopy enumeration value in the FCL. Pixels affected by the pen are set to the inverse of the pen color.

Represents the Merge Pen Not pen mode.

Alias for the FPCanvas.pmMerge enumeration value in the FCL. Pixels affected by the pen are set to a combination of the pen color and the inverse of the pixel color.

Represents the Mask Pen Not pen mode.

Alias for the FPCanvas.pmMaskPenNot enumeration value in the FCL. Pixels affected by the pen are set to colors common to both the pen and the inverse of the pixel color.

Represents the Merge Not Pen pen mode.

Alias for the FPCanvas.pmMergePenNot enumeration value in the FCL. Pixels affected by the pen are set to a combination of the pen color and the inverse of the pixel color.

Represents the Mask Not Pen pen mode.

Alias for the FPCanvas.pmMaskNotPen enumeration value in the FCL. Pixels affected by the pen are set to a combination of the colors common to the inverse of the pen color and the current pixel color.

Represents the Merge pen mode.

Alias for the FPCanvas.pmMerge enumeration value in the FCL. Pixels affected by the pen are set to a combination of the pen color and the current pixel color.

Represents the Not Merge pen mode.

Alias for the FPCanvas.pmNotMerge enumeration value in the FCL. Pixels affected by the pen are set to the inverse of the color derived using pmMerge pen mode.

Represents the Mask pen mode.

Alias for the FPCanvas.pmMask enumeration value in the FCL. Pixels affected by the pen are set a combination of the colors common to the pen color and the current pixel color.

Represents the Not Mask pen mode.

Alias for the FPCanvas.pmNotMask enumeration value in the FCL. Pixels affected by the pen are set to the inverse of the color for pmMask pen mode.

Represents the XOR pen mode.

Alias for the FPCanvas.pmXor enumeration value in the FCL. Pixels affected by the pen are set to a combination of the pen color and the current pixel color, but not both.

Represents the Not XOR pen mode.

Alias for the FPCanvas.pmNotXor enumeration value in the FCL. Pixels affected by the pen are set to the inverse of the color using pmXor pen mode.

Represents the Solid brush style.

Alias for the TFPBrushStyle.bsSolid enumeration value in the FCL. Fills a shape using the color for the brush.

Represents the Clear brush style.

Alias for the TFPBrushStyle.bsClear enumeration value in the FCL. Fills a shape with transparency (using the existing color as the fill color).

Represents the Horizontal brush style.

Alias for the TFPBrushStyle.bsHorizontal enumeration value in the FCL. Fills a shape with a pattern consisting of equidistant horizontal lines.

Represents the Vertical brush style.

Alias for the TFPBrushStyle.bsVertical enumeration value in the FCL. Fills a shape with a pattern consisting of equidistant vertical lines.

Represents the FDiagonal brush style.

Alias for the TFPBrushStyle.bsFDiagonal enumeration value in the FCL. Fills a shape with a pattern consisting of equidistant lines drawn with a 45-degree downward, left-to-right hatch.

Represents the BDiagonal brush style.

Alias for the TFPBrushStyle.bsBDiagonal enumeration value in the FCL. Fills a shape with a pattern consisting of equidistant lines drawn with a 45-degree upward, left-to-right hatch.

Represents the Cross brush style.

Alias for the TFPBrushStyle.bsCross enumeration value in the FCL. Fills a shape with a pattern consisting of equidistant lines drawn as a horizontal and vertical cross-hatch.

Represents the DiagCross brush style.

Alias for the TFPBrushStyle.bsDiagCross enumeration value in the FCL. Fills a shape with a pattern consisting of equidistant lines drawn as a 45 degree cross-hatch.

Represents the Round pen end cap.
Added in LCL version 2.6.3.
Represents the Square pen end cap.
Added in LCL version 2.6.3.
Represents the Flat pen end cap.
Added in LCL version 2.6.3.
Represents the Round pen join style.
Added in LCL version 2.6.3.
Represents the Bevel pen join style.
Added in LCL version 2.6.3.
Represents the Miter pen join style.
Added in LCL version 2.6.3.
Alias for the TGraphicsFillStyle enumeration type in LazUtils.

Alias for the TGraphicsFillStyle enumeration type in LazUtils.

TGraphicsFillStyle
Represents Fill Mode values.

Not used in the current LCL implementation. Appears to have been replaced with the LazRegionFillMode type in lazregions.pas.

Type used to represent canvas copy modes.

TCopyMode is an alias for the LongInt type. TCopyMode is the type used to implement the CopyMode property in TCanvas. Normally contains a value defined in the copy mode constants:

cmBlackness
  Fills the destination rectangle with the first color in the physical palette. (Black for the default palette).
cmDstInvert
  Inverts colors in the destination rectangle.
cmMergeCopy
  Merges colors from the source rectangle with the brush color.
cmMergePaint
  Merges inverted colors from the source rectangle with the colors in the destination rectangle using an OR operation.
cmNotSrcCopy
  Copies inverted colors from the source rectangle to the destination rectangle.
cmNotSrcErase
  Combines the colors from the source and destination rectangles using an OR operation, and inverts the result.
cmPatCopy
  Copies the brush into the destination rectangle.
cmPatInvert
  Combines the brush colors with the colors in the destination rectangle using an XOR operation.
cmPatPaint
  Combines the brush colors with the inverted colors from the source rectangle using an OR operation, and combines the result with the colors in the destination rectangle using an OR operation.
cmSrcAnd
  Combines colors from the source and destination rectangles using an AND operation.
cmSrcCopy
  Copies the source rectangle to the destination rectangle.
cmSrcErase
  Combines the inverted colors in the destination rectangle with the colors from the source rectangle using an AND operation.
cmSrcInvert
  Combines the colors in the source and destination rectangles using an XOR operation.
cmSrcPaint
  Combines the colors in the source and destination rectangles using an OR operation.
cmWhiteness
  Fills the destination rectangle using the second color in the physical palette. (White for the default palette).

The default value for the propriety is cmSrcCopy.

Copy mode constants are omitted for the CAPTUREBLT and NOMIRRORBITMAP values used in the Windows GDI API.

Represents states values for TCanvas.

TCanvasStates is an enumerated type with values that represent the state for a TCanvas instance. Value(s) from the enumeration are stored in the TCanvasState set type used to implement the State property in TCanvas.

The handle for the canvas is valid.
Font properties correspond to the selected Font Handle in the Device Context (DC).
Set type used to store TCanvasStates values.
Represents orientations for a canvas.
Not used in the current LCL implementation.

TODO: Change this to coLeftToRight?

Alias for the TFPImgProgressStage type in the FCL.
TProgressEvent - for monitoring the progress of a drawing process.
Alias for the TFPImgProgressEvent type in the FCL.
Represents storage formats for pixels in image data.

TPixelFormat is an enumerated type with values that represent the storage format for pixels in image data. In general, it indicates the number of bits required for each pixel in an image. It also determines the color spectrum and color depth available in image data.

TPixelFormat is the type used to implement the PixelFormat property in TRasterImage, TSharedCustomBitmap, TCustomBitmap, TSharedIcon, TIconImage, TCustomIcon, et. al.

Indicates that the source device determines the pixel format.
1 bit per pixel. Monochrome.
4 bits per pixel. 16 colors.
8 bits per pixel. 256 colors.
15 bits per pixel. 32,768 colors. Also called High Color.
16 bits per pixel. 65,536 colors. Also referred to as High Color.
24 bits per pixel. 16,777,216 colors. Also called TrueColor.
32 bits per pixel. 4,294,967,296 colors. Not a common pixel format.
Uses a pixel format other than the defined values.
Constant with the number of bits per pixel for TPixelFormat enumeration values.

PIXELFORMAT_BPP is a constant which contains an array of Byte values representing the number of bits used for pixel data in an image. Elements in the array are indexed values in the TPixelFormat enumeration, and contain the number of bits per pixel for the associated pixel format.

Represents transparency modes used in raster images.
Transparency is determined by examining a designated pixel in the image data.
Uses a designated color as the transparent color.
One of the standard colors. Delphi compatible.
One of the standard colors. Delphi compatible.
One of the standard colors. Delphi compatible.
One of the standard colors. Delphi compatible.
One of the standard colors. Delphi compatible.
One of the standard colors. Delphi compatible.
One of the standard colors. Delphi compatible.
One of the standard colors. Delphi compatible.
One of the standard colors. Delphi compatible.
One of the standard colors. Delphi compatible.
One of the standard colors. Delphi compatible.
One of the standard colors. Delphi compatible.
One of the standard colors. Delphi compatible.
One of the standard colors. Delphi compatible.
One of the standard colors. Delphi compatible.
One of the standard colors. Delphi compatible.
An alias for clSilver.
One of the standard colors. Delphi compatible.
An alias for clGray.
One of the standard colors. Delphi compatible.
Number of defined standard color constants.
One of the extended colors.
One of the extended colors.
One of the extended colors.
One of the extended colors.
The number of defined extended color constants.
One of the special colors.
The default color of a given control.

The default color for a given control. This color alone does not have any meaning; it needs to be resolved using a control instance and one of the methods like: TControl.GetDefaultColor, TControl.GetColorResolvingParent or TControl.GetRGBColorResolvingParent.

TControl.GetDefaultColor TControl.GetColorResolvingParent TControl.GetRGBColorResolvingParent
One of the System colors.
One of the System colors.
One of the System colors.
One of the System colors.
One of the System colors.
Background color for an edit control.

The color of the background of a widget, for example a TEdit. This is usually white. Don't confuse this with the background of a window, or form, which is given by clForm.

One of the System colors.
The color of the text in menus.
The color for the text in an edit control.

The color of the text in a widget, such as for example TEdit. This is usually black. Don't confuse with the color of the window decoration caption or of a raised control such as buttons or anything else.

One of the System colors.
One of the System colors.
One of the System colors.
One of the System colors.
One of the System colors.
One of the System colors.
Color for a button face.

The color used for a button face. This color is also utilized in many other places for raised areas such as a panel.

One of the System colors.
One of the System colors.
The color for the text or other raised area on a button.
One of the System colors.
One of the System colors.
One of the System colors.
One of the System colors.
One of the System colors.
One of the System colors.
One of the System colors.
One of the System colors.
One of the System colors.
One of the System colors used for highlights on a menu.
One of the System colors used for the menu bar.
Represents the color of the background for a form.
A synonym not displayed in color lists.
A synonym not displayed in color lists.
A synonym not displayed in color lists.
A synonym not displayed in color lists.
A synonym not displayed in color lists.
Alias for the clBtnHiLight constant.
Alias for the clWhite constant.
Alias for the clBlack constant.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color. Do not use.
Deprecated CLX color range. Do not use.
Deprecated CLX color enumeration. Do not use.
Deprecated CLX color enumeration. Do not use.
Class reference used to create new instances of TRasterImage.
Class reference used to create new instances of TCustomBitmap.
Primitive ancestor class, mainly for Delphi compatibility.

TGraphicsObject - In Delphi VCL this is the ancestor of TFont, TPen and TBrush. Since FPC 2.0 the LCL uses TFPCanvasHelper as ancestor.

Changing
- software emulation of OnChanging event.
Changed
- software emulation of OnChange event.
Lock
- method for locking the object, making it unavailable for changes.
UnLock
- method for releasing locked object.
OnChanging
- event handler for changing object.
OnChange
- event handler for changed object.
TFontHandleCacheDescriptor
- descriptor for items in Font Handle Cache.
Contains the logical font information for the cache descriptor.
LongFontName
- the long name for the Font.
TFontHandleCache
- a resource cache for font handles.
Removes the specified resource item from the cache.
TResourceCache.RemoveItem
Item removed from the resource cache.
Constructor for the class instance.

Calls the inherited constructor on entry. Assigns TFontHandleCacheDescriptor to the ResourceCacheDescriptorClass property used to create new cache entries.

TResourceCache.Create
Compares the specified logical font names and font details.
TResourceCache.CompareDescriptors
FindFont
- returns the Font specified by its handle as a cache item from the FontHandleCache.
FindFontDesc
- returns the descriptor for the FontHandle using its LogName and its LongFontName.
Add
the Font specified by its handle, LogFont and LongFontName, and returns a descriptor.
Represents a font used to draw text in an application.

TFont is a TFPCustomFont descendant, and provides properties and methods needed to represent a font used in an LCL application.

Most of the information about the font is provided in a TFontData instance used in protected methods like GetData and SetData. Data items in the structure are exposed as properties, and includes: CharSet, Color, Height,Name, Orientation, Pitch, Quality, Size, and Style.

Its Reference property provides access to the font Handle in the widgetset implementation.

Frees the widgetset font reference in the class instance.

FreeReference calls the inherited Changing method to signal the OnChanging event handler (when assigned). FreeReference ensures that a cache font handle for the font reference is removed from the FontResourceCache. If the font handle is not cached, the handle is deleted and the LCL handle in the font reference is set to 0 (zero).

FreeReference is called from methods which set the value in font properties like: Name, Size, Pitch, Height, Style, and Orientation. It is also called when the class instance is freed.

Gets the value for the Handle property.
Value for the property.
Gets the value for the FontData property.
Values for the property.
Gets the value for the IsMonoSpace property.
Value for the property.
Gets the value for the Reference property.
Value for the property.
Gets the storage specifier for the Height property.
True when Height contains a value different than the value in DefFontData.
Gets the storage specifier for the Name property.
True when Name contains a value different than the value in DefFontData.
Sets the value for the FontData property.
New value for the property.
Sets the value for the Handle property.
New value for the property.
Ensures that Reference contains a valid logical font instance for the widgetset.

No actions are performed in the method when the logical font in Reference has already been allocated.

Sets the value for the PixelsPerInch property.
New value for the property.
Gets the value for the CharSet property.
Value for the property.
Gets the value for the Height property.
Value for the property.
Gets the value for the Name property.
Value for the property.
Gets the value for the Orientation property.
Value for the property.
Gets the value for the Pitch property.
Value for the property.
Gets the value for the Size property.
Value for the property.
Gets the value for the Style property.

Bold, Italic, StrikeOut, Underline.

Value for the property.
Changed
- checks for pending updates (if there are any, returns True) or calls inherited Changed.

Changed is an overridden procedure used to maintain the internal state for the class instance. If Changed has already been called for the font instance, no additional actions are required or performed. Otherwise, the inherited method is called to signal the OnChanged event handler (when assigned).

Changed is called when any of the properties for the font are modified, or when a new value is assigned to FontData or PixelsPerInch. Changed is called from the EndUpdate method when the internal update count reaches 0 (zero).

DoAllocateResources
- calls inherited method then calls

GetReference
.
DoCopyProps
- calls inherited method; if From argument is another Font, copies specified properties directly.
DoDeAllocateResources
- frees references then calls inherited method.
Sets the value for the CharSet property.
New value for the property.
Sets the value for the Color property.

An overloaded variant of the method handles converting the TColor value to the TFPColor values used in ancestor class.

New value for the property.
New value for the property.
New property value as a TFPColor type.
Gets the value for the Color property.
Value for the property.
Sets the value for an indexed style flag.

SetFlags is an overridden method used to set the value for an individual style flag by its ordinal position.

Index contains the position for the style flag used in the canvas helper for the class.

AValue is a Boolean value that indicates whether the TFontStyle value is included in or excluded from the style flags.

SetFlags is called when a new value is assigned to the Style property differs from the existing value.

Ordinal position for the style flag updated in the method.
New value for the style flag at the specified position.
Sets the font Color to the specified TFPColor value.

SetFPColor is a method used to set the Color for the font to the value specified in AValue. AValue contains a TFPColor value as defined in the FCL. SetFPColor calls FPColorToTColor to convert AValue to the TColor value applied to the Color property.

TFPColor value applied to the Color property.
Sets the value for the Height property.

Any change to Height is also converted to Points and applied to Size.

New value for the property.
Sets the value for the Name property.
New value for the property.
Sets the value for the Orientation property.
New value for the property.
Sets the value for the Pitch property.
New value for the property.
SetSize
- if AValue is a new size, frees the old reference, calls the inherited method, performs the appropriate rounding and sets the Changed property.
SetStyle
- specify which style to use.
New value for the property.
SetQuality
- specify the quality.
Default, Draft, Proof, NonAntialiased, Antialiased
New value for the property.
Constructor for the class instance.

Create is the overridden constructor in TFont. Create calls the inherited constructor on entry, and sets the default values for properties including:

Color
  Set to clDefault for platforms or widgetsets where it is enabled. Otherwise, set to clWindowText.
Pitch
  Set to the value in DefFontData.
Charset
  Set to the value in DefFontData.
Quality
  Set to the value in DefFontData.
Height
  Set to the value in DefFontData.
Style
  Set to the value in DefFontData.
PixelsPerInch
  Set to the vertical display density used in ScreenInfo.
Size
  Calculated using values in Height and PixelsPerInch. Applied by calling the SetSize method inherited from TFPCustomFont.
Name
  Set to the value in DefFontData, and applied by calling the SetName name method inherited from TFPCustomFont.
FPColor
  Calls the SetFPColor method inherited from TFPCanvasHelper to set the font color to colBlack.

The DelayAllocate property from the TFPCanvasHelper ancestor is set to True to defer resource allocation for the Canvas until it is used.

TObject.Create
Destructor for the class instance.

Destroy is the overridden destructor for the class instance. Destroy calls FreeReference to free cached font resources for the Reference class, and frees the Handle for the font. The inherited destructor is called prior to exiting from the method.

TPersistent.Destroy
Copies values from Source to the current class instance.

Assign is an overridden method used to copy values from the specified Source into the current class instance. Overloaded variants are provided that allow the source to be a TPersistent instance (which is cast to TFont) or a TLogFont record instance.

TPersistent.Assign TLogFont
Persistent object with values stored in the method.
Logical font resource with values stored in the method.
Starts an update process for the class instance.
Finishes an update process for the class instance.
Contains the data describing the font.
HandleAllocated
- returns True if a handle has been allocated.
Operating system Handle for the Font.

Operating system Handle for the Font.

Deprecated?

IsDefault
- returns True if this is the default Font.
IsEqual
- returns True if this Font is the same as the specified Font.
True when the font matches the one in the current class instance.
Font instance to compare to the current class instance.
Indicates if the font uses fixed-width characters (monospace).

IsMonoSpace is a read-only Boolean property which indicates if the font is a monospaced font with a fixed character width. The FontIsMonoSpace routine from the LCL interface is called to get the property value, and uses the font handle in Reference to retrieve the font data.

FontIsMonoSpace
Sets font properties to their default values.

SetDefault is a procedure used to set properties in the font to the values used in the DefFontData variable. SetDefault calls BeginUpdate to start an update process, and sets the values for the following properties:

- Name
- Charset
- Height
- Pitch
- Quality
- Style
- Color

Color is set to clDefault when the UseCLDefault compiler directive is defined. Otherwise, the value clWindowText is used in the property.

EndUpdate is called to finish the update process prior to exiting from the method.

Display density for the font.

PixelsPerInch is an Integer property which indicates the display density (or pixels per inch) for the font.

The default value for the property is set when the class instance is created, and uses the value from the PixelsPerInchY member in ScreenInfo. It is also updated when Assign is used to copy property values from another font instance.

PixelsPerInch is used when values are assigned to the Height or Size properties to convert pixel values to the Points unit of measure used in Size.

Setting a new value in PixelsPerInch causes Height to be scaled to the new value for the property. Changed is also called to signal the OnChange event handler (when assigned).

Reference
- References made to this Font.

Reference is a read-only TWSFontReference property which contains a reference to the widgetset class used for the font instance. It provides access to the Handle for the font resource, and is used in methods that need access to an existing font handle.

Resources for the property are allocated (when needed) and initialized by calling the ReferenceNeeded method. The resources are freed in the FreeReference method.

Indicates the character set used in the font.

CharSet is a TFontCharSet property which contains a numeric value representing the character set in the font instance. The default value for the property is defined in the DEFAULT_CHARSET constant, and indicates that the default character set for the operating system or platform is used.

Setting a new value for the property causes the font Reference class to be re-created, and Changed is called to signal the OnChange event handler (when assigned).

CharSet is updated when the font data is read for the class instance, and when Assign is called to copy values from another font instance.

Color used to render text using the font.

Color is a TColor property which contains the color used to render text using the font. The default value for the property is clDefault when the UseCLDefault compiler directive is defined. Otherwise, the default value is clWindowText.

Setting a new value for the property causes the ancestor class to be notified, and Changed is called to signal the OnChange event handler (when assigned).

Height for the font (in pixels).

Height is an Integer property which contains the height for the font in pixels. The property value is not stored during LCL streaming operations when its value is the same as the value in DefFontData.

Setting a new value for the property causes the font handle in Reference to be re-created. Size is also updated with the new property value converted to Points (1/72 of an inch). Changed is called to signal the OnChange event handler (when assigned).

Use Size to read or write the height for the font as a number of Points (1/72 inch).

Name of the font.

Name is a String property which contains the name of the font in the class instance. The initial value for the property is set when the class instance is created, and uses the Name from the DefFontData variable. The property is updated when Assign is called to copy values from another font instance.

Setting a new value for the property causes the font Reference to be re-created, and the Changed method is called to signal the OnChange event handler (when assigned).

Name is not included in LCL streaming when the property value is the same as the Name member in DefFontData.

Rotation for the current font in 1/10ths of a degree.

Orientation is an Integer property which contains the rotation angle used for text in 1/10ths of a degree. The rotation angle is determined by the relationship between the X Axis for the Canvas and the baseline for the font, and uses the following directionality:

Orientation Values and Directions
0 | Text is drawn horizontally from left to right.
900 | Text is drawn vertically from bottom to top.
1800 | Text is drawn upside down from right to left.
2700 | Text is drawn vertically from top to bottom.

Setting a new value for the property causes the font Reference to be re-created, and calls Changes to signal the OnChange event handler (when assigned).

The default value for the property is 0 (zero).

Pitch
type of the Font.

Pitch is a TFontPitch property which indicates the pitch for the font face.

Setting a new value for the property causes the font Reference to be re-created, and the Changed method is called to signal the OnChange event handler (when assigned).

Output quality for the Font, such as anti-aliasing.

Quality is a TFontQuality property which contains a value with the output quality for the font. The output quality determines how carefully font attributes are applied to output using the font.

The default value for the property is fqDefault. See TFontQuality for more information about the enumeration values and their meanings.

Setting a new value for the property causes the font Reference to be re-created, and Changed is called to signal the OnChange event handler (when assigned).

Vertical size for the font in Points.

Size is an Integer property which contains the height for the font in Points (1/72 of an inch). The value in Size is calculated using the logical font height, and is not read or written in LCL component streaming.

Setting a new value for the property causes the font Reference to be re-created for the class instance. The new value is stored by calling SetSize in the ancestor class. The new value is also converted to pixels (using PixelsPerInch) and stored in the Height property.

Styles applied to the font face.

Style is a TFontStyles property which indicates the font styles applied to the font face. The Style set contains 0 (zero ) or more values from the TFontStyle enumeration, including:

fsBold
  Bold font style
fsItalic
  Italic font style
fsStrikeOut
  Strike-out (or strike-through) font style
fsUnderline
  Underline font style

The default value for the property is an empty set ([]), and indicates that no styles are applied to the font face.

Setting a new value for the property causes the font Reference to be re-created. The Change method is called to signal the OnChange event handler (when assigned).

Represents line drawing styles used when rendering to a canvas.

TPenStyle is an alias for the TFPPenStyle type in the FCL.

Represents pen modes used when rendering to a canvas.

TPenMode is an alias for the TFPPenMode type in the FCL.

Represents end cap styles used for a pen.

TPenEndCap is an enumerated typed with values representing geometric shapes used as end caps for a pen. End caps are applied to the starting and ending points in a line segment.

TPenEndCap is the type used to implement the EndCap property in TPen.

Added in LCL version 2.6.3.
Rounded end cap which extends beyond the point.
Rectangular end cap which extends beyond the point.
Flat (or blunt) end cap which does not extend beyond the point.
Represents join styles used between line segments.
Added in LCL version 2.6.3.
Round shape used at the join points.
Bevel shape used at the join points.
Mitered angular shape used at join points.
Represents a pattern brush for a pen.

TPenPattern is an array type used to store the sequence of LongWord values that make up the pattern. TPenPattern is essentially a user-defined pen style.

TPenPattern is the type used to implement the Pattern property in TPen.

Cache descriptor for Pen Handles.
Extended logical pen structure for the cache entry.
The Pattern for this pen.
TPenHandleCache
- Resource Cache for Pen Handles.
TResourceCache.RemoveItem
Constructor for the class instance.
Compares the specified image descriptors to determine if they have the same pens and pattern data.
TResourceCache.CompareDescriptors
FindPen
- returns a ResourceCacheItem corresponding to the nominated Handle.
FindPenDesc
- returns a descriptor for the given pen and pattern.
Add
- returns a cache descriptor corresponding to the pen that has been added to the cache.
Represents a pen used to draw on a canvas.

TPen is a TFPCustomPen descendant which contains settings for a pen used to draw lines and shapes on a canvas. It includes properties that define the color for the pen, the end cap and join style used for line segments, and a pattern used for user-defined line drawing styles.

Essentially, TPen maps the types used for properties in the FCL ancestor class to the types used in the LCL.

TPen is the type used to implement the Pen property in TCanvas.

Frees the Pen class reference and optionally removes it from the Pen resource cache.
Gets the value for the Handle property.
Value for the property.
Gets the value for the Reference property.
Value for the property.
Ensures that the Reference class is allocated and initialized.
Sets the value for the Cosmetic property.
New value for the property.
Sets the value for the Handle property.
New value for the property.
Performs actions needed to allocate resources for the class instance.

DoAllocateResources is an overridden method used to allocate resources for the class instance. DoAllocateResources calls the inherited method , and calls GetReference to initialize the Reference property used in the class instance.

Performs actions to free resources allocated for the class instance.

Overridden. Calls FreeReference. Calls the inherited method.

Copies properties from the specified source to the class instance.

Overridden. Provides support for the TPen type in the From parameter. Calls the inherited method.

Canvas helper descendant with properties copied in the method.
Sets the value for the Color property.
New value for the property.
Sets the pen Color to the specified TFPColor value.

SetFPColor is a method used to set the Color for the pen to the value specified in AValue. AValue contains a TFPColor value as defined in the FCL. SetFPColor calls FPColorToTColor to convert AValue to the TColor value applied to the Color property.

SetEndCap
- specified the type of end cap to be used for the pen, if it is a geometric pen.

Defined for FCL versions where the EndCap property is implemented.

New value for the property.
Sets the value for the JoinStyle property.

SetJoinStyle - specifies the style to be used by the geometric pen when lines join (at corners etc).

New value for the property.
Sets the value for the Mode property.
Overridden write access specifier.
New value for the property.
Sets the value for the Style property.

Overridden write access specifier.

New value for the property.
Sets the value for the Width property.

Overridden write access specifier.

New value for the property.
Constructor for the class instance.

Create is the overridden constructor for TPen. It calls the inherited Create method, and sets the default values for properties including:

- DelayAllocate
- Cosmetic
- EndCap
- JoinStyle
- Width
- Style
- Mode
- Color

TObject.Create
Destructor for the class instance.

Destroy is the destructor for TPen. It frees resource in Reference and calls the inherited Destroy method.

TPersistent.Destroy
Copies property values from the specified persistent object.

Assign is an overridden method used to copy property values from the persistent object in Source to the current class instance.

Source is the TPersistent class instance with the property values copied in the method. If Source is a TPen instance, the properties introduced in TPen are copied into the current class instance. Otherwise, the inherited method is called.

TPersistent.Assign
Persistent object with values copied in the method.
The Operating System Handle for the current Pen.

Handle is a HPEN property with the handle allocated for the pen by the operating system or widgetset. Setting a new value for the property causes the pen Reference to be re-created. The Changed method is called to signal the OnChange event handler (when assigned).

The Handle property has been marked as deprecated. Use the Reference property to access the Handle for the pen.
A Reference made to this Pen.

Reference is a read-only TWSPenReference property which provides a reference to the class allocated for the pen by a widgetset class. Use Reference to access the handle allocated for the pen resource.

Gets the Pattern used in the Pen.

GetPattern is a TPenPattern function used to get Pattern for the pen. Use SetPattern to assign the Pattern used for the pen.

Please note that the Pattern property in the TFPCustomPen ancestor class uses a different type (LongWord instead of TPenPattern).
SetPattern
- specifies the pattern for the pen.

SetPattern is a reintroduced procedure in TPen to use the TPenPattern type. The property in the ancestor class uses the LongWord type.

The Color of the current Pen.

Color is a TColor property which contains the color used by the pen to draw on a canvas. The default value for the property is clBlack.

Whether the Pen is Cosmetic, or non-geometric.

Cosmetic is a Boolean property which indicates whether the pen is a Cosmetic one. When set to False, it is a Geometric Pen.

A Pen can be either Cosmetic or Geometric. A cosmetic pen is always 1 pixel wide, while a geometric pen can have any width. The width of a geometric pen is defined in world units and thus depends on transforms (scaling, rotation, shear, reflection) applied to a canvas. Operations using a cosmetic pen are faster.

The default value for the property is True.

Setting a new value for the property causes the pen Reference to be re-created. The Changed method is called to signal the OnChange event handler (when assigned).

The sort of EndCap used on the Pen.

The end cap can be Round, Square or Flat. When end caps are round, the last points are drawn round. When end caps are square, the last points are drawn square. When end caps are flat, the last points are not drawn at all.

Added in LCL version 2.6.3.
JoinStyle
- the style of joint where two lines meet or cross.

The join style can be: Round, Bevel or Miter. When style is Round, then line joins are round. When style is Bevel, then line joins are beveled. When style is Miter, then line joins are mitered.

Added in LCL version 2.6.3.
Pen mode for the class instance.

Mode is a TFPPenMode property which contains the pen mode used in the class instance. A pen mode indicates the raster operation performed to combine the pen color with existing pixels in the destination bitmap. Mode can contain any of the values:

pmBlack
  Pixels affected by the pen are always set to black.
pmWhite
  Pixels affected by the pen are always set to white.
pmNop
  Pixels affected by the pen are unchanged.
pmNot
  Pixels affected by the pen are set to the inverse for the current color.
pmCopy
  Pixels affected by the pen are set to the pen color.
pmNotCopy
  Pixels affected by the pen are set to the inverse of the pen color.
pmMergePenNot
  Pixels affected by the pen are set to a combination of the pen color and the inverse of the pixel color.
pmMaskPenNot
  Pixels affected by the pen are set to colors common to both the pen and the inverse of the pixel color.
pmMergeNotPen
  Pixels affected by the pen are set to a combination of the pen color and the inverse of the pixel color.
pmMaskNotPen
  Pixels affected by the pen are set to a combination of the colors common to the inverse of the pen color and the current pixel color.
pmMerge
  Pixels affected by the pen are set to a combination of the pen color and the current pixel color.
pmNotMerge
  Pixels affected by the pen are set to the inverse of the color derived using pmMerge pen mode.
pmMask
  Pixels affected by the pen are set a combination of the colors common to the pen color and the current pixel color.
pmNotMask
  Pixels affected by the pen are set to the inverse of the color for pmMask pen mode.
pmXor
  Pixels affected by the pen are set to a combination of the pen color and the current pixel color, but not both.
pmNotXor
  Pixels affected by the pen are set to the inverse of the color using pmXor pen mode.

The default value is pmCopy.

Contains the line drawing style for the pen.

Style is a TPenStyle property with the style used to draw lines with the Pen, and can contain one of the following values:

- psSolid
- psDash
- psDot
- psDashDot
- psDashDotDot
- psinsideFrame
- psPattern
- psClear

psDash, psDot, psDashDot, and psDashDotDot are drawn using the corresponding TPenPattern for the Style. On the Windows platform, these styles are not available if the Width is any value other than 1.

psInsideFrame uses a solid drawing style, and a Color dithered to one of the values in the color table for the device. The content drawn with the pen is reduced in size so that it appears inside of a bounding rectangle including the Width for the pen.

psClear, in general, tells the implementing class or routine that the drawing operation is not needed.

The default value for the property is psSolid. Setting a new value for the property cause the Changed method to be called to signal the OnChange event handler (when assigned).

Width for the Pen.

Width is an Integer property which contains the width for the pen.

Setting a new value for the property causes the pen Reference to be re-created. The Changed method is called to signal the OnChange event handler (when assigned). The default value for the property is 1.

Width is related to the Cosmetic property. A cosmetic pen has a width of 1. Setting Width to a value larger than 1 prevents using it as a cosmetic pen.

Represents the pattern for a Brush.

TBrushStyle is an alias for TFPBrushStyle from the FCL. Brush style constants are defined in the LCL, and includes:

- bsSolid
- bsClear
- bsHorizontal
- bsVertical
- bsFDiagonal
- bsBDiagonal
- bsCross
- bsDiagCross

TBrushHandleCache
- resource cache for Brush Handles.
Deletes the widgetset object with the handle in Item and removes it from the resource cache.
TResourceCache.RemoveItem
Item removed from the cache.
Constructor for the class instance.
TObject.Create
The Brush to be used to Paint on the current Canvas.

A Brush is typically used to fill an enclosed area on the Canvas with one particular color or colored pattern.

Frees the widgetset reference for the Brush.
Gets the value for the Handle property.
Gets the value for the Reference property.
Gets the value for the Color property.
Ensures that resources are allocated for the Reference property.
Sets the value for the Handle property.
New value for the property.
Performs action needed when the Brush is changed.
DoAllocateResources
- calls inherited method then calls GetReference.
DoDeAllocateResources
- frees reference then calls inherited method.
DoCopyProps
- if the From argument is another Brush, frees reference before calling inherited method, then sets the Changed property.
Sets the value for the Color property.

An overloaded variant provides both TColor and TFPColor values. It is used to set the color by calling the SetFPColor method in the ancestor class. No actions are performed in the method when the values in Color and FPColor have not been changed and the brush Style contains bsClear.

Frees the brush handle in the References property, and sets the value in Bitmap to Nil. Calls the inherited SetStyle method when Style is bsClear. Calls Changed to signal the OnChange event handler (when assigned).

New value for the property.
TColor value applied to the brush Color.
TFPColor value applied to the brush Color.
Sets the Brush color to the specified TFPColor value.

SetFPColor is an overridden method used to set the color using the TFPColor value in AValue. Calls FPColorToTColor to convert AValue to a TColor value, and applies it to the Color property.

Color value applied to the Color property.
Sets the value for the Bitmap property.
New value for the property.
Sets the value for the Style property.
New value for the property.
Copies values from Source to the current brush instance.

Assign is a procedure used to copy properties values from Source to the current brush instance.

TPersistent.Assign
Brush instance with values copied in the method.
Constructor for the class instance.

Create is the overridden constructor for the class instance. Create calls the inherited constructor on entry, and sets the default values for properties including:

Bitmap
  Set to Nil.
Color
  Set to clWhite. The inherited SetFPColor method is called to apply the new value.
Style
  The default value is bsSolid, and the inherited SetStyle method is called to apply the value in ancestor classes.

Create sets the value in DelayAllocate to True to defer resource allocation until the brush is used. The internal counter used to track updates is reset.

TObject.Create
Destructor for the class instance.

Destroy is the overridden destructor for the class instance. Destroy frees the handle for the brush in the Reference property, and calls the inherited destructor prior to exiting from the method.

TPersistent.Destroy
Compares the specified Brush to the current class instance.
True when the brush properties match the values in the current class instance.
Brush instance compared to the current class.
Bitmap with the pattern for the Brush.

Bitmap is a TCustomBitmap property which contains the pattern used to draw the brush, and is generally used to fill shapes or rectangular areas.

When assigned, the Bitmap image is used to draw the brush pattern instead of using the Style for brush. Setting a value for the property causes values in Color and Style to be reset. Color is set to clWhite, and the brush Style is set to bsSolid. The Handle for the brush is freed, and the Changed method is called to signal the OnChange event handler (when assigned).

The image in Bitmap will be discarded when a new value is assigned to the Style property.

Operating System handle for the brush.

Handle is a HBRUSH property which contains the handle allocated for the brush.

Handle has been marked as deprecated. Use the Reference property to access the handle for the brush.
Contains a Reference to the handle allocated for the Brush.

Reference is a read-only TWSBrushReference property which contains a reference to the widgetset class used for the brush instance. It provides access to the Handle allocated for the brush resource, and is used in methods that need access to an existing brush handle.

Resources for the property are allocated (when needed) and initialized by calling the ReferenceNeeded method. The resources are freed in the FreeReference method.

The Color of the current Brush.

Color is a TColor property with the color used to draw the brush pattern indicated in the Style property. It is the background or fill color when Style contains bsSolid. Color is not used when Style is set to bsClear; in fact, the brush style in TFPCustomBrush ancestor is actually set to bsSolid.

Setting a new value for the property causes an existing brush handle in Reference to be freed, and the pattern image in Bitmap is discarded.

The default value for the property is clWhite. The default property value is restored when a new value is assigned to the Bitmap property.

Indicates the pattern drawn for the brush.

Style is a TFPBrushStyle property which indicates the pattern drawn using the brush. Style contains one of the enumeration values defined in the FCL. The enumeration values are introduced as constants in the LCL, and includes:

- bsSolid
- bsClear
- bsHorizontal
- bsVertical
- bsFDiagonal
- bsBDiagonal
- bsCross
- bsDiagCross

Setting a new value in Style causes the brush Handle in Reference to be freed. The image in Bitmap is also discarded by setting the member to Nil. The Changed method is called to signal the OnChange event handler (when assigned).

The default value for the property is bsSolid. The value in Style is automatically set to bsSolid when a value is assigned to the Bitmap property.

Represents combination methods used for regions.
Create a region with the intersecting parts of the original regions.
Create a region that is a copy of the first of the two original regions.
Create a region with the area in the first region not found in the second region.
Create a region that represents both of the original regions.
Create a region with the areas from the original regions that do not overlap.
Represents Region operators used in TRegionOperation.
Create a new bounding box for the region.
Create a new region using the combine mode for an operation.
Represents a region operation.
Raster operation type.
Index to a source region.
Index to a source region.
Index to the destination region.
Region combine mode for the operation.
Rectangle with the bounding box for the destination region.
Array type used to store TRegionOpertation elements.
A defined area on a screen or canvas used to render a graphic image or text output.

TRegion is a TGraphicsObject descendant which represents shaped areas that can be drawn, filled, or examined on a screen or canvas. The shaped areas can be one or more rectangles, and can overlap.

Use AddRectangle to create and combine a new rectangular area with the existing areas in the region. Each region has a Handle which identifies the construct. It is modified when a new rectangular area is added to the region.

TRegion is the type used to implement the Region propriety in TCanvas, and passed as an argument to the SetShape method in TWinControl.

Some operating systems and widgetsets allow regions to be defined with ellipses, rounded rectangles, and polygons as the sub-regions. TRegion is limited to the rectangle with the area that is the bounding box for a shape. See TLazRegion in LazRegions.pas and TLazCanvas in LazCanvas.pas for alternate implementations that provide these capabilities.
Adds the specified operation to the region.
AddOperation is an empty implementation in the current LCL version.
Clears sub-regions defined for the region.
ClearSubRegions is an empty implementation in the current LCL version.
Adds a sub-region with the specified handle to the region .

AddSubRegion is an empty implementation in the current LCL version.

Frees the Region Reference in the class instance.
Gets the value for the Reference property.
Value for the property.
Gets the value for the Handle property.
Value for the property.
Ensures that resources are allocated in Reference for the region.
Sets the value for the Handle property.
New value for the property.
Sets the value for the ClipRect property.
New value for the property.
Gets the value for the ClipRect property.
Value for the property.
Constructor for the class instance.
TObject.Create
Destructor for the class instance.

Destroy is the overridden destructor for the class instance. It calls FreeReference to free resources allocated for the Reference, and calls the inherited destructor prior to exit.

TPersistent.Destroy
Assign
- if Source is another TRegion, copies the dimensions of the clipping rectangle.
TPersistent.Assign
Persistent object with properties copied in the method.
Convenience routine to add a rectangle to the region.

Gets a handle for the rectangular defined by the opposing corners with the X1, Y1, X2, and Y2 coordinates. The new region handle is OR'd with the existing handle for the region.

Calls ReferenceNeeded to ensure that the handle for the region has been allocated.

Discards the new region handle by calling DeleteObject.

Horizontal coordinate for one corner of the rectangular area.
Vertical coordinate for one corner of the rectangular area.
Horizontal coordinate for the opposing corner of the rectangular area.
Vertical coordinate for the opposing corner of the rectangular area.
The clipping rectangle for the region.
Operating System Handle for the region.
HRGN
A Reference to the current Region.
Abstract base class used for images in supported image formats.

The TGraphic class is an abstract base class for graphic images in image formats supported in the LCL. TGraphic establishes an API that is used in the LCL to read and write image data using a file, stream, resource, or the clipboard. Many of its methods are defined as virtual and/or abstract, and must be implemented (or re-implemented) in descendent classes to provide support for specific image formats.

Methods defined in TGraphic include:

- LoadFromFile
- LoadFromStream
- LoadFromMimeStream
- LoadFromLazarusResource
- LoadFromResourceName
- LoadFromResourceID
- LoadFromClipboardFormat
- LoadFromClipboardFormatID
- SaveToFile
- SaveToStream
- SaveToClipboardFormat
- SaveToClipboardFormatID
- GetSupportedSourceMimeTypes
- GetResourceType
- GetFileExtensions
- IsStreamFormatSupported

TGraphic does not contain a mechanism for displaying or rendering an image. This capability is implemented in descendent classes which provide a TCanvas suitable for the image data, such as: TRasterImage, TBitmap, TIcon, TPixmap, TJPegImage, TGifImage, et. al.

Properties common to most image formats are defined in the class, and include:

- Height
- Width
- Modified
- Empty
- MimeType
- Palette
- PaletteModified
- Transparent

Event handlers are provided for change and progress notifications, including:

- OnChange
- OnProgress

TGraphic is the type used to implement the Graphic property in TPicture, and passed as an argument to methods in TCanvas.

Performs action needed when the image data has changed.

Changed is a procedure used to perform actions needed when the image data for the class instance has been changed. Changed sets the value in Modified to True, and signals the OnChange event handler (when assigned).

Changed is called when the value in Modified is changed from False to True.

Object for the change notification.
Determines if the specified class instance is the same as the current class instance.
True when the specified object the same instance as the current class.
TGraphics instance compared in the method.
TObject instance compared in the method.
DefineProperties
finds out whether the object really is a binary (graphic).

Ensures that ReadData and WriteData are used to read the binary values for image data in TGraphic instances. Calls the DefineBinaryProperty method in Filer to set the read and write procedures for the data.

TFiler instance used to read and write property values during component streaming.
Method to Draw the Graphic on the specified Canvas, in the specified Rectangle.

Draw is an abstract virtual procedure used to render data in the graphic to the specified Canvas using the given coordinate rectangle. Draw must be implemented in a descendent class to perform actions required for a specific image format.

Canvas is the TCanvas instance where the graphic is rendered.

Rect is a TRect instance with the coordinates where graphic is drawn on the Canvas.

Canvas used to render the graphic.
Canvas coordinates where the graphic is drawn.
Gets the value for the Empty property.

GetEmpty is an abstract virtual Boolean function used to get the value for the Empty property. The return value is True when no image data exists for the graphic.

GetEmpty must be implemented in a descendent class to provide support for a specific image format.

True when no data exists in the graphic.
Gets the value for the Height property.
Value for the property.
Gets the value for the MimeType property.
Gets the value for the Palette property.

Always returns 0 (representing an unassigned handle) in TGraphic.

Value for the property.
Gets the value for the Transparent property.
Value for the property.
Gets the value for the Width property.
Value for the property.
Monitor the Progress of the drawing.

Progress is an overloaded procedure used to perform actions needed for progress notifications for the class instance. Arguments passed to the method identify the class instance, the progress step, the completion amount, and display options for the notification.

Progress signals the OnProgress event handler (when assigned) using the parameter values as arguments. Applications must implement an OnProgress event handler to respond to the progress notification.

Progress is a virtual method, and can be overridden in a descendent class to preform any actions needed when reading or writing image data for a specific image format.

Please note the data type used for the PercentDone argument. It is declared as a Byte type, and will accept a value that exceeds 100.
Object for the notification.
Indicates whether an operation is starting, running, or ending.
Completion percentage for the progress step.
Indicates if the application should redraw the image.
Rectangle with the coordinates affected by the progress step.
Message for the progress notification.
Indicates if the caller should continue the current operation.
ReadData
- reads data for the Graphic from a stream.

ReadData is a procedure used to read binary data for the graphic from the specified stream. It is used by the TFiler instance which loads data during component streaming.

ReadData calls LoadFromStream to complete the operation.

TStream instance where data for the graphic is stored.
Sets the value for the Height Property.

SetHeight is an abstract virtual method, and must be implemented in a descendent class.

New value for the property.
Sets the value for the Palette property.

SetPalette is an empty implementation in TGraphic.

New value for the property.
Sets the value for the Transparent property.

SetTransparent is an abstract virtual method, and must be implemented in a descendent class.

New value for the property.
Sets the value for the Width property.

SetWidth is an abstract virtual method, and must be implemented in a descendent class.

New value for the property.
Sets the value for the Modified property.
Value for the property.
WriteData
- writes Graphic data to a stream.
Assign
- checks if there really is a source to assign (if not, calls

Clear
), then calls inherited method.
TPersistent.Assign
Persistent object with values copied in the method.
Clear
the resources used by the Graphic, leaving a blank Graphic.
Create
- constructor for TGraphic: calls inherited Create.
Virtual method, so recommend that a constructor be supplied to override this method in descendent classes.
TObject.Create
Determines if the specified resource type is valid for the image format.

LazarusResourceTypeValid is a Boolean function used to determine if the specified resource type is valid for the image format.

LazarusResourceTypeValid always returns False in TGraphic. The method must be overridden in descendent classes to check for resource type(s) supported for a specific image format.

Returns True when ResourceType is supported in the image format.
The resource type examined in the method.
Reads data for the graphic from a file.

LoadFromFile reads data for the graphic from the local file system. FileName contains the name of the file on the local file system with data for the graphic, and may contain UTF-8-encoded characters in the file name.

LoadFromFile creates a temporary TFileStreamUTF8 instance that is used to read the contents of the file by calling LoadFromStream. Any existing image data in the class instance is discarded. An Exception can be raised in LoadFromStream if Filename does not contain a valid file name.

Raises an Exception if an invalid file name is passed to the method.
The name of the file containing the graphic data.
Reads graphic data from a stream.

LoadFromStream is an abstract virtual method used to load graphic data from the stream instance specified in Stream. It must be implemented in a descendent class to provide support for reading a specific image format from the stream.

LoadFromStream is used in the implementation of methods like: ReadData, LoadFromMimeStream, LoadFromResourceID, LoadFromResourceName, LoadFromLazarusResource, and LoadFromFile.

TStream instance with the graphic data read in the method.
Loads the from the specified stream for the given MIME type.

LoadFromMimeStream reads graphic data from a stream for the given MIME type. LoadFromMimeStream compares the value in AMimeType to the value in the MimeType property. When the values are the same, the LoadFromStream method is called the load the image data for the graphic from the stream in AStream.

In TGraphic, an EInvalidGraphic is raised when AMimeType contains any value other than an empty string ('').

Must be overridden in a descendent class to provide support for a MIME type representing a specific image format.
Stream with the content loaded in the method.
MIME type representing the stream content.
Load the graphic data from a Lazarus Resource (.lrs) file.
Name of the .lrs file with the content loaded in the method.
Loads a resource with the specified name from the given handle.

LoadFromResourceName is a procedure used to load a resource with the name specified in ResName using the handle provided in Instance. LoadFromResourceName calls GetResourceType to get the Integer resource type used in the class instance. No actions are performed in the method when the TResourceType value is unassigned (contains Nil).

LoadFromResourceName creates a temporary TResourceStream that is used to load the content for the class instance by calling the LoadFromStream method.

Use LoadFromResourceID to load a resource by its Resource ID.

Use LoadFromLazarusResource to load a Lazarus resource from a .lrs file with a give name.

Handle where the content for the resource is stored.
Name for the resource loaded in the method.
Load graphic data from a resource identified by the integer identifier ResID.

LoadFromResourceID is a procedure used to load a resource with the specified Resource ID into the class instance. Instance contains the Handle used to read the resource. LoadFromResourceName calls GetResourceType to get the Integer resource type used in the class instance. No actions are performed in the method when the TResourceType value is unassigned (contains Nil).

LoadFromResourceName creates a temporary TResourceStream that is used to load the content for the class instance by calling the LoadFromStream method. The value in ResID is located in the resource, and its resource handle is used to get the content stored in the stream.

An EResNotFound exception is raised during stream initialization if the resource type or the resource handle is invalid.

Use LoadFromResourceName to load a resource with a given resource name.

Use LoadFromLazarusResource to load a Lazarus resource from a .lrs file with a give name.

Raises an EResNotFound exception when the TResourceStream is initialized if the resource type or the resource handle is invalid.
Handle where the content for the resource is stored.
Pointer to the Integer Resource ID for the resource.
LoadFromClipboardFormat
- Replace the current image with the contents of the clipboard.
LoadFromClipboardFormat
- Replaces the current image with the data provided from the clipboard.
If the TGraphic does not support that format it will generate an exception.
Load the data from the clipboard using the format type specified by ClipboardType and the format identifier FormatID.
Writes graphic data to the specified file name.

SaveToFile is a procedure used to write the graphic data in the class instance to the specified file name. Filename is the fully-qualified file name on the local file system where the data is stored, and may contain UTF-8-encoded characters.

SaveToFile creates a temporary TFileStreamUTF8 instance that is used to write graphic data by calling the SaveToStream method.

The name of the file where the graphic data is stored.
SaveToStream
- write graphic data to a stream.

SaveToStream is an abstract virtual method in TGraphic. It must be implemented in a descendent class to provide support for a specific graphic format.

Stream instance where the graphic data is stored.
SaveToClipboardFormats
- Converts the image to a clipboard format.
SaveToClipboardFormats
- Converts the image to a clipboard format.
If the image does not support being translated into a clipboard format it will generate an exception
Identity of the clipboard format.
Saves the data to a clipboard of Type ClipboardType using the format FormatID.
Gets a list of supported MIME types for data used in the graphic.
Gets the Integer Resource Type for the class instance.

GetResourceType is a TResourceType function used to get the resource type identifier for the class instance. It identifies the storage format used for graphic data in a resource.

GetResourceType is declared as a virtual method, and is normally overridden in descendants to return the resource type identifier for a specific image format. The return value is RT_RCDATA in TGraphic.

GetResourceType is used in the implementation of methods including: LoadFromResourceID and LoadFromResourceName.

TResourceType value used in the class instance.
Returns a list of the file extensions available.

GetFileExtensions is a String class function used to get a delimited list of file extensions used for graphic files supported in the class. The '.' character is omitted from file extension(s), and extensions are separated by a SemiColon (;) character. For example:

'jpeg;jpg;jpe;jfif'

GetFileExtensions is declared as a virtual class method, and is overridden in descendants to return the value(s) used for the supported graphic format. In TGraphic, the return value is always an empty string ('').

File extensions supported for the graphic format used in the class.
Indicates whether the specified stream type is supported in the class.

IsStreamFormatSupported is a Boolean class function used to determine if the specified stream contains graphic data in a format supported in the class.

IsStreamFormatSupported is declared as a virtual method, and is overridden in descendants to check whether the values stored in the stream instance can be used in the reader and/or writer classes for the graphic format.

In general, IsStreamFormatSupported indicates whether the LoadFromStream method can be successfully used to load graphic data into the class instance using the specified stream.

True when the stream contains supported graphic data; otherwise, False.
Stream with content examined in the method.
Indicates if the graphic is empty (contains no data).

Empty is a read-only Boolean property which indicates if the graphic is empty (contains no data). The return value is True when no image data exists for the graphic.

The native, unstretched height for the graphic.

Height is an Integer property which contains the native, unstretched height for the graphic stored in the class instance.

Use Width to access the native width for the graphic.

Please note that both the read and write access specifiers for the property are declared as abstract virtual method in TGraphic. They must be implemented in a descendent class to provide support for a specific graphic format.
Indicates if the graphic data in the class instance has been modified.

Modified is a Boolean property which indicates if the graphic data in the class instance has been modified. Setting the value in Modified to True causes the Changed method to be called to signal the OnChange event handler (when assigned).

Modified is updated when methods in descendent classes call the Changed method.

MimeType
- the MIME type of the graphic.

MimeType is a read-only String property which contains the MIME type (or IANA Media Type/Subtype) used for the graphic data in the class instance. MimeType is composed of values representing the general category for the data and a specification of the exact content for the type. It conforms to the values defined by the IANA (Internet Assigned Numbers Authority).

In TGraphics, the MimeType is always an empty string (''). In descendent classes, the value indicates that it is in the 'image' category and uses a subtype with the common extensions for the graphics format. For example:

- 'image/bmp'
- 'image/gif'
- 'image/jpg'
- 'image/jpeg'
- 'image/png'
- 'image/xpm'

Event handler signalled when data in the class instance is changed.

OnChange is a TNotifyEvent property with an event handler signalled when data in the class instance is changed.

OnChange is triggered from the Changed method (when assigned), and occurs after values in the class instance have been modified. In TGraphic, it indicates that the Modified property has been set to True. In descendent classes, which support specific image formats and provide a Canvas, it occurs more frequently.

Applications must assign an object procedure to respond to the event notification. The Sender argument contains the object which triggered the event notification.

Event handler signalled to track the progress of operations in the class instance.

OnProgress is a TProgressEvent property with the event handler signalled to track the progress of operations in the class instance. See the Progress topic for more detailed information.

Applications must assign an object procedure to the event handler to respond to progress notification messages. The Sender argument contains the object with triggered the notification.

Handle to the color palette used in image data.

Palette is a HPALETTE property which contains the handle to the color palette used in image data. When Palette is set to 0, the graphic does not need or use a palette.

The value for the property is always 0 in the current implementation. Setting a new value is not implemented.
Indicates whether the palette of colors been modified.

Currently, it is used in the jvcllaz package in the TJvImageControl class.

Indicates whether some parts of the image are not opaque.
Width
- The native, unstretched, width of the graphic.
TGraphicClass
- class of TGraphic.
Implements a container for TGraphic and descendent classes.

TPicture is a TGraphic container. It is used in place of a TGraphic if the graphic can be of any TGraphic class.

It is not a direct descendant of TGraphic, so you will not see TGraphic listed in the Inheritance chart, but it contains a property Graphic, of type TGraphic, so can contain all the properties of a TGraphic.

Defines many private methods for getting and storing various sorts of images such as bitmaps, pixmaps, icons, PNGs etc.

TPicture does not have a defined area used to display the image. This is supplied in the Canvas property in the classes which support BitMap, PixMap, PNG, JPEG, GIF, TIFF or Icon image formats.

LoadFromFile and SaveToFile are polymorphic. For example, if the TPicture is holding an Icon, you can LoadFromFile a bitmap file, whereas if the class is TIcon you could only read .ICO files.

- LoadFromFile
  - Reads a picture from disk. The TGraphic class created is determined by the file extension of the file. If the file extension is not recognized an exception is generated.
- SaveToFile
  - Writes the picture to disk.
- LoadFromClipboardFormat
  - Reads the picture from the handle provided in the given clipboard format. If the format is not supported, an exception is generated.
- SaveToClipboardFormats
  - Allocates a global handle and writes the picture in its native clipboard format (CF_BITMAP for bitmaps, CF_METAFILE for metafiles, etc.). Formats will contain the formats written. Returns the number of clipboard items written to the array pointed to by Formats and Datas or would be written if either Formats or Datas are Nil.
- SupportsClipboardFormat
  - Returns true if the given clipboard format is supported by LoadFromClipboardFormat.
- Assign
  - Copies the contents of the given TPicture. Used in the implementation of TPicture properties.
- RegisterFileFormat
  - Register a new TGraphic class for use in LoadFromFile.
- RegisterClipboardFormat
  - Registers a new TGraphic class for use in

  LoadFromClipboardFormat
  .
- UnRegisterGraphicClass
  - Removes all references to the specified TGraphic class and all its descendants from the file format and clipboard format internal lists.
- Height
  - The native, unstretched, height of the picture.
- Width
  - The native, unstretched, width of the picture.
- Graphic
  - The TGraphic object contained by the

  TPicture
- Bitmap
  - Returns a bitmap. If the contents is not already a bitmap, the contents are discarded and a blank bitmap is returned.
- Pixmap
  - Returns a pixmap. If the contents is not already a pixmap, the contents are discarded and a blank pixmap is returned.
- PNG
  - Returns a png. If the contents is not already a png, the contents are discarded and a blank png ( TPortableNetworkGraphic) is returned.
- PNM
  - Returns a pnm. If the contents is not already a pnm, the contents are discarded and a blank pnm ( TPortableAnyMapGraphic) is returned.
- Jpeg
  - Returns a jpeg. If the contents is not already a jpeg, the contents are discarded and a blank jpeg ( TJPegImage) is returned.

Ensures that the Graphic property is an instance of the specified class.

When the Graphic member is not a descendant of GraphicType, an new instance of GraphicType is created and used as the member variable for the Graphic property. The values in the existing Graphic property is assigned to the new class instance, and the old instance is freed. The Changed and Process methods are assigned to the OnChange and OnProgress event handlers in the new TGraphic class instance. The Changed method is called to signal the OnChange event handler (when assigned).

No actions are performed in the method when the Graphic member is an instance of the class in GraphicType.

ForceType is used in the read access specifiers for properties using the various supported image formats, like: Bitmap, Icon, Jpeg, Pixmap, PNG, and PNM.

Class type required in the Graphic member.
Gets the value for the Bitmap property.

Calls ForceType to ensure that Graphic is a TBitmap class instance.

Value for the property.
Gets the value for the Icon property.

Calls ForceType to ensure that Graphic is a TIcon class instance.

Value for the property.
Gets the value for the Jpeg property.

Calls ForceType to ensure that Graphic is a TJpegImage class instance.

Gets the value for the PNG property.

Calls ForceType to ensure that Graphic is a TPortableNetworkGraphic class instance.

Value for the property.
Gets the value for the PNM property.

Calls ForceType to ensure that Graphic is a TPortableAnyMapGraphic class instance.

Value for the property.
Gets the value for the Pixmap property.

Calls ForceType to ensure that Graphic is a TPixmap class instance.

Value for the property.
Gets the Height of the image stored in the Graphic property.

The return value is 0 (zero) if Graphic has not been assigned (contains Nil).

Use Width to the width of the image in the Graphic property.

Height of the image in the Graphic property.
Gets the width of the image stored in the Graphic property.

The return value is 0 (zero) if Graphic has not been assigned (contains Nil).

Use Height to the height of the image in the Graphic property.

Width of the image stored in the Graphic property.
Reads data for the persistent object during LCL streaming.

ReadData implements the procedure used to read a persistent object during LCL streaming. Stream is the TStream instance with the data for the persistent object.

ReadData is used by the TFiler instance for the class type.

TStream instance with the data for the persistent object.
Sets the value for the Bitmap property.

Calls SetGraphic to assign the new property value to the Graphic property.

New value for the property.
Sets the value for the Icon property.

Calls SetGraphic to assign the new property value to the Graphic property.

New value for the property.
Sets the value for the Jpeg property.

Calls SetGraphic to assign the new property value to the Graphic property.

New value for the property.
Sets the value for the PNG property.

Calls SetGraphic to assign the new property value to the Graphic property.

New value for the property.
Sets the value for the PNM property.

Calls SetGraphic to assign the new property value to the Graphic property.

New value for the property.
Sets the value for the Pixmap property.

Calls SetGraphic to assign the new property value to the Graphic property.

New value for the property.
Sets the value for the Graphic property.

SetGraphic is the write access specifier for the Graphic property.

SetGraphic ensures that the TGraphic instance in the new property Value is copied and used as the member variable for the property. The class type in Value is used to create a temporary class instance where Value is stored. Its OnChange and OnProgress event handlers are set to the addresses for the Changed and Progress methods (respectively). The existing member variable is freed, and the new class instance is used as the member variable. The Changed method is called to signal the OnChange event handler (when assigned).

No actions are performed in the method when Value is unassigned (contains Nil), or when Value and Graphic are the same class instance.

SetGraphic is called when a new value is assigned to properties representing a specific image format, like:

- Bitmap
- Icon
- Jpeg
- Pixmap
- PNG
- PNM

New value for the property.
Writes data for the persistent object during LCL component streaming.
AssignTo
if Dest is the correct (Graphic) class type, calls Assign for Dest, otherwise calls inherited AssignTo.
TPersistent.Assign
Persistent object where the values from the class instance are stored.
Performs actions needed when value(s) in the class instance have been modified.

Changed performs actions needed when value(s) in the class instance have been modified. In TPicture, it signals the OnChange event handler (when assigned). No actions are performed in the method when OnChange has not been assigned (contains Nil).

Defines properties handled during LCL component streaming.

DefineProperties is an overridden method in TPicture, and re-implements the method defined in TPersistent. DefineProperties uses the TFiler instance in Filer to identify the binary properties handled during LCL component streaming. The ReadData and WriteData methods are assigned as the procedures used to read and write the data for the persistent object. An internal method is used to determine whether binary data is available in the Graphic property.

TFiler instance used to read and write the persistent object.
Monitors progress of a drawing process.

Performs actions needed to monitor the progress of operations in the class instance.

The parameters identify the calling object, the action being performed, the completion percentage, whether the picture should be redraw. The DoContine variable parameter is updated in the event handler to indicate if the process is continued. False indicates an error condition where the process should be halted. It is set to True on entry.

Progress signals the OnProgress event handler (when assigned) using the parameters values as arguments.

No actions are performed in the method when OnProgress has not been assigned (contains Nil). In this scenario, DoContine returns True.

See Progress for more details on progress monitoring.

Object for the notification.
Loads values for the Graphic property from a stream using the specified class type.
Create
- constructor for TPicture: performs inherited Create then loads file and clipboard formats.

Create is the overridden constructor for the class instance, and calls the inherited constructor on entry.

Creates ensures that the list of image formats supported in LCL has been initialized with the class types and file extensions as required. The list of clipboard formats for the supported image formats is also initialized when needed.

TObject.Create
Destroy
- destructor for TPicture: frees graphic then performs inherited Destroy.
Any destructor method defined here will override destructors defined in ancestor classes.
TPersistent.Destroy
Clear
- removes the Graphic in the class instance.
LoadFromClipboardFormat
- Reads the picture from the handle provided in the given clipboard format.
LoadFromClipboardFormat
- Reads the picture from the handle provided in the given clipboard format.
If the format is not supported, an exception is generated
The identifier for the clipboard format.
Reads the picture from a clipboard of type ClipboardType using the format FormatID.
LoadFromFile
- Reads a picture from disk.
LoadFromFile
- Reads a picture from disk. The TGraphic class created is determined by the file extension of the file.
If the file extension is not recognized an exception is generated
The name of the file containing the picture, stored as a string.
Loads content from the specified resource into the Graphic property.

LoadFromResourceName is an overloaded method used to created a TGraphic instance with the content from the specified resource name. Instance is the Handle with the resources examined in the method. ResName is the name of the resource loaded in the method.

LoadFromResourceName creates a new TGraphic class instance that is used as the member variable for the Graphics property. The CreateGraphicFromResourceName routine is called to create the graphic and load the named resource from the handle. The Changed method is assigned to the OnChange event handler in the class instance.

An overloaded variant includes an AClass argument with the class type for the TGraphic descendant needed for a supported image format. The LoadFromStream in the class instance is called to load the named resource.

The existing TGraphic instance in Graphic is freed and the new TGraphic instance is used as the member variable. The Changed method is called to signal the OnChange event handler (when assigned).

Handle with the resources examine in the method.
Name of the resource loaded in the method.
TGraphic descendant for the image format.
Gets the named resource from a Lazarus Resource (.lrs) file.
File name with resource retrieved in the method.
Loads a supported image format from the specified stream.
Loads picture from a stream with a specified file extension.
SaveToClipboardFormats
- Allocates a global handle and writes the picture in its native clipboard format.

SaveToClipboardFormats - Allocates a global handle and writes the picture in its native clipboard format ( CF_BITMAP for bitmaps, CF_METAFILE for metafiles, etc.). Formats will contain the formats written. Returns the number of clipboard items written to the array pointed to by Formats and Datas or would be written if either Formats or Datas are Nil.

Identity of the clipboard format.
SaveToFile
- Writes the picture to disk.
The name of the file to save the picture, stored as a string.
Saves the graphic to the specified stream.
TStream instance where the graphic is stored.
Saves the graphic to a stream using the class type for the specified file extension.
SupportsClipboardFormat
- Returns true if the given clipboard format is supported by LoadFromClipboardFormat.
Boolean - returns true if format supported.
Identity of the clipboard format.
Assign
- if the Source is a valid graphic type, copy the relevant details to the current object, otherwise call inherited

Assign
.
Assign
- Copies the contents of the given TPicture. Used most often in the implementation of TPicture properties.
TPersistent.Assign
RegisterFileFormat
- Register a new TGraphic class for use in LoadFromFile.
RegisterClipboardFormat
- Registers a new TGraphic class for use in LoadFromClipboardFormat.
UnRegisterGraphicClass
- Removes all references to the specified TGraphic.
UnRegisterGraphicClass
- Removes all references to the specified TGraphic class and all its descendants from the file format and clipboard format internal lists.
Finds a graphic class with the named file extension Ext, returning an exception if not found.
Bitmap
- Returns a bitmap.
Bitmap
- Returns a bitmap. If the contents is not already a bitmap, the contents are discarded and a blank bitmap is returned.
Icon
contained within the picture.
Jpeg
- returns a JPEG image.

Jpeg - returns a JPEG image.

If the contents is not already a JPEG image, the contents are discarded and a blank JPEG is returned.

Pixmap
- Returns a pixmap.
Pixmap
- Returns a pixmap. If the contents is not already a pixmap, the contents are discarded and a blank pixmap is returned.
PNG
- Returns a png.
PNG
- Returns a png. If the contents is not already a png, the contents are discarded and a blank png (TPortableNetworkGraphic) is returned.
PNM
- a PortableAnyMapGraphic image.

PNM - a PortableAnyMapGraphic image.

Reads a PNM image. If it is not a valid PNM image, the contents are discarded and a blank PNM is generated.

Graphic
- The TGraphic object contained by the TPicture.
Height
- The native, unstretched, height of the picture.
Width
- The native, unstretched, width of the picture.
OnChange
- Event handler for any change in the picture.
OnProgress
- Event handler for monitoring progress in drawing the picture.
Base exception type for an error in a graphic operation.

EGraphicException is an Exception descendant which implements the base class for exceptions raised during graphic operations. It provides a means to handle any of the descendent exceptions, like EInvalidGraphic or EInvalidGraphicOperation.

EInvalidGraphic
- exception handler for an invalid graphic.
EInvalidGraphicOperation
- exception handler for invalid graphic operation.
Represents fill directions for gradients.
Gradient fill direction is vertically oriented.
Gradient fill direction is horizontally oriented.
Represents anti-aliasing modes used in TCanvas.
Default anti-aliasing.
Enabled.
Disabled.
Represents text metrics used in the LCL.
The portion of a font face above the mean line.
The portion of a font face below the baseline for a font face.
Distance between the baseline and the mean line for a font face.
Indicates whether a default color applies to a font or a brush.

Values from TDefaultColorType are passed as an argument to the GetdefaultColor method in TCanvas. It allows the the color clDefault to be resolved to the correct color value in the class instance.

Default color refers to the the Brush color.
Default color refers to the the Font color.
Implements a drawing surface for a visual control or bitmap image.

TCanvas is a descendant of the TFPCustomCanvas class in the FCL (Free Pascal Component Library). TCanvas implements a drawing surface which can be used to display a visual control or render output to a bitmap. TCanvas provides drawing tools like Brush, Pen, and Font needed to draw on the surface. Events are provided to respond to change notifications and progress events. Methods are provided to implement common drawing operations, such as:

- Pen, Brush, and Color selection
- Drawing lines or shapes
- Filling shapes with colors or patterns
- Rendering text to the drawing surface
- Rendering image content to the drawing surface
- Direct manipulation of pixels on the drawing surface

A TCanvas instance (or a specialized descendant) is used in visual controls which are responsible for rendering their own content. It is also used in non-visual components like TPrinter, and in class that provide support for drawing operations using bitmap data.

TGraphicControl.Canvas TCustomControl.Canvas TControlCanvas
Performs actions needed when the Brush for the canvas is changed.

BrushChanged is a procedure used to perform actions needed when the Brush for the canvas is changed. BrushChanged ensures that state flags for the class instance are updated to remove the value csBrushValid (when present).

ABrush contains the Brush instance which generated the change notification.

BrushChanged is assigned as the OnChange event handler in the TBrush instance used in the Brush property.

Brush instance generating the change notification.
Performs actions needed when the Font for the canvas is changed.

FontChanged is a procedure used to performs actions needed when the Font for the canvas is changed. FontChanged ensures that state flags for the canvas are updated to remove the value csFontValid (when present).

AFont is the font instance which generated the change notification.

FontChanged is assigned as the OnChange event handler in the TFont instance used in the Font property.

Font instance generating the change notification.
Performs actions needed when the Pen for the canvas is changed.

PenChanged is a procedure used to performs actions needed when the Pen for the canvas is changed. PenChanged ensures that state flags for the canvas are updated to remove the value csPenValid (when present).

APen is the pen instance which generated the change notification.

PenChanged is assigned as the OnChange event handler in the TPen instance used in the Pen property.

Pen instance generating the change notification.
Performs actions needed when the Region for the canvas is changed.

RegionChanged is a procedure used to perform actions needed when the Region for the canvas is changed. RegionChanged ensures that state flags for the canvas are updated to remove the value csRegionValid (when present).

ARegion is the region instance which generated the change notification.

RegionChanged is assigned as the OnChange event handler in the TRegion instance used in the Region property.

Region instance generating the change notification.
Gets the value for the Handle property.
Value for the property.
Sets the value for the AntialiasingMode property.
Value for the property.
Sets the value for the AutoRedraw property.
Value for the property.
Sets the value for the Font property.
New value for the property.
Sets the value for the Pen property.
New value for the property.
Sets the value for the Brush property.
New value for the property.
Sets the value for the Region property.
New value for the property.
Creates the TFont instance used as the default font for the canvas.

DoCreateDefaultFont is an overridden method in TCanvas used to create the TFont instance used as the default font for the canvas. The return value contains the TFont instance created in the method.

DoCreateDefaultFont implements the abstract method defined in the TFPCustomCanvas ancestor. It is called from the inherited CreateDefaultFont method, and ensures that a font resource has been allocated for the Font property.

TFont instance created in the method.
DoCreateDefaultPen
- calls TPen.Create to create a default pen.
DoCreateDefaultBrush
- calls TBrush.Create to create a default brush.
Sets the value for the indexed Colors property.

SetColor is a method used to set the value for the indexed Colors property. SetColor implements the abstract virtual method defined in the TFPCustomCanvas ancestor. Equivalent to setting the color value using the Pixels property.

Horizontal coordinate for the pixel.
Vertical coordinate for the pixel.
Color for the specified pixel.
Gets the Color for the pixel at the given coordinates as a TFPColor value.

Uses the indexed Pixels property to retrieve the color information for the pixel at the coordinates in x and y. Calls TColorToFPColor to convert the TColor value to the TFPColor type used in the return value.

TFPColor value for the pixel at the specified position.
Horizontal position for the pixel.
Vertical position for the pixel.
SetHeight
- should never be called for Canvas: raises an exception if it is called.
If called, raises an exception: 'TCanvas.SetHeight not allowed for LCL canvas.
GetHeight
- if a handle has been allocated, returns the height from the device size.
SetWidth
- should never be called; raises an exception if it is called.
Raises an exception: 'TCanvas.SetWidth not allowed for LCL canvas'
Gets the value for the Width property.

If a valid Handle for the canvas instance has not been allocated, the value for the property is 0 (zero).

Value for the property.
Moves the pen to the specified position.

Re-implements the method defined in the TFPCustomCanvas ancestor. Calls MoveTo using the X and Y coordinates specified in Value. Does not call the inherited method.

TPoint instance with the canvas coordinates for the pen.
Enters the critical section used to lock the canvas, and calls the inherited method.
Leaves the critical section used to lock the canvas, and calls the inherited method.
DoTextOut
calls TextOut for the specified coordinates and string.
Calls TextExtent to find the width and height of the specified text.
DoGetTextHeight
calls TextHeight to return the height of the text.
DoGetTextWidth
calls TextWidth to return the width of the given text string.
DoRectangle
calls Frame to draw a rectangle in the given bounds.
DoRectangleFill
calls FillRect to draw a filled rectangle with the given bounds.
DoRectangleAndFill
- calls Rectangle to draw a rectangle and fill it.
Draws an Arc of 360 degrees within the specified Bounds.
DoEllipse
draws an Arc of 360 degrees within given Bounds, making an ellipse.
DoEllipseFill
calls Ellipse.
DoEllipseAndFill
calls the inherited DoEllipseAndFill.
DoPolygon
calls PolyLine to draw a series of lines through the points.
DoPolygonFill
calls Polygon for the supplied points.
DoPolygonAndFill
calls inherited method.
DoPolyline
calls PolyLine.
TCanvas.PolyLine
Performs actions needed to draw a Bézier curve using the specified control points.

Calls the PolyBezier method using the values in Points, NumPts, Filled, and Continuous as arguments.

Pointer to the control points for the Bézier curve.
Number of control points in the Pointer.
True if interior of the Bézier curve is filled; default is False.
True if the Bézier end-points are continuous (without kinks); default is False.
DoFloodFill
calls the FloodFill method.
DoMoveTo
calls the MoveTo method.
DoLineTo
calls the LineTo method.
DoLine
calls Line to draw from x1, y1 to x2, y2.
Verifies and copies the source canvas.

DoCopyRect checks that SrcCanvas is of correct type then copies coordinates and calls CopyRect.

If SrcCanvas is not of type TCanvas then writes a warning to the debug output that copying is not supported
DoDraw
checks that Image is of the right type, makes a local copy, creates the necessary handles and bitmaps for drawing.
Ignored in the current implementation of the class.
Writes a message to debug output indicating the call is ignored.
Gets the default color value for the canvas.
TColor value that is the default color for the canvas.
Not used in the current implementation.
GetClipRect
- if an error is encountered in finding the Clipping Rectangle dimensions, sets some defaults anyway.
Sets the value for the ClipRect property.

Overrides the method defined in the TFPCustomCanvas ancestor. Calls the inherited method. Handles conversion of the logical coordinates in the clipping rectangle to device coordinates, and sets the clipping region to the converted values.

New value for the property.
GetClipping
returns True if clipping is being performed.
SetClipping
specifies (via boolean argument) whether clipping is to be performed.
Gets the value for the indexed Pixels property.
Value for the property.
Horizontal canvas coordinate for the pixel.
Vertical canvas coordinate for the pixel.
Ensures that the handle for the Brush is valid and configured with the Brush settings.

CreateBrush is a procedure used to create and/or configure handles for the canvas Brush.

SelectObject is called to get an existing Brush handle, and save a copy of the handle for local access in the canvas. Canvas state flags are updated to indicate that the Brush handle is valid.

The styles store in Brush are checked for hatched-style brushes. When no hatch styles are used, the background color for the canvas is set to the color specified in Brush. If the Brush style is bsSolid, the background mode is set to OPAQUE. Otherwise, the TRANSPARENT background mode is used.

Ensures that the Font for the canvas is valid and uses the correct color.

Gets the handle for the Font from its Reference class. The first time the Font handle is selected, the handle for the default font is returned as saved for use with DeselectHandles.

CreateFont updates the state flags for the canvas to include the value csFontValid. SetTextColor is called to apply the color from the Font to the canvas Handle.

Creates a new Handle for the Canvas.
CreateHandle has an empty implementation in TCanvas.
Ensures that the Pen for the canvas is valid, configured, and positioned.

CreatePen is a procedure used to create, configure and position the pen for the canvas.

CreatePen calls SelectObject to get the Handle for the Pen, and saves a copy for local access in the class instance. The MoveTo method is called to position the Pen to the coordinates in the PenPos property. Canvas state flags are updated to indicate that the handle for the Pen is valid.

CreatePen is called when RequiredState is used to check for a valid pen handle.

Ensures that the handle for the canvas Region is valid.

CreateRegion is a procedure used to ensure that the handle for the rectangular Region in the canvas is valid.

CreateRegion calls SelectObject to the get the handle for the Region, and saves a local copy for access in the class instance. Canvas state flags are updated to indicates that the handle for the Region is valid.

CreateRegion is declared as a virtual method, and may be overridden in descendant classes.

CreateRegion is not used in the current LCL implementation.
Deselects all sub-handles in the current device context.
Implements the default OnChanging event handler used for the Pen in the canvas.

Ensures that canvas state flags indicate both the handle and the pen handle are valid. No actions are performed in the method if either handle is not valid.

Removes the value csPenValid from the canvas state flags, and selects the saved pen handle in the class instance. The internal copy of the saved pen handle is set to 0.

Object for the event notification.
Implements the OnChanging event handler for the Font used on the canvas.

FontChanging is assigned as the OnChanging event handler for the Font property in the constructor for the class instance. It allows the canvas class to be notified and updated when a new font is assigned to the canvas.

FontChanging ensures that both the Handle and the Font for the canvas are valid. No actions are performed in the method if State does not contain the values csFontValid and csHandleValid. It removes csFontValid from the States property and reselects the handle for the Font in the control.

Not used in the current implementation of the method.
Implements the OnChanging event handler for the Brush on the canvas.

BrushChanging is assigned as the OnChanging event handler for the Brush property in the constructor for the class instance. It allows the canvas class to be notified and updated when a new brush is assigned to the canvas.

BrushChanging ensures that both the Handle and the Brush for the canvas are valid. No actions are performed in the method if State does not contain the values csBrushValid and csHandleValid. It removes csBrushValid from the States property and reselects the handle for the Brush in the control.

Not used in the current implementation of the method.
Implements the OnChanging event handler for the Region on the canvas.

RegionChanging is assigned as the OnChanging event handler for the Region property in the constructor for the class instance. It allows the canvas class to be notified and updated when the region for the canvas is modified.

RegionChanging ensures that both the Handle and the Region for the canvas are valid. No actions are performed in the method if State does not contain the values csRegionValid and csHandleValid. It removes csRegionValid from the States property and reselects the handle for the Region on the control.

Not used in the current implementation of the method.
Implements the AutoRedraw feature when enabled.

RealizeAutoRedraw is called when a new value for the AutoRedraw property is assigned. No actions are performed in the method when AutoRedraw is False, or when the Handle for the canvas has not been allocated.

RealizeAutoRedraw calls the DCRedraw method in the widgetset class using the value in Handle as the device context.

Implements the Anti-aliasing feature for the canvas.

RealizeAntialiasing is called when a new value has been assigned to the AntialiasingMode property. No actions are performed in the method if the Handle has not been allocated for the canvas.

RealizeAntialiasing uses the value in AntialiasingMode to determine the action required in the method.

amOn
  Calls DCSetAntialiasing in the widgetset to enable anti-aliasing for the Handle.
amOff
  Calls DCSetAntialiasing in the widgetset to disable anti-aliasing for the Handle.
amDontCare
  Calls DCSetAntialiasing using the default capabilities for the widgetset.

Ensures that all handles needed for the canvas are valid.

RequiredState is a procedure used to ensure that the canvas state flags include the values specified in the ReqState parameter. The TCanvasStates values represent handles that must be allocated for the canvas.

When a state value is not present in the flags, the corresponding routine used to create the required handle is called.

csHandleValid
  Calls CreateHandle, and raises an EInvalidOperation if the handle could not be allocated. Sets the AntialiasingMode for the canvas. Includes csHandleValid in the canvas state flags on success.
csFontValid
  Calls CreateFont, and includes csFontValid in the canvas state flags on success.
csPenValid
  Calls CreatePen. Includes csBrushValid in the canvas state flags when the Pen style is a Brush pattern (psDash, psDot, psDashDot, psDashDotDot). Includes csPenValid in the canvas state flags on success.
csBrushValid
  Calls CreateBrush. Includes csBrushValid in the canvas state flags on success.

RequiredState is called from method implementations prior to performing an operation which requires a specific canvas state (or handles).

Required state flags.
Sets the value for the Handle property.

De-selects any existing handles in the class instance, and sets the new value for the property. Applies the anti-aliasing mode when the handle is valid. Updates the state flags for the canvas.

New value for the property.
SetInternalPenPos
- specify position for the Pen.
Sets the value for the indexed Pixels property.
Horizontal canvas coordinate for the pixel.
Vertical canvas coordinate for the pixel.
New value for the indexed property.
Frees the Handle for the canvas.

FreeHandle is a procedure used to free the Handle for the canvas. FreeHandle sets the value in Handle to 0 (zero) to indicate that it is unassigned.

Constructor for the class instance.

Create is the constructor for TCanvas. It calls the inherited Create method and sets defaults for many properties and actions.

It also initializes Font, Pen, and Brush properties and assigns their event handlers. It sets default values for Alignment, Layout, Clipping and Opacity.

Destructor for the class instance.

Destroy is the destructor for TCanvas. It frees handles and regions, and calls the inherited Destroy method, sets font, pen and brush resources to Nil in the TCanvas class instance and makes its resources available.

Lock
the canvas, making it unavailable for drawing.

Calls the LockCanvas method in the TFPCustomCanvas ancestor.

TryLock
- examines the Lock state, and performs Lock if necessary.
Unlock
or release a previously locked Canvas.

Calls the UnlockCanvas method in the TFPCustomCanvas ancestor.

Sets Pen, Brush, and Font handles to their default values.

Calls DeselectHandles to reset the handles to their default values. Requires a valid Handle for the canvas. Saved handles for the Pen, Brush, and Font are released.

Signals the OnChanging event handler (when assigned).

Changing is called in methods which perform drawing operations, and occurs before the actions that affect the handles or settings for the canvas.

Signals the OnChange event handler (when assigned).

Changed is called in methods which perform drawing operations, and occurs after the actions that affect the handles or settings for the canvas have been completed.

Stores the state for the Handle in the canvas.

SaveHandleState is used in the LCL instead of direct calls to SaveDC and RestoreDC in widgetset classes. Used along with RestoreHandleState. It allows multiple device contexts to be captured and handled in a LIFO fashion.

Restores the previous Handle state for the canvas.
Use Arc to draw an elliptically curved line with the current Pen.

Use Arc to draw an elliptically curved line with the current Pen. Arc is re-introduced in TCanvas to provide additional overloads for the method found in the platform-specific LCL interface object. Parameter values passed to the overloaded methods are in turn passed to the widgetset class for the platform.

ALeft, ATop, ABottom, and ARight represent the canvas bounds in which the drawing operation is performed.

One variant of the method provides the Angle16Deg and Angle16DegLength arguments.

Angle16Deg contains the central angle which defines the direction for the arc endpoint. Positive values indicate a counter-clockwise direction.Zero degrees lies at the 3 o'clock position. These value is expressed in 1/16ths of a degree. For example, a full circle equals 5760 (16*360) increments.

Angle16DegLength contains the arc length used to determine the over-all circumference of the circle for with the arc is a segment.

Another variant provides the SX, SY and EX, EY arguments representing the starting and ending radial points between which the Arc is drawn.

Drawing methods which reintroduce those in the TFPCustomCanvas ancestor class were added in LCL version 2.6.1.
Left boundary for the canvas.
Top boundary for the canvas.
Right boundary for the canvas.
Bottom boundary for the canvas.
Angle for the arc segment in 1/16ths of a degree.
Arc length.
Horizontal coordinate for the the starting radial point in the arc.
Vertical coordinate for the the starting radial point in the arc.
Horizontal coordinate for the the ending radial point in the arc.
Vertical coordinate for the the ending radial point in the arc.
Draws an elliptically curved line and updates the Pen position.
Like the Arc method, but updates the Pen position.
Draws a circular Arc with a given starting angle and boundary length in degrees.
Copies part of a bitmap to a rectangle on the canvas and replaces the transparent color with the Brush color.
Draw a filled chord shape starting and finishing at the specified angular positions on the circumference.

Use Chord to draw a filled Chord-shape on the canvas.

The angles angle1 and angle2 are 1/16th of a degree. For example, a full circle equals 5760 (16*360).

Positive values of Angle and AngleLength mean counter-clockwise while negative values mean clockwise direction. Zero degrees is at the 3 o'clock position.

Alternatively the starting and ending points may be specified as radial points (sx, sy, ex, ey).

Copies the rectangle found at Source in SrcCanvas to the destination position Dest.
Draw
- copies bounds from SrcGraphic, then calls StretchDraw to perform the drawing.
DrawFocusRect
- draws a focused rectangle at the specified position.
StretchDraw
- uses the Draw method of the source graphic ( TGraphic).
Draws a filled ellipse (or circle) on the canvas.
Ellipse
Fills a rectangular area on the canvas using the current Brush settings.

FillRect is an overloaded method used to fill a rectangular area on the canvas using the style, color, or bitmap defined in Brush. The overloaded variants allow the vertices for the rectangle to be specified as either:

- Four separate Integer coordinates representing the top/left and bottom/right of the shape.
- A TRect instance where the vertices are represented as either four Integers, two TPoint instances for TopLeft and BottomRight, or a vector using the TArray4IntegerType.

FillRect calls the routine in the LCL interface used to implement the method for a specific widgetset.

Use Rectangle to draw a filled rectangle with borders. Use FloodFill to fill a rectangular area bounded by a specified color value.

LCLIntf.FillRect
TRect instance with the vertices for the rectangular area filled in the method.
Left coordinate for the Top, Left of the rectangle.
Top coordinate for the Top, Left of the rectangle.
Right coordinate for the Bottom, Right of the rectangle.
Bottom coordinate for the Bottom, Right of the rectangle.
Fills an area at the specified coordinates with the current Brush for the canvas.

FloodFill is a method used to fill the area at the point specified in X, Y with the style, color, or bitmap defined in Brush.

FillColor contains the color value for the boundary of the fill, or the area to be filled, depending on the value in FillStyle.

FillStyle determines the type of fill operation performed in the method. For example:

fsBorder
  The fill area is bounded by pixels with the color specified in FillColor. Pixels are filled in all directions with the Brush until the a pixel with the specified color is found.
fsSurface
  The fill area is defined as the color specified in FillColor. Pixels with this color are filled in all directions with the Brush until no more pixels with this color are found.

Please note that comments in the TGraphicsFillStyle source code have these conditions reversed.

FloodFill calls the routine in the LCL interface used to implement the method for the widgetset. The return value from the LCL interface is ignored.

LCLIntf.FloodFill
Horizontal coordinate where the fill operation is performed.
Vertical coordinate where the fill operation is performed.
Color replaced or used as a boundary in the fill operation.
Determines whether FillColor is the boundary or the target for the fill operation.
Draws a frame for the specified rectangle with a 3-dimensional appearance.

Frame3D is an overloaded method used to draw a frame for the specified rectangle with a 3-dimensional appearance. It draws the frame using the Brush for the canvas with the style, colors, and size passed in the parameter values. Frame3D does not fill the inner area for the rectangle; it draws the frame or borders only.

ARect is the TRect instance with the bounds where the drawing operation is performed. It is a variable parameter updated in the method to return the inner area for the rectangle without the frame area.

The overloaded variants allow the drawing style and size for the 3-dimensional frame to be specified.

Style contains a value from the TGraphicsBevelCut enumeration and is used when a beveled frame is desired.

TColor values can be provided to use colors to simulate 3-Dimensional relief. TopColor is the color used to draw the top and left edges on the frame. BottomColor is used to draw the bottom and right edges on the frame. System colors like cl3DLight, cl3DHilight, cl3DDkShadow, cl3DShadow, and cl3DFace are commonly used in these parameters.

FrameWidth contains the thickness for the 3-D frame; for left and right edges it is the border width, for top and bottom edges it is the border height. The bounds in ARect are inflated by this value before exit.

TGraphicsBevelCut LCLIntf.Frame3D
Bounds for the rectangle on entry, the inner rectangle without the frame area on exit.
Thickness for the borders drawn in the method.
Bevel style used to draw the borders on the rectangle.
Color used for the top and left edges of the frame.
Color used for the bottom and right edges of the frame.
Draws a frame or border around the specified rectangle using the Pen for the canvas.

Frame is method used to draw a border or frame for the specified rectangle use the Pen for the canvas. Overloaded variants of the method are provided which allow the rectangle to be specified as:

- Four separate Integer coordinates representing the top/left and bottom/right of the rectangle.
- A TRect instance where the vertices are represented as either four Integers, two TPoint instances for TopLeft and BottomRight, or a vector using the TArray4IntegerType.

Frame sets the Style property in Brush to bsClear. This suppresses filling the interior of the rectangle with the Color for the Brush. In others words, the area in side the frame is transparent. The Brush style is restored to its previous value prior to exit.

Frame calls the Rectangle method to draw the borders on the frame using the Pen for the canvas.

Set property values in Pen prior to calling the method, including:

- Mode
- Style
- Color
- Width
- JoinStyle
- EndCap

TRect instance with the bounds for the rectangle.
Left coordinate for the Top, Left of the rectangle.
Top coordinate for the Top, Left of the rectangle.
Right coordinate for the Bottom, Right of the rectangle.
Bottom coordinate for the Bottom, Right of the rectangle.
Draws a border around the specified rectangle with the Brush for the canvas.

FrameRect is an overloaded method used to draw a frame or border for the specified rectangular area using the Brush for the canvas. Overloaded variants allow the bounds for the rectangle to be defined using:

Four separate Integer values representing the Top/Left and Bottom/Right coordinates for the rectangle.

A TRect instance where the vertices are represented as either four Integers, two TPoint instances for TopLeft and BottomRight, or a vector using the TArray4IntegerType.

FrameRect draws the border for the shape using the style, color, or bitmap defined in Brush. The drawing operation is always performed using a 1 pixel width / height.

FrameRect calls the routine in the LCL interface which implements the method for the widgetset. The return value from the LCL interface is ignored.

Use Frame to draw borders on a rectangle using the Pen for the canvas. Use Frame3D to draw borders using a specified bevel style or colors which simulate 3-dimensional relief.

LCLIntf.FrameRect
TRect instance with the bounds for the rectangle.
Left coordinate for the Top, Left of the rectangle.
Top coordinate for the Top, Left of the rectangle.
Right coordinate for the Bottom, Right of the rectangle.
Bottom coordinate for the Bottom, Right of the rectangle.
Gets text metrics for the canvas font.

Calls RequiredState to check state flags for the canvas, and ensure that the Handle and the Font are valid. RequiredState raises an Exception if the Handle for the canvas is not valid.

Calls GetTextMetrics in the LCL interface to retrieve the ascender, descender, and height metrics for the canvas Handle. The values are assigned to members in the TM output argument.

The return value is True when text metrics were successfully retrieved from the widgetset.

True on success.
Structure with the text metrics.
Fills a rectangle with a color gradient using the specified colors in a given direction.

GradientFill fills the area inside the specified rectangle using a color gradient with the specified start and stop colors.

No actions are performed in the method when ARect has no discernible area; both the calculated height and width for the rectangle are 0 or a negative number.

The direction for the color gradient is specified in the ADirection argument. gdVertical causes the color variations to be drawn from top to bottom in the rectangle starting with the color in AStart and ending with the color in AStop. gdHorizontal causes the color variations to be draw from left to right in the rectangle, also starting with the color in AStart and ending with the color in AStop.

GradientFill decomposes color values in AStart and AStop into their Red, Green, and Blue component values. The differences between the byte values are varied evenly in the color gradient, and drawn as colored lines oriented in the direction opposite to the color gradient. The color setting in Pen is updated, and LineTo is used to draw the number of 1 pixel lines available in the gradient direction.

Please note that the settings in Pen are not stored on entry, or restored prior to exiting from the method. The Pen color will contain the color in AStop on exit.

Use FloodFill to fill a rectangular area bounded by or filled with a specified color value. Use FillRect to fill a rectangular area with the Brush for the canvas.

TRect instance with the bounds for the rectangle.
TColor value used at the start of the color gradient.
TColor value used at the end of the color gradient.
Direction for the color gradient.
RadialPie
draws a filled pie-shaped wedge on the canvas with specified start and end coordinates, and starting and ending angular positions.

Use Pie to draw a filled pie-shaped wedge on the canvas.

The angles StartAngle16Deg and Angle16DegLength are 1/16th of a degree. For example, a full circle equals 5760 (16*360).

Positive values in StartAngle16Deg means counter-clockwise while negative values mean clockwise direction. Zero degrees is at the 3 o'clock position.

Pie
draws a filled Pie-shaped wedge on the canvas.

Pie is a method used to draw a filled Pie-shaped wedge on the canvas. The pie is part of an ellipse between the points EllipseX1, EllipseY1, EllipseX2, EllipseY2. The values StartX, StartY and EndX, EndY represent the starting and ending radial-points between which the Bounding-Arc is drawn.

Polybezier
draws cubic Bézier curves.

Use Polybezier to draw cubic Bézier curves.

The first curve is drawn from the first point to the fourth point with the second and third points being the control points.

If the Continuous flag is True then each subsequent curve requires three more points, using the end-point of the previous Curve as its starting point, the first and second points being used as its control points, and the third point its end-point.

If the Continuous flag is set to False, then each subsequent curve requires 4 additional points, which are used exactly as in the first curve.

If the Filled flag is set to True then a straight line is drawn from the last connected point to the starting point, and the entire curve is filled with the current brush.

Any additional points which do not add up to a full Bézier (4 for Continuous, 3 otherwise) are ignored. There must be at least 4 points to be connected.

Draws a closed, many-sided shape using the Pen for the canvas.

Use Polygon to draw a closed, many-sided shape on the canvas, using the Pen for the canvas. After drawing the complete shape, Polygon fills the shape using the canvas Brush.

The Points parameter is an array of points that give the vertices of the polygon.

Winding determines how the polygon is filled. When Winding is True, Polygon fills the shape using the Winding fill algorithm.

When Winding is False, Polygon uses the even-odd (alternative) fill algorithm.

StartIndex gives the index of the first point in the array to use. All points before this are ignored.

NumPts indicates the number of points to use, starting at StartIndex.

If NumPts is -1 (the default), Polygon uses all points from StartIndex to the end of the array. The first point is always connected to the last point.

To draw a polygon on the canvas without filling the internal area, use the Polyline method specifying the first point a second time at the end of the line.

Draws a line which connects a set of points on the canvas.

Use Polyline to connect a set of points on the Canvas. If you specify only two points, Polyline draws a single line. The Points parameter is an array of points to be connected.

StartIndex identifies the first point in the array to use.

NumPts indicates the number of points to use. If NumPts is -1 (the default), PolyLine uses all the points from StartIndex to the end of the array.

Calling the MoveTo function with the value of the first point, and then repeatedly calling LineTo with all subsequent points will draw the same image on the canvas. However, unlike LineTo, Polyline does not change the values in PenPos.

Array of or pointer to the TPoint instances for the line.
Position of the first point used when drawing the line.
Number of points available in the pointer.
Draws a Rectangle with the specified coordinates.

Rectangle is an overloaded method reintroduced in TCanvas. It is used to draw a rectangular shape on the drawing area for the canvas. The overloaded variants allow the coordinates to be specified as either:

- Four separate Integer values representing the top, left, bottom, and right vertices for the shape (X1, Y1, X2, Y2).
- A TRect instance where the vertices are represented as either four Integers, two TPoint instances for TopLeft and BottomRight, or a vector using the TArray4IntegerType (Rect).

Rectangle draws an outline (or borders) for the shape using the mode, style and width defined in Pen. The rectangle is also filled using the style, color and/or bitmap defined in Brush.

Use FillRect to fill a rectangular area with the current Brush without drawing its borders. Use FrameRect to draw the borders for the shape using the current Brush without filling the interior. Use Frame to draw borders for the shape using the current Pen and a clear Brush for the interior.

Rectangle calls the routine in the LCL interface used to implement the method for the current widgetset.

LCLIntf.Rectangle
Left coordinate for the top, left of the rectangle.
Top coordinate for the top, left of the rectangle.
Right coordinate for the bottom, right of the rectangle.
Bottom coordinate for the bottom, right of the rectangle.
TRect instance with the coordinates for the rectangle vertices.
Draws a rectangle with rounded (or radiused) corners at the specified position.

RoundRect is an overloaded method in TCanvas used to draw a rectangle with rounded (or radiused) corners. The overloaded variants allow the coordinates to be specified as either:

- Four separate Integer values representing the top, left, bottom, and right vertices for the shape (X1, Y1, X2, Y2).
- A TRect instance where the vertices are represented as either four Integers, two TPoint instances for TopLeft and BottomRight, or a vector using the TArray4IntegerType (Rect).

RX and RY contain the width and height (respectively) for an ellipse used to draw arc segments for the rounded corners on the rectangular shape.

RoundRect (like Rectangle) draws an outline (or borders) for the shape using the mode, style and width defined in Pen. The rounded rectangle is also filled using the style, color and/or bitmap defined in Brush.

RoundRect calls the routine in the LCL interface used to implement the method for the current widgetset.

LCLIntf.RoundRect
Left coordinate for the top, left of the rectangle.
Top coordinate for the top, left of the rectangle.
Right coordinate for the bottom, right of the rectangle.
Bottom coordinate for the bottom, right of the rectangle.
Horizontal distance to the ellipse origin used for the rounded corners.
Vertical distance to the ellipse origin used for the rounded corners.
TRect instance with the coordinates for the rectangle vertices.
Writes text at the specified position on the canvas.

Writes the value in Text at the given X, Y coordinates on the canvas.

Calls Changing to signal the OnChanging event handler (when assigned). Calls RequiredState to ensure that handles for the canvas, Font, and Brush are valid.

Properties in TextStyle are converted and combined into the numeric flag used to format the Text, including Opaque and RightToLeft. Uses ExtUTF8Out to write to the device context using the position and style flags needed.

The Pen is positioned at the end of the Text when the output operation is completed. The vertical canvas coordinate is not altered in the method. In other words, TextOut does not handle multi-line text or word wrapping of the value in Text.

TextOut calls Changed to signal the OnChange event handler (when assigned).

ExtUTF8Out
Horizontal canvas coordinate where the text is written.
Vertical canvas coordinate where the text is written.
Values written in the text output operation.
Draws text on the canvas at the specified location using the given style.

Writes Text string within a specified rectangle, according to predefined Style.

The boundaries of the text rectangle are specified in ARect. X, Y define the starting point for writing the Text within the rectangle.

TextStyle determines whether the text is justified, centered, word-wrapped, clipped at the rectangle boundaries, etc. If the Style argument is omitted, defaults are assumed.

Note: The exact text position depends on the specified rectangle, the X, Y coordinates, and settings in TextStyle:

- TextStyle.Alignment = taLeftJustify
  : Text begins at X
- TextStyle.Alignment = taCenter
  : Text center is in the center of the rectangle (horizontally)
- TextStyle.Alignment = taRightJustify
  : Text ends at right edge of the rectangle
- TextStyle.Layout = tlTop
  : Top of the text is at Y
- TextStyle.Layout = tlCenter
  : Text center is in the center of the rectangle (vertically)
- TextStyle.Layout = tlBottom
  : Text sits above the the bottom edge of the rectangle

Rectangle within which the specified text is drawn.
Horizontal text start (respected only if TextStyle.Alignment = taLeftJustify).
Vertical position of the top of the text (respected only if TextStyle.Layout = tlTop).
Text to be drawn.
Optional parameter which determines whether the text is justified, word-wrapped, clipped, etc. If omitted, the current TextStyle for the canvas is used.
Calculates the size for the specified Text using the canvas Font.
TSize instance with the Width and Height for the text.
Text examined and measured in the method.
Gets the height for the specified text using the canvas Font.

Calls TextExtent to get the TSize instance with the return value for the method.

Height for the specified text (in pixels).
Text measured in the method.
Gets the width for the specified text using the canvas Font.

Calls TextExtent to get the TSize instance with the return value for the method.

Width for the specified text (in pixels).
Text measured in the method.
Gets the number of characters that fit in the specified maximum width.

TextFitInfo is an Integer function used to the determine the number characters from Text that will fit within the maximum width specified in MaxWidth. It is useful for situations where text must be truncated or wrapped to fit within a given area.

Text is a String type and allows UTF-8-encoded multi-bytes values in its content.

MaxWidth contains the maximum number of pixels allowed in the measurement.

TextFitInfo calls the GetTextExtentExPoint routine in the LCL interface to measure each of the characters (UTF-8 code points) in Text. Please note that partial character extents are not used when calling the LCL interface routine.

The return value contains a non-zero value on successful completion of the method, or 0 when number of characters cannot be determined.

Use TextWidth to get width in pixels for a given string value.

Number of code points allowed in the specified maximum width.
Text examined in the method.
Maximum width allowed for the character values.
Checks whether the Handle has been allocated for the canvas.

The return value is True when Handle contains a non-zero value. 0 (zero) indicates that a Handle has not been assigned or is invalid.

True when Handle has been assigned.
Checks the required canvas states and gets the updated Handle for the canvas.

Includes the value csHandleValid flag in ReqState and calls RequiredState to check the canvas state flags. The return value contains the updated value for the Handle property.

New value for Handle after checking required canvas states.
Canvas state flags required in the method.
The color of the Pixels located at the specified position.

Pixels is an indexed TColor color property which provides access to the color for pixels on the drawing surface. The X and Y arguments provide the horizontal and vertical offsets on the drawing surface.

Read and write access to color values in the property requires a valid Handle (or device context) for the canvas. RequiredState is called, and allocates a Handle if one does not already exist. An EInvalidGraphicOperation exception may be raised in the method if a valid handle cannot be acquired.

Methods in the widgetset class are called to read or write the pixel color using the Handle.

When setting a new color for a pixel, the Changing method is called to signal the OnChanging event handler (when assigned). After setting the new color, the Changed method is called to signal the OnChange event handler (when assigned).

Horizontal offset on the drawing surface.
Vertical offset on the drawing surface.
Handle (or device context) for the drawing surface.

Handle is a HDC property that provides the device context for the drawing surface. A valid Handle is required for nearly all operations performed on the canvas.

Read access calls RequiredState, and allocates a Handle by calling CreateHandle if one does not already exist. An EInvalidGraphicOperation exception may be raised in the method if a valid handle cannot be acquired.

CreateHandle is an empty implementation in TCanvas, and is overridden in descendent classes to return a handle for an image format or output device. See TBitmapCanvas, TControlCanvas, TPrinterCanvas, et. al.

Setting a new value for Handle causes saved Brush, Pen, and Font handles to be reset to their default values. The AntialiasingMode for the canvas is also re-applied.

Text style attributes used to draw text on the canvas.

TextStyle is a TTextStyle property with the attributes applied to text drawn on the canvas. It is used in methods which output text to the drawing surface, like TextOut and TextRect.

Default values in the property are assigned in the constructor.

See TTextStyle for details about members in the record and their usage.

Controls anti-aliasing for canvas drawing operations.

AntialiasingMode is a TAntialiasingMode property which indicates if smoothing is performed for drawing operations on the canvas. The default value for the property is amDontCare, and indicates that the default actions for the platform or operating system is used.

Setting a new value for the property causes the RealizeAntialiasing method to be called to apply settings in widgetset classes when a Handle has been allocated.

AutoRedraw
- if True, the Canvas is to be redrawn automatically after each change or update.

AutoRedraw is a Boolean property which indicates if the window for the canvas is automatically redrawn when updated. When set to True, the DCRedraw method in the widgetset class is called to enable the feature for the Handle in the canvas.

The default value for the property is False.

The Brush used to paint on the Canvas.

Brush is a TBrush property with the tool used to paint the interior of filled shapes on the drawing surface. It has settings like Color and Style, but may also use a Bitmap to fill the interior of shapes.

Setting a new value for the property causes the handle for the Brush to be freed and re-created in the cached resources for the canvas.The values from the new Brush are assigned to the member variable for the property. The BrushChanged method is called to update the state flags for the canvas.

Use Pen to configure the tool used to draw lines and curves on the drawing surface.

Use Font to set the typeface, color, and style used to draw text on the drawing surface.

Indicates the raster operation used to combine pixel colors on the drawing surface.

CopyMode is a TCopyMode property which contains the ternary raster operation used to combine pixel colors in region transfers. CopyMode contains values from constants defined for the raster operations, and includes:

cmBlackness
  Fills the destination rectangle with the first color in the physical palette. (Black for the default palette).
cmDstInvert
  Inverts colors in the destination rectangle.
cmMergeCopy
  Merges colors from the source rectangle with the brush color.
cmMergePaint
  Merges inverted colors from the source rectangle with the colors in the destination rectangle using an OR operation.
cmNotSrcCopy
  Copies inverted colors from the source rectangle to the destination rectangle.
cmNotSrcErase
  Combines the colors from the source and destination rectangles using an OR operation, and inverts the result.
cmPatCopy
  Copies the brush into the destination rectangle.
cmPatInvert
  Combines the brush colors with the colors in the destination rectangle using an XOR operation.
cmPatPaint
  Combines the brush colors with the inverted colors from the source rectangle using an OR operation, and combines the result with the colors in the destination rectangle using an OR operation.
cmSrcAnd
  Combines colors from the source and destination rectangles using an AND operation.
cmSrcCopy
  Copies the source rectangle to the destination rectangle.
cmSrcErase
  Combines the inverted colors in the destination rectangle with the colors from the source rectangle using an AND operation.
cmSrcInvert
  Combines the colors in the source and destination rectangles using an XOR operation.
cmSrcPaint
  Combines the colors in the source and destination rectangles using an OR operation.
cmWhiteness
  Fills the destination rectangle using the second color in the physical palette. (White for the default palette).

The default value for the property is cmSrcCopy.

Copy mode constants are not provided for the CAPTUREBLT and NOMIRRORBITMAP values used in the Windows GDI API.

Contains the Font used to render text on the drawing surface.

Font is a TFont property which contains the font used to render text on the drawing surface. Values in Font determine the formatting / layout applied in methods that render text, like TextOut and TextRect. Setting a new value in Font calls the Assign method in the class instance to store the new values. Property values in Font can also be modified directly to use the desired values.

The values assigned in Font are used in methods that calculate the size for text like TextExtent, TextHeight, TextWidth, and TextFitInfo.

Height of the canvas.

Height is a read-only Integer property which contains the vertical dimension in Pixels for the canvas drawing area. Height and Width determine the limits for the 2-dimensional coordinate system used to access the Pixels on the drawing surface.

The value for the property is determined by calling the GetDeviceSize routine using the Handle for the class instance. The property value is 0 (zero) when Handle has not been assigned (contains 0).

Use Width to get the horizontal dimension for the drawing surface.

Changing the value for Height or Width in TCanvas is not allowed. These values are controlled using the capabilities in an image format or output device, and are normally handled in classes which implement the canvas.
GetDeviceSize
The Pen to be used for writing in this canvas.

Pen is a TPen property which contains settings used when drawing lines, shapes, gradients, or generally changing pixels on the canvas. The available properties include:

- Color
- Mode
- Style
- Width
- Cosmetic
- EndCap
- JoinStyle

See TPen for more information about properties, methods, and events in the class. See TFPCustomCanvas for information about the pen used in the FCL ancestor class.

The Pen property is used in the implementation of TCanvas drawing methods, like: SetPixel, MoveTo, LineTo, Arc, ArcTo, Chord, GradientFill, RadialPie, PolyBezier, Polygon, Polyline, Ellipse, Frame, Frame3D, Rectangle, and RoundRect.

Use Brush to access settings used to fill enclosed areas on the drawing surface.

The Region where the Canvas is located.

Region is a TRegion property which contains the rectangular area(s) which define the bounding box for the drawing surface. See TRegion for more information.

The Width of the Canvas.

Width is a read-only Integer property which contains the horizontal dimension in Pixels for the canvas drawing area. Height and Width determine the limits for the 2-dimensional coordinate system used to access the Pixels on the drawing surface.

The value for the property is determined by calling the GetDeviceSize routine using the Handle for the class instance. The property value is 0 (zero) when Handle has not been assigned (contains 0).

Use Height to get the vertical dimension for the drawing surface.

Changing the value for Height or Width in TCanvas is not allowed. These values are controlled using the capabilities in an image format or output device, and are normally handled in classes which implement the canvas.
Event handler signalled after a change to the canvas.

OnChange is a TNotifyEvent property which contains an event handler signalled after values in the canvas have been changed. The event handler is signalled (when assigned) from the Changed method, which is called when drawing operations are completed that alter the Pixels on the canvas.

Assign an object procedure to the property which implements the signature in TNotifyEvent to respond to the event notification.

Use OnChanging to respond to the notification that occurs prior to a drawing operation.

Event handler signalled prior to changing the canvas.

OnChanging is a TNotifyEvent property which contains an event handler signalled before changing values in the canvas. The event handler is signalled (when assigned) from the Changing method, which is called before start drawing operations that alter the Pixels on the canvas.

Assign an object procedure to the property which implements the signature in TNotifyEvent to respond to the event notification.

Use OnChange to respond to the notification that occurs when a drawing operation is completed.

Specifies the base class for reference-counted shared images.

TSharedImage is a class which specifies the base class for reference-counted shared images. TSharedImage defines properties and methods which are used to track and maintain the reference count for a shared image.

Use the RefCount property to determine the number of references acquired for a shared image.

Use Reference to increment the value in RefCount. Use Release to decrement the value in RefCount.

TSharedImage includes abstract virtual methods, like HandleAllocated and FreeHandle, which must be implemented in a descendent class to perform actions needed for the handle in a specific image type.

TSharedImage is the ancestor for the TSharedRasterImage class.

Increases the reference count.
Decreases the reference count.
Release the handle for this image and free its resources.
The number of references to this shared image.
Indicates whether a handle been allocated for the image.
True when Handle is a non-zero value.
Represents handle types used for Bitmaps.

TBitmapHandleType is an enumerated type with values that represent handle types available for Bitmaps. On Windows platforms, the handle may represent two distinctly different storage mechanisms:

- DIB (Device-Independent Bitmap)
- DDB (Device-Dependent Bitmap)

The handle type indicates the storage format and content for the Bitmap.

TBitmapHandleType is the type used to implement the HandleType property in TCustomBitmap and TSharedCustomBitmap.

Device-Independent Bitmap handle.
Device-Dependent Bitmap handle.
Implements a reference counted raster image that may be shared between controls.
Frees the handle for the shared image.

Implements the abstract virtual method defined in the TSharedImage ancestor.

FreeHandle calls the DeleteObject routine to remove the handle from the widgetset class. FreeHandle sets the value for the internal handle to 0 (zero) to indicate that it is not assigned or no longer valid.

No actions are performed in the method when the handle is already set to 0.

ReleaseHandle
- returns the identity of the handle that has just been released.

ReleaseHandle is a THandle function used to release a reference for the handle in the class instance. The return value contains the value for the handle on entry.

ReleaseHandle sets the handle value to 0 to indicate that it is no longer used or invalid. It does not call DeleteObject to remove the handle in widgetset classes.

ReleaseHandle is called from classes which support a specific image format, like TCustomBitmap and TIcon, when their ReleaseHandle method is called to free the handle for its shared image.

Indicates if image content has been assigned for the shared image.

IsEmpy is a Boolean function which indicates if image content has been assigned for the shared image. The return value is True when both the Handle and the SaveStream for the shared image are unassigned. Specifically, Handle contains 0 and SaveStream is Nil.

Constructor for the class instance.

Create is the constructor for the class instance, and calls the inherited constructor on entry.

TObject.Create
Not implemented in the current LCL version.
Destructor for the class instance.

Frees resource allocated to SaveStream and Handle. Calls the inherited destructor prior to exiting from the method.

Determines whether the Handle for the class has been allocated.

The return value is True when the Handle contains a non-zero value.

Implements the abstract virtual method defined in TSharedImage.

True when the handle for the shared image has been allocated.
Canvas used to render the bitmap for the raster image.

BitmapCanvas is a TCanvas property which represents the drawing surface used to render the shared raster image.

TSharedRasterImage does not supply a value for the property. The property value is supplied by an image class, like TRasterImage, which uses the shared image paradigm. It normally contains an instance of TBitmapCanvas (or a descendant).

SaveStream
- the memory stream to be used for saving this image.

SaveStream is a TMemoryStream property which contains the stream with the content for the shared image. TSharedRasterImage does not manipulate values in SaveStream; it is maintained by the image class that uses the shared image paradigm (like TRasterImage and descendants).

TSharedRasterImageClass
- class of TSharedRasterImage.

Class reference used to create new instances of TSharedRasterImage.

TRasterImage
- base class for a number of graphic controls, including TCustomBitmap and TCustomIcon, which use a raster of dots to display graphic information.

TRasterImage is a TGraphic descendant which implements the base class for images displayed as rasterized pixels on a canvas. It is used as the ancestor class for TCustomBitmap ( TBitmap) and TCustomIcon ( TIcon).

TRasterImage introduces the shared properties and methods common to the image formats. It is also provides a shared, reference-counted image that reduces resource requirements in graphical applications. Support is provided for bitmaps which use DIB (Device-Independent Bitmap) or DDB (Device-Dependent Bitmap) handles as well as common pixel storage formats used in the RawImage data. Handles are provided for the Bitmap, Mask, and Palette resources used in an image. TRasterImage also includes a Canvas used to render the pixels for the image.

Many of the methods in TRasterImage are defined as abstract virtual methods, and must be implemented in a descendent class to provide support for a specific image format.

Performs actions needed before the canvas is modified.

CanvasChanging is used to perform actions needed before the canvas is modified. Ensures that the Handle for the raster image is not shared to prevent changes in copies.

Object for the notification message.
Creates a Canvas for the raster image, and assigns its event handlers.

CreateCanvas is a method used to created and configure the Canvas for the raster image. No actions are performed in the method when Canvas has already been assigned for the class instance.

A TBitmapCanvas instance is created and assigned to the member for the Canvas property. The CanvasChanging and Changed methods are assigned as the event handlers for the OnChanging and OnChange properties (respectively) in the canvas.

CreateCanvas is called when the value for the Canvas property is read and the member has not already been initialized.

Ensures that a mask bitmap is allocated, configured, and applied when needed.

No actions (other than clearing the MaskHandle) are performed in the method when the raster image is empty, has no Color, uses fixed transparency, or has no transparency color. CreateMask forces creation of temporary handles for the image and the mask when needed. They are used to load the mask bitmap for the image in BitmapHandle.

AColor contains the color that is used for transparent pixels in the mask for the image. When AColor contains clDefault and TransparentMode is not tmFixed, the color for the bottom left pixel in the mask bitmap is used as the transparency color.

CreateMask is used in the implementation of the Mask method.

Color used for transparent pixels in the image mask.
Frees the Device Context (DC) for the Canvas (when assigned).

FreeCanvasContext is a procedure used to free the device context (DC) for the Canvas in the raster image. No actions are performed in the method when Canvas has not been assigned (contains Nil).

FreeCanvasContext casts the Canvas to a TBitmapCanvas class instance and calls its FreeDC method.

FreeCanvasContext is called when values in the BitmapHandle, MaskHandle, or Palette properties are updated.

Gets the value for the Canvas property.
Value for the property.
Gets the value for the RawImage property.

Calls CreateCanvas if a value has not been assigned for the property.

Value for the property.
Gets the value for the indexed ScanLine property.
Value for the property.
Ordinal position for the row of pixels in the raster image.
Gets the value for the TransparentColor property.
Value for the property.
Sets the value for the TransparentColor property.
Value for the property.
Shared image with existing handles, canvases, etc.
CanShareImage
- returns True if specified class of image can be shared.

CanShareImage is a Boolean function which indicate if the raster image uses a shareable image class. The return value is True when AClass matches the value returned from the GetSharedImageClass method, and is not TSharedCustomBitmap. Only images of the same class type can be shared.

True is the image class is shareable.
Class type requested in the method.
Changed
- method to call when properties have changed.

Changed is an overridden method in TRasterImage used to perform actions needed when property values in the class instance have been updated. No actions are performed when BeginUpdate has been called and a corresponding EndUpdate has not occurred.

Changed ensures that the SaveStream used in the shared image is freed.

Changed calls the inherited method in TGraphic to set the value for the Modified property and signal the OnChange event handler (when assigned).

Object for the change notification.
Gets the default value for the Bitmap handle used in the class instance.

Always returns 0 (for an unassigned handle) in TRasterImage.

Not used in the current implementation.
Renders the image to the specified canvas.

Draw is an overridden method used to render the raster image to the specified canvas using the given rectangle. Draw implements the abstract method defined in the ancestor class.

DestCanvas contains the canvas instance where the raster image is rendered.

DestRect contains the canvas coordinates in DestCanvas where the image is drawn.

No actions are performed in the method if the Width or the Height for the image is 0 (zero).

Draw ensures that valid handles are available in BitMapHandle and MaskHandlle (when Masked is True). No actions are performed in the method when a valid BitmapHandle does not exist.

Draw uses the Device Contexts for Canvas and DestCanvas, and calls the StretchMaskBlt routine in the LCL interface to render the image using methods in the widgetset. The Changing method in DestCanvas is called before drawing the image. The Changed method in DestCanvas is called after the image is drawn.

Canvas where the image is rendered.
Canvas coordinates where the image is drawn.
Gets the value for the Empty property.

Implements the abstract virtual method defined in the ancestor. The property value contains the result from the IsEmpty method in the shared raster image for the class instance.

Value for the property.
Gets the value for the Handle property.

Calls HandleNeeded to ensure that valid handles exist for the image. Requires a valid handle in the shared raster image for the class instance.

Value for the property.
Gets the value for the BitmapHandle property.

GetBitmapHandle is an abstract virtual method, and must be implemented in a descendent class to return the handle for a specific image type or implementation.

Value for the property.
Gets the value for the Masked property.
Value for the property.
Gets the value for the MaskHandle property.

GetMaskHandle is an abstract virtual method, and must be implemented in a descendent class to return the mask handle for a specific image type or implementation.

Value for the property.
Gets the value for the MimeType property.
Value for the property.
GetPixelFormat
- returns the pixel format for the Image.
Value for the property.
Gets a pointer with the raw image data.

Declared as an abstract virtual method. Must be implemented in a descendent class to provide support for a specific image format.

Gets a pointer to the metadata for the raw image data.

Declared as an abstract virtual method. Must be implemented in a descendent class to provide support for a specific image format.

Gets the value for the Transparent property.
Value for the property.
Gets the class reference used to create new shared image instances in the class.

GetSharedImageClass is a class function used to get the class reference needed to create a shared image in the class instance. The return value the TSharedRasterImage class type.

GetSharedImageClass is called from the implementation of the Assign method when a reference to an existing image is stored in the class instance. It is also used in CanShareImage to determine is the request image type is the one used in the current class instance.

Class reference used to create the shared image in the class.
Gets the value for the Height property.
Value for the property.
Gets the value for the Width property.
Value for the property.
Ensures that handles for the image and mask are valid for the raw image data.

BitmapHandleNeeded is a procedure used to ensures that handles for both the image and its mask are valid for the RawImage data. No actions are performed in the method when BitmapHandleAllocated returns True, or when RawImage data does not exist.

The MaskHandle is not created when:

- A mask handle already exists.
- The mask is created using the transparent color for the image.
- Mask values do not exist in the raw image data.

BitmapHandleNeeded calls CreateCompatibleBitmaps to get the handles for the bitmap and mask using a pointer to the raw image data, and creates a default handle if CreateCompatibleBitmaps is unsuccessful. UpdateHandles is called to assign the new handles to BitmapHandle and MaskHandle (when used).

BitmapHandleNeeded is called from the Draw method prior to performing operations using the Canvas for the class instance. It is also used when the Canvas creates a new DC (Device Context).

Ensures that a handle for the image is allocated in widgetset classes.
Declared as an abstract virtual method. Must be implemented in a descendent class.
Ensures that a handle is allocated for the image mask (when needed).
Declared as an abstract virtual method. Must be implemented in a descendent class.
Ensures that a handle for the palette is allocated.
Declared as an abstract virtual method. Must be implemented in a descendent class.
InternalReleaseBitmapHandle
- releases Bitmap Handle and returns its value.
Declared as an abstract virtual method. Must be implemented in a descendent class.
InternalReleaseMaskHandle
- releases Mask Handle and returns its value.
Declared as an abstract virtual method. Must be implemented in a descendent class.
InternalReleasePalette
- releases Palette Handle and returns its value.
Declared as an abstract virtual method. Must be implemented in a descendent class.
Sets the value for the BitmapHandle property.
New value for the property.
Sets the value for the Masked property.
New value for the property.
Sets the value for the MaskHandle property.
New value for the property.
Sets the value for the Transparent property.
New value for the property.
Unshares a shared image when its handle is changed or the save stream is freed.
UnshareImage
- stops an image from being shared: if CopyContent is True, the Image gets copied. Declared as an abstract virtual method. Must be implemented in a descendent class.
Updates image handles when the raw image data is loaded.
UpdateHandles
is called when handles are created for the raw image in the class instance. Returns True when the Handle for the bitmap image is changed in the method. Declared as an abstract virtual method. Must be implemented in a descendent class.
True when the handle has changed for the image.
Handle for the Bitmap.
Handle for the Mask.
Ensures that the save stream for the shared image is allocated.

SaveStreamNeeded is a procedure used to ensure that the internal save stream for the shared image is allocated.

Raises an EInvalidGraphicOperation exception if BeginUpdate (without a matching EndUpdate) is active in the class instance.

No actions a performed in the method when a TMemoryStream has already been assigned as the save stream for the internal TSharedRasterImage instance.

SaveStreamNeeded is called from methods like SaveToStream and WriteData, and occurs before operations which read or write to the save stream.

Frees the save stream assigned to the internal shared image.

FreeSaveStream is a procedure used to free the TStream instance assigned as the SaveStream in the shared image. No actions are performed in the method when the SaveStream has not been assigned in the shared image.

FreeSaveStream calls UnshareImage to discard and recreate the shared image class instance in the class. The TStream instance in the shared image is freed prior to exiting from the method.

FreeSaveStream is used in the implementation of methods like: Assign, Clear, EndUpdate, and Changed.

Reads image data during component streaming.

ReadData is a procedure used to read binary data for the graphic from the specified stream. It is used by the TFiler instance which loads data during component streaming. It is overridden in TRasterImage to provide support for TRasterImageClass and descendants when loading raw image data.

Versions of Lazarus prior to 0.9.26 did not maintain a relationship between graphics formats and image class types. ReadData checks the LongInt value at the beginning of the stream to determine the version number for the streaming format. When a newer version is used, the signature for the image format is read from the Stream. If the image class used is not derived from the TRasterImageClass type, additional conversion is needed to load the raw image data and assign the values to the class instance.

ReadData calls LoadFromStream to complete the operation.

Stream with the raw image data read in the method.
ReadStream
- loads image data into the raw image.

Declared as an abstract virtual method. Must be implemented in a descendent class. This method should not call Changed().

Stream with the image data.
Number of bytes read from the stream.
SetSize
- specifies height and width of Image.

SetSize is used to set the Height and Width for the image to the specified values.

SetSize is an abstract virtual method in TRasterImage, and must be implemented in a descendent class to perform actions needed to resize the raw image data for a specific image format.

New width for the image.
New height for the image.
Sets the Handle used for the image.

SetHandle stores the specified THandle value as the handle used for the image. The handle is actually the one used by the internal TSharedRasterImage instance for the class. No actions are performed in the method when the value in AHandle is the same as the handle in the shared image instance.

SetHandle frees the device context for the bitmap Canvas, unshares the shared image, and discards its image data. The handle in AValue is assigned to the internal shared image. When no other active update processes are pending, the Changed method is called.

New value for the Handle.
Sets the value for the Height property.

Calls SetSize using the existing value for the Width property and the value for the AHeight parameter.

New value for the property.
Sets the value for the Width property.

Calls SetSize using the existing value for the Height property and the value for the AWidth parameter.

New value for the property.
Sets the value for the TransparentMode property.

No actions are performed in the method when AValue is the same as the existing value for the property.

When AValue contains tmAuto, the clDefault constant is used as the value for the property. Otherwise, the RequestTransparentColor method is called to get the color stored in the bottom-left pixel in the raw image data.

New value for the property.
Sets the value for the PixelFormat property.

Defined as an abstract virtual method. Must be implemented in a descendent class to use the storage format supported for a specific image format.

New value for the property.
Writes raw image data to the specified stream.

WriteData is a method used to write raw image data to the stream specified in Stream. WriteData is used by the TFiler instance during LCL component streaming.

WriteData ensures that an internal save stream is available for the shared image in the class instance. An FPImageException is raised when a valid stream could not be created for the image data.

WriteData is an overridden method with support for writing a header with the size for the raw image data. WriteData re-implements the method, and does not call the inherited method - but does call SaveToStream to complete the operation (just like the ancestor).

Raises an FPImageException with the message in rsErrorWhileSavingBitmap when a stream could not be created for the shared image data.
TFiler
Stream instance where image data is written in the method.
Writes the image content to the specified stream instance.

WriteStream is an abstract virtual method, and must be implemented in a descendant class to write data for a specific image format.

Stream where image data is written in the method.
Gets the color used to represent transparent pixels in the image.

RequestTransparentColor is a TColor function used to get the color for transparent pixels in the image. It is called when the value tmFixed is assigned to the TransparentMode property.

RequestTransparentColor examines pixels in the raw image data to get the return value for the method. It gets the color for the pixel located at the bottom-left corner of the image (x = 0, y - Height-1).

When Empty returns True (raw image data is not available), the return value is clNone.

Constructor for the class instance.

Create is the overridden constructor for the class instance, and calls the inherited constructor on entry. Create ensures that the internal shared image instance is created and referenced for the implementation.

Create sets the default value for the TransparentColor property to clDefault. This is done for Delphi compatibility where clDefault indicates that the bottom left pixel in the image is used as the transparent color.

Destroy
is the destructor for TRasterImage: frees the canvas, and releases image then calls inherited Destroy.
TPersistent.Destroy
Assign
- copies details from Source according to data type.

Assign is a procedure used to copy values from the specified TPersistent object into the current class instance. Assign is overridden to handle using a TRasterImage or TFPCustomImage instance in the Source parameter.

No actions are performed in the method when Source is the same class instance as the current class instance (Self).

When Source is a TRasterImage instance, the following actions are performed:

- Clears an allocated mask handle by calling UpdateHandles.
- Sets TransparentMode, TransparentColor, and Masked to the values in Source.
- Frees an existing Canvas context when shared images are not the same.
- Makes a copy of the shared image in Source when they are of the same image class.
- Creates a new shared image and copies its raw image data when they are NOT of the same image class.
- Copies an allocated mask handle from Source.
- Calls Changed to update Modified and signal the OnChange event handler (when assigned).

When Source is a TFPCustomImage instance, the following actions are performed:

- Copies the raw image data from Source using its bitmap and mask handles.
- Calls UpdateHandles to reflect the new handles in the current class instance.
- Calls Changed to update Modified and signal the OnChange event handler (when assigned).

For other TPersistent descendants, the inherited method is called using Source as an argument.

Persistent object with values copied in the method.
Removes raw image data and frees the internal save stream.

Clear is an overridden method used to remove raw image data and free the internal save stream in the class instance. No actions are performed in the method when Empty returns True.

Clears set the values in Height and Width to 0 (zero) to reflect the new size for the image. Clear calls the Changed method when a BeginUpdate process is not active.

BeginUpdate
- start the update process.

BeginUpdate is a method used to initiate an update to the image.

BeginUpdate uses the value in an internal member to track the number of active updates for the image. When the counter has a non-zero value, BeginUpdate has already been called and EndUpdate has not yet been executed. If the value in the counter is 0, the shared image is released and the value in ACanvasOnly is stored in the class instance.

BeginUpdate can raise an EInvalidGraphicOperation exception if a pending update was for a canvas only and a subsequent update requests a full update. The default value for ACanvasOnly is False (full update).

BeginUpdate increments the value in the internal counter prior to exiting from the method.

Raises an EInvalidGraphicOperation exception with the message in rsRasterImageUpdateAll if a pending update was for a canvas only and a subsequent update requests a full update.
True when only the Canvas is updating; False when image data is loading.
EndUpdate
- finishes the update process.

EndUpdate finishes an update process.

EndUpdate maintains the value in the internal counter used to track active update processes started by calling BeginUpdate. It decrements the counter when it has a non-zero value, and exits immediately.

An EInvalidGraphicOperation exception is raised if the counter is already at 0 (zero) when EndUpdate is called.

When a full update was requested (loading image data), the device context for the Canvas and an allocated BitmapHandle are freed.

AStreamIsValid indicates if the save stream for the shared image is valid. When set to False, the save stream is freed. Any operation that modifies the save stream for the shared image should be performed within bracketed BeginUpdate / EndUpdate calls.

EndUpdate calls Changed to set the value in Modified and to signal the OnChange event handler (when assigned).

Raises an EInvalidGraphicOperation exception with the message in rsRasterImageEndUpdate if the counter is already at 0 (zero) when EndUpdate is called.
Indicates if the save stream for a shared image is valid.
Frees the image by resetting its handle.

Calls SetHandle to set the bitmap handle to 0 (zero). Generally, FreeImage is overridden and used in the destructor for descendent classes.

BitmapHandleAllocated
- returns True if a handle has been allocated for the Bitmap.

Declared as an abstract virtual method. Must be implemented in a descendent class to provide support for a specific image format.

True when a handle has been allocated for bitmap data in the image.
MaskHandleAllocated
- returns True if a handle has been allocated for the Mask.

Declared as an abstract virtual method. Must be implemented in a descendent class to provide support for a specific image format.

True when a handle has been allocated for mask data in the image.
PaletteAllocated
- returns True if a Palette has been allocated.

Declared as an abstract virtual method. Must be implemented in a descendent class to provide support for a specific image format.

True when a handle has been allocated for the palette in the image.
Loads the image data from the specified Bitmap and Mask handles.
Bitmap handle for the image.
Mask handle for the image.
Pointer to the source rectangle for the image data.
Loads image data from the specified device context.
Device context used for the operation.
LoadFromStream
- loads data for the image from a specified data stream, optionally supplying its size.

LoadFromStream is an overloaded method in TRasterImage used to load image data from the TStream instance specified in AStream.

One of the overloaded variants provides an ASize argument which contains the number of bytes to read from the stream. When the ASize argument is omitted, the remaining content in the stream is read starting at the current position in the stream.

LoadFromStream calls BeginUpdate to increment the internal update counter in the class instance. EndUpdate is called when the stream has been processed in the method.

LoadFromStream discards an existing shared image and its save stream, and clears existing handles and raw image data in the class instance. No additional actions are performed in the method when ASize is 0 (zero).

LoadFromStream re-creates the save stream for the shared image and copies the content in AStream to the save stream. The ReadStream method is called to load the image data for the class instance.

Stream with the image data loaded in the method.
Number of byte to read from the stream.
Loads image data from a stream for the specified MIME type.

LoadFromMimeStream is an overridden method in TRasterImage.

LoadFromMimeStream examines the ClassType for the image to determine if it is handled in the overridden method. TBitmap, TPixmap, and TCustomIcon descendants are handled in the method.

LoadFromMimeStream compares the value in AMimeType to the PredefinedClipboardMimeTypes values defined in LCL. If AMimeType matches one of the values defined for TPixmap or TBitmap, then the LoadFromStream method is called to load image data from AStream.

Other ClassType or MIME type values cause the inherited LoadFromMimeStream method to be called.

LoadFromMimeStream is used in the implementation of the AssignGraphic method in TClipboard.

TClipboard
Stream with the image data loaded in the method.
MIME type for the image data in the stream.
Loads image data from the specified TRawImage instance.

LoadFromRawImage is a procedure used to load raw image data in AImage into the class instance.

LoadFromRawImage calls BeginUpdate to increment the update process count, and calls EndUpdate when the image data has been loaded in the method.

LoadFromRawImage calls Clear to free the internal save stream for the class instance, and calls SetSize to reflect an empty image. No additional actions are performed in the method If AImage contains an empty image.

The Image Descriptor in AImage is assigned to the internal TRawImage instance to capture the image metadata.

ADataOwner indicates if the internal TRawImage instance is the owner for the image data in AImage. When set to True, values in AImage data are assigned directly to the pointer to the internal raw image data. Values include the size and content for the image data, the image mask, and the palette. When set to False, storage for values is allocated using GetMem and copied from AImage using the Move routine.

TRawImage
Raw image instance loaded in the method.
True if the image owns the raw image data.
Loads the image from a TLazIntfImage instance.
Calls the CreateBitmaps method to create the image and mask handles used to access the image data. Calls SetHandles to apply the image and mask handles to the class instance.
TLazIntfImage instance with image data loaded in the method.
Saves image data to the specified stream.

SaveToStream is an overridden method used to write image data to the stream specified in AStream.

SaveToStream calls SaveStreamNeeded to ensure that an internal save stream exists in the class instance. An EInvalidGraphicOperation exception is raised in SaveStreamNeeded when the active update count for the count is not 0 (zero). An FPImageException is raised when a TMemoryStream instance could not be created and initialized in SaveStreamNeeded.

SaveToStream resets the internal save to stream to its origin, and resizes AStream to include sufficient storage for the values in the internal save stream. The CopyFrom method in AStream is called to store the content for the internal shared image. An FPImageException is raised when the number of bytes written in the CopyFrom method does not match the size for the internal save stream.

Raises an FPImageException exception when the number of bytes written to the stream does not match the size for the raw image data.

An Exception may be raised in SaveToStream (called in the method).

Stream where the image data is stored.
Gets a list of supported MIME types for image data used in the image type.

GetSupportedSourceMimeTypes is an overridden method in TRasterImage used to get the list of MIME types used for image data in the image type. List is the TStrings instance where the list of supported MIME types is stored.

GetSupportedSourceMimeTypes uses the value in ClassType to determine if the request is handled in the overridden method. It is handled in the method when ClassType is TBitmap, TPixmap, or TCustomIcon. Values in the PredefinedClipboardMimeTypes constant for the TBitmap and TPixmap types are added to List. When ClassType contains any other type, the inherited method is called.

GetSupportedSourceMimeTypes is called from the AssignPicture method in TClipboard.

TClipboard
Gets the image Width and Height from the metadata for the raw image.

Calls GetRawImageDescriptionPtr to get a pointer to the image descriptor in the raw image data. When the image descriptor is Nil, or its Format contains ricfNone, the values in AWidth and AHeight are both set to 0 (zero). Otherwise, the Width and Height values in the image descriptor are used as the output parameter values.

Width for the raw image data.
Height for the raw image data.
Applies the color used for transparent pixels to the image.

Calls CreateMask to create and appy the mask handle required for the fixed color transparency.

Color used to represent transparent pixels in the mask.
Sets handles for the bitmap and the mask to the specified values.

SetHandles is a procedure used to set the handles for the bitmap and the mask to the values specified in ABitmap and AMask. SetHandles is an abstract virtual method in TRasterImage, and must be implemented in a descendent class to store handle values in the shared image used in the image format.

Handle to use for the Bitmap.
Handle to use for the Mask.
Releases the handle in the shared image without freeing the BitmapHandle.

ReleaseBitmapHandle is a HBITMAP function used to release the hndle for the shared image without freeing it. The return value contains the handle value in the shared image when its ReleaseHandle method is called.

Calls BitmapHandleNeeded to ensure that the BitmapHandle and optional MaskHandle are valid for the image type. Calls FreeCanvasContext to free the cavas context when the handle been has changed.

Value for the handle in the shared image before it is released.
ReleaseMaskHandle
- releases the Handle used for the Mask.
ReleasePalette
- release the Handle used for the Palette.
CreateIntfImage
- creates an image on the Interface.
The Canvas where the raster image is rendered.

Canvas is a read-only TCanvas property which contains the drawing surface where the data for the image is rendered.

Reading the value for the property causes the CreateCanvas method to be called when the member has not been initialized. In TRasterImage, the Canvas member is an instance of TBitmapCanvas. It is configured to use the CanvasChanging and Changed methods for the OnChanging and OnChange event handlers in the canvas.

The device context (or handle) for the Canvas is modified when the BitmapHandle or MaskHandle are assigned or released for the class instance.

Canvas is used in the Draw method to get the rendered content transferred to a destination canvas. Canvas is also used to auto-detect the TransparentColor using the Pixels in the image.

Indicates if a handle has been assigned for the shared image in the class.

HandleAllocated is a Boolean function which indicates if a valid handle has been assigned for the internal TSharedRasterImage instance in the class. The return value is True when the handle in the shared image contains a non-zero value.

Use BitmapHandleAllocated to determine if a HBITMAP handle has been assigned for the Bitmap in the class instance.

Use MaskHandleAllocated to determine if a HBITMAP handle has been assigned for the Mask in the class instance.

True when a handle has been assigned for the shared image.
BitmapHandle
- the Handle that has been allocated for the Bitmap.
Masked
- returns True if a Mask is being applied.
The handle allocated for the Bitmap Mask.
Storage format for the Pixels in the Image.

PixelFormat is a TPixelFormat property which contains the storage format for colors in Pixels. The default value is pfDevice and indicates that the source device determines the pixel format. The value is PixelFormat indicates the number of bits required to store the color, and the maximum number of colors allowed for a given pixel.

See TPixelFormat for the values in the enumeration and their meanings.

PixelFormat is essentially a read-only property in TRasterImage. The read and write access specifiers are declared as abstract virtual methods, and are overridden in descendent classes to access raw image data for a specific image format.

Provides access to the raw image data for the image type.

RawImage is a read-only TRawImage property which provides access to the raw image data for the image type. It provides access to the raw image descriptor and pointers to the bytes values used in the Bitmap, Mask, and Palette for the image. The value for the property is captured using the pointer returned by the GetRawImagePtr method.

Always use BeginUpdate and EndUpate to surround any action which modifies member values in RawImage.

TRawImage
Provides indexed access to a scan line in the raw image data.

ScanLine is a read-only indexed Pointer property which provides access to a scan line in the raster image. The scan line consists of a single row of pixels in the the raw image data.

Row contains the row number read from the TRawImage instance provided by the GetRawImage method. Row number values start at 0 (zero).

The return value is a Pointer to the byte values for the requested row in the raw image data.

Reading a value in ScanLines should always be performed inside a BeginUpdate ... EndUpdate sequence.

ScanLine is a platform-specific property, and may not be implemented for all platforms or widgetsets.

Which platforms support it? Win, Qt, macOS Carbon...

Row number for the pixels accessed in the raw image data.
Color used for transparent pixels in the image.

TransparentColor is a TColor property which indicates the color used for transparent pixels in the raw image data. The default value for the property is clDefault.

TransparentColor is used along with TransparentMode to determine whether a fixed color is used for transparency, or if the tranparent color is read from a specified pixel in the raw image data.

When TransparentColor contains clDefault, the RequestTransparentColor method is used to get the transparency color value from the bottom-left pixel in the raw image data.

When setting a new value for the property, the TransparentMode property is updated as well. When clDefault is assigned to the property, TransparentMode is set to tmAuto. For other color values, TransparentMode is set to tmFixed.

MaskHandleAllocated is called to determine if a HBITMAP handle has been allocated for the MaskHandle property. When True, the MaskHandle is reset to 0 to indicate the handle is no longer in use or is invalid.

The Changed method is called to update the internal save stream for the image (when needed), set Modified to True, and signal the OnChange event handler (when assigned).

Determines how transparent pixels are represented in the image.

TransparentMode is a TTransparentMode property which indicates how transparent pixels in the image are represented in the raw image data. It is related to the TransparentColor and Masked properties. TransparentMode can contain one of the following values from the TTransparentMode enumeration:

tmAuto
  Transparent pixels are represented using the color stored at the bottom-left pixel in the raw image data. TransparentColor is set to clDefault.
tmFixed
  Transparent pixels are represented using the color stored in the TransparentColor property. Masked is set to True.

The default value for the property is tmAuto.

Implements the base class for a reference-counted shared image.

TSharedCustomBitmap is a TSharedRasterImage descendant which implements the base class for reference-counted shared images, like: TSharedBitmap, TSharedPixmap, TSharedJPEGImage, TSharedPortableNetworkGraphic and TSharedPortableAnyMapGraphic.

Gets the value for the Height property.
Value for the property.
Gets the value for the Width property.
Value for the property.
Frees the Handle and the Palette for the shared Bitmap.
FreeHandle
frees Palette then calls inherited FreeHandle.
Frees the handle in the Palette property.

FreePalette is a procedure used to free the handle assigned for the Palette. FreePalette calls DeleteObject to release the Palette handle. The Palette handle is set to 0 (zero) to indicate that the handle is no longer in use or is invalid.

No actions are performed in the method when the Palette handle contains 0 on entry.

Frees raw image data for the shared bitmap and resets its image descriptor.

Calls the FreeData method in the internal TRawImage member to free the raw image data. Sets the Format in its Description property to ricfNone.

FreeImage is called from the destructor when the class instance is destroyed.

TRawImage
Returns the Handle of the released Palette.

ReleasePalette is a HPALETTE function used to release the internal pallette handle for the shared bitmap. The return value contains the existing palette handle on entry.

Sets the value in the internal palette handle to 0 to indicate that the palette handle is no longer in use or is invalid.

Use FreePalette to remove the palette handle in widgetset classes.

Gets the value for the PixelFormat property.
Value for the property.
Determines if the shared bitmap is empty.

IsEmpty is an overridden method in TSharedCustomBitmap used to determine if the shared bitmap is empty. IsEmpty calls the inherited method on entry, and adds additional logic needed for the Bitmap image format.

The return value is True when all of the following conditions are met:

- The Handle is unassigned (contains 0).
- The internal save stream for the image is not assigned.
- The color format used for raw image data is ricfNone.
- The raw image data is Nil.
- The raw image data size is 0.

True if the shared bitmap is empty.
Create
- constructor for TSharedCustomBitmap: calls inherited Create and initializes the image.

Create is the overridden constructor for the class instance, and calls the inherited constructor on entry. Create calls the Init method in the internal TRawImage instance uses in the class. This ensures that resources are allocated and initialized, and properties are set to their default values in both the raw image and its image descriptor.

TRawImage.Init TObject.Create
Destructor for the class instance.

Destroy is theoverridden destructor for TSharedCustomBitmap.

Destroy frees the internal save stream for the class instance. It also calls FreeHandle and FreeImage to free the handle and the raw image data for the shared bitmap. Calls the inherited destructor prior to exiting from the method.

Determines if the handle for the shared bitmap has been allocated.

HandleAllocated is an overridden method used to determine if the handle for the shared bitmap has been allocated. HandleAllocated implements the abstract virtual method defined in TSharedImage.

The return value is True when the internal handle has a non-zero value.

True when the handle has a non-zero value.
ImageAllocated
- returns True if an image has been allocated.

ImageAllocated is a Boolean function which indicates if the internal raw image data has been allocated for the shared bitmap. The return value is True when the TRawImage instance in the class has a value other than ricfNone in its image descriptor.

TRawImage.Description TRawImageDescription.Format TRawImageColorFormat
True when the color format for the raw image data has been assigned.
HandleType
the type of Bitmap Handle that has been allocated.

HandleType is a TBitmapHandleType property which indicates the Bitmap handle type and the storage mechanism used for the Bitmap header and data.

Use of HandleType is not implemented in the current LCL version.
The Height of the Bitmap.

Height is a read-only Integer property which contains the height for the shared bitmap image as indicated in the descriptor for the raw image data. The property value is always 0 (zero) when the descriptor for the internal raw image data contains ricfNone.

TRawImage.Description TRawImageDescription.Format TRawImageColorFormat
Storage format for pixels in the raw image data.

PixelFormat is a read-only TPixelFormat property with the storage format used for pixel data in the raw image. It also determines the number of colors (or color depth) allowed in the raw image data.

See TPixelFormat for more information about the values and meanings in the enumeration.

TRawImageDescription.Depth
The Width of the Bitmap.

Width is a read-only Integer property which contains the width for the shared bitmap image as indicated in the descriptor for the raw image data. The property value is always 0 (zero) when the descriptor for the internal raw image data contains ricfNone.

TRawImage.Description TRawImageDescription.Format TRawImageColorFormat
TCustomBitmap
- the base class for TBitmap.

TCustomBitmap is a TRasterImage descendant which implements the base class for TBitmap. It contains image data using the .bmp (Windows bitmap) or .xpm (XPixMap) formats. Image data can be loaded from a file, stream, or resource. The loading routine automatically recognizes the format, and can be used to load images from a Delphi form streams (.dfm files).

When the handle is created, it is up to the widgetset interface (gtk, qt, win32, etc.) to automatically convert it to the best internal format for the platform. That is the reason the Handle is interface dependent. To access the raw image data, see TLazIntfImage in IntfGraphics.pas.

Do not create instances of TCustomBitmap; use the TBitmap descendant.

Gets the value for the HandleType property.
Value for the property.
Gets the value for the Monochrome property.
Value for the property.
Sets the value for the Handle property.
New value for the property.
Sets the value for the HandleType property.
New value for the property.
Sets the value for the Monochrome property.
New value for the property.
Updates the value in PixelFormat from the shared Bitmap image.

Called when the value for PixelFormat is retrieved and the image descriptor has not already been read for the shared image.

Ensures that a handle is allocated for the image mask (when needed).

Implements the abstract virtual method defined in the ancestor class.

Ensures that a handle is allocated for the Palette in the image.

PaletteNeeded has an empty implementation in TCustomBitmap.

Indicates if the image uses the specified shared image class.

CanShareImage is an overridden method which indicates if the image uses the specified shared image class. The image can be shared only when it uses the same shared image class type.

Shared image class type compared in the method.
Performs actions needed when the image data for the bitmap has been changed.

Changed is an overridden method in TCustomBitmap. Changed examines the value in Sender to determine the origin for the change.

When Sender is the Canvas for the class instance, the image was changed after an update to its Canvas. The raw image data in the shared image is no longer valid, and it is freed. The inherited method is called to free the save stream for the shared image, set the value in Modified, and signal the OnChange event handler (when assigned).

Object instance for the change notification.
Creates a handle for the bitmap using the bitmap handle type in the bitmap image data.

CreateDefaultBitmapHandle is an overridden method in TCustomBitmap used to get the default bitmap handle needed to represent the image. The device description information in ADesc is used to determine the bit depth for the image data.

For DDB (Device-Dependent Bitmaps), the CreateBitmap routine is called to get the handle used as the return value.

For DIB (Device-Independent Bitmaps), the CreateDIBSection routine is called to get the handle. For platforms where CreateDIBSection is not implemented, the CreateBitmap routine is used as the fallback.

CreateDefaultBitmapHandle is called from the BitmapHandleNeeded method in the ancestor class.

Default handle for the bitmap.
Device description information for the bitmap.
FreeMaskHandle
- method to release Mask handle.

Frees the handle allocated for the image Mask in the MaskHandle property. FreeMaskHandle sets the value in MaskHandle to 0 (zero) to indicate that the handle is no longer need or is invalid. No actions are performed in the method when MaskHandle is already set to 0.

FreeMaskHandle calls the DeleteObject routine to remove the handle in the widgetset class.

Gets the value for the Handle property.
Value for the property.
Gets the value for the MaskHandle property.
Value for the property.
Gets the value for the Palette property.
Value for the property.
Gets the value for the PixelFormat property.
Value for the property.
Gets a pointer with the raw image data.

Calls RawImageNeeded to ensure that the image descriptor, save stream, and handle are valid for the shared Bitmap image. Calls the CreateData method in the raw image pointer (when needed) prior to exiting from the method.

Pointer to the TRawImage instance for the shared bitmap image.
Gets a pointer to the image descriptor for the shared Bitmap image.

Calls RawimageNeeded to ensure that the image desriptor is valid.

Pointer to the TRawImageDescription instance for the shared bitmap image.
Gets the class reference used to create new shared image instances in the class.

GetSharedImageClass is an overridden method in TCustomBitmap. The return value is a TSharedRasterImageClass class reference used to create a shared image in the class instance. The return value is actually TSharedCustomBitmap in the method implementation.

GetSharedImageClass is called from the Assign method when a reference to an existing image is stored in the class instance. It is also used in CanShareImage to determine is the request image type is the one used in the current class instance.

TSharedCustomBitmap class type for the shared image.
Ensures that the handle for the bitmap has been assigned.

Calls BitmapHandleNeeded to create handles for both the image and its mask (when needed).

Ensures that the RawImage data is allocated prior to use.

Ensures that the RawImage property is allocated prior to accessing values in the raw image data.

ADescOnly indicates whether the image descriptor or the the complete raw image data is required. When ADescOnly is True, only the TRawImageDescription in the raw image is needed. When set to False, all values in the TRawImage instance are required.

RawImageNeeded is called from methods access the raw image data, and occurs before the value in RawImage is accessed. For example:

- SetSize
- UpdatePixelFormat
- GetMonochrome
- UnshareImage
- GetRawImagePtr
- GetRawImageDescriptionPtr

True when only the image descriptor in the raw image data is needed.
Re-implements the method from the ancestor class.

SetHandle is an overridden method in TCustomBitmap, and re-implements the method from the TRasterImage ancestor class. AValue contains the new handle assigned to the BitmapHandle property.

New value used as the handle for the bitmap.
Sets the value for the PixelFormat property.

Implements the abstract virtual method defined in the TRasterImage ancestor.

Frees the raw image data in the class instance. No actions are performed in the method when the new property value is the same as the existing property value.

New value for the property.
Frees the shared image in the bitmap, and creates a new one.

UnshareImage is an overridden method used to free the shared image in the bitmap, and create a new one. UnshareImage implements the abstract virtual method defined in the ancestor class.

UnshareImage calls GetSharedImageClass to get the class type used for the shared image, and creates a new instance of the class. It is cast to TSharedCustomBitmap, and its Reference method is called to increment the reference count for the shared image.

CopyContent indicates whether the existing image data is copied into the new shared image instance. When set to True, the content in the existing shared image is copied and stored in the new shared image instance. When set to False, only the image descriptor in the shared image is copied. This gets the metadata for the image.

UnshareImage calls FreeCanvasContext to free the device context for the Canvas used in the image.

True copies the existing content in the shared image.
Sets the handles for the image and mask in the shared Bitmap to the specified values.

UpdateHandles is an overridden Boolean function which implements the abstract virtual method defined in TRasterImage. UpdateHandles is used to set the handles for the shared bitmap image and its mask to the values specified in ABitmap and AMask.

The return value is True when the values in ABitmap and AMask are successfully applied in the class instance. The return value is False when ABitmap and Mask have the same values as the existing handles in the class instance, and the action is not needed.

The FreeHandle method in the internal shared image is called before applying the value in ABitmap.

FreeMaskHandle is called to free the value in MaskHandle before applying the value in AMask.

UpdateHandles is used in the implementation of the MaskHandleNeeded and SetHandles methods.

True when the handle(s) are successfully applied.
Handle assigned for the bitmap and shared image.
Handle assigned to the mask in the image.
Constructor for the class instance.

Create is the overridden constructor for the class instance, and calls the inherited constructor on entry. Create sets the default value for the PixelFormat property to pfDevice.

Destructor for the class instance.

Destroy is the overridden destructor for the class instance. Destroy calls FreeMaskHandle to free the handle in MaskHandle (when assigned). Destroy calls the inherited destructor prior to exiting from the method.

Copies values from the specified persistent object into the class instance.

Assign is an overridden method in TCustomBitmap used to copy property values from the persistent object in Source into the current class instance. Assign calls the inherited method on entry using Source as an argument.

When Source is a TCustomBitmap descendant, values in its PixelFormat and PixelFormatNeedsUpdate members are copied into the members in the class instance.

Persistent object with values copied in the method.
Clears the content for the bitmap image.

Clear is an overridden method in TCustomBitmap. It extends the method defined in TRasterImage. It sets the PixelFormat property to its default value ( pfDevice), and calls the inherited method to free the internal save stream for the shared image.

Releases the resources for the image when it is discarded.

FreeImage is an overridden method used to free the bitmap image. FreeImage calls the inherited method on entry to invalidate the handle used for the shared image. This also causes the device context for the Canvas to be freed and the shared image is release and freed.

FreeImage is called when a new value is assigned to the PixelFormat property.

Determines if the specified resource type is valid for the image format.

LazarusResourceTypeValid is a Boolean function used to determine if the value in ResourceType is a valid resource type for the image format.

LazarusResourceTypeValid is an overridden method in TCustomBitmap, and re-implements the method defined in the ancestor class. The return value is True when ResourceType contains one of the values:

'BMP'
  Bitmap resource type.
'BITMAP'
  Bitmap resource type.
'XPM'
  Pixmap resource type.

Case is not significant for the value in ResourceType; it is converted to uppercase prior to checking its value.

The return value is False if ResourceType contains any other value.

LazarusResourceTypeValid is used in the implementation of the LoadFromLazarusResource method.

Returns True if the resource type is valid for the image format.
The resource type examined in the method.
Returns True if a handle has been allocated for the Bitmap.

BitmapHandleAllocated is an overridden Boolean function used to determine if a handle has been allocated for the bitmap. BitmapHandleAllocated implements the abstract virtual method defined in the ancestor class.

The return value is True when the handle in the internal shared image has a non-zero value.

BitmapHandleAllocated is used in the implementation of the MaskHandleNeeded method.

Determines if the mask handle has been allocated for the image.

MaskHandleNeeded is an overridden Boolean function in TCustomBitmap, and is used to determine if MaskHandle has been allocated for the image mask. It implements the abstract virtual method defined in the ancestor class.

The return value is True when the MaskHandle property contains a non-zero value.

MaskHandleAllocated is used in the implementation of methods like:

- BitmapHandleNeeded
- SetTransparentColor
- SetBitmapHandle
- CreateMask
- Assign

Returns True if a mask handle has been allocated for the image.
Indicates whether a handle has been allocated for a palette in the image.

PaletteAllocated is an overridden Boolean function in TCustomBitmap, and indicates whether a handle has been allocated for a palette in the image. PaletteAllocated implements the abstract virtual method defined in the ancestor class.

The return value is True when palette handle in the internal shared image contains a non-zero value.

Returns True if a palette handle has been allocated for the image.
Releases the bitmap handle for the shared image.

Calls HandleNeeded to ensure that the handles for the bitmap and mask reflect the values for the raw image data. Calls the ReleaseHandle method in the shared image to free the handle for the bitmap.

Returns True when the handle is sucessfully released.
Sets handles for the bitmap and the mask to the specified values.

SetHandles is a procedure used to set the handles for the bitmap and the mask to the values specified in ABitmap and AMask. SetHandles ensures that the Canvas context, shared image, and save stream are unshared and freed. SetHandles calls UpdateHandles to store the specified handles for the shared image and its mask.

SetHandles is called from methods that load image data using TLazIntfImage from the LCL interface. It is also called when values are assigned to the BitmapHandle or MaskHandle properties.

New Bitmap handle for the image.
New Mask handle for the image.
Sets the Height and Width for the image to the specified values.

SetSize is an overridden method in TCustomBitmap used to change the Height and Width for the bitmap image to the specified values. SetSize implements the abstract virtual method defined in the ancestor class.

Calls RawImageNeeded to ensure that the image header in RawImage is valid for the image.

The values in AWidth and AHeight contain the new dimensions for the image. Both values must contain a positive value or 0. The default value for an argument is set to 0 when a negative value is found. Their values are assigned to the image desriptor in the shared imaged to change the size for the image content. No additional actions are performed in the method if either value is not successfully applied to the raw image descriptor.

Calls UnshareImage and RawImageNeeded to re-create the raw image data for the shared image.

Copies existing pixel data for the image into the resized image. When the new image size is smaller, only the portion of the image that fits within the new dimensions is copied. Uses the CopyPixels method in the TLazIntfImage instance to copy the image content.

Ensures that the Canvas context, BitMapHandle, and MaskHandle are updated for the image. Calls the Changed method to update the shared image data and signal the OnChange event handler (when assigned).

New width for the image.
New height for the image.
The operating system Handle associated with this bitmap.

In TCustomBitmap, the handle is provided by the internal shared image class (TSharedCustomBitmap) and stored in the BitmapHandle property.

Handle type for the Bitmap.

HandleType is a TBitmapHandleType property which indicates the handle type used for the bitmap image data. HandleType identifies whether the bitmap handle is classified as a Device-Dependent Bitmap (DDB) or a Device-Independent Bitmap (DIB).

See TBitmapHandleType for more information about the handle types and their specifics.

The value for the property is read from the internal shared image in the class instance. Setting a new value for the property has no effect in the current implementation; the value is always read from the raw image data.

True when the image contains monochrome image data.

Monochrome is a Boolean property which indicates whether the raw image data is represented using pixels of a single color.

The property value is True when the descriptor for the shared raw image data has a color depth of 1. The PixelFormat property willl also contain the value pf1bit.

Setting a new value in Monochrome causes the value in PixelFormat to be changed. When set to True, PixelFormat is set to pf1bit. When set to False, the value pfDevice is assigned to the PixelFormat property.

Changing the value in Monochrome (and PixelFormat) causes the image data to be discarded, and the Handle for the internal shared image is freed.

No actions are performed when Monochrome is set to the existing value for the property.

Implements a Bitmap using the FPImage reader and writer from the FCL.

Use this class to easily create a TCustomBitmap descendant using an FPImage reader and writer.

Gets the MIME type used for the image data in the image type.

GetMimeType is an overridden String function used to get the MIME type for the image data in the class instance.

Calls GetFileExtensions to get the delimited list of file extensions supported for the image type. The list is an empty string in TFPImageBitmap. Descendent classes provide value(s) which reflect the image formats supported in their implementations.

GetMimeType extracts the first file extension in the list (separated by a SemiColon character), and uses the file extension in the return value. For example:

- 'image/bmp'
- 'image/gif'
- 'image/jpg'
- 'image/png'
- 'image/tiff'
- 'image/xpm'

GetMimeType is not implemented in the current LCL version.
MIME type used for the image data in the class.
Gets the class reference used to create new instances of the FCL-compatible image reader.

Defined as an abstract virtual method in TFPImageBitmap. Must be implemented in a descendent class which provides support for a specific image format.

TFPCustomImageReaderClass descendent used for the image class type.
Gets the class reference used to create new instances of the FCL-compatible image writer.

Defined as an abstract virtual method in TFPImageBitmap. Must be implemented in a descendent class which provides support for a specific image format.

TFPCustomImageWriterClass descendent used for the image class type.
Configures the reader class instance for the image type.

InitializeReader is a virtual method used to configure the FCL-compatible image reader class instance in AReader. InitializeReader assigns the Progress method to the OnProgress event handler in AReader.

AImage is not used in the current implementation.

InitializeReader is called from the ReadStream method prior to any operation that reads the image descriptor, header, or data.

Not used in the current implementation.
FCL image reader instance updated in the method.
Configures the writer class instance for the image type.

InitializeWriter is a virtual method used to configure the FCL-compatible image writer class instance in AWriter. InitializeWriter assigns the Progress method to the OnProgress event handler in AWriter. When AWriter implmements the ILazImageWriter interface, its Initialize method is called to store the data for the LCL interface image in AImage.

InitializeWriter is called from the WriteStream method prior to any operation that writes the raw image data to a stream.

LCL interface image with the image data for the write class instance.
FCL image write instance updated in the method.
Finalizes the FCL image reader when a read operation has been completed.

FinalizeReader has an empty implementation in TFPImageBitmap. In a descendent class, it is used to update properties in the class instance to reflect values encountered by the image reader.

FCL reader class instance examined in the method.
FinalizeWriter
- ends the Image writing process.

FinalizeWriter is a virtual method used to finalize the FCL-compatible image writer class instance in AWriter. When AWriter implements the ILazImageWriter interface, its Finalize method is called to release image data in the LCL interface image.

FCL image writer class examined in the method.
Read the image data from the specified Stream.

ReadStream is an overridden method used to read the image data from the stream specified in AStream.

ReadStream creates an instance of the TFPCustomImageReader class used to read the image type from a stream. It calls InitializeReader to configure the reader class instance. If the image reader class supports the ILazImageReader interface, it is configure to update its description from the image data. Otherwise, the GetDescriptionFromDevice routine is called to store the defaults for the LCL interface image.

ReadStream calls the ImageRead method in the TFPCustomImageReader instance to load the image data from AStream. FinalizeReader is called when the operation is completed. The shared image for the image type is freed, and the raw image data from the LCL interface image is loaded into the shared image. The mask information in raw image data is applied to the shared image. The image is flagged to update the value for the PixelFormat property in the calling routine.

TMemoryStream instance with the image data read in the method.
Not used in the current implementation.
Write the data to a stream.

WriteStream is an overridden procedure in TFPImageBitmap used to write the image content to the stream specified in AStream. WriteStream implements the abstract virtual method defined in TRasterImage.

WriteStream creates temporary TLazIntfImage and TFPCustomImageWriter instances that are used to write the data for the internal TRawImage instance used in the class. Raw image data is stored in the TLazIntfImage instance, and its SaveToStream method is called to write the values to AStream.

No actions are performed in the method when the data size for the raw image is 0.

Stream where the image data is stored.
Returns a list of the file extensions available for the image type.

Always returns an empty string ('') in TFPImageBitmap.

List of file extensions supported for the image type.
Determines if the specified stream contains image data supported for the image type.

IsStreamFormatSupported is an overridden TFPImageBitmap class function used to determine if the stream specified in Stream contains image data supported in the image type.

IsStreamFormatSupported creates a temporary instance of the TFPCustomImageReader used for the image type, and calls its CheckContents method to examine the values in Stream. The return value is True when the FCL image reader recognizes the image format.

IsStreamFormatSupported saves the position in Stream on entry, and restores the position prior to exiting from the method.

True when the stream contains a image data in a supported format.
Indicates whether the given file extension is supported for the image type.

IsFileExtensionSupported is a Boolean class function used to determine if the file extension in FileExtension is valid for the image type. If FileExtension includes a period character ('.'), it is removed before use.

The return value is True when FileExtension is included in the value returned by the GetFileExtensions method. No actions are performed in the method when FileExtension is an empty string ('').

IsFileExtensionSupported is used in the implementation of LazarusResourceTypeValid.

True when the file extension is valid for the image type.
File extension checked for the image type.
Determines if the specified resource type is valid for the image format.

LazarusResourceTypeValid is a Boolean function used to determine if the value in ResourceType is a valid resource type for the image format.

LazarusResourceTypeValid is an overridden method, and re-implements the method defined in the ancestor class. The return value is True when ResourceType contains is one the file extensions returned from IsFileExtensionSupported. The return value is False if ResourceType contains any other value.

LazarusResourceTypeValid is used in the implementation of the LoadFromLazarusResource method.

True when the resource type name is one file extensions for the image format.
Resource type examined in the method.
Class reference used to create new instances of TFPImageBitmap.
Defines a reference-counted shared Bitmap graphic.

TSharedBitmap is a TSharedCustomBitmap descendant.

Implements a FCL-compatible reader/writer for a Bitmap image.

TBitmap is a TFPImageBitmap descendant which represents the data for a Bitmap image. The image can be loaded from a file, stream or resource which uses .bmp (windows bitmap) format.

TBitmap provides overridden methods which get the image reader (TLazReaderBMP) and writer (TLazWriteBMP) class references, as well as the shared image storage class (TSharedBitmap).

An overridden LoadFromStream method is provided which handles reading the BMP header using the correct endian-ness for the platform. The loading routine automatically recognizes the format, so it is also used to load the images from Delphi form streams (e.g. .dfm files) or FreePascal/Lazarus form streams (.lfm).

When the handle for the image is created, it is up to the interface (GTK, QT, Win32,etc.) to convert it automatically to the best internal format for the widgetset. That is why the Handle is interface dependent.

To access the raw image data, see TLazIntfImage.

Please note that the current implementation is dramatically different than previous LCL implementations. Most of the low-level functionality for TBitmap has been refactored into ancestor or descendent classes.
TLazIntfImage TLazReaderBMP TLazWriterBMP
Initializes the image reader to use the transparency settings in the class instance.

InitializeReader is an overridden procedure used to apply transparency settings to the image reader in AReader. InitializeReader calls the inherited method on entry to signal the OnProgress event handler (when assigned).

InitializeReader ensures that AReader is derived from TLazReaderBMP. No additional actions are performed in the method when AReader is not a TLazReaderBMP class instance.

InitializeReader applies values from the TransparentMode and TransparentColor properties to the mask settings in AReader.

TransparentMode

Determines whether the transparency color is auto-detected in the image data, or a fixed transparency color is used.

tmAuto
  The bottom left pixel in the image data contains the transparency color.
tmFixed
  Uses a predefined color in TransparentColor as the transparency color.

TransparentColor

Determines the color used to represent transparent areas in the image data.

clDefault
  Uses the bottom left pixel as the transparency color. This is a Lazarus extension.
clNone
  Ignores transparency in the image data. This is a Lazarus extension.

All other color constants represent the color for transparent pixels in the image.

Values in TransparentMode and TransparentColor are assigned to the MaskMode and MaskColor properties in AReader as required.

Provides access to the raw data for the image.
Reader used to access raw data for the image.
Gets the class reference used to create the FCL-compatible reader for the image.

GetReaderClass is an overridden TFPCustomImageReaderClass class function used to get the FCL-compatible reader for the image type. The return value is a TLazReaderBMP class reference in TBitmap.

GetReaderClass is called from the ReadStream method when the reader is created and initialized. It is used to load a TLazIntfImage instance with the image content supplied in a stream. It is also used in the IsStreamFormatSupported method to determine if the stream contains an image format that can be read using the reader class type.

TLazReaderBMP TLazReaderDIB ILazImageReader
Class reference used to create instances of the reader class.
Gets the class reference used to create instances of the FCL-compatible image writer.

The return value is a TLazWriterBMP class reference in TBitmap.

GetWriterClass is called from the WriteStream method when the image writer is used to write a TLazIntfImage instance to a stream.

Class reference used to create instances of the writer class.
Gets the class reference used to create new instances of a shared image.

GetSharedImageClass provides a class reference used to create new instances of the shared image class used in TBitmap.

The return value is a TSharedBitmap class reference in TBitmap.

GetSharedImageClass is called from methods like Create, Assign, and CanShareImage.

Class reference used to create new instances of the shared image class.
Gets the file extensions supported for the image type.

GetFileExtensions is an overridden String class function used to get a delimited list of file extensions used for graphic files supported in the class. The '.' character is omitted from file extension(s), and extensions are separated by a SemiColon (;) character.

In TBitmap, the method returns the value 'bmp' for the Windows Bitmap format supported in the class.

File extensions used for the image type.
Gets the resource type identifier for the image format.

GetResourceType is an overridden method used to get the resource type identifier for the image format. GetResourceType returns the value in the RT_BITMAP constant for the Windows Bitmap image format.

Returns the RT_BITMAP constant.
Loads image data from the specified stream.

LoadFromStream is an overridden method used to read data for the image from the TStream instance specified in AStream. ASize contains the number of bytes to read in the method.

LoadFromStream provides supported for reading the image data from a resource stream. When AStream is a TResourceStream instance, an image header included in the stream is handled. This includes allocating additional storage for the header, and setting the type and size of the image header using the correct endian handling for bytes as needed for the platform.

LoadFromStream calls the inherited method to read the image data (including the header for a resource stream).

TResourceStream
Stream instance with the image data loaded in the method.
Number of bytes to read in the method.
Implements a reference-counted shared Pixmap image type.
Implements support for the XPM (Pixmap) image format.

TPixMap is a TFPImageBitmap descendant, and is a wrapper used to handle the Pixmap ('XPM') image format.

Pixmap is an image file format used by the X Window System. It is intended primarily for creating icons, and supports transparent pixels. Derived from the earlier XBM syntax, it is a plain text file using the XPM2 format or a C programming language syntax, which can be included in a source code file.

TPixmap ensures that specified resources (image, file, or stream) are of the correct type and format.

Gets the class reference for a reader used during component streaming.
Class reference for a reader used during component streaming.
Gets the class reference for a writer used during component streaming.
Class reference for a writer used during component streaming.
Gets the class reference used to create the shared image in the class instance.
class reference used to create the shared image in the class instance.
Determines if the specified resource type is valid for the image format.
Returns True if the resource type is 'XPM'
Resource type examined in the method.
Gets the file extensions supported for the image type.

GetFileExtensions is an overridden String class function used to get a delimited list of file extensions used for graphic files supported in the class. The '.' character is omitted from file extension(s), and extensions are separated by a SemiColon (;) character.

In TPixmap, the method returns the value 'xpm' for the Pixmap format supported in the class.

File extension(s) supported for the image format.
TSharedPortableNetworkGraphic
- a reference counted PNG Image.

TSharedPortableNetworkGraphic is a TSharedCustomBitmap descendant which implements a reference counted PNG image. TSharedPortableNetworkGraphic is the type returned by the GetSharedImageClass method in TPortableNetworkGraphic.

Implements support for the PNG image format.

TPortableNetworkGraphic is a TFPImageBitmap descendant which implements support for the PNG (Portable Network Graphics) image format. PNG is a raster graphic file format that supports loss-less data compression. PNG was developed as an improved, non-patented replacement for GIF (Graphics Interchange Format).

PNG supports palette-based images (using 24-bit RGB or 32-bit RGBA colors), grayscale images (with or without alpha channel transparency), and full-color non-palette-based RGB or RGBA images. A PNG file contains a single image in an extensible chunk structure, and uses encoding to compress repetitive pixel values in the image.

PNG image files use the file extension PNG or png, and uses the MIME media type 'image/png'.

Determines if the specified stream contains image data supported for the image type.
TSharedPortableAnyMapGraphic
- a reference counted shared PNM.
Implements an image which supports for the Portable Any Map (PNM) graphic format.

TPortableAnyMapGraphic is a TFPImageBitmap descendant which implements support for the Portable Any Map (PNM) graphic format.

PNM is a member of the NetPBM family of image formats and includes PBM, PGM, and PPM image formats. The group is referred to collectively as the Portable Any Map format, and uses the .PNM file extension.

Determines if the specified stream contains image data supported for the image type.
Class reference used to create new instances of TIconImage.
Implements a reference-counted shared Icon image type.

TSharedIcon is a TSharedRasterImage descendant which implements a reference counted shared Icon. TSharedIcon provides access to the list of images available in the Icon as TIconImage instances using the Images property. Methods are provided to add, delete, clear, sort, and retrieve the images.

TSharedIcon is the type used to implement the internal shared image in TCustomIcon (and descendant classes).

Frees the handle for the shared reference-counted icon.

FreeHandle is an overridden method in TSharedIcon. It calls DestroyIcon to free the Handle for the shared Icon in the widgetset class. It does not call the inherited method. No actions are performed in the method when Handle contains 0 (zero).

Frees the existing icon image and reloads it from the specified handle.

Calls FreeHandle to free the existing handle for the Icon in the widgetset class, and sets the Handle to the value specified in NewHandle. Gets icon information from the widgetset class and adds a new icon image to the list of Images.

Indicates if the shared icon is empty (contains no icon images).
Gets the value for the indexed Images property.
TIconImage instance at the specified position in the image list.
Ordinal position for the image retrieved from the image list.
Create
- constructor for TSharedIcon: performs inherited Create then creates a list of images.
TObject.Create
Destroy
- destructor for TSharedIcon: frees the list of images and performs inherited Destroy.
TObject.Destroy
Clear
- remove the icon and free its resources.
Removes the icon image with the specified index.
Ordinal position for the icon image removed in the method.
Gets the Index of an image with specified pixel format, height and width.
Ordinal position for the icon image matching the requested value(s).
Pixel format (color depth) to locate in the Images.
Height for the requested image.
Width for the requested image.
Gets the class reference used to create a new icon image in the Images property.
Adds the specified image to the list of Images in the icon.
Sorts values in Images using the IconCompare routine.
Count
- returns the number of references to the shared icon.
Provides indexed access to the images available in the Icon.
Ordinal position for an icon image in the list of images.
TIconImage
- a primitive Icon class with handles for the Bitmap, Mask and Palette.
Gets the value for the Palette property.
Value for the property.
RawImageNeeded
- if ADescOnly is True (descriptor only), then we need a Raw Image.
Updates the icon image from the specified raw image data.

UpdateFromImage is a procedure used to update the icon image from the specified raw image data.

AImage is a TRawImage instance with the image content stored in the RawImage property in the class instance. The image descriptor in AImage is examined to get the values stored in the Height and Width properties. The color depth in AImage is converted and stored in the PixelFormat property.

UpdateFromImage is called from the Create constructor when a TRawImage or a TIconInfo argument is provided.

TRawImage
Raw image data stored in the method.
Create
- Specifies a Raw image to be used, then used Inherited Create.

Create is the overloaded constructor for the class instance. Variants are provided with parameters which specify the dimensions and/or content for the icon image. The variant with the TIconInfo argument is used to create a new icon image when a handle is assigned in TSharedIcon.

TObject.Create
Pixel format (color depth) for the image data.
Height in pixels for the image.
Width in pixels for the image.
Raw image data used to load the content in the image.
Structure with Hotspot, Mask and Color information for the icon image.
Destructor for the class instance.

Destroy is the overridden destructor for the class instance. Destroy ensures that existing values in Handle, MaskHandle, and Palette are freed by calling DeleteObject. The raw image data used the class instance is also freed. Destroy calls the inherited destructor prior to exiting from the method.

TObject.Destroy
Releases the Handle for the icon image.

ReleaseHandle is a HBITMAP function used to release the Handle assigned for the icon image. The return value contains the HBITMAP value for Handle before it is released. ReleaseHandle sets the value in Handle to 0 (zero) to indicate that the handle is no longer in use or invalid.

ReleaseHandle is called when a TCustomIcon descendant calls its InternalReleaseBitmapHandle method.

Use ReleaseMaskHandle to release the MaskHandle for the icon image.

Use ReleasePalette to release the Palette handle used in the icon image.

ReleaseMaskHandle
- returns mask Bitmap handle to operating system.
ReleasePalette
- returns Palette handle to operating system.
UpdateHandles
- returns True when Bitmap and Mask handles have been updated.

UpdateHandles is a Boolean function used to set the handles for the Bitmap and its optional Mask to the specified values. DeleteObject is called to remove existing handle value(s) in the Handle and MaskHandle properties.

The return value is True when the value(s) in Handle and/or MaskHandle are successfully set to the specified values.

UpdateHandles emulates the method with the same name in TCustomBitmap. UpdateHandles is called when the TIcon instance where the icon image is used calls its UpdateHandles method.

True when the handles are successfully updated.
Handle for the Bitmap stored in the method.
Handle for the Mask stored in the method.
The Height of the Icon.
The Width of the Icon.
PixelFormat
- the format of the Pixels in the Image.
Handle
- for the Bitmap.
MaskHandle
- Bitmap handle for the Mask.
Handle for the Palette.

Palette is a read-only HPALETTE property which provides access to the color palette used in the Icon image.

Palette is not implemented in the current LCL version.
Raw image data for the icon image.

RawImage is a read-only TRawImage property which contains the raw image data for the icon image.

The property value is assigned in the Create method when a TRawImage argument is provided. The UpdateFromImage method is used to examine the raw image data and get the values stored in properties.

TRawImage
TCustomIcon
- base class for TIcon.

TCustomIcon is a TRasterImage descendant which implements the base class for TIcon. TIcon supports image files using the .ICO file format. An .ICO file typically contains several images with different sizes and/or color depths.

TCustomIcon extends the ancestor class to include an internal list of images, and provides overridden methods which use the list of images in their implementations. This includes the ReadData method used during LCL component streaming. ReadStream is overridden to handle not only multiple images but PNG and DIB image formats used in some Icon files.

When loading an icon file, the largest/most colorful image is selected as the current image. Other sizes and/or color depths are accessed by setting the value in the Current property, or using Size when Current is not already set, or by setting Current to the value from the GetBestIndexForSize method.

Use the Count, Add, Delete, Remove, Clear, and AssignImage methods to maintain the images in the internal list.

Please note that writing to an icon file is not currently implemented in TCustomIcon (or descendent classes).
Gets the value for the Count property.
Value for the property.
Sets the value for the Current property.
New value for the property.
FCurrent
- local variable to hold current sequence number.
Member used for the requested icon size.
Ensures that a handle for the mask in the icon is valid.
An empty implementation in TCustomIcon.

Palette information is handled in the .ICO image format.

Indicates whether the image class type has a shared handle.

Determines whether the the image class type can be shared. Returns True when AClass is derived from TSharedIcon.

This is a temporary work-around to make Assign work with cursors, icons and icnsicons.

Returns True when AClass is derived from TSharedIcon.
CheckRequestedSize
- method to ensure correct size requested.
GetIndex
- returns the Index value of the Icon with specified format and size (.icn files can contain several versions of image).

Gets the ordinal position in the internal image list for the icon with the specified pixel format, height, and width. The return value is -1 if an image using all of the requested values was not found in the list.

Assign the return value to the Current property to use it as the selected image for the icon.

Use GetBestIndexForSize to find the position of the image which matches most closely the specified height and width.

Ordinal position for the image with the requested attributes, or -1 when not found.
Color depth for the requested icon image.
Height for the requested icon image.
Width for the requested icon image.
Gets the value for the BitmapHandle property.

Implements the abstract method defined in the ancestor class.

Value for the property.
GetDefaultSize
- returns default size for Icon.

GetDefaultSize is a TSize class function used to get the default size in new instances of the class. The return value uses the SM_CXICON and SM_CYICON values returned from the GetSystemMetrics function in its cx and cy members.

TSize instance with the default width and height for an icon.
Gets the value for the MaskHandle property.

GetMaskHandle implements the abstract method defined in the ancestor class.

Value for the property.
Gets the value for the Palette property.
Value for the property.
Gets the value for the PixelFormat property.

Implements the abstract virtual method defined in the ancestor class.

Value for the property.
Gets a pointer to the raw image data for the icon.

GetRawImagePtr is an overridden method used to get a pointer to the raw image data for the icon image. The return value is a PRawImage type which points to the data in a TIconImage instance in the shared image list for the icon.

GetRawImagePtr uses the value in Current to determine which image is retrieved from the internal image list. When Current is -1, the return value is Nil. Otherwise, the shared icon image at the position in Current is accessed to get the return value for the method.

GetRawImagePtr is called from AssignImage a raw image is assigned to the icon. It is also used to get mask image data in the MaskHandleNeeded method.

Pointer to the raw image data, or Nil when Current is not assigned.
Gets the stream signature used for icon data.

GetStreamSignature is a Cardinal class function used to get the signature which identifies the image content when stored in a stream. GetStreamSignature is used in the implementation of the ReadData method which reads the values for the class instance during LCL component streaming.

GetStreamSignature is defined as a virtual method, and is overridden in TIcon to use the value required for the icon image format.

Cardinal value with the stream signature for the class.
Gets the icon type identifier used in the image list header.

GetTypeId is a Word class function used to get the image type identifier used for icon images. It is used in the implementation of the WriteStream method, and provides the value stored in the icon image header.

Since TCustomIcon instances are not included in component streaming, the return value is always returns 0. GetTypeId is overridden in TIcon to provide the value used in the derived class.

Type identifier for images in the icon.
Ensures that a handle for the image has been allocated.

HandleNeeded is an overridden procedure used to ensure that a handle for the image has been allocated. HandleNeeded re-implements the method defined in the ancestor class.

No actions are performed in the method when a valid valid has already been assigned to the shared image in the class instance.

HandleNeeded calls the CreateIconIndirect routine for the widgetset to get the value used as the Handle for the shared image.

Reads data for the class instance from a stream.

ReadData is an overridden method used to read the data for the class instance from the TStream instance specified in

Stream. ReadData is the method called when TFiler reads a persistent object during LCL component streaming.

ReadData saves the position in Stream on entry, and restores the original position prior to exiting from the method.

ReadData checks the values in Stream to determine if a size prefix for the content is stored in the stream. Delphi streaming does not include the size prefix. Current Lazarus versions do. When the LongInt value used as the StreamSignature is 0, the LoadFromStream method is called to load the contents of the stream. Otherwise, the inherited method is called to complete the operation.

ReadData is also called from the LoadFromResourceHandle method in TIcon.

TFiler
Reads the content for the icon from the specified stream.

ReadStream is an overridden procedure used to read the content for the icon from the stream specified in AStream. ReadStream implements the abstract virtual method defined in the ancestor class.

ReadStream verifies that AStream contains an icon image by checking for header value(s) that are valid for .ICO data. If the header values are nopt found, an EInvalidGraphic exception is raised.

For icon data, the icon directory must be read from the stream. The header contains the number of icon directory entries included in the stream. The icon directory entries are read from AStream, and include values for each icon image that includes:

- HotSpotX
- HotSpotY
- BytesInRes
- ImageOffset

ReadStream positions the stream, and reads image data for the each of the icon directory entries. It handles both DIB Bitmap and PNG (used in WIndows Vista) image data for the icon images. An FCL-compatible image reader is created as required for the image type, and a TLazIntfImage instance is used to capture the raw image data from the stream. Images read from the stream are added to the internal list of images in the TSharedIcon member for the class instance.

ReadStream calls CheckRequestedSize to use the Width and/or Height specified in the class instance. GetBestIndexForSize is called to determine the value in Current with the requested image size.

Stream instance with the image content read in the method.
Number of bytes expected for the icon data.
Sets the value for the Masked property.

SetMasked is an empty implementation in TCustomIcon.

New value for the property.
Sets the value for the PixelFormat property.

Changing the value for PixelFormat raises an EInvalidGraphicOperation exception in TCustomIcon.

New value for the property.
Sets the value for the Transparent property.

SetTransparent is an empty implementation in TCustomIcon.

New value for the property.
Unshares the shared image when the content in the icon is changed.

UnshareImage is an overridden procedure used to stop sharing the image(s) for the icon. UnshareImage implements the abstract virtual method defined in the enacestor class.

No actions are performed in the method when the RefCount for the internal TSharedIcon instance is less than 1.

When sharing is stopped, the internal TSharedIcon instance in the class is re-created.

CopyContent indicates whether existing content from icon images is copied into the new image list. When set to True, TIconImage instances are re-created for each of the icon images and their existing content is copied. When set to False, image data for the icon is empty.

UnshareImage calls FreeCanvasContext to discard the device context used in the Canvas.

UnshareImage calls the Release method for the old TSharedIcon instance.

UnshareImage is called from methods which alter the handle or image content for the icon, including:

- SetHandle
- Add
- Assign
- AssignImage
- Delete

True if existing image content is copied in the method.
UpdateCurrentView
- updates the current appearance of the Icon.

UpdateCurrentView is a procedure used to refresh the canvas when an icon image has been modified. UpdateCurrentView frees the device context (or handle) for the Canvas, and calls the Changed method.

UpdateCurrentView is called from methods like Add and Delete, and when a new icon image is selected by setting the value in the Current property.

Unshares an existing shared image handle and set the new value.

SetHandle is a method used to set set the value for the shared image handle in the icon instance. It ensures that an existing shared image handle frees both its canvas context and the data in its TSharedImage instance.

It calls UpdateHandle to set the new shared handle for the icon instance to AValue. Values in Current and Count are reset when the handle is changed. Current is set 0 when multiple images are used in the icon. It is set to -1 when a single image is present. Changed is called to update the value in Modified and signal the OnCHange event handler (when assigned).

New value for the shared image handle in the icon.
Updates the handle in the shared icon image top the specified value.

UpdateHandle is a Boolean function used to update the shared icon image when the handle specified in AValue differs from the handle in the shared image.

The return value is True when the handles have different values on entry. UpdateHandle calls the UpdateFromHandle method in the TSharedIcon instance using AValue as an argument.

No actions are performed in the method when the return value is False.

UpdateHandle is called when a new value is assigned to the Handle property.

True when the handle in the icon is different that the handle in the shared icon image.
Handle compared to the shared icon image.
Sets the Bitmap and Mask handles for the current image in the icon.

UpdateHandles is an overridden method used to set the Bitmap and Mask handles for the Current icon image to the specified values. UpdateHandles implements the abstract virtual method defined in the ancestor class.

UpdateHandles uses the value in Current to determine the TIconImage in the internal image list that is updated in the method.

When Current is set to -1, an icon image has not been selected and no actions are performed in the method. The return value is False if the handles could not be applied to icon image.

UpdateHandles calls the UpdateHandles method for the TIconImage indicated in Current using the values in ABitmap and AMask as arguments. The return value is True if the handles are successfully applied to the icon image.

UpdateHandles is called from methods like:

- BitmapHandleNeeded
- MaskHandleNeeded
- UpdateHandle
- Assign

True if the new handles are successfully applied to the icon image.
Bitmap handle for the current image in the icon.
Mask handle for the current image in the icon.
Writes the content for the multi-image icon to the specified stream.

WriteStream is an overridden method used to write the content for the multi-image icon to the stream specified in AStream. WriteStream implements the abstract virtual method defined in the ancestor class.

WriteStream performs actions needed to write the header, icon directory, and content for each of the images used in the multi-image icon to the TMemoryStream instance. It handles both PNG and DIB Bitmap icon images, and creates Mask data for images when it is not already present.

For icon images used in TCursorImage, the X and Y coordinates for the HotSpot are also included in the image data.

WriteStream is called from SaveStreamNeeded when the SaveToStream method is performed.

TMemoryStream instance where icon data is stored.
Constructor for the class instance.

Create is the overridden constructor for the class instance, and calls the inherited constructor on entry. Create sets the default values for properties, including:

Current
  Set to -1 to indicate that an icon image has not been selected.
Masked
  Set to True. By definition, an icon is masked. Does not account for icon images with an alpha channel.

Create initializes the internal member used to track the size for a requested icon.

Add
- an Icon formatted as AFormat, with specified Height and Width.

Add is procedure used to create an image for the icon with the attributes specified in AFormat, AHeight, and AWidth. Add calls GetIIndex to determine if an icon image with the requested attributes already exists in the image list for the icon. An EInvalidGraphicOperation exception is raised when the image already exists in the internal image list.

Add calls UnshareImage to release the shared image handle, and adds a new image class instance to the shared icon. If the icon image is the first one in the list, the value in Current is set to 0 (zero) and the UpdateCurrentView method is called.

Use Current to make an icon image active for the class instance. Use AssignImage to store the image at the position in Current.

Pixel format (color depth) for the icon image.
Height in pixels for the icon image.
Width in pixels for the icon image.
Copies values from the specified persistent object into the current class instance.

Assign is an overridden method used to copyvalues from the persistent object in Source into the current class instance. Assign calls BeginUpdate to increment the active update counter, and calls EndUpdate prior to exiting from the method.

Assign handles specific class types in Source, including:

TRasterImage
  Calls Clear to remove existing image content, and calls Add to create and icon image with the attributes in the PixelFormat, Height, and Width properties in Source. Calls AssignImage to store the image content from Source in the icon image. If the shared image class in Source is different than the one for the current class instance, UnshareImage is called.
TCustomIcon
  Sets the value in Current to the value found in Source.

When Source is derived from another class type, the inherited Assign method is called.

TPersistent.Assign
Persistent object with values copied into the current class instance.
Copies image data from the source image to the current icon image.

AssignImage is used to copy image data from ASource to the currently selected image for the icon.

AssignImage is typically used to assign the icon image when Add is used to create a new icon image with the required attributes (PixelFormat, Height, Width). AssignImage is called from the Assign method to store a single raster image to the icon.

Image with the values assigned to the current icon image.
Removes the image content for the icon.

Clear is an overridden method used to remove the image content for the icon. Clear frees the internal save stream for the image. The internal shared image is also freed and re-created. The value in Current is set to -1 to indicate that an icon image has not been selected.

Clear calls the Changed method to set the value in Modified and signal the OnChange event handler (when assigned).

No actions are performed in the method when Empty returns True.

Clear does not call the method inherited from TRasterImage.
Deletes the image at the specified position in the list of images for the icon.

Delete is a procedure used to delete the icon image at the ordinal position specified in AIndex from the list of images for the icon.

Delete calls UnshareImage to stop sharing the image list for the icon. A copy of the images is kept and restored when the Delete method in TSharedIcon has removed the image at the specified postion.

When AIndex is also the Current image for the icon, Current is set to -1 and the UpdateCurrentView method is called. Otherwise, the value in Current is decremented.

Use Remove to delete an icon image with specific PixelFormat, Height, and Width values.

Use Add to add an icon image with specific PixelFormat, Height, and Width values.

Use Count to determine the number of images in the list of images for the icon.

Ordinal position for the icon image deleted in the method.
Removes an icon image with the specified attributes.

Remove is used to locate and delete an icon image with the attributes specified in AFormat, AHeight, and AWidth.

Remove calls GetIndex to get the position in the internal image list where the icon image with the specified attributes is stored. If an image is found, the Delete method is called to the remove the icon image.

The value in Current is modified when it represents an icon image affected by the removal. Current is set to -1 when it contains the index for the icon image removed in the method.

Pixel format (color depth) for the icon image.
Height for the icon image.
Width for the icon image.
Gets metadata which describes the icon image at the specified position in the image list.

GetDescription is used to get image metadata whcih describes the icon image at the position specified in AIndex. AFormat, AHeight, and AWidth are output parameters where the corresponding values from the TIconImage instance are stored.

GetDescription accesses the image list in the internal TSharedIcon instance used in the class.

Aindex
- the Index value for the Icon.
AFormat
- the Pixel Format for the Icon.
AHeight
- the height of the Icon.
AWidth
- the width of the Icon.
Sets the size (width, height) for the image in the Icon.

SetSize is an overridden method used to set the size for the image in the icon to the values specified in AWidth and AHeight. SetSize implements the abstract virtual method defined in the ancestor class. SetSize stores the argument values in an internal member used to track the requested icon image size used in the GetBestIndexForSize method.

SetSize raises an EInvalidGraphicOperation exception when an icon size has been selected by setting a value in the Current property.

SetSize is called from the ReadStream method.

Raises an EInvalidGraphicOperation with the message in rsIconImageSizeChange when Current contains a value other than -1.
New Width for the icon.
New Height for the icon.
Gets a delimited list of file extensions supported for the image type.

GetFileExtensions is an overridden String class function used to get a delimited list of file extensions supported for the image type. In TCustomIcon and TIcon, the return value is always 'ico'.

Delimited list of file extensions supported for the image type.
Determines if the specified resource type is valid for the image format.

LazarusResourceTypeValid is an overridden Boolean function used to determine if the specified resource type is valid for the image format.

The return value is True when ResourceType contains 'ICO' or 'ICON'. The inherited method is called to get the return value when ResourceType contains any other resource type name. Case is not significant when comparing the value in ResourceType; it is converted to uppercase in the method.

True when the resource type identifier is valid for the image format.
Resource type identifier examined in the method.
Loads the icon with the specified resource name from the instance handle.

LoadFromResourceName is an overridden procedure used to load a resource with the name specified in ResName using the handle provided in Instance. LoadFromResourceName re-implements the method defined in the ancestor class, and does not call the inherited method.

LoadFromResourceName calls GetResourceType to get the Integer resource type used in the class instance. No actions are performed in the method when the TResourceType value is unassigned (contains Nil).

LoadFromResourceName calls FindResource to get the resource handle needed in the method. An EResNotFound exception is raised if a resource with the specified name and type is not found in FindResource.

LoadFromResourceName calls LoadFromResourceHandle to load the icon using the Instance and resource handle values.

Use LoadFromResourceID to load a resource by its Resource ID.

Use LoadFromLazarusResource to load a Lazarus resource from a .lrs file with a give name.

Handle where the content for the resource is stored.
Name for the resource loaded in the method.
Load icon data from a resource with the specified integer resource identifier.

LoadFromResourceID is an overridden procedure used to load a resource with the specified Resource ID into the class instance. LoadFromResourceID re-implements the method defined in the ancestor class, and does not call the inherited method.

Instance contains the Handle used to read the resource. ResID contains an Integer pointer to the resource identifier loaded in the method.

LoadFromResourceID calls GetResourceType to get the Integer resource type used in the class instance. No actions are performed in the method when the TResourceType value is unassigned (contains Nil).

LoadFromResourceName calls FindResource to get the resource handle needed in the method. An EResNotFound exception is raised if a resource with the specified ID and type is not found in FindResource.

LoadFromResourceName calls LoadFromResourceHandle to load the icon using the Instance and resource handle values.

Use LoadFromResourceName to load a resource with a given resource name.

Use LoadFromLazarusResource to load a Lazarus resource from a .lrs file with a give name.

Raises an EResNotFound exception if the resource handle for the specified ID and type is not valid.
Handle where the content for the resource is stored.
Integer resource identifier loaded in the method.
Loads icon data from the specified instance and resource handles.

LoadFromResourceHandle has an empty implementation in TCustomIcon. It is re-implemented in TIcon descendant.

Handle with the resource data loaded in the method.
Resource handle with the icon data loaded in the method.
Indicates if a handle for the icon image has been allocated.

BitmapHandleAllocated is an overridden Boolean function which indicates if a handle for the icon image has been allocated in the class instance. BitmapHandleAllocated implements the abstract virtual method defined in the ancestor class.

The return value is True when Current has a valid image index for the icon image, and the handle for the TIconImage in the shared icon has a non-zero value.

BitmapHandleAllocated is called from methods that required a valid image handle prior to performing actions using the image data. For example:

- Assign
- BitmapHandleNeeded
- MaskHandleNeed
- Draw
- EndUpdate
- SetMaskHandle

True when a valid handle has been assigned for the shared icon image.
True if a handle has been allocated for the mask in the image.

MaskHandleAllocated is an overridden method used to determine if a handle for the image mask has been allocated in the class instance. MaskHandleAllocated implements the abstract virtual method defined in the ancestor class.

The return value is True when Current contains a value other than -1, and the MaskHandle for the TIconImage in the shared image list has a non-zero value.

MaskHandleAllocated is called from methods that required a valid handle prior to performing actions using the mask image data. For example:

- Assign
- AssignImage
- BitmapHandleNeeded
- MaskHandleNeeded
- CreateMask
- SetTransparentColor
- SetBitmapHandle
- SetMaskHandle

True when the MaskHandle has been allocated for the icon image.
Determine if a handle has been allocated for the Palette in the icon.

PaletteAllocated is an overridden method used to determine if a handle has been allocated for the Palette in the icon image. PaletteAllocated implements the abstract virtual method defined in the ancestor class.

The return value is True when Current contains a value other than -1, and the palette handle in the TIconImage instance for the shared icon image has a non-zero value.

While provided as property in TCustomIcon, Palette is never assigned in the TIconImage class instances used to represent the individual images in the icon. Effectively, Palette is not implemented for TCustomIcon and PaletteAllocated will always return False.
True when the Palette handle has been allocated for the icon.
Not implemented in TCustomIcon.

SetHandles has an empty implementation in TCustomIcon.

Handle for the Bitmap in the icon.
Handle for the Mask in the icon.
Sorts the images for the icon.

Sorts images in the internal image list for the icon. The Sort method in TSharedIcon is called to perform the sort, and compares the Width/PixelFormat values in the images to determine the sort order. Preference is given to the value in Width; if two items have the same Width, the value in PixelFormat is used for the comparison.

Sort keeps a reference to the image in Current when it is set to a value other than -1. The image is used to restore the value in Current when the sort operation is completed. The IndexOf method for the internal image list is called determine the new position for the referenced image.

Gets the ordinal position for the image closest to the requested size.

The default icon size from GetSystemMetrics is used when ASize does not have explicit values in its cx and cy members. The best color depth is determined using the GetDeviceCaps routine for the screen context.

GetBestIndexForSize iterates over the items in the internal image list to find the TIconImage which most closely matches the required values. The return value is -1 if no images are stored in the internal image list for the icon.

Ordinal position for the image, or -1 when no images are available.
TSize instance with the height and width for the requested image size.
Ordinal position for the current image displayed for the icon.

Current is an Integer property which contains the ordinal position for the selected image in the icon. Setting a new value for the property causes the UpdateCurrentView method to be called to update the Canvas, and the save stream for the shared image. The OnChange event handler is signalled (when assigned).

Set Current to -1 before calling SetSize (or changing values in Height and Width) to avoid raising an EInvalidGraphicOperation exception.

Number of images in the image list for the shared icon.

Count is a read-only Integer property which contains the number of images in the internal image list for the icon. Read access for the property value is redirected to the Count property in the internal TSharedIcon instance used in the class.

Use methods like Add, Delete, Remove, Clear, Assign, and AssignImage to maintain the list of images available in the icon.

Implements an icon image type; small images typically associated with applications, controls, etc.

Icons can be loaded from .ICO files, or from Lazarus resources. An icon resource typically contains several versions of the same image, in multiple resolutions and color depths.

When loading, the largest/most colorful image is loaded as the Bitmap property, and so can be handled as any other bitmap.

Writing to icon files is not (yet) implemented.
Gets the value for the Handle property.
Value for the property.
Sets the value for the Handle property.
New value for the property.
Ensures that handle values for the icon are valid.

Ensures that Handle values are valid for the icon. Configures the values in IconInfo with the BitmapHandle and MaskHandle for the class instance. Calls CreateIconIndirect for the widgetset to get the Handle used for the shared image in the icon.

No actions are performed in the method when the Handle for the shared icon image has already been assigned.

Loads icon data from the specified instance and resource handles.
Handle with the resource data loaded in the method.
Resource handle with the icon data loaded in the method.
Frees the Handle used for the Icon.
HICON value removed from the Handle in the class instance.
Gets the Integer Resource Type for the class instance.

GetResourceType is an overridden TResourceType function in TIcon. It is used to get the resource type identifier for the class instance. It identifies the storage format used for graphic data in a resource.

The return value is RT_GROUP_ICON in TIcon.

Resource type used for the icon image type.
Handle used to access the image data for the icon.

Handle is a HICON property which contains the icon handle used to access image data for the icon. The property value is provided by the GetHandle method.

Record type with the icon type and raw image data for a TIcnsIcon instance.
TIcnsIconType value for the icon data, mask, or alpha channel used in the raw image.
Contains the TRawImage instance with the data for an icon image.
Pointer to a TIcnsRec instance.
Implements a list used to maintain TIcnsIcon instances.

TIcnsList is a TList descendant which implements a list used to create, store, and maintain TIcnsIcon instances. It provides indexed access to the icons using the Items property. It re-implements the Add method to allow an icon instance to be created and stored using the specified icon type and raw image data.

TIcnsList is the type used to implement storage for images and masks in TIcnsIcon.

TList
Handles the notification when an icon image is added to or removed from the list.
Pointer to the TIcnsRec with the icon type and raw image data for the notification.
Action performed for the icon image.
Creates and stores a entry in the list for the specified icon type and raw image.
Ordinal position in the list where the new entry was stored.
Type for the image data, mask, or alpha channel image in the raw data.
Raw image instance added to the container.
Provides indexed access to the icon images in the list by their ordinal position.
Ordinal position in the list for the property value.
Declares the shared icon for the TIcnsIcon type.
Implements a macOS Icon Resource file.

TIcnsIcon is a TCustomIcon descendant which implements a class used for macOS Icon resources. TIcnsIcon is similar to the .ICO format used on Windows platforms. An Icns Icon can store one or more images, which generally use the PNG image format. Standard icon sizes used in Icns Icon files include: 16x16, 32x32, 48x48, 128x128, 256x256, 512x512, and 1024x1024 pixels.

Gets the class reference used to create the shared image for the icon.
Reads icon data from the specified stream, and performs byte order conversion when needed.
Reads each of the icon resources from the specified stream, and adds them to the list of icon images.
Writes each of the icon resources in the list to the specified stream.

Does not write icons using the JPEG2000 image format in the current LCL version.

Constructor for the class instance.
Destructor for the class instance.
Gets the file extension(s) used for the icon type.
Always returns 'icns' in TIcnsIcon.
Checks whether the specified Resource Type name is valid for the icon type.
True when the uppercase value in ResourceType is 'ICNS'.
Resource type name checked in the method.
Implements a reference-counted shared image used for cursors.
Frees the handle for the cursor image.
Gets the class reference used to create a new cursor image in the Images property.
Class reference used to create images in the shared cursor image list.
Implements the image for a cursor, stored as an Icon.

Provides a HotSpot property with the coordinates in the cursor that is the point that interacts with other elements on the screen.

Constructor for the class instance.

Calls the inherited constructor on entry using the value in AInfo as an argument. AInfo contains the coordinates that are assigned to the HotSpot property.

TIconInfo instance with the hotspot information for the cursor image.
HotSpot
- the coordinates of the point to which the cursor refers, and which represents the 'active' position on the current form or canvas.
TCursorImage
- an Icon to be used to represent a cursor.
Gets the value for the HotSpot property.
Value for the property.
Gets the value for the CursorHandle property.
Value for the property.
Sets the value for the CursorHandle property.
New value for the property.
Gets the resource type identifier for the cursor image.

Returns RT_GROUP_CURSOR in TCursorImage.

RT_GROUP_CURSOR
ReleaseHandle
- free the handle used for the cursor Image.
Updates the HotSpot coordinate to the center point for the Current image in the cursor.
HotSpot
- the coordinates of the point to which the cursor refers, and which represents the 'active' position on the current form or canvas.
Handle for the cursor image.

Handle is a HCURSOR property in TCursorImage, and contains the handle used to identify the cursor image. The value for the property is provided by the GetHandle method.

Setting a new value for Handle causes the device context in Canvas to be freed, and the shared image for the icon is cleared. The UpdateHandle method is called to update the shared image using the new value for the property. If the shared icon contains image data, the value in Current is set to 0 (the first image in the internal list of images). Otherwise, Current is set to -1.

Changed is called to re-create the internal save stream for the shared image and signal the OnChange event handler (when assigned).

TSharedJpegImage
- a reference counted shared image of type JPEG.
Represents JPEG compression quality values.

TJPEGQualityRange is an alias to the TFPJPEGCompressionQuality type defined in the FCL. TJPEGQualityRange is the type used to implement the CompressionQuality property in TJPEGImage.

Represents JPEG read performance setting values.

TJPEGPerformance is an alias to the TJPEGReadPerformance type defined in the FCL. TJPEGPerformance is the type used to implement the Performance property in TJpegImage.

TJPEGImage
- a class for handling images stored in JPEG (compressed) format.

TJPEGImage is a TFPImageBitmap descendant which implements support for the JPEG (Joint Photographic Experts Group) image format. JPEG images are commonly used for storing digital photographs. They can represent detailed color photos using a high degree of compression, resulting in very efficient storage, though with some loss of quality.

JPEG image files normally have a file extension like: jpeg, jpg, jpe, or jfif.

The CompressionQuality and Performance properties can be used to set the balance between storage efficiency and picture quality. CompressionQuality is an Integer value between 1 and 100, with 100 representing the best quality. Performance is an enumerated variable with two states: BestQuality or BestSpeed (for compression).

Sets the value for the CompressionQuality property.
New value for the property.
Sets the value for the GrayScale property.
New value for the property.
Sets the value for the ProgressiveEncoding property.
New value for the property.
Initializes the FCL-compatible image reader for the image type.

InitializeReader is an overridden method used transfer property values specific to the JPEG image in AImage to the TFPCustomImageReader class instance in AReader. The following property values are stored to the corresponding properties in AReader:

- MinHeight
- MinWidth
- Performance
- Scale
- Smoothing

Image with values used to configure the reader class.
FCL-compatible image reader class updated in the method.
Initializes the FCL-compatible Image Writer for the image type.
Image with values used to configure the writer class.
FCL-compatible image writer class updated in the method.
Finalizes the FCL Image reader.
FCL-compatible image reader examined in the method.
Constructor for the class instance.

Create is the overridden constructor for the TJpegImage class instance, and calls the inherited constructor on entry. Creates sets the default values for properties, including:

Performance
  Set to jpBestQuality.
ProgressiveEncoding
  Set to False.
GrayScale
  Set to False.
Quality
  Set to 75.

TCustomBitmap.Create
Applies compression settings in the class instance to the image data.
Indicates if the stream contains a format supported for the image type.
True when Stream contains a valid image format for the image type.
TStream instance examined in the method.
Gets the file extension(s) supported for the image format.
Delimited list of file extensions supported for the image type.
Determine the compression quality for the image data.

Extreme compression can lead to loss of quality at the expense of a small file size.

The allowed range is 1..100, where 100 is best quality, and 25 is pretty awful.

Indicates if the image contains grayscale image data.
Minimum height allowed for the image when read using an FCL image reader.
Minimum width allowed for the image when read using an FCL image reader.
Indicates if progressive encoding is used for the image data.
Set for best quality or best speed.
A predefined scaling value applied to the image data.

Scale is a TJPEGScale property which contains one of the prefined scaling values applied to the raw image data. For instance:

jsFullSize
  Image is not scaled.
jsHalf
  Image is scaled to one-half of its width and height.
jsQuarter
  Image is scaled to one-quarter of its width and height.
jsEighth
  Image is scaled to one-eighth of its width and height.

Indicates if smoothing is applied to the raw image data.

Smoothing is a Boolean property which indicates if smoothing is applied to raw data in the image. Smoothing uses a low pass filter to remove high spatial frequency noise from a digital image.

The value in Smoothing is used in the InitializeReader method to configure the image reader used to load the raw image data. Set the value in Smoothing prior to calling methods which load the image content using an FCL-compatible image reader.

Declares the shared image for the TTiffImage type.
Represents units of measure used in TIFF image data.
Unit of measurement is unknown.
No absolute unit of measurement.

Used for images that may have a non-square aspect ratio, but no meaningful absolute dimensions.

Unit of measure is Inches.
Unit of measure is Centimeters.
Implements support for the TIFF (Tag Image File Format) graphic format.

TTiffImage is a TFPImageBitmap descendant which implements support for the TIFF (Tag Image File Format) image format.

It is a raster graphics image format. TIFF is widely supported by scanning, faxing, word processing, optical character recognition, image manipulation, desktop publishing, and page-layout applications. TIFF was created for use as a common image format for scanners. Various revisions to the specification have added grayscale and color support to the image format. It is a popular format for deep-color images.

TIFF images use .TIF or .TIFF file extensions, and the MIME types 'image/TIF' or 'image/TIFF'.

TTiffImage implements the class methods from the ancestor class which get FCL TFPCustomImageReaderClass and TFPCustomImageWriterClass instances, as well as the shared graphics class instance for the image format.

TTiffImage has properties which expose values for Baseline Tags in the image data, including:

- Artist
- Copyright
- DateTime
- DocumentName
- HostComputer
- ImageDescription
- Make
- Model
- ResolutionUnit
- Software
- XResolution
- YResolution

Scanner manufacturer or brand.
Scanner model.
Initializes the FCL-compatible image reader for the image.
Initializes the FCL-compatible image writer for the image.
Captures values from the image reader after loading an image.
Constructor for the class instance.

Create is the overridden constructor for the class instance, and calls the inherited constructor on entry. Create sets the default value for the Title property to include the class name, the LCL version, and the FPC version.

Get the delimited list of file extension(s) for files which support the image format.
In TTiffImage, the return value is: 'tif;tiff'.
Person who created the image.
Copyright notice for the image.
Date and time the image was created.
Name of the document from which the image was scanned.
The computer and/or operating system where the image was created.
A string that describes the subject of the image.
The scanner manufacturer.
The scanner model name or number.
The unit of measurement for XResolution and YResolution.
Name and version number for the software used to create the image.
Number of pixels in ResolutionUnits for the image width.
Number of pixels in ResolutionUnits for the image height.
Implements a reference-counted shared GIF image.
Implements an image using the GIF (Graphics Interchange Format) image format.

TGIFImage is a TFPImageBitmap descendant which implements support for the GIF (Graphics Interchange Format) image format. GIF images support up to 8 bits per pixel in the image data, and a color palette of up to 256 colors from the 24-bit RGB color space. While GIF images allow animation, the LCL implementation does not support the feature.

Updates the image when the reader has finished loading the image content.

Ensures that image properties discovered using the reader class are applied to the properties in the GIF image.

Calls the inherited method on entry. Copies values found in AReader to the following properties:

- Transparent
- Interlaced
- BitsPerPixel

FinalizeReader is called from the ReadStream method when the reader class has loaded the image content into a TLazIntfImage instance.

FCL-compatible reader for the image type.
Gets the class reference used to create the shared image in new class instances.
Constructor for the class instance.

Calls the inherited constructor on entry.

Determines if the specified Stream contains a valid GIF image format.
True when the stream contains the GIF87a or GIF89a signature.
TStream instance with values examined in the method.
Gets the file extensions used for the GIF image format.
Returns the value 'gif'
Indicates if the image is drawn with transparent pixels.
Indicates if the image uses the "venetian blind" effect during display.

TODO: Describe GIF89a. Two pass using alternating lines. Similar to progressive JPEG.

Number of bits needed to represent a pixel in the image.

BitsPerPixel indicates the color depth (or maximum number of colors) that can be represented in the image data.

Gets a filter string for files using the specified image class type.
Gets a string with the file extension used for the specified image class type.

Calls GetPicFileFormats to get the list which maps TGraphicClass (or descendent) references to a file extension.

GraphicExtension iterates over the values in the mapping list in reverese order, and compares the class name for the list item to the class name in GraphicClass. When a match is found, the GetFormatExt method for the item is called to get the return value for the function.

The return value is an empty string ('') when a mapping for GraphicClass is not found in the list.

File extension for the image type.
Graphic class used to determine the file extension.
Gets a file filter which can be used to select image files for the specified TGraphicClass instance.
File filter for the graphics class, or an empty string when the graphics class is not supported.
TGraphicsClass instance to locate in the supported graphic formats.
Gets the TGraphicClass instance used for images with the specified file extension.
TGraphicClass descendant for the image format.
File extension used to determine the TGraphicClass for an image format.
Specifies an object procedure used to process color value to color identifier map entries.
Checks whether a given Entry exists in a Map of color names.

IdentEntry checks whether a given Entry exists in a Map of color names.

A list of system Colors is specified as a look-up table of indices (Entry) and names (MapEntry).

This function checks that the value in Entry is within the permitted range, and returns the data pair Value, Name of the corresponding color in MapEntry.

If Entry is out of range the Result is False.

If Entry is out of the range [0..High(colors)] the Result is returned as False.
True if Entry was a valid index into the color look-up table.
Entry
- a numeric index into the table of colors.
MapEntry
- the record of Value, Name returned from the look-up table of Colors.
ColorToIdent - given a Color value, find its name (Ident) in the look-up table of Colors.
Returns True if there is a valid entry in the Colors look-up table.
the Color value to be sought in the look-up table.
Ident
- the name of the supplied Color as found in the look-up table of Colors.
IdentToColor
- given a color identifier (name) returns the color value.
Returns True if Ident is part of a valid entry in the look-up table of Colors.
Ident
- the supplied name for the required Color.
The Color returned from the look-up table, with the name supplied in Ident.
Finds the position in the color identifier map for the specified value.

ColorIndex is a

Boolean function used to determine if the color value specified in

Color exists in the color value to name identifier map.

ColorIndex iterates over the values in the Colors constant to find an element in the array with the value specified in Color. The position for the value is assigned to the Index output parameter. The return value is True when a value is located in Colors. Otherwise, the return value is False. The value in Index is not significant when the return value is False.

True when the color value exists in Colors.
Color value to locate in Colors.
Position in Colors where the color value was found.
SysColorToSysColorIndex
- if Color is one of the system colors, returns the Index of the system color.
If Color is not a system color, returns -1.
Returns the Index value of the Color if it is a system color, otherwise returns -1
The Color to examine in the routine.
Converts a TColor value to an RGB color constant.

ColorToRGB ensures that TColor values for special and system colors remove the non-RGB values in the constant.

LongInt value representing the specified color.
TColor value converted in the method.
ColorToString
- given a color value, returns a corresponding color name like 'Green'
Returns the name of the color, expressed as a string (like 'Green').
The Color to examine in the routine.
StringToColor
- given a color name like 'clBlue', returns the corresponding color value.
Returns the color corresponding to the name in String S.
S
- the name of the required color, expressed as a string.
Converts a color name, like "clBlue", to a TColor value with an optional default value when the color name does not exist.
Executes the specified procedure for each of the non-deprecated Color names defined for the platform.
InvertColor
- returns the complementary color to the supplied value - helps to produce a 'negative' image.
Returns the inverse of the original color (i.e. a 'negative' effect).
AColor
- the original color for processing.
DecColor
- decrease the component RGBs of a color by the quantity specified (usually results in a darker color overall).
Returns a copy of the original color, decremented by a specified amount.
AColor
- the original color for processing.
AQuantity
- the amount by which the color is to be changed.
Indicates whether the specified color reference is one of the system colors.

Returns True when AColor has value greater than or equal to the value in the SYS_COLOR_BASE constant.

SYS_COLOR_BASE
True when AColor is a system color.
TColorRef value examined in the routine.
Finds the Blue component of the supplied color.

Does not work with system color values.

Returns the Blue component of the color specified in RGB.
The color for processing, expressed as a RGB value.
Finds the Green component of the supplied color.

Does not work with system color values.

Returns the Green component of the color specified in RGB.
The color for processing, expressed as RGB.
Finds the Red component of the supplied color.

Does not work with system color values.

Returns the Red component of the color specified in RGB.
The color for processing, expressed as RGB.
Combines the values for Red, Green and Blue into a TColor value.
TColor value for the specified color components.
Byte with the Red color component.
Byte with the Green color component.
Byte with the Blue color component.
RedGreenBlue
- decomposes a composite color into its component Red, Green and Blue values.

Does not work with system color values.

The color for processing, expressed as RGB.
The Red component of the color defined in RGB.
The Green component of the color defined in RGB.
The Blue component of the color defined in RGB.
Converts a TFPColor value to a Cardinal color reference used in API system color constants.
FPColorToTColor
- converts a color specified as a FPColor to a color of type TColor.
Returns the color specified in FPColor as a color of type TColor.
The color for processing, expressed as a FPColor.
TColorToFPColor
- converts a color of type TColor to one specified as a

FPColor
.

Does not work with system color values.

Returns the color specified as a FPColor.
c
- the supplied color specified as type TColor.
Calls the specified procedure for each of the character set names in FontCharsets.

Not used in the current LCL implementation.

Converts the specified numeric font identifier to its representation as a string.
Converts the specified string value to the numeric font identifier for the value.
Gets font data for the specified font handle.

Values from DefFontData are assigned as the default return value for the routine. No additional actions are performed in the routine when Font contains 0 (for an unassigned font handle). When the font handle is valid, the following members in the return value are updated:

- Name
- Height
- Style
- CharSet
- Pitch
- Orientation
- Handle

TFontData structure with values read in the routine.
Font handle with the logical font data read in the routine.
Gets the default TFontCharSet value for the platform.

Returns the value for the DEFAULT_CHARSET constant.

DEFAULT_CHARSET
Determines if the specified font name is a valid X Logical Font Description.

IsFontNameXLogicalFontDesc is a Boolean function used to determine whether the specified font name is a valid X Logical Font Description (XLFD).

True when the font name is a valid XLFD font name.
Font name with segments examined in the routine.
Gets a logical font record with values representing the specified XLFD font descriptor.

XLFDName contains the font descriptor examined in the function. Its value consists of delimited segments that contain the attributes for the font, including:

Registry
  Ignored.
Foundry
  Ignored.
FamilyName
  Font family.
WeightName
  Font weight.
Slant
  Italic, Reverse Italic, Oblique.
SetwidthName
  Normal, Condensed, Narrow, Wide, Expanded.
AddStyleName
  Orientation or rotation.
PixelSize
  Height in pixels.
PointSize
  Height in points.
ResolutionX
  Horizontal resolution in points.
ResolutionY
  Vertical resolution in points.
Spacing
  Monospace, Proportional, Character Cell (Fixed Pitch).
AverageWidth
  Average character width.
CharSetRegistry
  Ignored.
CharSetCoding
  Ignored.

Values read from the segments are converted, translated, and massaged into the values expected in the logical font record.

TLogFont instance with values for the XLFD font.
Font descriptor examined in the routine.
Gets the value for the specified segment in an XLFD font descriptor.
Value for the XLFD segment, or an empty string when not found.
XLFD font descriptor examined in the routine.
Ordinal position (starting at 0) for the requested segment in XLFDName.
Gets the family name for the typeface used in the XLFD font descriptor.

Parses a font name in XLFD format and extracts the FamilyName sequence with the typeface family name.

Typeface family name found in XLFDName.
XLFD font descriptor examined in the routine.
Replaces the specified XLFD segment value with the '*' wildcard.
Replaces the PixelSize, PointSize, ResolutionX, ResolutionY and AverageWidth segments in an XLFD font name with the '*' wildcard.
Replaces the spacing for a XLFD font descriptor format with a '*' wildcard.
Replaces the WeightName, Slant and SetwidthName segments in an XLFD font name with the '*' wildcard.
Checks whether an explicit value is assigned to XLFD segments controlling font height.
Parses the specified font name into X Logical Font Descriptor attributes.

Used in the implementation of the GTK2 widgetset to create font handles for logical fonts.

Specifies a procedure type used to load a graphic image from a clipboard format.
Specifies a procedure type used to save a graphic image to a clipboard format.
Specifies a function type which returns a HFONT handle for a system font.

TOnGetSystemFont is the type used to implement the OnGetSystemFont variable in the graphics unit.

TScreen
HFONT handle for the system font.
Indicates whether clipboard formats for graphic types have been registered for the application.
Address of the routine used to load a graphic from a clipboard format.
Address of the routine used to save a graphic to a clipboard format.
Address of the routine used to get the handle for the system font.
Examines values in the specified stream to determine if it contains a .BMP image.
True when the stream contains a valid .BMP signature at the required position.
TStream instance examined in the routine.
Examines values in the specified stream to determine if it contains a .XPM image.

Skip comments and searches for the 'static [const] [unsigned] char*' statement in the stream.

True when .XPM signature is found in the stream.
TStream instance examined in the routine.
Examines values in the specified stream to determine if it contains a .ICO image.
True when the .ICO signature is found in the stream.
TStream instance examined in the routine.
Examines values in the specified stream to determine if it contains a .CUR cursor image.
True when the .CUR signature is found in the stream.
TStream instance examined in the routine.
Converts an XPM image file into an array of PChar values.

Converts an XPM image file into an array of PChar values. The memory is allocated as one block, so freeing can simply be done using FreeMem. The data is just behind the array.

An XPM file can be included in a C source file, because it has a C syntax. In the compiled program it is simply an array of PChar. This function converts an XPM source file to the same array, by removing the comments and the string constant symbols.

Loads an XPM image resource into an array.

Loads an XPM image from the specified resource name into an array of PChar values. See XPMToPPChar for more information.

Pointer to the memory allocated for the XPM image resource.
Name of the XPM image resource loaded in the routine.
Converts an XPM image stored in the specified stream into an array of PChar values.

See XPMToPPChar for more info.

Reads the first line from an XPM PChar array which contains the width, height and number of colors for the XPM data.
LoadCursorFromLazarusResource
- loads a named cursor handle from the Lazarus Resource (.LRS).
Deprecated - technically a bitmap is created, not loaded.
Deprecated - technically a bitmap is created, not loaded.
Creates and loads a TGraphic instance using the specified instance handle and resource name.
Creates a TCustomBitmap instance with the content for the named Lazarus resource.

Used in the implementation of components, and the LCL, to get a bitmap image stored in a Lazarus resource. Typically used to load button glyphs and icons displayed on the component palette in the Lazarus IDE.

Bitmap instance created and loaded in the routine.
Handle for the Lazarus resource with the content for the bitmap.
Name for the RT_BITMAP resource loaded in the routine.
Creates and loads a Bitmap from a Lazarus Resource (.lrs) file.
Creates a TLazIntfImage instance for the specified raw image data, and returns the handles to the image and optional mask information.
True if the widgetset class was able to create handles using the raw image data.
Creates a Bitmap with the content from the specified TFPCustomImage instance.

Creates a temporary TLazIntfImage instance used to copy the image content in Img into the TBitmap instance in the return value.

TLazIntfImage
TBitmap instance created and loaded in the routine.
TFPCustomImage with the content copied into the return value.
Ensures that a Pattern Bitmap with the specified colors exists in the Pattern cache.

AllocPatternBitmap is a TBitmap function used to ensure that a bitmap with the specified colors exists in the internal pattern cache.

AllocPatternBitmap tries to locate a TPatternBitmap instance with the colors specified in colorBG and colorFG. If the requested Pattern Bitmap does not already exist, it is created and added to the pattern cache.

The return value is the TBitmap instance stored in the Bitmap property for the cached TPatternBitmap instance. No actions are performed if the Pattern cache has not been assigned; the return value is Nil in this situation.

Bitmap retrieved or created with the specified colors.
Background color for the Bitmap.
Foreground color for the Bitmap.
Contains display attributes for the current screen in an application.

ScreenInfo is a TScreenInfo variable which contains display attributes for the current screen in an application, including:

PixelsPerInchX
  Horizontal display density (Pixels Per Inch). Default is 72.
PixelsPerInchY
  Vertical display density (Pixels Per Inch). Default is 72.
ColorDepth
  Number of colors used in image data. Default is 24.
Initialized
  Default value is False.

Values in ScreenInfo are updated when an application initializes the widgetset classes used in the LCL interface.

ScreenInfo is used in the implementation of the ScaleX and ScaleY routines.

TScreenInfo
Variable used as the cache for Font resources.

FontResourceCache is a TFontHandleCache variable used as the cache for Font resources. FontResourceCache allows reference-counted font handles to be created or retrieved when the ReferenceNeeded method in TFont is called. Values in FontResourceCache are maintained when the FreeReference method in TFont is called.

Resources for FontResourceCache are allocated when the Graphuic.pp unit is initialized, and freed when the unit is finalized.

Variable used as the cache for Pen resources.
Variable used as the cache for Brush resources.
Array constant with TIdentMapEntry values for character sets in TFont instances.

Array elements contain TIdentMapEntry record instances which map the numeric identifier for a character set to its representation as a string value.

TIdentMapEntry
Creates a formatted debugger message with values from the TFontStyles set.

Return value contains the formatted set of font styles, with content like:

'fsBold,fsItalic,fsStrikeout,fsUnderline'
Message formatted for use in the debugger.
Set of TFontStyle values included in the formatted string.
Resizes the specified horizontal size from a given display density to the current screen PPI.

Multiplies the values in SizeX and the PixelsPerInchX member in ScreenInfo, and divides the product by the value in FromDPI. The return value is rounded to the nearest Integer value.

MulDiv
New horizontal size after scaling.
Size value scaled in the routine.
Original display density (Pixels per Inch).
Resizes the specified vertical size from a given display density to the current screen PPI.

Multiplies the values in SizeY and the PixelsPerInchY member in ScreenInfo, and divides the product by the value in FromDPI. The return value is rounded to the nearest Integer value.

MulDiv
New vertical size after scaling.
Size value scaled in the routine.
Original display density (Pixels per Inch).
Registers TPersistent classes for use in the RTL.

Register calls RegisterClasses to add the following persistent objects to the list of classes available in the RTL:

- TBitmap
- TPixmap
- TPortableNetworkGraphic
- TPortableAnyMapGraphic (When DisableLCLPNM is not defined)
- TJpegImage (When DisableLCLJPEGis not defined)
- TGIFImage (When DisableLCLGIF is not defined)
- TPicture
- TFont
- TPen
- TBrush
- TRegion

RegisterClass
Renews handles for Fonts, Pens, and Brushes.
Monitoring the progress of drawing a complicated Graphic.

TProgressEvent is a generic progress notification event which may be used by TGraphic classes with computationally intensive (slow) operations, such as loading, storing, or transforming image data.

Event parameters

Stage

Indicates whether this call to the OnProgress event is to prepare for, process, or clean up after a graphic operation.

If OnProgress is called at all, the first call for a graphic operation will be with Stage = psStarting, to allow the OnProgress event handler to allocate whatever resources it needs to process subsequent progress notifications. After Stage = psStarting, you are guaranteed that OnProgress will be called again with Stage = psEnding to allow you to free those resources, even if the graphic operation is aborted by an exception.

Zero or more calls to OnProgress with Stage = psRunning may occur between the psStarting and psEnding calls.

PercentDone | The ratio of work done to work remaining, on a scale of 0 to 100. Values may repeat or even regress (get smaller) in successive calls. PercentDone is usually only a guess, and the guess may be dramatically altered as new information is discovered in decoding the image. The value of this property could usefully be passed to a ProgressBar to show the user how drawing is progressing

RedrawNow

Indicates whether the graphic can be/should be redrawn immediately. Useful for showing successive approximations of an image as data is available instead of waiting for all the data to arrive before drawing anything. Since there is no message loop activity during graphic operations, you should call Update to force a control to be redrawn immediately in the OnProgress event handler. Redrawing a graphic when RedrawNow = False could corrupt the image and/or cause exceptions.

Rect | Area of image that has changed and needs to be redrawn.
Msg | Optional text describing in one or two words what the graphic class is currently working on. Ex: "Loading", "Storing", "Reducing colors", etc. The Msg string can also be empty. Msg strings should be resourced for translation, should not contain trailing periods, and should be used only for display purposes. (Do not use the construct: if Msg = 'Loading' then...)