Sign in Join
Wiki copytemporary

Anchor Docking

English · Русский · 中文（中国）

About docking in general see Docking.

Overview

Docking allows you to combine forms, or to treat controls as forms. You use the mouse to drag and dock forms together or undock (split) them. The basic dragging, docking and undocking functionality is provided by the LCL. But you need a docking manager to add splitters and grab zones, and to save and restore layouts.

Anchor docking has been implemented since version 0.9.29 in the package anchordocking.lpk for use in your own Lazarus applications, and AnchorDockingDsgn.lpk if you wish to make the Lazarus IDE windows dockable. It is easy to use, and provides many features and options not available in earlier docking packages.

You will find a code example at: components/anchordocking/miniide/miniide1.lpi

This means that the earlier TLazDockingManager and unit LDockCtrl are obsolete and now deprecated.

Features

ToDos

Usage I. (Add docking support to the Lazarus IDE)

If you don't like the default "separate windows" look of the Lazarus IDE and prefer a single window (e.g., like RAD Studio™), you can install a package called AnchorDockingDsgn (lazarus/components/anchordocking/design/anchordockingdsgn.lpk). This package makes the IDE windows dockable.

Important to macOS users

Before Lazarus 3.0, there are many bugs related to docking.

If "anchordockingdsgn" has been installed before Lazarus 3.0, the wrong configuration may be saved and needs to be reset first.

The configuration is saved in environmentoptions.xml, which usually located in ~/.lazarus

Close the IDE, locate environmentoptions.xml, delete the content between <AnchorDocking> and </AnchorDocking>, and the initial setting of anchordockingdsgn will be automatically set when the IDE is started again.

Installation

Uninstall any other docking managers (e.g., easydockmgrdsgn). From the Lazarus menu bar pick "Package" - "Install/Uninstall Packages" and install the "anchordockingdsgn" package.

After you have successfully installed the package and restarted the IDE, the IDE starts with a default docked layout like shown below. Note that AnchorDocking headers and splitters have been added to all dockable windows of the IDE. In case the headers don't get visible, see the section "Options" below on how to enable/disable them.

You can change the layout by grabbing a dockable window by the Anchordocking header and drag and dock it anywhere else, or resize docked windows via splitters added to the window borders. You can right-click on the headers too for other options, for example, to change the look of the headers, as shown farther down below.

You can save the layout via the menu item Tools / Save window layout as default. This saves to ~/.lazarus/anchordocklayout.xml and restores it when the IDE starts up.

You can also save the layout to a file and load them later.

Since Lazarus 1.1 you can pass a command line parameter

text
./lazarus --anchordocklayout=<filename>

The look (like the headers) can be further tweaked by right-clicking on them.

Options

After the successful installation of the AnchorDockingDsgn package, an additional configuration menu is added to the Lazarus options dialog ("Tools" - "Options" - "Environment")

Scale on resize

When resizing a window, all docked forms inside are scaled by the same percentage.

Show headers

To dock/undock a window, you need to enable this option.

Flatten headers

No 3d frame in headers.

Header align top/left

Headers are automatically put at top or left depending on these two values:

Which means the header is by default put at the smaller side of a docked control. When the control is resized, the header switches to the smaller side.

Allow dock sites to be minimized

A extra minimize button is added, so a site can be minimized. Then sites next to it get more space. If needed, the minimized site then can easy be opened.

Multine Tabs

Feature added in Lazarus 2.2. If a OS support multiline tabs (like Windows), if there are no many tabs, they are shown in multiple lines.

Floating windows on top

Feature added in Lazarus 2.2. If there are undocked windows shown, show these on top of main window. In a own application, there can be set DockMaster.MainDockForm, then all floating windows are shown on top of it. If MainDockForm is not set, Application.MainForm is used.

Usage II. (Add docking support to your own applications)

Quick start

Add the package AnchorDocking to the required packages in the project inspector.

Then add the unit AnchorDocking to the uses section of your main unit (the unit with your main form).

Add to the FormCreate of your main form:

pascal
  DockMaster.MakeDockSite(Self,[akBottom],admrpChild);

For the other dockable forms replace all calls of Show and ShowOnTop with

pascal
  DockMaster.MakeDockable(Form1,true,true);

For the other dockable forms replace all calls of Visible:=true with

pascal
  DockMaster.MakeDockable(Form1,true);

Remove or comment all Hide, Visible:=false, WindowState:= calls.

Prerequisites

Making forms dockable

