Contains types and classes used to implement specialized buttons.

buttons.pp contains classes, types, and routines used to implements specialized button controls. It registers the following components on the Additional tab in the Lazarus IDE component palette:

TBitBtn
TSpeedButton

Enumerated type which defines the position for a glyph on a button.

TButtonLayout is an enumerated type which contains constants that define the position for a glyph on a button. It is used to implement the Layout property in TBitBtn and TSpeedButton classes. It is also used to control the layout of images drawn in the columns for TGrid and TStringGrid.

TCustomGrid TCustomStringGrid TGridColumn TGridColumnTitle.ImageLayout Image is drawn aligned to the left. Image is drawn aligned to the right. Image is drawn aligned to the top. Image is drawn aligned to the bottom. A set of constants to define the state of a SpeedButton.

TButtonState is an enumerated type with constants that define the drawing state for a button. TButtonState is the type used to implement the internal State member in TCustomSpeedButton. It is also used to access bitmap images in TButtonGlyph drawn for the corresponding state using its Draw method.

Draw the button in its up state. Draw the button in its disabled state. Draw the button in its down state. Draw the button as the only one down in its group. Draw the button when the mouse cursor is hovered over the control. Defines the range of values available to access button glyphs.

TNumGlyphs is an Integer range constant which defines the minimum and maximum number of glyphs available for buttons. TNumGlyphs is the type used to implement the NumGlyphs property in TButtonGlyph, TCustomBitBtn, and TCustomSpeedButton.

Enumerated type with transparency mode values for button glyphs.

TGlyphTransparencyMode is an enumerated type which contains values representing the transparency modes used for button glyphs. TGlyphTransparencyMode is the type used to implement the TransparentMode property in TButtonGlyph.

Transparency is defined in the glyph. Transparent is not used, as defined by the owner of the glyph. Glyph is drawn with transparency. Represents an image that can be attached to a button.

TButtonGlyph is a TObject descendant used to represent the image with the symbol or pictograph displayed on a button, or in a column in a grid. Use the properties and methods in the class to specify the image displayed in the glyph, and the display settings required for the image.

Images and ExternalImages are image lists with the content that can be displayed in the glyph. Glyph contains the bitmap, scaled to the necessary display density, used in the class instance. Width and Height represent the dimensions for the Glyph.

ShowMode determines when the image is displayed, just like its usage in TMenu and TMenuItem.

TransparentMode indicates whether the glyph image is drawn with transparency, as works in conjunction with the Transparent property in the parent control.

TButtonGlyph implements the IImageCacheListener interface used to provide support for cached images in TImageList. TButtonGlyph also implements the IUnknown interface to support the QueryInterface method and reference counting.

TButtonGlyph is the type used to implement the ButtonGlyph property in TCustomBitBtn and TCustomSpeedButton.

TMenu TMenuItem Gets the value for the ExternalImageIndex property. Value for the ExternalImageIndex property. Ordinal position in the array of image indexes accessed for the property value. Gets the value for the Height property. Value for the property. Gets the value for the NumGlyphs property. Value for the property. Gets the value for the Width property. Value for the property. Initializes values in the internal array of image indexes used in property values.

Sets all byte values in the storage for an internal array of image indexes to the value $FF. Called from the Create constructor, and when a new bitmap is assigned to the Glyph property.

Added in LCL version 2.3.0. Sets the value for the ExternalImageIndex property. Ordinal position in the array of image indexes updated with the new value for the property. New value for the ExternalImageIndex property. Sets the value for the ExternalImages property. New value for the property. Sets the value for the ExternalImageWidth property. New value for the property. Sets the value for the Glyph property. New value for the property. Sets the value for the NumGlyphs property. New value for the property. Sets the value for the ShowMode property. New value for the property. Removes the references to Images for the button states.

ClearImages is a procedure used to remove index references to Images used for button states in the glyph. ClearImages sets the values in an internal member to -1 to indicate that the image for the corresponding TButtonState is not used.

Removes the name for the LCL Glyph resource used in the class instance. Sets the value for the LCLGlyphName property. New value for the LCLGlyphName property. Implements the method from IUnknown. Interface identifier for the specified object. Object examined for the specified interface. Implements the method from IUnknown. Always contains -1. Implements the method from IUnknown. Always contains -1. Stores the specified Image list in the Images property.

Implements the IImageCacheListener interface method used to receive changes to the cached image list. Stores the image list specified in AImageList to the Images property.

Image list stored to the Images property. Sets the button state for the image in AIndex to the value specified in AImageIndex. Position of the Button state applied to the specified image. Position of the Image updated in the method. Indicates if the glyph image can be drawn for the button glyph.

CanShow is a Boolean function which indicates if the glyph can be drawn for the button glyph. The return value is determined by examining the value in the ShowMode property. Values in the TGlyphShowMode enumeration determine the return value using the following logic:

gsmAlways: Return value is True
gsmNever: Return value is False
gsmApplication: Uses the Application.ShowButtonGlyphs property to determine the return value
gsmSystem: Uses the value from SystemShowButtonGlyphs as the return value

The return value is always True at design-time.

Use CanShowGlyph to determine if an image is available to be drawn on the button.

True when the glyph can be displayed on the button. Determines if an image is available for the button glyph.

CanShowGlyph is a Boolean function used to determine if an image is available for the button glyph. The return value is True when an image has been specified using one of the following mechanisms (in the order of precedence):

Images is assigned and contains valid button state images
LCLGlyphName contains a non-empty resource name
ExternalImages is assigned and contains a valid ExternalImageIndex value

True when a glyph image is available. Performs actions needed when the glyph image has been changed for the class instance.

DoChange is a procedure used to performs actions needed when the glyph image has been changed for the class instance. DoChange signals the OnChange event handler (when assigned).

Provides a default implementation for the OnChange event handler.

GlyphChanged is procedure which provides the default implementation for the OnChange event handler. Sender is the TObject instance for the change notification, and normally receives a reference to the current TButtonGlyph class instance.

GlyphChanged ensures that the internal ImagesCache member is set to Nil, and the ClearImages methods is called to remove images stored in the Images property. When CanShow returns True, the internal ImagesCache member is re-populated and registered to listen for changes to the Glyph property.

GlyphChanged is assigned to the OnChange event handler when the class instance is created, and when a bitmap is assigned to the Glyph property.

Button glyph for the change notification. Sets the value for the TransparentMode property.

SetTransparentMode is a procedure used to set the value in the TransparentMode property to the specified TGlyphTransparencyMode value. SetTransparentMode ensures that the bitmap in the Glyph property is updated to use the same transparency mode.

SetTransparentMode is not the write access specifier for TransparentMode, which is a read-only property. Value stored in the TransparentMode property. Indicates the transparency mode used to render the glyph image.

TransparentMode is a read-only TGlyphTransparencyMode property used to indicate the transparency mode applied when the glyph image is drawn.

Use SetTransparentMode to change the value for the property.

Create - constructor for TButtonGlyph: frees the Images cache then creates a Glyph Bitmap.

If you drop a component on the form in the form editor, you don't need to add code to explicitly create it. The component is automatically created together with the the form, and destroyed when the form is destroyed.

However, if you create the component by code, don't forget to free it when it is no longer needed. Constructors allocate memory and system resources needed by the object. They also call the constructor for any sub-objects present in the class.

Destroy - destructor for TButtonGlyph: frees caches and calls inherited Destroy.

