Copyright: Copyright © 2002-2008 Developer Express Inc. ALL RIGHTS RESERVED


dxDockPanel Unit Overview
dxDockPanel Unit

Classes

TdxDockPanel


TdxDockPanel
TdxDockPanel Object

Hierarchy          Properties          Methods          Events          Concepts

Represents a dock panel.

Unit

dxDockPanel

TdxDockPanel = class(TdxCustomDockControl)

Description

The TdxDockPanel control represents a dock panel.  Dock panels are the main building blocks of applications using dock windows.  They serve as containers for the controls available.

Note that dock panels cannot reside on forms directly.  If not residing on a dock site or a layout site, an underlying float site is automatically created for them.  The float site, it turn, accommodates the float form specifically created to hold it.

In addition to docking panels to dock sites, layout sites or making them float, you can dock panels to each other in order to form various containers.  If a panel is docked to the left or right edge of another panel, a horizontal side container is created.  If docked to the top or bottom edge, a vertical side container is created.  In addition, you can dock a panel to the entire client area of another panel.  This will form a tab container.

Once panels are docked to each other and containers are created, you can perform docking operations on the containers created also.  This implies either docking panels to containers or docking containers to each other in order to form containers of a more complex structure.  For instance, there can be a tab container within a side container, etc.  Please refer to the docking manager’s Options property description for details on the operations allowed.

The TdxDockPanel control’s functionality is mostly implemented by its ancestor TdxCustomDockControl class.  The TdxDockPanel class publishes properties and events and overrides the base class methods.


TdxDockPanel Hierarchy
Hierarchy

TCustomControl

     |

TdxCustomDockControl

     |


Properties for TdxDockPanel
TdxDockPanel Properties

TdxDockPanel          Legend

In TdxDockPanel

ShowSingleTab

TabPosition

Derived from TdxCustomDockControl

Active

AllowDock

AllowDockClients

AllowFloating

AutoHide

AutoHideControl

AutoHideHostSite

Caption

CaptionButtons

ChildCount

Children

Color

Container

Controller

Dockable

DockIndex

DockLevel

DockState

DockType

DockZones

FloatDockSite

FloatForm

Font

ImageIndex

Images

LayoutDockSite

ManagerColor

ManagerFont

OriginalHeight

OriginalWidth

ParentDockControl

ParentForm

ResizeZones

ShowCaption

SideContainer

SideContainerIndex

SideContainerItem

TabContainer

TopMostDockControl

UseDoubleBuffer


Methods for TdxDockPanel
TdxDockPanel Methods

TdxDockPanel          Legend

Derived from TdxCustomDockControl

Activate

CanActive

CanAutoHide

CanDock

CanDockHost

CanMaximize

Close

DockTo

GetDockZoneAtPos

GetResizeZoneAtPos

MakeFloating

SetBounds

UnDock


Events for TdxDockPanel
TdxDockPanel Events

TdxDockPanel          Legend

Derived from TdxCustomDockControl

OnActivate

OnAutoHideChanged

OnCanResize

OnClose

OnCloseQuery

OnCreateFloatSite

OnCreateLayoutSite

OnCreateSideContainer

OnCreateTabContainer

OnCustomDrawDockingSelection

OnCustomDrawResizingSelection

OnDock

OnDocking

OnEndDocking

OnEndResizing

OnGetAutoHidePosition

OnLayoutChanged

OnMakeFloating

OnResize

OnResizing

OnRestoreDockPosition

OnStartDocking

OnStartResizing

OnStoreDockPosition

OnUnDock

OnUpdateDockZones

OnUpdateResizeZones


TdxDockPanel.ShowSingleTab

TdxDockPanel

Specifies if the panel should display its tab when not joined into a tab container.

property ShowSingleTab: Boolean;

Description

By default, tabs that correspond to dock panels are displayed only when panels are joined into a tab container.  These tabs are used for switching between the tab container’s children.  There are cases, however, when you may need to display the panel’s corresponding tab even when it is not within a tab container.  This takes place, for instance, when developing a user interface similar to the Visual Studio .NET IDE.  In such cases, dock panels containing documents do not display their captions (their ShowCaption property value is False).  Documents are identified by their corresponding tabs.  Thus, tabs should be displayed even when there is only a single document open (there is no tab container created).

If the ShowSingleTab property value is True, the dock panel displays its corresponding tab at the position specified by the TabPosition property.

The default value of the ShowSingleTab property is False.


TdxDockPanel.TabPosition

TdxDockPanel

Specifies where the dock panel’s tab is displayed.

type

  TdxTabContainerTabsPosition = (tctpTop, tctpBottom);

property TabPosition: TdxTabContainerTabsPosition;

Description

You can display tabs for individual dock panels by setting their ShowSingleTab property to True.  In this case, the TabPosition property value specifies where the tab will be displayed.  The following options are available.

Value	Meaning
tctpTop	The tab is displayed at the panel’s top-left corner.
tctpBottom	The tab is displayed at the panel’s bottom-left corner.

The default value of the TabPosition property is tctpBottom.


TdxCustomDockControl
TdxCustomDockControl Object

Hierarchy          Properties          Methods          Events

Serves as the base for classes representing dock sites and dock panels.

Unit

dxDockControl

TdxCustomDockControl = class(TCustomControl)

Description

Dock panels and dock sites have much in common.  They both provide settings controlling how they can be docked to other sites and how panels can be docked to them.  Also, dock panels and sites can be contained within other sites.  This and other common functionality is implemented in the TdxCustomDockControl class.

The TdxCustomDockControl class has two direct descendants.  These are the TdxDockPanel control, representing docking panels, and the TdxCustomDockSite class.  The latter represents a common ancestor for all dock sites.


TdxCustomDockControl Hierarchy
Hierarchy

TCustomControl

     |


Properties for TdxCustomDockControl
TdxCustomDockControl Properties

TdxCustomDockControl          Legend

In TdxCustomDockControl

Active

AllowDock

AllowDockClients

AllowFloating

AutoHide

AutoHideContainer

AutoHideControl

AutoHideHostSite

Caption

CaptionButtons

ChildCount

Children

Color

Container

Controller

Dockable

DockIndex

DockLevel

DockState

DockType

DockZones

FloatDockSite

FloatForm

Font

ImageIndex

Images

LayoutDockSite

ManagerColor

ManagerFont

OriginalHeight

OriginalWidth

ParentDockControl

ParentForm

ResizeZones

ShowCaption

SideContainer

SideContainerIndex

SideContainerItem

TabContainer

TopMostDockControl

UseDoubleBuffer


Methods for TdxCustomDockControl
TdxCustomDockControl Methods

TdxCustomDockControl          Legend

In TdxCustomDockControl

Activate

CanActive

CanAutoHide

CanDock

CanDockHost

CanMaximize

Close

DockTo

GetDockZoneAtPos

GetResizeZoneAtPos

MakeFloating

SetBounds

UnDock


Events for TdxCustomDockControl
TdxCustomDockControl Events

TdxCustomDockControl          Legend

In TdxCustomDockControl

OnActivate

OnAutoHideChanged

OnAutoHideChanging

OnCanDocking

OnCanResize

OnClose

OnCloseQuery

OnCreateFloatSite

OnCreateLayoutSite

OnCreateSideContainer

OnCreateTabContainer

OnCustomDrawDockingSelection

OnCustomDrawResizingSelection

OnDock

OnDocking

OnEndDocking

OnEndResizing

OnGetAutoHidePosition

OnLayoutChanged

OnMakeFloating

OnParentChanged

OnParentChanging

OnResize

OnResizing

OnRestoreDockPosition

OnStartDocking

OnStartResizing

OnStoreDockPosition

OnUnDock

OnUpdateDockZones

OnUpdateResizeZones

OnVisibleChanged

OnVisibleChanging


TdxCustomDockControl.Active

TdxCustomDockControl          See Also

Determines whether a dock control is active.

property Active: Boolean;

Description

Use the Active property to determine whether a dock control is active.  When the current dock control is active the Active property’s value is True.  Otherwise, False is returned.

Call the Activate method to activate the current dock control.  Alternatively, you can change the docking controller’s ActiveDockControl property.  The controller can be obtained using the dxDockController function call.

ReadOnly Property


TdxCustomDockControl.AllowDock

TdxCustomDockControl          See Also           Concepts

Specifies how a dock control can be docked to other dock controls.

type

  TdxDockingType = dtClient..dtBottom;

  TdxDockingTypes = set of TdxDockingType;

property AllowDock: TdxDockingTypes;

Description

Use the AllowDock property to specify whether the dock control can be docked to the left, top, right and bottom edges of dock sites and whether it is allowed to fill entire sites.  For instance, if you want to allow panel docking only to the right or left edges of sites, set the AllowDock property to [dtLeft, dtRight].  (At design-time, you need to set the dtLeft and dtRight flags of the AllowDock property to True and set the other flags to False to implement this).

If an empty set is assigned to the AllowDock property, the dock control can be floating only and its AllowFloating property is automatically set to True.  If the dock control was already docked to a site, it is set to float automatically.  (To achieve this effect at design-time, set all the AllowDock flags to False).

Note that the target site’s AllowDockClients property must allow the dock operation.  Otherwise, it will not succeed, even if the AllowDock property of the control being docked is set to True.


TdxCustomDockControl.AllowDockClients

TdxCustomDockControl          See Also          Concepts

Specifies if and how other dock controls can be docked to it.

type

  TdxDockingType = dtClient..dtBottom;

  TdxDockingTypes = set of TdxDockingType;

property AllowDockClients: TdxDockingTypes;

Description

Use the AllowDockClients property to specify whether dock controls are allowed to be docked to the left, top, right and bottom edges of the current control and whether they are allowed to fill the entire control’s area.  For instance, if you want to prevent docking to the top edge of the control, set the AllowDockClients property to [dtClient, dtLeft, dtRight, dtBottom].  Note that the dtTop value is excluded from the set.  (To perform the same at design-time, you need to set the dtTop flag of the AllowDockClients property to False.  All other flags should be set to True.)

If an empty set is assigned to the AllowDockClients property, dock controls cannot be docked to the control.  If any controls were already docked to it, they then float.  Their AllowFloating properties are automatically set to True.  (At design-time, you need to set all the flags of the AllowDockClients property to False to achieve such an effect.)

Note that you can also use the AllowDock property of the control being docked to specify the set of allowed operations.  A docking operation succeeds only if both properties allow it.


TdxCustomDockControl.AllowFloating

TdxCustomDockControl          See Also          Concepts

Specifies whether the dock control is allowed to float.

property AllowFloating: Boolean;

Description

Dock controls can be either docked to a site or floating.  When floating, they are represented as separate forms.  Use the AllowFloating property to specify whether such a dock control state is allowed.  If set to False, the dock control cannot float freely but must be docked to a site or float within a tab container or a side container.

If the control should always float free, set its AllowDock property to an empty set.


TdxCustomDockControl.AutoHide

TdxCustomDockControl          See Also          Concepts

Specifies whether the dock control is automatically hidden when the mouse pointer is elsewhere.

property AutoHide: Boolean;

Description

When a panel, tab container or side container is not floating, you can set its AutoHide property to True so that it is automatically hidden when the mouse pointer doesn’t point at it.  A bar showing tabs with the names of the hidden panels is displayed at the edge of the dock site.  Pointing to a tab makes the corresponding dock control visible. If the panel is not active, moving the mouse pointer away from the panel hides it again.  This imitates the behavior of docking windows in the Microsoft Visual Studio .NET IDE.

Usually, the edge where the bar with tabs is displayed is determined automatically.  However, you can handle the OnGetAutoHidePosition event to specify it manually.

Note that you can allow end-users to enable and disable this auto hide feature.  They need to use the [image] button displayed within the caption to do this.  The panel’s or tab container’s ShowCaption property should be set to True for the caption to be visible.

If you need to respond to the enabling/disabling of the auto hide feature, handle the OnAutoHideChanged event.


TdxCustomDockControl.AutoHideHostSite

TdxCustomDockControl          See Also          Concepts

Returns the dock site controlling the dock control’s auto hide functionality.

property AutoHideHostSite: TdxDockSite;

Description

Panels, tab containers and side containers support an auto hide feature.  To enable it, set the AutoHide property of the dock control to True.  Once this has been done, showing/hiding the dock control is controlled by the dock site referenced by its AutoHideHostSite property.  You can use the ShowingControl property of the site returned by this property to show and hide the control (or its children) programmatically.

Note that if the control’s AutoHideHostSite property returns nil, the control’s auto hide feature cannot be enabled.  This occurs, for instance, if the dock control is on a float site.

Note: if a dock panel is within a container whose auto hide feature is enabled, assigning the panel to the ShowingControl property of the host dock site will have no effect.  You should assign the owning container to this property instead.  To access the control whose auto hide feature is actually enabled, use the AutoHideControl property of a dock control.

You can handle the OnShowControl and OnHideControl events of the site returned by the AutoHideHostSite property to respond to showing and hiding the dock control.

The following sample code shows how to use the AutoHideHostSite property.  It shows and hides the help panel (TdxDockPanel control) in response to pressing the F1 key.  The OnKeyDown event of the form is handled in response to key pressing.  The same handler can be assigned to the OnKeyDown event of any control.

// Delphi

procedure TForm1.FormKeyDown(Sender: TObject; var Key: Word; Shift: TShiftState);

begin

  if Key <> VK_F1 then Exit;

  if not HelpPanel.AutoHide then Exit;

  // toggling the panel's visibility

  with HelpPanel.AutoHideHostSite do

  begin

    if ShowingControl = nil then

      ShowingControl := HelpPanel

    else

      ShowingControl := nil;

  end;

end;

ReadOnly Property


TdxCustomDockControl.AutoHideContainer

TdxCustomDockControl          See Also          Concepts

When the auto hide feature is enabled, it returns the parent of the dock control.

property AutoHideContainer: TdxDockSiteAutoHideContainer;

Description

If the control’s AutoHide property value is True, the AutoHideContainer property returns a TdxDockSiteAutoHideContainer control representing the dock control’s parent.  The returned object is a TWinControl descendant.  You will have no need to access members of this object in applications.

If the control’s AutoHide property value is False, the AutoHideContainer property returns nil.


TdxCustomDockControl.AutoHideControl

TdxCustomDockControl          See Also          Concepts

If the dock control’s auto hide feature is enabled, this property returns the control itself.  Otherwise, it returns the first control within the parent hierarchy that satisfies this condition.

property AutoHideControl: TdxCustomDockControl;

Description

The auto hide feature can be enabled for a dock control by setting its AutoHide property to True.  If enabling the auto hide feature for a container, the actual control’s behavior depends on the doTabContainerCanAutoHide and doSideContainerCanAutoHide options.  If these options are enabled, activating the auto hide feature for a container results in hiding all of its child controls.  Use the Options property of the docking manager to access these options.

When the auto hide feature is enabled, you can show/ hide the control using code.  To do this, you should assign the desired control to the ShowingControl property of the dock control returned by the auto hide host site.  This site can be accessed via the dock control’s AutoHideHostSite property.

Note that if a control is within an auto-hidden container, assigning this control to the ShowingControl property of the host site will have no effect.  To show the control programmatically, you need to assign the owning container to that property.

The AutoHideControl property eliminates the need to check whether the control is auto-hidden itself or within an auto-hidden container.  If the auto hide feature is enabled for the control itself, the panel’s AutoHideControl property will return the control.  If a control is within an auto-hidden container, the container will be returned by this property.  If the auto hide feature is not enabled for the dock control or for any of its parents, the AutoHideControl property will return nil.

Thus, assigning the AutoHideControl property to the ShowingControl property of the host site results in making the control visible.  Note, however, that if the control is within an auto-hidden tab container, you should also set the container’s ActiveChildIndex property to the DockIndex property of the child to be displayed.


TdxCustomDockControl.Caption

TdxCustomDockControl          See Also

Specifies the caption of the dock control.

property Caption: TCaption;

Description

Use the Caption property to specify the dock control’s caption text.  Note that the caption is only displayed if the ShowCaption property is set to True.

When joining several panels within a tab container, the panels’ Caption properties specify the text displayed on the tabs.  This text is also used to identify panels when they are hidden (i.e. the auto hide feature is enabled).  Please refer to the AutoHide property description for details on enabling the auto hide feature.

Note: the OnSetFloatFormCaption event of the docking manager and the OnSetFloatFormCapton event of the float site allow you to specify the captions of floating forms.


TdxCustomDockControl.CaptionButtons

TdxCustomDockControl          See Also          Concepts

Specifies which buttons are displayed within the caption of the dock control.

type

  TdxCaptionButton = (cbMaximize, cbHide, cbClose);

  TdxCaptionButtons = set of TdxCaptionButton;

property CaptionButtons: TdxCaptionButtons;

Description

Use the CaptionButtons property to specify the set of buttons that can be displayed within the dock control’s caption.  The table below lists all the available buttons, describes their purpose and the situations when they are visible.

Values	Description
cbMaximize	This button is only visible when panels are joined into a side container.  If clicked, the corresponding panel is expanded so that client areas of neighboring panels are not displayed.  The button’s appearance changes and clicking it again will restore the previous panel size. See the ActiveChildIndex property description for details on maximizing and restoring dock controls’ sizes.
cbHide	This button is only visible when panels are not on a float site.  If clicked, the auto hide feature for the corresponding panel is enabled.  The button changes its appearance and if clicked once again, disables the auto hide feature for the panel. See the AutoHide property description for details on the auto hide feature.
cbClose	This button hides the dock control when clicked.  Note that if the tab container's close button is clicked it can either close all panels within it or only the active one.  This is controlled by the doTabContainerCanClose option.  This option can be accessed via the Options property of the docking manager (or the docking controller).  Also, refer to the doFreeOnClose and doUndockOnClose options for details on the functionality of the close button.

The table below shows the caption buttons painted in different styles.  (The current painting style is specified using the ViewStyle property of the docking manager).

Button	Standard Paint Style	NET Paint Style	XP Paint Style
Maximize
Hide
Close
Note: dock controls only display captions if their ShowCaption property is set to True.


TdxCustomDockControl.ChildCount

TdxCustomDockControl          See Also

Gets the number of dock controls owned by the dock control.

property ChildCount: Integer;

Description

Use the ChildCount property to determine the number of immediate children of the dock control.  This property can be used in combination with the Children property.  The latter provides indexed access to child dock sites.  The index of the first child is 0.  The index of the last child is the ChildCount property value decremented by one.

Do not confuse the ChildCount property value with the number of panels visually residing on the current dock control.  Suppose a side container contains a tab container and a panel.  In this case, the ChildCount property of the side container will return 2 regardless of the number of panels within the tab container.  The number of panels within the tab container can be obtained by reading its ChildCount property in turn.

Please refer to the Dock Sites, Float Sites, Layout Sites, Tab Container Sites and Side Container Sites topics for information on how dock controls are arranged when docking them to each other.

ReadOnly Property


TdxCustomDockControl.Children

TdxCustomDockControl          See Also

Provides indexed access to immediate children of the dock control.

property Children[Index: Integer]: TdxCustomDockControl;

Description

Use the Children property to access the immediate children of the dock control.  This property can be used in combination with the ChildCount property to traverse through the children list.  The ChildCount property value is always one greater than the index of the last available child.  The first child’s index is 0.

The image below illustrates the Children and ChildCount property values.  The dock windows structure and the Object TreeView windows are shown for this purpose.  Note that the ChildCount property will return 3 for the vertical side container (its immediate children are the tab container and two panels).  Other panels are immediate children of the tab container and will be returned by its Children property.

ReadOnly Property


TdxCustomDockControl.Color

TdxCustomDockControl          See Also

Specifies the color of the dock control.

property Color: TColor;

Description

Use the Color property to specify the color of the dock control.  For dock sites and panels, the Color property specifies the color of the client area, caption and the bar displayed when the auto hide feature is enabled for the control.  For tab containers, the Color property specifies the color of the caption and the tabs.

Note that when the XP or Office 11 painting style is used, colors of dock controls are set automatically and the Color value is ignored.  Also, when the .NET style is applied, the background color of the tab container’s tab area is set automatically.  To specify the painting style, use the ViewStyle property of the docking manager.

Note that if the ManagerColor property of the dock control is set to True, the Color value is ignored.  The color specified by the Color property of the docking manager (or docking controller) is used in this case.  Please refer to the ManagerColor property description for details.

The default value of the Color property is clBtnFace.


TdxCustomDockControl.Container

TdxCustomDockControl          See Also

Returns the immediate container of the dock control.

property Container: TdxContainerDockSite;

Description

Use the Container property to access the container dock site that owns this dock control.  The image below illustrates the Container property.  It shows the Object TreeView window and the corresponding visual dock controls structure.  Note that the Container property will return the tab container for panels residing in it.  The vertical side container owns the other panels and the tab container.

Note: if the parent dock control is not a container (not a side container or tab container), the Container property will return nil.  In this case, you can use the ParentDockControl property to access the immediate parent of the dock control.  If the immediate parent is a container, these properties return the same values.

Use the Container property if you are not sure that the dock control is within a container or don’t know the container’s type.  Otherwise, you can use the SideContainer or TabContainer properties to obtain the owning container.

The Container property can be useful when you need to modify the container’s settings or to access dock controls residing within the same container as the current one.  Use the Children property of the container obtained to access its children.

ReadOnly Property


TdxCustomDockControl.Controller

TdxCustomDockControl          See Also          Concepts

Returns the docking controller that holds the common settings of dock controls and manages the dock operations.

property Controller: TdxDockingController;

Description

The TdxDockingController object available via the Controller property is used for the following purposes:

•	Central processing of dock operations;

•	Updating, saving and restoring the dock controls layout;

•	Storing common settings for all dock controls.

Most of settings stored by the docking controller can be accessed at design-time using the TdxDockingManager component.  If you do not use the docking manager in your application, you can only access these settings via code using the Controller property.

Please refer to the TdxDockingController class description for details on how the docking controller can be used in your applications.

ReadOnly Property


TdxCustomDockControl.Dockable

TdxCustomDockControl          See Also          Concepts

Specifies whether the dock control can be docked to other dock controls.

property Dockable: Boolean;

Description

Set the Dockable property to False to prevent end-users from performing docking operations on this docking control.  Once this has been done, end-users are unable to change the control’s state or position.  However, docking operations can still be performed via code.

If the Dockable property is set to True, the dock control can be docked as specified by its AllowDock property and by the AllowDockClients properties of dock sites.

You can also restrict a dock control to be in a floating or docked state only.  For a control always to float, set its AllowDock property to an empty set.  If you need to force the control to be always docked, set the control’s AllowFloating property to False.

Note: if the dock control allows docking other controls onto it, they can be joined into a container site.  For instance, two panels can be joined into a tab container.  In this case, the tab container can be docked independently of its children’s properties.  Thus, if you want to make sure that a panel is not moved anywhere, you can prohibit docking other controls onto it to avoid creation of such a container.  This can be done using the AllowDockClients property.  The another method is handling container site creation to modify their settings to prohibit their docking.  Please refer to the OnCreateTabContainer and OnCreateSideContainer events description for more information.

The default value of the Dockable property is True.


TdxCustomDockControl.DockIndex

TdxCustomDockControl          See Also

Returns the index of the dock control in its parent’s child collection.

property DockIndex: Integer;

Description

Use the DockIndex property to obtain the index of the dock control in its parent’s child collection.  The parent dock control can be obtained using the ParentDockControl property.  Child controls are available via the Children property.

If a dock control is within a tab container or a side container, the DockIndex property represents its position within the container.  For instance, the DockIndex property of a panel corresponding to the first tab of the tab container will return 0.  The DockIndex property of the panel corresponding to the second tab will return 1, etc.  Tabs are counted from left to right.  Children of horizontal side containers are counted in the same order.  In vertical side containers, child dock controls are counted from top to bottom.

The sample code below shows how the DockIndex property can be used.  It checks whether the parent of the HelpPanel dock panel is a tab container.  If so, the panel index is assigned to the ActiveChildIndex property of the tab container to ensure that the panel is currently active.

// Delphi

if HelpPanel.TabContainer <> nil then

  HelpPanel.TabContainer.ActiveChildIndex := HelpPanel.DockIndex;

ReadOnly Property


TdxCustomDockControl.DockLevel

TdxCustomDockControl          See Also

Returns a value indicating the nesting level of the dock control.

property DockLevel: Integer;

Description

Use the DockLevel property if you need to obtain the nesting level of the dock control.  Note that this property returns 1 for float sites and TdxDockSite components.  Thus, if a panel is on either of these containers, the DockLevel property of the panel will return 2.  If a tab container or side container is docked to either of these containers, the DockLevel property of panels in the container will return 3.

ReadOnly Property


TdxCustomDockControl.DockState

TdxCustomDockControl

Returns the current state of the dock control.

type

  TdxDockingState = (dsDestroyed, dsUndocked, dsHidden, dsDocked, dsFloating);

property DockState: TdxDockingState;

Description

Use the DockState property to determine the current state of the dock control.  The following values can be returned by this property.

Value	Description
dsUndocked	The dock control has no parent dock control (it is not docked to any control).  This can be achieved by calling the Undock method of the dock control.  The is the state for dock controls created at runtime before they have been docked or made to float.
dsHidden	This value can be returned in two cases.  First, if the dock control’s auto hide feature is enabled and it is hidden currently.  Please refer to the AutoHide property description for details on enabling this feature.  Second, when the dock control’s Visible property is set to False.
dsDocked	This value is returned if the dock control is currently visible and its immediate parent is not a float site.
dsFloating	This value is returned if the dock control is currently visible and its immediate parent is a float site.  Note that a dock control may be on a float site but with its immediate parent being a tab container or a side container.  In this case, the DockState property returns dsDocked.
dsDestroyed	Indicates that the control is no longer available.  This value is returned by dock controls before they are actually destroyed.  For instance, consider a tab container that is docked to a dock panel to form another tab container with other dock controls.  In this case, the tab container is destroyed when docking and a new one is created.  At the moment of docking, the tab container will not be actually destroyed, but its DockState property will return dsDestroyed indicating that the control is no longer available.

ReadOnly Property


TdxCustomDockControl.DockType

TdxCustomDockControl

Returns a value indicating how the dock control is aligned within its parent control.

type

  TdxDockingTypeEx = (dtNone, dtClient, dtLeft, dtTop, dtRight, dtBottom);

property DockType: TdxDockingTypeEx;

Description

Use the DockType property to determine how the dock control is aligned within its parent control.  This property can return the following values.

Value	Description
dtNone	The dock control has no parent control.  The dock control hasn’t been docked to any control or made to float.  Also, dock sites always return dtNone.
dtClient	The dock control occupies all the available area of its parent control.  This value is returned by • dock controls filling the area of a dock site; • layout sites; • dock controls whose immediate parent is a float site; • panels joined into a tab container; • controls maximized within side containers.
dtLeft	The control is docked to the left edge of its parent.
dtTop	The control is docked to the top edge of its parent.
dtRight	The control is docked to the right edge of its parent.
dtBottom	The control is docked to the bottom edge of its parent.

Suppose that dock controls are joined into a vertical or horizontal side container.  In this case, the DockType property of all controls that are before the active child (the maximized control) will return dtLeft or dtTop respectively.  As stated above, active children will return dtClient.  Controls that follow the active child will return dtRight or dtBottom respectively.  If none of the controls within a side container are maximized, the DockType property all controls will return dtLeft or dtTop.

ReadOnly Property


TdxCustomDockControl.DockZones

TdxCustomDockControl          See Also          Concepts

Returns the list of dock zones owned by this dock control.

property DockZones: TList;

Description

Each dock control owns a list of dock zones.  Dock zones specify rectangles within the dock control’s client area and the action performed when docking another control within a rectangle.  Please refer to the TdxZone class description and the Dock Zones topic for more information regarding dock zones.

You can use the DockZones property to add or remove dock zones.  Note that the order of dock zones in the collection is important, since they are processed in the order they appear in the collection.  For instance, if the first dock zone within the collection occupies the entire dock control’s client area, no other dock zones will be processed.  In other words, if a point is within more than one dock zone, the dock zone with a smaller index in the collection will be processed.

Note that the list of dock zones is recalculated each time the layout of dock controls changes.  Thus, if you need to modify the dock zone list, you need to perform the modification with every recalculation.  This can be achieved by handling the OnUpdateDockZones event.

ReadOnly Property


TdxCustomDockControl.FloatDockSite

TdxCustomDockControl          See Also          Concepts

Returns the float site where the dock control resides.

property FloatDockSite: TdxFloatDockSite;

Description

Use the FloatDockSite property to get the float site that owns the dock control.  Note that if the immediate parent of the dock control is not a float site, the property returns nil.  Thus, you can compare the property value to nil to determine whether the control’s immediate parent is a float site.  An alternative method is to compare the DockState property value to dsFloating.

When the control is visually floating, its FloatDockSite property can return nil.  This occurs, for instance, if a control is joined into a tab container that resides on a float site.  To obtain the owner float site in this case, you need to read the TopMostDockControl property value and convert it to the TdxFloatDockSite type.

To access the floating form settings, use the FloatForm property.

ReadOnly Property


TdxCustomDockControl.FloatForm

TdxCustomDockControl          See Also          Concepts

Gets the floating form where the dock control resides.

property FloatForm: TdxFloatForm;

Description

Use the FloatForm property to access the settings of the form where the dock control resides.  Note that if the dock control is not floating, the property returns nil.

The FloatForm property is useful if you need to change the form’s appearance, caption, etc.  For instance, the following sample code changes the style of all float forms so that they look like ordinary forms.  The OnCreateFloatSite event is handled for this purpose.

// Delphi

procedure TForm1.dxDockingManager1CreateFloatSite(

  Sender: TdxCustomDockControl; AFloatSite: TdxFloatDockSite);

begin

  with Sender.FloatForm do

  begin

   BorderStyle := bsSizeable;

   Icon.LoadFromFile('C:\Images\Icons\FloatFormIcon.ico');

  end;

end;

Note: if you need to set the captions of floating forms according to the dock controls contained within them, handle the OnSetFloatFormCaption event of the docking manager.  This event fires each time the layout of dock controls changes within a float site.

ReadOnly Property


TdxCustomDockControl.Font

TdxCustomDockControl          See Also

Specifies the font applied to the dock control’s text elements.

property Font: TFont;

Description

Use the Font property to specify the font applied to text elements of the dock control.  For panels, this property specifies the font used to paint their captions (if the ShowCaption property value is True) and panel labels when the auto hide feature is enabled (i.e. the AutoHide property value is True).  For tab containers, it also sets the font used to paint text within tabs.

Note that if the ManagerFont property value is True, the dock control uses the font specified by the Font property of the docking manager.  If there is no docking manager on the form, the Font property of the docking controller is used.  Please refer to the TdxDockingController property for details on the docking controller.

You can also specify default font settings for panels and sites of specific types.  Please refer to the Docking Manager Features topic for details.


TdxCustomDockControl.ImageIndex

TdxCustomDockControl

Specifies the index of the image associated with the dock control.

property ImageIndex: Integer;

Description

Use the ImageIndex property to specify the image associated with the dock control.  The image is specified by its index within the source image list.  If the ImageIndex property value is –1 or greater than the last available index, no image is associated with the control.

Images associated with panels are displayed within tabs when panels are joined into a tab container.  Also, these images are painted within panel labels when the auto hide feature is enabled.

The source image list is specified by the Images property of the docking manager.  If there is no docking manager on the form, the Images property of the docking controller is used.  Please refer to the TdxDockingController class description for details on the docking controller.

The default value of the ImageIndex property is -1.


TdxCustomDockControl.Images

TdxCustomDockControl          See Also          Concepts

Returns the image list that provides images for dock controls.

property Images: TImageList;

Description

Each dock control can be associated with an image using the ImageIndex property.  This property specifies the image by its index within the source image list.  If there is a docking manager component on the form, the source image list can be specified using its Images property.  Otherwise, you should use the Images property of the docking controller to set the image list.  Actually, the specified image list is stored in the Images property of the docking controller in any case.  The docking manager simply provides design-time access to it.

The Images property of a dock control simply provides access to the Images property of the docking controller.

ReadOnly Property


TdxCustomDockControl.LayoutDockSite

TdxCustomDockControl          See Also          Concepts

Provides access to the neighboring layout dock site.

property LayoutDockSite: TdxLayoutDockSite;

Description

When a control is docked to a dock site, a layout site is created to fill the area not occupied by the control.  You can use the LayoutDockSite property of the docked control to obtain its neighboring layout site.  This property allows you to modify the appearance and behavior of the layout site obtained or to access dock controls residing on it.

If the control has no neighboring layout site (it is floating or included within a tab container or side container), the LayoutDockSite property returns nil.

If you need to perform particular actions on layout sites as they are created or provide default property values you can:

•	Handle the OnCreateLayoutSite event of the docking manager.  It fires whenever a layout site is created in your application;

•	Handle the OnCreateLayoutSite event of a particular dock control.  It fires when a layout site is created for the dock control;

•	Use the DefaultLayoutSiteProperties property of the docking manager.

ReadOnly Property


TdxCustomDockControl.ManagerColor

TdxCustomDockControl          See Also          Concepts

Specifies whether the dock control uses the color specified by the docking manager.

property ManagerColor: Boolean;

Description

Use the ManagerColor property to specify whether the dock control should use the color provided by the docking manager.  This implies that changing the Color property of the docking manager sets the Color property of the dock control, thus providing centralized control over the dock controls’ appearance.

If the ManagerColor property is set to False, the color of the dock control is specified by its Color property.  The docking manager’s Color property value is ignored in this case.

Note: setting the ManagerColor property to True changes the Color property of the dock control to the value specified by the docking manager.  However, setting the ManagerColor property to False doesn’t restore the previous value of the Color property.

The default value of the ManagerColor property is True.


TdxCustomDockControl.ManagerFont

TdxCustomDockControl          See Also          Concepts

Specifies whether the dock control uses the font specified by the docking manager.

property ManagerFont: Boolean;

Description

Use the ManagerFont property to specify whether the dock control should use the font specified by the docking manager.  This implies that changing the Font property of the docking manager sets the Font property of the dock control, thus allowing you to provide centralized control over the dock controls’ appearance.

If the ManagerFont property is set to False, the font of the dock control is specified by its Font property.  The docking manager’s Font property value is ignored in this case.

Note: setting the ManagerFont property to True changes the Font property of the dock control to the value specified by the docking manager.  However, setting the ManagerFont property to False doesn’t restore the previous value of the Font property.

The default value of the ManagerFont property is True.


TdxCustomDockControl.OriginalHeight

TdxCustomDockControl          See Also

Gets the real height of the dock control.

property OriginalHeight: Integer;

Description

When a control is docked to a site, the site controls the control’s dimensions.  For instance, when docking a control to the left edge of a dock site, its height is changed to match the height of the site.  When a control floats again, its dimensions need to be restored.  For this purpose, the control’s dimensions while floating are stored in the OriginalHeight and OriginalWidth properties.  These specify the height and width of the control’s client area respectively.  Note that size restoring relates to dock panels and tab containers only.

Normally, you will have no need to use this property in applications.

ReadOnly Property


TdxCustomDockControl.OriginalWidth

TdxCustomDockControl          See Also

Gets the real width of the dock control.

property OriginalWidth: Integer;

Description

Please refer to the OriginalHeight property description for details.

ReadOnly Property


TdxCustomDockControl.ParentDockControl

TdxCustomDockControl

Returns the immediate parent of the dock control.

property ParentDockControl: TdxCustomDockControl;

Description

Use the ParentDockControl to access the immediate parent of the dock control.  If the control is not owned by a container, its immediate parent can be a dock site, a float site or a layout site.  Otherwise, the container is the immediate parent for the control.

If you need to access the top most parent of the dock control, use the TopMostDockControl property.

Child controls of a dock control can be accessed using the Children property.  The number of children is returned by the ChildCount property.

ReadOnly Property


TdxCustomDockControl.ParentForm

TdxCustomDockControl          See Also

Returns the form that owns the dock control.

property ParentForm: TCustomForm;

Description

When a dock control is created, it is associated with a form.  When creating a control at design-time, it is associated with the form in which it has been placed.  If creating a control via code, the associated form is specified by the constructor parameter.  After this has been done, the dock control becomes the associated form’s property.

The ParentForm property is used to obtain the form to which the dock control belongs.  Do not confuse the return value of this property with the float form where the control can reside.  To obtain the owning float form, use the FloatForm property.

Note that dock controls having different ParentForm property values cannot be docked to each other.

ReadOnly Property


TdxCustomDockControl.ResizeZones

TdxCustomDockControl          See Also          Concepts

Provides a list of resize zones owned by the dock control.

property ResizeZones: TList;

Description

Each dock control owns a list of resize zones.  These are TdxZone class descendants that specify where resizing is available.  By default, dock controls create their lists to provide all available resize zones and then update the lists each time the layout of dock controls change.

Each time a dock control updates its resize zones list, the OnUpdateResizeZones event is raised.  You can handle it to add your own zones or to delete those created by default.  Note that the order of zones in the list is important.  When a mouse pointer moves over a dock control, the control’s resize zones list is scanned to determine whether there is a resize zone under the pointer.  Zones with smaller indexes are processed first.  Once a zone residing under the mouse pointer is found, the search is stopped and this zone’s functionality is used to implement control resizing.


TdxCustomDockControl.ShowCaption

TdxCustomDockControl          See Also          Concepts

Specifies whether the dock control’s caption is visible.

property ShowCaption: Boolean;

Description

Use ShowCaption to change the dock control’s caption visibility.  Captions are supported by dock panels and tab containers.  For dock panels, captions display the string specified by the Caption property and a set of buttons as specified by the CaptionButtons property.  The caption displays the same information for tab containers except that the string is specified by the Caption property of the panel currently active.

If the ShowCaption property value is True, the dock control displays its caption when it is docked to a dock site or when it is in a side container.  If the ShowCaption property value is False, the caption is never displayed.

The image below shows a tab container with the ShowCaption property set to True and False respectively.

The default value of the ShowCaption property is True.


TdxCustomDockControl.SideContainer

TdxCustomDockControl          See Also          Concepts

Returns the owning side container.

property SideContainer: TdxSideContainerDockSite;

Description

The SideContainer property returns an object (i.e. value not nil) in the following cases:

•	The immediate parent (the ParentDockControl property) of the dock control is a side container;

•	The immediate parent of the dock control is a tab container, whose parent is a side container.

In these cases, the SideContainer property returns the side container found.

You can also access the owning tab container by reading the TabContainer property value.  If you are not sure whether the owner is a container or don’t know its type, use the Container property.

ReadOnly Property


TdxCustomDockControl.SideContainerIndex

TdxCustomDockControl          See Also          Concepts

Returns the position of the dock control within the owning side container.

property SideContainerIndex: Integer;

Description

The SideContainerIndex property value indicates:

•	The index of the dock control within its owning side container, if the side container is its immediate parent;

•	The index of the owning tab container within its owning side container.  This occurs if the immediate parent of the dock control is a tab container residing within a side container.

If neither condition above is satisfied, the SideContainerIndex property returns –1.

Note that if the immediate parent of the dock control is a side container, the SideContainerIndex property value coincides with the DockIndex property value.  If the immediate parent is a tab container, the DockIndex property will return the position of the control within the tab container.

ReadOnly Property


TdxCustomDockControl.SideContainerItem

TdxCustomDockControl          See Also          Concepts

Returns the dock control that owns it and is the immediate child of a side container.

property SideContainerItem: TdxCustomDockControl;

Description

If the dock control’s immediate parent is a side container, the SideContainerItem returns the dock control itself.  If the control’s parent is a tab container within a side container, the SideContainerItem returns the owning tab container.

Actually, the control returned by the SideContainerItem can also be obtained by reading the Children property value of the side container returned by the SideContainer property.  The value of the SideContainerIndex property must be passed to the Children property as the parameter.  Thus, the SideContainerItem property just simplifies the access.

ReadOnly Property


TdxCustomDockControl.TabContainer

TdxCustomDockControl          See Also          Concepts

Returns the owning tab container control.

property TabContainer: TdxTabContainerDockSite;

Description

Use the TabContainer property to access the tab container that owns this dock control.  Note that if the immediate parent of the dock control is not a tab container, the property returns nil.

If you are not sure whether the control is within a container or don’t know its type, use the Container property.  If you need to access the owning side container, use the SideContainer property.

ReadOnly Property


TdxCustomDockControl.TopMostDockControl

TdxCustomDockControl          See Also

Returns the topmost parent for the dock control.

property TopMostDockControl: TdxCustomDockControl;

Description

Use the TopMostDockControl property to obtain the topmost parent of the dock control.  If a dock control is not floating, the owning dock site is returned.  Otherwise, the property returns the owning float site.  For dock sites and float sites, the TopMostDockControl property returns nil.

If you need to access the immediate parent of a dock control, read its ParentDockControl property value.

ReadOnly Property


TdxCustomDockControl.UseDoubleBuffer

TdxCustomDockControl

Specifies whether controls paint non-client elements directly to the window or via a memory bitmap.

property UseDoubleBuffer: Boolean;

Description

Painting of controls can be performed in two ways:

•	paint directly on the underlying window.

•	first paint the control to a memory bitmap and then copy it to the window (double buffering).

The second method is quicker and is commonly used to avoid flicker when repainting the control.  However, it is more memory intensive.  Thus, it is recommended to use double buffering when target computers have a sufficient amount of free memory.

The dock control property manages how controls paint their client areas.  However, some dock controls can paint additional (non-client) elements, e.g. captions and tabs.  Painting of these elements is controlled by the UseDoubleBuffer property.  If its value is True, double buffering is used for painting these elements.  The way control paint their client area is specified by their DoubleBuffered property.

The default value of the UseDoubleBuffer property is True for dock panels, tab containers, side containers and dock sites.


TdxCustomDockControl.Activate

TdxCustomDockControl          See Also

Activates the current dock control.

procedure Activate: virtual;

Description

Call the Activate method to activate the current dock control.  Alternatively, you can change the docking controller’s ActiveDockControl property.  The controller can be obtained using the dxDockController function call.

The active control has the following points to note:

•	It is painted differently from all other controls in most of the view styles.  The current view style is specified by the ViewStyle property of the docking manager.

•	It is not hidden if its auto hide feature is enabled and the mouse cursor is outside its area.  See the AutoHide property description for details on the auto hide feature.

Handle the control’s OnActivate event or the dock control’s OnActivate event to perform additional actions when the control is activated.

Having access to the active control provides additional docking management abilities.  For instance, you can provide shortcuts to perform actions on the control currently active.

End-users can activate controls by clicking them or the controls residing within them.  Also, a control is activated if it is docked to other controls provided that the doActivateAfterDocking option is enabled.  This option can be accessed via the docking manager’s Options property.

Note:	if a control contained within a tab container is activated either by assigning the ActiveDockControl property or by calling the control’s Activate method, its owning tab container actually becomes the active control.  The assigned control is selected then within its tab container.  If a floating control is activated, its float form automatically becomes the topmost visible.


TdxCustomDockControl.CanActive

TdxCustomDockControl

Returns a value indicating whether the dock control can be activated.

function CanActive: Boolean; virtual;

Description

You can activate the control either by calling its Activate method or by changing the docking controller’s ActiveDockControl property.  The controller can be obtained using the dxDockController function call.  Active controls have a different appearance in some views.  To perform additional actions when a control becomes active handle the control’s OnActivate event.

The return value of the CanActive function indicates whether the control is allowed to be active.  As implemented in the TdxCustomDockControl class, this method simply returns False.  The TdxDockPanel and TdxTabContainerDockSite classes override this method to return True.

Normally, you will have no need to use this method in applications.


TdxCustomDockControl.CanAutoHide

TdxCustomDockControl          See Also

Returns a value indicating whether the control’s auto hide feature can be enabled.

function CanAutoHide: Boolean; virtual;

Description

When a panel or tab container is docked to a site, the auto hide feature can be enabled.  End-users enable it by pressing the auto hide button within the control’s caption (see the CaptionButtons property for details).  The feature can be enabled via code by setting the dock control’s AutoHide property to True.

The CanAutoHide method’s return value indicates whether the feature is currently available.  If this method returns True, the auto hide button is displayed within the control’s caption and setting the AutoHide property to True succeeds.

As implemented in the TdxCustomDockControl class, the CanAutoHide method simply returns False.  The TdxDockPanel, TdxTabContainerDockSite and TdxSideContainerDockSite classes override this method to return True when a control is docked to a site.

Normally, you will have no need to use this method in applications.


TdxCustomDockControl.CanDock

TdxCustomDockControl          See Also

Returns a value indicating whether the control can be docked to other controls.

function CanDock: Boolean; virtual;

Description

The value returned by the CanDock method indicates whether docking operations on the control are allowed.  In other words, it determines whether the control’s DockTo method can succeed.

As implemented in the TdxCustomDockControl class, the CanDock method simply returns False.  The TdxDockPanel and TdxContainerDockSite classes override this method to return True.

Most commonly, you will have no need to use this method in applications.


TdxCustomDockControl.CanDockHost

TdxCustomDockControl          See Also

Returns a value indicating whether controls can be docked to the control in the manner specified.

function CanDockHost(AControl: TdxCustomDockControl; AType: TdxDockingType): Boolean; virtual;

Description

The return value of the CanDockHost method indicates whether the specified control can be docked to the current control.  The docked control is specified by the AControl parameter.  The AType parameter specifies the manner in which the specified control is required to be docked.

The CanDockHost method is called internally when performing docking operations to check the operation’s validity.  Normally, you will have no need to use this method in applications.


TdxCustomDockControl.CanMaximize

TdxCustomDockControl          See Also

Returns a value indicating whether the dock control can be maximized.

function CanMaximize: Boolean; virtual;

Description

When dock controls are within a side container, they can be maximized to fill the entire container’s client area.  End-users can perform this by clicking the maximize button displayed within the control’s caption (see the CaptionButtons property for details).  This can also be performed via code by assigning the control’s DockIndex property value to the ActiveChildIndex property of the owning side container.

The CanMaximize method’s return value indicates whether the maximize button can be displayed within the control’s caption.  If this method returns True, the maximize button is displayed when the control is within a side container.

As implemented in the TdxCustomDockControl class, the CanMaximize method simply returns False.  The TdxDockPanel and TdxTabContainerDockSite classes override this method to return True when the control is within a side container.

Normally, you will have no need to use this method in applications.


TdxCustomDockControl.Close

TdxCustomDockControl          See Also          Concepts

Closes the dock control.

procedure Close;

Description

The behavior of the Close method depends on the control for which it is called and options specified by the Options property of the docking manager.  The list below describes possible actions performed by this method:

•	If the Close method is called for any dock control except tab containers, its behavior depends on the doFreeOnClose and doUndockOnClose options.  If the doFreeOnClose option is enabled, the control is destroyed when closed.  If the doUndockOnClose option is enabled, the control is undocked when closed (see the UnDock method description for details).  If neither of these options are enabled, the control is simply hidden (its Visible property is set to False).

•	If the Close method is called for a tab container, its behavior depends on the doTabContainerCanClose option.  If the option is enabled, the Close method closes the tab container as for other dock controls.  Otherwise, the method closes the active child of the tab container.


TdxCustomDockControl.DockTo

TdxCustomDockControl          See Also          Concepts

Docks the control to the specified dock control in the specified manner.

procedure DockTo(AControl: TdxCustomDockControl; AType: TdxDockingType; AIndex: Integer);

Description

Use the DockTo method to perform a docking operation on a dock control.  The AControl parameter specifies the control to which the current docking control will be docked.  The AType parameter specifies the manner in which the control will be docked.  It can either be docked to an edge of the target control or fill its entire client area.  The AIndex parameter specifies the target position of the control within the container where it is to be docked.  If docked to a tab container, this parameter specifies the index of the tab corresponding to the control.  If docked to a side container, it specifies the visual position of the control in the container.  Note that tabs are counted from left to right, the same as for controls within horizontal side containers.  In vertical side containers, controls are indexed from top to bottom.  Indexes are always zero-based.  If a negative index is specified, the control is docked to the last position within the container.  The same occurs if the specified index is greater than the last available.  After a control has been docked, you can determine its position within the container by reading the control’s DockIndex property value.

Note that docking is performed taking into account the AllowDock property of the control being docked and the AllowDockClients property of the target control.  If these properties do not allow the specified docking operation, the DockTo method does nothing.


TdxCustomDockControl.GetDockZoneAtPos

TdxCustomDockControl          See Also          Concepts

Gets the dock zone at the specified point, provided that the control can be docked to it.

function GetDockZoneAtPos(AControl: TdxCustomDockControl; pt: TPoint): TdxZone;

Description

Dock controls store a list of dock zones in their DockZones property.  The GetDockZoneAtPos method is used to obtain the dock zone residing under the specified point and capable of accepting the specified control.

The pt parameter specifies the search point and is specified in the dock control’s client coordinates.  If a dock zone is found, the method checks whether the control specified by the AControl parameter can be docked to it.  If so, the found zone is returned.  Otherwise, the GetDockZoneAtPos method returns nil.

Normally, you will have no need to use this method in applications.


TdxCustomDockControl.GetResizeZoneAtPos

TdxCustomDockControl          See Also          Concepts

Gets the resize zone located under the specified point.

function GetResizeZoneAtPos(pt: TPoint): TdxZone;

Description

Dock controls store a list of resize zones in their ResizeZones property.  The GetResizeZoneAtPos method is used to obtain the resize zone located under the specified point.  The point is specified in control’s client coordinates via the pt parameter.  If no zone is found at the specified position, the GetResizeZoneAtPos method returns nil.

Normally, you will have no need to use this method in applications.


TdxCustomDockControl.MakeFloating

TdxCustomDockControl          See Also          Concepts

Makes the control floating.

procedure MakeFloating();

procedure MakeFloating(XPos, YPos: Integer);

Description

Use the MakeFloating method to change the dock control's state to floating.  Note that if the control is within a floating container, it is undocked from the container so that it floats separately.

The MakeFloating method has two overloads.  If it is called without parameters, the method acts as if the end-user has double-clicked the control’s caption (or the tab corresponding to the control, if it is within a tab container).  The control is made to float with its previous floating size and close to its docking site.

If you need to specify a custom position for the control when floating, use MakeFloating’s second overload.  The XPos and YPos parameters specify the position of the top-left corner of the floating window.  These parameters represent screen coordinates.


TdxCustomDockControl.SetBounds

TdxCustomDockControl

Specifies the position and size of the dock control.

procedure SetBounds(ALeft, ATop, AWidth, AHeight: Integer); override;

Description

The SetBounds method overrides the base class method to implement size and/or position changes.  As implemented in the TdxCustomDockControl class, the ALeft and ATop parameters are not used.  The AWidth and AHeight parameters specify the new width and height of the control respectively.  When a control is docked to the left or right edge of a dock site or when it is in a horizontal side container, you can change the control’s width.  When a control is docked to a top or bottom edge of a dock site or when it is within a vertical side container, you can change its height.

To change the position and size of the control when it is floating, use the properties and methods of the float form where it resides.  This can be accessed using the FloatForm property, for instance.


TdxCustomDockControl.UnDock

TdxCustomDockControl          See Also          Concepts

Undocks the control.

procedure UnDock;

Description

Use the UnDock method if you need to undock the control from its parent control.  After the UnDock method is called, the control is not docked to any parent and, thus, is not displayed.  Note that this is not the same as just hiding the control by setting its Visible property to False.

The UnDock method is useful when you need to rearrange dock controls.  It is recommended that you undock all controls before performing rearrangement.  Otherwise, the layout may not be set properly.  For instance, if docking one panel to another in order to form a side container, you need to be sure that the target panel is not within a tab container.  If all controls are undocked before performing docking operations, you will have no need to worry about it.

Controls are also undocked when calling the Close method (or closing them using the close button) provided that the doUndockOnClose option is enabled.  This option can be accessed via the Options property of the docking manager.


TdxCustomDockControl.OnActivate

TdxCustomDockControl          See Also

Fires when a dock control is activated or deactivated.

type

  TdxActivateEvent = procedure(Sender: TdxCustomDockControl; Active: Boolean) of object;

property OnActivate: TdxActivateEvent;

Description

The currently active dock control is specified by the docking controller’s ActiveDockControl property.  The docking controller can be accessed using the dxDockingController function.  To activate a specific control, call its Activate.

End-users can activate controls by clicking their captions.  If the doActivateAfterDocking option is enabled, dock controls are automatically activated after performing docking operations.  This option can be accessed via the Options property of the docking manager.

When the active dock control is changed, the OnActivate event fires for the previously and currently active controls.  For the previously active control, the Active parameter returns False.  For the activated one, it returns True.  The Sender parameter identifies the control whose active state has been changed.

The OnActivate event can be used for display purposes or to help end-users when working with dock controls.  For instance, when a control is activated you can move focus to one of controls residing on it and display explanatory information within the status bar.

Switching between tabs within a tab container also fires the OnActivate event for the control’s immediate children.  To respond to switching between tabs, you can also handle the OnActiveChildChanged event of the tab container.

The following sample code shows how to use the OnActivate event to change the form’s caption when a dock control is activated or deactivated.  If activated, the form’s caption is set to the Caption property of the dock control.  Otherwise, it is set to the ‘Docking Demo’ string.

// Delphi

procedure TForm1.dxDockPanel1Activate(Sender: TdxCustomDockControl; Active: Boolean);

begin

  if Active then

    Sender.ParentForm.Caption := Sender.Caption

  else

    Sender.ParentForm.Caption := 'Docking Demo';

end;


TdxCustomDockControl.OnAutoHideChanged

TdxCustomDockControl          See Also          Concepts

Fires when the dock control’s auto hide feature is enabled or disabled.

type

  TdxDockControlNotifyEvent = procedure(Sender: TdxCustomDockControl) of object;

property OnAutoHideChanged: TdxDockControlNotifyEvent;

Description

The auto hide feature can be enabled by changing the AutoHide property.  End-users can enable or disable this feature by clicking the auto hide button within the dock control’s caption (see the CaptionButtons property description for details).  This also results in the AutoHide property value change.

Whenever the AutoHide property value changes, the OnAutoHideChanged event is raised.  Its Sender parameter identifies the appropriate dock control.

Note that you can specify the edge of the dock site where the control will be hidden when the auto hide feature is enabled.  Handle the OnGetAutoHidePosition event for this purpose.


TdxCustomDockControl.OnAutoHideChanging

TdxCustomDockControl          See Also          Concepts

Fires before the auto hide feature is enabled or disabled.

type

  TdxDockControlNotifyEvent = procedure(Sender: TdxCustomDockControl) of object;

property OnAutoHideChanging: TdxDockControlNotifyEvent;

Description

When the auto hide feature is activated or deactivated, an OnAutoHideChanging event is raised.  Note that the event fires before the control is actually switched to auto hide mode.  Thus, this event enables you to save any desired settings of controls residing within this dock control.  This capability is needed since certain settings may be lost as a result of enabling or disabling of the auto hide feature.  The reason is that the handle of the dock control changes when auto hide occurs.

The Sender parameter identifies the control whose auto hide feature is about to be enabled or disabled.

Note: to restore the settings saved by the OnAutoHideChanging event handler, handle the OnAutoHideChanged event.

For more information about persisting control settings please refer to the Persisting Settings of Controls Residing in Dock Panels topic.


TdxCustomDockControl.OnCanDocking

TdxCustomDockSite          See Also          Concepts

Enables you to control whether or not the dragged dock control can be docked to the current control.

type

  TdxCanDockingEvent = procedure(Sender, Source: TdxCustomDockControl; Zone: TdxZone; X, Y: Integer; var Accept: Boolean) of object;

property OnCanDocking: TdxCanDockingEvent;

Description

The OnCanDocking event fires repeatedly when dragging a dock control over the current control.  The event’s Sender parameter identifies the current control (the target).  The Source parameter is the control being dragged over.  The Accept parameter specifies whether the current control should accept the control being dragged.  Set this parameter to False to prohibit dropping.

The event provides three more parameter for greater control over docking operations.  The Zone parameter identifies the target dock zone.  You can read this zone’s settings to determine the docking type, for instance.  The X and Y parameters specify the current mouse pointer coordinates.  Note that these coordinates are set relative to the screen’s top-left corner.

Note: the OnCanDocking event is raised for the target control immediately after raising the OnDocking event for the source control.  The Accept parameter’s initial value depends on whether the source control’s OnDocking event handler allows dropping.  Thus, when handling the OnCanDocking event, you should first check the Accept parameter value.  If the parameter is set to False, the source control doesn’t allow dropping, so you should not change this parameter value to avoid breaking the docking logic specified by the source control.


TdxCustomDockControl.OnCanResize

TdxCustomDockControl          See Also          Concepts

Enables you to restrict control resizing to particular positions.

type

  TdxCanResizeEvent = procedure(Sender: TdxCustomDockControl; NewWidth, NewHeight: Integer; var Resize: Boolean) of object;

property OnCanResize: TdxCanResizeEvent;

Description

When a dock control is docked to an edge of a dock site or when it resides within a side container, you can resize it by dragging its border.  Before a dock control is actually resized, the OnCanResize event fires.  The Sender parameter identifies the control being resized.  The NewWidth and NewHeight parameters indicate the width and height that the control will have if the resizing operation is successful.  The Resize parameter specifies whether resizing to these dimensions is allowed.  If it is set to False, the resize operation is rejected and the control snaps back to its original size.

You can identify whether the control is being resized horizontally or vertically by reading its DockType property value.  If this property returns either dtLeft or dtRight, the control is being resized horizontally.  If either dtTop or dtBottom is returned, the control is being resized vertically.

The following sample code handles the OnCanResize event to change the dock control’s horizontal resizing behavior.  It allows control resizing only within the range of 100 and 200 pixels.  Also, it allows only widths divisible by 20.  (In other words, only the 100, 120, 140, 160, 180 and 200 pixels widths are allowed.)

// Delphi

procedure TForm1.dxDockPanel1CanResize(Sender: TObject; NewWidth, NewHeight: Integer; var Resize: Boolean);

begin

  with Sender as TdxCustomDockControl do

  begin

    if (DockType = dtLeft) or (DockType = dtRight) then

    begin

      if (NewWidth < 100) or (NewWidth > 200) then

        Resize := False;

      if NewWidth mod 20 <> 0 then

        Resize := False;

    end;

  end;

end;


TdxCustomDockControl.OnClose

TdxCustomDockControl          See Also

Fires when the dock control is closed.

type

  TdxDockControlNotifyEvent = procedure(Sender: TdxCustomDockControl) of object;

property OnClose: TdxDockControlNotifyEvent;

Description

Dock controls can be closed by calling their Close method.  End-users can do this by clicking the close button within the control’s caption or by clicking the close button of the floating window.  (Please refer to the CaptionButtons property for details on caption buttons.)

Whenever a dock control is closed the OnClose event is raised.  Its Sender parameter identifies the closed control.

Note that the OnClose event is actually raised before the control is closed.  Thus, even when the doUndockOnClose or doFreeOnClose options are enabled, the control isn’t undocked or destroyed until after the event handler has been executed.  These options are available via the Options property of the docking manager.


TdxCustomDockControl.OnCloseQuery

TdxCustomDockControl          See Also

Enables you to override the control’s behavior when it is being closed.

type

  TdxDockControlCloseQueryEvent = procedure(Sender: TdxCustomDockControl; var CanClose: Boolean) of object;

property OnClose: TdxDockControlNotifyEvent;

Description

End-users can close a dock control by clicking the close button within the control’s caption.  You can also close the control using code by calling its Close method.  In both cases, the OnCloseQuery event is raised before the control is actually closed.  Handle this event if you need to restrict control closing depending on conditions or if you require custom functionality.  If you only need to perform actions when closing a control, handle the OnClose event instead.

Use the event’s CanClose parameter to specify whether closing is allowed.  If you need to prevent the control closing depending on conditions, simply set this parameter to False when these are met.

The control being closed is identified by the Sender parameter.

The following sample code handles the OnCloseQuery event to implement custom closing behavior.  It stops the default behavior and, instead, the dock control is docked to the left edge of a dock site and its auto hide feature is enabled.

// Delphi

procedure TForm1.dxDockPanel1CloseQuery(Sender: TdxCustomDockControl; var CanClose: Boolean);

begin

  CanClose := False;

  Sender.DockTo(dxDockSite1, dtLeft, -1);

  Sender.AutoHide := True;

end;


TdxCustomDockControl.OnCreateFloatSite

TdxCustomDockControl          See Also          Concepts

Fires in response to float site creation.

type

  TdxCreateFloatSiteEvent = procedure(Sender: TdxCustomDockControl; AFloatSite: TdxFloatDockSite) of object;

property OnCreateFloatSite: TdxCreateFloatSiteEvent;

Description

When changing the state of a dock control to floating, its underlying float site is created.  This float site fills the complete client area of the float form in order to accommodate the dock control.  This is required since dock controls such as panels, tab containers and side containers cannot reside directly on forms.

The OnCreateFloatSite event fires each time the underlying float site is created for the dock control.  You can handle this event to perform custom initialization of the newly created float site.

The Sender parameter of the event identifies the dock control whose underlying float site is created.  The AFloatSite parameter returns the created float site.

Note: dock controls can be made to float by performing docking operations on them or by calling their MakeFloating method.


TdxCustomDockControl.OnCreateLayoutSite

TdxCustomDockControl          See Also          Concepts

Fires in response to layout site creation.

type

  TdxCreateLayoutSiteEvent = procedure (Sender: TdxCustomDockControl; ALayoutSite: TdxLayoutDockSite) of object;

property OnCreateLayoutSite: TdxCreateLayoutSiteEvent;

Description

When a control is docked to a dock site it becomes the dock site’s child control.  Also, a layout site is created and made a child of the dock site.  After this has been done, you can dock controls to the layout site.  If another dock control is docked to it, the layout site becomes the parent for the control and another layout site is created, etc.

Each time a layout site is created, the OnCreateLayoutSite event of its parent is raised.  The Sender parameter identifies the control that is the layout site’s parent.  The ALayoutSite parameter represents the layout site created.  Handle this event if you need to modify settings when creating layout sites.


TdxCustomDockControl.OnCreateSideContainer

TdxCustomDockControl          See Also          Concepts

Fires in response to side container creation.

type

  TdxCreateSideContainerEvent = procedure(Sender: TdxCustomDockControl; ASideContainer: TdxSideContainerDockSite) of object;

property OnCreateSideContainer: TdxCreateSideContainerEvent;

Description

When a dock control is docked to an edge of another control, a side container is created.  The OnCreateSideContainer event fires immediately after this has been done.  The Sender parameter of the event identifies the control to which another one has been docked.  The ASideContainer parameter identifies the side container created.  You can use the Children property of the object represented by this parameter to access all dock controls comprising the side container.

Handle the OnCreateSideContainer event if you need to perform particular initialization of the side container created.  Note that the event fires only if another dock control has been docked to it.  If the current control is docked to another one, the target control’s OnCreateSideContainer event is raised.


TdxCustomDockControl.OnCreateTabContainer

TdxCustomDockControl          See Also          Concepts

Fires in response to tab container creation.

type

  TdxCreateTabContainerEvent = procedure(Sender: TdxCustomDockControl; ATabContainer: TdxTabContainerDockSite) of object;

property OnCreateTabContainer: TdxCreateTabContainerEvent;

Description

When a dock control is docked to fill the client area of another control, a tab container is created.  The OnCreateTabContainer event is raised immediately after this has been done.  The Sender parameter identifies the control to which another control has been docked.  The ATabContainer parameter represents the tab container created.  You can use the Children property of the tab container to access all of its children.

Handle the OnCreateTabContainer event if you need to perform particular initialization when creating tab containers.  Note that the event fires for the control to which another control has been docked.  If the current dock control has been docked to another control to create a tab container, the target control’s OnCreateTabContainer event is raised.


TdxCustomDockControl.OnCustomDrawDockingSelection

TdxCustomDockControl          See Also          Concepts

Enables you to custom paint docking selections.

type

  TdxCustomDrawSelectionEvent = procedure(Sender: TdxCustomDockControl; DC: HDC; Zone: TdxZone; ARect: TRect; Erasing: Boolean; var Handled: Boolean) of object;

property OnCustomDrawDockingSelection: TdxCustomDrawSelectionEvent;

Description

The Sender parameter identifies the dock control being dragged.

The DC parameter specifies the handle to the display device context.

The ARect parameter specifies the potential position and size of the dock control relative to the top-left corner of the screen.

The AErasing parameter specifies whether to paint the docking selection or whether you need to erase the previously painted selection.

The Zone parameter identifies the dock zone of the target dock control that can currently accept the dragged control.  This parameter can be used to determine whether the control will be docked or left floating if the dragging operation completes now.  If the Zone parameter returns nil, the dock control will float if released.  Otherwise, it will be docked to another control.  If the Zone parameter value is not nil, you can read the target dock zone settings.  This can be used, for instance, to determine the edge of the target control to which the current one will be docked if released.

Use the Handled parameter value to specify whether default painting still needs to be performed.  Set this parameter to True if all painting has been done within the OnCustomDrawDockingSelection event handler.

Refer to the Docking Frame and Resizing Bar Custom Painting topic for more information and code examples.


TdxCustomDockControl.OnCustomDrawResizingSelection

TdxCustomDockControl          See Also          Concepts

Enables you to custom paint resizing bars.

type

  TdxCustomDrawSelectionEvent = procedure(Sender: TdxCustomDockControl; DC: HDC; Zone: TdxZone; ARect: TRect; Erasing: Boolean; var Handled: Boolean) of object;

property OnCustomDrawResizingSelection: TdxCustomDrawSelectionEvent;

Description

The Sender parameter identifies the dock control being resized.

The DC parameter specifies the handle to the display device context.

The ARect parameter specifies the position and size of the bar.  Note that this is the position and size that are used when for the default painting of the bar and you can use your own settings.  For instance, you can paint the bar with a different width.

The Erasing parameter specifies whether the event handler must erase the previously painted bar or paint it.

The Zone parameter represents the resize zone where the control resizing has been initiated.  You can use properties of the object returned by this parameter to obtain the initial position of the resize bar and to determine the resize direction.  Access the Rectangle and Direction properties of this object.

Use the Handled parameter to specify whether default painting needs to be performed.  If all the desired painting is implemented manually in the OnCustomDrawResizingSelection event, set this parameter to True.

Please refer to the Docking Frame and Resizing Bar Custom Painting topic for more information and code examples.


TdxCustomDockControl.OnDock

TdxCustomDockControl          See Also          Concepts

Fires immediately after a dock control has been docked to a site.

type

  TdxDockEvent = procedure(Sender, Site: TdxCustomDockControl; ADockType: TdxDockingType; AIndex: Integer) of object;

property OnDock: TdxDockEvent;

Description

Handle the OnDock event to perform actions immediately after docking a control to a site.  The docked control is identified by the Sender parameter.  The Site parameter represents the target site.

The ADockType parameter enables you to determine whether the control has been docked to an edge of the site (and which edge) or to its entire client area.  This parameter matches the DockType property of the docked control.  The AIndex parameter represents the index of the docked site within the container where it has been docked.  If the target site is not a side container or a tab container, the parameter value is –1.  Actually, this parameter matches the DockIndex property of the docked control.

Note that the OnDock event doesn’t fire if the control now floats or has been dragged from one floating position to another.  If you need to provide a response to such actions, handle the OnEndDocking event.


TdxCustomDockControl.OnDocking

TdxCustomDockControl          See Also          Concepts

Enables you to control whether the dragged dock control can be docked to the current target.

type

  TdxDockingEvent = procedure(Sender: TdxCustomDockControl; Zone: TdxZone; X, Y: Integer; var Accept: Boolean) of object;

property OnDocking: TdxDockingEvent;

Description

You can specify how the dock control can be docked to other controls using its AllowDock property.  Also, you can specify how other dock controls can be docked to it using its AllowDockClients property.  If you need a more flexible approach to specify whether a particular docking operation is allowed, handle the OnDocking event.

The OnDocking event fires repeatedly when the dock control is being dragged over another dock control.  The Sender parameter identifies the dragged control.  The Zone parameter represents the current target dock zone.  You can use properties of the object returned by this parameter to determine the docking type, for instance, by accessing the zone’s DockType property.  The target dock control can be obtained by reading the Owner property of the dock zone.

The X and Y parameters specify the current mouse pointer position (in screen coordinates).  To obtain the target site’s client coordinates, use its ScreenToClient method.  Note that the X and Y parameters are only useful if you need to restrict docking to certain areas of a dock site.

Use the Accept parameter to specify whether the current dock operation is allowed.  This parameter value is True by default.  Set it to False to prohibit the operation.

Note: after the OnDocking event is raised for a control, the OnCanDocking event is raised for the docking operation target.  Thus, the docking operation may still be cancelled by the target control even if it is allowed by the control being dragged.


TdxCustomDockControl.OnEndDocking

TdxCustomDockControl          See Also          Concepts

Fires immediately after a dragging operation on a dock control has been finished.

type

  TdxEndDockingEvent = procedure(Sender: TdxCustomDockControl; Zone: TdxZone; X, Y: Integer) of object;

property OnEndDocking: TdxEndDockingEvent;

Description

Handle the OnEndDocking event to perform specific actions when a dragging or docking operation on a dock control is finished.  For instance, if you perform some operations in the OnStartDocking event handler, the OnEndDocking event can be used to perform any necessary cleanup.  Also, you can use the OnStartDocking event to save settings of controls residing on panels.  This may be required since controls may lose settings when their underlying window is recreated, which takes place when performing docking operations.  For instance, the focused item in list view controls is reset in such cases.  The OnEndDocking event can be used then to restore those saved settings.

The Sender parameter identifies the control on which the operation has been performed.  The Zone parameter specifies the dock zone to which the control has been docked.  If the control has been made to float or is simply dragged from one floating position to another, this parameter returns nil.  Otherwise, you can use settings of the dock zone to obtain information about the docking operation performed.  The Owner and DockType properties can be used, for instance, to determine the target dock control and the docking type.

The X and Y parameters specify the mouse pointer coordinates at the moment dragging or docking was completed.


TdxCustomDockControl.OnEndResizing

TdxCustomDockControl          See Also          Concepts

Fires immediately after a resizing operation has been finished.

type

  TdxResizingEvent = procedure(Sender: TdxCustomDockControl; Zone: TdxZone; X, Y: Integer) of object;

property OnEndResizing: TdxResizingEvent;

Description

Handle the OnEndResizing event to perform specific actions when a resizing operation on the dock control is finished.  For instance, you can perform actions in the OnStartResizing event handler.  In this case, the OnEndResizing event can be used to perform any necessary cleanup.

The Sender parameter identifies the control on which the resizing operation has been performed.  The Zone parameter returns the resize zone that took part in the resizing process.  Use this parameter to obtain additional information about the resizing performed.  For instance, you can determine whether horizontal or vertical resizing has just finished.  Read the Direction property of the zone obtained for this purpose.

The X and Y parameters indicate the current mouse pointer position in screen coordinates.


TdxCustomDockControl.OnGetAutoHidePosition

TdxCustomDockControl          See Also          Concepts

Enables you to specify the container edge where the dock control is hidden when its auto hide feature is enabled.

type

  TdxGetAutoHidePosition = procedure(Sender: TdxCustomDockControl; var APosition: TdxAutoHidePosition) of object;

property OnGetAutoHidePosition: TdxGetAutoHidePosition;

Description

When end-users click the auto hide button of a dock control or when its AutoHide property is set to True, the auto hide feature is enabled.  A label corresponding to the control is then displayed at the nearest edge of the container.  Using the mouse over this label makes the control visible.  When the mouse pointer is not over this label or the control’s area, the control is hidden.

The OnGetAutoHidePosition event enables you to determine the edge where the label corresponding to the hidden control will appear.  The Sender parameter represents the control whose auto hide feature is enabled.  The APosition parameter specifies the edge of the container where the control must be hidden.  Read this parameter value to identify the edge currently assigned.  If you need to specify a different edge, set the appropriate value.

The following sample code uses the OnGetAutoHidePosition event handler.  It prevents the control from being hidden next to the top and right edges of the container.  If the position automatically specified is the top edge, the control is then hidden to the left edge.  If the right edge is specified automatically, the control is hidden to the bottom edge.

// Delphi

procedure TForm1.dxDockPanel1GetAutoHidePosition(Sender: TdxCustomDockControl; var APosition: TdxAutoHidePosition);

begin

  if APosition = ahpTop then

    APosition := ahpLeft;

  if APosition = ahpRight then

    APosition := ahpBottom;

end;


TdxCustomDockControl.OnLayoutChanged

TdxCustomDockControl          See Also          Concepts

Fires each time the control’s docking layout is changed.

type

  TdxDockControlNotifyEvent = procedure(Sender: TdxCustomDockControl) of object;

property OnLayoutChanged: TdxDockControlNotifyEvent;

Description

Each time the dock control is docked to another dock control, made to float or another dock control is docked to it, the OnLayoutChanged event is raised.  Handle this event if you need to perform dock control updates each time its docking layout is changed.

The Sender parameter of the event allows you to identify the control whose layout has changed.


TdxCustomDockControl.OnMakeFloating

TdxCustomDockControl          See Also          Concepts

Fires immediately after a dock control is made to float.

type

  TdxMakeFloatingEvent = procedure(Sender: TdxCustomDockControl; X, Y: Integer) of object;

property OnMakeFloating: TdxMakeFloatingEvent;

Description

A dock control can be made to float by end-users dragging it from a container dock site.  You can also do it in code by calling its MakeFloating method.  Each time a control is made to float, the OnMakeFloating event is raised.

The Sender parameter identifies the appropriate dock control.  The X and Y parameters specify the screen coordinates of the floating window.


TdxCustomDockControl.OnParentChanged

TdxCustomDockControl          See Also          Concepts

Fires immediately after the control’s parent has been changed.

type

  TdxDockControlNotifyEvent = procedure(Sender: TdxCustomDockControl) of object;

property OnParentChanged: TdxDockControlNotifyEvent;

Description

Handle the OnParentChanged event to provide the appropriate response to changing the parent of a dock control.  Generally, this event will be used to restore settings saved in the OnParentChanging event.  Please refer to this event description for details on when dock control parents are changed and why such changes must be processed.

The Sender parameter identifies the control whose parent has been changed.


TdxCustomDockControl.OnParentChanging

TdxCustomDockControl          See Also          Concepts

Fires before the parent of the dock control is changed.

type

  TdxDockControlNotifyEvent = procedure(Sender: TdxCustomDockControl) of object;

property OnParentChanging: TdxDockControlNotifyEvent;

Description

The parent of the dock control is changed as a result of docking operations or toggling the auto hide feature for the control.  As a result, the control’s handle changes.  This may lead to a loss of settings for controls residing on the dock control.  The OnParentChanging event enables you to save such settings.  These settings can then be restored in the OnParentChanged event handler.

The Sender parameter identifies the control whose parent has been changed.

For detailed information on persisting control settings, please refer to the Persisting Settings of Controls Residing in Dock Panels topic.


TdxCustomDockControl.OnResize

TdxCustomDockControl          See Also          Concepts

Fires immediately after the dock control has been resized.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnResize: TNotifyEvent;

Description

The OnResize event fires each time the width or height of the dock control has changed.  Handle this event if you need to update the control in response to dimension changes.

The Sender parameter identifies the appropriate dock control.

Note: if the dimensions of a dock control are changed by resizing its owning float form, the OnResize event fires repeatedly when dragging the float form’s edge or corner.


TdxCustomDockControl.OnResizing

TdxCustomDockControl          See Also          Concepts

Fires repeatedly when resizing the dock control.

type

  TdxResizingEvent = procedure(Sender: TdxCustomDockControl; Zone: TdxZone; X, Y: Integer) of object;

property OnResizing: TdxResizingEvent;

Description

Handle the OnResizing event if you need to perform actions during the dock control resizing process.  The event fires each time the width or height of the control is potentially changed.  Note that if you need to restrict resizing the control to specific dimensions, the OnCanResize event should be handled.  It has an additional parameter specifying whether resizing is allowed.

The Sender parameter of the event specifies the dock control being resized.  The Zone parameter identifies the resize zone where the resizing process has been initiated.  You can use the Direction property of this zone object to determine whether the dock control is being resized vertically or horizontally.  The Rectangle property can be used to obtain the initial zone position.  The X and Y parameters specify the current screen coordinates of the mouse pointer.  To obtain the control’s client coordinates, use the ScreenToClient method.


TdxCustomDockControl.OnRestoreDockPosition

TdxCustomDockControl          See Also          Concepts

Specify where the dock control is docked when its header is double-clicked.

type

  TdxDockPositionEvent = procedure(Sender: TdxCustomDockControl; var APosition: TdxDockPosition) of object;

property OnRestoreDockPosition: TdxDockPositionEvent;

Description

When a dock control is docked to a site, end-users can make it float by double-clicking its header.  At this The control’s original position is stored in a TdxDockPosition structure.  If the dock control’s caption is double-clicked again, the structure’s data is used to restore the control to its previous position.  However, you may wish to control this yourself by handling the OnRestoreDockPosition event.

The Sender parameter of the OnRestoreDockPosition event identifies the control whose previous position is being restored.  The APosition parameter provides information on the previous position of the dock control.  You can modify settings of the structure represented by this parameter to change the position.

Note that settings provided by the APosition parameter can also be changed by handling the OnStoreDockPosition event.  For instance, if a control is within a tab container, you can specify that it must be restored in the first position.  However, the actual arrangement of dock controls may change since the event was raised.  For instance, the tab container that owned this control may have been destroyed.  Thus, you may need to make additional changes to the saved control’s position when handling the OnRestoreDockPosition event.

The code below is an example of an OnRestoreDockPosition event handler.  The handler checks whether the dock control’s parent still exists.  If it has been destroyed already, the control is docked to the right edge of the dock site.  Such a situation can take place, for instance, if the dock control has been previously docked to a container site and all other controls have been undocked from the container.

// Delphi

procedure TForm1.dxDockPanel1RestoreDockPosition(Sender: TdxCustomDockControl; var APosition: TdxDockPosition);

begin

  if APosition.Parent = nil then

  begin

    APosition.Parent := dxDockSite1;

    APosition.DockType := dtRight;

  end;

end;


TdxCustomDockControl.OnStartDocking

TdxCustomDockControl          See Also          Concepts

Fires when a docking operation starts.

type

  TdxStartDockingEvent = procedure(Sender: TdxCustomDockControl; X, Y: Integer) of object;

property OnStartDocking: TdxStartDockingEvent;

Description

End-users can perform docking operations by pressing the dock control’s caption with the mouse and dragging it.  Once the dragging operation starts, the OnStartDocking event fires.  Handle it if you need to perform actions each time the end-user starts to dock a control.  If the actions performed require any cleanup, handle the OnEndDocking event.

The OnStartDocking event can be used, for instance, to store settings of control residing in panels.  This is useful, since controls may lose their settings when the underlying window is recreated, which takes place when performing docking operations.  The OnEndDocking event should be handled then to restore those saved settings.

The Sender parameter identifies the control being dragged.  The X and Y parameters identify the current screen coordinates of the mouse pointer.

Note: the OnStartDocking event is not raised if docking the control is via code.


TdxCustomDockControl.OnStartResizing

TdxCustomDockControl          See Also          Concepts

Fires when the resizing operation starts.

type

  TdxResizingEvent = procedure(Sender: TdxCustomDockControl; Zone: TdxZone; X, Y: Integer) of object;

property OnStartResizing: TdxResizingEvent;

Description

End-users can resize dock controls by dragging their borders.  Once the user has pressed the left mouse button while the cursor is over a border, the OnStartResizing event fires.  If the mouse button is released, the OnEndResizing event is raised.  Note that the actual resizing may not take place between these two events.  If you need to response to the actual resizing of a dock control, handle the OnResize event.

The Sender parameter of the OnStartResizing event identifies the control which is about to be resized.  The Zone parameter represents the resize zone where the resizing process has been started.  You can read its Direction property, for instance, to determine whether the control is resized vertically or horizontally.  The X and Y parameters specify the screen coordinates of the mouse pointer.


TdxCustomDockControl.OnStoreDockPosition

TdxCustomDockControl          See Also          Concepts

Enables you to store a custom docking position when undocking the control by double-clicking its caption.

type

  TdxDockPositionEvent = procedure(Sender: TdxCustomDockControl; var APosition: TdxDockPosition) of object;

property OnStoreDockPosition: TdxDockPositionEvent;

Description

If the doDblClickDocking option of the docking manager is enabled, end-users can change the state of dock controls by double-clicking their captions.  When a control is docked to a site, double-clicking its caption results in making it float.  At that time, the previous position of the dock control is saved to a TdxDockPosition structure.  You can handle the OnStoreDockPosition event to change these settings.  For instance, you can specify that the control must be placed in a different position within its owning tab container when restored.  However, when double-clicking the control’s caption once again, the actual arrangement of dock controls may have changed.  For instance, the control’s owning tab container may have been destroyed earlier.  In this case, you should handle the OnRestoreDockPosition event to correct the settings of the current control’s layout.

The Sender parameter of the OnStoreDockPosition event specifies the control whose position is being saved.  The APosition parameter contains the control’s original position.  You can modify this data if needed.

The sample code below handles the OnStoreDockPosition event to clear the control’s position information.  If the event is handled in such manner, the dock control can only be made to float using a double click on its caption.  Double-clicking the control’s caption when it is floating will have no effect.

// Delphi

procedure TForm1.dxDockPanel1StoreDockPosition(Sender: TdxCustomDockControl; var APosition: TdxDockPosition);

begin

  with APosition do

  begin

    Parent := nil;

    SiblingAfter := nil;

    SiblingBefore := nil;

  end;

end;


TdxCustomDockControl.OnUnDock

TdxCustomDockControl          See Also          Concepts

Fires immediately after the dock control has been undocked.

type

  TdxUnDockEvent = procedure(Sender, Site: TdxCustomDockControl) of object;

property OnUnDock: TdxUnDockEvent;

Description

Dock controls can be undocked by calling their UnDock method.  End-users can also undock controls by closing them, provided that the doUndockOnClose option is enabled.  This option can be accessed via the Options property of the docking manager.

Each time a control is undocked, its OnUnDock event is raised.  The Sender parameter of the event specifies the undocked control.  The Site parameter identifies the parent of the undocked control (the control, from which it has been undocked).


TdxCustomDockControl.OnUpdateDockZones

TdxCustomDockControl          See Also          Concepts

Enables you to provide custom dock zones for the dock control.

type

  TdxUpdateZonesEvent = procedure(Sender: TdxCustomDockControl; AZones: TList) of object;

property OnUpdateDockZones: TdxUpdateZonesEvent;

Description

Each control holds a list of dock zones in its DockZones property.  These zones specify where other controls can be docked and provide the docking functionality.  You can modify the list of zones directly via the property, if needed.  However, the list will be automatically recalculated each time the layout of dock controls changes.  Thus, dock controls provide the OnUpdateDockZones event so that you can modify the list each time it is automatically repopulated.

The Sender parameter of the OnUpdateDockZones event specifies the control whose dock zones list has been repopulated.  The AZones parameter provides access to the list of zones (to the DockZones property of the control).  You can add your own or delete zones, if needed.


TdxCustomDockControl.OnUpdateResizeZones

TdxCustomDockControl          See Also          Concepts

Enables you to provide custom resize zones for the dock control.

type

  TdxUpdateZonesEvent = procedure(Sender: TdxCustomDockControl; AZones: TList) of object;

property OnUpdateResizeZones: TdxUpdateZonesEvent;

Description

Each dock control stores a list of resize zones in its ResizeZones property.  These zones specify areas of the control where resizing can be initiated and implement resizing.  If you need to provide custom resize zones for a control, you can modify its ResizeZones property value as required.  However, the list of zones will be automatically repopulated each time the dock control’s layout is changed.  Thus, the OnUpdateResizeZones event is provided.  It fires each time the list of resize zones is repopulated, thus allowing you to update it as needed.

The Sender parameter of the OnUpdateResizeZones event specifies the control whose resize zones list is being repopulated.  The AZones parameter provides access to the list of zones (to the ResizeZones property).  You can add your own zones or delete them as needed.


TdxCustomDockControl.OnVisibleChanged

TdxCustomDockControl          See Also

Fires immediately after the dock control’s visibility has been changed.

type

  TdxDockControlNotifyEvent = procedure(Sender: TdxCustomDockControl) of object;

property OnVisibleChanged: TdxDockControlNotifyEvent;

Description

The visibility of a dock control can be changed using several methods.  First, you can use the Visible property of the control or its Show and Hide methods.  Also, the dock control becomes invisible when closing it, provided that the doFreeOnClose and doUndockOnClose options are disabled.  These options can be accessed via the Options property of the docking manager.  Finally, the visibility of the control changes when it is in auto hide mode.

Handle the OnVisibleChanged event to perform specific actions each time the dock control’s visibility has been changed.  The current state of the control can be obtained via its Visible property.

The Sender parameter of the event identifies the control whose visibility has been changed.


TdxCustomDockControl.OnVisibleChanging

TdxCustomDockControl          See Also

Fires before the visibility of the dock control is changed.

type

  TdxDockControlNotifyEvent = procedure(Sender: TdxCustomDockControl) of object;

property OnVisibleChanging: TdxDockControlNotifyEvent;

Description

Handle the OnVisibleChanging event if you need to perform specific actions before the dock control is hidden or made visible.  The control whose visible state is changed is returned by the Sender parameter of the event.

If you need to perform any actions immediately after the control’s visibility has been changed, handle the OnVisibleChanged event.  Please refer to this event’s description for details on how the visibility of dock controls can be changed.


TdxDockPosition type

Contains data about a dock control’s docking position and size.

type

  TdxDockPosition = record

    DockIndex: Integer;

    DockType: TdxDockingType;

    OriginalHeight: Integer;

    OriginalWidth: Integer;

    Parent: TdxCustomDockControl;

    SiblingAfter: TdxCustomDockControl;

    SiblingBefore: TdxCustomDockControl;

  end;

Description

Structures of type TdxDockPosition are used to save the state of a dock control when it is made to float and docked back to dock sites by double-clicking its caption.  Note that this functionality is only available if the doDblClickDocking option is enabled and this can be accessed via the docking manager’s Options property.

When saving and restoring the dock control’s position, the dock control’s OnStoreDockPosition and OnRestoreDockPosition events are raised respectively.  These events provide a parameter of the TdxDockPosition type.  Use this parameter to modify the settings automatically determined.

The DockIndex field of the structure represents the index of the dock control within its container.  This field value matches the DockIndex property of the dock control.  The DockType field specifies the manner in which the control is docked to its parent.  This field value matches the DockType property of the dock control.

The OriginalHeight and OriginalWidth fields specify the dock control’s dimensions while floating.  These field values match the OriginalHeight and OriginalWidth properties of the dock control.

The Parent, SiblingAfter and SiblingBefore fields of the TdxDockPosition structure are used to specify the dock control to which the control will be docked when its position is restored.  The Parent field specifies the parent dock control and matches the ParentDockControl property.  The SiblingBefore and SiblingAfter fields specify dock controls neighboring to the current one within the container site (either a tab container or a side container).  Note: if the dock control is not within a container site, the SiblingBefore and SiblingAfter fields are set to nil.  If the control is the first within the owning container, the SiblingBefore field is set to nil.  If it is the last one, nil is assigned to the SiblingAfter field.

When restoring the control’s position, the Parent field value is examined first.  If it is not nil, the control is docked to the specified parent.  Otherwise, the SiblingBefore and SiblingAfter fields are examined one after another.  If they are both nil, the dock control remains floating.


TdxDockingController
TdxDockingController Object

Hierarchy          Properties          Methods           See Also           Concepts

Provides centralized control over dock controls and docking operations.

Unit

dxDockControl

TdxDockingController = class(TObject)

Description

The TdxDockingController object is the center of docking functionality.  This object provides access to all the dock controls and docking managers in the application, provides information about the current docking or resizing operation and enables you to save or restore the dock controls layout.  One more important functionality aspect that is worth mentioning, is that the docking controller serves as the bridge between dock controls and dock managers.  When dock controls need to obtain their settings or raise the related manager’s event handlers, they delegate these tasks to the docking controller.  The docking controller finds the dock control’s related manager and performs the required task.  Please refer to the Docking Controller and Docking Managers topic for additional information.

The main members provided by the docking controller include:

•	the DockControls and DockManagers properties – provide access to all dock controls and docking managers in the application;

•	the ActiveDockControl property – specifies the active dock control;

•	the IsDocking, IsResizing, DockingDockControl and ResizingDockControl properties – enable you to determine whether a docking or resizing operation is being performed and to obtain the dock control involved in it;

•	the BeginUpdate and EndUpdate methods – enable you to perform batch layout modifications;

•	the GetDockControlAtPos, GetFloatDockSiteAtPos and GetNearestDockSiteAtPos methods – enable you to locate dock controls by their coordinates.

There is always a single instance of the TdxDockingController class in any application.  You can access this instance using the dxDockingController global function call.


TdxDockingController Hierarchy
Hierarchy

TObject

     |


Properties for TdxDockingController
TdxDockingController Properties

TdxDockingController          Legend

In TdxDockingController

ActiveDockControl

DockControlCount

DockControls

DockingDockControl

DockManagerCount

DockManagers

IsDocking

IsResizing

ResizingDockControl

SelectionBrush


Methods for TdxDockingController
TdxDockingController Methods

TdxDockingController          Legend

In TdxDockingController

AutoHideInterval

AutoHideMovingInterval

AutoHideMovingSize

AutoShowInterval

BeginUpdate

Color

Create

DefaultFloatSiteProperties

DefaultHorizContainerSiteProperties

DefaultLayoutSiteProperties

DefaultTabContainerSiteProperties

DefaultVertContainerSiteProperties

Destroy

DockZonesWidth

EndUpdate

Font

GetDockControlAtPos

GetFloatDockSiteAtPos

GetNearestDockSiteAtPos

Images

LoadLayoutFromIniFile

LoadLayoutFromRegistry

LoadLayoutFromStream

Options

ResizeZonesWidth

SaveLayoutToIniFile

SaveLayoutToRegistry

SaveLayoutToStream

SelectionFrameWidth

TabsScrollInterval

ViewStyle


TdxDockingController.ActiveDockControl

TdxDockingController          See Also

Specifies the currently active dock control.

property ActiveDockControl: TdxCustomDockControl;

Description

Use the ActiveDockControl property to specify the active dock control.  Alternatively, you can call the control’s Activate method.

The active control has the following points to note:

•	It is painted differently from all other controls in most of the view styles.  The current view style is specified by the ViewStyle property of the docking manager.

•	It is not hidden if its auto hide feature is enabled and the mouse cursor is outside its area.  See the TdxCustomDockControl.AutoHide property description for details on the auto hide feature.

You can handle the docking manager’s OnActiveDockControlChanged event or the dock control’s OnActivate event to perform actions when a control becomes active.

Having access to the active control provides additional docking management abilities.  For instance, you can provide shortcuts to perform actions on the control currently active.

End-users can activate controls by clicking them or the controls residing within them.  Also, a control is activated if it is docked to other controls provided that the doActivateAfterDocking option is enabled.  This option can be accessed via the docking manager’s Options property.

Note:	if a control contained within a tab container is activated either by assigning the ActiveDockControl property or by calling the control’s Activate method, its owning tab container actually becomes the active control.  The assigned control is selected then within its tab container.  If a floating control is activated, its float form automatically becomes the topmost visible.


TdxDockingController.DockControlCount

TdxDockingController          See Also

Returns the number of dock control in the application.

property DockControlCount: Integer;

Description

Use the DockControlCount property to determine the number of dock controls in the application.  This property can be used in combination with the DockControls property to traverse through dock controls.

Note that dock panels and dock sites are taken into account by the DockControlCount and DockControls properties.  For instance, if there is a single floating panel in the application, the DockControlCount property will return 2.  The reason is that actually there are two dock controls – the float site and the dock panel residing on it.

ReadOnly Property


TdxDockingController.DockControls

TdxDockingController          See Also

Provides indexed access to all dock controls in the application.

property DockControls[Index: Integer]: TdxCustomDockControl;

Description

Use the DockControls property to access dock controls.  This property can be used in combination with the DockControlCount property to traverse through all the dock controls in the application.  The index of the first available dock control is 0.  The last dock control’s index is the DockControlCount property value decremented by 1.

The following sample code traverses the dock controls to find all tab containers and to set them all to show tabs at the top:

// Delphi

var

  I: Integer;

  TabContainers: TList;

  TabContainer: TdxTabContainerDockSite;

// ...

TabContainers := TList.Create;

try

  for I := 0 to dxDockingController.DockControlCount - 1 do

  begin

    if dxDockingController.DockControls[I] is TdxTabContainerDockSite then

      TabContainers.Add(dxDockingController.DockControls[I]);

  end;

  for I := 0 to TabContainers.Count - 1 do

  begin

    TabContainer := TabContainers.Items[I];

    TabContainer.TabsPosition := tctpTop;

  end;

finally

  TabContainers.Free;

end;

ReadOnly Property


TdxDockingController.DockingDockControl

TdxDockingController          See Also

Returns the dock control currently being docked.

property DockingDockControl: TdxCustomDockControl;

Description

The DockingDockControl property is used to obtain the dock control being docked at the moment.  This property returns nil if no docking operations are currently being performed.  In this case, the IsDocking property returns False.

The DockingDockControl property can be used if you need to perform actions on the control being docked in response to some user action.  For instance, you may need to respond to key presses.  In this case, you need to check whether the IsDocking property returns True and if so, perform the desired actions on the control being docked.

If you need to perform actions as docking starts or finishes, handle the OnStartDocking and OnEndDocking events of dock controls.

ReadOnly Property


TdxDockingController.DockManagerCount

TdxDockingController          Concepts

Returns the number of docking manager components in the application.

property DockManagerCount: Integer;

Description

Use the DockManagerCount property to determine the number of TdxDockingManager components in the application.  This property can be used in combination with the DockManagers property to traverse through all the available docking managers.

ReadOnly Property


TdxDockingController.DockManagers

TdxDockingController          Concepts

Provides indexed access to docking manager components.

property DockManagers[Index: Integer]: TdxDockingManager;

Description

Each form can hold a single TdxDockingManager component.  Once such a component is placed onto a form, it is automatically added to the DockManagers collection.  Destroying a docking manager component results in the corresponding collection item being removed.

Use the DockManagers property to access the registered docking managers by their indexes.  The desired component’s index should be passed as the Index parameter.  Note that the first registered manager’s index is zero.  The last manager’s index is the DockManagerCount property value decremented by one.  Specifying an invalid index will raise an exception.

The DockManagers property can be used in combination with the DockManagerCount property to traverse through all the docking managers registered.  This can be used when you need to change settings for all controls in the application.  For instance, you may need to change the dock controls’ paint style and thus, will need to change each manager’s ViewStyle property.

ReadOnly Property


TdxDockingController.IsDocking

TdxDockingController          See Also

Returns a value indicating whether a docking operation is currently being performed.

property IsDocking: Boolean;

Description

The IsDocking property returns True if a dock operation is being performed on a control.  Otherwise, the property returns False.  If True is returned, the control being docked can be accessed via the DockingDockControl property.

If you need to perform actions as docking starts or finishes, handle the OnStartDocking and OnEndDocking events of dock controls.

ReadOnly Property


TdxDockingController.IsResizing

TdxDockingController          See Also

Returns a value indicating whether a resizing operation is currently being performed.

property IsResizing: Boolean;

Description

The IsResizing property returns True if a dock control is currently being resized.  The affected control can be obtained via the ResizingDockControl property.  If there is no resizing in progress, the IsResizing property returns False.

If you need to respond to starting or finishing a resizing operation, handle the OnStartResizing and OnEndResizing events of dock controls.

ReadOnly Property


TdxDockingController.ResizingDockControl

TdxDockingController          See Also

Returns the dock control currently being resized.

property ResizingDockControl: TdxCustomDockControl;

Description

The ResizingDockControl property is used to obtain the control currently being resized.  If no resizing operation is in progress, the property returns nil.  The IsResizing property returns False in this case.

If you need to respond to starting or finishing a resizing operation, handle the OnStartResizing and OnEndResizing events of dock controls.

ReadOnly Property


TdxDockingController.SelectionBrush

TdxDockingController          See Also           Concepts

Specifies the brush used to paint docking and resizing selections.

property SelectionBrush: TBrush;

Description

When docking a control, a frame displays its potential docked position.  When resizing, a bar indicates the potential position of the control’s edge.  These frames and bars are painted using the brush specified by the SelectionBrush property.  Note that this brush is actually inverted with respect to the background.  This makes erasing the previously painted frame or bar possible.  The inverted frame or bar is painted at the same position, resulting in restoring the initial colors.

If you need greater control over painting the docking frame or resizing bar, handle the OnCustomDrawDockingSelection and OnCustomDrawResizingSelection events of the docking manager.  If you need to provide custom painting of these elements for particular dock controls, handle their OnCustomDrawDockingSelection and OnCustomDrawResizingSelection events.

The following sample code changes the SelectionBrush property value to provide changed painting of the docking frames and resizing bars.

// Delphi

var SelectBrush: TBrush;

// ...

SelectBrush := TBrush.Create;

SelectBrush.Color := clBlack;

SelectBrush.Style := bsFDiagonal;

dxDockingController.SelectionBrush := SelectBrush;

The image below displays the result of the sample code execution.


TdxDockingController.AutoHideInterval

TdxDockingController

Returns the time interval that passes before auto hiding dock controls.

function AutoHideInterval(AForm: TCustomForm): Integer;

Description

This method’s return value is used for dock controls that reside on the form specified by the AForm parameter.  The method first tries to find the docking manager that provides settings for controls residing on the form specified.  If the manager exists, its AutoHideInterval property value is returned.  Otherwise, the method returns the dxAutoHideInterval constant value.


TdxDockingController.AutoHideMovingInterval

TdxDockingController

Returns the time interval that passes between docking control displacements when it slides from the hidden to visible state or vice versa.

function AutoHideMovingInterval(AForm: TCustomForm): Integer;

Description

This method’s return value is used for dock controls that reside on the form specified by the AForm parameter.  The method first tries to find the docking manager that provides settings for controls residing on the form specified.  If the manager exists, its AutoHideMovingInterval property value is returned.  Otherwise, the method returns the dxAutoHideMovingInterval constant value.


TdxDockingController.AutoHideMovingSize

TdxDockingController

Returns the sliding step for controls whose auto hide feature is enabled.

function AutoHideMovingSize(AForm: TCustomForm): Integer;

Description

This method’s return value is used for dock controls that reside on the form specified by the AForm parameter.  The method first tries to find the docking manager that provides settings for controls residing on the form specified.  If the manager exists, its AutoHideMovingSize property value is returned.  Otherwise, the method returns the dxAutoHideMovingSize constant value.


TdxDockingController.AutoShowInterval

TdxDockingController

Returns the time interval that passes before making auto hidden dock controls visible.

function AutoShowInterval(AForm: TCustomForm): Integer;

Description

This method’s return value is used for dock controls that reside on the form specified by the AForm parameter.  The method first tries to find the docking manager that provides settings for controls residing on the form specified.  If the manager exists, its AutoShowInterval property value is returned.  Otherwise, the method returns the dxAutoShowInterval constant value.


TdxDockingController.BeginUpdate

TdxDockingController

Prevents the dock controls layout from being updated until the EndUpdate method is called.

procedure BeginUpdate;

Description

The BeginUpdate and EndUpdate methods should be used in combination.  The first increments the internal counter (which is initially zero) by one.  The second decrements the counter.  Layout updates are only allowed while the counter value is zero.  Thus, you can use the BeginUpdate and EndUpdate methods to perform batch layout modifications.

Suppose you need to change the layout of dock controls via code by performing three sequential docking operations.  By default, the layout will be updated after each modification.  To avoid this, enclose your code into the BeginUpdate and EndUpdate method calls.  In this case, the layout will be updated only once which will result in a performance benefit.


TdxDockingController.Color

TdxDockingController

Returns the color of dock controls that use manager settings.

function Color(AForm: TCustomForm): TColor;

Description

This method’s return value is used for dock controls that reside on the form specified by the AForm parameter.  The method first tries to find the docking manager that provides settings for controls residing on the form specified.  If the manager exists, its Color property value is returned.  Otherwise, the method returns the clBtnFace value.

Note that the color returned is used by dock controls whose ManagerColor property value is True.


TdxDockingController.Create

TdxDockingController

Creates an instance of the TdxDockingController class.

constructor Create; virtual;

Description

The constructor is used to create and initialize a new TdxDockingController object.  Note that you don’t need to use this constructor in applications, since there is always a single instance of the docking controller available.  To access the docking controller, use the dxDockingController global function call.


TdxDockingController.DefaultFloatSiteProperties

TdxDockingController

Returns the default settings for float sites.

function DefaultFloatSiteProperties(AForm: TCustomForm): TdxFloatDockSiteProperties;

Description

This method’s return value is used for dock controls that reside on the form specified by the AForm parameter.  The method first tries to find the docking manager that provides settings for controls residing on the form specified.  If the manager exists, its DefaultFloatSiteProperties property value is returned.  Otherwise, the method returns a TdxFloatDockSiteProperties object with the default settings.


TdxDockingController.DefaultHorizContainerSiteProperties

TdxDockingController

Returns the default settings for horizontal side containers.

function DefaultHorizContainerSiteProperties(AForm: TCustomForm): TdxSideContainerDockSiteProperties;

Description

This method’s return value is used for dock controls that reside on the form specified by the AForm parameter.  The method first tries to find the docking manager that provides settings for controls residing on the form specified.  If the manager exists, its DefaultHorizContainerSiteProperties property value is returned.  Otherwise, the method returns a TdxSideContainerDockSiteProperties object with the default settings.


TdxDockingController.DefaultLayoutSiteProperties

TdxDockingController

Returns the default settings for layout sites.

function DefaultLayoutSiteProperties(AForm: TCustomForm): TdxLayoutDockSiteProperties;

Description

This method’s return value is used for dock controls that reside on the form specified by the AForm parameter.  The method first tries to find the docking manager that provides settings for controls residing on the form specified.  If the manager exists, its DefaultLayoutSiteProperties property value is returned.  Otherwise, the method returns a TdxLayoutDockSiteProperties object with the default settings.


TdxDockingController.DefaultTabContainerSiteProperties

TdxDockingController

Returns the default settings for tab containers.

function DefaultTabContainerSiteProperties(AForm: TCustomForm): TdxTabContainerDockSiteProperties;

Description

This method’s return value is used for dock controls that reside on the form specified by the AForm parameter.  The method first tries to find the docking manager that provides settings for controls residing on the form specified.  If the manager exists, its DefaultTabContainerSiteProperties property value is returned.  Otherwise, the method returns a TdxTabContainerDockSiteProperties object with the default settings.


TdxDockingController.DefaultVertContainerSiteProperties

TdxDockingController

Returns the default settings for vertical side containers.

function DefaultVertContainerSiteProperties(AForm: TCustomForm): TdxSideContainerDockSiteProperties;

Description

This method’s return value is used for dock controls that reside on the form specified by the AForm parameter.  The method first tries to find the docking manager that provides settings for controls residing on the form specified.  If the manager exists, its DefaultVertContainerSiteProperties property value is returned.  Otherwise, the method returns a TdxSideContainerDockSiteProperties object with the default settings.


TdxDockingController.Destroy

TdxDockingController

Destroys the TdxDockingController object.

destructor Destroy; override;

Description

The destructor is used to dispose of the docking controller and free its memory usage.  You have no need to use the destructor in applications.  The docking controller is destroyed automatically.


TdxDockingController.DockZonesWidth

TdxDockingController

Returns the default width of dock zones.

function DockZonesWidth(AForm: TCustomForm): Integer;

Description

This method’s return value is used for dock controls that reside on the form specified by the AForm parameter.  The method first tries to find the docking manager that provides settings for controls residing on the form specified.  If the manager exists, its DockZonesWidth property value is returned.  Otherwise, the method returns the dxDockZonesWidth constant value.


TdxDockingController.EndUpdate

TdxDockingController

Cancels the update lock established by the BeginUpdate method and forces an immediate layout update.

procedure EndUpdate;

Description

The EndUpdate method should be used in combination with the BeginUpdate method.  Please refer to the BeginUpdate method description for details.


TdxDockingController.Font

TdxDockingController

Returns the font settings for dock controls that use manager settings.

function Font(AForm: TCustomForm): TFont;

Description

This method’s return value is used for dock controls that reside on the form specified by the AForm parameter.  The method first tries to find the docking manager that provides settings for controls residing on the form specified.  If the manager exists, its Font property value is returned.  Otherwise, the method returns the default font settings for dock controls.

Note that the color returned is used by dock controls whose ManagerFont property value is True.


TdxDockingController.GetDockControlAtPos

TdxDockingController

Returns the dock control located at the specified screen coordinates.

function GetDockControlAtPos(pt: TPoint): TdxCustomDockControl;

Description

Use the GetDockControlAtPos method to obtain the dock control located at the specified coordinates.  The coordinates are specified relative to the top-left corner of the screen via the pt parameter.

First, the GetDockControlAtPos method obtains the control at the specified point.  If the control is a dock control or it has a dock control as a parent, the dock control found is returned.  If it is not a dock control and doesn’t have such a parent, the GetDockControlAtPos method returns nil.

The code below shows how to obtain the dock panel currently located under the mouse pointer.  The OnTimer event of the timer component is handled for this purpose.  This can be used, for instance, to display explanatory information about the panel  where the mouse is hovering.

// Delphi

procedure TForm1.Timer1Timer(Sender: TObject);

var DockControl: TdxCustomDockControl;

begin

  DockControl := dxDockingController.GetDockControlAtPos(Mouse.CursorPos);

  if DockControl = nil then Exit;

  if DockControl is TdxDockPanel then

  begin

    // perform actions on the panel found here

    // ...

  end;

end;


TdxDockingController.GetFloatDockSiteAtPos

TdxDockingController

Returns the float dock site whose float form’s caption is located under the specified point.

function GetFloatDockSiteAtPos(pt: TPoint): TdxCustomDockControl;

Description

The GetFloatDockSiteAtPos method returns nil if the specified point is not over a float form’s caption.  If it is over a float form’s caption, the form’s child float site is returned.  The test point is specified in screen coordinates via the pt parameter.


TdxDockingController.GetNearestDockSiteAtPos

TdxDockingController

Returns the dock site that can accept the dock control at the specified position.

function GetFloatDockSiteAtPos(pt: TPoint): TdxCustomDockControl;

Description

The GetNearestDockSiteAtPos method is used to manage dock sites whose AutoSize property is set to True.  Such dock sites can accept dock controls even when the mouse pointer is outside them.  This takes place if the following conditions are satisfied:

•	The dock site is aligned to the left, top, right or bottom edge of its parent control (form, frame, etc).

•	The dock site’s width or height is less than specified by the dxDockZonesWidth constant.  The dimension used is specified by the alignment type.  If the dock site is aligned to the top or bottom edge, its height is considered.  If it is aligned to the left or right edge, its width is considered.

The GetNearestDockSiteAtPos method scans through dock sites whose AutoSize property value is True and that are aligned to a container’s edge.  Note also, that only dock sites whose width or height (depending on the alignment type) is less than that specified by the dxDockZonesWidth constant are considered.  The bounding rectangle of such dock sites is expanded so that the appropriate dimension is equal to the required height or width.  If the modified bounding rectangle contains the point passed as the pt parameter, the method returns the dock site found and stops the search.

The image below illustrates the situation where a dock site can accept the dragged dock control while the mouse pointer isn’t pointing to the site.


TdxDockingController.Images

TdxDockingController

Returns the image list used by dock controls on a particular form.

function Images(AForm: TCustomForm): TImageList;

Description

This method’s return value is used for dock controls that reside on the form specified by the AForm parameter.  The method first tries to find the docking manager that provides settings for controls residing on the form specified.  If the manager exists, its Images property value is returned.  Otherwise, the method returns nil.


TdxDockingController.LoadLayoutFromIniFile

TdxDockingController

Loads the layout of dock controls from the specified file.

procedure LoadLayoutFromIniFile(AFileName: string; AForm: TCustomForm = nil);

Description

Use the LoadLayoutFromIniFile method to restore the layout of dock controls from a file.  The file is specified by its name and path via the AFileName parameter.  If the specified file doesn’t exist or is in use by another process, an exception is raised.  If the file doesn’t contain dock controls layout information, all dock panels become undocked.  Please refer to the dock control’s UnDock method description for details on undocking controls.

The method’s AForm parameter is optional.  If omitted or set to nil, this method restores the layout of all dock controls whose settings are stored within the specified file.  To restore the layout of dock controls that belong to a particular form, pass the desired form as this parameter.

Note: files containing the dock control’s layout can be created using the SaveLayoutToIniFile method.


TdxDockingController.LoadLayoutFromRegistry

TdxDockingController

Loads the layout of dock controls stored at the specified registry path.

procedure LoadLayoutFromRegistry(ARegistryPath: string; AForm: TCustomForm = nil);

Description

Use the LoadLayoutFromRegistry method to restore the layout of dock controls previously saved to a specific path in the registry using the SaveLayoutToRegistry method call.  The source registry path is specified by the ARegistryPath parameter.  If the specified path doesn’t exist or doesn’t contain dock controls layout settings, all dock panels become undocked.  Please refer to the dock control’s UnDock method description for details on undocking panels.

The method’s AForm parameter is optional.  If omitted or set to nil, this method restores the layout of all dock controls whose settings are stored within the specified file.  To restore the layout of dock controls that belong to a particular form, pass the desired form as this parameter.


TdxDockingController.LoadLayoutFromStream

TdxDockingController

Loads the layout of dock controls from the specified stream.

procedure LoadLayoutFromStream(AStream: TStream; AForm: TCustomForm = nil);

Description

Use the LoadLayoutFromStream method to restore the layout of dock controls previously saved to a stream using the SaveLayoutToStream method call.  The source stream is specified by the AStream parameter.  If the specified stream is nil, an exception is raised.  If the stream’s content is not dock controls layout information, all dock panels become undocked.  Please refer to the dock control’s UnDock method description for details on undocking panels.

Note: the LoadLayoutFromStream method reads information starting from the current position within the stream.  Thus, you may need to update the Position property of the source stream before calling the LoadLayoutFromStream method.

The method’s AForm parameter is optional.  If omitted or set to nil, this method restores the layout of all dock controls whose settings are stored within the specified file.  To restore the layout of dock controls that belong to a particular form, pass the desired form as this parameter.


TdxDockingController.Options

TdxDockingController

Returns the options specifying the behavior of dock controls on a particular form.

function Options(AForm: TCustomForm): TdxDockingOptions;

Description

This method’s return value is used for dock controls that reside on the form specified by the AForm parameter.  The method first tries to find the docking manager that provides settings for controls residing on the form specified.  If the manager exists, its Options property value is returned.  Otherwise, the method returns the default options set.


TdxDockingController.ResizeZonesWidth

TdxDockingController

Returns the default width of resize zones.

function ResizeZonesWidth(AForm: TCustomForm): Integer;

Description

This method’s return value is used for dock controls that reside on the form specified by the AForm parameter.  The method first tries to find the docking manager that provides settings for controls residing on the form specified.  If the manager exists, its ResizeZonesWidth property value is returned.  Otherwise, the method returns the dxResizeZonesWidth constant value.


TdxDockingController.SaveLayoutToIniFile

TdxDockingController

Saves the dock controls layout to the specified file.

procedure SaveLayoutToIniFile(AFileName: string; AForm: TCustomForm = nil);

Description

Use the SaveLayoutToIniFile method to save the layout of dock controls to a file.  The target file is specified by its name and path using the AFileName parameter.  If the path is not specified, the file is created within the same folder as the application’s executable file.  Note that if the file’s extension is not specified, it is automatically set to ‘ini’.  If an empty string is specified as the parameter, the ‘.ini’ file will be created.

The AForm parameter is optional.  If omitted or set to nil, the method saves the layout of all dock controls in the application.  To save the layout of dock controls residing on a particular form, pass the desired form as this parameter.

The saved dock controls layout can be restored using the LoadLayoutFromIniFile method.


TdxDockingController.SaveLayoutToRegistry

TdxDockingController

Saves the dock controls layout to the specified registry path.

procedure SaveLayoutToRegistry(ARegistryPath: string; AForm: TCustomForm = nil);

Description

Use the SaveLayoutToRegistry method to save the layout of dock controls to a specific registry path.  The target registry path is specified by the ARegistryPath parameter.  This is the sub path for the system’s registry root key (HKEY_CURRENT_USER by default).

The AForm parameter is optional.  If omitted or set to nil, the method saves the layout of all dock controls in the application.  To save the layout of dock controls residing on a particular form, pass the desired form as this parameter.

The saved dock controls layout can be restored using the LoadLayoutFromRegistry method.


TdxDockingController.SaveLayoutToStream

TdxDockingController

Saves the layout of dock controls to the specified stream.

procedure SaveLayoutToStream(AStream: TStream; AForm: TCustomForm = nil);

Description

Use the SaveLayoutToStream method to save the layout of dock controls to a stream.  The target stream is specified by the AStream parameter.  If the specified parameter value is nil, an exception is raised.  Note also, that if the specified stream is a file stream, the SaveLayoutToStream method call results in creating a file with the same content as if using the SaveLayoutToIniFile method.

The AForm parameter is optional.  If omitted or set to nil, the method saves the layout of all dock controls in the application.  To save the layout of dock controls residing on a particular form, pass the desired form as this parameter.

The saved dock controls layout can be restored using the LoadLayoutFromStream method.


TdxDockingController.SelectionFrameWidth

TdxDockingController

Returns the default width of the pen used to paint the docking frame and resizing bar.

function SelectionFrameWidth(AForm: TCustomForm): Integer;

Description

This method’s return value is used for dock controls that reside on the form specified by the AForm parameter.  The method first tries to find the docking manager that provides settings for controls residing on the form specified.  If the manager exists, its SelectionFrameWidth property value is returned.  Otherwise, the method returns the dxSelectionFrameWidth constant value.


TdxDockingController.TabsScrollInterval

TdxDockingController

Returns the scrolling interval for tabs.

function TabsScrollInterval(AForm: TCustomForm): Integer;

Description

This method’s return value is used for dock controls that reside on the form specified by the AForm parameter.  The method first tries to find the docking manager that provides settings for controls residing on the form specified.  If the manager exists, its TabsScrollInterval property value is returned.  Otherwise, the method returns the dxTabsScrollInterval constant value.


TdxDockingController.ViewStyle

TdxDockingController

Returns the view style of dock controls residing on a particular form.

function ViewStyle(AForm: TCustomForm): TdxDockingViewStyle;

Description

This method’s return value is used for dock controls that reside on the form specified by the AForm parameter.  The method first tries to find the docking manager that provides settings for controls residing on the form specified.  If the manager exists, its ViewStyle property value is returned.  Otherwise, the method returns the vsStandard value.


TdxCustomDockSite
TdxCustomDockSite Object

Hierarchy          Properties          Methods          Events          Concepts

Serves as the base for dock controls capable of holding other dock controls.

Unit

dxDockControl

TdxCustomDockSite = class(TdxCustomDockControl)

Description

The TdxCustomDockControl class (the common ancestor for all dock controls) has two direct descendants.  The first is the TdxDockPanel class that represents a dock panel – the main building block of docking applications.  Another descendant is the TdxCustomDockSite class.  This class represents the common ancestor for all dock controls that can hold other dock controls.  Its descendants consist of dock sites, layout sites, float sites, tab containers and side containers.  Please refer to the Dock Controls Hierarchy topic for details.

All descendants of the TdxCustomDockSite class just hold dock controls as their children.  Thus, this class raises an exception when attempting to insert a control that is not a TdxCustomDockControl descendant.


TdxCustomDockSite Hierarchy
Hierarchy

TCustomControl

     |

TdxCustomDockControl

     |


Properties for TdxCustomDockSite
TdxCustomDockSite Properties

TdxCustomDockControl          Legend

Derived from TdxCustomDockControl

Active

AllowDock

AllowDockClients

AllowFloating

AutoHide

AutoHideControl

AutoHideHostSite

Caption

CaptionButtons

ChildCount

Children

Color

Container

Controller

Dockable

DockIndex

DockLevel

DockState

DockType

DockZones

FloatDockSite

FloatForm

Font

ImageIndex

Images

LayoutDockSite

ManagerColor

ManagerFont

OriginalHeight

OriginalWidth

ParentDockControl

ParentForm

ResizeZones

ShowCaption

SideContainer

SideContainerIndex

SideContainerItem

TabContainer

TopMostDockControl

UseDoubleBuffer


Methods for TdxCustomDockSite
TdxCustomDockSite Methods

TdxCustomDockControl          Legend

Derived from TdxCustomDockControl

Activate

CanActive

CanAutoHide

CanDock

CanDockHost

CanMaximize

Close

DockTo

GetDockZoneAtPos

GetResizeZoneAtPos

MakeFloating

SetBounds

UnDock


Events for TdxCustomDockSite
TdxCustomDockSite Events

TdxCustomDockControl          Legend

Derived from TdxCustomDockControl

OnActivate

OnAutoHideChanged

OnAutoHideChanging

OnCanDocking

OnCanResize

OnClose

OnCloseQuery

OnCreateFloatSite

OnCreateLayoutSite

OnCreateSideContainer

OnCreateTabContainer

OnCustomDrawDockingSelection

OnCustomDrawResizingSelection

OnDock

OnDocking

OnEndDocking

OnEndResizing

OnGetAutoHidePosition

OnLayoutChanged

OnMakeFloating

OnParentChanged

OnParentChanging

OnResize

OnResizing

OnRestoreDockPosition

OnStartDocking

OnStartResizing

OnStoreDockPosition

OnUnDock

OnUpdateDockZones

OnUpdateResizeZones

OnVisibleChanged

OnVisibleChanging


TdxDockSite
TdxDockSite Object

Hierarchy          Properties          Methods          Events          Concepts

Represents a dock site.

Unit

dxDockControl

TdxDockSite = class(TdxCustomDockSite)

Description

Dock controls can be either floating or docked.  To enable end-users to dock controls to a form, you must place a TdxDockSite control on the form (create a dock site).  This control can accept only dock controls.  Attempts to place any other control on a dock site raise an exception.  Dock controls can be docked to any edge of a dock site or fill its entire client area (provided that dock types are not prohibited by the AllowDockClients property of the dock site).

When dock controls are floating, a float site represented by the TdxFloatDockSite class is automatically created for them.

Unlike the float site, dock sites provide an auto hide functionality for their dock controls.  Please refer to the AutoHide property of dock controls for details on this feature.  The TdxDockSite class introduces the ShowingControl property that allows you to show and hide controls via code.  Also, you can handle the OnShowControl and OnHideControl events to respond dock control visibility changes.


TdxDockSite Hierarchy
Hierarchy

TCustomControl

     |

TdxCustomDockControl

     |

TdxCustomDockSite

     |


Properties for TdxDockSite
TdxDockSite Properties

TdxDockSite          Legend

In TdxDockSite

AutoSize

AutoSizeClientControl

ShowingControl

Derived from TdxCustomDockControl

Active

AllowDock

AllowDockClients

AllowFloating

AutoHide

AutoHideControl

AutoHideHostSite

Caption

CaptionButtons

ChildCount

Children

Color

Container

Controller

Dockable

DockIndex

DockLevel

DockState

DockType

DockZones

FloatDockSite

FloatForm

Font

ImageIndex

Images

LayoutDockSite

ManagerColor

ManagerFont

OriginalHeight

OriginalWidth

ParentDockControl

ParentForm

ResizeZones

ShowCaption

SideContainer

SideContainerIndex

SideContainerItem

TabContainer

TopMostDockControl

UseDoubleBuffer


Methods for TdxDockSite
TdxDockSite Methods

TdxDockSite          Legend

Derived from TdxCustomDockControl

Activate

CanActive

CanAutoHide

CanDock

CanDockHost

CanMaximize

Close

DockTo

GetDockZoneAtPos

GetResizeZoneAtPos

MakeFloating

SetBounds

UnDock


Events for TdxDockSite
TdxDockSite Events

TdxDockSite          Legend

In TdxDockSite

OnHideControl

OnShowControl

Derived from TdxCustomDockControl

OnActivate

OnAutoHideChanged

OnAutoHideChanging

OnCanDocking

OnCanResize

OnClose

OnCloseQuery

OnCreateFloatSite

OnCreateLayoutSite

OnCreateSideContainer

OnCreateTabContainer

OnCustomDrawDockingSelection

OnCustomDrawResizingSelection

OnDock

OnDocking

OnEndDocking

OnEndResizing

OnGetAutoHidePosition

OnLayoutChanged

OnMakeFloating

OnParentChanged

OnParentChanging

OnResize

OnResizing

OnRestoreDockPosition

OnStartDocking

OnStartResizing

OnStoreDockPosition

OnUnDock

OnUpdateDockZones

OnUpdateResizeZones

OnVisibleChanged

OnVisibleChanging


TdxDockSite.AutoSize

TdxDockSite

Specifies whether the dock site is automatically resized to fit the size of dock controls placed on it.

property AutoSize: Boolean;

Description

By default, when docking a control to a dock site, the control’s size is changed to fit the dock site’s size.  If the control is docked to the top or bottom edge, its width is modified.  If it is docked to the left or right edge, the control is resized vertically.  Finally, if docked to fill the entire dock site’s area, the control is resized in both directions.

Sometimes, you may need to change this default behavior.  This can be done by setting the AutoSize property to True.  In this case, dock sites are resized to fit the dock control placed on it.  This enables you, for instance, to create an extremely narrow dock site and align it to the left or right edge of the form.  When a control is docked to the site, it will be automatically resized horizontally to fit the docked control’s width.  Note that when enabling the auto hide feature for the docked control, the site will revert to its original size.  Thus, it will never occupy any unused space.

Note: you cannot set the AutoSize property to True, when the dock site already has control(s) docked to it.

The default value of the AutoSize property is False.


TdxDockSite.AutoSizeClientControl

TdxDockSite

Returns the dock control that specifies the dimensions of the dock site.

property AutoSizeClientControl: TdxCustomDockControl;

Description

When the AutoSize property of a dock site is set to True, the dock site is resized to fit controls placed on it.  In this case, the AutoSizeClientControl property returns the dock control docked to the site.  This control’s dimensions specify the dock site’s current dimensions.

If there is no control docked to the dock site or if the site’s AutoSize property value is False, the AutoSizeClientControl property returns nil.


TdxDockSite.ShowingControl

TdxDockSite          See Also          Concepts

Enables you to show and hide those controls with the auto hide feature enabled.

property ShowingControl: TdxCustomDockControl;

Description

You can enable the auto hide feature for a control by setting its AutoHide property to True.  In this case, the control will be automatically hidden unless it is active or the mouse pointer is over it.  A label referencing the control will be displayed at the dock site’s edge.  Pointing to this label with the mouse makes the control visible.

You can also change such control visibility via code.  The ShowingControl property is used for this purpose.  Assign a dock control to this property to make it visible.  The control previously shown is hidden in this case.  If you need to hide all auto hide enabled dock controls, set the ShowingControl property to nil.

If the dock control’s auto hide feature is not enabled, assigning this control to the ShowingControl property has no effect.


TdxDockSite.OnHideControl

TdxDockSite          See Also          Concepts

Fires when an auto hide enabled dock control gets hidden.

type

  TdxAutoHideControlEvent = procedure(Sender: TdxDockSite; AControl: TdxCustomDockControl) of object;

property OnHideControl: TdxAutoHideControlEvent;

Description

Dock controls with their auto hide feature enabled are automatically hidden when the mouse pointer is not over them or their referencing label, provided that the control is not active.  The control can also be hidden by assigning nil to the ShowingControl property.  In either case, the OnHideControl event is raised.

Handle OnHideControl to provide a proper response to hiding an auto hide enabled dock control.  For instance, if you handle the OnShowControl event, you can use the OnHideControl event to perform any necessary cleanup.

The Sender parameter of the OnHideControl event identifies the controlling dock.  The AControl parameter specifies the hidden control.


TdxDockSite.OnShowControl

TdxDockSite          See Also          Concepts

Fires when an auto hide enabled dock control becomes visible.

type

  TdxAutoHideControlEvent = procedure(Sender: TdxDockSite; AControl: TdxCustomDockControl) of object;

property OnShowControl: TdxAutoHideControlEvent;

Description

Dock controls with their auto hide feature enabled can be made visible by pointing to their corresponding labels with the mouse pointer.  You can also make such a control visible using code by assigning it to the ShowingControl property of the owning dock site.  In both cases, the OnShowControl event is raised.

Handle the OnShowControl event if you need to perform actions each time a dock control becomes visible.  If you need to respond to hiding the control, handle the OnHideControl event.

The Sender parameter of the OnShowControl event specifies the dock site where the control being shown resides.  The AControl parameter identifies the dock control itself.

The code below handles the OnShowControl event to activate the control being shown.  In this case, the control being shown will not be automatically hidden when the mouse pointer leaves it.  End-users will have to click outside the control to hide it again.

// Delphi

procedure TForm1.dxDockSite1ShowControl(Sender: TObject; AControl: TdxCustomDockControl);

begin

  dxDockingController.ActiveDockControl := AControl;

end;

Alternatively, you can call the control’s Activate method as shown in the following code snippet which is equivalent to the above code.

// Delphi

procedure TForm1.dxDockSite1ShowControl(Sender: TObject; AControl: TdxCustomDockControl);

begin

  AControl.Activate;

end;


TdxFloatDockSite
TdxFloatDockSite Object

Hierarchy          Properties          Methods          Events          Concepts

Represents a float site.

Unit

dxDockControl

TdxFloatDockSite = class(TdxCustomDockSite)

Description

When a dock control is made to float, an underlying float site is created for it.  The float site occupies the entire client area of the parent float form.  The dock control, in turn, occupies the entire client area of the underlying float site.  Unlike a dock site, the float site doesn’t allow docking of controls to its edges and doesn’t provide an auto hiding facility.  Controls can only be docked to the child control of the float site thus forming either a tab container or a side container.  The container created becomes the float site’s child and then occupies its entire area.

You can access the child of the float site using the Child property.  The OnSetFloatFormCaption event enables you to assign a caption to the float form where the site resides.

Note that the float site is destroyed each time its child is docked to a dock site.  If the dock site is made to float again, a new float site is created.


TdxFloatDockSite Hierarchy
Hierarchy

TCustomControl

     |

TdxCustomDockControl

     |

TdxCustomDockSite

     |


Properties for TdxFloatDockSite
TdxFloatDockSite Properties

TdxFloatDockSite          Legend

In TdxFloatDockSite

Child

FloatHeight

FloatLeft

FloatTop

FloatWidth

Derived from TdxCustomDockControl

Active

AllowDock

AllowDockClients

AllowFloating

AutoHide

AutoHideControl

AutoHideHostSite

Caption

CaptionButtons

ChildCount

Children

Color

Container

Controller

Dockable

DockIndex

DockLevel

DockState

DockType

DockZones

FloatDockSite

FloatForm

Font

ImageIndex

Images

LayoutDockSite

ManagerColor

ManagerFont

OriginalHeight

OriginalWidth

ParentDockControl

ParentForm

ResizeZones

ShowCaption

SideContainer

SideContainerIndex

SideContainerItem

TabContainer

TopMostDockControl

UseDoubleBuffer


Methods for TdxFloatDockSite
TdxFloatDockSite Methods

TdxFloatDockSite          Legend

Derived from TdxCustomDockControl

Activate

CanActive

CanAutoHide

CanDock

CanDockHost

CanMaximize

Close

DockTo

GetDockZoneAtPos

GetResizeZoneAtPos

MakeFloating

SetBounds

UnDock


Events for TdxFloatDockSite
TdxFloatDockSite Events

TdxFloatDockSite          Legend

In TdxFloatDockSite

OnSetFloatFormCaption

Derived from TdxCustomDockControl

OnActivate

OnAutoHideChanged

OnAutoHideChanging

OnCanDocking

OnCanResize

OnClose

OnCloseQuery

OnCreateFloatSite

OnCreateLayoutSite

OnCreateSideContainer

OnCreateTabContainer

OnCustomDrawDockingSelection

OnCustomDrawResizingSelection

OnDock

OnDocking

OnEndDocking

OnEndResizing

OnGetAutoHidePosition

OnLayoutChanged

OnMakeFloating

OnParentChanged

OnParentChanging

OnResize

OnResizing

OnRestoreDockPosition

OnStartDocking

OnStartResizing

OnStoreDockPosition

OnUnDock

OnUpdateDockZones

OnUpdateResizeZones

OnVisibleChanged

OnVisibleChanging


TdxFloatDockSite.Child

TdxFloatDockSite          See Also

Returns the dock control residing in the float site.

property Child: TdxCustomDockControl;

Description

Float sites always have a single child dock control.  This child control occupies the entire client area of the site.  When docking other controls to the float site, they are actually docked to the site’s child control.  As a result, either a tab container or a side container is created.  The new container becomes the float site’s child.

The Child property can be used to obtain the float site’s child.  Children of the dock control obtained can be accessed via its Children property.

ReadOnly Property


TdxFloatDockSite.FloatHeight

TdxFloatDockSite          See Also

Specifies the child dock control’s height.

property FloatHeight: Integer;

Description

When a dock control is floating (resides on a float site), changing this control’s Height property has no effect.  The reason is that the control is client aligned on its parent site, which is client aligned within the float form.  To change a floating control’s height, you should use the FloatHeight property of the owning float site.  This property actually sets the float form’s client height.

Use a control’s FloatDockSite property to access its parent float site.


TdxFloatDockSite.FloatLeft

TdxFloatDockSite          See Also

Specifies the horizontal coordinate of the float form.

property FloatLeft: Integer;

Description

The FloatLeft property can be used to specify the horizontal coordinate of the float form’s top-left corner.  The coordinate is set relative to the left edge of the screen.

The FloatLeft property is used mostly to save and restore the float site’s layout.  If you need to modify the settings of the float form, you can access it using the FloatForm property of the float site.


TdxFloatDockSite.FloatTop

TdxFloatDockSite          See Also

Specifies the vertical coordinate of the float form.

property FloatTop: Integer;

Description

The FloatTop property can be used to specify the vertical coordinate of the float form’s top-left corner.  The coordinate is set relative to the top edge of the screen.

The FloatTop property is used mostly to save and restore the float site’s layout.  If you need to modify the settings of the float form, you can access it using the FloatForm property of the float site.


TdxFloatDockSite.FloatWidth

TdxFloatDockSite          See Also

Specifies the child dock control’s width.

property FloatWidth: Integer;

Description

When a dock control is floating (resides on a float site), changing this control’s Width property has no effect.  The reason is that the control is client aligned on its parent site, which is client aligned within the float form.  To change a floating control’s width, you should use the FloatWidth property of the owning float site.  This property actually sets the float form’s client width.

Use a control’s FloatDockSite property to access its parent float site.


TdxFloatDockSite.OnSetFloatFormCaption

TdxFloatDockSite

Enables you to change float form settings when the layout of dock controls change within it.

type

  TdxSetFloatFormCaptionEvent = procedure(Sender: TdxCustomDockControl; AFloatForm: TdxFloatForm) of object;

property OnSetFloatFormCaption: TdxSetFloatFormCaptionEvent;

Description

The OnSetFloatFormCaption event fires each time the layout of dock controls within the float site changes.  Use it if you need to change float form settings with respect to the current dock controls layout.  Most commonly, you will use this to specify the caption of the floating form.

The Sender parameter of the event identifies the float site.  Use its Child property to access the dock control residing within it.  The children of dock control obtained can be accessed via its Children property, etc.

The AFloatForm parameter provides access to the float form containing the site.

Note: if you need to provide common logic to modify float form settings with respect to the layout of dock controls, handle the OnSetFloatFormCaption event of the docking manager.  This event’s handler affects all the float sites in the application.


TdxFloatForm
TdxFloatForm Object

Hierarchy          Properties          Concepts

Represents the form holding floating dock controls.

Unit

dxDockControl

TdxFloatForm = class(TCustomForm)

Description

When a dock control is made to float, an underlying float site is created for it.  Also, a form holding that float site is created.  TdxFloatForm objects represent such forms.

The TdxFloatForm class overrides the default form behavior for two purposes:

•	To change the initial appearance of floating forms.

•	To change the way the form behaves when dragging it.  The form is not moved but, instead, a frame indicating its potential position is painted.

Also, the TdxFloatForm class implements float site management.  For instance, it closes the site when the form is closed.  Additionally, it updates the site when either the position or size of the float form has been changed.


TdxFloatForm Hierarchy
Hierarchy

TCustomForm

     |


Properties for TdxFloatForm
TdxFloatForm Properties

TdxFloatDockSite          Legend

In TdxFloatForm

DockSite

ParentForm


TdxFloatForm.DockSite

TdxFloatDockSite          See Also

Provides access to the float site residing on the form.

property DockSite: TdxFloatDockSite;

Description

There is always a single float site residing on the form and occupying its entire client area.  This float site is used to hold the floating dock control.

The DockSite property can be used to access this float site.  The Child property of the float site obtained provides access to the floating dock control.

ReadOnly property


TdxFloatForm.ParentForm

TdxFloatDockSite

Returns the form that owns the float site residing on the float form.

property ParentForm: TCustomForm;

Description

The value returned by the ParentForm property is obtained from the ParentForm property value of the float site residing on the float form.

ReadOnly property


TdxLayoutDockSite
TdxLayoutDockSite Object

Hierarchy          Properties          Methods          Events          Concepts

Represents a layout site.

Unit

dxDockControl

TdxLayoutDockSite = class(TdxCustomDockSite)

Description

When a dock control is docked to a dock site a layout site is created.  The layout site occupies the remaining client area of the dock site that is not occupied by the docked control.  This site is also capable of serving as a host for dock controls.  If a dock control is docked to it, another layout site is created filling the remaining area of the first layout site not occupied by its child dock control.

Layout sites allow the creation of any structure of dock controls.  If there were no layout sites, docking controls to the neighboring edges would lead to an automatic arrangement.  This means that the dock site would automatically decide which of dock controls would occupy the entire edge and which would partially occupy its edge.  Layout sites give you the ability to choose whether the dock control needs to be docked to the dock site (filling their edge entirely) or to the layout site (filling their edge partially).  Please refer to the Layout Sites topic for details.

Most layout site settings are inherited from its ancestor – the TdxCustomDockSite class.  The TdxLayoutDockSite class introduces a single SiblingDockControl property that returns the site’s neighboring dock control.


TdxLayoutDockSite Hierarchy
Hierarchy

TCustomControl

     |

TdxCustomDockControl

     |

TdxCustomDockSite

     |


Properties for TdxLayoutDockSite
TdxLayoutDockSite Properties

TdxLayoutDockSite          Legend

In TdxLayoutDockSite

SiblingDockControl

Derived from TdxCustomDockControl

Active

AllowDock

AllowDockClients

AllowFloating

AutoHide

AutoHideControl

AutoHideHostSite

Caption

CaptionButtons

ChildCount

Children

Color

Container

Controller

Dockable

DockIndex

DockLevel

DockState

DockType

DockZones

FloatDockSite

FloatForm

Font

ImageIndex

Images

LayoutDockSite

ManagerColor

ManagerFont

OriginalHeight

OriginalWidth

ParentDockControl

ParentForm

ResizeZones

ShowCaption

SideContainer

SideContainerIndex

SideContainerItem

TabContainer

TopMostDockControl

UseDoubleBuffer


Methods for TdxLayoutDockSite
TdxLayoutDockSite Methods

TdxLayoutDockSite          Legend

Derived from TdxCustomDockControl

Activate

CanActive

CanAutoHide

CanDock

CanDockHost

CanMaximize

Close

DockTo

GetDockZoneAtPos

GetResizeZoneAtPos

MakeFloating

SetBounds

UnDock


Events for TdxLayoutDockSite
TdxLayoutDockSite Events

TdxLayoutDockSite          Legend

Derived from TdxCustomDockControl

OnActivate

OnAutoHideChanged

OnAutoHideChanging

OnCanDocking

OnCanResize

OnClose

OnCloseQuery

OnCreateFloatSite

OnCreateLayoutSite

OnCreateSideContainer

OnCreateTabContainer

OnCustomDrawDockingSelection

OnCustomDrawResizingSelection

OnDock

OnDocking

OnEndDocking

OnEndResizing

OnGetAutoHidePosition

OnLayoutChanged

OnMakeFloating

OnParentChanged

OnParentChanging

OnResize

OnResizing

OnRestoreDockPosition

OnStartDocking

OnStartResizing

OnStoreDockPosition

OnUnDock

OnUpdateDockZones

OnUpdateResizeZones

OnVisibleChanged

OnVisibleChanging


TdxLayoutDockSite.SiblingDockControl

TdxLayoutDockSite          See Also

Returns the layout site’s neighboring dock control.

property SiblingDockControl: TdxCustomDockControl;

Description

When a control is docked to a dock site or layout site, the target site becomes its parent.  Also, a layout site is created to fill the area of the parent not occupied by the dock control.  This layout site also becomes the child of the target site.  Thus, each layout site corresponds to a dock control.  This dock control can be accessed via the layout site’s SiblingDockControl property.

You can also access a dock control’s neighboring layout site, if needed.  Use the LayoutDockSite property of the desired dock control for this purpose.

ReadOnly Property


TdxContainerDockSite
TdxContainerDockSite Object

Hierarchy          Properties          Methods          Events          Concepts

Serves as the base for container sites.

Unit

dxDockControl

TdxContainerDockSite = class(TdxCustomDockSite)

Description

The TdxContainerDockSite class implements the common functionality of container sites.  It serves as the ancestor for tab containers and side containers.  Both these container types are capable of holding several dock controls within them.  Each dock control within a container can become the active child.  For tab containers, the active child is the dock control whose corresponding tab is currently selected.  For side containers, the active child is the maximized dock control.  The TdxContainerDockSite class introduces the ActiveChildIndex and ActiveChild properties to allow setting or obtaining the active child control via code.  Additionally, the OnActiveChildChanged event is implemented to respond to changing the active child.

Container dock controls, like dock panels, can be docked or made floating either by end-users or via code.  They are capable of displaying their own caption and this is used to manage them.  The actual behavior of container control depends on docking manager options.  You can access these options via the manager’s Options property.


TdxContainerDockSite Hierarchy
Hierarchy

TCustomControl

     |

TdxCustomDockControl

     |

TdxCustomDockSite

     |


Properties for TdxContainerDockSite
TdxContainerDockSite Properties

TdxContainerDockSite          Legend

In TdxContainerDockSite

ActiveChild

ActiveChildIndex

ValidChildCount

ValidChildren

Derived from TdxCustomDockControl

Active

AllowDock

AllowDockClients

AllowFloating

AutoHide

AutoHideControl

AutoHideHostSite

Caption

CaptionButtons

ChildCount

Children

Color

Container

Controller

Dockable

DockIndex

DockLevel

DockState

DockType

DockZones

FloatDockSite

FloatForm

Font

ImageIndex

Images

LayoutDockSite

ManagerColor

ManagerFont

OriginalHeight

OriginalWidth

ParentDockControl

ParentForm

ResizeZones

ShowCaption

SideContainer

SideContainerIndex

SideContainerItem

TabContainer

TopMostDockControl

UseDoubleBuffer


Methods for TdxContainerDockSite
TdxContainerDockSite Methods

TdxContainerDockSite          Legend

In TdxContainerDockSite

CanContainerDockHost

Derived from TdxCustomDockControl

Activate

CanActive

CanAutoHide

CanDock

CanDockHost

CanMaximize

Close

DockTo

GetDockZoneAtPos

GetResizeZoneAtPos

MakeFloating

SetBounds

UnDock


Events for TdxContainerDockSite
TdxContainerDockSite Events

TdxContainerDockSite          Legend

In TdxContainerDockSite

OnActiveChildChanged

Derived from TdxCustomDockControl

OnActivate

OnAutoHideChanged

OnAutoHideChanging

OnCanDocking

OnCanResize

OnClose

OnCloseQuery

OnCreateFloatSite

OnCreateLayoutSite

OnCreateSideContainer

OnCreateTabContainer

OnCustomDrawDockingSelection

OnCustomDrawResizingSelection

OnDock

OnDocking

OnEndDocking

OnEndResizing

OnGetAutoHidePosition

OnLayoutChanged

OnMakeFloating

OnParentChanged

OnParentChanging

OnResize

OnResizing

OnRestoreDockPosition

OnStartDocking

OnStartResizing

OnStoreDockPosition

OnUnDock

OnUpdateDockZones

OnUpdateResizeZones

OnVisibleChanged

OnVisibleChanging


TdxContainerDockSite.ActiveChild

TdxContainerDockSite          See Also

Specifies the container site’s currently active child.

property ActiveChild: TdxCustomDockControl;

Description

Use the ActiveChild property to access the currently active child of the container site.  For tab containers, the active child is the child dock control whose corresponding tab is currently selected.  For side containers, the active child is the maximized child control.  If there is no currently active child control, the ActiveChild property returns nil.

You can also use the ActiveChild property to set the container’s active child.  Assign the desired child dock control to this property to perform this.  Note that assigning a control that is not the container’s child has no effect.  If nil is assigned to the ActiveChild property, the container will not have an active child.

You can also activate a child dock control via:

•	the container’s ActiveChildIndex property;

•	the container site’s ActivateNextChild method.

When changing the active child, the OnActiveChildChanged event is raised.


TdxContainerDockSite.ActiveChildIndex

TdxContainerDockSite          See Also

Specifies the child control currently active by its index within the container.

property ActiveChildIndex: Integer;

Description

Use the ActiveChildIndex property to specify the active control within the container site.  Assign the desired child control’s DockIndex property value to this property to perform this.  If the assigned value is negative or exceeds the last available child index, the container will not have an active child.

The ActiveChildIndex property is useful if you know the dock index of the desired control.  For instance, you may want to make the first, last, previous or next child to be activated.  If you need to make a particular control active, you can assign the control directly to the container’s ActiveChild property or call the container site’s ActivateNextChild method.

When changing the active child of a dock control, the OnActiveChildChanged event is raised.


TdxContainerDockSite.ValidChildCount

TdxContainerDockSite          See Also

Returns the number of container’s child controls that are actually displayed in it.

property ValidChildCount: Integer;

Description

Children of a dock control can be accessed via its Children property.  Their number can be obtained by reading the ChildCount property value.  However, some of the child controls may not actually be displayed within the container.  This occurs if a child control’s Visible property is set to False, for instance.  In this case, the control is not displayed, but the container still remains its parent.  The same happens when the auto hide feature is enabled for the control.  When disabling the auto hide feature or when showing the control again, it is displayed in its container at its previous position.

Use the ValidChildCount property to obtain the number of controls that are actually displayed by the container.  To traverse the valid children of the container, use this property in combination with the ValidChildren property.

ReadOnly Property


TdxContainerDockSite.ValidChildren

TdxContainerDockSite          See Also

Provides indexed access to valid children of the container site.

property ValidChildren[Index: Integer]: TdxCustomDockControl;

Description

Use the ValidChildren property to access valid child controls of the container site.  The accessed child is specified by its index within the valid children list via the Index parameter.  Note that if you need to access all child dock controls, you should use the Children property.

The ValidChildren property can be used in combination with the ValidChildCount property to traverse the list of valid children.  The index of the first available valid child is zero.  The index of the last valid child is the ValidChildCount property decremented by one.

Please refer to the ValidChildCount property description for more information and the definition of a ‘valid child’.

ReadOnly Property


TdxContainerDockSite.CanContainerDockHost

TdxContainerDockSite          See Also

Returns a value indicating whether the container can accept other docking controls of the docking type specified.

function CanContainerDockHost(AType: TdxDockingType): Boolean; virtual;

Description

The CanContainerDockHost method is used to check whether the specified docking type is supported by the container.  If the method returns True, dock controls can be docked to the container in the specified manner and become the container’s children.  If the method returns False, docking is prohibited or another container is created which becomes the docked control’s parent.

For instance, the CanContainerDockHost method of vertical side containers returns True if the specified dock type is either dtTop or dtBottom.  This means that controls can be docked to the top or bottom edge of any control within the container.  The docked control will become the container’s child.  However, you can also try to dock a control to the left or right edge of a container’s child.  In this case, the CanContainerDockHost method returns False.  This means that another container must be created in order to accommodate the docked control.  If the doSideContainerCanInSideContainer option is enabled, a horizontal side container is created to accommodate it.  This and other docking options can be accessed via the Options property of the docking manager.


TdxContainerDockSite.OnActiveChildChanged

TdxContainerDockSite          See Also

Fires when the container’s active child control is changed.

type

  TdxActiveChildChangeEvent = procedure(Sender: TdxContainerDockSite; Child: TdxCustomDockControl) of object;

property OnActiveChildChanged: TdxActiveChildChangeEvent;

Description

The OnActiveChildChanged event fires in response to changing the container’s active child.  End-users can change the active child of a tab container by switching between tabs.  For side containers, they need to maximize a control by pressing the maximize button in its caption.  Note that the active child control can also be changed programmatically via:

•	the container’s ActiveChildIndex and ActiveChild properties;

•	the container site’s ActivateNextChild method.

The Sender parameter of the event represents the container whose active child has been changed.  The newly active child can be accessed via the Child parameter.


TdxHorizContainerDockSite
TdxHorizContainerDockSite Object

Hierarchy          Properties          Methods          Events          Concepts

Represents a horizontal side container site.

Unit

dxDockControl

TdxHorizContainerDockSite = class(TdxSideContainerDockSite)

Description

When a dock control is docked to the left or right edge of another control, a horizontal side container is created.  It becomes the parent for the docked controls.  In such a container, dock controls are arranged horizontally one after another.  End-users can maximize a control by pressing the maximize button in its caption.  Pressing the button again restores the previous size of the maximized control.

The image below shows an example of a horizontal side container containing three dock panels.

The next image shows the same container but with the Solution Explorer panel maximized.

If you need to provide default settings for such containers created at runtime as the result of docking operations, use the docking manager’s DefaultHorizContainerSiteProperties property.  You can also initialize these containers by handling the OnCreateSideContainer event of the docking manager.

Please refer to the Side Container Sites topic for additional information about side containers.


TdxHorizContainerDockSite Hierarchy
Hierarchy

TCustomControl

     |

TdxCustomDockControl

     |

TdxCustomDockSite

     |

TdxContainerDockSite

     |

TdxSideContainerDockSite

     |


Properties for TdxHorizContainerDockSite
TdxHorizContainerDockSite Properties

TdxHorizContainerDockSite          Legend

Derived from TdxContainerDockSite

ActiveChild

ActiveChildIndex

ValidChildCount

ValidChildren

Derived from TdxCustomDockControl

Active

AllowDock

AllowDockClients

AllowFloating

AutoHide

AutoHideControl

AutoHideHostSite

Caption

CaptionButtons

ChildCount

Children

Color

Container

Controller

Dockable

DockIndex

DockLevel

DockState

DockType

DockZones

FloatDockSite

FloatForm

Font

ImageIndex

Images

LayoutDockSite

ManagerColor

ManagerFont

OriginalHeight

OriginalWidth

ParentDockControl

ParentForm

ResizeZones

ShowCaption

SideContainer

SideContainerIndex

SideContainerItem

TabContainer

TopMostDockControl

UseDoubleBuffer


Methods for TdxHorizContainerDockSite
TdxHorizContainerDockSite Methods

TdxHorizContainerDockSite          Legend

Derived from TdxContainerDockSite

CanContainerDockHost

Derived from TdxCustomDockControl

Activate

CanActive

CanAutoHide

CanDock

CanDockHost

CanMaximize

Close

DockTo

GetDockZoneAtPos

GetResizeZoneAtPos

MakeFloating

SetBounds

UnDock


Events for TdxHorizContainerDockSite
TdxHorizContainerDockSite Events

TdxHorizContainerDockSite          Legend

Derived from TdxContainerDockSite

OnActiveChildChanged

Derived from TdxCustomDockControl

OnActivate

OnAutoHideChanged

OnAutoHideChanging

OnCanDocking

OnCanResize

OnClose

OnCloseQuery

OnCreateFloatSite

OnCreateLayoutSite

OnCreateSideContainer

OnCreateTabContainer

OnCustomDrawDockingSelection

OnCustomDrawResizingSelection

OnDock

OnDocking

OnEndDocking

OnEndResizing

OnGetAutoHidePosition

OnLayoutChanged

OnMakeFloating

OnParentChanged

OnParentChanging

OnResize

OnResizing

OnRestoreDockPosition

OnStartDocking

OnStartResizing

OnStoreDockPosition

OnUnDock

OnUpdateDockZones

OnUpdateResizeZones

OnVisibleChanged

OnVisibleChanging


TdxSideContainerDockSite
TdxSideContainerDockSite Object

Hierarchy          Properties          Methods          Events          Concepts

Serves as the base for side container sites.

Unit

dxDockControl

TdxSideContainerDockSite = class(TdxContainerDockSite)

Description

The TdxSideContainerDockSite class implements the common functionality of side containers.  Being the direct descendant of the TdxContainerDockSite class, it inherits all features relating to docking operations, active child management, etc.  The functionality introduced mainly relates to managing child controls when they are arranged one after another either horizontally or vertically.

Descendants of the TdxSideContainerDockSite class are the TdxVertContainerDockSite and TdxHorizContainerDockSite classes representing the vertical and horizontal side containers respectively.

Please refer to the Dock Controls Hierarchy for a complete inheritance diagram of dock controls.


TdxSideContainerDockSite Hierarchy
Hierarchy

TCustomControl

     |

TdxCustomDockControl

     |

TdxCustomDockSite

     |

TdxContainerDockSite

     |


Properties for TdxSideContainerDockSite
TdxSideContainerDockSite Properties

TdxContainerDockSite          Legend

Derived from TdxContainerDockSite

ActiveChild

ActiveChildIndex

ValidChildCount

ValidChildren

Derived from TdxCustomDockControl

Active

AllowDock

AllowDockClients

AllowFloating

AutoHide

AutoHideControl

AutoHideHostSite

Caption

CaptionButtons

ChildCount

Children

Color

Container

Controller

Dockable

DockIndex

DockLevel

DockState

DockType

DockZones

FloatDockSite

FloatForm

Font

ImageIndex

Images

LayoutDockSite

ManagerColor

ManagerFont

OriginalHeight

OriginalWidth

ParentDockControl

ParentForm

ResizeZones

ShowCaption

SideContainer

SideContainerIndex

SideContainerItem

TabContainer

TopMostDockControl

UseDoubleBuffer


Methods for TdxSideContainerDockSite
TdxSideContainerDockSite Methods

TdxContainerDockSite          Legend

Derived from TdxContainerDockSite

CanContainerDockHost

Derived from TdxCustomDockControl

Activate

CanActive

CanAutoHide

CanDock

CanDockHost

CanMaximize

Close

DockTo

GetDockZoneAtPos

GetResizeZoneAtPos

MakeFloating

SetBounds

UnDock


Events for TdxSideContainerDockSite
TdxSideContainerDockSite Events

TdxContainerDockSite          Legend

Derived from TdxContainerDockSite

OnActiveChildChanged

Derived from TdxCustomDockControl

OnActivate

OnAutoHideChanged

OnAutoHideChanging

OnCanDocking

OnCanResize

OnClose

OnCloseQuery

OnCreateFloatSite

OnCreateLayoutSite

OnCreateSideContainer

OnCreateTabContainer

OnCustomDrawDockingSelection

OnCustomDrawResizingSelection

OnDock

OnDocking

OnEndDocking

OnEndResizing

OnGetAutoHidePosition

OnLayoutChanged

OnMakeFloating

OnParentChanged

OnParentChanging

OnResize

OnResizing

OnRestoreDockPosition

OnStartDocking

OnStartResizing

OnStoreDockPosition

OnUnDock

OnUpdateDockZones

OnUpdateResizeZones

OnVisibleChanged

OnVisibleChanging


TdxTabContainerDockSite
TdxTabContainerDockSite Object

Hierarchy          Properties          Methods          Events          Concepts

Represents the tab container site.

Unit

dxDockControl

TdxTabContainerDockSite = class(TdxContainerDockSite)

Description

When a dock control is docked to another control to fill its entire client area, an underlying tab container is created.  This container becomes the parent of dock controls.  Tab containers display the client area of a single child at a time.  They also display tabs that can be used to switch between children.

Being the direct descendant of the TdxContainerDockSite class, the TdxTabContainerDockSite class inherits all the functionality relating to docking operations, auto hiding, active child management, etc.  The functionality introduced relates to displaying tabs and providing child switching facilities.

The image below shows an example of a tab container’s appearance.

You can provide default settings for tab containers created at runtime as the result of docking operations.  Use the DefaultTabContainerSiteProperties property of the docking manager for this purpose.  Additionally, you can initialize dynamically created tab containers by handling the manager’s OnCreateTabContainer event.

Please refer to the Tab Container Sites topic for more information regarding tab containers.


TdxTabContainerDockSite Hierarchy
Hierarchy

TCustomControl

     |

TdxCustomDockControl

     |

TdxCustomDockSite

     |

TdxContainerDockSite

     |


Properties for TdxTabContainerDockSite
TdxTabContainerDockSite Properties

TdxTabContainerDockSite          Legend

In TdxTabContainerDockSite

TabsPosition

TabsScroll

Derived from TdxContainerDockSite

ActiveChild

ActiveChildIndex

ValidChildCount

ValidChildren

Derived from TdxCustomDockControl

Active

AllowDock

AllowDockClients

AllowFloating

AutoHide

AutoHideControl

AutoHideHostSite

Caption

CaptionButtons

ChildCount

Children

Color

Container

Controller

Dockable

DockIndex

DockLevel

DockState

DockType

DockZones

FloatDockSite

FloatForm

Font

ImageIndex

Images

LayoutDockSite

ManagerColor

ManagerFont

OriginalHeight

OriginalWidth

ParentDockControl

ParentForm

ResizeZones

ShowCaption

SideContainer

SideContainerIndex

SideContainerItem

TabContainer

TopMostDockControl

UseDoubleBuffer


Methods for TdxTabContainerDockSite
TdxTabContainerDockSite Methods

TdxTabContainerDockSite          Legend

In TdxTabContainerDockSite

ActivateNextChild

Derived from TdxContainerDockSite

CanContainerDockHost

Derived from TdxCustomDockControl

Activate

CanActive

CanAutoHide

CanDock

CanDockHost

CanMaximize

Close

DockTo

GetDockZoneAtPos

GetResizeZoneAtPos

MakeFloating

SetBounds

UnDock


Events for TdxTabContainerDockSite
TdxTabContainerDockSite Events

TdxTabContainerDockSite          Legend

Derived from TdxContainerDockSite

OnActiveChildChanged

Derived from TdxCustomDockControl

OnActivate

OnAutoHideChanged

OnAutoHideChanging

OnCanDocking

OnCanResize

OnClose

OnCloseQuery

OnCreateFloatSite

OnCreateLayoutSite

OnCreateSideContainer

OnCreateTabContainer

OnCustomDrawDockingSelection

OnCustomDrawResizingSelection

OnDock

OnDocking

OnEndDocking

OnEndResizing

OnGetAutoHidePosition

OnLayoutChanged

OnMakeFloating

OnParentChanged

OnParentChanging

OnResize

OnResizing

OnRestoreDockPosition

OnStartDocking

OnStartResizing

OnStoreDockPosition

OnUnDock

OnUpdateDockZones

OnUpdateResizeZones

OnVisibleChanged

OnVisibleChanging


TdxTabContainerDockSite.TabsPosition

TdxTabContainerDockSite          See Also

Specifies the position of tabs.

type

  TdxTabContainerTabsPosition = (tctpTop, tctpBottom);

property TabsPosition: TdxTabContainerTabsPosition;

Description

Use the TabsPosition property to specify the position of tabs used to switch between the tab container’s children. The following values are available for this property.

Value	Description
tctpTop	Tabs are located at the top of the tab container.
tctpBottom	Tabs are located at the bottom of the tab container.

Note that in both cases, the tab corresponding to the first child is displayed at the left side.

The image below shows a tab container when its TabsPosition property is set to tctpBottom and tctpTop respectively.

The default value of the TabsPosition property is tctpBottom.


TdxTabContainerDockSite.TabsScroll

TdxTabContainerDockSite          See Also

Specifies whether tab navigation buttons are displayed when tabs don’t fit into the tab container’s width.

property TabsScroll: Boolean;

Description

There are two possible ways tab containers behave when the total width of tabs exceeds the container’s width.  If the TabsScroll property value is True, tabs are not resized and tab navigation buttons are displayed.  These buttons can be used to scroll through tabs forward and backward.

If the TabsScroll property value is False, tabs are proportionally resized when they don’t fit into the container’s width.

The image below shows a tab container with TabsScroll set to True and False respectively.


TdxTabContainerDockSite.ActivateNextChild

TdxTabContainerDockSite          See Also

Activates the child dock control next to or prior to the currently active child dock control.

procedure ActivateNextChild(AGoForward: Boolean; AGoOnCycle: Boolean = True);

Description

The AGoForward parameter value specifies whether the next (True) or previous (False) child dock control is to be activated.

Set the AGoOnCycle parameter to False to prohibit searching for a child dock control after reaching the last available dock control in the direction specified by the AGoForward parameter.


TdxVertContainerDockSite
TdxVertContainerDockSite Object

Hierarchy          Properties          Methods          Events          Concepts

Represents the vertical side container.

Unit

dxDockControl

TdxVertContainerDockSite = class(TdxSideContainerDockSite)

Description

When a control is docked to the top or bottom edge of another control, an underlying vertical side container is created.  The controls become children of the container thus created.  All child dock controls of such containers are arranged vertically one under another.  End-users can maximize controls so that they fill the entire container’s area.  This is done by pressing the maximize button within the control’s caption.  When a control is maximized, other controls within the container display their captions only.  Note that pressing the button again restores the previous size of the control.

The image below shows the appearance of a vertical side container (the Solution Explorer window is maximized).

You can provide default settings for such containers created as the result of docking operations.  Use the DefaultVertContainerSiteProperties property of the docking manager for this purpose.  Additionally, you can initialize such dynamically created vertical side containers by handling the manager’s OnCreateSideContainer event.

Please refer to the Side Container Sites topic for additional information on side containers.


TdxVertContainerDockSite Hierarchy
Hierarchy

TCustomControl

     |

TdxCustomDockControl

     |

TdxCustomDockSite

     |

TdxContainerDockSite

     |

TdxSideContainerDockSite

     |


Properties for TdxVertContainerDockSite
TdxVertContainerDockSite Properties

TdxHorizContainerDockSite          Legend

Derived from TdxContainerDockSite

ActiveChild

ActiveChildIndex

ValidChildCount

ValidChildren

Derived from TdxCustomDockControl

Active

AllowDock

AllowDockClients

AllowFloating

AutoHide

AutoHideControl

AutoHideHostSite

Caption

CaptionButtons

ChildCount

Children

Color

Container

Controller

Dockable

DockIndex

DockLevel

DockState

DockType

DockZones

FloatDockSite

FloatForm

Font

ImageIndex

Images

LayoutDockSite

ManagerColor

ManagerFont

OriginalHeight

OriginalWidth

ParentDockControl

ParentForm

ResizeZones

ShowCaption

SideContainer

SideContainerIndex

SideContainerItem

TabContainer

TopMostDockControl

UseDoubleBuffer


Methods for TdxVertContainerDockSite
TdxVertContainerDockSite Methods

TdxHorizContainerDockSite          Legend

Derived from TdxContainerDockSite

CanContainerDockHost

Derived from TdxCustomDockControl

Activate

CanActive

CanAutoHide

CanDock

CanDockHost

CanMaximize

Close

DockTo

GetDockZoneAtPos

GetResizeZoneAtPos

MakeFloating

SetBounds

UnDock


Events for TdxVertContainerDockSite
TdxVertContainerDockSite Events

TdxHorizContainerDockSite          Legend

Derived from TdxContainerDockSite

OnActiveChildChanged

Derived from TdxCustomDockControl

OnActivate

OnAutoHideChanged

OnAutoHideChanging

OnCanDocking

OnCanResize

OnClose

OnCloseQuery

OnCreateFloatSite

OnCreateLayoutSite

OnCreateSideContainer

OnCreateTabContainer

OnCustomDrawDockingSelection

OnCustomDrawResizingSelection

OnDock

OnDocking

OnEndDocking

OnEndResizing

OnGetAutoHidePosition

OnLayoutChanged

OnMakeFloating

OnParentChanged

OnParentChanging

OnResize

OnResizing

OnRestoreDockPosition

OnStartDocking

OnStartResizing

OnStoreDockPosition

OnUnDock

OnUpdateDockZones

OnUpdateResizeZones

OnVisibleChanged

OnVisibleChanging


dxDockControl Unit Overview
dxDockControl Unit

Classes

TdxContainerDockSite

TdxCustomDockControl

TdxCustomDockControlProperties

TdxCustomDockSite

TdxDockingController

TdxDockingManager

TdxDockSite

TdxFloatDockSite

TdxFloatDockSiteProperties

TdxFloatForm

TdxHorizContainerDockSite

TdxLayoutDockSite

TdxLayoutDockSiteProperties

TdxSideContainerDockSite

TdxSideContainerDockSiteProperties

TdxTabContainerDockSite

TdxTabContainerDockSiteProperties

TdxVertContainerDockSite

TdxZone

Other Types

TdxAutoHidePosition

TdxDockingType

TdxDockingTypes

Routines

dxDockingController


TdxZone
TdxZone Object

Hierarchy          Properties          Methods          Concepts

Serves as the base for classes representing dock zones and resize zones.

Unit

dxDockControl

TdxZone = class(TObject)

Description

Each dock control stores lists of its dock zones and resize zones in its DockZones and ResizeZones properties.  These zones are TdxZone class descendants that store information about where other controls can be docked to it and where resizing can be initiated.  Also, they provide the functionality to implement these two kinds of operation.  This includes specifying the dimensions and painting docking frames, resizing bars and initiating docking & resizing operations.  Please refer to the Zones Overview topic for the list of the TdxZone class descendants and the overview of their functionality.

Dock zones and resize zones are recalculated each time the layout of dock controls changes.  Thus, if you change the DockZones and ResizeZones property values manually, the changes will be lost following the next layout update.  However, dock controls provide the OnUpdateDockZones and OnUpdateResizeZones events.  You can handle them to update zone lists each time they are recalculated.  Thus, you can provide custom docking and resizing behavior of controls by modifying these lists.  Please refer to the Dock Zones and Resize Zones topics for examples.

Most of the methods declared by the TdxZone class are overridden by its descendants to provide proper zone behavior.  You can also create a custom zone by deriving it from an appropriate zone object and by overriding the desired methods.  The descendants created can then be added to the zone lists of a dock control.

Objects representing dock zones and resize zones are passed to a number of events as parameters.  You can read zone properties values to obtain information about the current operation.  For instance, settings of dock zones may be used to obtain the docking type.  Settings of resize zones can be used to determine whether horizontal or vertical resizing is performed.


TdxZone Hierarchy
Hierarchy

TObject

     |


Properties for TdxZone
TdxZone Properties

TdxZone          Legend

In TdxZone

Direction

DockIndex

DockType

Owner

Rectangle

Width


Methods for TdxZone
TdxZone Methods

TdxZone          Legend

In TdxZone

CanDock

CanResize

Create

GetDockingSelection

GetResizingSelection

IsZonePoint

ValidateDockZone

ValidateResizeZone


TdxZone.Direction

TdxZone          Concepts

Returns the resizing direction.

type

  TdxZoneDirection = (zdUndefined, zdVertical, zdHorizontal);

property Direction: TdxZoneDirection;

Description

The Direction property is useful for resize zones only.  It enables you to determine whether the zone can initiate horizontal or vertical resizing.  If you use the resize zone as the parameter of events that control the resizing process, the Direction property indicates whether the width or height of the control is being changed.

The following values can be returned by the Direction property.

Value	Description
zdUndefined	This value is returned by zones that cannot initiate control resizing.
zdVertical	This value is returned by zones located at the top or bottom edge of the control.  It indicates that this zone can initiate vertical resizing.  In other words, the height of the control will change when resizing.  When the mouse pointer is over a zone that returns this value, it displays a horizontal splitter.
zdHorizontal	This value is returned by zones located at the left or right edge of the control.  It indicates that this zone can initiate horizontal resizing.  In other words, the width of the control will change when resizing.  When the mouse pointer is over a zone that returns this value, it displays a vertical splitter.

ReadOnly Property


TdxZone.DockIndex

TdxZone          See Also          Concepts

Returns the dock index that controls will have when docked to this zone.

property DockIndex: Integer;

Description

The DockIndex property is useful for dock zones only.  It indicates the value of the DockIndex property that controls docked to this zone will have.  Note however, that the DockIndex property returns –1 for most zones.  This is because most dock controls are docked to controls that are not containers.  For instance, if docking a control to a side container, it is actually docked to one of the controls residing in it and the side container becomes the control’s parent.  In this case, the DockIndex property of the control will differ from the DockIndex property of the zone where it has been docked.

The DockIndex property returns a value that matches the DockIndex property of controls only in zones residing in tabs of a tab container.  In this case, controls are docked directly to the tab container, not one of its child controls.  Thus, the dock index of the docked control can be determined.  It is equal to the dock index of the control corresponding to the tab where the dock zone resides.

ReadOnly Property


TdxZone.DockType

TdxZone          See Also          Concepts

Returns the docking type supported by the zone.

property DockType: TdxDockingType;

Description

The DockType property is useful for dock zones only.  It indicates the docking type supported by the zone.  The value returned by this property specifies the DockType value that controls docked to this zone will have.  You can use this property when obtaining a zone as the parameter of events that control docking operations.  Using it, you can determine whether the control is being docked to the client area of the target control or to which edge.

ReadOnly Property


TdxZone.Owner

TdxZone          See Also

Gets the control to which the zone belongs.

property Owner: TdxCustomDockControl;

Description

The Owner property returns the dock control to which the zone belongs.  If a zone is used as the target of docking operations, the Owner property returns the control that will be the parent of controls docked to this zone.  If a zone is a resize zone, the Owner property returns the control that is resized.

You can use the Owner property when handling events that fire in response to performing docking or resizing operations.  These events provide zones as parameters.  Thus, you can determine the control to which another control is docked or the control being resized.

ReadOnly Property


TdxZone.Rectangle

TdxZone          See Also          Concepts

Returns the bounding rectangle of the zone.

property Rectangle: TRect;

Description

The Rectangle property can be used to obtain the bounding rectangle of the zone.  The rectangle is specified in the client coordinates of the control that owns this zone.

This property is used to determine whether the mouse pointer is currently within the zone.  The IsZonePoint method performs this task.

ReadOnly Property


TdxZone.Width

TdxZone          See Also          Concepts

Gets the width of the zone.

property Width: Integer;

Description

The Width property returns the width of the zone in pixels.  Note that the width of the zone specifies its entire dimension.  The reason is that at least one dimension of a zone is controlled by the corresponding dimension of its owning control.  For instance, the height of the left dock zone is specified by the owner control’s height.  Dimensions of client zones match the dimensions of the owning control.

The width of a zone is specified by the constructor’s parameter.

You can access the position and dimensions of a zone via the Rectangle property.

ReadOnly Property


TdxZone.CanDock

TdxZone          See Also

Returns a value indicating whether the specified control can be docked to the zone.

function CanDock(AControl: TdxCustomDockControl): Boolean; virtual;

Description

The CanDock method returns True if the control specified by the AControl parameter can be docked to the zone.  Otherwise, the method returns False.  Actually, the method’s return value is the return value of its owning control’s CanDockHost method.  The specified control and the DockType property value of the zone are passed to the CanDockHost method as parameters.

The CanDock method is used internally to determine whether the control being dragged can be docked to the dock zone residing under it.  Usually, you will have no need to use it in applications.


TdxZone.CanResize

TdxZone          See Also

Returns a value indicating whether the specified resizing operation can be performed.

function CanResize(StartPoint, EndPoint: TPoint): Boolean; virtual;

Description

The CanResize method returns True if the specified resizing operation can be performed.  The operation’s parameters are specified by the StartPoint and EndPoint parameters.  They specify the mouse pointer position at the beginning and end of the operation.  When performing horizontal resizing, only horizontal coordinates of the specified points are taken into account.

If the specified resizing operation is not valid, the CanResize method returns False.  This takes place, for instance, if the potential dimension is greater than that of its parent control.

In addition to performing internal operation validity checking, the CanResize method raises the OnCanResize event of the owning control.  You can write a handler for this event to add constraints if needed.  If the event handler prevents the operation, the CanResize method returns False.

The CanResize method is used internally.  Most commonly you will have no need to use it in applications.

Note: the CanResize method is not called when changing dimensions of the owning dock control via code.


TdxZone.Create

TdxZone          See Also

Creates a new zone.

constructor Create(AOwner: TdxCustomDockControl; AWidth: Integer);

Description

The Create method is used to create a new zone object.  The AOwner parameter specifies the zone’s owner control.  This is the control whose DockZones or ResizeZones list will contain the zone.  The AWidth parameter specifies the zone width.  This value is assigned to the Width property of the zone.  Note that if zero or a negative value is specified as the AWidth parameter, the zone’s Width property will return the dxDockZonesWidth constant value.

Use the constructor to create zones at runtime.  This can be used if you add custom zones to either the DockZones or ResizeZones list of a dock control.


TdxZone.GetDockingSelection

TdxZone          See Also          Concepts

Returns the bounding rectangle of the docking frame indicating the specified control’s position if it is docked to this zone.

function GetDockingSelection(ATarget: TdxCustomDockControl): TRect; virtual;

Description

If the mouse pointer is not currently over the dock zone, the docking frame’s bounding rectangle is specified by the dock control’s OriginalWidth and OriginalHeight properties.  If a dock zone is under the mouse pointer, the bounding rectangle of the docking frame is specified by the GetDockingSelection method’s return value.  This provides the potential position of the control if the docking operation is finished immediately (i.e. if the mouse button is released).

The ATarget parameter of the GetDockingSelection method specifies the control whose docking frame dimensions are to be obtained.  Note that the rectangle returned is expressed in screen coordinates.

Note: To fill docking frames with the clHighlight system color, set the doFillDockingSelection flag in the Options property of a docking controller or manager.  To manually paint docking frames, handle the OnCustomDrawDockingSelection event of the desired dock control or the OnCustomDrawDockingSelection event of the docking manager.


TdxZone.GetResizingSelection

TdxZone          See Also          Concepts

Returns the bounding rectangle of a dock control’s resizing bar.

function GetResizingSelection(pt: TPoint): TRect; virtual;

Description

The pt parameter represents the mouse pointer coordinates relatively to the upper-left corner of the screen.  If horizontal resizing is performed, the horizontal coordinate of the specified point is used to calculate the resizing bar’s position.

The rectangle returned by the GetResizingSelection method is expressed in screen coordinates.

Note: To manually paint resizing bars, handle the OnCustomDrawResizingSelection event of the desired dock control or the OnCustomDrawResizingSelection event of the docking manager.


TdxZone.IsZonePoint

TdxZone          See Also

Returns a value indicating whether the specified point is within the zone.

function IsZonePoint(pt: TPoint): Boolean; virtual;

Description

The IsZonePoint method is used by the GetDockZoneAtPos and GetResizeZoneAtPos methods of dock controls.  These methods determine the zone currently located under the mouse pointer.  The first method is called repeatedly when performing a docking operation.  If it finds a zone, the zone becomes the potential target of the docking operation.  The second method is called repeatedly when moving the mouse pointer over dock controls.  If it finds a zone, the mouse pointer changes its appearance to indicate that a resizing operation can be initiated.

The IsZonePoint method returns True if the point specified by the pt parameter is within the zone.  Otherwise, the method returns False.  Note that the point is specified in screen coordinates.


TdxZone.ValidateDockZone

TdxZone          See Also

Returns a value indicating whether a zone of this type should be added to the control’s dock zones list.

class function ValidateDockZone(AOwner, AControl: TdxCustomDockControl): Boolean; virtual;

Description

Each time the layout of dock controls is changed, dock controls recalculate their dock zones lists.  Each control adds its own zones to the list and scans all of its parents to add their zones to the list.  Zones of parent controls are added with a smaller width, thus docking is allowed either to the control itself or to one of its parent controls. In other words, the closer the mouse pointer is to the edge of the control, the higher the dock level of the target dock control.

The ValidateDockZone method is called to determine whether the parent’s zone (of the current type) must be added to the control.  The AControl parameter specifies the control whose dock zones list is recalculated.  The AOwner parameter specifies the control whose dock zones are checked for validity.  Note that these two parameters may coincide.  This means that the control checks its own zone for validity.  Otherwise, a zone of the control’s parent is checked.

The method returns True if the dock zone type is allowed by the AllowDockClients property of the zone owner and if the control doesn’t already contain a zone providing the same docking functionality.  If True is returned, the checked zone is added to the list.

You can also use the ValidateDockZone method when filling the dock zones lists manually.  Note that you should handle the OnUpdateDockZones event of a dock control to update this list yourself.


TdxZone.ValidateResizeZone

TdxZone          See Also

Returns a value indicating whether a resize zone of this type should be added to the specified control’s resize zones list.

class function ValidateResizeZone(AOwner, AControl: TdxCustomDockControl): Boolean; virtual;

Description

Each time the layout of dock controls change, they recalculate their lists of resize zones.  Note that if a control is within a container, the control’s resize zone list is populated by zones specified by its container.

The ValidateResizeZone method is used to determine whether a zone of a specific type should be added to the control’s resize zones list.  The AOwner parameter specifies the control whose resize zones are used to fill the control’s zones.  The AControl parameter represents the control whose resize zones list is updated.  Note that the AOwner and AControl parameters are the same if the control is not within a container.  In other words, if these two parameters are identical, the control must fill its resize zones list itself.  Otherwise, the AOwner control fills resize zones of the AControl control.

The ValidateResizeZone method returns True if a zone of the current type should be added to the control’s resize zones list.  This method’s return value is used internally to determine which zone types are required by the control.  You can also use this method when filling the resize zones list manually.  Handle the OnUpdateResizeZones event of the desired dock control to implement this.


dxDockingController
dxDockingController Function

Returns the docking controller.

Unit

dxDockControl

function dxDockingController: TdxDockingController;

Description

All docking operations are controlled by the docking controller object.  There is always a single instance of the docking controller in the application.  You can access this instance using the dxDockingController function call.  Note that the docking controller can also be accessed using the Controller property of any dock control.

Please refer to the TdxDockingController class description for details on the docking controller.


TdxAutoHidePosition
TdxAutoHidePosition type

Contains values specifying the edges of dock sites where dock controls can be hidden when their auto hide feature is enabled.

Unit

dxDockControl

TdxAutoHidePosition = (ahpLeft, ahpTop, ahpRight, ahpBottom);

Description

Values listed in the TdxAutoHidePosition type are passed to the OnGetAutoHidePosition event of dock controls.  They specify the automatically determined edge of the dock site to which a control is hidden when the auto hide feature is enabled.  However, you can specify a different value to force the control to be hidden to different edge of the dock site.

The following values are available in the TdxAutoHidePosition enumerator.

Value	Description
ahpLeft	The dock control is hidden to the left edge of the dock site.
ahpTop	The dock control is hidden to the top edge of the dock site.
ahpRight	The dock control is hidden to the right edge of the dock site.
ahpBottom	The dock control is hidden to the bottom edge of the dock site.


TdxDockingType
TdxDockingType type

Contains values specifying the docking type.

Unit

dxDockControl

TdxDockingType = dtClient..dtBottom;

Description

The TdxDockingType enumerator represents the type of several properties and parameters of methods and events.  Values listed by this enumerator specify the manner in which one dock control is docked to another.  The following values are available.

Value	Description
dtClient	A control is docked to fill the entire client area of the target control.  If the target control is not a dock site or float site, such docking results in forming a tab container.
dtLeft	A control is docked to the left edge of the target control.  If the target control is not a dock site or layout site, such docking results in forming a horizontal side container.
dtTop	A control is docked to the top edge of the target control.  If the target control is not a dock site or layout site, such docking results in forming a vertical side container.
dtRight	A control is docked to the right edge of the target control.  If the target control is not a dock site or layout site, such docking results in forming a horizontal side container.
dtBottom	A control is docked to the bottom edge of the target control.  If the target control is not a dock site or layout site, such docking results in forming a vertical side container.


TdxDockingTypes
TdxDockingTypes type

Represents a set of values specifying the docking type.

Unit

dxDockControl

TdxDockingType = dtClient..dtBottom;

TdxDockingTypes = set of TdxDockingType;

Description

The TdxDockingTypes type represents the type of the AllowDock and AllowDockClients properties of dock controls.  These properties specify how this control can be docked to other controls and how other controls can be docked to it respectively.

The TdxDockingTypes type is a set of values listed in the TdxDockingType enumerator.  Please refer to the enumerator description for details on which values are available.


TdxCustomDockControlProperties
TdxCustomDockControlProperties Object

Hierarchy          Properties          Methods

Serves as the base for classes providing default settings for dynamically created dock controls.

Unit

dxDockControl

TdxCustomDockControlProperties = class(TPersistent)

Description

The docking manager (TdxDockingManager component) provides a set of properties that define the default settings for dynamically created dock controls.  These are the DefaultFloatSiteProperties, DefaultHorizContainerSiteProperties, DefaultLayoutSiteProperties, DefaultTabContainerSiteProperties and DefaultVertContainerSiteProperties.  They provide default property values for float sites, horizontal side containers, layout sites, tab containers and vertical side containers respectively.  Note that all these controls have much in common and are derived from the TdxCustomDockControl class.  Thus, an object serves as the base for objects providing default settings.  This common ancestor is the TdxCustomDockControlProperties object.

The descendants of the TdxCustomDockControlProperties class available are the TdxFloatDockSiteProperties, TdxLayoutDockSiteProperties, TdxTabContainerDockSiteProperties and TdxSideContainerDockSiteProperties classes.


TdxCustomDockControlProperties Hierarchy
Hierarchy

TPersistent

     |


Properties for TdxCustomDockControlProperties
TdxCustomDockControlProperties Properties

TdxCustomDockControlProperties          Legend

In TdxCustomDockControlProperties

AllowDock

AllowDockClients

AllowFloating

CaptionButtons

Color

Cursor

Dockable

Font

Hint

ImageIndex

ManagerColor

ManagerFont

PopupMenu

ShowCaption

ShowHint

Tag


Methods for TdxCustomDockControlProperties
TdxCustomDockControlProperties Methods

TdxCustomDockControlProperties          Legend

In TdxCustomDockControlProperties

Create


TdxCustomDockControlProperties.AllowDock

TdxCustomDockControlProperties

Specifies the default value of the AllowDock property of dynamically created dock controls.

property AllowDock: TdxDockingTypes;

Description

Use the AllowDock property to set the default value for the AllowDock property of dock controls created dynamically.  Please refer to the dock control’s AllowDock property description for details on the functionality it provides.


TdxCustomDockControlProperties.AllowDockClients

TdxCustomDockControlProperties

Specifies the default value of the AllowDockClients property of dynamically created dock controls.

property AllowDockClients: TdxDockingTypes;

Description

Use the AllowDockClients property to set the default value for the AllowDockClients property of dock controls created dynamically.  Please refer to the dock control’s AllowDockClients property description for details on the functionality it provides.


TdxCustomDockControlProperties.AllowFloating

TdxCustomDockControlProperties

Specifies the default value of the AllowFloating property of dynamically created dock controls.

property AllowFloating: Boolean;

Description

Use the AllowFloating property to set the default value for the AllowFloating property of dock controls created dynamically.  Please refer to the dock control’s AllowFloating property description for details on the functionality it provides.

The default value of the AllowFloating property is True.


TdxCustomDockControlProperties.CaptionButtons

TdxCustomDockControlProperties

Specifies the default value of the CaptionButtons property of dynamically created dock controls.

property CaptionButtons: TdxCaptionButtons;

Description

Use the CaptionButtons property to set the default value for the CaptionButtons property of dock controls created dynamically.  Please refer to the dock control’s CaptionButtons property description for details on the functionality it provides.


TdxCustomDockControlProperties.Color

TdxCustomDockControlProperties

Specifies the default value of the Color property of dynamically created dock controls.

property Color: TColor;

Description

Use the Color property to set the default value for the Color property of dock controls created dynamically.  Please refer to the dock control’s Color property description for details on the functionality it provides.

The default value of the Color property is clBtnFace.


TdxCustomDockControlProperties.Cursor

TdxCustomDockControlProperties

Specifies the default value of the Cursor property of dynamically created dock controls.

property Cursor: TCursor;

Description

Use the Cursor property to set the default value for the Cursor property of dock controls created dynamically.  Please refer to the dock control’s Cursor property description for details on the functionality it provides.


TdxCustomDockControlProperties.Dockable

TdxCustomDockControlProperties

Specifies the default value of the Dockable property of dynamically created dock controls.

property Dockable: Boolean;

Description

Use the Dockable property to set the default value for the Dockable property of dock controls created dynamically.  Please refer to the dock control’s Dockable property description for details on the functionality it provides.


TdxCustomDockControlProperties.Font

TdxCustomDockControlProperties

Specifies the default value of the Font property of dynamically created dock controls.

property Font: TFont;

Description

Use the Font property to set the default value for the Font property of dock controls created dynamically.  Please refer to the dock control’s Font property description for details on the functionality it provides.


TdxCustomDockControlProperties.Hint

TdxCustomDockControlProperties

Specifies the default value of the Hint property of dynamically created dock controls.

property Hint: string;

Description

Use the Hint property to set the default value for the Hint property of dock controls created dynamically.  Please refer to the dock control’s Hint property description for details on the functionality it provides.


TdxCustomDockControlProperties.ImageIndex

TdxCustomDockControlProperties

Specifies the default value of the ImageIndex property of dynamically created dock controls.

property ImageIndex: Integer;

Description

Use the ImageIndex property to set the default value for the ImageIndex property of dock controls created dynamically.  Please refer to the dock control’s ImageIndex property description for details on the functionality it provides.


TdxCustomDockControlProperties.ManagerColor

TdxCustomDockControlProperties

Specifies the default value of the ManagerColor property of dynamically created dock controls.

property ManagerColor: Boolean;

Description

Use the ManagerColor property to set the default value for the ManagerColor property of dock controls created dynamically.  Please refer to the dock control’s ManagerColor property description for details on the functionality it provides.

The default value of the ManagerColor property is True.


TdxCustomDockControlProperties.ManagerFont

TdxCustomDockControlProperties

Specifies the default value of the ManagerFont property of dynamically created dock controls.

property ManagerFont: Boolean;

Description

Use the ManagerFont property to set the default value for the ManagerFont property of dock controls created dynamically.  Please refer to the dock control’s ManagerFont property description for details on the functionality it provides.

The default value of the ManagerFont property is True.


TdxCustomDockControlProperties.PopupMenu

TdxCustomDockControlProperties

Specifies the default value of the PopupMenu property of dynamically created dock controls.

property PopupMenu: TPopupMenu;

Description

Use the PopupMenu property to set the default value for the PopupMenu property of dock controls created dynamically.  Please refer to the dock control’s PopupMenu property description for details on the functionality it provides.


TdxCustomDockControlProperties.ShowCaption

TdxCustomDockControlProperties

Specifies the default value of the ShowCaption property of dynamically created dock controls.

property ShowCaption: Boolean;

Description

Use the ShowCaption property to set the default value for the ShowCaption property of dock controls created dynamically.  Please refer to the dock control’s ShowCaption property description for details on the functionality it provides.

The default value of the ShowCaption property is True.


TdxCustomDockControlProperties.ShowHint

TdxCustomDockControlProperties

Specifies the default value of the ShowHint property of dynamically created dock controls.

property ShowHint: Boolean;

Description

Use the ShowHint property to set the default value for the ShowHint property of dock controls created dynamically.  Please refer to the control’s ShowHint property description for details on the functionality it provides.

The default value of the ShowCaption property is True.


TdxCustomDockControlProperties.Tag

TdxCustomDockControlProperties

Specifies the default value of the Tag property of dynamically created dock controls.

property Tag: Integer;

Description

Use the Tag property to set the default value for the Tag property of dock controls created dynamically.  Please refer to the dock control’s Tag property description for details on the functionality it provides.

The default value of the Tag property is 0.


TdxCustomDockControlProperties.Create

TdxCustomDockControlProperties

Creates an instance of the TdxCustomDockControlProperties class.

constructor Create(AOwner: TdxDockingManager); virtual;

Description

The constructor is used to create and initialize a new instance of the TdxCustomDockControlProperties class.  The AOwner parameter specifies the docking manager.  This is needed to access manager settings that affect all the dock controls.  For instance, when setting the ManagerColor property of a dock control to True, the dock control’s Color property must be initialized to the manager’s Color property value.

You will have no need to create instances of the TdxCustomDockControlProperties class in applications.  Its descendants are automatically created when the docking manager component initializes its properties.


TdxFloatDockSiteProperties
TdxFloatDockSiteProperties Object

Hierarchy          Properties          Methods

Provides the default settings for float sites.

Unit

dxDockControl

TdxFloatDockSiteProperties = class(TdxCustomDockControlProperties)

Description

The docking manager’s DefaultFloatSiteProperties property holds a TdxFloatDockSiteProperties object and this provides default values for dynamically created float sites.

The TdxFloatDockSiteProperties class simply publishes properties, as its functionality is implemented by its ancestor, the TdxCustomDockControlProperties class.


TdxFloatDockSiteProperties Hierarchy
Hierarchy

TPersistent

     |

TdxCustomDockControlProperties

     |


Properties for TdxFloatDockSiteProperties
TdxFloatDockSiteProperties Properties

TdxFloatDockSiteProperties          Legend

Derived from TdxCustomDockControlProperties

AllowDock

AllowDockClients

AllowFloating

CaptionButtons

Color

Cursor

Dockable

Font

Hint

ImageIndex

ManagerColor

ManagerFont

PopupMenu

ShowCaption

ShowHint

Tag


Methods for TdxFloatDockSiteProperties
TdxFloatDockSiteProperties Methods

TdxFloatDockSiteProperties          Legend

Derived from TdxCustomDockControlProperties

Create


TdxLayoutDockSiteProperties
TdxLayoutDockSiteProperties Object

Hierarchy          Properties          Methods

Provides the default settings for layout sites.

Unit

dxDockControl

TdxLayoutDockSiteProperties = class(TdxCustomDockControlProperties)

Description

The docking manager’s DefaultLayoutSiteProperties property holds a TdxLayoutDockSiteProperties object and this provides default values for dynamically created layout sites.

The TdxLayoutDockSiteProperties class simply publishes properties, as its functionality is implemented by its ancestor, the TdxCustomDockControlProperties class.


TdxLayoutDockSiteProperties Hierarchy
Hierarchy

TPersistent

     |

TdxCustomDockControlProperties

     |


Properties for TdxLayoutDockSiteProperties
TdxLayoutDockSiteProperties Properties

TdxLayoutDockSiteProperties          Legend

Derived from TdxCustomDockControlProperties

AllowDock

AllowDockClients

AllowFloating

CaptionButtons

Color

Cursor

Dockable

Font

Hint

ImageIndex

ManagerColor

ManagerFont

PopupMenu

ShowCaption

ShowHint

Tag


Methods for TdxLayoutDockSiteProperties
TdxLayoutDockSiteProperties Methods

TdxLayoutDockSiteProperties          Legend

Derived from TdxCustomDockControlProperties

Create


TdxSideContainerDockSiteProperties
TdxSideContainerDockSiteProperties Object

Hierarchy          Properties          Methods

Provides the default settings for side containers.

Unit

dxDockControl

TdxSideContainerDockSiteProperties = class(TdxCustomDockControlProperties)

Description

The docking manager’s DefaultHorizContainerSiteProperties and DefaultVertContainerSiteProperties properties hold TdxSideContainerDockSiteProperties objects and this provides default values for dynamically created side containers.

The TdxSideContainerDockSiteProperties class simply publishes properties, as its functionality is implemented by its ancestor, the TdxCustomDockControlProperties class.


TdxSideContainerDockSiteProperties Hierarchy
Hierarchy

TPersistent

     |

TdxCustomDockControlProperties

     |


Properties for TdxSideContainerDockSiteProperties
TdxSideContainerDockSiteProperties Properties

TdxSideContainerDockSiteProperties          Legend

Derived from TdxCustomDockControlProperties

AllowDock

AllowDockClients

AllowFloating

CaptionButtons

Color

Cursor

Dockable

Font

Hint

ImageIndex

ManagerColor

ManagerFont

PopupMenu

ShowCaption

ShowHint

Tag


Methods for TdxSideContainerDockSiteProperties
TdxSideContainerDockSiteProperties Methods

TdxSideContainerDockSiteProperties          Legend

Derived from TdxCustomDockControlProperties

Create


TdxTabContainerDockSiteProperties
TdxTabContainerDockSiteProperties Object

Hierarchy          Properties          Methods

Provides the default settings for tab containers.

Unit

dxDockControl

TdxTabContainerDockSiteProperties = class(TdxCustomDockControlProperties)

Description

The docking manager’s DefaultTabContainerSiteProperties property holds a TdxTabContainerDockSiteProperties object and this provides default values for dynamically created tab containers.

The basic functionality of this class is implemented by its ancestor, the TdxCustomDockControlProperties class.  The TdxTabContainerDockSiteProperties class publishes some inherited properties and introduces the TabsScroll and TabsPosition properties specific for tab containers.


TdxTabContainerDockSiteProperties Hierarchy
Hierarchy

TPersistent

     |

TdxCustomDockControlProperties

     |


Properties for TdxTabContainerDockSiteProperties
TdxTabContainerDockSiteProperties Properties

TdxTabContainerDockSiteProperties          Legend

In TdxTabContainerDockSiteProperties

TabsPosition

TabsScroll

Derived from TdxCustomDockControlProperties

AllowDock

AllowDockClients

AllowFloating

CaptionButtons

Color

Cursor

Dockable

Font

Hint

ImageIndex

ManagerColor

ManagerFont

PopupMenu

ShowCaption

ShowHint

Tag


Methods for TdxTabContainerDockSiteProperties
TdxTabContainerDockSiteProperties Methods

TdxTabContainerDockSiteProperties          Legend

Derived from TdxCustomDockControlProperties

Create


TdxTabContainerDockSiteProperties.TabsPosition

TdxTabContainerDockSiteProperties

Specifies the default value of the TabsPosition property of dynamically created tab containers.

property TabsPosition: TdxTabContainerTabsPosition;

Description

Use the TabsPosition property to set the default value for the TabsPosition property of tab containers created dynamically.  Please refer to the dock control’s TabsPosition property description for details on the functionality it provides.

The default value of the TabsPosition property is tctpBottom.


TdxTabContainerDockSiteProperties.TabsScroll

TdxTabContainerDockSiteProperties

Specifies the default value of the TabsScroll property of dynamically created tab containers.

property TabsScroll: Boolean;

Description

Use the TabsScroll property to set the default value for the TabsScroll property of tab containers created dynamically.  Please refer to the dock control’s TabsScroll property description for details on the functionality it provides.

The default value of the TabsScroll property is True.


TdxDockingManager
TdxDockingManager Object

Hierarchy          Properties          Methods          Events          Concepts

Enables you to provide centralized control over all dock controls in the application or the dock controls residing on particular forms.

Unit

dxDockControl

TdxDockingManager = class(TComponent)

Description

The TdxDockingManager component is used to centralize control over the dock controls’ appearance and behavior.  You can place a single component onto each form.  Thus, you can get the following controlling mechanisms depending on how many docking managers you use:

•	There are no docking manager components in the application.  In this case, the dock controls’ appearance and behavior is specified by the return values of the docking controller’s methods.  (Please refer to the TdxDockingController class description for details on the docking controller).

•	There is a single docking manager component in the application.  In this case, all dock controls are affected by that component.

•	There is a single docking manager component on each form.  In this case, each docking manager provides settings for controls residing on the same form.

•	There are several docking manager components in the application, but not on each form.  As in the previous case, each docking manager provides settings for controls residing on the same form.  Dock controls residing on forms that do not have a docking manager are controlled by the first docking manager component registered in the docking controller’s DockManagers collection.

Please refer to the Docking Manager Features topic for an overview of functionality provided by docking manager components.


TdxDockingManager Hierarchy
Hierarchy

TComponent

     |


Properties for TdxDockingManager
TdxDockingManager Properties

TdxDockingManager          Legend

In TdxDockingManager

AutoHideInterval

AutoHideMovingInterval

AutoHideMovingSize

AutoShowInterval

Color

DefaultFloatSiteProperties

DefaultHorizContainerSiteProperties

DefaultLayoutSiteProperties

DefaultSitesProperties

DefaultSitesPropertiesCount

DefaultTabContainerSiteProperties

DefaultVertContainerSiteProperties

DockZonesWidth

Font

Images

LookAndFeel

Options

ParentForm

ResizeZonesWidth

SelectionFrameWidth

TabsScrollInterval

UseDefaultSitesProperties

ViewStyle


Methods for TdxDockingManager
TdxDockingManager Methods

TdxDockingManager          Legend

In TdxDockingManager

LoadLayoutFromIniFile

LoadLayoutFromRegistry

LoadLayoutFromStream

SaveLayoutToIniFile

SaveLayoutToRegistry

SaveLayoutToStream


Events for TdxDockingManager
TdxDockingManager Events

TdxDockingManager          Legend

In TdxDockingManager

OnActiveDockControlChanged

OnCreateFloatSite

OnCreateLayoutSite

OnCreateSideContainer

OnCreateTabContainer

OnCustomDrawDockingSelection

OnCustomDrawResizingSelection

OnLayoutChanged

OnSetFloatFormCaption

OnUpdateDockZones

OnUpdateResizeZones

OnViewChanged


TdxDockingManager.AutoHideInterval

TdxDockingManager          See Also          Concepts

Specifies the time interval that passes before auto hiding a dock control.

property AutoHideInterval: Integer;

Description

When the auto hide feature is enabled for a dock control, the control’s behavior depends on whether it is currently active.  If inactive, it is automatically hidden when the mouse pointer leaves its area.  Otherwise, the control will be hidden when made inactive, provided that the mouse pointer is outside of it.

The AutoHideInterval property specifies the time interval that passes between the action that forces the control to be hidden and the actual start of hiding the control.  The property value is set in milliseconds.  If you need immediate control hiding, set this property to 0.

Setting the AutoHideInterval property to larger values allows you to avoid accidental control hiding.  This implies, that end-users will be able to return the mouse pointer to the control’s area after accidentally moving it away.

The default value of the AutoHideInterval property is dxAutoHideInterval.


TdxDockingManager.AutoHideMovingInterval

TdxDockingManager          See Also          Concepts

Specifies the time interval that passes between docking control displacements when it slides from the hidden to visible state or vice versa.

property AutoHideMovingInterval: Integer;

Description

Enabling the auto hide feature for a dock control implies that the control can be made visible or hidden in response to specific end user actions.  Hiding the control or making it visible, in this instance, is implemented using a sliding animation effect.  The control is moved with the specified time interval and size step.  The time interval is specified by the AutoHideMovingInterval property.  This property’s value is set in milliseconds.

For instance, if the AutoHideMovingInterval property value is 1, the control will be moved by the specified offset each millisecond.  If the constant value is 0, the control will be displayed immediately.

Setting the AutoHideMovingInterval property to smaller values results in smoother animation.  However, animation also depends upon the moving offset, which is specified by the AutoHideMovingSize property.  The two properties must be used in conjunction to achieve the desired result.

The default value of the AutoHideMovingInterval property is dxAutoHideMovingInterval.


TdxDockingManager.AutoHideMovingSize

TdxDockingManager            See Also         Concepts

Specifies the sliding step for controls whose auto hide feature is enabled.

property AutoHideMovingSize: Integer;

Description

The value of the AutoHideMovingSize property specifies the number of pixels by which the control is moved when automatically hidden or made visible.  The specified offset is applied to the control with the time interval specified by the AutoHideMovingInterval property.  Please refer to that property description for details.

Do not set the AutoHideMovingSize property to 0.  In this instance, dock controls will not be auto hidden.

The default value of the AutoHideMovingSize property is dxAutoHideMovingSize.


TdxDockingManager.AutoShowInterval

TdxDockingManager          See Also           Concepts

Specifies the time interval that passes before making auto hidden dock controls visible.

property AutoShowInterval: Integer;

Description

When the auto hide feature is enabled for a control, end-users can make the control visible by pointing the corresponding label with the mouse pointer.  The AutoShowInterval property specifies the time interval that passes between pointing to a label with the mouse pointer and the actual start of making the corresponding control visible.

The value of the AutoShowInterval property is set in milliseconds.  Set this constant to 0 if you don’t need an interval before starting to make the control visible.

Larger values of the AutoShowInterval property allow you to avoid accidental operations.  Large intervals will allow end-users to move the pointer away from a label if pointing to it accidentally.

The default value of the AutoShowInterval property is dxAutoShowInterval.


TdxDockingManager.Color

TdxDockingManager          See Also

Specifies the color of dock controls that use the manager’s color settings.

property Color: TColor;

Description

You can specify the color of a dock control using its Color property.  However, usually you will wish to specify the same color for all (or most) dock controls in the application.  To avoid multiple assignments, the docking manager component introduces the Color property.  Values assigned to this property are automatically assigned to the Color property of all dock controls that use manager color settings.  Dock controls use manager color settings if their ManagerColor property value is True.

Note that changing the Color property value of a dock control automatically sets the control’s ManagerColor property to False.  Thus, the control will not update its Color property value in response to manager settings changes unless the control’s ManagerColor property is set to True.


TdxDockingManager.DefaultFloatSiteProperties

TdxDockingManager          See Also          Concepts

Specifies the default settings for float sites.

property DefaultFloatSiteProperties: TdxFloatDockSiteProperties;

Description

When a dock panel, tab container or side container is set to float, an underlying float form is created.  However, those dock controls cannot reside directly on forms.  Thus, a float site is created to be the floating control’s parent.  This float site fills the entire client area of the form and is completely filled by its child, in turn.

Default settings of float sites are provided by the DefaultFloatSiteProperties property.  Each time a float site is created, these settings are used to initialize the site’s properties.  Thus, the DefaultFloatSiteProperties property can be used if you need float sites to be created with custom settings.

Note: changing the settings of the DefaultFloatSiteProperties property doesn’t affect existing float sites.  The specified settings are applied to float sites created subsequently.

You can disable the DefaultFloatSiteProperties property functionality by setting the UseDefaultSitesProperties property to False.


TdxDockingManager.DefaultHorizContainerSiteProperties

TdxDockingManager          See Also          Concepts

Specifies the default settings for horizontal side containers.

property DefaultHorizContainerSiteProperties: TdxSideContainerDockSiteProperties;

Description

If a dock control is successfully docked to the left or right edge of a dock panel or a tab container, a horizontal side container is created.  The container created becomes the parent for the docked control and the target control.

Default settings of horizontal side containers are provided by the DefaultHorizContainerSiteProperties property.  Each time a horizontal side container is created, these settings are used to initialize the container’s properties.  Thus, the DefaultHorizContainerSiteProperties property can be used if you need horizontal side containers to be created with custom settings.

Note: changing the settings of the DefaultHorizContainerSiteProperties property doesn’t affect existing horizontal side containers.  The specified settings are applied to horizontal side containers created subsequently.

You can disable the DefaultHorizContainerSiteProperties property functionality by setting the UseDefaultSitesProperties property to False.


TdxDockingManager.DefaultLayoutSiteProperties

TdxDockingManager          See Also          Concepts

Specifies the default settings for layout sites.

property DefaultLayoutSiteProperties: TdxLayoutDockSiteProperties;

Description

When docking a control to an edge of a dock site, a layout site is created.  This site occupies the area of the dock site that is not occupied by the docked control.  You can also a dock control to the edge of a layout site.  This results in creating a further layout site to occupy the remaining empty space.

Default settings of layout sites are provided by the DefaultLayoutSiteProperties property.  Each time a layout site is created, these settings are used to initialize the site’s properties.  Thus, the DefaultLayoutSiteProperties property can be used if you need layout sites to be created with custom settings.

Note: changing the settings of the DefaultLayoutSiteProperties property doesn’t affect existing layout sites.  The specified settings are applied to layout sites created subsequently.

You can disable the DefaultLayoutSiteProperties property functionality by setting the UseDefaultSitesProperties property to False.


TdxDockingManager.DefaultSitesProperties

TdxDockingManager          See Also

Provides indexed access to objects specifying the default settings of dock controls.

property DefaultSitesProperties[Index: Integer]: TdxCustomDockControlProperties;

Description

The docking manager component introduces properties that allow you to specify the default settings for dynamically created dock controls.  The DefaultFloatSiteProperties, DefaultHorizContainerSiteProperties, DefaultLayoutSiteProperties, DefaultTabContainerSiteProperties and DefaultVertContainerSiteProperties properties provide the default settings for dynamically created float sites, horizontal side containers, layout sites, tab containers and vertical side containers.

The DefaultSitesProperties property provides indexed access to objects holding the default settings for dock controls.  It can be used when you need to change settings in all or most of these default settings objects.  Thus, you can traverse through the list and perform the modifications desired.

The object currently accessed is specified by the Index parameter.  The index of the first object in the list is zero.  The last available index is the DefaultSitesPropertiesCount property value decremented by one.  If an invalid index is specified, the DefaultSitesProperties property returns nil.

ReadOnly property


TdxDockingManager.DefaultSitesPropertiesCount

TdxDockingManager          See Also

Returns the number of elements in the DefaultSitesProperties list.

property DefaultSitesPropertiesCount: Integer;

Description

The DefaultSitesProperties property provides indexed access to objects specifying the default settings for dock controls.  This property can be used in combination with the DefaultSitesPropertiesCount property to traverse the list of such objects.  The DefaultSitesPropertiesCount property returns the number of objects in the list.

ReadOnly property


TdxDockingManager.DefaultTabContainerSiteProperties

TdxDockingManager          See Also          Concepts

Specifies the default settings for tab containers.

property DefaultTabContainerSiteProperties: TdxTabContainerDockSiteProperties;

Description

When a control is docked to the client area of a dock panel, a tab container is created.  The container created becomes the parent for the docked control and the target control.  In other words, two controls are united by the tab container.

Default settings of tab containers are provided by the DefaultTabContainerSiteProperties property.  Each time a tab container is created, these settings are used to initialize the site’s properties.  Thus, the DefaultTabContainerSiteProperties property can be used if you need tab containers to be created with custom settings.

Note: changing the settings of the DefaultTabContainerSiteProperties property doesn’t affect existing tab containers.  The specified settings are applied to containers created subsequently.

You can disable the DefaultTabContainerSiteProperties property functionality by setting the UseDefaultSitesProperties property to False.


TdxDockingManager.DefaultVertContainerSiteProperties

TdxDockingManager          See Also          Concepts

Specifies the default settings for vertical side containers.

property DefaultVertContainerSiteProperties: TdxSideContainerDockSiteProperties;

Description

If a dock control is successfully docked to the top or bottom edge of a dock panel or a tab container, a vertical side container is created.  The created container becomes the parent for the docked control and the target control.  In other words, two controls are united by the side container.

Default settings of vertical side containers are provided by the DefaultVertContainerSiteProperties property.  Each time a vertical side container is created, these settings are used to initialize the container’s properties.  Thus, the DefaultVertContainerSiteProperties property can be used if you need vertical side containers to be created with custom settings.

Note: changing the settings of the DefaultVertContainerSiteProperties property doesn’t affect existing vertical side containers.  The specified settings are applied to vertical side containers created subsequently.

You can disable the DefaultVertContainerSiteProperties property functionality by setting the UseDefaultSitesProperties property to False.


TdxDockingManager.DockZonesWidth

TdxDockingManager           See Also          See Also

Specifies the default width of dock zones.

property DockZonesWidth: Integer;

Description

Dock zones are areas of dock controls where other controls can be docked.  There are two different kinds of dock zones.  One type of zone is aligned to edges of dock controls.  Other zones are aligned to the entire dock control or to its elements.

Zones of the first type have a fixed width.  If a single zone is at a control’s edge, its width is specified by the DockZonesWidth property.  This property value is set in pixels.

If there are several zones, they are placed one onto another.  The higher the zone, the less its width.  The width of the bottommost zone is specified by the DockZonesWidth property.  The image below shows examples.

For more information regarding dock zones, please refer to the Dock Zones topic.

The default value of the DockZonesWidth property is dxDockZonesWidth.


TdxDockingManager.Font

TdxDockingManager          See Also

Specifies the font used by dock controls.

property Font: TFont;

Description

You can specify font settings of individual dock controls by modifying their Font property value.  However, you will often need to provide the same font settings for all or most of the dock controls in your application.  This can be done using the docking manager’s Font property.  Values assigned to this property are automatically assigned to the Font property of all dock controls whose ManagerFont property value is True (the default).  Thus, the docking manager’s Font property affects the font settings of all dock controls by default.

Note that changing the Font property of a dock control automatically sets the control’s ManagerFont property to False.  Thus, subsequent changes to the manager’s Font property will not affect this control unless its ManagerFont property is set back to True.


TdxDockingManager.LookAndFeel

TdxDockingManager          See Also          Concepts

Provides look and feel settings for dock controls.

property LookAndFeel: TcxLookAndFeel;

Description

Settings provided by the LookAndFeel property are only used when the ViewStyle property is set to vsUseLookAndFeel value.  Otherwise, the painting style of dock controls is specified by the ViewStyle property.

The LookAndFeel property is represented by the TcxLookAndFeel object and its properties are used to specify the actual painting style.  Please refer to this class description for details on the settings it provides.


TdxDockingManager.Images

TdxDockingManager          See Also

Specifies the source of images used by dock controls.

property Images: TCustomImageList;

Description

Each dock panel can be associated with an image using its ImageIndex property.  When a panel is within a tab container, the associated image is displayed in the corresponding tab.  If the auto hide feature is enabled for the panel, the image is displayed within the label corresponding to the panel.  Images associated with panels are specified by their indexes within the source image list.  This image list is specified by the docking controller’s Images property.

To specify the source of images for dock controls, place a TImageList component onto the form and add the desired images to it.  Assign the image list to the docking manager’s Images property.


TdxDockingManager.Options

TdxDockingManager          See Also

Specifies a set of flags affecting the behavior of dock controls.

type

  TdxDockingOption = (doActivateAfterDocking, doDblClickDocking, doFloatingOnTop, doFreeOnClose, doUndockOnClose, doTabContainerHasCaption, doTabContainerCanClose, doTabContainerCanAutoHide, doSideContainerHasCaption, doSideContainerCanClose, doSideContainerCanAutoHide, doTabContainerCanInSideContainer, doSideContainerCanInTabContainer, doSideContainerCanInSideContainer, doImmediatelyHideOnAutoHide, doHideAutoHideIfActive, doRedrawOnResize, doFillDockingSelection, doUseCaptionAreaToClientDocking);

  TdxDockingOptions = set of TdxDockingOption;

property Options: TdxDockingOptions;

Description

The Options property provides a set of flags affecting dock controls’ functionality.  The following flags are available.

Flag	Description
doActivateAfterDocking	If enabled, dock controls become active after docking them to another dock control or to a site.  Please refer to the descriptions of the docking controller’s ActiveDockControl property or the dock control’s Activate method for more information on active dock controls.
doDblClickDocking	If enabled, dock controls can be made floating and returned back to their previous position by double-clicking their captions.  If a control is within a tab container, its tab must be double-clicked for this purpose.
doFloatingOnTop	If enabled, float forms are always displayed topmost.  This implies that the fsStayOnTop flag is enabled in the FormStyle property of float forms.  Otherwise, this flag is disabled and float forms may be hidden when other forms get focus.
doFreeOnClose	If enabled, dock controls are destroyed when closed (when their close button is clicked or the Close method is called).  Otherwise, the control is either simply made invisible or undocked.  This depends on the doUndockOnClose option setting.
doUndockOnClose	If enabled, dock controls are undocked when closed (when their close button is clicked or the Close method is called).  Otherwise, they are made invisible or destroyed.  This depends on the doFreeOnClose option setting. Please refer to the UnDock method description for details on the undocking functionality.
doTabContainerHasCaption	If enabled, tab containers display captions if their ShowCaption property is set to True.  Otherwise, tab container captions are not displayed regardless of the ShowCaption property value.
doTabContainerCanClose	If active, all children of a tab container are closed when clicking the close button within the container’s caption.  Otherwise, only the control corresponding to the selected tab is closed.
doTabContainerCanAutoHide	If enabled, pressing the auto hide button within a tab container’s caption enables the auto hide feature for the tab container.  Otherwise the auto hide feature is enabled for the tab container’s selected child only.
doSideContainerHasCaption	If enabled, vertical side containers display captions when within horizontal side containers.  Horizontal side containers display captions when within vertical side containers.  Note that side containers are allowed to be children of other side containers only when the doSideContainerCanInSideContainer option is enabled.
doSideContainerCanClose	If enabled, pressing the close button within a side container’s caption or calling the container’s Close method results in closing all the container’s children.  Otherwise, the active child of the side container is closed.  If there is no current active child, the first valid child control is closed.
doSideContainerCanAutoHide	If enabled, pressing the auto hide button within a side container’s caption or setting the container’s AutoHide property to True results in enabling the auto hide feature for the entire container.  Otherwise, the auto hide feature is enabled for the current active child control.  If there is no current active child, the feature is enabled for the first valid child control within the container.
doTabContainerCanInSideContainer	If enabled, tab containers can be children of side containers.
doSideContainerCanInTabContainer	If enabled, side containers can be children of tab containers.
doSideContainerCanInSideContainer	If enabled, side containers can be children of side containers.
doImmediatelyHideOnAutoHide	If enabled, dock controls are immediately hidden when the auto hide feature is enabled for them.  Otherwise, they are hidden using the sliding animation effect and only when the mouse pointer leaves their area.
doHideAutoHideIfActive	If a dock control’s auto hide feature is enabled and the control is active, the doHideAutoHideIfActive option defines this control’s behavior when the mouse pointer leaves its area.  If the option is active the control is automatically hidden in such cases.  Otherwise, the control remains visible (the default behavior).
doRedrawOnResize	If active, all the child controls within a container are redrawn when the container is resized.  This option is required to ensure that controls, which have transparent backgrounds, are painted correctly within a container.  The doRedrawOnResize option has no effect within a container, which has a paint style other than the vsOffice11 or vsXP styles applied to it. Note: When this option is active, resizing of a container might make the child controls flicker.
doFillDockingSelection	If active, a docking frame indicating a control’s potential position and size during drag operations is filled with the clHighlight system color.
doUseCaptionAreaForClientDocking	By default, to dock a control onto another with the client alignment, you need to drop a control into the target control’s center.  This takes place when the doUseCaptionAreaForClientDocking option is disabled.  If the option is active, you should drop controls to the captions of other controls to achieve the same result.  This enables you to imitate the Visual Studio .NET IDE behavior.


TdxDockingManager.ParentForm

TdxDockingManager

Returns the form where the docking manager resides.

property ParentForm: TCustomForm;

Description

The docking controller uses this property to find a docking manager that provides settings for controls residing on a particular form.  You may need to use this property to identify docking managers when traversing through the DockManagers collection.

ReadOnly Property


TdxDockingManager.ResizeZonesWidth

TdxDockingManager          See Also          Concepts

Specifies the default width of resize zones.

property ResizeZonesWidth: Integer;

Description

Resize zones are areas within dock controls where resizing can be initiated.  These areas are aligned to specific edges of the control and have a fixed width.  This width is specified by the ResizeZonesWidth property.  Its value is set in pixels.

For additional information on resize zones, please refer to the Resize Zones topic.

The default value of the ResizeZonesWidth property is dxResizeZonesWidth.


TdxDockingManager.SelectionFrameWidth

TdxDockingManager          See Also           Concepts

Specifies the default width of the pen used to paint the docking frame and resizing bar.

property SelectionFrameWidth: Integer;

Description

The image below shows the resizing bar when this property is set to 4 and 8 respectively.

Note that you can custom paint docking frames and resizing bars.  Please refer to the Docking Frame and Resizing Bar Custom Painting topic for details.

The default value of the SelectionFrameWidth property is dxSelectionFrameWidth.


TdxDockingManager.TabsScrollInterval

TdxDockingManager

Specifies the scrolling interval for tabs.

property TabsScrollInterval: Integer;

Description

When dock controls are joined into a tab container and the width of all the tabs exceeds the container’s width, you can control how tabs are displayed using the container’s TabsScroll property.  If the property value is True, the container displays scroll buttons that enable you to scroll through all the available tabs.  If a scroll button is held down, the container will continuously switch tabs.  The time interval that passes before switching to the next tab is specified by the TabsScrollInterval property.  This property value is set in milliseconds.

The default value of the TabsScrollInterval property is dxTabsScrollInterval.


TdxDockingManager.UseDefaultSitesProperties

TdxDockingManager          See Also          Concepts

Specifies whether dynamically created dock controls use default settings provided by the docking manager.

property UseDefaultSitesProperties: Boolean;

Description

If the UseDefaultSitesProperties property is set to True, dock controls created at runtime use settings provided by the docking manager to initialize themselves.  The table below shows the list of properties that provide the default settings for dock controls.

Property	Dock control type
DefaultFloatSiteProperties	Float site
DefaultHorizContainerSiteProperties	Horizontal side container
DefaultLayoutSiteProperties	Layout site
DefaultTabContainerSiteProperties	Tab container
DefaultVertContainerSiteProperties	Vertical side container

If the UseDefaultSitesProperties property value is False, dynamically created dock controls initialize their properties to default values.  Settings specified by the properties in the above table are ignored.


TdxDockingManager.ViewStyle

TdxDockingManager          See Also          Concepts

Specifies the painting style of dock controls.

type

  TdxDockingViewStyle = (vsStandard, vsNET, vsOffice11, vsXP, vsUseLookAndFeel);

property ViewStyle: TdxDockingViewStyle;

Description

Use the ViewStyle property to specify how dock controls are painted.  The following values are available for this property.

Value	Description
vsStandard	Dock windows use the painting style as in the Delphi IDE.
vsNET	Dock controls use the painting style as in the Visual Studio .NET IDE.
vsOffice11	Dock controls use the Microsoft Office 11 painting style.
vsXP	Dock controls use the Microsoft Windows XP painting style.  Note that this painting style can only be used if Windows XP is installed and an XP theme is currently used.  Otherwise, setting the ViewStyle property to vsXP will be the same as setting it to the vsStandard value.
vsUseLookAndFeel	The actual painting style of dock controls is specified by the LookAndFeel property. Note that if there is no docking manager in the application the painting style is specified by the docking controller’s ViewStyle property.  However, the TcxLookAndFeel object returned by the manager’s LookAndFeel property is not available in this case.  Thus, assigning the vsUseLookAndFeel value to the ViewStyle property of the docking controller is the same as assigning the vsStandard value.

Please refer to the Paint Styles topic for additional information.


TdxDockingManager.LoadLayoutFromIniFile

TdxDockingManager          See Also

Loads the layout of dock controls from the specified file.

procedure LoadLayoutFromIniFile(AFileName: string);

Description

Use the LoadLayoutFromIniFile method to restore the layout of dock controls from a file created using the SaveLayoutToIniFile method call.  The file is specified by its name and path via the AFileName parameter.  If the specified file doesn’t exist or is in use by another process, an exception is raised.  If the file doesn’t contain dock controls layout information, all dock panels become undocked.  Please refer to the dock control’s UnDock method description for details on undocking controls.

Note: the LoadLayoutFromIniFile method loads setting only for the controls which reside on the same form as the docking manager.  If the file contains settings for other controls these settings are ignored.  To load the layout of all dock controls in the application, use the docking controller’s LoadLayoutFromIniFile method.


TdxDockingManager.LoadLayoutFromRegistry

TdxDockingManager          See Also

Loads the layout of dock controls stored at the specified registry path.

procedure LoadLayoutFromRegistry(ARegistryPath: string);

Description

Use the LoadLayoutFromRegistry method to restore the layout of dock controls previously saved to a specific path in the registry using the SaveLayoutToRegistry method call.  The source registry path is specified by the ARegistryPath parameter.  If the specified path doesn’t exist or doesn’t contain dock controls layout settings, all dock panels become undocked.  Please refer to the dock control’s UnDock method description for details on undocking panels.

Note: the LoadLayoutFromRegistry method loads setting only for the controls which reside on the same form as the docking manager.  If the file contains settings for other controls these settings are ignored.  To load the layout of all dock controls in the application, use the docking controller’s LoadLayoutFromRegistry method.


TdxDockingManager.LoadLayoutFromStream

TdxDockingManager          See Also

Loads the layout of dock controls from the specified stream.

procedure LoadLayoutFromStream(AStream: TStream);

Description

Use the LoadLayoutFromStream method to restore the layout of dock controls previously saved to a stream using the SaveLayoutToStream method call.  The source stream is specified by the AStream parameter.  If the specified stream is nil, an exception is raised.  If the stream’s content is not dock controls layout information, all dock panels become undocked.  Please refer to the dock control’s UnDock method description for details on undocking panels.

Note: the LoadLayoutFromStream method reads information starting from the current position within the stream.  Thus, you may need to update the Position property of the source stream before calling the LoadLayoutFromStream method.

Note that the LoadLayoutFromStream method loads setting only for the controls which reside on the same form as the docking manager.  If the file contains settings for other controls these settings are ignored.  To load the layout of all dock controls in the application, use the docking controller’s LoadLayoutFromStream method.


TdxDockingManager.SaveLayoutToIniFile

TdxDockingManager

Saves the layout of dock controls to the specified file.

procedure SaveLayoutToIniFile(AFileName: string);

Description

Use the SaveLayoutToIniFile method to save the layout of dock controls to a file.  The target file is specified by its name and path using the AFileName parameter.  If the path is not specified, the file is created within the same folder as the application’s executable file.  Note that if the file’s extension is not specified, it is automatically set to ‘ini’.  If an empty string is specified as the parameter, the ‘.ini’ file will be created.

Settings saved by the SaveLayoutToIniFile method call can be restored using the LoadLayoutFromIniFile method.  If storing settings in an INI file doesn’t suit your needs, use either the SaveLayoutToRegistry or SaveLayoutToStream methods.

Note: the SaveLayoutToIniFile method saves the settings for dock controls which reside on the same form as the docking manager.  To save the dock controls layout for all forms in an application, use the docking controller’s SaveLayoutToIniFile method instead.


TdxDockingManager.SaveLayoutToRegistry

TdxDockingManager          See Also

Saves the dock controls layout to the specified registry path.

procedure SaveLayoutToRegistry(ARegistryPath: string);

Description

Use the SaveLayoutToRegistry method to save the layout of dock controls to a specific registry path.  The target registry path is specified by the ARegistryPath parameter.  This is the sub path for the system’s registry root key (HKEY_CURRENT_USER by default).

Settings saved by the SaveLayoutToRegistry method call can be restored using the LoadLayoutFromRegistry method.  If storing settings within the registry doesn’t suit your needs, use either the SaveLayoutToIniFile or SaveLayoutToStream methods.

Note: the SaveLayoutToRegistry method saves the settings for dock controls which reside on the same form as the docking manager.  To save the dock controls layout for all forms in an application, use the docking controller’s SaveLayoutToRegistry method instead.


TdxDockingManager.SaveLayoutToStream

TdxDockingManager          See Also

Saves the layout of dock controls to the specified stream.

procedure SaveLayoutToStream(AStream: TStream);

Description

Use the SaveLayoutToStream method to save the layout of dock controls to a stream.  The target stream is specified by the AStream parameter.  If the specified parameter value is nil, an exception is raised.  Note also, that if the specified stream is a file stream, the SaveLayoutToStream method call results in creating a file with the same content as if using the SaveLayoutToIniFile method.

Settings saved by the SaveLayoutToStream method call can be restored using the LoadLayoutFromStream method.  If storing settings within a stream doesn’t suit your needs, use either the SaveLayoutToIniFile or SaveLayoutToRegistry methods.

Note: the SaveLayoutToStream method saves the settings for dock controls which reside on the same form as the docking manager.  To save the dock controls layout for all forms in an application, use the docking controller’s SaveLayoutToStream method instead.


TdxDockingManager.OnActiveDockControlChanged

TdxDockingManager          See Also

Fires when the active dock control is changed.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnActiveDockControlChanged: TNotifyEvent;

Description

When clicking anywhere within a dock control, the dock control becomes active.  You can also set the active dock control via code either calling the desired control’s Activate method or by assigning the control to the docking controller’s ActiveDockControl property.  Please refer to the descriptions of these members for information on active dock controls.

The OnActiveDockControlChanged event fires immediately after the active dock control has been changed.  Handle this event if you need to perform actions in response to activating dock controls.  For instance, you can focus a specific control within the active dock control or display explanatory information about the activated control.

The Sender parameter of the event identifies the docking manager.


TdxDockingManager.OnCreateFloatSite

TdxDockingManager          See Also

This event fires immediately after a float site has been created.

type

  TdxCreateFloatSiteEvent = procedure(Sender: TdxCustomDockControl; AFloatSite: TdxFloatDockSite) of object;

property OnCreateFloatSite: TdxCreateFloatSiteEvent;

Description

When changing the state of a dock control to floating, its underlying float site is created.  This float site fills the client area of the float form in order to accommodate the dock control.  This is required since dock controls such as panels, tab containers and side containers cannot reside directly on forms.

The OnCreateFloatSite event fires each time the underlying float site is created for any of the dock controls in the application.  You can handle this event to perform common initialization of float sites.  Note, however, that if you only need to change default values of float sites’ properties, you can use the DefaultFloatSiteProperties property instead.  Thus, the OnCreateFloatSite event should be handled if you need to apply different settings for float sites created or if you simply need to respond to making dock controls floating.  Note that you can also respond to making individual dock controls floating or for creating their float sites.  Handle the OnCreateFloatSite or OnMakeFloating events of a dock control for this purpose.

The Sender parameter of the event identifies the dock control whose underlying float site is created.  Use this parameter to determine the control whose state has been changed to floating.  The AFloatSite parameter returns the created float site.

Note: dock controls can be made floating either by performing docking operations on them or by calling their MakeFloating method.


TdxDockingManager.OnCreateLayoutSite

TdxDockingManager          See Also

This event fires in response to layout site creation.

type

  TdxCreateLayoutSiteEvent = procedure(Sender: TdxCustomDockControl; ALayoutSite: TdxLayoutDockSite) of object;

property OnCreateLayoutSite: TdxCreateLayoutSiteEvent;

Description

When a control is docked to a dock site it becomes the dock site’s child control.  Also, a layout site is created and made a child of the dock site.  After this has been done, you can dock controls to the layout site.  If another dock control is docked to it, the layout site becomes the parent for the control and another layout site is created, etc.

Each time a layout site is created, the OnCreateLayoutSite event of its parent is raised.  The Sender parameter identifies the control that is the layout site’s parent.  The ALayoutSite parameter represents the layout site created.  Handle this event if you need to modify settings when creating layout sites.

Note that if you only need to change the default values for properties of dynamically created layout sites, you should use the DefaultLayoutSiteProperties property.


TdxDockingManager.OnCreateSideContainer

TdxDockingManager          See Also

This event fires in response to side container creation.

type

  TdxCreateSideContainerEvent = procedure(Sender: TdxCustomDockControl; ASideContainer: TdxSideContainerDockSite) of object;

property OnCreateSideContainer: TdxCreateSideContainerEvent;

Description

When a dock control is docked to an edge of another control, a side container is created.  The OnCreateSideContainer event fires immediately after this has been done.  The Sender parameter of the event identifies the control to which another one has been docked.  The ASideContainer parameter identifies the side container created.  You can use the Children property of the object represented by this parameter to access all dock controls comprising the side container.

Handle the OnCreateSideContainer event if you need to perform particular initialization of the side containers created.  However, note that if you only need to change the default property values for side containers, you should use the DefaultHorizContainerSiteProperties and DefaultVertContainerSiteProperties properties instead.


TdxDockingManager.OnCreateTabContainer

TdxDockingManager          See Also

This event fires in response to tab container creation.

type

  TdxCreateTabContainerEvent = procedure(Sender: TdxCustomDockControl; ATabContainer: TdxTabContainerDockSite) of object;

property OnCreateTabContainer: TdxCreateTabContainerEvent;

Description

When a dock control is docked to fill the client area of another control, a tab container is created.  The OnCreateTabContainer event is raised immediately after this has been done.  The Sender parameter identifies the control to which another control has been docked.  The ATabContainer parameter represents the tab container created.  You can use the Children property of the tab container to access all of its children.

Handle the OnCreateTabContainer event if you need to perform particular initialization when creating tab containers.  However, if you only need to change the default values of tab containers’ properties, you should use the DefaultTabContainerSiteProperties property instead.  The event should be handled if you need to perform conditional initialization or simply need to respond to the tab container’s creation.


TdxDockingManager.OnCustomDrawDockingSelection

TdxDockingManager          See Also         Concepts

Enables you to custom paint docking selections.

type

  TdxCustomDrawSelectionEvent = procedure(Sender: TdxCustomDockControl; DC: HDC; Zone: TdxZone; ARect: TRect; Erasing: Boolean; var Handled: Boolean) of object;

property OnCustomDrawDockingSelection: TdxCustomDrawSelectionEvent;

Description

The Sender parameter identifies the dock control being dragged.

The DC parameter specifies the handle to the display device context.

The ARect parameter specifies the potential position and size of the dock control relative to the top-left corner of the screen.

The AErasing parameter specifies whether to paint the docking selection or whether you need to erase the previously painted selection.

The Zone parameter identifies the dock zone of the target dock control that can currently accept the dragged control.  This parameter can be used to determine whether the control will be docked or left floating if the dragging operation completes now.  If the Zone parameter returns nil, the dock control will float if released.  Otherwise, it will be docked to another control.  If the Zone parameter value is not nil, you can read the target dock zone settings.  This can be used, for instance, to determine the edge of the target control to which the current one will be docked if released.

Use the Handled parameter value to specify whether default painting still needs to be performed.  Set this parameter to True if all painting has been done within the OnCustomDrawDockingSelection event handler.

To fill docking frames with the clHighlight system color, set the doFillDockingSelection flag in the Options property of a docking controller or manager.  To manually paint a docking frame of a desired dock control, handle the control’s OnCustomDrawDockingSelection event.  Please refer to the Docking Frame and Resizing Bar Custom Painting topic for more information and code examples.


TdxDockingManager.OnCustomDrawResizingSelection

TdxDockingManager          See Also         Concepts

Enables you to custom paint resizing bars.

type

  TdxCustomDrawSelectionEvent = procedure(Sender: TdxCustomDockControl; DC: HDC; Zone: TdxZone; ARect: TRect; Erasing: Boolean; var Handled: Boolean) of object;

property OnCustomDrawResizingSelection: TdxCustomDrawSelectionEvent;

Description

The Sender parameter identifies the dock control being resized.

The DC parameter specifies the handle to the display device context.

The ARect parameter specifies the position and size of the bar.  Note that this is the position and size that are used when for the default painting of the bar and you can use your own settings.  For instance, you can paint the bar with a different width.

The Erasing parameter specifies whether the event handler must erase the previously painted bar or paint it.

The Zone parameter represents the resize zone where the control resizing has been initiated.  You can use properties of the object returned by this parameter to obtain the initial position of the resize bar and to determine the resize direction.  Access the Rectangle and Direction properties of this object.

Use the Handled parameter to specify whether default painting needs to be performed.  If all the desired painting is implemented manually in the OnCustomDrawResizingSelection event, set this parameter to True.

To manually paint a resizing bar of a desired dock control, handle the control’s OnCustomDrawResizingSelection event.  Please refer to the Docking Frame and Resizing Bar Custom Painting topic for more information and code examples.


TdxDockingManager.OnLayoutChanged

TdxDockingManager          See Also          Concepts

This event fires each time the layout of dock control changes.

type

  TdxDockControlNotifyEvent = procedure(Sender: TdxCustomDockControl) of object;

property OnLayoutChanged: TdxDockControlNotifyEvent;

Description

Each time a dock control is docked to another dock control or made to float, the OnLayoutChanged event is raised.  Handle this event if you need to perform dock control updates each time its docking layout is changed.

The Sender parameter of the event allows you to identify the control on which the docking operation has been performed.

Note that the OnLayoutChanged event doesn’t fire in response to changing the size of controls.


TdxDockingManager.OnSetFloatFormCaption

TdxDockingManager          See Also

Enables you to change float form settings when the layout of dock controls change within them.

type

  TdxSetFloatFormCaptionEvent = procedure(Sender: TdxCustomDockControl; AFloatForm: TdxFloatForm) of object;

property OnSetFloatFormCaption: TdxSetFloatFormCaptionEvent;

Description

The OnSetFloatFormCaption event fires each time the layout of dock controls within a float site changes.  Use it if you need to change float form settings with respect to the current dock controls layout.  Most commonly, you will use this to specify the caption of the floating form.

The Sender parameter of the event identifies the float site.  Use its Child property to access the dock control residing within it.  The children of dock control obtained can be accessed via its Children property, etc.

The AFloatForm parameter provides access to the float form containing the site.

Note that you can also specify settings for individual float forms.  Handle the OnSetFloatFormCaption event of the corresponding float site for this purpose.


TdxDockingManager.OnUpdateDockZones

TdxDockingManager          See Also         Concepts

Enables you to provide custom dock zones for dock controls.

type

  TdxUpdateZonesEvent = procedure(Sender: TdxCustomDockControl; AZones: TList) of object;

property OnUpdateDockZones: TdxUpdateZonesEvent;

Description

Each control holds a list of dock zones in its DockZones property.  These zones specify where other controls can be docked and also provide the docking functionality.  You can modify the list of zones directly via this property, if needed.  However, the list will be automatically recalculated each time the layout of dock controls changes.  Thus, the OnUpdateDockZones event is provided so that you can modify the list as it is automatically repopulated.

The Sender parameter of the OnUpdateDockZones event specifies the control whose dock zones list has been repopulated.  The AZones parameter provides access to the list of zones (to the DockZones property of the control).  You can add your own or delete zones, if needed.

You can also specify custom dock zones for individual dock controls.  Handle the OnUpdateDockZones event for this purpose.


TdxDockingManager.OnUpdateResizeZones

TdxDockingManager          See Also         Concepts

Enables you to provide custom resize zones for the dock control.

type

  TdxUpdateZonesEvent = procedure(Sender: TdxCustomDockControl; AZones: TList) of object;

property OnUpdateResizeZones: TdxUpdateZonesEvent;

Description

Each dock control stores a list of resize zones in its ResizeZones property.  These zones specify areas of the control where resizing can be initiated and implement resizing.  If you need to provide custom resize zones for a control, you can modify its ResizeZones property value as required.  However, the list of zones will be automatically repopulated each time the dock control’s layout is changed.  Thus, the OnUpdateResizeZones event is provided.  It fires each time the list of resize zones of a control is repopulated, thus allowing you to update it as needed.

The Sender parameter of the OnUpdateResizeZones event specifies the control whose resize zones list is being repopulated.  The AZones parameter provides access to the list of zones (to the ResizeZones property).  You can add your own zones or delete them as needed.

You can also provide custom resize zones for individual dock controls.  Handle the OnUpdateResizeZones event for this purpose.


TdxDockingManager.OnViewChanged

TdxDockingManager          See Also          Concepts

This event fires in response to changing the painting style of dock controls.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnViewChanged: TNotifyEvent;

Description

The painting style of dock controls is specified by the ViewStyle property of the docking manager.  Changing this property value raises the OnViewChanged event.  Note that if the ViewStyle property value is vsUseLookAndFeel, the actual painting style of dock controls is specified by the LookAndFeel property of the docking manager.  In this case, the OnViewChanged event fires whenever the settings of the LookAndFeel property are changed.

Handle the OnViewChanged event to provide a proper response to changing the painting style of dock controls.  However, note that the OnViewChanged event is not raised when system settings change.

The Sender parameter of the event identifies the docking manager.


Dock Panels

Concepts List          See Also

Dock panels are the main building blocks of any docking application – they represent the client area of dock windows and serve as containers for any VCL control so that they act as forms in this regard.

Creating Dock Panels

To add a dock panel to your application, place a TdxDockPanel control onto a form.

Note that the dock panel is not placed directly onto the form.  An underlying float form is automatically created for it.  However, dock panels cannot reside on forms.  Thus, a float site is created on the float form to accommodate the panel.  This can be seen in the Object TreeView window.

Note: the form where a dock panel has been created is assigned to the ParentForm property of the panel.  Dock controls that have different values for the ParentForm property cannot be docked to one another.  Thus, if you have a dock site on another form, the dock panel cannot be docked to it.

If you already have a dock site on your form, you can place a new dock panel directly to the site.  The dock panel will reside on the dock site as a result.  The image below shows an example.

As can be seen in the Object TreeView window, the dock panel’s parent is the dock site control.  Also, a layout site is automatically created.  It fills the area of the dock site not occupied by the dock panel.  Please refer to the layout sites description for details on why it is needed.

Once a dock panel has been created, you can place VCL controls onto it.

Settings of Dock Panels

Dock panels provide a number of settings affecting their appearance and functionality.  The image below illustrates the most commonly used.  For a complete list of available settings, please refer to the TdxDockPanel class description.

The dock panel in the picture above is displayed with the auto hide feature enabled.  This is made to illustrate the ImageIndex property.  Note that the image specified by this property is also used when panels are in tab containers.  Please refer to the Tab Container Sites topic for details.

Feature Specifics

Caption Buttons

The dock panel’s caption is displayed when the panel is docked to a dock site (or layout site) or when it is within a side container.  The ShowCaption property must be set to True for this purpose.  The CaptionButtons property specifies which buttons are to be displayed.  Note however, that the auto hide button can only be displayed when the panel is not on a float form.  The maximize button can only be displayed when the panel is within a side container.

Auto Hide Feature

This feature is available to end-users if the auto hide button is displayed within the panel’s caption.  The previous paragraph explains when this button is visible.  If the auto hide feature is enabled, the label corresponding to the panel is displayed within the bar at the edge of the host dock site.  The label displays the panel’s caption and image.  These are specified using the Caption and ImageIndex properties.  If there is no image assigned, only the caption string is displayed.  Please see the image above for an example of the dock panel’s appearance when the auto hide feature is enabled for it.


Dock Sites

Concepts List          See Also

Dock sites hold dock controls on forms.  If there are no dock sites on a form, dock control can only float.  Also, dock sites provide the auto hiding functionality for dock controls.  When a control is docked to a dock site (or any layout site residing on it) the auto hide feature can be enabled for it.

Creating Dock Sites

To create a dock site, you need to place a TdxDockSite control onto a form.  The image below shows how this can be achieved.

Once a dock site is created, you can place dock controls onto it.

Generally, you will need a single dock site on a form.  If the dock site occupies the entire client area of a form, dock controls can be docked to any form edge as specified by the site’s AllowDockClients property.  However, only dock controls can reside on dock sites.  Thus, if you have a dock site that fills the entire form, you will need to place a dock panel onto it that will serve as the container for controls that must reside on the form.  Please refer to the Quick Start section for details on building a basic docking application.

Docking Controls to Dock Sites

To dock a control to a dock site, it must be dragged by its caption to the dock site’s area.  Basically, dock controls can be docked to any edge of the dock site and to its entire client area.  The image below shows how to dock a floating panel to the left edge of the dock site that fills the entire form.  (The design-time example is shown.)

As you can see in the above image, the dock panel displays its own caption when docked.  Also, the auto hide button is visible.

Consider the Object TreeView window that corresponds to the application state after the panel has been docked to the dock site.

As you can see, a layout site has been created.  This layout site fills the dock site’s area not occupied by the docked panel.  Other controls can be either docked to the dock site, the panel or the generated layout site.  Refer to the Layout Sites topic for more information on the purpose of layout sites.

Note that dock sites can have only two direct child controls – the docked control and the neighboring layout site.  These child controls can have their own children, etc.

Feature Specifics

Since dock sites merely serve as containers for other dock controls, they do not support many of the features provided by dock panels.  They cannot be docked or resized, cannot display caption buttons and the auto hide feature cannot be enabled for them.


Float Sites

Concepts List          See Also

Float sites hold dock controls on floating forms.  They are required since dock panels, tab containers and side containers cannot reside on forms directly.  For reference, refer to the TdxFloatDockSite class description.

When Float Sites are Created

Float sites are automatically created when making a dock control float.  The generated float site occupies the entire client area of the created float form.  The floating dock control, in turn, occupies the entire area of the float site.  Thus, you will never see float sites since they are hidden by child controls.

Note that float sites can have a single child only.  This can either be a dock panel, a tab container or a side container.  You can access the immediate child of the site using its Child property.

Having only a single child implies that no controls can be docked to float sites.  Controls can only be docked to float site’s children.  Thus, docking a control to a floating control will always form a container (either a tab container or a side container).

Consider the image below.  It shows a floating control and the corresponding Object TreeView window (that can be used to access the float site).

Feature Specifics

Since float sites merely serve as containers for other dock controls, they do not support many of the features provided by dock panels.  They cannot be docked or resized, cannot display caption buttons and the auto hide feature cannot be enabled for them.


Layout Sites

Concepts List          See Also

Layout sites provide advanced docking capabilities when arranging dock controls on a dock site.  They are dynamically created when docking controls to a dock site and can also hold their own child dock controls.  For reference information about layout sites, please refer to the TdxLayoutDockSite class description.

When Layout Sites are Created

When docking a control to a dock site, the control becomes the child of the site.  Also, the neighboring layout site is created.  The image below illustrates such a control layout.

Once a layout site has been created, you can dock controls to it.  When a control is docked to a layout site, it becomes the site’s child.  Also, the control’s neighboring layout site is created that fills the area of the first layout site that is not occupied by the docked control.  The image below shows an example.  (Since the structure of dock controls becomes complex, the first layout site is shown individually.)

The next image shows the Object TreeView window corresponding to such control layout.

Note that there is one additional way layout sites can be created.  When there are controls already docked to a dock site you don’t necessarily have to dock other controls to layout sites.  You can also dock them to the edge of the dock site itself.  In this instance, all the previously docked controls together with neighboring layout sites are moved to a newly created layout site that becomes a neighbor of the docked control.  The image below illustrates the layout of controls if the Folders panel was docked to the edge of the dock site rather than layout site.

What we’ve described so far in this topic give you the basic principles of creating layout sites.  Perhaps the best way to understand the technology is to dock controls to dock sites and see the changes in the Object TreeView window.  Also, this window can be used to select layout sites.  Thus, you will see their actual arrangement.

The Purpose of Layout Sites

The best way to explain the purpose of layout sites is to provide an example of creating a layout of panels on a form.  The form will correspond to a dock site and panels will correspond to dock panels.

Suppose you want to create the layout of panels as shown in the image below.

If you try to set the Align property of blue and green panels to alLeft and alBottom respectively, you will not get the desired layout.  Actually, the layout will be as displayed in the image below. (The bottom aligned panel occupies the entire edge of the form.)

To create the desired layout, you need to perform the following steps:

•	Create a blue panel and set its Align property to alLeft;

•	Create one additional panel (yellow in the image below) and set its Align property to alClient.  This panel will occupy all the form space not occupied by the blue panel;

•	Place a green panel onto the second panel (yellow) and set its Align property to alBottom.

The image below illustrates the result.

As you can see, the yellow panel is the analog of a layout site.  It is used to enable different layouts of panels.  In other words, it gives you the choice of whether to align a panel at the entire edge of the owning form, or to partially occupy this edge.

Feature Specifics

Since layout sites merely provide advanced arrangement capabilities, they do not support many of the features provided by dock panels.  They cannot be docked or resized, cannot display caption buttons and the auto hide feature cannot be enabled for them.


Tab Container Sites

Concepts List          See Also

Tab containers are a special kind of dock control that unite several other dock controls within them.  Their direct children may be dock panels or side containers.  Tab containers display a single child at a time.  End-users can switch between child controls using tabs.  The image below shows an example of a tab container.

For reference information on tab containers, please refer to the TdxTabContainerDockSite class description.

How to Create a Tab Container

By default, you can comprise a tab container from dock panels only.  To do so, you have to dock a panel to another panel so that the target control is filled entirely.  This implies that the mouse cursor should point in the middle of the target dock panel when dropping.  The image below shows an example.

Also, you can have side containers as direct children of a tab container.  To enable this feature, activate the doSideContainerCanInSideContainer option.  This option can be accessed via the Options property of the docking manager.  If the option is enabled, you can create a tab container in the same manner as with dock panels.  The image below shows an example.

If you need to drag individual controls away from the tab container, you must drag the corresponding tabs.

Settings of Tab Containers

Tab containers, as well as other dock controls, provide a number of settings specifying their appearance and functionality.  Also they provide settings for child management (switching between child controls).  The image below illustrates some of these settings.  For more information about tab containers, please refer to the TdxTabContainerDockSite class description.

Feature Specifics

Docking Operations

Docking operations on tab containers are available to end-users only when the tab container displays its caption.  When floating, the caption is always displayed.  When docked, the caption’s visibility is dependant upon the ShowCaption property of the tab container and the doTabContainerHasCaption option.

Tab containers can be docked to side containers only when the doTabContainerCanInSideContainer option is enabled.  Both options can be accessed via the Options property of the docking manager.

Caption Buttons

Caption buttons are displayed only when the tab container’s caption is visible.  The previous paragraph explains how the tab container’s caption visibility is controlled.

The behavior of the close button depends upon the doTabContainerCanClose option.  If enabled, pressing the close button hides the tab container together with its children.  Otherwise, only the currently active child is affected by the button.

The behavior of the auto hide button depends upon the doTabContainerCanAutoHide option.  If enabled, pressing the button results in activating the auto hide feature for the tab container.  Otherwise, the feature is activated for the currently active child.

Auto Hide Feature

If the auto hide feature is enabled for a tab container, only individual children can be displayed at a single time.  However, the labels corresponding to auto hidden child controls have a specific appearance.  The active child’s corresponding label displays the control’s caption and image.  Labels of other controls display images only.  Note that if there is no image assigned to a control, the first letters of the control’s caption are displayed.  The image below shows an example – a tab container with three child dock panels with the auto hide feature enabled.


Side Container Sites

Concepts List          See Also

Side containers are a specific kind of dock control that hold several child controls.  Child controls are displayed all at once and are arranged either vertically or horizontally.  The image below shows examples of a vertical side container.

For reference information on side containers, please refer to the TdxVertContainerDockSite and TdxHorizContainerDockSite class descriptions.

How to Create a Side Container

To create a horizontal side container, you need to dock one control to the left or right edge of another control.  The image below shows how to create a horizontal side container comprised of two dock panels.  One panel is docked to the left edge of another.

If you need to create a vertical side container, a dock control must be docked to the top or bottom edge of another control.  The image below shows an example.

Tab containers and side containers can be direct children of side containers.  Note however, that such functionality is only available when the doTabContainerCanInSideContainer and doSideContainerCanInSideContainer options are enabled respectively.  These options can be accessed via the Options property of the docking manager.

The image below shows an example of creating a side container whose children are a tab container and another side container.

Settings of Side Containers

Side containers, as well as dock panels provide a number of settings affecting their appearance and functionality.  Also, they provide settings for child management, such as specifying the currently active (maximized) child.  The image below shows some of these settings.  (The vertical side container is considered.)

For detailed information on features provided by side containers, please refer to the TdxVertContainerDockSite and TdxHorizContainerDockSite class descriptions.

Feature Specifics

Docking Operations

Docking operations on side containers are allowed only when their caption is visible.  When a side container is floating its caption is displayed independently of any settings.  If docked, the caption visibility is specified by the doSideContainerHasCaption option and the container’s ShowCaption property.

Side containers can be docked to tab containers only when the doSideContainerCanInTabContainer option is enabled.  If the doSideContainerCanInSideContainer option is active, side containers can be docked to other side containers.  Note that the latter implies that different kinds of containers are docked to each other (for instance, a vertical side container is docked to a horizontal side container).  If the same kind of side container are docked to each other, children of the source container are added to the target container.  Such operations are allowed independent of any settings.  Note also, that if the doSideContainerCanInSideContainer option is disabled, docking different kinds of side containers to each other results in forming a single side container of the target container’s kind.

Caption Buttons

The functionality of the close button is controlled by the doSideContainerCanClose option.  If enabled, the close button affects all the controls comprising the side container.  Otherwise, the button affects the currently active (maximized) child.  If none of the children is maximized, the first valid child is closed.  Refer to the ValidChildren property description for details on which children are considered valid.

The functionality of the auto hide button is controlled by the doSideContainerCanAutoHide option.  If enabled, pressing the auto hide button enables the auto hide feature for the side container.  Otherwise, the auto hide feature is enabled for the currently active child.  When there is no active child, the child control to be closed is determined in the same manner as described in the previous paragraph for the close button.

Auto Hide Feature

When the auto hide feature is enabled for a side container, the corresponding label displays captions of child panels separated by comma characters.  The image below shows an example.


Dock Controls Hierarchy

Concepts List

When building a docking application using the ExpressDocking Library, you will make use of three kinds of controls:

•	Dock Panels

These are the main building blocks of a docking application.  They represent panels that serve as containers for other controls.  Note that they cannot reside on forms as standard panel controls.  Instead, they can only reside on sites (either floating or not).  You can perform docking and resizing operations on dock panels in order to make them floating or docked.  Also, you can dock them to one another to create containers.

•	Sites

Sites are containers for dock controls.  Dock sites are used to accommodate dock controls on forms (when they are non-floating).  Note that you can only have floating dock controls if there are no dock sites on the form.  Layout sites are automatically created when dock controls are docked to dock sites.  They fill the dock site’s free space to provide advanced docking capabilities.  Finally, float sites are used to accommodate dock controls on float forms.

•	Containers

There are two different kinds of containers – tab containers and side containers.  Both of these are capable of holding several other dock controls (dock panels or other containers).  Tab containers display a single child control at a given time.  End-users can switch between children using tabs.  Side containers display their children all at once.  Child controls are arranged one after another either vertically (if using the vertical side container) or horizontally (if using the horizontal side container).  Note that you can perform docking operations on containers as well as on dock panels.

As you can see, these dock controls have common functionality.  For instance, both sites and containers can own child dock controls.  Docking operations can be performed on both containers and dock panels.  All common functionality is implemented in the TdxCustomDockControl class, the common ancestor for dock controls.

The image below shows an inheritance diagram.  You can click individual diagram items or click the corresponding links below to navigate to topics describing corresponding dock controls in detail.

TdxCustomDockControl

TdxDockPanel

TdxCustomDockSite

TdxLayoutDockSite

TdxFloatDockSite

TdxDockSite

TdxContainerDockSite

TdxTabContainerDockSite

TdxSideContainerDockSite

TdxVertContainerDockSite

TdxHorizContainerDockSite


The Docking Controller and Docking Managers

Concepts List          See Also

The ExpressDocking Library includes a docking manager component (TdxDockingManager) which can be used to provide centralized control over the appearance and behavior of dock controls. The image below shows this component on the component palette.

Control over docking operations together with the appearance and behavior of dock controls is provided by the docking controller – an instance of the TdxDockingController class. There is always a single docking controller instance in an application and it can be accessed via the dxDockingController global function call. The docking controller introduces a set of methods that return settings for the dock controls residing on a particular form. Thus, dock controls call the docking controller’s methods passing their parent form as the parameter. If the docking controller finds a docking manager component on the form specified, this docking manager’s settings are returned. This enables you to provide centralized control over the docking controls on each form by placing docking manager components on each.

The image below illustrates the approach described:

Note that each time a docking manager is placed onto a form, it is registered in the docking controller’s DockManagers collection. The first manager registered is used as the default docking manager.  This manager’s settings are used for dock controls owned by forms that do not have their own docking managers. This enables you to provide centralized control over dock controls on all forms using a single docking manager component. For this purpose, you only need to have a single docking manager in the application.

The image below shows how dock controls obtain their settings when there is a single docking manager in the application:

Note that if there are no docking managers in an application the docking controller’s methods return default values and thus, all dock controls have default behavior.

Note that the docking controller doesn’t only provide a means for interaction between dock controls and docking managers. It also introduces members which allow you to manage individual dock controls. For instance, you can specify the currently active dock control using the ActiveDockControl property or obtain the dock control located at a specified position using the GetDockControlAtPos method. Please refer to the TdxDockingController class description for more information on the docking controller’s abilities.

Please refer to the Docking Manager Features topic for a detailed description of features provided by the docking manager component.


Docking Manager Features

Concepts List

The docking manager (TdxDockingManager) provides centralized control over the appearance and behavior of all dock controls in an application.  Refer to the When to Use the Docking Manager topic for a brief overview of its benefits and an explanation as to when you may wish to incorporate it into your application.  This topic provides a description of the docking manager’s features in detail.

Generic Appearance Settings

The docking manager provides a number of properties that affect the appearance of dock controls in an application.  The image below shows these properties in the Object Inspector window.

The Color and Font properties specify the color and font used to paint dock controls whose ManagerColor and ManagerFont properties are set to True.  Note that True is the default value for these properties.  With them, you can provide a common appearance for all controls using only the docking manager’s properties.

The Images property represents the source of images for dock controls.  You should assign a TImageList component to this property.  Once an image list has been assigned, you can associate dock controls with images using the ImageIndex property of the controls.

Finally, the LookAndFeel and ViewStyle properties specify the painting style of dock controls.  All controls in the application are painted as specified by these two properties.  Please refer to the Paint Styles topic for more information on painting styles and examples.

Docking Options

The docking manager provides an Options property which represents a set of options affecting docking operations and other functionality for dock controls.  For instance, they specify whether different kinds of containers can reside within other containers, whether double-click docking operations are allowed and the behavior of caption buttons.  Please refer to the property descriptions for details on each option.

Default Settings of Dynamically Created Sites

Docking operations imply that dock controls are created dynamically.  For instance, a tab container or a side container can be dynamically created when docking one panel to another.  The docking manager provides a number of properties that specify default settings of dynamically created controls.  The image below shows these properties in the Object Inspector window.

For instance, you may need tab containers to be created with tabs located at the top.  For this purpose, expand the DefaultTabContainerSiteProperties property and set its TabsPosition attribute to tctpTop.  Note that changing this property will not affect existing tab containers.  This will be applied to the newly created containers only.

The specified default settings are only applied to controls if the UseDefaultSitesProperties property value is True (the default behavior).

Events

Most events provided by the docking manager duplicates events provided by dock controls.  Thus, you will not have to assign the same event handler to dock controls.  Instead you can assign a handler to a docking manager’s event.

The docking manager also provides two unique events.  The OnActiveDockControlChanged event fires each time the active dock control changes.  The OnViewChanged event notifies whether changes have been made to the painting style applied to controls.

One other unique event is the OnLayoutChanged.  This event fires immediately after changing the layout of dock controls in the application.  Handle this event if you need to provide a common response to docking operations.


Performing Docking Operations via Code

Concepts List          See Also

This topic describes how to perform docking operations via code.  For a general overview of docking operations, please refer to Docking Operations.

The table below lists dock controls methods that can be used to perform docking operations against them.

Method	Description
DockTo	Docks the control to a specified control with the specified docking type and index.
MakeFloating	Floats the control.  A float site becomes the control’s immediate parent as a result.
UnDock	Undocks the control.  The control has no parent as a result.

The DockTo method accepts three parameters.  These are the target control, docking type and docking index.  Thus, you can specify where to dock a control, how it must be docked and its position within the new parent’s children list.  For instance, the following code can be used to dock one panel to another in order to form a tab container.

// Delphi

dxDockPanelFolders.DockTo(dxDockPanelShortcuts, dtClient, -1);

The above code implies that the Folders panel is docked to the Shortcuts panel with client alignment.  Docking index is set to –1 indicating that the control should be added to end of its new parent’s children collection.  As such, the Folders panel will correspond to the last tab of the newly created tab container.

The MakeFloating method can be used to float the control.  As a result, the control is undocked from its current parent control and the underlying float form and a float site is created for it.  Note that the method has two overloads.  One of them enables you to float the control and set the position of the float form.  If it’s already floating, the method simply changes the position of the float form.  Another is equivalent to a double-click docking operation.  Please refer to the doDblClickDocking option for details on such operations.  This option is available via the Options property of the docking manager.

The following code makes the Folders panel float at the upper left corner of the owner form’s client area.

// Delphi

var

  APoint: TPoint;

// ...

with dxDockPanelFolders do

begin

  APoint := ParentForm.ClientRect.TopLeft;

  APoint := ParentForm.ClientToScreen(APoint);

  MakeFloating(APoint.X, APoint.Y);

end;

The last method used in docking operations is the UnDock method.  This method clears the control’s parent.  Thus, the control is undocked from any other control and not visible as a result.  However, this is not the same as setting the Visible property of a dock control to False.  In the latter case, the control remains docked to its parent.

We recommended that you use the UnDock method when customizing the layout of dock controls via code.  The reason is that performing the same docking operations on controls can lead to different docking layouts if they are not undocked.  If all controls are undocked before rearranging them, the resulting layout will always be the same.  Note that all controls are also undocked before restoring the saved layout by calling the LoadLayoutFromIniFile, LoadLayoutFromStream or LoadLayoutFromRegistry method.

The sample code below shows you how to undock all dock panels in an application.

// Delphi

var

  I: Integer;

// ...

I := 0;

with dxDockingController do

begin

  while I < DockControlCount do

  begin

    if (DockControls[I] is TdxDockPanel) and (DockControls[I].ParentDockControl <> nil) then

    begin

      DockControls[I].UnDock;

      I := 0;

    end

    else Inc(I);

  end;

end;


Controlling Docking Operations

Concepts List          See Also

The Docking Operations and Performing Docking Operations via Code topics provide an overview of docking operations available and how they can be performed via code.  This topic explains how you can respond to docking operations performed by end-users and how to provide custom functionality for such operations.

Responding to Docking Operations Performed by End-Users

Dock controls provide a number of events that fire in response to docking operations performed against them.  These events can be handled if you need to perform specific actions immediately after such operations are completed.  For instance, you may need to update the control’s layout or contents when it is docked or made to float.

The OnDock, OnMakeFloating and OnUnDock events fire in response to docking a control to another dock control, making it float and undocking it respectively.  Also, dock controls provide a OnLayoutChanged event that is raised when the layout of the control’s children is modified.  If you need to respond to any dock control layout changes in an application, handle the OnLayoutChanged event of the docking manager.

There are two more events provided by dock controls that fire when starting a docking operation and immediately after it has been completed.  These are the OnStartDocking and OnEndDocking events.

Providing Custom Constraints for Docking Operations

The AllowDock, AllowDockClients, AllowFloating and Dockable properties of dock controls enable you to specify constraints on docking operations performed on a dock control.  However, using these properties may not be enough.  For instance, the AllowDock property specifies how this control can be docked to other controls.  However, you may have a need to specify different logic for docking a control to different targets.  In such cases, handle the OnDocking event.  This event is raised repeatedly when performing a docking operation.  It enables you to specify whether docking to the current position is allowed.  After the event handler has been executed, the target dock control’s OnCanDocking event is raised.  Thus, the docking operation target can also cancel the docking operation being performed.

The following sample code handles the OnDocking event to allow panel docking only when the target is a dock site or layout site.  You can assign such an event handler to the OnDocking event of all panels.  As a result, panels will not be docked to one another and container sites will not be created.

// Delphi

procedure TForm1.dxDockPanel2Docking(Sender: TdxCustomDockControl;  Zone: TdxZone; X, Y: Integer; var Accept: Boolean);

begin

  if Zone = nil then Exit;

  if (Zone.Owner is TdxDockSite) or

     (Zone.Owner is TdxLayoutDockSite) then

    Accept := True

  else

    Accept := False;

end;

Controlling Double-Click Docking Operations

End-users can perform docking operations by double-clicking captions of dock controls.  When a control is a child of a tab container, its corresponding tab must be double-clicked.  Note that this functionality is only available when the doDblClickDocking option is enabled.  This option is available via the Options property of the docking manager.

A double-click docking operation floats a control.  If the control’s caption is double-clicked once again, the previous position of the control is restored.  You can provide custom behaviors for these operations by handling the OnStoreDockPosition and OnRestoreDockPosition events of dock controls.  Please refer to the appropriate event descriptions for additional information and code samples.


Controlling Resizing Operations

Concepts List          See Also

The basics of performing resizing operations on dock controls are explained in the Resizing Operations topic.  This topic provides information on how to respond to such operations and how to provide resizing constraints.

Responding to Resizing Operations Performed by End-Users

Dock controls provide a number of events that enable you to respond to control resizing.  When the resizing process starts, the OnStartResizing event of the dock control is raised.  Note that this happens immediately after an end-user has pressed the mouse button when the pointer is over a resize zone.  When the mouse pointer moves, the OnResizing event fires.  It enables you to perform specific actions during the resizing process.  When the mouse button is released, the dragged edge is moved to a new position and the OnEndResizing event is raised.

The sample code below shows an example of handling the OnStartResizing, OnResizing and OnEndResizing events.  The first is used to display a message within the status bar.  The second changes the message to display the potential width of the dock control (only horizontal resizing is processed).  The last event is used to clear the status bar.

// Delphi

procedure TForm1.dxDockPanel2StartResizing(Sender: TdxCustomDockControl; Zone: TdxZone; X, Y: Integer);

begin

  StatusBar1.SimpleText := 'Drag the border to resize the dock control';

end;

procedure TForm1.dxDockPanel2Resizing(Sender: TdxCustomDockControl; Zone: TdxZone; X, Y: Integer);

var AWidthDelta, ANewWidth: Integer;

begin

  if Zone.Direction = zdVertical then

  begin

    AWidthDelta := Zone.GetResizingSelection(Mouse.CursorPos).Left - Sender.ClientToScreen(Zone.Rectangle.TopLeft).X;

    if Zone.DockType = dtRight then

      ANewWidth := Sender.Width + AWidthDelta

    else

      ANewWidth := Sender.Width - AWidthDelta;

    StatusBar1.SimpleText := 'New Width: ' + IntToStr(ANewWidth);

  end;

end;

procedure TForm1.dxDockPanel2EndResizing(Sender: TdxCustomDockControl; Zone: TdxZone; X, Y: Integer);

begin

  StatusBar1.SimpleText := '';

end;

The image below shows the result of handling events in such a manner.  Note the status bar text.

To respond to changes in dock control dimensions, you can also handle the OnResize event.  This event is useful since it fires when the dock control is floating and its owning float form is resized.  Other events do not fire in such a case.

Providing Custom Resizing Constraints

You can provide constraints for resizing dock controls.  For instance, you can specify the maximum and minimum allowed dimension or implement a resizing step.  To do so, handle the OnCanResize event of the dock control.  The event repeatedly fires during resizing.  It provides a parameter that enables you to specify whether resizing to the current position is allowed.

Please refer to the OnCanResize event description for details on implementing resizing constraints and code samples.


Persisting Settings of Controls Residing in Dock Panels

Concepts List          See Also

When docking operations are performed, dock control handles change.  As a result, child control handles are also changed.  This creates a number of issues with control that reside on dock panels.  For instance, memo controls loose their selection settings. The same situation takes place when enabling or disabling the auto hide feature for a dock control.

To avoid such losses when docking, you can handle the OnStartDocking and OnEndDocking events.  The first enables you to save the desired settings.  The second event should be handled to restore them.  If you need to persist settings when enabling or disabling the auto hide feature for a dock control, handle its OnAutoHideChanging and OnAutoHideChanged events.  These also enable you to save settings before the handle is changed and restore them after the operation has completed.

A common approach to persisting control settings residing on dock panels is also available - the OnParentChanging and OnParentChanged events.  The first fires before the dock panel handle is changed.  Handle it to save the desired settings.  The second event is raised immediately after the handle has been changed thus allowing you to restore the saved settings.

If the OnParentChanging and OnParentChanged events are handled, you have no need to write any additional event handlers to implement settings persistence.


Docking Frame and Resizing Bar Custom Painting

Concepts List          See Also

This topic explains the basic principles of custom painting docking frames and resizing bars.

•	Docking Frame Custom Painting Sample

•	Resizing Bar Custom Painting Sample

Basic Principles of Painting Selections

If you need to provide custom painting for individual controls, handle their OnCustomDrawDockingSelection and OnCustomDrawResizingSelection events.  If you need to provide the same painting for all dock controls in an application, handle the OnCustomDrawDockingSelection and OnCustomDrawResizingSelection events of the docking manager.

All the mentioned events have a common syntax.  The code below illustrates this.

procedure(Sender: TdxCustomDockControl; DC: HDC; Zone: TdxZone; ARect: TRect; Erasing: Boolean; var Handled: Boolean);

The Zone parameter represents the dock zone when painting the docking frame.  Note that if the potential state of the dock control is floating, this parameter returns nil.  Thus you can provide a different appearance for the frame when it indicates floating and docked positions.  To do so, you need to provide different painting algorithms when the parameter value is nil and not.  Also, you can read the zone’s settings to determine the potential edge where the control will be docked if released.  This enables you to provide different painting with respect to docking type.

When resizing, the Zone parameter represents the resize zone where the operation has been initiated.  In this instance, the parameter value cannot be nil.  You can use properties of the obtained zone to determine whether horizontal or vertical resizing is being performed.

The Erasing parameter specifies whether the selection must be painted or erased.  This is needed since the selection is painted on screen directly and the previously painted selection must be erased before painting it in another position.  You will not need this parameter in most cases.  The reason is that it is recommended to paint selections using inverse brushes.  Painting the same selection at the same position will automatically erase the previously painted selection (all colors will be double inverted and thus restored).

The Handled parameter specifies whether default painting needs to be performed.  Set this parameter to True if the required painting is performed by the event handler.  Note that this parameter can also be used to provide conditional custom painting.  For instance, you can perform painting and set this parameter to True only when horizontal resizing is performed.  In other cases, the selection will be painted by default.


Paint Styles

Concepts List          See Also

Dock controls can be painted using four predefined paint styles.  The paint style is specified using the ViewStyle property of the docking manager.  If there is no docking manager in the application, you can use the ViewStyle property of the docking controller.

The image below shows how to change the ViewStyle property of the docking manager at design-time.

The possible paint styles are illustrated in the table below.  Images show the same control layout – a tab container and a dock panel whose auto hide feature is enabled.

vsStandard	vsNET
vsXP	vsOffice11

If the ViewStyle property is set to vsXP and the operating system is not Windows XP or the currently applied theme is Windows Classic, dock controls will be painted using the vsStandard style.

If the XP or Office 11 painting style is currently applied, the color scheme of dock controls is specified by system settings.  You can only change font settings of dock controls in such an instance.

When the ViewStyle property is set to vsUseLookAndFeel, the actual paint style is specified by the LookAndFeel property of the docking manager.  This property is represented by a TcxLookAndFeel object.  Please refer to this object description for details on settings it provides.  Note that specifying styles using the LookAndFeel property enables you to provide a common paint style for the entire application, since most Developer Express controls also make use of this technology.  To provide a common style, you need to place a TcxLookAndFeelController component onto the form.  Please refer to its description for details.


Docking Frame Custom Painting Sample

Concepts List          See Also

You have the following options to paint a docking frame that is displayed during docking operations:

•	Fill this frame with the clHighlight system color.  To do this, set the doFillDockingSelection flag in the Options property of a docking controller or manager).

•	Custom paint the docking frame by handling the docking manager's OnCustomDrawDockingSelection event.

•	Custom paint the docking frame for an individual dock control by handling only the control’s OnCustomDrawDockingSelection event.

Refer to the Docking Frame and Resizing Bar Custom Painting topic, for basic information about these events.

The following sample code handles the OnCustomDrawDockingSelection event of the docking manager.  If the potential state of the dock control is floating, the docking frame is painted by default.  Otherwise, the potential position of the dock control is filled with an inverse solid brush.

// Delphi

procedure TForm1.dxDockingManager1CustomDrawDockingSelection(Sender: TdxCustomDockControl; DC: HDC; Zone: TdxZone; ARect: TRect; Erasing: Boolean; var Handled: Boolean);

var

  ABrush, AOldBrush: HBRUSH;

begin

  if Zone = nil then Exit;

  ABrush := CreateSolidBrush($FFFFFF);

  AOldBrush := SelectObject(DC, ABrush);

  try

    with ARect do

      PatBlt(DC, Left, Top, Right - Left, Bottom - Top, PATINVERT);

    Handled := True;

  finally

    SelectObject(DC, AOldBrush);

    DeleteObject(ABrush);

  end;

end;

The image below illustrates a docking operation when the event is handled in this manner.


Resizing Bar Custom Painting Sample

Concepts List          See Also

You have the following options to paint a resizing bar that is displayed when resizing dock controls:

•	Custom paint the resizing bar by handling the docking manager's OnCustomDrawResizingSelection event.

•	Custom paint the resizing bar for an individual dock control by handling only the control’s OnCustomDrawDockingSelection event.

Refer to the Docking Frame and Resizing Bar Custom Painting topic, for basic information about these events.

The sample code below handles the docking manager’s OnCustomDrawResizingSelection event.  For horizontal resizing operations, the resizing bar is painted in the default manner.  For vertical resizing operations, the resizing bar is painted using an inverse texture brush.

// Delphi

procedure TForm1.dxDockingManager1CustomDrawResizingSelection(Sender: TdxCustomDockControl; DC: HDC; Zone: TdxZone; ARect: TRect; Erasing: Boolean; var Handled: Boolean);

var

  ABrush, AOldBrush: HBRUSH;

  Bitmap: TBitmap;

begin

  if Zone.Direction = zdVertical then Exit;

  Bitmap := TBitmap.Create;

  Bitmap.LoadFromFile('d:\SelectionBarTexture.bmp');

  ABrush := CreatePatternBrush(Bitmap.Handle);

  AOldBrush := SelectObject(DC, ABrush);

  try

    with ARect do

      PatBlt(DC, Left, Top, Right - Left, Bottom - Top, PATINVERT);

    Handled := True;

  finally

    SelectObject(DC, AOldBrush);

    DeleteObject(ABrush);

    Bitmap.Free;

  end;

end;

The image below shows the resulting appearance of the resizing bar.

The following image shows a bitmap that was used as the brush’s pattern.  (The image is magnified four times.  A red border was not used – it simply shows image boundaries.)


Overview

The ExpressDocking Library is provided as part of the ExpressBars Suite to give you the ability to create flexible docking applications with a couple of mouse clicks.  With this product, you can easily create complex interfaces just like the Visual Studio .NET IDE, Delphi IDE and others.  All you have to do is place a dock site on the form, add dock panels and populate them with the VCL controls you need.  The rest will be done for you automatically!  From this moment, you can dock panels to sites, float them or dock them to each other to form complex dock controls including tab containers and side containers.  And all this is achievable just by dragging them with the mouse and without having to write a single line of code!

And this is not all that the ExpressDocking Library offers you.  It gives you total control over docking and resizing operations using a wide set of specifically designed properties and events.  With the zones technology introduced, you are free to implement any docking behavior you can ever possibly ask for!

Below is the short summary of main features you will find when using the ExpressDocking Library:

•	Complete Design-time Support – the behavior of dock controls at design-time is just the same as at runtime.  This enables you to create dock window layouts at design-time using simple drag and drop operations.  Thus, you do not need to run the application again and again just to see the result.

•	Tab Containers Support – dock controls can form tab containers.  This enables you to use tabs to switch between them.  The Tab Containers topic provides additional information.

•	Side Containers Support – these are SideBar-like containers that are capable of arranging child controls either vertically or horizontally.  Please refer to the Side Containers topic for details.

•	Support for Layouts of Any Complexity – dock panels can be docked to each other to form either tab container or side containers.  These three types of control (dock panels and the two containers) can then be docked to construct any combination with no restrictions on docking types and with unlimited docking levels.

•	The Auto Hide Feature Support – this feature completely imitates the auto hide feature of dock windows in the Visual Studio .NET IDE.  Windows can be hidden automatically when moving the mouse outside them.  Pointing to their corresponding labels makes them visible again.  Please refer to the Auto Hide Feature topic for details.

•	Flexible Dock Controls Hierarchy – all dock controls (panels, containers and sites) are descendants of a single class and this simplifies runtime processing.  See the Dock Controls Hierarchy topic for additional information.

•	Docking Manager – the library provides a docking manager component that enables common control over the behavior and appearance of dock windows.  The When to Use the Docking Manager and Docking Manager Features topics provide a detailed overview of this functionality.

•	Four Predefined Paint Styles – with these styles your application can look just the same as the Delphi IDE, Visual Studio .NET IDE or Microsoft Office 11.  Also, the ExpressDocking Library provides XP theme support for its controls.  Please refer to the Paint Styles topic for details.

•	Look And Feel Support – you can make use of the look and feel technology used by most of Developer Express controls, thus providing a common look throughout the entire application.

•	Zones Technology – each dock control in the ExpressDocking Library owns a number of zones that specify its docking and resizing behavior.  You can customize the number and layout of these zones or create your own zones to provide any behavior you can imagine.  Please refer to the Zones Overview topic for more information.

•	Saving and Restoring the Layout – the docking manager enables you to save the current layout to a text file, stream or registry.  The saved layout can then be loaded to restore the previous position and dimensions of the docking controls.

•	Custom Painting – if you need to provide a custom display for docking frames or resizing bars, it’s not a problem.  Just handle an event.  Refer to the Custom Painting Overview topic for details.


Zones Overview

Concepts List          See Also

Dock controls own lists of dock zones and resize zones.  These zones are specially designed objects that implement the docking and resizing functionality of dock controls.  A general overview of these objects and their purpose is listed below.  For a detailed explanation on each zone type, please refer to the Dock Zones and Resize Zones topics.

General Overview

Zones are areas within the owning dock control.  Dock zones are areas where other controls can be docked.  In other words, when docking, the dock zone residing under the mouse pointer provides the docking functionality if the control is dropped.  When the mouse pointer is over a dock zone, the docking frame changes its size and position indicating the potential position of the control.  For example, consider a dock site.  It has four dock zones at its edges so that controls can be docked to the left, top, right and bottom edges.  It also contains a client zone that allows you to dock controls to the entire area of the dock site.

Resize zones are areas where resizing can be initiated.  When the mouse pointer is over a resize zone, the mouse cursor is changed thus indicating that resizing can be initiated here.  For instance, if a dock panel is docked to the left edge of a dock site, it has a single resize zone located at the right edge.  This enables resizing operations by dragging the right edge of the dock panel.

Dock zones and resize zones have common functionality and as such, have a common ancestor – the TdxZone class.  Also, a single TdxZone descendant can serve both as dock zone and resize zone.  If a zone is within a dock control’s DockZones list, its docking functionality is used.  If it resides within a dock control’s ResizeZones list, its resizing functionality is used.

Note that zones indicate the areas where docking and resizing operations can be performed and they also implement the actual operations and auxiliary functionality such as painting the docking frame and resizing bar.  Also, zone object are passed to a number of events.  They provide information on operations currently performed.  For instance, dock zones provide information on the type of docking operation performed.  Resize zones provide information about resizing direction.

Zones Hierarchy

The image below shows the inheritance diagram for zones.  Click the diagram items or the corresponding links below for a brief overview of each zone type.

TdxZone

TdxBottomZone

TdxAutoHideBottomZone

TdxAutoSizeBottomZone

TdxVertContainerZone

TdxClientZone

TdxAutoSizeClientZone

TdxDockPanelClientZone

TdxTabContainerZone

TdxTabContainerTabZone

TdxLeftZone

TdxAutoHideLeftZone

TdxAutoSizeLeftZone

TdxRightZone

TdxAutoHideRightZone

TdxAutoSizeRightZone

TdxHorizContainerZone

TdxTopZone

TdxAutoHideTopZone

TdxAutoSizeTopZone


Dock Zones

Concepts List          See Also

Each dock control holds lists of dock zones and resize zones.  A general overview of zone objects and complete lists of available zones can be found in the Zones Overview topic.  This topic describes the specifics of dock zones.

Dock Zones Functionality

Dock zones are TdxZone descendants representing areas within dock controls where other controls can be docked.  A list of such objects is stored within the control’s DockZones property.

There are two different kinds of zones with respect to their position within dock controls:

•	Dock zones that have a fixed width

Such dock zones occupy a rectangle at an edge of a dock control.  One dimension of the rectangle matches the length of the dock control’s edge.  Another dimension is specified by the width of the dock zone.  This width is specified by the zone’s constructor parameter and then returned by the Width property.  Note that the actual rectangle occupied by a zone is determined by reading its Rectangle property.  The image below shows an example of such a dock zone.

•	Dock zones that do not have a fixed width

The position and size of such zones depends upon the dimensions of the owner or some of its elements.  For instance, the TdxTabContainerTabZone dock zone occupies the area of a specific tab in tab containers.  The TdxDockPanelClientZone dock zone occupies the entire area of a dock panel.  The image below shows examples.

When performing a docking operation, the dock control residing under the mouse pointer is obtained.  If found, its list of dock zones is scanned.  If there is a dock zone under the mouse pointer and it can accept the dragged control, the docking frame changes its position and size to indicate that dropping can be performed.  The position and size of the docking frame at this moment is specified by the zone’s GetDockingSelection method.  The zone’s CanDock method is used to determine whether the obtained zone can accept the dragged control.

The image below shows an example of docking a control to the right edge of a floating panel.  The mouse pointer is over a zone and the docking frame indicating the potential position of the dragged control is displayed.

If the dragged control is dropped, it is docked to the control specified by the Owner property of the dock zone.  Docking type and index are specified by the DockType and DockIndex properties of the dock zone.

How Dock Zone Lists are Populated

Each time control layout changes, lists of dock zones are recalculated.  This means that the DockZones property of dock controls is cleared and populated with the required dock zones.  The reason for such recalculation is that dock controls contain not only their own dock zone but that some dock zones are provided by their parent controls and parents may change as the result of docking operations.  Thus, the Owner property of a dock zone doesn’t necessarily match the control whose DockZones property contains this zone.

Consider an example of a floating dock panel.  It has five dock zones – a zone at each edge and a client zone.  The image below illustrates such zone layout.

As you can see, zones can overlap.  Thus, their order within the list is important.  When searching for a zone residing under the mouse pointer, zones with smaller indexes are checked first.  In the image above, if pointing to the upper left corner of the dock control, the top dock zone will be considered as the target of the docking operation.

As mentioned above, parent controls can also provide zones for their children.  Consider a dock panel that is docked to the left edge of a dock site.  The underlying dock panel provides three dock zones for its child – the top, left and bottom zones.  Thus, end-users can choose whether to dock controls to the panel or to the dock site.

The image below shows top dock zones residing in a panel’s DockZones list when it is on a dock site.  Also, it shows the result of docking other panels to these zones.

As you can see, the width of parent zones is smaller than the width of control’s zones.  Thus, the closer the mouse pointer to an edge, the higher parent will accept the docked control.  Also, it can be seen that dock zones owned by parents are added to the list with smaller indexes so that they are on top of child’s zones.

Populating Dock Zone Lists Manually

Dock controls raise the OnUpdateDockZones event each time the list of dock zones has been recalculated.  This enables you to change the layout of zones within the control.  Also, you can provide a common logic to dock zone updates for all controls. Handle the OnUpdateDockZones event of the docking manager for this purpose.

The following sample code handles the OnUpdateDockZones event of a dock panel.  It removes all dock zones owned by this panel.  It also adds top and bottom zones that occupy the top and bottom portions of the dock control respectively.  Thus, dock zone layout will appear as shown in the image below (zone layout is shown for a floating panel).  Note that zones are added to the end of the list, thus allowing docking to parent zones.

Note: if you only need to disable docking to specific edges of a dock control, you have no need to handle the mentioned events.  Instead, use the AllowDockClients property of the dock control.  The events should be handled if you need to change the layout of dock zones.  For instance, you can change their size, as in the sample code below.

// Delphi

procedure TForm1.dxDockPanel1UpdateDockZones(Sender: TdxCustomDockControl; AZones: TList);

var I: Integer;

begin

  I := 0;

  while I < AZones.Count do

  begin

    if TdxZone(AZones.Items[I]).Owner = Sender then

      AZones.Delete(I)

    else

      Inc(I);

  end;

  AZones.Add(TdxTopZone.Create(Sender, Sender.Height div 2));

  AZones.Add(TdxBottomZone.Create(Sender, Sender.Height div 2));

end;


Resize Zones

Concepts List          See Also

Resize Zones Functionality

Resize zones, as well as dock zones, are descendants of the TdxZone class.  They are dock control areas where resizing operations can be started.  These areas reside at control edges.  One of their dimensions is specified by the length of the corresponding edge.  Another is specified by the zone width which is set as the constructor parameter.  Then, this width can be obtained using the Width property of the zone object.  The calculated bounding rectangle of the zone is returned by the Rectangle property.

The image below shows an example of a resize zone.

When the mouse pointer is over a dock control, the control’s ResizeZones list is scanned.  If a resize zone residing under the mouse pointer is found, the cursor’s appearance changes to indicate that resizing can be initiated.  If the zone’s Direction property returns zdVertical, the mouse cursor is changed to a vertical splitter.  If zdHorizontal is returned, it is changed to a horizontal splitter.

If resizing starts, the CanResize method of the zone is called in response to mouse movements.  This method determines whether the control’s edge can be moved to a position where the mouse pointer resides.  If resizing can be performed, the zone paints a resizing bar indicating the potential position of the control’s edge.  The bounding rectangle of the bar is returned by the GetResizingSelection method of the zone object.  The current mouse pointer location is passed to this method as the parameter.

When the dragging operation is complete, the resize zone changes the size of the owner control.  This owner control is returned by the Owner property of the zone object.  Note that this property’s return value doesn’t necessarily match the control whose ResizeZones list contains this zone.  The following section describes when this can happen.

How Resize Zones Lists are Populated

Each time the layout of dock controls changes, a list of resize zones is repopulated.  The reason is that resize zones can be supplied to a control by its parent and parents may change as a result of docking operations.

If a dock control is not within a tab container or a side container, its own resize zones are added to the ResizeZones list.  This means that the owner of these zones will be the control itself.  In this case, a single resize zone is added if the control is docked to an edge of a dock site or layout site.  The type of added zone is determined by the docking type of the control.  For instance, if a dock control is docked to the left edge, a right resize zone is added.  Thus, the control can be resized by dragging its right edge.  An example is shown in the image below.  Note that if the control is floating or occupies the entire area of the parent site, no resize zones are added to the list.

If within a tab container or a side container, the parent provides dock zones for the control.  The owner of zones is the parent control in this case.  The logic behind determining zone type is the same as described in the previous paragraph.  The only addition is that vertical side containers provide bottom zones for their children (except the last one).  Horizontal side containers provide right zones.

Suppose a tab container docked to the left edge of a dock site.  When the mouse pointer is in the position displayed in the image below, it is actually above the tab container’s child panel.  Thus, the panel’s zones will be used to implement resizing.  However, when dragging the panel’s edge, its parent tab container must be resized.  That is the reason for requesting resize zone from the parent control.  The image shows how resize zones are formed in this case.

Consider a more complicated layout of dock controls.

All resize zones displayed in the image are owned by vertical side container.  The process of populating the zones list can be described with the following points:

•	The vertical side container is docked to the left edge of a dock site.  Thus, a right resize zone is added to its zones list (blue).

•	The tab container is within a side container.  Thus, it requests resize zones from its parent.  The side container provides two zones.  The right zone (red) is provided to allow side container resizing by dragging the tab container’s edge.  The bottom zone (green) is provided to allow resizing of side container’s children.

•	The bottom panel is the child of the vertical side container.  Thus, it also requests resize zones from its parent.  The supplied right zone (orange) enables resizing the vertical side container by dragging the panel’s edge.

•	The Output panel is within the tab container.  Thus, it requests resize zones from its parent.  The parent, it turn, requests zones from the owning side container.  As a result, the right zone is added (yellow).  This zone allows you to resize the vertical side container by dragging the panel’s right-most edge.

Populating Resize Zone Lists Manually

Each time the list of a dock control resize zones has been repopulated, the control raises an OnUpdateResizeZones event.  You can handle this event to change the list of zones as needed.  You can also provide a common logic of modifying resize zone lists for all dock controls.  For this purpose, handle the OnUpdateResizeZones event of the docking manager.

The sample code below handles the OnUpdateResizeZones event of the docking manager.  It removes all resize zones whose Direction property returns zdHorizontal.  As a result, end-users will be unable to resize dock controls vertically.

// Delphi

procedure TForm1.dxDockingManager1UpdateResizeZones(Sender: TdxCustomDockControl; AZones: TList);

var I: Integer;

begin

  I := 0;

  while I < AZones.Count do

  begin

    if TdxZone(AZones.Items[I]).Direction = zdHorizontal then

      AZones.Delete(I)

    else

      Inc(I);

  end;

end;


TdxBottomZone
TdxBottomZone Object

Docking Functionality

Controls dropped onto the zone are docked to the bottom edge of the owner.

Resizing Functionality

Available when a control is docked to the top-most edge of a dock site or layout site.  Allows you to resize the owner control vertically by dragging its bottom-most edge.

Position

Occupies a rectangle at the bottom edge of the owning dock control.  The height of the rectangle is specified by zone width.  The width of the rectangle is specified by the corresponding edge’s length.


TdxLeftZone
TdxLeftZone Object

Docking Functionality

Controls dropped onto the zone are docked to the left edge of the owner.

Resizing Functionality

Available when a control is docked to the right edge of a dock site or layout site.  Allows you to resize the owner control horizontally by dragging its left-most edge.

Position

Occupies a rectangle at the left edge of the owning dock control.  The width of the rectangle is specified by zone width.  The height of the rectangle is specified by the corresponding edge’s length.


TdxTopZone
TdxTopZone Object

Docking Functionality

Controls dropped onto the zone are docked to the top edge of the owner.

Resizing Functionality

Available when a control is docked to the bottom edge of a dock site or layout site.  Allows you to resize the owner control vertically by dragging its top-most edge.

Position

Occupies a rectangle at the top edge of the owning dock control.  The height of the rectangle is specified by zone width.  The width of the rectangle is specified by the corresponding edge’s length.


TdxRightZone
TdxRightZone Object

Docking Functionality

Controls dropped onto the zone are docked to the right edge of the owner.

Resizing Functionality

Available when a control is docked to the left edge of a dock site or layout site.  Allows you to resize the owner control horizontally by dragging its right-most edge.

Position

Occupies a rectangle at the right-most edge of the owning dock control.  The width of the rectangle is specified by the zone width.  The height of the rectangle is specified by the corresponding edge’s length.


TdxClientZone
TdxClientZone Object

Available for dock sites and layout sites.

Docking Functionality

Controls dropped onto the zone fill the entire area of the owner.

Resizing Functionality

Not available.

Position

Occupies the entire client area of the owner control.


TdxVertContainerZone
TdxVertContainerZone Object

Available for vertical side containers only.

Docking Functionality

Not available.

Resizing Functionality

Gives you the ability to resize vertical side container children by dragging their bottom-most borders.

Position

Occupies a rectangle at the bottom edge of a vertical side container child.  The height of the rectangle is specified by zone width.  The width of the rectangle is specified by the corresponding edge’s length.


TdxHorizContainerZone
TdxHorizContainerZone Object

Available for horizontal side containers only.

Docking Functionality

Not available.

Resizing Functionality

Gives you the ability to resize horizontal side container children by dragging their right-most borders.

Position

Occupies a rectangle at the right edge of a horizontal side container child.  The width of the rectangle is specified by zone width.  The height of the rectangle is specified by the corresponding edge’s length.


TdxDockPanelClientZone
TdxDockPanelClientZone Object

Available only for dock panels that are not within a tab container.

Docking Functionality

Controls dropped onto the zone form a tab container with the owner control.

Resizing Functionality

Not available.

Position

Occupies the entire client area of the owner control.


TdxTabContainerZone
TdxTabContainerZone Object

Available only for tab containers and dock panels residing within them.

Docking Functionality

Controls dropped onto the zone are added to the tab container.

Resizing Functionality

Not available.

Position

Occupies the entire client area of the owner control.


TdxTabContainerTabZone
TdxTabContainerTabZone Object

Available for tab containers only.

Docking Functionality

Controls dropped onto the zone are added to the tab container.  The position of the docked control within the container is determined by the position of the tab where the zone resides.

Resizing Functionality

Not available.

Position

Occupies the area of a specific tab.


TdxAutoHideLeftZone
TdxAutoHideLeftZone Object

Available for dock controls docked to the right edge of a site when their auto hide feature is enabled.

Docking Functionality

Not available.

Resizing Functionality

Gives you the ability to resize dock controls by dragging their left edge.

Position

Resides at the left edge of the dock control.


TdxAutoHideTopZone
TdxAutoHideTopZone Object

Available for dock controls docked to the bottom edge of a site when their auto hide feature is enabled.

Docking Functionality

Not available.

Resizing Functionality

Gives you the ability to resize dock controls by dragging their top edge.

Position

Resides at the top edge of the dock control.


TdxAutoHideRightZone
TdxAutoHideRightZone Object

Available for dock controls docked to the left edge of a site when their auto hide feature is enabled.

Docking Functionality

Not available.

Resizing Functionality

Gives you the ability to resize dock controls by dragging their right edge.

Position

Resides at the right edge of the dock control.


TdxAutoHideBottomZone
TdxAutoHideBottomZone Object

Available for dock controls docked to the top edge of a site when their auto hide feature is enabled.

Docking Functionality

Not available.

Resizing Functionality

Gives you the ability to resize dock controls by dragging their bottom edge.

Position

Resides at the bottom edge of the dock control.


TdxAutoSizeLeftZone
TdxAutoSizeLeftZone Object

Supplied by right aligned dock sites whose AutoSize property value is True to dock controls residing within such sites.

Docking Functionality

Not available.

Resizing Functionality

Gives you the ability to resize dock controls by dragging their left edge.

Position

Resides at the left edge of the dock control.


TdxAutoSizeTopZone
TdxAutoSizeTopZone Object

Supplied by bottom aligned dock sites whose AutoSize property value is True to dock controls residing within such sites.

Docking Functionality

Not available.

Resizing Functionality

Gives you the ability to resize dock controls by dragging their top edge.

Position

Resides at the top edge of the dock control.


TdxAutoSizeRightZone
TdxAutoSizeRightZone Object

Supplied by left aligned or unaligned dock sites whose AutoSize property value is True to dock controls residing within such sites.

Docking Functionality

Not available.

Resizing Functionality

Gives you the ability to resize dock controls by dragging their right edge.

Position

Resides at the right edge of the dock control.


TdxAutoSizeBottomZone
TdxAutoSizeBottomZone Object

Supplied by top aligned or unaligned dock sites whose AutoSize property value is True to dock controls residing within such sites.

Docking Functionality

Not available.

Resizing Functionality

Gives you the ability to resize dock controls by dragging their bottom edge.

Position

Resides at the bottom edge of the dock control.


TdxAutoSizeClientZone
TdxAutoSizeClientZone Object

Available for dock sites whose AutoSize property value is True.

Docking Functionality

Gives you the ability to dock controls to the dock site. The dock site changes its size to fit the size of the docked control as the result.

Resizing Functionality

Not available.

Position

Occupies the entire dock site’s area.


Auto Hide Feature

Concepts List          See Also

The auto hide feature enables you to imitate the behavior of dock windows in the Microsoft Visual Studio .NET IDE.  When it is enabled for a dock control, the control is automatically hidden when the mouse pointer leaves its area.  Also, the host dock site displays a bar at the edge where the control is hidden.  Such bars contain labels corresponding to the controls that are hidden to this edge.  Each label displays the caption text and image of the associated control.  When end-users point to a label with the mouse, the appropriate control becomes visible.

End-users can enable this feature by clicking the auto hide button displayed within the control’s caption.  Note that this button is displayed only if the cbHide option of the control’s CaptionButtons property is enabled.  The feature can also be enabled via code by setting the control’s AutoHide property to True.

The image below illustrates how the auto hide feature can be enabled and how to show the hidden control.

Note that if the control is activated, it is not automatically hidden when the mouse pointer leaves its area.  Dock controls can be activated by clicking their captions or by focusing any control residing within them.  When the auto hide feature is enabled, it can also be activated by clicking its corresponding label.  Finally, you can activate a control via code either by calling the control’s Activate method or assigning the control to the docking controller’s ActiveDockControl property.

Sometimes you may need to show and hide an auto hidden control via code.  For instance, you may want to make a control visible in response to pressing a specific key.  To do this, you need to assign the desired control to the ShowingControl property of the dock site where it resides.  This dock site can be obtained via the AutoHideHostSite property of the control.  Please refer to this property description for a code example.

If you need to respond to showing or hiding the control, handle the OnShowControl and OnHideControl events of the host dock site.

Note that by default, dock controls are hidden at the nearest dock site’s edge.  Thus, if a control is docked to the right edge of a dock site, it will be hidden at the right edge.  If a dock control fills the entire area supplied, the edge where it will be hidden is determined taking into account its dimensions and position.  However, you can manually specify the edge where to hide the control.  For this purpose, handle the control’s OnGetAutoHidePosition event.

Finally, the docking manager component provides a number of properties that affect the behavior of auto hidden controls.  The table below lists these properties and provides their descriptions.

Property	Description
AutoHideInterval	Specifies the time interval that passes before dock controls are hidden.  If the dock control is not active, for instance, this is the interval between moving the mouse pointer away from the control’s area and starting to hide the control.
AutoHideMovingInterval	Specifies the time interval between control displacements when the control is sliding to become visible or hidden.
AutoHideMovingSize	Specifies the number of pixels by which the dimensions of a dock control change when it slides to change its visibility state.  The dimension changes occur repeatedly for every time interval specified by the AutoHideMovingInterval property.
AutoShowInterval	Specifies the time interval that passes before dock controls are shown.  For instance, this is the time taken from pointing to the control’s corresponding label and the start of displaying the control.

Dock panels, tab containers and side containers have additional concepts related to the auto hide feature.  Please refer to their descriptions for details.


Caption Buttons

Concepts List          See Also

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.  The available button types are the close button, auto hide button and maximize button.

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.

Pressing the auto hide button activates the auto hide feature for the control.  Please refer to the Auto Hide Feature topics for details.

The Maximize Button

The maximize button is displayed within control captions within side containers.  When clicking the button, the corresponding dock control becomes the container’s active child.  This implies that the control is maximized to fill the entire client area of the container.  Clicking the button once again restores the previous size of the control.

You can also maximize controls via code.  To do so, you must 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.


Docking Operations

Concepts List          See Also

This topic describes how end-users can perform docking operations.  Also, it provides information on the properties and options that affect the availability of such operations and the result of performing them.

Basically, docking operations use drag and drop.  Dragging can be initiated in the caption area of a dock control or in its corresponding tab (when a control is a child of a tab container).  After dragging has been started, the control remains at the same position.  Its potential target position and size are displayed by a docking frame as shown in the image below.

Note: the frame shown in the image above can be painted in a custom manner.  Please refer to the Docking Frame and Resizing Bar Custom Painting topic for more information regarding this.

Anytime during the docking operation, end-users can press the ESC key to cancel the current operation.  The dock control remains at the same position and the docking frame.  Also, they can use the CTRL key when performing docking operations.  When this key is pressed, the dock control cannot be docked to a dock site or another control if dropped.  This is useful, for instance, if you want the control to float over a dock site.  If dropped when not using the CTRL key, the control will be docked to the site or the control residing under the mouse pointer.

Note that there are four properties that affect the individual behavior of dock controls:

Property	Description
AllowDock	Specifies how the dock control can be docked to other dock controls.
AllowDockClients	Specifies how other dock controls can be docked to the dock control.
AllowFloating	Specifies whether the dock control can be made to float.
Dockable	Specifies whether docking operations can be performed on the dock control.

Another way of performing docking operations is to double-click the caption of a dock control.  If the control is currently docked to a dock site, tab container or side container, it then floats.  If the caption is double-clicked once again, the dock control is restored to its previous position.  Note: this functionality can be disabled by deactivating the docking manager’s doDblClickDocking option.  Please refer to the docking manager’s Options property description for details.

Docking functionality can also be controlled by handling events.  Please refer to the Controlling Docking Operations topic for details.  The Performing Docking Operations via Code topic, in turn, shows how to perform docking operations using code.

Note that tab containers and side containers have particular facilities related to docking operations.  Please refer to their descriptions for details.


Resizing Operations

Concepts List

This topic provides information on how end-users can perform resizing operations on dock controls.  Also, it lists topics that give additional information about how such operations can be controlled via code.

Basically, resizing operations are dragging operations.  When a dock control is floating, it can be resized by dragging the borders or corners of the float form.

When controls are docked to an edge of a dock site (or layout site), you can resize them by dragging their edges.  Note that the control is not resized immediately when dragging the edge.  A bar indicating the edge’s potential position is painted when dragging.  The control changes its size when dropped.  The image below shows an example.

Note:  the bar indicating the edge’s potential position can be painted in a custom manner.  Please refer to the Docking Frame and Resizing Bar Custom Painting topic for details.

You can also use the same technique to resize dock controls when they comprise side containers.

When resizing dock controls that are docked to a site or comprise a side container, the OnCanResize event is raised.  You can handle this event to specify whether resizing to the current potential position is allowed.  This can be used to specify the maximum or minimum sizes of the dock control, the resizing step, etc.

Also, dock controls provide a number of events that fire when starting or finishing the resizing process and fire repeatedly when resizing.  However, not all these events fire for dock controls when they are resized as the result of resizing the owning float form.  Please refer to the Controlling Resizing Operations topic for details and code examples.


Concepts List

Common Features

Docking Operations

Resizing Operations

Auto Hide Feature

Caption Buttons

Dock Controls

Hierarchy

Dock Panels

Dock Sites

Layout Sites

Float Sites

Containers

Tab Container Sites

Side Container Sites

Docking Manager

When to Use the Docking Manager

Docking Manager Features

Paint Styles and Custom Painting

Paint Styles

Docking Frame and Resizing Bar Custom Painting

Overview

Docking Frame Custom Painting Sample

Resizing Bar Custom Painting Sample

Dock Zones and Resize Zones

Zones Overview

Dock Zones

Resize Zones

Managing Dock Controls via Code

Performing Docking Operations

Controlling Docking Operations

Controlling Resizing Operations

Persisting Settings of Controls Residing in Dock Panels


Legend

Protected

Published

ReadOnly


Dock Controls

Dock panels, dock sites, layout sites, float sites, tab containers and side containers are referred to as dock controls.  The reason is that they are derived from the same TdxCustomDockControl class and, thus, have much in common.


Docking Frame

A frame (also called a docking selection) that indicates a dock control’s potential position and size during docking operations.


Resizing Bar

A bar that indicates the potential position of a dock control’s edge during resizing operations.


dxDockConsts Unit Overview
dxDockConsts Unit

Global Constants

dxAutoHideInterval

dxAutoHideMovingInterval

dxAutoHideMovingSize

dxAutoShowInterval

dxDefaultImageHeight

dxDefaultImageWidth

dxDockZonesWidth

dxResizeZonesWidth

dxSelectionFrameWidth

dxTabsScrollInterval


dxAutoHideInterval constant
dxAutoHideInterval global constant

See Also          Concepts

Holds the default time interval that passes before auto hiding a dock control.

Unit

dxDockConsts

dxAutoHideInterval = 500;

Description

The dxAutoHideInterval constant is used for two purposes:

•	provides the default value for the AutoHideInterval property of docking managers;

•	provides the return value for the docking controller’s AutoHideInterval method if there are no docking managers in the application.


dxAutoHideMovingInterval constant
dxAutoHideMovingInterval global constant

See Also          Concepts

Specifies the default time interval that passes between docking control displacements when it slides from the hidden to visible state or vice versa.

Unit

dxDockConsts

dxAutoHideMovingInterval = 1;

Description

The dxAutoHideMovingInterval constant is used for two purposes:

•	provides the default value for the AutoHideMovingInterval property of docking managers;

•	provides the return value for the docking controller’s AutoHideMovingInterval method if there are no docking managers in the application.


dxAutoHideMovingSize constant
dxAutoHideMovingSize global constant

See Also          Concepts

Specifies the default sliding step for controls whose auto hide feature is enabled.

Unit

dxDockConsts

dxAutoHideMovingSize = 20;

Description

The dxAutoHideMovingSize constant is used for two purposes:

•	provides the default value for the AutoHideMovingSize property of docking managers;

•	provides the return value for the docking controller’s AutoHideMovingSize method if there are no docking managers in the application.


dxAutoShowInterval constant
dxAutoShowInterval global constant

See Also          Concepts

Specifies the default time interval that passes before making auto hidden dock controls visible.

Unit

dxDockConsts

dxAutoShowInterval = 300;

Description

The dxAutoShowInterval constant is used for two purposes:

•	provides the default value for the AutoShowInterval property of docking managers;

•	provides the return value for the docking controller’s AutoShowInterval method if there are no docking managers in the application.


dxDefaultImageHeight constant
dxDefaultImageHeight global constant

Specifies the default length of labels corresponding to auto hidden tab container children docked to the left or right edge of a dock site.

Unit

dxDockConsts

dxDefaultImageHeight = 16;

Description

When the auto hide feature is enabled for a tab container, the size of labels corresponding to its children is calculated as shown in the image below.

The height of images is specified by image list settings assigned to the Images property of the docking manager.  However, there may be no image list assigned in which case, the dxDefaultImageHeight constant value is used.  The image below shows the same control layout when there is no image list assigned and the dxDefaultImageHeight constant value is 40.


dxDefaultImageWidth constant
dxDefaultImageWidth global constant

Specifies the default length of labels corresponding to auto hidden tab container children docked to the top or bottom edge of a dock site.

Unit

dxDockConsts

dxDefaultImageWidth = 16;

Description

dxDefaultImageWidth functionality is almost the same as the functionality of the dxDefaultImageHeight constant.  The only difference is that the dxDefaultImageWidth constant value is used when tab containers are docked to the top or bottom edge of a site.

Please refer to the dxDefaultImageHeight constant description for details.


dxDockZonesWidth constant
dxDockZonesWidth global constant

See Also          Concepts

Specifies the default width of dock zones.

Unit

dxDockConsts

dxDockZonesWidth = 20;

Description

The dxDockZonesWidth constant is used for two purposes:

•	provides the default value for the DockZonesWidth property of docking managers;

•	provides the return value for the docking controller’s DockZonesWidth method if there are no docking managers in the application.


dxResizeZonesWidth constant
dxResizeZonesWidth global constant

See Also          Concepts

Specifies the default width of resize zones.

Unit

dxDockConsts

dxResizeZonesWidth = 3;

Description

The dxResizeZonesWidth constant is used for two purposes:

•	provides the default value for the ResizeZonesWidth property of docking managers;

•	provides the return value for the docking controller’s ResizeZonesWidth method if there are no docking managers in the application.


dxSelectionFrameWidth constant
dxSelectionFrameWidth global constant

See Also          Concepts

Specifies the default width of the pen used to paint the docking frame and resizing bar.

Unit

dxDockConsts

dxSelectionFrameWidth = 4;

Description

The dxSelectionFrameWidth constant is used for two purposes:

•	provides the default value for the SelectionFrameWidth property of docking managers;

•	provides the return value for the docking controller’s SelectionFrameWidth method if there are no docking managers in the application.


dxTabsScrollInterval constant
dxTabsScrollInterval global constant

Specifies the default scrolling interval for tabs.

Unit

dxDockConsts

dxTabsScrollInterval = 300;

Description

The dxTabsScrollInterval constant is used for two purposes:

•	provides the default value for the TabsScrollInterval property of docking managers;

•	provides the return value for the docking controller’s TabsScrollInterval method if there are no docking managers in the application.


Adding Components and Controls

Quick Starts

The ExpressDocking Library provides three components that are displayed within the ExpressBars palette: TdxDockingManager, TdxDockSite and TdxDockPanel.  This topic briefly describes each component and provides information on when to use them.

Dock Panels

Dock panels are the main building blocks of a docking application’s interface.  They represent dock windows’ client areas and serve as containers for VCL controls.  Dock panels can be located on individual floating forms or on your application’s forms (floating or docked).  By default, when a dock control is placed on a form, it floats automatically.  If you need to allow dock panels to be docked to forms, you should use the TdxDockSite component described later in this topic.

The image below shows a floating dock panel with a memo control containing two buttons.

Placing components on dock panels is similar to placing them on forms.  Note, however, that when removing, copying, pasting controls and other similar operations involving a floating dock panel, you should use the control’s context menu to perform such operations.

An important point about dock panels is that they can be docked to each other to form container controls.  There are two container types available – tab containers and side containers.  Container controls can also be joined into containers.  For instance, you may join a side container and a panel into a tab container.  Note: there is no limit to container nesting levels.

Please refer to the Dock Controls Hierarchy topic for additional information on the dock panels and containers available.

Dock Sites

Dock sites are components that support the placing of panels onto forms.  Note: these sites can only accept docking controls (panels or containers).

However, you will not want dock sites to be visible on forms, since they will display as empty rectangles if no controls are docked.  To avoid this, the following techniques should be used:

•	Fill the entire form with a dock site and place a panel on the site.  The panel will represent the form’s client area and also hide the dock site.  End-users will still be allowed to dock other panels and containers on the site.  Please refer to the Creating a Visual Studio.NET like Interface topic for additional information.

•	Set a dock site’s AutoSize property to True.  This allows you to create extremely small dock sites that are automatically stretched as panels or containers are placed on them.  Please refer to the Using Dock Controls in MDI Applications topic for details.

Docking Manager

The docking manager component enables you to provide centralized control over all or  part of the dock controls.  Note that it is not necessary to use this component.  If it is not placed on any form within your application, the docking controller will manage dock controls.  However the docking controller doesn’t allow you to change the dock controls’ settings, it only provides the default values.  Thus, you will generally need docking manager components.

Please refer to the Docking Controller and Docking Managers topic for additional information on the docking manager and docking controller.  The topic explains when you should use the docking manager and when it is not required.  For detailed information on the features provided by the docking manager component, see the Docking Manager Features topic.


Customizing Dock Panels Appearance
Customizing Dock Panels’ Appearance

Quick Starts

This topic provides information on customizing the appearance of dock panels.  This includes information about specifying their painting style, captions and images, colors and fonts.

Painting Style

The ExpressDocking Library lets you use four predefined painting styles.  These are the standard (Delphi-like), Visual Studio .NET style, Office 11 style and Windows XP style.  To specify the desired style at design-time, you should use the docking manager’s ViewStyle and LookAndFeel properties.  Note: the LookAndFeel property’s settings are only used when the ViewStyle property is set to vsUseLookAndFeel.  In this case, the painting style of dock controls depends on settings provided by the TcxLookAndFeelController component (if present).  You can use this to provide a common look and feel for all Developer Express controls in your application.

The image below shows how to access the ViewStyle and LookAndFeel properties at design-time.

Please refer to the Paint Styles topic for additional information and samples of painting styles.

Colors and Fonts

The color of dock panels is specified by their Color property.  This color is applied to the panel’s client area and its child controls whose ParentColor property value is True.  Note: it is not used when the XP or Office11 painting style is applied.  A dock panel’s font is set using the Font property.  The font is applied to the dock panel’s caption (when a panel is docked to a form) and to controls residing on that panel whose ParentFont property value is True.

The image below shows how to change a dock panel’s font style.  Changes to Font settings are also applied to the panel’s child control since its ParentFont property value is True.

You can also provide a centralized control over the font and color settings of dock panels.  The docking manager component provides its own Font and Color properties for this purpose.  Note: settings supplied by the docking manager are only used by controls whose ManagerFont and ManagerColor properties are set to True.

Captions and Images

Captions and images are used to identify dock panels in your application.  They are displayed within the following elements:

•	Dock panels’ headers;

•	Tabs representing dock panels joined within a tab container;

•	Labels representing dock panels with the  auto hide feature enabled.

To specify a dock panel’s caption, use the Caption property.  The image is set using the ImageIndex property.  Note: an image list must be assigned to the docking manager’s Images property to provide the source of images displayed in dock panels.

The image below shows samples of images and captions.


Docking Operations Basics
Docking Operation Basics

Quick Starts

This topic covers the basics of the docking functionality available to end-users (i.e. the functionality available at design-time when customizing the dock controls’ layout).  This topic also describes the main properties affecting the docking behavior of panels, sites and containers.

Common features

Docking operations are performed by dragging panels and containers.  Dragging can be initiated in a dock control’s caption.  When dragging, a docking frame indicating the dock control’s bounds is painted.  The frame’s size and position are changed dynamically to reflect the control’s position if it were to be dropped.  Thus, the frame’s size changes when dragging a control over another dock control or a dock site.  If you only need to change the dock control’s position without actually docking it to the underlying dock control, hold the CTRL key pressed when dropping.  If you need to cancel the docking operation, press the ESC key.

The images below show a sample docking operation (the first image shows the dragging process and the frame shows the panel’s target position, while the second illustrates the result of the docking operation).

There are two docking operation types available.  First, you can dock a control to another control’s edge.  You can also dock a control so that it fills the target control’s entire area.  The dock control’s AllowDockClients property allows you to specify which operation types are allowed for each panel, container or site.  The image below shows these settings.  (Note that you can control the docking availability for each control’s edge.)

You can also control how panels and containers can be docked to other dock controls.  This is controlled by their AllowDock property, which provides similar settings.  See the image below.

You can stop a control from floating by setting the AllowFloating property False and force it to float by setting its Dockable property to False.

For additional information on controlling docking operations please refer to the following topics:

•	Dock Controls Hierarchy

Provides links to documents describing each dock control type in detail, including the docking operations required to create a control.

•	TdxDockingManager.Options

Describes options that affect docking behavior.

•	Controlling Docking Operations

Provides common information about controlling docking operations by handling specially designed events.

•	Zones Overview and Dock Zones

Describes the dock zones technology introduced by the ExpressDocking Library.  This technology gives you unlimited control over docking operations.


Creating a Visual Studio .NET like Interface

Quick Starts

This topic will guide you through creating an application with docking functionality similar to Microsoft’s Visual Studio .NET IDE.  The resulting application will display a memo editor and a number of dock panels that can be docked to form’s edges, combined into tab containers and side containers.

Follow the steps below:

•	Create a new application.

•	Place a TdxDockSite control on the form and set the control’s Align property to alClient.  The dock site will always occupy the form’s entire area.

•	Place a TdxDockPanel control on the form so that it fills the dock site’s entire area.  Set the dock panel’s ShowCaption property to False to hide the panel’s caption.  The panel created will represent the form’s client area.

•	Place a memo control on the panel and set the memo control’s Align property to alClient.  The memo editor will occupy the entire panel (and thus the entire form).

•	Select the dock panel using the Object TreeView window.  Set all the values of the AllowDockClients property to False.  This will prevent other dock panels from being docked to the panel and panels will only be allowed to be docked to the underlying site.  This prevents side containers and tab containers from being created which would include the panel representing the form’s client area.

•	Select the dock site using the Object TreeView window.  Set the dtTop flag of the AllowDockClients property to False.  This will prevent panels being docked to the form’s top edge.

•	All the preparatory steps are now complete.  You are now able to add dock panels to represent tool windows and fill them with the controls desired.  These panels will be allowed to float, to be docked to the form’s edges (except the top edge) and to be joined into containers.  Note: when a panel or a container is docked to a form’s edge, you can enable its auto hide feature.  This can be done by pressing the auto hide button (highlighted in the image below).

The image below displays an arrangement of dock panels.  The auto hide feature is enabled for the panel that is docked to the left edge.  The panels at the bottom edge are joined into a side container.  The panels at the right are in a tab container.  A floating panel is also illustrated.

•	There is one more thing to do in this topic.  To make the application look more like the Visual Studio IDE, place the docking manager on the form and set its ViewStyle property to vsNET.  The image below shows the result.


Using Dock Controls in MDI Applications

Quick Starts

The approach described in the Creating a Visual Studio .NET like Interface is not appropriate for MDI applications.  This is because MDI child windows will not be visible if a dock site fills the form’s entire client area.  Thus, you need to use the dock sites’ auto size feature to use dock windows in your MDI applications.  This topic shows a simple example of creating such an application.

Follow the steps below:

•	Select the main menu’s File | New | Other… item.  Switch to the Projects tab and select the MDI Application item.  Click the OK button to create a new MDI application.

•	Place a TdxDockSite control on the form.  Set the control’s Align property to alLeft.

•	Set the dock site’s AutoSize property to True.  This forces the dock site to stretch automatically when docking panels or containers on it.

•	Set the site’s Width property to 0.  This will hide the dock site.  Note, however, that panels and containers can still be docked to the site.  This is because the docking area doesn’t depend on the site’s size.  Instead, it is controlled by the site’s dock zones.  Please refer to the Zones Overview and Dock Zones topics for additional information.

•	All preparation is now complete.  You can add dock panels to the application.  The panels and containers constructed can be docked to the form’s left edge (where the hidden dock site resides).  You can add additional dock sites to the form’s edges to allow docking to other edges.

The image below shows an example of a running MDI application.  A panel is docked to the dock site residing at the form’s left edge.

Note: the approach described in this topic is not restricted to MDI applications, of course.  You can also use it when developing non-MDI applications.  However, using a single dock site occupying the entire form’s area provides more flexibility for dock control arrangements.  Please refer to the Layout Sites topic for additional information.


Understanding the Dock Control Internal Layout
Understanding the Dock Controls Internal Layout

Quick Starts

This topic explains the basic principles of dock control arrangement.  It provides a set of rules that will help you to understand how and when dock controls are automatically created and destroyed as the result of docking operations.

Site Related Rules

•	Dock panels (and containers) can only reside on sites.  The ExpressDocking Library provides three site types: dock sites, layout sites and float sites.  Dock sites are controls that you place on forms to allow docking panels and containers to them.  Layout sites are created on dock sites as the result of docking operations and they allow flexible dock control layout customization.  Finally, float sites are used to accommodate dock controls on floating forms.

•	Float sites are created automatically when a dock control is made to float.  They are automatically destroyed when docking a control on a dock site or layout site.

•	Layout sites are created automatically when docking a panel or container on a dock site.  They fill the area not occupied by docked controls.  Note: controls can also be docked to layout sites and this results in creating a layout site that fills the area not occupied by the control just docked.

The points above can be illustrated by using the Object TreeView window.  Consider the following dock control layout customization steps:

The form contains a dock site.  Two dock panels are floating (reside on float sites).

The first panel is now docked to the dock site.  This destroys the panel’s underlying float site, places the panel on the dock site and creates a neighboring layout site.

The second panel is docked to the layout site.  This destroys the panel’s underlying float site, places the panel on the layout site and creates a neighboring layout site.  Now the second panel and its neighboring layout site belong to the first layout site.

Container Related Rules

•	Docking a panel to the left, right, top or bottom edge of another panel creates a side container.  The container created becomes the parent of the two panels.  Its position within the object tree is determined by the target panel’s position.

•	Docking a panel to the center of another panel creates a tab container.  The container created becomes the parent of the two panels.  Its position within the object tree is the target panel’s position.

•	Dragging a panel away from a container destroys the container (if only a single panel is left within it).

•	Docking a panel to an existing container adds the panel to the container’s child list.

The following sample steps illustrate some of the rules above.

First, there are three individual dock panels (each residing on its own float site).

The second panel is docked to the first panel to form a tab container.  The first panel’s underlying float site has been destroyed as a result.  The tab container’s position within the object tree is the previous position of the target panel.

The third panel is docked to the tab container to create a vertical side container.  The third panel’s underlying float site is destroyed as a result.  The side container’s position within the object tree is the previous position of the tab container (the target of the docking operation).


Docking Panels to Sites at Runtime

Quick Starts

This topic provides examples of docking panels to sites and making them float.

You can perform docking operations via code using the DockTo, MakeFloating and UnDock methods of panels and containers.  The UnDock method clears a control’s parent and it is recommended that you undock controls before docking them elsewhere.  Otherwise, a sequence of actions may result in different layouts depending on the initial layout.  The MakeFloating and DockTo methods are used to perform the docking operations.

Consider a simple example of using the DockTo method.  (The sample assumes that there are three existing dock panels, named dxDockPanel1, dxDockPanel2 and dxDockPanel3 by default).

// Delphi

dxDockPanel1.DockTo(dxDockSite1, dtLeft, 0);

dxDockPanel2.DockTo(dxDockSite1, dtBottom, 0);

dxDockPanel3.DockTo(dxDockSite1, dtRight, 0);

The resulting panel layout is shown in the image below.

Note: you may need to modify the layout of the dock panels slightly.  For instance, you may need the bottom panel (dxDockPanel2) to occupy the entire form’s width.  To do this, you have two alternatives.  The first is to dock the bottom panel last.  In this case, the other panels will be moved to the neighboring layout site.  The second approach is to dock the right panel to the bottom panel’s neighboring layout site instead of the dock site.  The code below shows the second method.  Note that the first two code lines are unchanged.

// Delphi

dxDockPanel1.DockTo(dxDockSite1, dtLeft, 0);

dxDockPanel2.DockTo(dxDockSite1, dtBottom, 0);

dxDockPanel3.DockTo(dxDockPanel2.LayoutDockSite, dtRight, 0);

The resulting dock panel layout is shown in the image below.

The main conclusion at this point is that you need to be aware of the current dock panel layout on a dock site before trying to modify it.  Thus, the best way is to undock all the panels before customizing the layout.  A further approach is to store the desired layouts and load them when needed.  This can be done using the docking manager’s SaveLayoutToIniFile, SaveLayoutToRegistry, SaveLayoutToStream, LoadLayoutFromIniFile, LoadLayoutFromRegistry, LoadLayoutFromStream methods.

The sample code below shows how to make all panels float.  (Note: virtually the same code can be used to undock all the panels, by calling the UnDock method instead of MakeFloating.)

// Delphi

var I: Integer;

begin

  with dxDockingController do

  begin

    for I := 0 to DockControlCount - 1 do

    begin

      if DockControls[I] is TdxDockPanel then

        DockControls[I].MakeFloating;

    end;

  end;

end;


Creating and Managing Container Controls at Runtime

Quick Starts

This topic provides examples of creating container controls, specifying their active child controls and moving child controls within the owning container.

You should use the following main methods and properties when managing container controls:

•	A dock control’s DockTo method – can be used to create a container.  Note: the docking target should be a dock panel or container.  This method can also be used to undock a panel from a container, which may result in the container’s destruction.  Finally, this method can be used to move a control within the owning container.

•	A dock control’s MakeFloating method – can be used to undock a control from a container.  Note: this may lead to container destruction.

•	A container’s ActiveChildIndex property – used to specify the container’s active child.  This is the active tab in tab containers and the expanded child in side containers.

•	A dock control’s DockIndex property – determines the control’s index within the container.  This property value can be assigned to the container’s ActiveChildIndex to activate the control within the container.

•	A container’s Children, ChildCount, ValidChildren and ValidChildCount properties – can be used to access a container control’s children.

•	A dock control’s ParentDockControl, TabContainer, SideContainer properties – allow access to the parent dock control.

The sample code below assumes that there are five dock panels in the application.  The code creates a tab container that includes three panels and a vertical side container containing the other two panels.

// Delphi

var

  ATabContainer: TdxTabContainerDockSite;

  ASideContainer: TdxSideContainerDockSite;

begin

  // create a side container by docking the second panel

  // to the center of the first one

  dxDockPanel2.DockTo(dxDockPanel1, dtClient, 1);

  // obtaining the tab container created

  ATabContainer := dxDockPanel1.TabContainer;

  if ATabContainer = nil then Exit;

  // adding the third panel to the tab container

  dxDockPanel3.DockTo(ATabContainer, dtClient, 2);

  // switching to the first panel (tab)

  ATabContainer.ActiveChildIndex := dxDockPanel1.DockIndex;

  // create a vertical side container

  dxDockPanel4.DockTo(dxDockPanel5, dtTop, 0);

  // obtain the side container created

  ASideContainer := dxDockPanel4.SideContainer;

  if ASideContainer = nil then Exit;

  // expand the top panel within the side container

  ASideContainer.ActiveChildIndex := dxDockPanel4.DockIndex;

  // dock the side container to a site's right edge

  ASideContainer.DockTo(dxDockSite1, dtRight, 0);

  // dock the tab container to a site's bottom edge

  ATabContainer.DockTo(dxDockSite1, dtBottom, 0);

end;

The image below shows the sample code execution’s result.

The following code customizes the layout created.

// Delphi

var

  ATabContainer: TdxTabContainerDockSite;

  ASideContainer: TdxSideContainerDockSite;

begin

  // obtain the tab container

  ATabContainer := dxDockPanel1.TabContainer;

  if ATabContainer = nil then Exit;

  // create a horizontal side container comprised of the

  // tab container and the third panel

  dxDockPanel3.DockTo(ATabContainer, dtRight, 1);

  // change the first panel's position within the tab container

  dxDockPanel1.DockTo(ATabContainer, dtClient, 1);

  // obtain the side container

  ASideContainer := dxDockPanel4.SideContainer;

  if ASideContainer = nil then Exit;

  // cancel the top panel's expansion

  ASideContainer.ActiveChildIndex := -1;

end;

The image below shows the result.


Creating, Destroying, Showing and Hiding Dock Controls

Quick Starts

This topic provides simple examples of creating, destroying dock controls and changes to their visibility.  Note: manual creation and destruction of dock controls is generally needed for dock panels representing documents.  Dock panels representing tool windows are likely to be created at design-time and not destroyed during the application’s execution.  For tool windows, you will generally change the visible state.

Summary

A dock control’s visibility is specified by its Visible property.  Set the property to False to hide the control.  Note: a control can also be hidden by calling its Close method.  Bear in mind though, that this method only hides the control if the docking manager’s doFreeOnClose option is disabled.  Otherwise, the Close method destroys the control.  Another way to hide a control is to undock it using the UnDock method.  In this case, the control has no parent, and thus the control is not displayed.  Finally, you can destroy a dock control directly by calling its Free method.

Note #1: you will not have to create and destroy container controls.  They are created and destroyed automatically as the result of docking operations.

Note #2: if a control is hidden, it still takes part in layout customization since its parent dock control is preserved.  For instance, if a control located within a tab container is hidden and then displayed again, it will appear in the same tab container as before.

Note #3: if the auto hide feature is enabled for a control and the control is not visible on the screen, setting the control’s Visible property to False does nothing.  You have two alternative ways of hiding a dock control in this case.  First, you can make the control visible on the screen and then set the control’s Visible property to False.  Another method is to disable the auto hide feature for the control before attempting to hide it.

You can respond to changes to a dock control’s visibility by handling the VisibleChanged and VisibleChanging events.  You can also respond to closing a control by using the OnClose event.  Finally, you can restrict end-users from closing a dock control by handling the OnCloseQuery event.

Showing and Hiding Dock Controls

This section provides a simple code sample showing how to show and hide dock controls.  The code below represents a button’s OnClick event handler.  The code toggles a dock panel’s visible state.  Note: it even handles the case when the panel’s auto hide feature is enabled and the panel’s client area is not currently visible.

// Delphi

procedure TForm1. Button1Click(Sender: TObject);

begin

  if dxDockPanel1.AutoHide and not dxDockPanel1.Visible then

  begin

    dxDockingController.BeginUpdate;

    try

      // make the panel's client area visible on screen

      dxDockPanel1.Visible := True;

      // hide the panel

      dxDockPanel1.Visible := False;

    finally

      dxDockingController.EndUpdate;

    end;

  end

  else

    dxDockPanel1.Visible := not dxDockPanel1.Visible;

end;

Creating and Destroying Dock Controls

This section shows how to create an application that enables you to display images on separate dock panels.  An image can be loaded by pressing the INSERT key.  Once an image has been loaded, it is placed on a dynamically created dock panel docked to the site.  Pressing the DELETE key destroys all panels.

To create the sample application, follow the steps below:

•	Create a new application.

•	Place a TdxDockingManager component on the form.

•	Place a TOpenDialog component on the form.

•	Place a TdxDockSite control on the form and set its Align property to alClient.

•	Write the following handler for the form’s OnCreate event.

procedure TForm1.FormCreate(Sender: TObject);

begin

  // specify the open dialog’s filter

  OpenDialog1.Filter := '*.bmp|*.bmp';

  with dxDockingManager1 do

  begin

    // force dock controls to be destroyed when closed

    Options := dxDockingManager1.Options + [doFreeOnClose];

    // specify the default tabs position and

    // the dock controls paint style

    DefaultTabContainerSiteProperties.TabsPosition := tctpTop;

    ViewStyle := vsNET;

  end;

end;

Write the following handler for the form’s OnKeyDown event.

procedure TForm1.FormKeyDown(Sender: TObject; var Key: Word;

  Shift: TShiftState);

var

  APicture: TPicture;

  APanel: TdxDockPanel;

  AImage: TImage;

  ALastIndex, I: Integer;

begin

  if Key = VK_INSERT then

  begin

    // open the file and create the corresponding image object

    if not OpenDialog1.Execute() then Exit;

    APicture := TPicture.Create();

    APicture.LoadFromFile(OpenDialog1.FileName);

    // create a new panel that will hold the image

    APanel := TdxDockPanel.Create(Self);

    APanel.Caption := ExtractFileName(OpenDialog1.FileName);

    // check whether the dock site already has docked controls

    if dxDockSite1.ChildCount > 0 then

    begin

      // add the panel to the tab container

      ALastIndex := dxDockSite1.Children[1].ChildCount;

      APanel.DockTo(dxDockSite1.Children[1], dtClient, ALastIndex + 1);

    end

    else

      // dock the panel to the dock site

      APanel.DockTo(dxDockSite1, dtClient, 0);

    // create an image control and place it on the panel

    AImage := TImage.Create(Self);

    AImage.Parent := APanel;

    AImage.Align := alClient;

    AImage.Center := True;

    AImage.Picture := APicture;

  end;

  // delete all panels if the DELETE key has been pressed

  if Key = VK_DELETE then

  begin

    for I := 0 to dxDockingController.DockControlCount - 1 do

    begin

      if dxDockingController.DockControls[I] is TdxDockPanel then

        dxDockingController.DockControls[I].Close;

    end;

  end;

end;

The image below shows the appearance of this sample application.


Quick Starts

Basics

Adding Components and Controls

Customizing Dock Panels Appearance

Docking Operations Basics

Building User Interfaces

Creating a Visual Studio .NET like Interface

Using Dock Controls in MDI Applications

Managing Dock Controls at Runtime

Understanding the Dock Control Internal Layout

Docking Panels to Sites at Runtime

Creating and Managing Container Sites at Runtime

Creating, Destroying, Showing and Hiding Dock Controls