There are two ways to make a form dockable. You can use DockMaster.MakeDockable to wrap a form into a dock site. Then your form can dock and be docked completely free. You will use that for the biggest part of your forms, except for the MainForm, because this is only supported for the MainForm on gtk2 and qt. The second way is to use DockMaster.MakeDockSite. The form can dock other sites, but can not be docked itself. You might want to use MakeDockSite for the MainForm. For most other forms you probably want to use this:

pascal
// shows YourForm
// if not already done, wrap the form into a dock site
DockMaster.MakeDockable(YourForm);

Here are some examples how a form looks like that was made dockable with DockMaster.MakeDockable:

The header position is normally done automatically and the user can with a right click put it to any of the four sides.

Example: miniide1

The example can be found in lazarus/components/anchordocking/miniide/miniide1.lpi. It has a mainform in unit unit1.pas with a main menu which works as a docksite and several forms that are dockable.

Making the main form a dock site

In the TMainIDE.FormCreate the main form MainIDE is turned into a docksite:

pascal
DockMaster.MakeDockSite(Self,[akBottom],admrpChild);

The parameter [akBottom] allows to dock other sites at the bottom of MainIDE. The parameter admrpChild tells the DockMaster that when the MainIDE is enlarged the extra space is distributed to the docked sites.

When the user docks a site to the bottom of MainIDE the site is put onto MainIDE (Site.Parent:=MainIDE) with Site.Align=alBottom. The other controls on MainIDE must be compatible to this. MainIDE for example has a BtnPanel with Align=alLeft and a TNoteBook with Align=alClient. See here how Align works.

The DockMaster adds automatically a splitter:

As soon as a dockable form is docked its caption is shown in the dock header.

Requirements for a custom dock site

As long as nothing is docked into a custom dock site, your form can do everything as a normal form. But when a site is docked to it, some properties and methods need special care:

Procedure to create all other forms by name

The MainIDE sets the DockMaster.OnCreateControl event, to enable the DockMaster to create forms by name. This is needed to restore layouts.

pascal
DockMaster.OnCreateControl:=@DockMasterCreateControl;
pascal
procedure TMainIDE.DockMasterCreateControl(Sender: TObject; aName: string; var
  AControl: TControl; DoDisableAutoSizing: boolean);

  procedure CreateForm(Caption: string; NewBounds: TRect);
  begin
    AControl:=CreateSimpleForm(aName,Caption,NewBounds,DoDisableAutoSizing);
  end;

begin
  // first check if the form already exists
  // the LCL Screen has a list of all existing forms.
  // Note: Remember that the LCL allows as form names only standard
  // pascal identifiers and compares them case insensitive
  AControl:=Screen.FindForm(aName);
  if AControl<>nil then begin
    // if it already exists, just disable autosizing if requested
    if DoDisableAutoSizing then
      AControl.DisableAutoSizing;
    exit;
  end;
  // if the form does not yet exist, create it
  if aName='CodeExplorer' then
    CreateForm('Code Explorer',Bounds(700,230,100,250))
  ...
  else if aName='DebugOutput' then
    CreateForm('Debug Output',Bounds(400,400,350,150));
end;

Creating a form can be as simple as this:

pascal
MyForm:=TMyForm.Create(Self);
if DoDisableAutoSizing then
  MyForm.DisableAutoSizing;

But of course you can put there all kind of initialization code.

The DisableAutoSizing reduces flickering. Make sure your forms Visible property is set to false.

Remember to call DisableAutoSizing for the form if the parameter DoDisableAutoSizing is set to true, because Disable- and EnableAutosizing calls must be balanced. If you miss the DisableAutosizing, the LCL will raise an exception later:

text
TControl.EnableAutoSizing SourceEditor1:TSimpleForm: missing DisableAutoSizing

If you call DisableAutoSizing too much, your forms will not appear and/or not resize properly as the LCL is waiting for the EnableAutoSizing call that never comes.

Showing forms

When a form should be shown, you have probably used something like 'MyForm.Show. Instead you should now use

pascal
DockMaster.MakeDockable(MyForm);

This will wrap MyForm in a dock site and show it. It is clever enough to figure out if the form is already wrapped in a dock site.

If you set the DockMaster.OnCreateControl event you can use this:

pascal
DockMaster.ShowControl('MyForm',true);

Docking manually, via code

Use the procedure DockMaster.ManualDock to dock a site to or into another.

pascal
procedure ManualDock(SrcSite, TargetSite: TAnchorDockHostSite; Align: TAlign; TargetControl: TControl = nil);