If you call Destroy for an object which hasn't been initialized yet, it will generate an error. Always use the Free method to deallocate objects, because it verifies that the object does not contain the value Nil.

Take the following precautions when creating your own Destroy method:

Declare Destroy with the override directive, because it is a virtual method.
Always call the inherited Destroy method as the last action in the destructor code.
An exception may be raised in the constructor if there is not enough memory to create an object, or something else goes wrong. If the exception is not handled inside the constructor, the object will be only partially built. In this case Destroy will be called, so your destructor must check if the resources were really allocated before the are released.
Remember to call Free for all objects created on the constructor.

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

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 image resolution for the specified display density and the drawing effect for the button State.

GetImageIndexAndEffect uses ThemeServices to determine if drawing effects are automatically applied to glyph images, and captures the effect in the AEffect output argument.

GetImageIndexAndEffect determines the image source and the ordinal position for the image used for the button glyph. ExternalImages and ExternalImageIndex are used (when assigned). The next available source is the resource name specified in LCLGlyphResourceName (when specified). Finally, the Images property is used (when assigned). When the image source has been determined, the correct image resolution for the value in APPI is selected and stored in AImageResolution. ImageIndexes is used to get the position for the image with the specified button State.

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

Draws the glyph for the button using the specified settings and state.

Draw is a method used to draw the glyph for the button using the target and configuration specified in the arguments. Draw is overloaded to provide a variant which uses a scaling factor for the glyph image.

Canvas is the TCanvas instance where the glyph is rendered.

Client is a TRectangle instance with the client coordinates for the drawing operation.

Offset is a TPoint instance which contains the offset where the glyph is drawn in the Client rectangle.

State contains the button drawing state and is used to get both the glyph image and graphic drawing effect applied in the method.

Transparent indicates if the glyph is draw transparently.

PPI indicates the display density for the image resolution requested in the method.

ScaleFactor is the canvas scaling factor applied when the image is drawn.

Images used for button glyphs can be loaded from three (3) different sources.

LCLGlyphResourceName property
ExternalImages property
Images property

By default, the LCL Glyph resource is used when the button is created. Setting values for the corresponding properties changes the source for the glyph image.

Draw calls GetImageIndexAndEffect to get the image resolution needed for the value in PPI, and the index for the image drawn in the method. The TScaledImageListResolution.Draw method is called to render the selected glyph in the resolution to the Canvas using the Client, Offset, and derived graphics drawing effect.

No actions are performed in the method when an bitmap has not been assigned to the Glyph property, when the coordinates in Client are invalid, or when an image resolution / image index was not found.

The return value is a TRectangle instance with the original value passed in Client. Please note, this is different than the Delphi VCL; it returns the text rectangle.

TScaledImageListResolution Rectangle where the glyph was drawn. Canvas where the glyph is rendered. Client coordinates for the drawing operation. Offset in the client coordinates where the glyph is drawn. Button state. True if the glyph is drawn transparently. Not used in the current implementation. Pixels Per Inch for the image resolution requested in the method. Canvas scaling factor used in the method. Updates the button glyph after changes to property values. The bitmap image drawn as the glyph on the button.

Glyph is a TBitmap property with the bitmap image drawn as the glyph for the class instance. The value in Glyph is created/loaded when a bitmap is assigned directly to the property, or when loaded from a Lazarus resource or stock icon.

Assigning a new TBitmap value to Glyph causes the reference in ExternalImages to be discarded. The GlyphChanged method is assigned to the OnChange event handler in the bitmap to track changes to the image. If the Bitmap contains multiple adjacent images (determined using Width and Height), the NumGlyphs property is updated to contain the number of glyphs stored in the bitmap. The Refresh method is called to update the button glyph following changes to its property values.

Indicates whether change notifications are suppressed while editing property values.

IsDesigning is a Boolean property which indicates whether change notifications are suppressed while editing property values for the button glyph. The default value for the property is False, as assigned in the Create constructor.

Set IsDesigning to True to prevent calls to the Refresh method following a change to the ShowMode property, or when getting/setting the image for the button Glyph. Controls which use TButtonGlyph, like TBitBtn and TSpeedButton, will update the property to indicate whether the ComponentState for the control includes the csDesigning enumeration value. This has the net effect of disabling OnChange notifications at design-time.

The number of glyphs available for button states.

NumGlyphs is a TNumGlyphs property which indicates the number of glyphs available for its button states. The default value for the property is 1 (the low value for the range), and indicates that a single image is used for all button states in the TButtonGlyph.

The value in NumGlyphs is updated when a TBitmap instance is directly assigned to the Glyph property, and when GetImageIndexAndEffect retrieves the Images and drawing effect(s) for a given display density (PPI).

Reading the value in NumGlyphs causes the ExternalImages property to be examined; when it is assigned, the value for the property is always 1 (corresponding to the ExternalImageIndex). Otherwise, the value in the internal member is used.

Changing the value in NumGlyphs causes the Refresh method to be called.

The list of available images for the button glyph.

Images is a read-only TCustomImageList property which contains the images available for the Glyph in the class instance. The values in Images come from ExternalImages (when an image list has been assigned to its button control). The values may come from the list of bitmaps loaded from the glyph resource with the name in LCLGlyphName.

ExternalImages (when assigned) is used as the source for the Images in the class instance. The images with the resolution needed for the display density (PPI) are scaled to the ExternalImageWidth and stored in Images. LCLGlyphName (when assigned) is used to retrieve a resource in LCLGlyphs when ExternalImages are unassigned.

See for more information about image retrieval for the button glyph with a given state.

Stores the standard LCL resource name used for the Glyph in the class instance.

LCLGlyphName is a String property used to store the name for the LCL resource used as the Glyph for the class instance. Changing the value in LCLGlyphName causes existing entries in Images and ExternalImages to be removed, and the OnChange event handler to be signalled. The Image lists are not modified when the property is set to an empty string ('').

LCLGlyphName normally contains a value like those in BitBtnResNames, and represents a standard resource name used in the LCL.

Contains a reference to an external list of images that can be used as the Glyph image,

ExternalImages is a TCustomImageList property with the list of images that can be displayed as a glyph for the class instance. ExternalImages represents an image list assigned to the Images property for a button control, like TBitBtn or TSpeedButton. The image list contains bitmaps displayed for the various states for an associated button; i. e. Up, Pressed, Hot, Disabled, or Selected. The image used for a given button state is indicated in the properties: ExternalImageIndex, ExternalHotImageIndex, ExternalDisabledImageIndex, ExternalPressedImageIndex, and ExternalSelectedImageIndex.

Values in ExternalImages are used when a glyph bitmap has not been allocated in the Glyph property. Setting a new value for ExternalImages causes the Glyph property to be cleared, and the OnChange event handler is signalled. Conversely, setting a value for the LCLGlyphName property causes the reference in ExternalImages to be discarded.

Bitmaps in ExternalImages (or Glyph) are stored in the Images property, and used in the GetImageIndexAndEffect method to determine the image resolution and bitmap used for the glyph and the button state.

Use ExternalImageWidth to specify the width of the images in the ExternalImages container.

Width for the images in the ExternalImages property.

ExternalImageWidth is an Integer property with the width for the images in the ExternalImages property. The property value is used to determine the image resolution needed for the Images displayed in the GetImageIndexAndEffect method.

Changing the value for the property causes the OnChange event handler to be signalled (when assigned).

