TButtonGlyph.GetImageIndexAndEffect procedure

Member of TButtonGlyphpublicIn unit Buttons

Gets the index for a glyph image using a given state, and the effect used to draw it.

Declaration

pascal

procedure GetImageIndexAndEffect(State: TButtonState; APPI: Integer; 
 const ACanvasScaleFactor: Double; 
 out AImageResolution: TScaledImageListResolution; 
 out AIndex: Integer; 
 out AEffect: TGraphicsDrawEffect)

Arguments

`State`	Drawing state for the button glyph.
`APPI`	Pixels per inch for the scaled image resolution created for the glyph images.
`ACanvasScaleFactor`	Canvas scaling factor applied to the scaled image resolution.
`AImageResolution`	Returns the scaled image resolution with the glyphs images.
`AIndex`	Returns the index for the glyph image in the image resolution.
`AEffect`	Returns the graphic drawing effect needed for the glyph image with the specified state.

Description

GetImageIndexAndEffect is a procedure used to get the ordinal position for the image used to render the Glyph for the class instance. In addition, it returns the scaled imagelist (AImageResolution) for the specified display resolution (APPI) and the drawing effect (AEffect) for the button state (normal, disabled, hot, clicked, selected) requested by the State argument. In principle, the user can provide dedicated images for each state, but for simplicity usually only a single image is provided for the "normal" state. In this case the imagelist can generate the missing images based on the AEffect parameter. Whether this is done, however, depends on the value of the DrawEffectsEnabled property of the ButtonGlyph:

deeAlways: State-dependent images are always created from the normal image (for this particular glyph).
deeNever: No state-dependent images are generated from the normal image.
deeSystem: Queries the ThemeServices whether state-dependent images should be created from the normal image.
deeApplication: Uses the application-wide settings in TApplication.GlyphDrawEffectsEnabled (or TApplicationProperties.GlyphDrawEffectsEnabled) to decide whether state-dependent images should be created. While the deeAlways, deeNever and deeSystem are applied only to the current button, the deeApplication setting is applied to all buttons of the application.

State contains the current button state and determines which graphic drawing effect is used in AEffect. For example:

bsUp: Causes AEffect to contain gdeNormal for both enabled and disabled glyph effects.
bsDisabled: Causes AEffect to contain gdeDisabled for both enabled and disabled glyph effects.
bsDown: Causes AEffect to contain gdeNormal for disabled glyph effects, and gdeShadowed for enabled glyph effects.
bsExclusive: Causes AEffect to contain gdeNormal for both enabled and disabled glyph effects.
bsHot: Causes AEffect to contain gdeNormal for disabled glyph effects, or gdeHighlighted for enabled glyph effects.

GetImageIndexAndEffect examines values in the ExternalImages, LCLGlyphResourceName, and Images properties (in that order) to determine the glyph image(s) used in the method.

ExternalImages is used (when assigned) to create the scaled image resolution returned in AImageResolution. AIndex is set to the ordinal position for the button state represented by the ExternalImageIndex, ExternalHotImageIndex, ExternalDisabledImageIndex, ExternalPressedImageIndex, or ExternalSelectedImageIndex properties.

If LCLGlyphResourceName has been assigned, values in LCLGlyphs are used to create the scaled image resolution returned in AImageResolution. LCLGlyphResourceName is used to get the value for AIndex, and AEffect is set to the graphic drawing effect indicated in State.

Finally, the Images property is used (when assigned) to create the scaled image resolution returned in AImageResolution. Images contains the cached image (s) created from the Glyph property. Images may contain as many as 5 distinct bitmaps (as defined in TNumGlyphs) representing the corresponding button states. AEffect is set to the value needed to represent State when DrawEffectsEnabled is enabled. AIndex is set to the image index calculated for button draw states when the glyphs were added to the image cache.

GetImageIndexAndEffect is used in in the implementation of the Draw method in TButtonGlyph, and in the GetGlyphSize method in TCustomSpeedButton.

TButtonGlyph.GetImageIndexAndEffect procedure

Declaration

Arguments

Description

See also