Undocking manually, via code

Use the procedure DockMaster.ManualFloat to undock a site from its neighbors and create a flotaing top level form. The embedded control stays embedded into a TAnchorDockHostSite.

pascal
procedure ManualFloat(AControl: TControl);

You can give as parameter a TAnchorDockHostSite or a control embedded into a TAnchorDockHostSite (for example a form made dockable with MakeDockable). The site will be put at the same screen location.

Save layout

The DockMaster allows to save the current layout to a TConfigStorage. The miniide example uses the xml version:

pascal
procedure TMainIDE.SaveLayout(Filename: string);
var
  XMLConfig: TXMLConfigStorage;
begin
  try
    // create a new xml config file
    XMLConfig:=TXMLConfigStorage.Create(Filename,false);
    try
      // save the current layout of all forms
      DockMaster.SaveLayoutToConfig(XMLConfig);
      XMLConfig.WriteToDisk;
    finally
      XMLConfig.Free;
    end;
  except
    on E: Exception do begin
      MessageDlg('Error',
        'Error saving layout to file '+Filename+':'#13+E.Message,mtError,
        [mbCancel],0);
    end;
  end;
end;

Load layout

pascal
procedure TMainIDE.LoadLayout(Filename: string);
var
  XMLConfig: TXMLConfigStorage;
begin
  try
    // load the xml config file
    XMLConfig:=TXMLConfigStorage.Create(Filename,True);
    try
      // restore the layout
      // this will close unneeded forms and call OnCreateControl for all needed
      DockMaster.LoadLayoutFromConfig(XMLConfig);
    finally
      XMLConfig.Free;
    end;
  except
    on E: Exception do begin
      MessageDlg('Error',
        'Error loading layout from file '+Filename+':'#13+E.Message,mtError,
        [mbCancel],0);
    end;
  end;
end;

Enlarge/Shrink

The anchor docking manager can enlarge/shrink docked neighbors. This is done via the popup menu of the dock header or in code with the function DockMaster.ManualEnlarge:

pascal
function ManualEnlarge(Site: TAnchorDockHostSite; Side: TAnchorKind; OnlyCheckIfPossible: boolean): boolean;

Site is a child site, Side the side of Site to expand. If you only want to test if enlarge is possible set OnlyCheckIfPossible to true.

Enlarge one, shrink another

Shrink neighbor Object Inspector, enlarge Messages: Right click on the header of Messages and click on Enlarge right side. Two splitters are resized.

enlarging Messages to the right side:

Enlarge one, shrink many

Shrink splitter at one side, enlarge both neighbor splitters, rotate the splitter behind, enlarge Control, shrink controls at rotate splitter. Right click on header of Source Editor 1 then click on Enlarge bottom side.

becomes

General docking options

The AnchorDocking package provides a dialog to setup some of the properties of the DockMaster. The dialog is in the unit AnchorDockOptionsDlg and you can use it simply:

pascal
uses ... AnchorDockOptionsDlg;
...
procedure TMainIDE.FormCreate(Sender: TObject);
...
begin
  ...
  DockMaster.OnShowOptions:=@ShowAnchorDockOptions;
  ...
end;

This will add a new menu item to the popup menus of the dock headers and pages called Docking options.

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:

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:

This requires only one hidden panel.

Changing Layouts

Now the user wants to enlarge the FPDocEditor horizontally (and shrink CodeExplorer). With the AnchorDocking you can simply right click on the FPDocEditor header and click Enlarge right side.

Other docking engines need at least 2 panels. One for SrcEditor,Messages,FPDocEdit,CodeExpl and one for SrcEdit and Messages. Most docking layouters do not even provide a simple way to change the layout in this way. 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 SourceEditor1 horizontally (and shrink ObjectInspector):

This layout is impossible with Align and panels, because you can not cut it in two halves. The same with

Conclusion

Align with hidden panels allows you to easily create a simple docking manager that works well 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.

Old/deprecated anchor docking

Create a TLazDockingManager

pascal
  DockingManager:=TLazDockingManager.Create(Self);

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.

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

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

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

Optional: Saving the user configuration to disk

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

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

See also

From the Free Pascal wiki, page "Anchor Docking", as it stood on 2024-01-27 after a change by Rich2014, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's Licensing page. If you have concerns about this material, message the admin.

Revision 5, last changed by WikiArchive .

Talk about this page

Nobody has opened a bench for this page yet. Sign in to open one.