Ordinal position for the bitmap in ExternalImages displayed when the button is Up (not pressed).

ExternalImageIndex is a Integer property with the ordinal position for the bitmap drawn on the control when the button is in the Up (not pressed) state. ExternalImageIndex is an indexed property which accesses the value stored in an internal array of image indexes for each of the button states. The property value contains the ordinal position in ExternalImages with the bitmap used for the button state. -1 indicates that an explicit value has not been assigned for the property.

Modified in LCL version 2.3.0 to use an internal array of button states for the property value. Ordinal position in ExternalImages for the image displayed when the button is Hot (hovered).

ExternalHotImageIndex is an indexed property which accesses the value stored in an internal array of image indexes for each of the button states. The property value contains the ordinal position in ExternalImages with the bitmap used for the button state. -1 indicates that an explicit value has not been assigned for the property.

Added in LCL version 2.3.0. Ordinal position in ExternalImages for the image displayed when the button is Disabled.

ExternalDiasabledImageIndex is an indexed property which accesses the value stored in an internal array of image indexes for each of the button states. The property value contains the ordinal position in ExternalImages with the bitmap used for the button state. -1 indicates that an explicit value has not been assigned for the property.

Added in LCL version 2.3.0. Ordinal position in ExternalImages for the image displayed when the button is Pressed (down).

ExternalPressedImageIndex is an indexed property which accesses the value stored in an internal array of image indexes for each of the button states. The property value contains the ordinal position in ExternalImages with the bitmap used for the button state. -1 indicates that an explicit value has not been assigned for the property.

Added in LCL version 2.3.0. Ordinal position in ExternalImages for the image displayed when the button is Selected (has focus).

ExternalSelectedImageIndex is an indexed property which accesses the value stored in an internal array of image indexes for each of the button states. The property value contains the ordinal position in ExternalImages with the bitmap used for the button state. -1 indicates that an explicit value has not been assigned for the property.

Added in LCL version 2.3.0. The width of the Glyph image.

Width is an Integer property with the width for bitmaps displayed in the class instance. When Images has been assigned, its Width is used as the property value. Otherwise, the property value is 0.

Width is used when a value is assigned to the Glyph property, and determines if multiple images are present in the bitmap loaded into the Images property.

The height of the glyph image.

Height is an Integer property with the height for bitmaps displayed in the class instance. When Images has been assigned, its Height is used as the property value. Otherwise, the property value is 0.

Height is used when a value is assigned to the Glyph property, and determines if multiple images are present in the bitmap loaded into the Images property.

Indicates the logic used to display the Glyph image for the class instance.

ShowMode is a TGlyphShowMode property which indicates logic used to display the Glyph image for the class instance.

The default value for the property is gsmApplication, and indicates that ShowButtonGlyphs in TApplication determines the visibility of the button Glyph. See for more information about TGlyphShowMode enumeration values and their usage in TButtonGlyph.

Changing the value for the property causes the Refresh method to be called at run-time (IsDesigning contains False).

Event handler signalled when the bitmap in Glyph has been changed.

OnChange is a TNotifyEvent property with the event handler signalled when the image used in the Glyph property is changed. OnChange is signalled from the DoChange method, and occurs after Glyph has been loaded using the resource or image lists available to the class instance.

TButtonGlyph provides a default implementation for the event handler in its GlyphChanged method.

TBitBtnKind - enumerated type of possible kinds of BitButtons.

TBitBtnKind - enumerated type of possible kinds of BitButtons. Values in TBitBtnKind are used to select the appropriate image displayed as the glyph for TBitBtn class instances. TBitBtnKind is the type used to implement the Kind property in TCustomBitBtn.

Uses a custom image assigned in the button. Uses the OK button image. Uses the CANCEL button image. Uses the HELP button image. Uses the YES button image. Uses the NO button image. Uses the CLOSE button image. Uses the ABORT button image. Uses the RETRY button image. Uses the IGNORE button image. Uses the ALL button image. Uses the NO TO ALL button image. Uses the YES TO ALL button image. TBitBtnKinds - set of TBitBtnKind.

Not used in the current LCL implementation.

TCustomBitBtn - the ancestor class for TBitBtn.

TCustomBitBtn is a TCustomButton descendant, and the ancestor for TBitBtn. It provides the interface used to display a button with a glyph (or image) and a caption. It performs an action when the button is clicked.

If you want to define your own bitbutton class, you should derive it from this class.

Gets the value for the Glyph property. Value for the property. Gets the value for the GlyphShowMode property. Value for the property. Gets the value for the NumGlyphs property. Value for the property. Perform a change notification when Images for the control are updated.

ImageListChange is a procedure used to perform a change notification when the Images for the control have been updated.

Sender is the TObject instance generating the change notification. ImageListChange compares Sender to the object in the Images property, and calls the GlyphChanged method when they are the same instance.

ImageListChange is assigned to the OnChange event handler in the internal TChangeLink member used in the class.

Object generating the change notification. Gets the storage specifier for the Glyph property.

IsGlyphStored is a Boolean function used to get the storage specifier for the Glyph property. The return value is True when an image has not already been assigned in the Action property, or in the TButtonGlyph constructed for the control. This ensures that the image is included in processing that occurs for the LCL component streaming mechanism.

True when the glyph image is stored in the LCL component stream. Sets the value for the Glyph property. New value for the property. Sets the value for the GlyphShowMode property. New value for the property. Sets the value for the Kind property. New value for the property. Sets the value for the Layout property. New value for the property. Sets the value for the Margin property. New value for the property. Sets the value for the NumGlyphs property. New value for the property. Sets the value for the Spacing property. New value for the property.

RealizeKind is a procedure used to load and configure properties for the control. RealizeKind ensures that the Glyph displayed on the control contains a valid image for the value in the Kind property. When Kind contains bkCustom, it is assumed that the image was assigned directly to the Glyph property. For all other values, the following logic is used to derive the Glyph image:

Call GetDefaultBitBtnGlyph to get a user-supplied bitmap for the glyph (when available).
Use ThemeServices to get a "stock" image supplied by the widget set (when available).
Use the graphic stored in Images at the position in ImageIndex (when assigned).
Load the Glyph image from a LCL resource for the specified Kind.

ForceDefaults indicates if default values are applied to properties in the control. When it contains True, the following properties are updated:

Caption
ModalResult
Default
Cancel

RealizeKind is called when the value in the Kind property is changed, and when the control has been Loaded using the LCL component streaming mechanism.

True if the default values for properties are used in the control. Sets the value for the DefaultCaption property.

SetDefaultCaption is the write access specifier for the DefaultCaption property. AValue contains the new value assigned to the property.

When AValue is True, and Kind contains a value other than bkCustom, the Caption property is updated to use the value returned from GetCaptionOfKind. This also causes the TextChanged method to be called when the Caption property is updated.

New value for the property. Gets the default Caption value for the button Kind. Default value for the Caption property. Enumeration value that identifies the kind of BitButton. Gets the value for the Images property. Value for the property. Sets the value for the Images property. New value for the property. Gets the value for the ImageIndex property. Value for the property. Sets the value for the ImageIndex property. New value for the property. Gets the value for the ImageWidth property. Value for the property. Sets the value for the ImageWidth property. New value for the property. An internal member which contains the TButtonGlyph instance for the control. Performs action when a new value is assigned to the Action property for the control.

