[Overview][Constants][Types][Classes][Procedures and functions][Index] | Reference for unit 'ComCtrls' (#lcl)

# TToolButton

[Properties (by Name)] [Methods (by Name)] [Events (by Name)]

TToolButton is a button control used in a TToolBar object.

## Declaration

Source position: comctrls.pp line 2104

`type TToolButton = class(TGraphicControl)`
`protected`
`Const`
`cDefSeparatorWidth = 8` |  | Default width for tool buttons using the separator style.
`cDefDividerWidth = 5` |  | Default width for tool buttons using the divider style.
`cDefButtonDropDecArrowWidth = 2` |  | Default width for the drop-down indicator in tool buttons.
`cHorIconTextDist = 5` |  | Default number of pixels between the icon and the text on the tool button. It is used when the List property in the parent tool bar is enabled, and contains the number of pixels (prior to scaling) between the right edge of the icon (when assigned) and the caption text. It is included in the size value returned from CalculatePreferredSize (when needed).
`cVertIconTextDist = 2`
`FToolBar: TToolBar;` |  | Member variable with the tool bar where the button is used.
`class procedure WSRegisterClass; override;` |  | Registers this component class with the current WidgetSet.
`procedure CopyPropertiesFromMenuItem();` |  | Copies properties from the specified menu item.
`function GetActionLinkClass; override;` |  | Gets the class type for the ActionLink in the tool button.
`procedure ActionChange(); override;` |  | Implements the handler signalled when the Action for the tool button is changed.
`procedure AssignTo(); override;` |  | Implements object persistence used to assign properties from the class instance to another persistent object.
`procedure BeginUpdate; virtual;` |  | Starts an update process for the tool button.
`procedure EndUpdate; virtual;` |  | Ends an update process for the tool button.
`procedure MouseMove(); override;` |  | Detects whether the mouse is hovered over the drop-down indicator for the tool button.
`procedure MouseDown(); override;` |  | Handles mouse click events for the tool button.
`procedure MouseUp(); override;` |  | Handles mouse up events for the tool button.
`procedure MouseEnter; override;` |  | Handles a message sent when the mouse enters a control.
`procedure MouseLeave; override;` |  | Handles a message sent when the mouse leaves a control.
`procedure Notification(); override;` |  | Handles the notification sent when a component is added to or removed from the control.
`procedure Paint; override;` |  | Draws the tool bar button to the Canvas for the control.
`procedure TextChanged; override;` |  | Performs actions needed when the caption text for the tool button has been changed.
`procedure CalculatePreferredSize(); override;` |  | Calculates the preferred dimensions for new instances of the control.
`class function GetControlClassDefaultSize; override;` |  | GetControlClassDefaultSize returns its own defaults, overriding inherited values.
`procedure Loaded; override;` |  | Performs actions needed when LCL component streaming has been completed.
`procedure RefreshControl; virtual;` |  | Refreshes the button control by updating it parent tool bar.
`procedure SetToolBar();` |  | Sets the value for the internal member with the TToolBar instance for the button.
`procedure UpdateControl; virtual;` |  | Causes the tool bar to adjust the size and position for its Buttons and Controls.
`function GetButtonDrawDetail; virtual;` |  | Gets the Theme Element Details used for the tool button.
`procedure SetParent(); override;` |  | Sets the value for the Parent property.
`procedure UpdateVisibleToolbar;` |  | Calls the corresponding method in the tool bar for the button.
`function GroupAllUpAllowed;` |  | Indicates if all buttons in the group are allowed to be in the 'Up' position.
`function DialogChar(); override;` |  | Clicks the button when the message contains the accelerator key for the button control.
`procedure SetAutoSize(); override;` |  | Sets the value the AutoSize property and adjusts the control size when needed.
`procedure RealSetText(); override;` |  | Sets the value for the Caption property.
`public`
`constructor Create(); override;` |  | Constructor for the class instance.
`function CheckMenuDropdown; virtual;` |  | Checks for and executes a drop-down menu for the tool button.
`procedure Click; override;` |  | Signals OnClick and/or executes the ActionLink when the control has been clicked.
`procedure ArrowClick; virtual;` |  | Signals the OnArrowClick event handler for the tool button.
`procedure GetCurrentIcon(); virtual;` |  | Gets the image list, index, and drawing effect for the icon on the tool button.
`procedure GetPreferredSize(); override;` |  | Returns default/preferred height and width, for use in auto-sizing.
`property Index: Integer; [r]` |  | Index- is the sequence number for the button in ButtonList.
`function PointInArrow();` |  | Indicates if the specified position is within the bounds for the arrow drawn on a drop-down button.
`published`
`property Action: TBasicAction;` |  | The Action associated with the control.
`property AllowAllUp: Boolean; [rw]` |  | Indicates if all buttons in a group can have their Down property set to False.
`property AutoSize: Boolean;` |  | Allows the control to grow to the size for its content.
`property Caption: TCaption;` |  | The text displayed for the control.
`property Down: Boolean; [rws]` |  | Indicates whether the button is in the "Down" state, i. e. has it been selected or clicked.
`property DragCursor: TCursor;` |  | The cursor shape shown during a drag operation.
`property DragKind: TDragKind;` |  | Indicates the action performed for a drag operation: drag-and-drop or drag-and-dock.
`property DragMode: TDragMode;` |  | Determines how a drag operation is started for the control.
`property DropdownMenu: TPopupMenu; [rw]` |  | The drop-down menu displayed when the button is pressed.
`property Enabled: Boolean;` |  | Determines whether the button can respond to click events, and how it is displayed.
`property Grouped: Boolean; [rw]` |  | Indicates if the tool button is a member of a group. The default value is False.
`property Height: Integer; [s]` |  | Contains the height for the control in pixels.
`property ImageIndex: TImageIndex; [rws]` |  | Ordinal position in an image list for the icon displayed on the tool button.
`property Indeterminate: Boolean; [rw]` |  | Indicates if the tool button is in an undetermined state.
`property Marked: Boolean; [rw]` |  | Indicates if the tool button is marked.
`property MenuItem: TMenuItem; [rw]` |  | Contains a menu item associated with the tool button.
`property ParentShowHint: Boolean;` |  | If True, the value of ShowHint for the control will be the same as the one from the Parent. Default is True.
`property PopupMenu: TPopupMenu;` |  | A context-sensitive menu that pops up when the right mouse button is clicked over this control.
`property ShowCaption: Boolean; [rw]` |  | Indicates whether the Caption text is displayed on the tool button.
`property ShowHint: Boolean;` |  | Enables Hint display for the control.
`property Style: TToolButtonStyle; [rw]` |  | Determines the display style for the tool button.
`property Visible: Boolean;` |  | Allows the control, and all of its children, to be displayed or hidden.
`property Width: Integer; [s]` |  | The horizontal size for the control.
`property Wrap: Boolean; [rw]` |  | Indicates whether the tool button is forced onto the next row on the parent tool bar.
`property OnArrowClick: TNotifyEvent; [rw]` |  | Event handler signalled when the drop-down indicator for a tool button is clicked.
`property OnClick: TNotifyEvent;` |  | Event handler signalled when the tool button has been clicked.
`property OnContextPopup: TContextPopupEvent;` |  | Invoked when a context-sensitive pop-up menu is requested.
`property OnDragDrop: TDragDropEvent;` |  | Event handler signalled when an object is dropped onto the control.
`property OnDragOver: TDragOverEvent;` |  | Event handler signalled when a control is dragged over the control instance.
`property OnEndDock: TEndDragEvent;` |  | Event handler signalled for the end of a drag-dock operation.
`property OnEndDrag: TEndDragEvent;` |  | Event handler signalled for the end of a drag-drop operation.
`property OnMouseDown: TMouseEvent;` |  | Event handler signalled when a mouse down event is handled for the control.
`property OnMouseEnter: TNotifyEvent;` |  | Event handler signalled when the mouse pointer has entered the control.
`property OnMouseLeave: TNotifyEvent;` |  | Event handler signalled when the mouse pointer has left the control.
`property OnMouseMove: TMouseMoveEvent;` |  | Event handler signalled when the mouse pointer is moved in the control.
`property OnMouseUp: TMouseEvent;` |  | Event handler signalled when a mouse up event is handled for the control.
`property OnMouseWheel: TMouseWheelEvent;` |  | Event handler for mouse wheel turned.
`property OnMouseWheelDown: TMouseWheelUpDownEvent;` |  | Event handler signalled for a downward movement of the mouse wheel.
`property OnMouseWheelUp: TMouseWheelUpDownEvent;` |  | Event handler signalled for an upward movement of the mouse wheel.
`property OnStartDock: TStartDockEvent;` |  | Event handler for the start of a docking operation.
`property OnStartDrag: TStartDragEvent;` |  | Event handler signalled for the start of a dragging operation.
`end;`

## Inheritance

`TToolButton` |  | TToolButton is a button control used in a TToolBar object.
`TGraphicControl` |  | TGraphicControl is the base class for all lightweight controls.
`TControl` |  | The base class for visible controls.
`TLCLComponent` |  | The base class for LCL components which have an associated widget.
`TComponent`
?
`TObject`

## Description

Use TToolButton to implement buttons on a toolbar. While other controls (including TButton and TSpeedButton) can be placed on toolbars, TToolButton utilizes special toolbar features to simplify the configuration of buttons and offers added display options such as edge borders and transparency.

To place tool buttons on a toolbar at design time, select the toolbar, right-click, and choose New Button.

## See also

TToolBar |  | Implements an application tool bar with buttons or other visual controls.
TButton |  | Implements a push button control.
TSpeedButton |  | A Button used to represent states (checked or unchecked).
How To Use Standard Controls |  | How to use StdCtrls, ComCtrls or ExtCtrls.

## Example

    { To use this example, create a new application and add the example code
      to the unit. Remember to add the ComCtls unit in the uses clause. }

    procedure AddButtons(ToolBar: TToolBar; const ButtonCaptions: array of String);
    var
      i: integer;
    begin
      for i := 0 to High(ButtonCaptions) do
      begin
        with TToolButton.Create(ToolBar) do
        begin
          Parent := ToolBar;
          Caption := ButtonCaptions[i];
          if (ButtonCaptions[i] = '|') then
            Style := tbsSeparator
          else
            Style := tbsButton;
          AutoSize := True;
        end;
      end;
    end;

    procedure TForm1.FormCreate(Sender: TObject);
    var
      ToolBar: TToolBar;
    begin
      ToolBar := TToolBar.Create(Self);
      ToolBar.Parent := Self;
      ShowMessage(IntToStr(ToolBar.ButtonCount));
      AddButtons(ToolBar, ['New', 'Save', '|', 'Cut', 'Copy', 'Paste']);
      ToolBar.ShowCaptions := True;
      ToolBar.Height := 40;
      ToolBar.ButtonWidth := 75;
      ShowMessage(IntToStr(ToolBar.ButtonCount));
    end;