Anchor Docking: what changed
Revision 5 to 6. Removed lines have a minus sign; added lines have a plus sign.
| Old | New | Line | |
|---|---|---|---|
| 1 | - | ||
| 1 | + | About docking in general see [[Docking]]. | |
| 2 | 2 | ||
| 3 | 3 | ## Overview | |
| 4 | 4 | ||
| 5 | - | ||
| 5 | + | 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. | |
| 6 | 6 | ||
| 7 | - | ||
| 7 | + | 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. | |
| 8 | 8 | ||
| 9 | - | ||
| 9 | + | You will find a code example at: components/anchordocking/miniide/miniide1.lpi | |
| 10 | 10 | ||
| 11 | - | ||
| 11 | + | This means that the earlier TLazDockingManager and unit LDockCtrl are obsolete and now deprecated. | |
| 12 | 12 | ||
| 13 | 13 | ### Features | |
| 14 | 14 | ||
| 15 | - | ||
| 16 | - | ||
| 17 | - | ||
| 18 | - | ||
| 19 | - | ||
| 20 | - | ||
| 21 | - | ||
| 22 | - | ||
| 23 | - | ||
| 24 | - | ||
| 25 | - | ||
| 26 | - | ||
| 27 | - | ||
| 28 | - | ||
| 29 | - | ||
| 30 | - | ||
| 31 | - | ||
| 32 | - | ||
| 33 | - | ||
| 34 | - | ||
| 35 | - | ||
| 36 | - | ||
| 37 | - | ||
| 38 | - | ||
| 39 | - | ||
| 40 | - | ||
| 41 | - | ||
| 42 | - | ||
| 43 | - | ||
| 44 | - | ||
| 45 | - | ||
| 15 | + | * **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. | |
| 16 | + | * **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. | |
| 17 | + | * **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. | |
| 18 | + | * **Splitters** are automatically inserted between docked forms to allow resizing. | |
| 19 | + | * **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. | |
| 20 | + | * **Easy use** : With one line of code you can make a form or control dockable. Just give them unique names. | |
| 21 | + | * Not only forms, but any **TWinControl** can be made dockable. | |
| 22 | + | * Can **save/load layouts**. The layout information is stored for each dockable control and old layout files will still work even when the application gets more dockable controls or some are removed. The information is stored in the abstract class LCL TConfigStorage. So you can use for example TXMLConfigStorage to store layouts in xml files or you can write your own storage to store it wherever you want. | |
| 23 | + | * Each docked form is put into a docksite providing an optional **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 sides and moves by default automatically to the smaller side to save space. You can customize this. The header shows a customizable hint allowing to read long captions. | |
| 24 | + | * When a docksite is resized the _child sites are automatically scaled_. You can turn this off. | |
| 25 | + | * **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. | |
| 26 | + | * **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. | |
| 27 | + | * **Header popup menu** : | |
| 28 | + | * lock/unlock (disable dragging) | |
| 29 | + | * header position (auto, left, top, right, bottom), this is saved/restored with the layout | |
| 30 | + | * merge (for example after moving a dock page into a layout) | |
| 31 | + | * undock (needed if no place to undock on screen) | |
| 32 | + | * enlarge side to left, top, right, bottom | |
| 33 | + | * close | |
| 34 | + | * options | |
| 35 | + | * **Page popup menu** : | |
| 36 | + | * lock/unlock (disable dragging) | |
| 37 | + | * undock (needed if no place to undock on screen) | |
| 38 | + | * tab position for pagecontrol (top,bottom, left, right), this is saved/restored with the layout | |
| 39 | + | * move page to the left, right, leftmost, rightmost | |
| 40 | + | * close | |
| 41 | + | * options | |
| 42 | + | * Forms can be made dock sites. Then they can dock at one side. But they can not be docked itself. | |
| 43 | + | * close button automatically saves a layout | |
| 44 | + | * Powerful functions to alter the layout. You can use D&D to move a form and you can undock and dock in one move. There are functions to enlarge forms and shrinking others. These functions are available via the header popup menu as well. See below. | |
| 45 | + | * There is an IDE package which makes the Lazarus IDE dockable. It is called anchordockingdsgn.lpk. Make sure you only install one docking package. Do not install the easydockmgr at the same time! | |
| 46 | 46 | ||
| 47 | 47 | ### ToDos | |
| 48 | 48 | ||
| 49 | - | ||
| 50 | - | ||
| 51 | - | ||
| 52 | - | ||
| 53 | - | ||
| 54 | - | ||
| 49 | + | * Design time package: Add all layout files to menu | |
| 50 | + | * simple way to make forms dockable at designtime (that means without writing any code) | |
| 51 | + | * minimize button and Hide | |
| 52 | + | * on show again: restore a default layout | |
| 53 | + | * close button for pages | |
| 54 | + | * Implement automatic menu merging in the LCL (when two forms with main menus are docked). | |
| 55 | 55 | ||
| 56 | - | ||
| 56 | + | ## | |
| 57 | 57 | ||
| 58 | - | ||
| 58 | + | Usage I. (Add docking support to the Lazarus IDE) | |
| 59 | 59 | ||
| 60 | + | 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. | |
| 61 | + | ||
| 60 | 62 | ### Important to macOS users | |
| 61 | 63 | ||
| 62 | - | ||
| 64 | + | Before Lazarus 3.0, there are many bugs related to docking. | |
| 63 | 65 | ||
| 64 | - | ||
| 66 | + | If "anchordockingdsgn" has been installed before Lazarus 3.0, the wrong configuration may be saved and needs to be reset first. | |
| 65 | 67 | ||
| 66 | - | ||
| 68 | + | The configuration is saved in environmentoptions.xml, which usually located in ~/.lazarus | |
| 67 | 69 | ||
| 68 | - | ||
| 70 | + | 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. | |
| 69 | 71 | ||
| 70 | 72 | ### Installation | |
| 71 | 73 | ||
| 72 | - | ||
| 73 | - | ||
| 74 | - | ||
| 74 | + | Uninstall any other docking managers (e.g., easydockmgrdsgn). From the Lazarus menu bar pick "Package" - "Install/Uninstall Packages" and install the "anchordockingdsgn" package. | |
| 75 | 75 | ||
| 76 | - | ||
| 76 | + | 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. | |
| 77 | 77 | ||
| 78 | - | ||
| 78 | + | [](</File:2021-12-02_10_21_07-Debian_10.8_Buster_-_VMware_Workstation.png>) | |
| 79 | 79 | ||
| 80 | - | ||
| 80 | + | 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. | |
| 81 | 81 | ||
| 82 | - | ||
| 82 | + | 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. | |
| 83 | 83 | ||
| 84 | - | ||
| 84 | + | You can also save the layout to a file and load them later. | |
| 85 | 85 | ||
| 86 | - | ||
| 86 | + | Since Lazarus 1.1 you can pass a command line parameter | |
| 87 | + | ``` | |
| 87 | 88 | ./lazarus --anchordocklayout=<filename> | |
| 88 | 89 | ``` | |
| 89 | 90 | ||
| 90 | - | ||
| 91 | + | The look (like the headers) can be further tweaked by right-clicking on them. | |
| 91 | 92 | ||
| 92 | - | ||
| 93 | + | [](</File:docking_headers.gif>) | |
| 93 | 94 | ||
| 94 | 95 | ### Options | |
| 95 | 96 | ||
| 96 | - | ||
| 97 | + | After the successful installation of the AnchorDockingDsgn package, an additional configuration menu is added to the Lazarus options dialog ("Tools" - "Options" - "Environment") | |
| 97 | 98 | ||
| 98 | - | ||
| 99 | + | [](</File:anchordocking_options.png>) | |
| 99 | 100 | ||
| 100 | 101 | #### Scale on resize | |
| 101 | 102 | ||
| 102 | - | ||
| 103 | + | When resizing a window, all docked forms inside are scaled by the same percentage. | |
| 103 | 104 | ||
| 104 | 105 | #### Show headers | |
| 105 | 106 | ||
| 106 | - | ||
| 107 | + | To dock/undock a window, you need to enable this option. | |
| 107 | 108 | ||
| 108 | 109 | #### Flatten headers | |
| 109 | 110 | ||
| 110 | - | ||
| 111 | + | No 3d frame in headers. | |
| 111 | 112 | ||
| 112 | 113 | #### Header align top/left | |
| 113 | 114 | ||
| 114 | - | ||
| 115 | + | Headers are automatically put at top or left depending on these two values: | |
| 115 | 116 | ||
| 116 | - | ||
| 117 | - | ||
| 118 | - | ||
| 117 | + | * Move header to top, when (width/height)*100<=HeaderAlignTop, default 80 | |
| 118 | + | * Move header to left, when (width/height)*100>=HeaderAlignLeft, default 120 | |
| 119 | + | * Otherwise keep the header at the current position. | |
| 119 | 120 | ||
| 120 | - | ||
| 121 | + | 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. | |
| 121 | 122 | ||
| 122 | 123 | #### Allow dock sites to be minimized | |
| 123 | 124 | ||
| 124 | - | ||
| 125 | + | 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. | |
| 125 | 126 | ||
| 126 | 127 | #### Multine Tabs | |
| 127 | 128 | ||
| 128 | - | ||
| 129 | + | 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. | |
| 129 | 130 | ||
| 130 | 131 | #### Floating windows on top | |
| 131 | 132 | ||
| 132 | - | ||
| 133 | + | 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. | |
| 133 | 134 | ||
| 134 | 135 | ## Usage II. (Add docking support to your own applications) | |
| 135 | 136 | ||
| 136 | 137 | ### Quick start | |
| 137 | 138 | ||
| 138 | - | ||
| 139 | - | ||
| 140 | - | ||
| 139 | + | Add the package **AnchorDocking** to the required packages in the project inspector. | |
| 141 | 140 | ||
| 142 | - | ||
| 141 | + | Then add the unit **AnchorDocking** to the uses section of your main unit (the unit with your main form). | |
| 143 | 142 | ||
| 144 | - | ||
| 145 | - | ||
| 143 | + | Add to the FormCreate of your main form: | |
| 146 | 144 | ``` | |
| 147 | - | ||
| 148 | - | ||
| 149 | - | ||
| 150 | - | ||
| 151 | - | ||
| 145 | + | DockMaster.MakeDockSite(Self,[akBottom],admrpChild); | |
| 152 | 146 | ``` | |
| 153 | 147 | ||
| 154 | - | ||
| 148 | + | For the other dockable forms replace all calls of _Show_ and _ShowOnTop_ with | |
| 149 | + | ``` | |
| 150 | + | DockMaster.MakeDockable(Form1,true,true); | |
| 151 | + | ``` | |
| 155 | 152 | ||
| 156 | - | ||
| 157 | - | ||
| 153 | + | For the other dockable forms replace all calls of _Visible:=true_ with | |
| 158 | 154 | ``` | |
| 155 | + | DockMaster.MakeDockable(Form1,true); | |
| 156 | + | ``` | |
| 159 | 157 | ||
| 160 | - | ||
| 158 | + | Remove or comment all _Hide_ , _Visible:=false_ , _WindowState:=_ calls. | |
| 161 | 159 | ||
| 162 | 160 | ### Prerequisites | |
| 163 | 161 | ||
| 164 | - | ||
| 165 | - | ||
| 166 | - | ||
| 167 | - | ||
| 162 | + | * Your project must use the package _AnchorDocking_. | |
| 163 | + | * All dockable forms must be shown with MakeDockable or MakeDockSite. Do not use _Show_ , _BringToFront_ , _ShowOnTop_ , _Visible:=true_. Of course you can have some non dockable forms, like hints or splashscreens. | |
| 164 | + | * All dockable forms must be free resizable, that means no constraints, no BorderStyle bsDialog. | |
| 165 | + | * No other docking system. AnchorDocking is incompatible with EasyDockMgr. | |
| 168 | 166 | ||
| 169 | 167 | ### Making forms dockable | |
| 170 | 168 | ||
| 171 | - | ||
| 172 | - | ||
| 173 | - | ||
| 169 | + | 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: | |
| 170 | + | ``` | |
| 174 | 171 | // shows YourForm | |
| 175 | - | ||
| 176 | - | ||
| 172 | + | // if not already done, wrap the form into a dock site | |
| 173 | + | DockMaster.MakeDockable(YourForm); | |
| 177 | 174 | ``` | |
| 178 | 175 | ||
| 179 | - | ||
| 176 | + | Here are some examples how a form looks like that was made dockable with **DockMaster.MakeDockable** : | |
| 180 | 177 | ||
| 181 | - | ||
| 178 | + | [](</File:Docksite1.png>) [](</File:Docksite2.png>) | |
| 182 | 179 | ||
| 183 | - | ||
| 180 | + | The header position is normally done automatically and the user can with a right click put it to any of the four sides. | |
| 184 | 181 | ||
| 185 | 182 | ### Example: miniide1 | |
| 186 | 183 | ||
| 187 | - | ||
| 184 | + | 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. | |
| 188 | 185 | ||
| 189 | - | ||
| 186 | + | [](</File:Anchordocking_miniide1.png>) | |
| 190 | 187 | ||
| 191 | 188 | ### Making the main form a dock site | |
| 192 | 189 | ||
| 193 | - | ||
| 194 | - | ||
| 195 | - | ||
| 190 | + | In the TMainIDE.FormCreate the main form **MainIDE** is turned into a docksite: | |
| 191 | + | ``` | |
| 196 | 192 | DockMaster.MakeDockSite(Self,[akBottom],admrpChild); | |
| 197 | 193 | ``` | |
| 198 | 194 | ||
| 199 | - | ||
| 195 | + | 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. | |
| 200 | 196 | ||
| 201 | - | ||
| 197 | + | 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 [[Autosize / Layout|here]] how Align works. | |
| 202 | 198 | ||
| 203 | - | ||
| 199 | + | The DockMaster adds automatically a splitter: | |
| 204 | 200 | ||
| 205 | - | ||
| 201 | + | [](</File:Anchordocking_miniide_dockedse1.png>) | |
| 206 | 202 | ||
| 207 | - | ||
| 203 | + | As soon as a dockable form is docked its caption is shown in the dock header. | |
| 208 | 204 | ||
| 209 | 205 | #### Requirements for a custom dock site | |
| 210 | 206 | ||
| 211 | - | ||
| 207 | + | 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: | |
| 212 | 208 | ||
| 213 | - | ||
| 214 | - | ||
| 215 | - | ||
| 216 | - | ||
| 209 | + | * AutoSize=true may result in an endless loop. Disable it or override DoAutoSize/CalculatePreferredSize and take special care. | |
| 210 | + | * Constraints: The DockMaster clears the maximum Constraints and will restore them on undock. | |
| 211 | + | * Child controls anchored to the aligned site may overlap. See [[Autosize / Layout|here]] how Align works. | |
| 212 | + | * ChildSizing: The spacing properties like LeftRightSpacing, TopBottomSpacing may interfere with the docking layout. | |
| 217 | 213 | ||
| 218 | 214 | ### Procedure to create all other forms by name | |
| 219 | 215 | ||
| 220 | - | ||
| 221 | - | ||
| 222 | - | ||
| 216 | + | The MainIDE sets the **DockMaster.OnCreateControl** event, to enable the DockMaster to create forms by name. This is needed to restore layouts. | |
| 217 | + | ``` | |
| 223 | 218 | DockMaster.OnCreateControl:=@DockMasterCreateControl; | |
| 224 | 219 | ``` | |
| 225 | - | ||
| 226 | - | ||
| 220 | + | ``` | |
| 227 | 221 | procedure TMainIDE.DockMasterCreateControl(Sender: TObject; aName: string; var | |
| 228 | - | ||
| 229 | - | ||
| 230 | - | ||
| 231 | - | ||
| 232 | - | ||
| 233 | - | ||
| 234 | - | ||
| 235 | - | ||
| 236 | - | ||
| 237 | - | ||
| 238 | - | ||
| 239 | - | ||
| 240 | - | ||
| 241 | - | ||
| 242 | - | ||
| 243 | - | ||
| 244 | - | ||
| 245 | - | ||
| 246 | - | ||
| 247 | - | ||
| 248 | - | ||
| 249 | - | ||
| 250 | - | ||
| 251 | - | ||
| 252 | - | ||
| 253 | - | ||
| 222 | + | AControl: TControl; DoDisableAutoSizing: boolean); | |
| 223 | + | ||
| 224 | + | procedure CreateForm(Caption: string; NewBounds: TRect); | |
| 225 | + | begin | |
| 226 | + | AControl:=CreateSimpleForm(aName,Caption,NewBounds,DoDisableAutoSizing); | |
| 227 | + | end; | |
| 228 | + | ||
| 229 | + | begin | |
| 230 | + | // first check if the form already exists | |
| 231 | + | // the LCL Screen has a list of all existing forms. | |
| 232 | + | // Note: Remember that the LCL allows as form names only standard | |
| 233 | + | // pascal identifiers and compares them case insensitive | |
| 234 | + | AControl:=Screen.FindForm(aName); | |
| 235 | + | if AControl<>nil then begin | |
| 236 | + | // if it already exists, just disable autosizing if requested | |
| 237 | + | if DoDisableAutoSizing then | |
| 238 | + | AControl.DisableAutoSizing; | |
| 239 | + | exit; | |
| 240 | + | end; | |
| 241 | + | // if the form does not yet exist, create it | |
| 242 | + | if aName='CodeExplorer' then | |
| 243 | + | CreateForm('Code Explorer',Bounds(700,230,100,250)) | |
| 244 | + | ... | |
| 245 | + | else if aName='DebugOutput' then | |
| 246 | + | CreateForm('Debug Output',Bounds(400,400,350,150)); | |
| 247 | + | end; | |
| 254 | 248 | ``` | |
| 255 | 249 | ||
| 256 | - | ||
| 257 | - | ||
| 258 | - | ||
| 250 | + | Creating a form can be as simple as this: | |
| 251 | + | ``` | |
| 259 | 252 | MyForm:=TMyForm.Create(Self); | |
| 260 | - | ||
| 261 | - | ||
| 253 | + | if DoDisableAutoSizing then | |
| 254 | + | MyForm.DisableAutoSizing; | |
| 262 | 255 | ``` | |
| 263 | 256 | ||
| 264 | - | ||
| 265 | - | ||
| 266 | - | ||
| 257 | + | But of course you can put there all kind of initialization code. | |
| 267 | 258 | ||
| 268 | - | ||
| 259 | + | The _DisableAutoSizing_ reduces flickering. Make sure your forms **Visible** property is set to **false**. | |
| 269 | 260 | ||
| 270 | - | ||
| 261 | + | 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: | |
| 262 | + | ``` | |
| 271 | 263 | TControl.EnableAutoSizing SourceEditor1:TSimpleForm: missing DisableAutoSizing | |
| 272 | 264 | ``` | |
| 273 | 265 | ||
| 274 | - | ||
| 266 | + | [](</File:MissingDisableAutoSizing.png>) | |
| 275 | 267 | ||
| 276 | - | ||
| 268 | + | 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. | |
| 277 | 269 | ||
| 278 | 270 | ### Showing forms | |
| 279 | 271 | ||
| 280 | - | ||
| 281 | - | ||
| 282 | - | ||
| 272 | + | When a form should be shown, you have probably used something like '_MyForm.Show_. Instead you should now use | |
| 273 | + | ``` | |
| 283 | 274 | DockMaster.MakeDockable(MyForm); | |
| 284 | 275 | ``` | |
| 285 | 276 | ||
| 286 | - | ||
| 287 | - | ||
| 288 | - | ||
| 277 | + | 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. | |
| 289 | 278 | ||
| 290 | - | ||
| 279 | + | If you set the **DockMaster.OnCreateControl** event you can use this: | |
| 280 | + | ``` | |
| 291 | 281 | DockMaster.ShowControl('MyForm',true); | |
| 292 | 282 | ``` | |
| 293 | 283 | ||
| 294 | 284 | ### Docking manually, via code | |
| 295 | 285 | ||
| 296 | - | ||
| 297 | - | ||
| 298 | - | ||
| 286 | + | Use the procedure **DockMaster.ManualDock** to dock a site to or into another. | |
| 287 | + | ``` | |
| 299 | 288 | procedure ManualDock(SrcSite, TargetSite: TAnchorDockHostSite; Align: TAlign; TargetControl: TControl = nil); | |
| 300 | 289 | ``` | |
| 301 | 290 | ||
| 302 | - | ||
| 303 | - | ||
| 304 | - | ||
| 291 | + | * **SrcSite** is the site to be docked. If SrcSite was docked it will be undocked first. | |
| 292 | + | * **TargetSite** is the site where SrcSite will be docked into or docked as neighbor. | |
| 293 | + | * **TargetControl** specifies if docking as neighbor (=nil), as inside neighbor (=TargetSide) or in front of a page (=a TAnchorDockPage). | |
| 305 | 294 | ||
| 306 | - | ||
| 295 | + | ||
| 307 | 296 | ||
| 308 | - | ||
| 297 | + | ### Undocking manually, via code | |
| 309 | 298 | ||
| 310 | - | ||
| 299 | + | 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. | |
| 300 | + | ``` | |
| 311 | 301 | procedure ManualFloat(AControl: TControl); | |
| 312 | 302 | ``` | |
| 313 | 303 | ||
| 314 | - | ||
| 304 | + | 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. | |
| 315 | 305 | ||
| 316 | 306 | ### Save layout | |
| 317 | 307 | ||
| 318 | - | ||
| 319 | - | ||
| 320 | - | ||
| 308 | + | The DockMaster allows to save the current layout to a TConfigStorage. The miniide example uses the xml version: | |
| 309 | + | ``` | |
| 321 | 310 | procedure TMainIDE.SaveLayout(Filename: string); | |
| 322 | - | ||
| 323 | - | ||
| 324 | - | ||
| 325 | - | ||
| 326 | - | ||
| 327 | - | ||
| 328 | - | ||
| 329 | - | ||
| 330 | - | ||
| 331 | - | ||
| 332 | - | ||
| 333 | - | ||
| 334 | - | ||
| 335 | - | ||
| 336 | - | ||
| 337 | - | ||
| 338 | - | ||
| 339 | - | ||
| 311 | + | var | |
| 312 | + | XMLConfig: TXMLConfigStorage; | |
| 313 | + | begin | |
| 314 | + | try | |
| 315 | + | // create a new xml config file | |
| 316 | + | XMLConfig:=TXMLConfigStorage.Create(Filename,false); | |
| 317 | + | try | |
| 318 | + | // save the current layout of all forms | |
| 319 | + | DockMaster.SaveLayoutToConfig(XMLConfig); | |
| 320 | + | XMLConfig.WriteToDisk; | |
| 321 | + | finally | |
| 322 | + | XMLConfig.Free; | |
| 323 | + | end; | |
| 324 | + | except | |
| 325 | + | on E: Exception do begin | |
| 326 | + | MessageDlg('Error', | |
| 327 | + | 'Error saving layout to file '+Filename+':'#13+E.Message,mtError, | |
| 328 | + | [mbCancel],0); | |
| 329 | + | end; | |
| 330 | + | end; | |
| 340 | 331 | end; | |
| 341 | - | ||
| 342 | - | ||
| 343 | 332 | ``` | |
| 344 | 333 | ||
| 345 | 334 | ### Load layout | |
| 346 | - | ||
| 347 | - | ||
| 335 | + | ``` | |
| 348 | 336 | procedure TMainIDE.LoadLayout(Filename: string); | |
| 349 | - | ||
| 350 | - | ||
| 351 | - | ||
| 352 | - | ||
| 353 | - | ||
| 354 | - | ||
| 355 | - | ||
| 356 | - | ||
| 357 | - | ||
| 358 | - | ||
| 359 | - | ||
| 360 | - | ||
| 361 | - | ||
| 362 | - | ||
| 363 | - | ||
| 364 | - | ||
| 365 | - | ||
| 366 | - | ||
| 337 | + | var | |
| 338 | + | XMLConfig: TXMLConfigStorage; | |
| 339 | + | begin | |
| 340 | + | try | |
| 341 | + | // load the xml config file | |
| 342 | + | XMLConfig:=TXMLConfigStorage.Create(Filename,True); | |
| 343 | + | try | |
| 344 | + | // restore the layout | |
| 345 | + | // this will close unneeded forms and call OnCreateControl for all needed | |
| 346 | + | DockMaster.LoadLayoutFromConfig(XMLConfig); | |
| 347 | + | finally | |
| 348 | + | XMLConfig.Free; | |
| 349 | + | end; | |
| 350 | + | except | |
| 351 | + | on E: Exception do begin | |
| 352 | + | MessageDlg('Error', | |
| 353 | + | 'Error loading layout from file '+Filename+':'#13+E.Message,mtError, | |
| 354 | + | [mbCancel],0); | |
| 355 | + | end; | |
| 356 | + | end; | |
| 367 | 357 | end; | |
| 368 | - | ||
| 369 | - | ||
| 370 | 358 | ``` | |
| 371 | 359 | ||
| 372 | 360 | ### Enlarge/Shrink | |
| 373 | 361 | ||
| 374 | - | ||
| 375 | - | ||
| 376 | - | ||
| 362 | + | 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** : | |
| 363 | + | ``` | |
| 377 | 364 | function ManualEnlarge(Site: TAnchorDockHostSite; Side: TAnchorKind; OnlyCheckIfPossible: boolean): boolean; | |
| 378 | 365 | ``` | |
| 379 | 366 | ||
| 380 | - | ||
| 367 | + | 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. | |
| 381 | 368 | ||
| 382 | 369 | ### Enlarge one, shrink another | |
| 383 | 370 | ||
| 384 | - | ||
| 371 | + | Shrink neighbor _Object Inspector_ , enlarge _Messages_ : Right click on the header of _Messages_ and click on **Enlarge right side**. Two splitters are resized. | |
| 385 | 372 | ||
| 386 | - | ||
| 373 | + | [](</File:Anchordocking_before_enlarge1.png>) enlarging _Messages_ to the right side: [](</File:Anchordocking_after_enlarge1.png>) | |
| 387 | 374 | ||
| 388 | 375 | ### Enlarge one, shrink many | |
| 389 | 376 | ||
| 390 | - | ||
| 377 | + | 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**. | |
| 391 | 378 | ||
| 392 | - | ||
| 379 | + | [](</File:Anchordocking_before_enlarge2.png>) becomes [](</File:Anchordocking_after_enlarge2.png>) | |
| 393 | 380 | ||
| 394 | 381 | ### General docking options | |
| 395 | 382 | ||
| 396 | - | ||
| 397 | - | ||
| 398 | - | ||
| 383 | + | 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: | |
| 384 | + | ``` | |
| 399 | 385 | uses ... AnchorDockOptionsDlg; | |
| 400 | - | ||
| 401 | - | ||
| 402 | - | ||
| 403 | - | ||
| 404 | - | ||
| 405 | - | ||
| 406 | - | ||
| 407 | - | ||
| 386 | + | ... | |
| 387 | + | procedure TMainIDE.FormCreate(Sender: TObject); | |
| 388 | + | ... | |
| 389 | + | begin | |
| 390 | + | ... | |
| 391 | + | DockMaster.OnShowOptions:=@ShowAnchorDockOptions; | |
| 392 | + | ... | |
| 393 | + | end; | |
| 408 | 394 | ``` | |
| 409 | 395 | ||
| 410 | - | ||
| 396 | + | This will add a new menu item to the popup menus of the dock headers and pages called _Docking options_. | |
| 411 | 397 | ||
| 412 | 398 | ## Why use Anchors instead of Align? | |
| 413 | 399 | ||
| 414 | - | ||
| 400 | + | 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. | |
| 415 | 401 | ||
| 416 | 402 | ### Layouts that can be created with Align | |
| 417 | 403 | ||
| 418 | - | ||
| 404 | + | Align can only create the following layouts: | |
| 419 | 405 | ||
| 420 | - | ||
| 406 | + | [](</File:Anchordocking_align_layout1.png>) | |
| 421 | 407 | ||
| 422 | - | ||
| 408 | + | 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. | |
| 423 | 409 | ||
| 424 | 410 | ### Layouts that can be created with Align and Panels | |
| 425 | 411 | ||
| 426 | - | ||
| 412 | + | 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: | |
| 427 | 413 | ||
| 428 | - | ||
| 414 | + | [](</File:Anchordocking_align_panels_layout1.png>) | |
| 429 | 415 | ||
| 430 | - | ||
| 416 | + | This requires only one hidden panel. | |
| 431 | 417 | ||
| 432 | 418 | ### Changing Layouts | |
| 433 | 419 | ||
| 434 | - | ||
| 420 | + | 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**. | |
| 435 | 421 | ||
| 436 | - | ||
| 422 | + | [](</File:Anchordocking_align_panels_layout2.png>) | |
| 437 | 423 | ||
| 438 | - | ||
| 424 | + | 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. | |
| 439 | 425 | ||
| 440 | 426 | ### Layouts that are impossible with Align and Panels | |
| 441 | 427 | ||
| 442 | - | ||
| 428 | + | Now the user wants to enlarge _SourceEditor1_ horizontally (and shrink _ObjectInspector_): | |
| 443 | 429 | ||
| 444 | - | ||
| 430 | + | [](</File:Anchordocking_impossible_with_align_panels1.png>) | |
| 445 | 431 | ||
| 446 | - | ||
| 432 | + | This layout is impossible with Align and panels, because you can not cut it in two halves. The same with | |
| 447 | 433 | ||
| 448 | - | ||
| 434 | + | [](</File:Anchordocking_impossible_with_align_panels2.png>) | |
| 449 | 435 | ||
| 450 | 436 | ### Conclusion | |
| 451 | 437 | ||
| 452 | - | ||
| 438 | + | 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. | |
| 453 | 439 | ||
| 454 | 440 | ## Old/deprecated anchor docking | |
| 455 | 441 | ||
| 456 | 442 | ### Create a TLazDockingManager | |
| 457 | - | ||
| 458 | - | ||
| 459 | - | ||
| 460 | 443 | ``` | |
| 444 | + | DockingManager:=TLazDockingManager.Create(Self); | |
| 445 | + | ``` | |
| 461 | 446 | ||
| 462 | - | ||
| 447 | + | 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. | |
| 463 | 448 | ||
| 464 | 449 | ### Optional: Loading a configuration | |
| 465 | 450 | ||
| 466 | - | ||
| 467 | - | ||
| 468 | - | ||
| 469 | - | ||
| 470 | - | ||
| 471 | - | ||
| 451 | + | You can load the user configuration from disk. | |
| 472 | 452 | ``` | |
| 453 | + | Config:=TXMLConfigStorage.Create('config.xml',true); | |
| 454 | + | DockingManager.LoadFromConfig(Config); | |
| 455 | + | Config.Free; | |
| 456 | + | ``` | |
| 473 | 457 | ||
| 474 | - | ||
| 458 | + | This loads the file _config.xml_. The config can be created by the SaveToConfig function. See below. | |
| 475 | 459 | ||
| 476 | 460 | ### Make a form/control dockable | |
| 477 | 461 | ||
| 478 | - | ||
| 479 | - | ||
| 480 | - | ||
| 481 | - | ||
| 482 | - | ||
| 483 | - | ||
| 462 | + | Create a TLazControlDocker for each form/control that should be dockable | |
| 484 | 463 | ``` | |
| 464 | + | ControlDocker1:=TLazControlDocker.Create(Self); | |
| 465 | + | ControlDocker1.Name:='DockerForm1'; | |
| 466 | + | ControlDocker1.Manager:=DockingManager; | |
| 467 | + | ``` | |
| 485 | 468 | ||
| 486 | 469 | ### Optional: Saving the user configuration to disk | |
| 487 | 470 | ||
| 488 | - | ||
| 489 | - | ||
| 490 | - | ||
| 491 | - | ||
| 492 | - | ||
| 493 | - | ||
| 494 | - | ||
| 471 | + | When the program is closed you can save the user configuration to disk | |
| 495 | 472 | ``` | |
| 473 | + | Config:=TXMLConfigStorage.Create('config.xml',true); | |
| 474 | + | DockingManager.SaveToConfig(Config); | |
| 475 | + | Config.WriteToDisk; | |
| 476 | + | Config.Free; | |
| 477 | + | ``` | |
| 496 | 478 | ||
| 497 | 479 | ## See also | |
| 498 | 480 | ||
| 499 | - | ||
| 500 | - | ||
| 501 | - | ||
| 502 | - | ||
| 481 | + | * [[AnchorDockingDsgn]] AnchorDocking in the Lazarus IDE | |
| 482 | + | * [[Anchor Docking Step by step example|Anchor Docking: A Step by step example]] | |
| 483 | + | * [[Docking]] in general | |
| 484 | + | * [[EasyDockingManager]] \- an alternative docking implementation with a simpler layout engine and fewer options. | |
| 503 | 485 | ||
| 504 | 486 | --- | |
| 505 | - | ||
| 506 | - | ||
| 507 | - | ||
| 487 | + | *From the Free Pascal wiki, page "Anchor Docking", as the Internet Archive kept it on 2025-12-19, last changed on 2025-09-02. 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](/wiki-contact).* |