Provides a panel with buttons using glyph images.

buttonpanel.pas contains classes and types used to implement TButtonPanel, a panel which contains common buttons used in an application form. It is part of the Lazarus Component Library (LCL).

The following components are added to the Lazarus IDE:

Misc Tab

TButtonPanel

Enumerated type with the display order used for buttons on TButtonPanel.

TButtonOrder is an enumeration with values which indicate the display order used for buttons on TCustomButtonPanel and TButtonPanel.

The value boDefault has a special meaning, and causes the button order to be set to the sequence normally used for the platform or operating system.

For example:

UNIX-like environments: Uses Ok, Cancel, Close, and Help button order.
All other platforms: Uses Cancel, Ok, Close, and Help button order.

TButtonOrder is the type used to implement the TCustomButtonPanel.ButtonOrder property.

Uses the common button order for the platform or operating system. Use the button order Close, Cancel, OK, Help. Use the button order Close, OK, Cancel, Help. Enumeration with values that represent the buttons used on TButtonPanel.

TPanelButtonEx is an enumeration type with values which represent the default button used on TButtonPanel. Values from the enumeration (except for pbNone) are used to define the TPanelButton type.

Added in LCL version 2.3.0. Represents the OK button on the panel. Represents the Cancel button on the panel. Represents the Close button on the panel. Represents the Help button on the panel. Indicates that a button is not enabled as the default button on a button panel. Represents the visible buttons and glyphs used on a TButtonPanel control.

TPanelButton is a range type with values which represent the visible buttons and glyphs used on TButtonPanel. Values in TPanelButton are stored in the TPanelButtons collection type, and used in the ShowButtons and ShowGlyphs properties in TButtonPanel control.

Changed to a range type in LCL version 2.3.0. Set type used to store TPanelButton values.

TPanelButtons is a set type used to store enumeration values from TPanelButton. TPanelButtons is the type used to implement the ShowButtons and ShowGlyphs properties in TButtonPanel.

Defines the default buttons displayed on a TButtonPanel instance.

DefShowButtons is a set constant which contains the default buttons displayed on a button panel instance. DefShowButtons provides the default value for the ShowButtons property in TCustomButtonPanel.

Defines the default glyphs displayed for the buttons on a button panel instance.

DefShowGlyphs is a set constant which contains the default glyphs displayed for the buttons on a button panel. DefShowGlyphs provides the default value for the ShowGlyphs property in TCustomButtonPanel.

Implements the buttons displayed for TButtonPanel.

TPanelBitBtn is a TCustomBitBtn descendant used to implement the buttons displayed for TButtonPanel. TPanelBitBtn is the type used to implement the OKButton, HelpButton, CloseButton, and CancelButton properties in TButtonPanel.

TPanelBitBtn includes an overridden constructor to mark its use as a sub-component. It also sets the visibility, storage specifiers, and default values for properties inherited from ancestors classes.

TCustomBitBtn Constructor for the class instance.

Create is the overridden constructor for the class instance. Create calls the inherited method, and calls SetSubComponent to indicate that the component is used as a sub-component in the parent control.

TCustomBitBtn.Create Owner for the class instance. Indicates if the Caption for the button contains a default value.

DefaultCaption determines if the value in Caption is included in the LCL component streaming mechanism; Caption is stored for the component when DefaultCaption is False.

Contains the Left pixel coordinate for the button.

Left is not a stored property value in the LCL component streaming mechanism. Its value it always calculated the button position relative to the parent control for the component.

Contains the Top pixel coordinate for the button.

Top is not a stored property value in the LCL component streaming mechanism. Its value it always calculated the button position relative to the parent control for the component.

Contains the Width in pixels for the button.

Width is not a stored property value in the LCL component streaming mechanism. Its value it always calculated the button position relative to the parent control for the component.

Contains the Height in pixels for the button.

Height is not a stored property value in the LCL component streaming mechanism. Its value it always calculated the button position relative to the parent control for the component.

Name or identifier assigned for the button.

Name is a String property with the identifier assigned to the button to indicates its usage in TButtonPanel. Name contains a constant value like 'OKButton', 'CancelButton', 'CloseButton', or 'HelpButton'. The value in Name is assigned when the button is created in the CreateButton method in TCustomButtonPanel.

Popup menu displayed when the button is pressed or clicked. Defines the base class for TButtonPanel.

TCustomButtonPanel is a TCustomPanel descendant which defines the base class for TButtonPanel, a panel containing buttons with glyph images. Buttons are provided for OK, Help, Close, and Cancel operations. Other properties are provided to control the display order for the buttons, the default button for the panel, visibility of the available buttons, and the use of glyphs.

