[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 in a TToolBar object.

## Declaration

Source position: comctrls.pp line 1525

`type TToolButton = class(TGraphicControl)`
`protected`
`FToolBar: TToolBar;` |  | FToolBar - local variable indicating in which toolbar this button lives
`protected`
`class procedure WSRegisterClass; override;` |  | WSRegisterClass - Register this Class for the current Widget Set
`protected`
`procedure CopyPropertiesFromMenuItem();` |  | CopyPropertiesFromMenuItem - method for copying the properties of the corresponding Menu Item, to ensure that ToolButton and MenuItem produce the same behaviour
`function GetActionLinkClass; override;` |  | GetActionLinkClass - returns the Class of the ActionLink for this ToolButton
`procedure ActionChange(); override;` |  | ActionChange - a method for changing the action associated with the Button
`procedure AssignTo(); override;` |  | AssignTo calls inherited method: if the destination is of correct type, copies ImageIindex to destination and sets it Checked
`procedure BeginUpdate; virtual;` |  | BeginUpdate - start the update process
`procedure EndUpdate; virtual;` |  | EndUpdate - finish the update process
`procedure MouseDown(); override;` |  | MouseDown - a procedure that allows the programmer to simulate a mouse button being down over the control, and initiates the same Action as that associated with the OnMouseDown event
`procedure MouseMove(); override;` |  | MouseMove - a procedure that allows the programmer to simulate a mouse being moved over the control, and initiates the same Action as that associated with the OnMouseMove event
`procedure MouseUp(); override;` |  | MouseUp - a procedure that allows the programmer to simulate a mouse button being Up over the control, and initiates the same Action as that associated with the OnMouseUp event
`procedure MouseEnter; override;` |  | MouseEnter - a procedure that allows the programmer to simulate a mouse entering the control, and initiates the same Action as that associated with the OnMouseEnter event
`procedure MouseLeave; override;` |  | MouseLeave - a procedure that allows the programmer to simulate a mouse leaving the control, and initiates the same Action as that associated with the OnMouseLeave event
`procedure Notification(); override;` |  |
`procedure Paint; override;` |  | Virtual Paint method called in response to paint requests.
`procedure TextChanged; override;` |  | Procedure to deal with changes in text
`procedure CalculatePreferredSize(); override;` |  | CalculatePreferredSize - find default/preferred height and width
`protected`
`class function GetControlClassDefaultSize; override;` |  | GetControlClassDefaultSize returns its own defaults, overriding inherited values
`protected`
`procedure Loaded; override;` |  | Loaded - called when the component has finished loading. Calls inherited Loaded then copies various properties from client and parent
`procedure RefreshControl; virtual;` |  | RefreshControl - refreshes the drawing of the tool, in case changes have been made
`procedure SetToolBar();` |  | SetToolBar - records the existence of a new toolbar
`procedure UpdateControl; virtual;` |  | UpdateControl - brings the control up to date
`function GetButtonDrawDetail; virtual;` |  | GetButtonDrawDetail - find theme information for Windows XP inplementations
`procedure SetParent(); override;` |  | Find who the parents are and store the information
`procedure UpdateVisibleToolbar;` |  | UpdateVisibleToolbar - updates just the visible part of the toolbar
`function GroupAllUpAllowed;` |  | GroupAllUpAllowed - returns True if all buttons in a group are allowed to ne 'Up'
`function DialogChar(); override;` |  | DialogChar - a LCL Key Message; returns True if a Dialog character has an associated message
`procedure SetAutoSize(); override;` |  |
`procedure RealSetText(); override;`
`public`
`constructor Create(); override;` |  | Create - constructor for TToolButton: calls inherited Create and sets initial bounds and style
`function CheckMenuDropdown; virtual;` |  | CheckMenuDropdown - returns True if there is a checked dropdown menu
`procedure Click; override;` |  | Click - a procedure that allows the programmer to simulate a mouse click over the control, and initiates the same Action as that associated with the OnClick event
`procedure GetCurrentIcon(); virtual;` |  | GetCurrentIcon - finds the icon for the current button
`procedure GetPreferredSize(); override;` |  | Returns default/preferred height and width, to be used in autosizing algorithms
`property Index: Integer; [r]` |  | Index - the sequence number of the current button in the list of buttons
`published`
`property Action;` |  | The action to be associated with this control
`property AllowAllUp: Boolean; [rw]` |  | AllowAllUp - if True, all buttons are allowed to be 'Up' at the same time. Default False
`property AutoSize;` |  | Whether auto-size is to be used
`property Caption;` |  | Caption - the text-string appearing on the Control, usually used to identify its function
`property Down: Boolean; [rws]` |  | Is this button Down (ie has it been selected)? Default false
`property DragCursor;` |  | DragCursor - the style of cursor to be used during the Drag process
`property DragKind;` |  | DragKind - what sort of dragging? Drag or Dock
`property DragMode;` |  | DragMode - whether manual or automatic
`property DropdownMenu: TPopupMenu; [rw]` |  | A DropDownMenu that appears when this button is selected
`property Enabled;` |  | Whether the control is Enabled (read/write). If not, it usually appears 'greyed-out'
`property Grouped: Boolean; [rw]` |  | Is this button a member of a group? Default false
`property Height; [s]` |  | Height - the vertical dimension of the control
`property ImageIndex: TImageIndex; [rws]` |  | ImageIndex - the index value of the image from the imagelist to be used with this button
`property Indeterminate: Boolean; [rw]` |  | Indeterminate - if True, this button is in an unspecified state. Default False
`property Marked: Boolean; [rw]` |  | Is this button Marked (ie has it been selected)? Default false
`property MenuItem: TMenuItem; [rw]` |  | The item on the Main Menu with which this tool button is associated
`property OnClick;` |  | Event Handler for mouse click
`property OnContextPopup;` |  | Event handler to supply information when a context-sensitive pop-up menu is required
`property OnDragDrop;` |  | Event handler for the drop of a control onto this control.
`property OnDragOver;` |  | Event handler for the case when a control is dragged over another control
`property OnEndDock;` |  | Event handler for the end of a docking operation
`property OnEndDrag;` |  | Event handler for the end of a dragging process
`property OnMouseDown;` |  | Event handler for when a mouse button is pressed down
`property OnMouseMove;` |  | Event handler for mouse movement within the current control
`property OnMouseUp;` |  | Event handler for when the mouse button is released, ie "up"
`property OnStartDock;` |  | Event handler for the start of a docking operation
`property OnStartDrag;` |  | Event handler for start of dragging operation
`property ParentShowHint;` |  | ParentShowHint - does the control adopt the same hinting behaviour as its parent? Default is true
`property PopupMenu;` |  | PopupMenu - a context-sensitive menu that pops up when the right mouse button is clicked over this control
`property ShowCaption: Boolean; [rw]` |  | Show/Hide caption
`property ShowHint;` |  | Flag to determine: Is hint to be displayed for this control?
`property Style: TToolButtonStyle; [rw]` |  | Determines the style of the tool button.
`property Visible;` |  | Visible - can the control be seen?
`property Width; [s]` |  | Width - the horizontal dimension of the control
`property Wrap: Boolean; [rw]` |  | Has this button been wrapped to the next row?
`end;`

## Inheritance

`TToolButton` |  | TToolButton is a button control in a TToolBar object.
`TGraphicControl` |  | TGraphicControl is the base class for all lightweight controls.
`TControl`
`TLCLComponent` |  | TLCLComponent - base class for LCL components
`TComponent,IUnknown,IInterfaceComponentReference`
`TPersistent`
`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 pop-up 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
TButton
TSpeedButton |  | A Button used to represent states (checked or not, etc)
HowToUseStdCtrls |  | 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;

The latest version of this document can be found at lazarus-ccr.sourceforge.net .