ActionChange is overridden in TCustomBitBtn to ensure that values from the new action instance in Sender are stored to properties in the control. ActionChange is the routine which implements the OnChange event handler for the ActionLink in the control. It is signalled (from TControl) when a new value is assigned to the Action property, or when the control is loaded using LCL component streaming.

Sender is the new action instance for the event, or Nil when the value in Action has been removed (set to Nil).

CheckDefaults indicates whether existing properties values in the control are used as default values. When set to False, the values from the action instance are applied to the control. Values from the action may be used (when assigned) if the properties in the control are unassigned - even when CheckDefaults is True.

ActionChange calls the inherited method to update property values like Caption, Enabled, Hint, Visible, HelpContext and HelpKeyword. When Sender is a TCustomAction instance, the values in ImageIndex and Images are also updated with the values from the action (when assigned).

New action instance for the event. True to use existing properties as default values, False to use properties from the new action. Performs actions needed when the value in Glyph has been changed.

Ensures that the widget set class is notified of a change in the value for the Glyph property. Calls InvalidatePreferredSize and AdjustSize to resize the control for the new Glyph image.

Assigned to the OnChange event handler in the TButtonGlyph instance for the control, and called directly from the ImageListChange method.

TObject instance for the change notification. Gets the storage specifier for the Caption property. True when a value for the property is included in the LCL component streaming mechanism. Performs actions needed when the component has been loaded using LCL component streaming. Performs actions needed when a sub-component is added or removed in the class instance. Component for the notification message. Operation performed for the notification message. Handles the CM_APPSHOWBTNGLYPHCHANGED message for the control.

CMAppShowBtnGlyphChanged is a method used to handle the CM_APPSHOWBTNGLYPHCHANGED control message for the control. It ensures that the bitmap in Glyph is refreshed when the value in the GlyphShowMode property is set to gsmApplication.

TGlyphShowMode Control message handled in the method. Constructor for the class instance.

Create is the constructor for the class instance. Create calls the inherited constructor, and initializes the layout, style, spacing, and Button Glyph for the control.

TComponent.Create TCustomButton.Create Owner of the class instance. Destructor for the class instance.

Destroy is the overridden destructor for the class instance. It ensures that resource allocated for the internal button glyph and image change link are freed. It calls the inherited destructor prior to exiting from the method.

TComponent.Destroy Performs actions needed when the button is clicked.

Click is an overridden method in TCustomBitBtn. It ensures that the correct actions are performed based on the value in the Kind property. When Kind is set to bkClose, the non-nested parent form is closed for the following conditions:

ModalResult is set to mrNone, or
ModalResult is mrCancel and the parent form is displayed as a modal dialog.

If Kind has any other value, the inherited Click method is called to determine the ModalResult and signal the OnChange event handler (when assigned).

Click is called when the DialogChar method handles an accelerator key for the control, when the Action for the control is executed, and when a mouse click event is handled for the control.

TCustomButton.Click TButtonControl.Click TControl.Click Loads the Glyph image with the specified named from a resource instance. Resource name for the image loaded in the method. LoadGlyphFromLazarusResource - method for loading the glyph from a Lazarus resource file (.lrs). Name for the resource loaded from the Lazarus resource file. Loads a stock glyph image for the specified button identifier. Button identifier used to determine the image loaded in the Glyph. Indicates if the Glyph for the button can be displayed.

CanShowGlyph is a Boolean function which indicates if the Glyph for the button can be displayed. The return value contains the result from the CanShowGlyph method in the internal TButtonGlyph member.

AWithShowMode indicates whether the ShowMode property for the button glyph is examined in the method by calling the CanShow method in TButtonGlyph.

True when the Glyph image can be displayed for the control. Indicates if the ShowMode for the glyph is examined in the method. Contains the descriptive text displayed for the Bitmap button control.

Caption is a public TCaption property which contains the descriptive text displayed for the Bitmap button control. Assign a value to Caption when the Kind property is set to bkCustom. When Kind contains one of the other TBitBtnKind enumeration values, the Caption is normally set using the GetCaptionOfKind method.

Use DefaultCaption to determine if the value in Caption is the default one for the control.

TControl.Caption Indicates if Caption contains the default value for the button Kind.

Changing the property value to True causes a resource string with the caption text for the button ID to be assigned to the Caption property when Kind is not bkCustom.

Ordinal position for the image displayed when the button is Disabled.

DisabledImageIndex is a TImageIndex property with the ordinal position for the bitmap displayed on the button when it is Disabled. It refers to the position in the Images property where the associated image data is stored. The default value for the property is -1, and indicates that an explicit value has not been assigned to the property.

Added in LCL version 2.3.0. Bitmap with the Glyph displayed on the control.

Glyph is a TBitmap property with bitmap(s) displayed on the button control. The bitmap is stored internally in a TButtonGlyph instance that is populated when a glyph resource is used for image(s) on the control. A bitmap can be assigned directly to the property. Or, it can be loaded when the LoadGlyphFromResourceName, LoadGlyphFromLazarusResource, or LoadGlyphFromStock method is called.

Glyph can contain a bitmap with multiple adjacent images representing the states for the button control. Use ImageWidth to define the width for individual images in the combined bitmap. If the bitmap has a width that is larger than ImageWidth, it is split into separate bitmaps for use in the internal TButtonGlyph instance. Use ImageIndex, DisabledImageIndex, HotImageIndex, and PressedImageIndex to indicate which bitmap is used for the corresponding button state.

Unlike TCustomSpeedButton, SelectedImageIndex is not available in TCustomBitBtn; it cannot receive input focus, so a selected image is neither needed nor implemented. The number of glyph bitmaps available for the control.

NumGlyphs is a TNumGlyphs property with the number of images in the bitmap assigned to the Glyph property. The property value is read from and written to the internal TButtonGlyph instance for the control. Changing the value for the property causes the original image to be re-examined and split into separate images based on the width specified in the ImageWidth property.

Ordinal position for the bitmap displayed when the button control is hot (hovered).

HotImageIndex is a TImageIndex property with the ordinal position for the bitmap displayed on the button when it is hot (under the mouse cursor - hovered). It refers to the position in the Images property where the associated image data is stored. The default value for the property is -1, and indicates that an explicit value has not been assigned to the property.

Added in LCL version 2.3.0. Contains images available for the control.

Images is a TCustomImageList property with the images displayed for the various states used on the button control.

Ordinal position for the default bitmap displayed when the button control is up (not pressed).

ImageIndex is a TImageIndex property with the ordinal position for the bitmap displayed on the button when it is in its default state (up). It refers to the position in the Images property where the associated image data is stored. The default value for the property is -1, and indicates that an explicit value has not been assigned to the property.

Added in LCL version 2.3.0. Display width for the glyph image on the control. What kind of BitButton? Custom, OK, Cancel, Yes, No etc. Layout of button - Glyph at top, bottom, left or right. The margin to be left around glyphs. Ordinal position for the bitmap displayed when the button control is pressed (down).

PressedImageIndex is a TImageIndex property with the ordinal position for the bitmap displayed on the button when it is pressed (down). It refers to the position in the Images property where the associated image data is stored. The default value for the property is -1, and indicates that an explicit value has not been assigned to the property.

Added in LCL version 2.3.0. The spacing around the BitButton. Indicates the policy for showing or hiding the glyph image for the button. TGlyphShowMode TApplication.ShowMenuGlyphs A Button with a small image attached.

TBitBtn is a TCustomBitBtn descendant which provides the interface used to display a button with a glyph (or image) and a caption. It performs an action when the button is clicked.

