Anchor Docking

About docking in general see Docking.

Overview

Anchor docking was implemented in the package examples/anchordocking/anchordocking.lpk (Since 0.9.29).

An example can be found in examples/anchordocking/miniide/miniide1.lpi

Obsolete: The old TLazDockingManager and unit LDockCtrl are deprecated. A step by step example

Features

• Drag and dock: Headers are added that can be dragged to dock controls with the mouse. Preview rectangles will show where and how a control is docked.
• Any layout: By using the LCL's anchors almost any layout is possible. You can dock to left, right, top, bottom, inside or outside or as page like in a TPageControl. You can enlarge docked controls via the popup menu. No need to undock your whole layout.
• What you see is how it is structured: There are no hidden panels to align controls in rows and columns. Anchor docking makes sure forms do not overlap and that you can .
• Splitters are automatically inserted between docked forms to allow resizing.
• Page docking. Forms can be docked not only left/right/above/below, but in pages too. A TPageControl is automatically created for native look and feel. A page can contain arbitrary docked forms too, including paged docked forms, allowing nested pages and layouts. When a page is undocked the pagecontrol is automatically removed. You can drag and drop the tabs or use the popup menu to move pages.
• Easy use: With one line of code you can make a form or control dockable. Just give them a unique name.
• Not only forms, but any TWinControl can be made dockable.
• Can save/load layouts from/to xml config files. The layout information is stored for each dockable control and if the application gets more or less dockable controls the old layout files will still work.
• Each docked form is put into a docksite providing a header. The header shows the caption of the docked form and contains a close button. You can drag the header to drag the form and undock it or to dock it at another position.
• The header can be at any of the four site and moves by default automatically to the smaller site to safe space. You can customize this.
• The header shows a customizable hint to read long captions.
• When a docksite is resized the child sites are scaled. You can turn this off.
• Preserve size of forms. For instance when docking a form to a left side of a site the width of the docked form is kept. The same for the other sides and the same for undocking.
• Flickerless: The restore tries to reuse existing sites and splitters to reduce creation and flickering of forms and to preserve the Z order of forms. This allows to quickly switch between layouts.
• Header popup menu:
  • lock/unlock (disable dragging)
  • header position (auto, left, top, right, bottom), this is saved/restored with the layout
  • merge (for example after moving a dock page into a layout)
  • undock (needed if no place to undock on screen)
  • enlarge side to left, top, right, bottom
  • tab position for pagecontrol (top,bottom, left, right), this is saved/restored with the layout
  • close
• Forms can be made dock sites. Then they can dock at one side. But they can not be docked itself.

ToDos

• Write examples and docs
• Write a design time package for the IDE
• Easy docking via code
• popup menu
  • shrink side left, top, right, bottom
  • options
• simple way to make forms dockable at designtime
• minimize button and Hide
• close button: save a default layout
• on show again: restore a default layout
• close button for pages
• Implement automatic menu merging in the LCL (when two forms with main menus are docked).

Usage

Create a TLazDockingManager

<DELPHI>

 DockingManager:=TLazDockingManager.Create(Self);

</DELPHI> The Self as parameter is only used as Owner. That means, when the mainform is freed, the DockingManager is freed too. You can use nil and free the DockingManager yourself.

Optional: Loading a configuration

You can load the user configuration from disk. <DELPHI>

 Config:=TXMLConfigStorage.Create('config.xml',true);
 DockingManager.LoadFromConfig(Config);
 Config.Free;

</DELPHI> This loads the file config.xml. The config can be created by the SaveToConfig function. See below.

Make a form/control dockable

Create a TLazControlDocker for each form/control that should be dockable <DELPHI>

 ControlDocker1:=TLazControlDocker.Create(Self);
 ControlDocker1.Name:='DockerForm1';
 ControlDocker1.Manager:=DockingManager;

</DELPHI>

Optional: Saving the user configuration to disk

When the program is closed you can save the user configuration to disk <DELPHI>

 Config:=TXMLConfigStorage.Create('config.xml',true);
 DockingManager.SaveToConfig(Config);
 Config.WriteToDisk;
 Config.Free;

</DELPHI>

Enlarge/Shrink

