Dock Zones
- 5 minutes to read
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.
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;