Applications should not create instances of TCustomButtonPanel; use the TButtonPanel ancestor which specifies the visibility of properties (including event handlers).

TCustomPanel Creates and configures a Bitmap button for the specified button type

CreateButton creates and stores the TPanelBitBtn instance used for the button type in AButton. AButton is a TPanelButton enumeration value.

Create sets values in the Name, Kind, AutoSize, TabOrder, Align, and Default properties in the button instance. The Bitmap for the button Glyph is created or re-assigned as necessary.

No actions are performed in the method if the button type in AButton has already been created for the panel.

CreateButton is used in the implementation of the DoShowButtons method.

TPanelButton value which identifies the button created in the method. Updates the buttons on the panel to match the DefaultButton property.

DoDefaultButton is a procedure used to update the buttons on the panel to identify the default button. Values from the TPanelButton enumeration are used to access the buttons present on the panel. The Default property in each button is updated to indicate if the button instance is the value stored in the DefaultButton property.

No actions are performed in the method when ShowButtons contains an empty set ([]). Performs actions needed to create and/or configure buttons displayed on the panel.

DoShowButtons is a procedure used to perform actions needed to create and/or configure buttons displayed on the panel. DoShowButtons iterates over the buttons defines for the panel. If the button has not already been created, the CreateButton method is called to initialize and store the button instance. The ShowButtons property is used to determine if the button is displayed at run-time and design-time.

DoShowButtons calls UpdateButtonOrder to display the buttons in the order specified in the ButtonOrder property. UpdateButtonLayout is called to ensure that the buttons use custom alignment, and to set the default button for the layout.

Autosizing for the panel control is disabled prior to updating the button layout, and restored prior to exiting from the method.

DoShowButtons is called when a value is assigned to the ShowButtons property.

Assigns the bitmaps used as glyphs for the buttons on the panel.

DoShowGlyphs is a procedure used to assign the bitmaps used as glyphs for the buttons on the panel. DoShowGlyphs iterates over the buttons displayed on the panel, and uses the values in the ShowGlyphs property to set or reset the glyph used in the button instance.

Autosizing for the panel control is disabled prior to updating the button glyphs, and restored prior to exiting from the method.

DoShowGlyph is called when a value is assigned to the ShowGlyphs property.

Sets the value for the ButtonOrder property.

Calls UpdateButtonOrder to refresh the display order for buttons on the panel.

New value for the property. Sets the value for the DefaultButton property.

Calls the DoDefaultButton method.

New value for the property. Sets the value for the ShowBevel property.

Calls the UpdateBevel method.

New value for the property. Sets the value for the ShowButtons property.

Calls the InvalidatePreferredSize and DoShowButtons methods.

New value for the property. Sets the value for the ShowGlyphs property.

Calls the InvalidatePreferredSize and DoShowGlyphs methods.

New value for the property. Sets the value for the Spacing property.

Calls the InvalidatePreferredSize and ReAlign methods.

New value for the property. Configures the shape and alignment for the bevel displayed on the panel.

UpdateBevel is a procedure used to set the shape and alignment for the bevel displayed on the panel. It sets the values in the Align and Shape properties for the TBevel instance based on the content in the Align property for the panel. For instance:

	Panel Align	Bevel Align	Bevel Shape
alTop	alBottom	bsBottomLine
alLeft	alRight	bsRightLine
alRight	alLeft	bsLeftLine
alBottom	alTop	bsTopLine

The width for the bevel is set to 2 for horizontal panel alignments (left or right). Otherwise, the height for the bevel is set to 2 for vertical panel alignments (top or bottom).

UpdateBevel is called when a value is assigned to the ShowBevel property.

No actions are performed in the method when ShowBevel is set to False. TBevel Sets the Tab order for visible buttons on the panel.

UpdateButtonOrder is a procedure used to set the tab order for visible buttons on the panel. It sets the TabOrder property in each of the TPanelBitBtn instances using the ButtonOrder for the panel.

UpdateButtonOrder calls the AdjustSize method to resize the panel and its controls.

Use ShowButtons to specify the visible buttons on the panel. Use ButtonOrder to define the display and tab order for the buttons.

Calculates the size for button controls displayed on the panel.

UpdateSizes is a procedure used to calculate the size for button controls displayed on the panel. UpdateSizes gets the button size using GetElementDetails and GetDetailSizeForPPI in ThemeServices, and stores the values in the internal members used in the panel class.

All button controls on the panel are updated. GetPreferredSize is called using the expected button Height and Width. The Align property is also updated when adjusting the button Height and Width.

UpdateSizes is called when a value is assigned to the Align property, and from the Notification method.

No actions are performed in the method at design-time. Updates the alignment for visible buttons on the panel.

