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 State property in TCustomSpeedButton.

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. 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 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. Sets the value for the ExternalImageIndex property. New value for the 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 used in the class instance. Sets the resource name for the LCL glyph used in the instance to the specified value. LCL glyph resource name used to get images in the glyph. Implements the method from IUnknown. Interface identifier for the specified object. Object examined for the specified interface. Implements the method from IUnkown. 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 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 ThemeServiecs 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.

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 scalilng 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. Ciient coordintates 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 content 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.

Images is used in conjunction with the ExternalImages and LCLGlyphName properties. 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. Otherwise, existing items in Images are used.

See for more information about image retrieval for the button glyph.

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 existing list of images available for use in the Glyph property.

ExternalImages is a TCustomImageList property with a list of images that can be used to set the glyph for the class instance.

TButtonGlyph can use images that originate from one of several properties: Images, ExternalImages, or Glyph. Images is a cached imaged list which may be refreshed when the cached images are changed. ExternalImages is an image list explicitly assigned to the property which does not use the image cache. Glyph is the bitmap to use for the glyph, and can originate from an LCL resource.

These image sources are used in the GetImageIndexAndEffect method to determine the image resolution and bitmap used for the glyph and the button state.

Setting a new value for the property causes the Glyph property to be cleared, and the OnChange event handler is signalled.

Setting a value for the Glyph or LCLGlyphName properties causes the image list in ExternalImages to be discarded.

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

Use ExternalImageIndex to specify the position in ExternalImages for the bitmap displayed as the button glyph.

Ordinal position in the external image list for the glyph image. Width of an image in the external image list. The width of the glyph image. The height of the glyph image. 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 when IsDesigning contains False.

Event handler for a change in the glyph.

OnChange is a TNotifyEvent property that represents an event handler signalled when the image used in the Glyph property is altered. OnChange is signalled from the DoChange method, and occurs after Glyph has been loaded using resources 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. ActionChange - Changes the action associated with the control. 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.

Bitmap with the Glyph displayed on the control. The number of glyphs available for the control. Contains images available for the control. Ordinal position for the image displayed on the control. 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. The spacing around the BitButton. Indicates the policy for showing or hiding the glyph image of this 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. SetChecked - stores the Checked status (True or False). 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 class for TSpeedButton.

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

A SpeedButton is designed to automatically perform a process when it is depressed. The user can push the 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 have a descriptive glyph (symbol or pictograph), and has a state (checked or unchecked).

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. 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. Control message passed when the button is pressed. Control message passed when the control is enabled. Performs actions needed when the Mouse Up message is received for the control. 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: 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. Calculates the Width and Height for theSpeedButton, and optionally renders the control. Used in the implementation of the CalculatePreferredSize and Paint methods. 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. Paints the background for the control. 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. GetDrawDetails - returns the structured details for drawing. MouseInControl - returns True if the mouse cursor is in the control. 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).

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 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 action 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 GetGlyphSize - returns the size of the glyph within the specified PaintRect. GetTextSize - returns the size of the text within the specified PaintRect. Draws the glyph on the specified canvas in the specified rectangle at a given offset within the client, with specified state and transparency. 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 FindDownButton - returns the button that 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). Boolean flag which indicates if all buttons in a group are allowed to be Up (default is False). 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 as TControl.GetColorResolvingParent and TControl.GetRGBColorResolvingParent.

TControl.Color TControl.ParentColor TControl.GetDefaultColor TControl.GetColorResolvingParent TControl.GetRGColGetRGBColorResolvingParentarent Indicates if the button has been set to the Down state. Whether the button is to be displayed Flat or in relief. The Bitmap used for the glyph image on the button. The ordinal position for the control within a group of related speedbuttons. Contains images available for use as the glyph for the control. Ordinal position for the Image used as the glyph for the control. Display width for the glyph image in the control. The button layout - Glyph at top, bottom, left or right. Margin - the space around glyph and caption. 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 Glyphs available. Indicates if the accelerator charactershould be shown (i.e. underlined character denoting key to be pressed for quick action). Indicates if the caption for the speed button is displayed. Spacing between Glyph and Caption. If Spacing is -1 and Margin is -1 then Glyph and Caption are centered and there is the same amount of space between Glyph and Caption and on the left and right. If Spacing is -1 and Margin is not -1 then Spacing will fill the remaining space. Indicates if the control is drawn with transparency. 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 represents the ability to see a visual control. If Visible is True the control is shown, otherwise it is hidden. Calling Show sets, among others, Visible to True. Setting Visible to False is equivalent to calling Hide method.

The Visible property does not depend on control's parent visibility. Use IsVisible method to consider this and get real 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 successfuly 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