TBitBtn sets the visibility for properties introduced in ancestor classes.

How To Use Standard Controls Event handler signalled when a key is down while the control has focus.

OnKeyDown differs from OnKeyPress in that the key may have already been down when the control received focus; with OnKeyPress the key needs to become pressed while the control has focus.

TWinControl.OnKeyDown Event handler signalled when a key is pressed while the control has focus.

OnKeyPress differs from OnKeyDown in that the key needs to become pressed while the control has focus; with OnKeyDown the key may have already been down when the control received focus.

TWinControl.OnKeyPress Event handler signalled when a key is released while the control has focus.

In OnKeyUp, the key may already have been up when the control received focus, or a pressed key may become released during the time the control has focus.

TWinControl.OnKeyUp Indicates if the control is visible on its parent.

The Visible property indicates the ability to see a visual control. If Visible is True, the control is shown, otherwise it is hidden. Calling Show sets Visible to True. Setting Visible to False is equivalent to calling the Hide method.

The Visible property does not depend on the visibility of a parent control. Use IsVisible method to consider this, and get the real visibility for a control in its parent container. TControl.Visible Links a TSpeedButton with a TAction instance. SetGroupIndex - stores the value of the index within the list of links. Sets the Checked state for the control in the action link. New value for the Checked state in the linked speed button control. Sets the image index in the control for the action link when enabled.

SetImageIndex is an overridden method used to change the selected image in the associated TSpeedButton control for the action link. SetImageIndex uses the value from IsImageIndexLinked to determine if the image can be changed by the action link. When IsImageIndexLinked returns False, no actions are performed in the method.

SetImageIndex accesses the internal TSpeedButton control for the action link, and sets its ImageIndex property to the ordinal position specified in Value.

TActionLink.SetImageIndex Ordinal position for the image selected in the speed button control. Determines whether the action link can update the image index for the associated control.

IsImageIndexLinked is an overridden Boolean function used to determine if the Action Link can update the image in its associated TSpeedButton control. The return value is True when the Action is derived from TCustomAction and the ImageIndex values in the TSpeedButton and the Action currently have the same values.

IsImageIndexLinked is called from the SetImageIndex method before updating the value in the ImageIndex for the TSpeedButton control.

TBasicActionLink.Action Returns True when the action is can update the image in the associated control. The ancestor for the TSpeedButton class.

TCustomSpeedButton is a TGraphicControl descendant, and the ancestor for TSpeedButton. If you want to define your own speed button class, you should derive it from TCustomSpeedButton.

A speed button is designed to automatically perform a process when it is pressed or clicked. The user can push the button to start an action or set a mode. When a user clicks on a speed button, focus is not shifted; a speed button never receives focus. The button may have a descriptive glyph (symbol or pictograph), and has state (checked, unchecked, Up, Down, Hovered, Selected, Disabled).

Gets the value for the Glyph property. Value for the property. Performs actions needed when the value in Images is changed. Gets the storage specifier for the Glyph property. True when a value for the Glyph property is included in the LCL component streaming mechanism. Sets the value for the ShowCaption property. New value for the property. Sends a message to the parent control when the value in AllowAllUp, GroupIndex, or Down is changed. Gets the value for the Transparent property. Value for the Transparent property. Sets the value for the Alignment property. New value for the Alignment property. Sets the value for the AllowAllUp property. New value for the property. Sets the value for the Glyph property. New value for the property. Sets the value for the Layout property. New value for the property. Sets the value for the ShowAccelChar property. New value for the property. Sets the value for the Transparent property. New value for the property. Handles the Control message passed when the button is pressed.

CMButtonPressed is a method used to handle a CM_BUTTONPRESSED control message received for the control. CMButtonPressed ensures that the Down property is set to False when another speed button with the same GroupIndex is pressed. AllowAllUp is updated and the control is redrawn.

No actions are performed in the method when the control in Message does not have the same GroupIndex value.

TLMessage instance examined in the method. Handles the Control message passed when the control is enabled. Gets the value for the Images property. Value for the property. Sets the value for the Images property. New value for the property. Gets the value for the ImageIndex property. Value for the property. Sets the value for the ImageIndex property. New value for the property. Gets the value for the ImageWidth property. Value for the property. Sets the value for the ImageWidth property. New value for the property. Internal member used to store the TButtonState for the control. Gets the TButtonGlyph used for the control. TButtonGlyph instance used for the control Gets the value for the NumGlyphs property. Value for the property. Performs actions needed when the value in the Glyph property has been changed. TObject instance for the change notification. Calculates the default height and width required for the control.

Calls MeasureDraw to gets the values for the variable parameters in PreferredWidth and PreferredHeight.

Please note that the WithThemeSpace parameter is NOT used in the current implementation. Width calculated for the control. Height calculated for the control. Not used in the current implementation. Performs actions needed when a Mouse Up message is received for the control.

DoMouseUp is an overridden method in TCustomSpeedButton. It re-implements the method from TControl and does not call the inherited method. DoMouseUp checks the flag values in ControlStyle. When csNoStdEvents is not included in the values, it calls the MouseUp method using Button and Message as arguments.

DoMouseUp is called when a LM_LBUTTONUP message is handled for the control.

TControl.MouseUp TControl.OnMouseUp TControl.DoMouseUp Mouse message examined in the method. Mouse button for the message. Calculates the Width, Height, and layout for the speed button and optionally renders the control.

Used in the implementation of the CalculatePreferredSize and Paint methods.

Performs actions needed for a mouse down event on the control.

MouseDown is an overridden method in TCustomSpeedButton. It calls the inherited MouseDown method on entry to signal the OnEditingDone event for the active control on the Parent form. It also updates the DragManager coordinates when a drag operation is already active.

No additional actions are performed in the method at design-time.

If the Left mouse button was pressed when the control is Enabled, Down is set to True (when needed) and the Action for the control is unchecked. An internal flag for a pending drag operation in MouseMove is set prior to exiting from the method.

TControl.MouseDown Button for the mouse event. Shift, Ctrl, or Alt modifier for the mouse event. Horizontal coordinate for the mouse pointer. Vertical coordinate for the mouse pointer. Performs actions needed for a mouse move message received for the control.

MouseMove calls the inherited method on entry to update the pointer position for the DragManager (when active) and to signal the OnMouseMove event handler (when assigned).

No additional actions are performed in the method at design-time.

if a drag operation has been started in MouseDown, the internal TButtonState for the control is updated to reflect the values in AllowAllUp and Down. When the button state has changed, the control is redrawn.

TControl.OnMouseMove TControl.MouseMove TControl.WMMouseMove Shift, Ctrl, or Alt modifier for the mouse move event. Horizontal coordinate where the mouse pointer was moved. Vertical coordinate where the mouse pointer was moved. Button for the mouse event. Shift, Ctrl, or Alt modifier for the mouse up event. Horizontal coordinate for the mouse pointer. Vertical coordinate for the mouse pointer. Performs action needed when a sub-component is added or removed for the control. Component for the notification message. Action performed for the notification message. Updates the state for the control, and paints it to the control Canvas.

Paint is an overridden method in TCustomSpeedButton used to draw the control to its Canvas.

Paint calls UpdateState to ensure that the internal TButtonState for the control is updated to reflect its current condition. No additional actions are performed in the method when a bitmap has not been assigned in the Glyph property.