UpdateButtonLayout is a procedure used to update the alignment for the visible buttons on the panel. UpdateButtonLayout uses the enumeration values from ShowButtons to determine the button instances updated in the method.

The Align property in each of the TPanelBitBtn instances on the panel is set to the value alCustom. In addition, the Default property in the button instance is updated to True when it contains the same class instance as the value stored in the DefaultButton property.

UpdateButtonLayout is called when a value is assigned to the Align property, and from the DoShowButtons method.

Applies button sizes when the visibility for the panel is changed.

UpdateButtonSize is a method used to adjust the size for the visible buttons on the panel when the value in the Visible property has been changed.

UpdateButtonSize applies the size used for push button elements in theme services to the Constraints property in the TPanelBitBtn instances on the panel. The button size is scaled when Application.Scaled is set to True and the design-time display density differs from the run-time Font setting.

No actions are performed in the method if a designer surface cannot be located for the panel; the designer surface has the original font density used in the scaling operation.

UpdateButtonSize temporarily disables auto-sizing in the panel while the button sizes are updated. Auto-sizing is re-enabled prior to exit.

UpdateButtonSize is called from the CMShowingChanged method when the CM_SHOWINGCHANGED message is handled for the control.

TControl.Constraints Indicates if the specified button is the last one defined in the button order.

IsLastButton is a Boolean function used to determine if the button in AControl is the last button in the ButtonOrder for the panel. The return value is True when AControl is a visible TPanelBitBtn instance which occurs last in the tab order for the visible buttons.

True when the specified button is the last in the button order. Control compared to the buttons on the panel. Called by components that are freed and which received a FreeNotification.

Notification is called whenever a child component is destroyed, inserted or removed from the list of owned components. Components that were requested to send a notification when they are freed (with FreeNotification) will also call Notification when they are freed.

The AComponent parameter specifies which component sends the notification, and Operation specifies whether the component is being inserted into or removed from the child component list, or whether it is being destroyed.

Notification is overridden in TCustomButtonPanel to ensure that TPanelBitBtn instances which are freed are excluded from the ShowButtons property, and their internal storage is Nil'd. If the panel control is not being destroyed, the remaining buttons are re-sized and re-aligned.

TComponent.Notification Component for the notification. Operation performed for the component. Sets the value for the Align property. Calls the UpdateButtonLayout, UpdateBevel, and UpdateSizes methods. New value for the property. Performs the control message needed when the visibility for a button glpyh has changed. Control message passed in the method. Performs the Lazarus control message when a button visibility is changed. Control message passed in the method. Constructor for the class instance.

Create is the overridden constructor for the class instance. Create calls the inherited constructor, and sets the default values for properties in the panel to the following:

Align: alBottom
BevelInner: bvNone
BevelOuter: bvNone
Caption: Set to an empty string ('')
AutoSize: True
Spacing: 6
ShowBevel: True
DefaultButton: pbOK
ButtonOrder: boDefault
ShowButtons: DefShowButtons
ShowGlyphs: DefShowGlyphs

The ControlStyle property is modified in the method to add the csOwnedChildrenNotSelectable style, and to remove the csSetCaption style.

Create calls the DoShowButtons method to create and configure the TPanelBitBtn instances used in the panel class.

TCustomPanel.Create Owner for the class instance. Destructor for the class instance.

Destroy is the overridden destructor for the class instance. Destroy ensures that TBitmap instances created for button glyphs in the panel are freed. Destroy calls the inherited destructor prior to exiting from the method.

Indicates the alignment used for the panel relative to the owner for the panel.

Align is a public property in TCustomButtonPanel used to specify the border (or edge) where the panel (and its buttons and bevel) are aligned. The default value for the property is alBottom.

Changing the value in Align causes the private UpdateButtonLayout, UpdateBevel, and UpdateSizes methods to be called.

Use AutoSize to enable or disable auto-sizing for the non-aligned or anchored dimensions in the control.

Indicates if the panel can automatically adjust its size.

AutoSize is a Boolean property which indicates if the button panel can automatically adjust its size. The default value for the property is True.

Please note that auto-sizing is affected by the value in the Align property. When Align is set to alBottom (the default), the panel width is determined by the available width for the parent. Height will be automatically sized, but Width will not.

TControl.AutoSize TControl.AdjustSize OKButton - a button with the caption 'OK' signifying acceptance by the user.

OKButton is a read-only TPanelBitBtn property which provides access to the OK button for the panel. Read access is redirected to the internal array of buttons in the class instance.

Use OKButton to set custom values for properties in the TPanelBitBtn instance, including:

Caption
Cursor
DefaultCaption
Enabled
Font
Glyph
Name
PopupMenu
ShowHint
Tag