The anchor docking manager can enlarge/shrink docked neighbors. This is done via the function TAnchoredDockManager.EnlargeControl.

Enlarge one, shrink another

Shrink one neighbor control, enlarge Control. Two splitters are resized.

     |#|         |#         |#|         |#
     |#| Control |#         |#|         |#
   --+#+---------+#   --> --+#| Control |#
   ===============#       ===#|         |#
   --------------+#       --+#|         |#
       A         |#        A|#|         |#
   --------------+#       --+#+---------+#
   ==================     ===================

Enlarge one, shrink many

Move one neighbor splitter, enlarge Control, resize one splitter, rotate the other splitter.

     |#|         |#|          |#|         |#|
     |#| Control |#|          |#|         |#|
   --+#+---------+#+--  --> --+#| Control |#+--
   ===================      ===#|         |#===
   --------+#+--------      --+#|         |#+--
           |#|   B            |#|         |#|B
           |#+--------        |#|         |#+--
       A   |#=========       A|#|         |#===
           |#+--------        |#|         |#+--
           |#|   C            |#|         |#|C
   --------+#+--------      --+#+---------+#+--
   ===================      ===================

Why use Anchors instead of Align?

Anchors allow to create any possible rectangular layout. Align is limited. Align with Panels can theoretically create a lot of layouts, but still not all. And some operations like enlarge/shrink are more complicated using Align/Panels than using Anchors. Align works good for a few forms, but the more forms are docked, the more the disadvantages of Align become visible.

Layouts that can be created with Align

Align can only create the following layouts:

 +------------------------------------------+
 |      alTop                               |
 +------------------------------------------+
 +------------------------------------------+
 |      alTop                               |
 +------------------------------------------+
 +------++------++--------++-------++-------+
 |alLeft||alLeft||alClient||alRight||alRight|
 +------++------++--------++-------++-------+
 +------------------------------------------+
 |      alBottom                            |
 +------------------------------------------+
 +------------------------------------------+
 |      alBottom                            |
 +------------------------------------------+

The alTop controls are always at the top, filling the whole horizontal width. That's because the LCL first aligns all controls with alTop, then all alBottom, then alLeft, then alRight and finally alClient.

Layouts that can be created with Align and Panels

It is possible to nest Align layouts by using hidden panels. Then any layout that can be recursively splitted in halves can be created. Then you can create for example:

 +--++-------++---+
 |  ||   B   ||   |
 |  |+-------+|   |
 |A |+-------+| E |
 |  ||   C   ||   |
 |  |+-------+|   |
 |  |+-------+|   |
 |  ||   D   ||   |
 +--++-------++---+

This requires only one hidden panel.

Changing Layouts

Now the user wants to enlarge D horizontally (and shrink E):

 +--++-------++---+
 |  ||   B   ||   |
 |  |+-------+|   |
 |A |+-------+| E |
 |  ||   C   ||   |
 |  |+-------++---+
 |  |+------------+
 |  ||   D        |
 +--++------------+

Now you need 3 panels. One for B,C,D,E, one for B,C,E and one for B,C. An algorithm to allow this layout change, must analyze the whole structure, as if there were no panels and must reparent a lot of things. Basically the algorithm must do the same as the anchor docking algorithm, but with the extra work of translating the layout into Align plus hidden panels.

Layouts that are impossible with Align and Panels

Now the user wants to enlarge B horizontally (and shrink A):

 +-----------++---+
 |    B      ||   |
 +-----------+|   |
 +--++-------+| E |
 |A ||   C   ||   |
 |  |+-------++---+
 |  |+------------+
 |  ||   D        |
 +--++------------+

This layout is impossible with Align and panels. The same with

  +-----------++--------------+
  |    A      ||              |
  +-----------+|      B       |
  +-----++----+|              |
  |     ||    |+--------------+
  |     || D  |+----++--------+
  |  C  ||    ||  E ||        |
  |     |+----++----+|   F    |
  |     |+----------+|        |
  |     ||    G     ||        |
  +-----++----------++--------+

Conclusion

Align with hidden panels allows to easily create a simple docking manager that works good for a few forms. But it will always limit the user. Align is useful for row and column layouts, not for tables. Anchor docking works even for complex forms.