When a Glyph is available, additional actions are performed to draw the control to its client rectangle. MeasureDraw is called to draw the background, Glyph, and Caption using the layout and state for the control.

Paint calls the inherited method prior to exit to signal the OnPaint event handler (when assigned).

TGraphicControl.Paint Paints the background for the control to the specified rectangle.

PaintBackground is a method used to draw the background for the speed button control on its Canvas. When Transparent is True and the theme element has transparent areas, the value in Color is used to fill the drawing area in PaintRect.

The DrawElement method in ThemeServices is called to render the drawing area to the Canvas for the control. PaintRect is updated following the drawing operation with the reduced content rectangle (the button surface without borders/edges) needed for the control.

PaintBackground is called when the MeasureDraw method is used to render the control. The adjusted rectangle is later used in the method to calculate the drawing areas for the glyph bitmap and caption text.

ThemeServices TGraphicControl.Canvas Rectangle where the control is drawn. Sets the value for the Down property. SetDown - specifies the Boolean value of Down (i.e. whether or not button was pressed) New value for the property. Sets the value for the GroupIndex property. SetGroupIndex - specifies the value of the Group Index. New value for the property. Sets the value for the Flat property. SetFlat - specifies whether or not the button is displayed Flat New value for the property. Sets the value for the Margin property. SetMargin - specifies the size of the margin New value for the property. Sets the value for the NumGlyphs property. SetNumGlyphs - specifies the number of glyphs. New value for the property. Sets the value for the Spacing property. SetSpacing - specifies the spacing between buttons. New value for the property.

Used by SetTextBuf to store a text string rather than performing read/write using a PChar buffer

Value stored in the method. Updates internal members used to track state changes in the control. UpdateState brings the state up to date, implementing any pending changes, and rendering non-valid if InvalidateOnChange is True. Indicates if the control is invalidated following a change in state. Gets the theme element details used to draw the control.

Called from the MeasureDraw method. The return value can be an enumeration value from either TThemedToolBar or TThemedButton depending on the value in the Flat property.

When Flat is True, one of the following TThemedToolBar values is returned:

ttbButtonDisabled: Used when IsEnabled is False.
ttbButtonChecked: Used when Down is True and the mouse pointer is not over the control.
ttbButtonCheckedHot: Used when Down is True and the mouse pointer is hovered over the control.
ttbButtonPressed: Used when Down is False and the mouse is hovered over a grouped button control.
ttbButtonHot: Used when Down is False and the mouse is hovered over a non-grouped button control.
ttbButtonNormal: Default state for the control.

When Flat is False, one of the following TThemedButton values is returned:

tbPushButtonDisabled: Used when IsEnabled is False.
tbPushButtonPressed: Used when a grouped button control is Down.
tbPushButtonHot: Used when a grouped button control is under the mouse pointer.
tbPushButtonNormal: Default state for the control.

Theme element detail used to draw the control in its current state. Returns True if the mouse pointer is in the display area for the control.

The property value is updated in the MouseEnter and MouseLeave methods when the mouse pointer enters or leaves the control area. The property value is used in the UpdateState method to determine if the button control is drawn using the "up" or "hot" states. It is used in the GetDrawDetails method to selected the theme element detail needed to draw the control in its current state.

Performs action when a new value is assigned to the Action property for the control.

ActionChange is overridden in TCustomSpeedButton to ensure that values from the new action instance in Sender are stored to properties in the control. ActionChange is the routine which implements the OnChange event handler for the ActionLink in the control. It is signalled (from TControl) when a new value is assigned to the Action property, or when the control is loaded using LCL component streaming.

Sender is the new action instance for the event, or Nil when the value in Action has been removed (set to Nil).

ActionChange calls the inherited method to update property values like Caption, Enabled, Hint, Visible, HelpContext and HelpKeyword. When Sender is a TCustomAction instance, the values in GroupIndex, ImageIndex, and Images are also updated with the values from the action.

TControl.ActionChange New action instance for the event. True to use existing properties as default values, False to use properties from the new action. Performs actions needed when LCL component streaming is completed for the control.

Loaded is called by the LCL streaming system when a root component was completely read from a stream and all properties and references to other objects have been resolved. Descendents of TComponent should override this method to perform additional processing when all published properties have been set from values obtained from the LCL component stream.

Application programmers should never call Loaded directly; this is done automatically by the LCL streaming system.

TComponent Gets the size of the glyph within the specified PaintRect.

GetGlyphSize is a TSize function used to get the size of the glyph within the client rectangle specified in the PaintRect argument. The return value contains the width (in CX) and the height (in CY). The member values are retrieved from a scaled image resolution for the glyph bitmaps in ButtonGlyph. The values are scaled to the client rectangle using the PixelsPerInch for the Font and the Canvas scaling factor for the control.

Use GetTextSize to get the width and height or the Caption displayed on the control.

GetGlyphSize is used in the implementation of the MeasureDraw method.

TSize instance with the width (CX) and height ( CY) for the glyph . True if the control is drawing, False if the control is measuring its components. Client rectangle for the control. Gets the size of the text within the specified PaintRect.

GetTextSize is a TSize function used to get the dimensions for the Caption text for the control.

GetTextSize removes Ampersand (&) characters in Caption prior to calculating the dimensions for the text using the TextStyle for the control Canvas. The value in PaintRect is updated with the calculated dimensions. The X and Y members in the return value contain the width and the height for the text using the Font for the control. Both member values are set to 0 when ShowCaption is False or Caption contains an empty string ('').

GetTextSize is called from the MeasureDraw method.

TGraphicControl.Canvas TControl.Caption TControl.Font TSize instance with the dimensions for the caption text. Not used in the current implementation. Display rectangle for the control; updated in the method with the calculated text dimensions. Draws the glyph image on the canvas at a given offset in the specified client rectangle.

Uses the internal TButtonGlyph instance for the control (when assigned) to access its Draw method. The PixelsPerInch setting in Font and the Canvas scaling factor for the control are used to scale the image.

The return value is a TRect instance with are needed to draw the glyph image on the the specified canvas. Its member values are set to 0 (zero) when a TButtonGlyph instance has not been assigned by setting a Glyph bitmap for the control.

TRect instance used to draw the glyph bitmap. Canvas where the control is glyph is drawn. Client rectangle for the drawing operation. Offset into the client rectangle where the glyph is drawn. Button state drawn for the control. True if the glyph image is drawn with transparency. Not used in the current implementation. Create - constructor for TCustomSpeedButton: calls inherited Create and initializes many defaults and properties.

Create is the constructor for TCustomSpeedButton. It calls the inherited Create method and sets the default values for properties in the class instance. Among the properties set are Glyph, the initial bounds, control style, layout, color, caption and mouse responses.

TGraphicControl.Create Owner of the class instance. Destroy - destructor for TCustomSpeedButton: frees Glyph then calls inherited Destroy. Destroy is the destructor for TCustomSpeedButton. It frees resources allocated to the Glyph property, and calls the inherited Destroy method. TGraphicControl.Destroy Gets the speed button with the same GroupIndex that has its Down property set.

FindDownButton locates a TCustomSpeedButton instance on the parent form which has the same GroupIndex and its Down property is set to True. FindDownButton visits each of the child controls on the parent form to find the speed buttons in the list of controls.

The return value contains the TCustomSpeedButton instance located. The return value is Nil if another speed button does not exist, is not in the same group, or is not Down.