HelpButton - a button with the 'Help' caption, for requesting help.

HelpButton is a read-only TPanelBitBtn property which provides access to the Help button for the panel. Read access is redirected to the internal array of buttons in the class instance.

Use HelpButton to set custom values for properties in the TPanelBitBtn instance, including:

Caption
Cursor
DefaultCaption
Enabled
Font
Glyph
Name
PopupMenu
ShowHint
Tag

CloseButton - a button with the 'Close' caption for terminating the Form or panel.

CloseButton is a read-only TPanelBitBtn property which provides access to the Close button for the panel. Read access is redirected to the internal array of buttons in the class instance.

Use CloseButton to set custom values for properties in the TPanelBitBtn instance, including:

Caption
Cursor
DefaultCaption
Enabled
Font
Glyph
Name
PopupMenu
ShowHint
Tag

CancelButton - a button with the 'Cancel' caption for cancelling the operation.

CancelButton is a read-only TPanelBitBtn property which provides access to the Cancel button for the panel. Read access is redirected to the internal array of buttons in the class instance.

Use CancelButton to set custom values for properties in the TPanelBitBtn instance, including:

Caption
Cursor
DefaultCaption
Enabled
Font
Glyph
Name
PopupMenu
ShowHint
Tag

ButtonOrder - the order in which the series of buttons will appear on the panel.

ButtonOrder is a TButtonOrder property which indicates the order of the buttons displayed on the panel. The default value for the property is boDefault, and causes the button order to be set to the sequence normally used for the platform or operating system.

For example:

UNIX-like environments: Uses Ok, Cancel, Close, and Help button order.
All other platforms: Uses Cancel, Ok, Close, and Help button order.

Use boCloseCancelOK or boCloseOKCancel to set the button order where Help is always the last button displayed.

Changing the value in ButtonOrder causes the button panel to be re-drawn.

The default button executed when Enter or Return are pressed.

DefaultButton contains the button which performs the default action when the Return or Enter key is pressed.

Indicates the buttons displayed on the panel.

ShowButtons is a TPanelButtons property which contains the set of buttons displayed on the panel. The default value for the property is defined in the DefShowButtons constant.

Changing the values in the property causes the panel and its buttons to be re-sized and re-drawn.

Use ShowGlyphs to indicate which buttons have an image displayed on the button surface.

For example:


// var aButtonPanel: TButtonPanel...
// use Ok and Cancel buttons only
AButtonPanel.ShowButtons := [pbOk, pbCancel];
AButtonPanel.ShowGlyphs := [pbOk, pbCancel];

Indicates the panel buttons displayed with Glyphs (small images).

ShowGlyphs contains values from the TPanelButton enumeration, and defines which panel buttons in ShowButtons are displayed with glyph images. The default value for the property is defined in the DefShowGlyphs constant.

Changing the values in the property causes the panel and its buttons to be re-sized and re-drawn.

A default glyph image is provided for each TPanelBitBtn instance on the panel using the internal button name, like "OKButton" or "CancelButton". The default glyph image is loaded from LCL glyph resources when the button is created. Use OkButton, CancelButton, CloseButton, and HelpButton to provide custom values used in the panel buttons.

Use ShowButtons to control which buttons are displayed on the panel. For example:


// var aButtonPanel: TButtonPanel...
// use Ok and Cancel buttons only
AButtonPanel.ShowButtons := [pbOk, pbCancel];
AButtonPanel.ShowGlyphs := [pbOk, pbCancel];

Indicates if a bevel is displayed for the button panel.

ShowBevel is a Boolean property which indicates if a TBevel is displayed on the edge opposite of the alignment for the panel. Changing the value for the property causes a TBevel instance to be created (or re-created). The private UpdateBevel method is called to apply the size, shape, and alignment needed for the bevel.

Contains the spacing around buttons and bevels on the panel.

Spacing is a TSpacingSize property which indicates the number of pixels reserved between buttons and bezels displayed on the panel. The default value for the property is 6. Changing the value in Spacing causes the InvalidatePreferredSize and ReAlign methods to be called.

Use BorderSpacing to indicate the space reserved on the borders (or edges) for the panel.

TWinControl.ReAlign TControl.InvalidatePreferredSize Implements a panel with Bitmap Button instances.

TButtonPanel is a TCustomButtonPanel descendant which implements a panel containing buttons with glyph images. Buttons are provided for OK, Help, Close, and Cancel operations. Other properties are provided to control the display order for the buttons, the default button for the panel, visibility of the available buttons, and the use of glyphs.

Registers the TButtonPanel class in the Lazarus IDE.

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

Misc Tab

TButtonPanel