Caption Buttons
- 3 minutes to read
Dock panels, tab containers and side containers are capable of displaying a caption bar. The caption bar is displayed if the following conditions are met:
The ShowCaption property of the dock control is set to True;
The dock control is docked to a dock site, within a tab container or a side container.
If the caption bar is visible, it displays the number of buttons specified by the CaptionButtons property and determined by the control’s layout. Available button types include:
Standard buttons (the Close, Auto Hide, and Maximize buttons);
Custom buttons.
The following sections describe each button type in detail. Note that tab containers and side containers have additional concepts regarding caption buttons. Please refer to their descriptions for more information.
The Close Button
By default, the Close button is intended to hide the dock control. When end-users press it, the Visible property of the control is set to False. Subsequently, you can set it back to True to show the control. Note that in this case, the control is not undocked from its parent and, thus, its position will be restored.
The behavior of the Close button can be changed using the Options property of the docking manager. If the doUndockOnClose option is enabled, the control is undocked from its parent when pressing the close button. You can achieve the same via code by calling the control’s UnDock method.
If the doFreeOnClose option is enabled, the dock control is destroyed when closed. This can also be done by calling the Free method of the desired dock control.
Note that Close button behavior can also be controlled by handling the dock control’s OnCloseQuery event. This event fires when a dock control’s Close button is pressed. The event provides a parameter to enable you to cancel the default action and execute your own code instead. Please refer to the event description for details.
The Auto Hide Button
The Auto Hide button is displayed within control captions when they are not floating. This implies that a control must be docked to a dock site or to a control that is docked to a dock site.
Clicking the Auto Hide button activates the auto hide feature for the control. Refer to the Auto Hide Feature topics for details.
The Maximize Button
This button is displayed inside control captions within side containers. Clicking the button makes the corresponding dock control the container’s active child. This implies that the control is maximized to occupy the entire client area of the container. Clicking the button once again restores the previous size of the control. The button switches its image according to the action available in the current control state.
You can also maximize controls in code. To do so, assign the control to the ActiveChild property of the owning side container. Also, you can assign the control’s DockIndex property value to the side container’s ActiveChildIndex property.
Custom Buttons
In addition to the standard caption buttons described above, you can provide buttons with custom functionality. A custom button has no predefined action. Handle button clicks to perform the required actions. With the dock controls shipped with the ExpressDocking Library, you can create as many custom buttons as you like and display them to the left of the standard caption buttons.
The table below lists the main properties that relate to custom buttons.
| Visibility | A custom button’s Visible property. |
|---|---|
| Appearance | A custom button’s ImageIndex property. |
| Behavior | The Enabled property and the OnClick event of a custom button. |
| Object | TdxDockControlCaptionButton objects stored in the collection referenced by a dock control’s CustomCaptionButtons.Buttons property. |