No actions are performed in the method if the Down property in the current class instance is set, or when GroupIndex is 0 (zero). The return value is the current class instance in this circumstance.

TControl.Parent The speed button in the group which is down. Loads the image for the Glyph with the specified name from a resource instance. LoadGlyphFromLazarusResource - method for loading a glyph from a Lazarus Resource file (.lrs). Horizontal alignment for the text displayed on the button control.

Alignment is a TAlignment property with the horizontal alignment for the Caption displayed on the button control. Alignment is used (along with UseRightToLeftReading) in the MeasureDraw method to set the text flags needed to measure / draw the Caption> for the control.

The default value for the property is taCenter, and causes the Caption to be centered in the text area on the control. Use taLeft to left-align the Caption in the text area. Use taRight to right-align the Caption for the control. Changing the value for the property causes the control to be redrawn.

Set the value in ShowCaption to True to display the Caption for the control.

Use the Layout property to control the placement of the image relative to the text value displayed on the control.

Use the Align property to specify the side on the parent control to which the speed button is aligned, or to specify that custom Anchors are used for positioning and sizing.

TControl.Align TControl.Anchors TControl.Caption TControl.UseRightToLeftReading TAlignment Indicates if all buttons in a group can be in an up state.

AllowAllUp is a Boolean property which indicates whether all speed buttons with the same GroupIndex value can be in the "up" state. The default value for the property is False, and means that one of the grouped speed buttons must have its Down property set to True when GroupIndex has a non-zero value.

Changing the value for the property causes a button pressed event to be sent to the Parent control (when assigned) and the Down property is toggled and updated for the new property value.

Set GroupIndex to a value other than 0 (zero) to use AllowAllUp when a mouse button or an accelerator key is handled for the control.

TControl.Parent The background color for the control.

The default value for the property is clBtnFace in TCustomSpeedButton.

If the color is clDefault, the result will need to be passed through GetDefaultColor to resolve clDefault to a TColor value. Convenience routines which obtain the color by resolving clDefault and ParentColor are also provided in the GetColorResolvingParent and GetRGBColorResolvingParent methods.

TControl.Color TControl.ParentColor TControl.GetDefaultColor TControl.GetColorResolvingParent TControl.GetRGBColorResolvingParent Ordinal position for the image displayed when the control is disabled.

DisabledImageIndex is a TImageIndex property with the ordinal position for the bitmap displayed when Enabled is set to False. It indicates the position in Images or Glyph where the image data is stored. The default value for the property is -1, and indicates that an explicit value has not been assigned for the property.

The property value is read from and written to the image index members in ButtonGlyph.

Added in LCL version 2.3.0. Indicates if the button has been set to the Down state.

Down is a Boolean property which indicates whether the button control is in the down (or pressed) state. The default value for the property is False. Changing the value for the property causes the control to be redrawn.

The value in Down is toggled in the DialogChar method when ShowAccelChar has been enabled and the accelerator key in Caption is received for the control. This also calls the Click method to execute the OnClick event handler or the action for the control.

Down is used in the UpdateState method, along with GroupIndex and MouseInControl, to determine the current TButtonState for the control.

Indicates whether the button is displayed with a Flat (non-relief) appearance.

Set Flat to True to draw the control without relief, elevation, or a three-dimensional appearance. The default value for the property is False. Changing the value for the property causes the control to be redrawn.

Flat is used in the GetDrawDetails method to select the theme element details applied to the control for its current state. When set to False, TThemedButton element details are used. When set to True, TThemedToolBar element details are used. See GetDrawDetails for more information about the values used for specific button states.

The bitmap with the glyph image(s) displayed for button states.

Glyph is a TBitmap property with the image drawn for the button control. Read and write access to the property value are redirected to an internal TButtonGlyph instance for the control. This allows a single image to be specified for Glyph, or multiple bitmaps for various button states using the Images property.

Changing the value for the property cause the control to be redrawn.

Identifies the group to which the speed button control belongs.

GroupIndex is used with AllowAllUp and Down to determine if the button state can be changed within the related group of controls. All buttons on the Parent control with the same value in GroupIndex are treated as a single group. The default value for the property is 0 (zero), and indicates that an explicit value has not been assigned for the property.

Set GroupIndex to a positive non-zero value to enable AllowAllUp checking when a mouse button event or an accelerator key is handled for the control.

Ordinal position for the glyph bitmap displayed when the mouse is hovered over the button control.

HotImageIndex is a TImageIndex property with the ordinal position for the bitmap displayed when the mouse cursor is hovered over the control. The default value for the property is -1, and indicates that an explicit value has not been assigned for the property.

The property value is read from and written to the image index members in ButtonGlyph.

Added in LCL version 2.3.0. List of images available for use as state glyphs on the control.

Provides an alternate way to specify images (individually) as opposed to multiple adjacent bitmaps in Glyph.

Use ImageIndex to specify the ordinal position in Images for the glyph bitmap displayed on the control.

Use Glyph to access an image in the TButtonGlyph assigned to the control.

Ordinal position for the glyph bitmap displayed when the button is in its up state.

ImageIndex is a TImageIndex property with the ordinal position for the glyph bitmap displayed when the button is in its up state. The default value for the property is -1, and indicates that an explicit value has not been assigned for the property.

The property value is read from and written to the image index members in ButtonGlyph.

Added in LCL version 2.3.0. Width for the glyph bitmap displayed on the control. Indicates the alignment of the glyph bitmap relative to the caption for the control. Space around the Glyph bitmap and Caption for the control.

A value of -1 centers the content. If Spacing is -1 too then there is the same space on the left, between the glyph and caption, and on the right.

The number of glyph bitmaps available for the control. Ordinal position for the glyph bitmap displayed when the button is in a pressed (down) state.

PressedImageIndex is a TImageIndex property with the ordinal position for the glyph bitmap displayed when the Down property is True. The default value for the property is -1, and indicates that an explicit value has not been assigned for the property.

The property value is read from and written to the image index members in ButtonGlyph.

Added in LCL version 2.3.0. Ordinal position for the glyph bitmap displayed when the button is selected.

SelectedImageIndex is a TImageIndex property. The default value for the property is -1, and indicates that an explicit value has not been assigned for the property.

Added in LCL version 2.3.0. Indicates if the accelerator key (shortcut) is displayed in the Caption for the control.

ShowAccelChar is a Boolean property which controls whether an accelerator key in Caption is displayed as an underlined character. The accelerator (or shortcut) key in Caption is identified by the '&' character, with the subsequent character used as the accelerator key.

When set to False, the underlined character is not drawn in Caption and the accelerator key is not handled in the DialogChar method.

The default value for ShowAccelChar is True. Changing the value for the property causes the control to be redrawn.

TControl.Caption Indicates if the Caption for the speed button is displayed.

The default value for the property is True. Changing the value for the property causes the control to be redrawn.

ShowCaption is used in the MeasureDraw method. When set to True, the text extent for Caption is displayed using the Font and Layout for the control. It is also used in the GetTextSize method when the text extent is calculated.

Spacing between the Glyph bitmap and the Caption for the control.

If Spacing is -1 and Margin is -1 then the glyph and the Caption are centered, with the same amount of unused space on each side of the control. If Spacing is -1 and Margin is not -1 then Spacing will fill the remaining unused space.

Indicates if the control is drawn with transparency.

Transparent is a Boolean property which indicates whether the control is drawn with transparency. Changing the value for the property causes the ControlStyle property to be updated to include or exclude the csOpaque flag as needed, and the control is redrawn. The property value is read from and written to the TransparentMode property in ButtonGlyph.

The property value is passed as an argument to the DrawGlyph method when MeasureDraw is executed. When set to False, the PaintBackground method fills the display area with the background Color when theme element details have transparent areas.

A Button used to represent states (checked or unchecked).

The Speed Button is designed to automate a process when it is selected. An user pushes a button to start an action or set a mode.

When a user clicks on a SpeedButton focus is not shifted; a Speed Button never gets focus. The button may carry an descriptive glyph, and has a state (checked or not, etc).

How To Use Standard Controls Indicates the bi-directional text mode for the control. String with the caption displayed for the control.

Gets caption as a text-string (GetText), or stores the new caption (SetText). Shows flag if caption is stored (IsCaptionStored).

By default, the Caption appears the same as the control Name in the Object Inspector, and the developer needs to set it explicitly to some new text.

The VCL implementation relies on the virtual Get/SetTextBuf to exchange text between widgets and VCL. This means a lot of (unnecessary) text copies.

The LCL uses strings for exchanging text (more efficient). To maintain VCL compatibility, the virtual RealGet/SetText is introduced. These functions interface with the LCLInterface.

The default Get/SetTextBuf implementation calls the RealGet/SetText. As long as the Get/SetTextBuf isn't overridden Get/SetText calls RealGet/SetText to avoid PChar copying.

To keep things optimal, LCL implementations should always override RealGet/SetText. Get/SetTextBuf is only kept for compatibility.

TControl.Caption Indicates if the control is visible on its parent.

The Visible property indicates whether a visual control is displayed. If Visible is True the control is shown, otherwise it is hidden. Calling Show sets Visible to True. Setting Visible to False is equivalent to calling the Hide method.

The Visible property does not use the visibility for the parent control. Use the IsVisible method to get the realized visibility. TControl.Visible TGetDefaultBitBtnGlyph - generic method to return a default Bit Button Glyph of specified Kind. Address of the routine used to get default glyphs for TBitBtn instances.

GetDefaultBitBtnGlyph is a TGetDefaultBitBtnGlyph variable with the address for the routine used to get the default glyphs for TBitBtn instances in the application.

Kind is a TBitBtnKind argument that identifies the content needed in the bitmap returned from the function.

Handled is a Boolean value which indicates if the TBitmap instance was successfully created and loaded in the routine.

Create a function using the signature in TGetDefaultBitBtnGlyph, and assign it the variable to use custom bitmaps for the glyphs in TBitBtn. For example:


// provides Ok and Cancel glyphs
function GetCustomBitBtnGlyph(Kind: TBitBtnKind; Handled: Boolean): TBitmap;
begin
  if Kind in [bkOK, bkCancel] then
  begin
    Result := TBitmap.Create;
    case Kind of
      bkOk: Result.Assign(MyOkGlyph);
      bkCancel: Result.Assign(MyCancelGlyph);
    end;
  end
  else
    Result := Nil;

  Handled := (Result <> Nil);
end;

// assign the routine to the GetDefaultBitBtnGlyph variable
Buttons.GetDefaultBitBtnGlyph := @GetCustomBitBtnGlyph;

GetLCLDefaultBtnGlyph gets the LCL default button glyph for the specified button Kind. Loads a bitmap from a named resource into the specified Glyph.

LoadGlyphFromResourceName is a procedure used to load a bitmap into the specified Glyph from a named resource. AGlyph is the TButtonGlyph where the bitmap is stored. Instance is a THandle for the resource instance accessed in the routine. AName contains the name for the resource loaded in the routine.

LoadGlyphFromResourceName calls CreateBitmapFromResourceName to retrieve a TCustomBitmap using the specified handle and resource name. The bitmap is assigned to the TButtonGlyph in AGlyph. When AName is an empty string (''), the Glyph image in AGlyph is set to Nil.

LoadGlyphFromResourceName is used in the implementation of the LoadGlyphFromResourceName method in both TCustomBitBtn and TCustomSpeedButton.

Button glyph updated in the routine. Handle for the resource. Resource name loaded in the routine. Loads the named glyph image from a Lazarus Resource file.

LoadGlyphFromLazarusResource loads a glyph image with the specified name from a Lazarus Resource file (.lrs). Used in the implementation of the LoadGlyphFromLazarusResource method in both TCustomBitBtn and TCustomSpeedButton.

Class instance where the bitmap for the glyph is stored. Resource name loaded in the routine. Loads the bitmap for the specified Glyph using the image for the specified button identifier.

LoadGlyphFromStock is a procedure used to load a TBitmap into the AGlyph argument with the image used for the button identifier in idButton. LoadGlyphFromStock calls the GetButtonIcon routine to load the graphic image for the button identifier.

Used in the implementation of the LoadGlyphFromStock method in both TCustomBitBtn.

TButtonGlyph where the bitmap is stored. Button identifier for the image loaded in the routine. Gets the default caption for the specified button identifier. Gets the default icon for the specified button identifier. Gets a bitmap with the glyph image for the specified button identifier.

GetButtonIcon is a TCustomBitmap function used to get a bitmap with the glyph image for the button identifier in idButton. GetButtonIcon calls the GetStockImage routine in ThemeServices to get the handle used for the stock image. If the return value is False, the GetDefaultButtonIcon is called to get the icon for the button identifier.

GetButtonIcon is used in the implementation of the LoadGlyphFromStock routine.

Adjusts the specified button layout for use in bi-directional rendering.

Adjusts the layout for button glyphs to reflect the settings in IsRightToLeft. Uses an implementation constant to get the TButtonLayout value needed for the setting in IsRightLeft.

In general, when IsRightToLeft is True the value in Layout is reversed and used as the return value. blGlyphLeft becomes blGlyphRight, blGlyphTop becomes blGlyphBottom, etc.

When IsRightToLeft is False, the value in Layout is used.

Adjusted glyph layout needed for the value in IsRightToLeft. True when BiDiMode has any value other than bdLeftToRight. Glyph layout needed for the button using the specified BiDi setting. Gets a String with debugging information from the specified TBitBtnKind instance. Formatted string value with the information for the type. TBitBtnKind instance examined in the routine. Contains modal result values for buttons defined in TBitBtnKind.

BitBtnModalResults is an Array constant which contains TModalResult values returned for buttons in TBitBtn. BitBtnModalResults is indexed by the enumeration values in TBitBtnKind. BitBtnModalResults is used in the implementation of the RealizeKind method in TCustomBitBtn.

Contains button identifiers used to get icons for TBitBtn button glyphs.

BitBtnImages is an Array constant which contains LongInt values for the button identifiers used in TBitBtn. BitBtnImages is indexed by the enumeration values in TBitBtnKind. Values in BitBtnImages are used in the GetLCLDefaultBtnGlyph routine.

Contains resource names for corresponding button identifiers in TBitBtn.

BitBtnResNames is an Array constant that contains Strings with the resource name for button identifiers used in TBitBtn. Values in BitBtnResNames are indexed by the range of values defined in BitBtnImages: idButtonOk..idButtonNoToAll.

BitBtnResNames is used in the implementation of the RealizeKind method in TCustomBitBtn.

Registers components for use in the Lazarus IDE.

Register is the procedure used to register components for us in the Lazarus IDE. The following components are added to the Lazarus IDE:

Additional Tab

TBitBtn
TSpeedButton