diff --git a/docs/xml/lcl/ldocktree.xml b/docs/xml/lcl/ldocktree.xml index 2c9401b948..b952319a96 100644 --- a/docs/xml/lcl/ldocktree.xml +++ b/docs/xml/lcl/ldocktree.xml @@ -7,52 +7,38 @@ ==================================================================== --> - This unit defines TLazDockTree, the default TDockTree for the LCL. + This unit defines TLazDockTree, the default TDockTree used in the LCL. + +

+ ldocktree.pas contains TLazDockTree, the default TDockTree used in the LCL. +

+

+ This file is part of the Lazarus Component Library (LCL). +

+ + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - TLazDockSplitter - a splitter used with Lazarus Docking components. - - - - + + + + + + + + + + + + + + + + + + + + @@ -61,57 +47,56 @@ + - - - - - - - - - - - - - - - - - + + + + - - Destroy - destructor for TLazDockZone; frees subcomponents then calls inherited Destroy. - - - - + Destructor for the class instance. + + Destroy is the overridden destructor for TLazDockZone, It calls FreeSubComponents to free resources allocated to Page, Pages, and Splitter. It calls the inherited destructor prior to exiting from the method. + + + + + + + + + + + FreeSubComponents - frees and nils the local splitter and page/pages components, ready for destroying the control. + + + - GetCaption - if there is a child control, returns the caption for that control; else returns the Index of the control as a string value. + GetCaption - if there is a child control, returns the caption for that control; else returns the Index of the control as a string value. + - - + - GetParentControl - returns the identity of the Parent control if there is one; otherwise returns the Root zone if this is, in fact, the Root, or the Child control. + GetParentControl - returns the identity of the Parent control if there is one; otherwise returns the Root zone if this is, in fact, the Root, or the Child control. + - - + The Splitter to be use to control the docking of this Zone. @@ -130,97 +115,165 @@ + + + + Record type used to track mouse position and button state in a dock header. + + +

+ Used in the implementation of TLazDockTree and TLazDockForm. +

+ + + + + + + + + + + + + + + + Enumerated type with values representing the images used in a dock header. + + + + + + Image for the restore button in a dock header. + + + Image for the close button in a dock header. + + + + Array type used to store bitmap images used in a dock header. + +

+ Elements in TDockHeaderImages can be accessed using the enumeration values in TDockHeaderImageKind. Used in the implementation of TLazDockTree and TLazDockForm. +

+ + + + + + + + - TLazDockTree - a tree of TLazDockZones found in a docked window. + TLazDockTree - a tree of TLazDockZones found in a docked window. + + - - - - - - - + + + + + - UndockControlForDocking - frees anchors from parent and sibling controls. + AnchorDockLayout - sets up anchors between all docked controls and helper controls. + - - - + - + + + + CreateDockLayoutHelperControls - creates any splitters and pages needed for the dock layout, including recursive creation for child controls. + + + + + + + + + + + ResetSizes - splits available size of Zone between children. + + + BreakAnchors - detach the anchors of all child controls. - - - - + + - CreateDockLayoutHelperControls - creates any splitters and pages needed for the dock layout, including recursive creation for child controls. + PaintDockFrame - finds the cursor position and paints the dock frame of the specified size on the nominated canvas. + + + + + + UndockControlForDocking - frees anchors from parent and sibling controls. + - - + - - + + - AnchorDockLayout - sets up anchors between all docked controls and helper controls. - - - + DefaultDockGrabberSize - returns the default size for the dock grabber. + - - - - - + Create - constructor for TLazDockTree: creates a docking form if required, sets up a dock manager then calls inherited Create. - - - + Destroy - destructor for TLazDockTree: frees the dock site, annuls the Docksite manager, destroys any images then calls inherited Destroy. - - + + + + AdjustDockRect - offset one of the borders of control rect in order to get space for frame. + + + - InsertControl - undocks AControl and docks it into the tree. + InsertControl - undocks AControl and docks it into the tree. +

- InsertControl - undocks AControl and docks it into the tree + InsertControl - undocks AControl and docks it into the tree.

It creates a new TDockZone for AControl and inserts it as a new leaf. @@ -234,88 +287,112 @@ A newly created TLazDockTree has only a DockSite (TLazDockForm) and a single TDockZone - the RootZone, which has as ChildControl the DockSite.

-
-    Visual:
-      +-DockSite--+
-      |           |
-      +-----------+
-    Tree of TDockZone:
-      RootZone (DockSite,doNoOrient)
-
-
-  Inserting the first control:  InsertControl(Form1,alLeft,nil);
-    Visual:
-      +-DockSite---+
-      |+--Form1---+|
-      ||          ||
-      |+----------+|
-      +------------+
-    Tree of TDockZone:
-      RootZone (DockSite,doHorizontal)
-       +-Zone2 (Form1,doNoOrient)
-
-
-  Dock Form2 right of Form1:  InsertControl(Form2,alLeft,Form1);
-    Visual:
-      +-DockSite----------+
-      |+-Form1-+|+-Form2-+|
-      ||        ||       ||
-      |+-------+|+-------+|
-      +-------------------+
-    Tree of TDockZone:
-      RootZone (DockSite,doHorizontal)
-       +-Zone2 (Form1,doNoOrient)
-       +-Zone3 (Form2,doNoOrient)
+

+ Visual: +

+ ++-DockSite--+ +| | ++-----------+ + +

+ Tree of TDockZone: +

+RootZone (DockSite,doNoOrient) +

+ Inserting the first control: +

+InsertControl(Form1,alLeft,nil); +

+ Visual: +

+ ++-DockSite---+ +|+--Form1---+| +|| || +|+----------+| ++------------+ + +

+ Tree of TDockZone: +

+ +RootZone (DockSite,doHorizontal) + +-Zone2 (Form1,doNoOrient) + +

+ Dock Form2 right of Form1: +

+InsertControl(Form2,alLeft,Form1); +

+ Visual: +

+ ++-DockSite----------+ +|+-Form1-+|+-Form2-+| +|| || || +|+-------+|+-------+| ++-------------------+ + +

+ Tree of TDockZone: +

+ +RootZone (DockSite,doHorizontal) + +-Zone2 (Form1,doNoOrient) + +-Zone3 (Form2,doNoOrient) + - - - - + + + + RemoveControl - destroy child zone and all parents if they does not contain anything else, then removes the dock control. + + + + + + - BuildDockLayout - breaks the current anchors, forms the appropriate helper controls then re-establishes the anchors. + BuildDockLayout - breaks the current anchors, forms the appropriate helper controls then re-establishes the anchors. + - - - + FindBorderControls - makes splitters for all bordering controls along the specified Side. - - - - - + Gets the control with the specified dock zone and anchor side. @@ -323,56 +400,99 @@ Returns the DockSite if no controls are found using the specified zone and anchor side.

- - - - - + - GetAnchorControl - find a control to anchor the Zone's Side. + GetAnchorControl - find a control to anchor the Zone's Side. + - - - - - - + + + + PaintSite - paint bounds for each control and close button (using the supplied handle). + + + + + + + + + MessageHandler - checks the state of the mouse and takes the appropriate action. Checks whether redraw is needed because of mouse move or change in mouse button status, text needs to be added, etc. + + + + + + + + + + + + DumpLayout - writes layout of Zone to a file, for debugging purposes etc. + + + + + + - AutoFreeDockSite - determines whether the dock site is free. + AutoFreeDockSite - determines whether the dock site is free. + - + + + Enumerated type representing the parts in a dock header. + + + + + Total header rectangle. + + + Header caption. + + + Header restore button. + + + Header close button. + + + - TLazDockForm - the default DockSite for a TLazDockTree and for TCustomAnchoredDockManager. + TLazDockForm - the default DockSite for a TLazDockTree and for TCustomAnchoredDockManager. +

TLazDockForm - the default DockSite for a TLazDockTree and for TCustomAnchoredDockManager @@ -384,63 +504,266 @@ - - + + + + + + + + + + Notification - if the required operation is removal, sets MainControl to nil, then calls inherited Notification. + + + TCustomForm.Notification + + + + + + UpdateMainControl - sets MainControl to a new value. + + + + + + MouseUp - calls inherited MouseUp then finds position and appropriate header. + + + TControl.MouseUp + + + + + + MouseDown - performs inherited MouseDown, then finds position and appropriate header. + + + TControl.MouseDown + + + + + + MouseMove - performs inherited MouseMove, then finds position and appropriate header. + + + TControl.MouseMove + + + + + + MouseLeave - performs inherited MouseLeave, and sets the local store of position to indicate absence of the mouse. + + + TControl.MouseLeave + + + + + + PaintWindow - calls inherited PaintWindow, then creates new canvas and handle at cursor position, inserts header caption, title and images. + + + TCustomControl.PaintWindow + + + + + + + + TrackMouse - finds position of the mouse, which part of the control it occupies (whether header or main part of control), and state of buttons. + + + + + + + + + + + + Create - constructor for TLazDocForm: calls inherited Create, then fills in the header. + + + TCustomForm.Create + + + + Owner of the object instance. + + + + + Destroy - destructor for TLazDockForm: removes header then calls inherited Destroy. + + + TCustomForm.Destroy + + + + + + CloseQuery - calls inherited method, then asks all top level forms if form can close. + + + TCustomForm.CloseQuery + + + + + + UpdateCaption - brings caption up-to-date if there have been changes. + + + + + UpdateMainControlInParents - make sure all parents recognize the presence of MainControl. + + + + + + + + + FindMainControlCandidate - finds forms and controls in the docktree hierarchy that could act as the MainControl. + + + + + + + + + FindHeader - identifies the part of the dock form that is the header, and returns a TControl. + + + + + + + + + + + + + + + + + + InsertControl - calls inherited method then updates the main control. + + + TWinControl.InsertControl + + + + + + + + + + + + IsDockedControl - checks if control is a child, not a TLazDockSplitter and properly anchor docked; returns True if OK. + + + + + + + + + ControlHasTitle - returns True if nominated control is visible, is a docked control and has a border spacing greater than zero. + + + + + + + + + GetTitleRect - returns the coordinates of the title rectangle for the nominated control. + + + + + + + + + + + GetTitleOrientation - returns the orientation (horizontal or vertical) of the title in the nominated control. + + + + + + + + + + + + The identity of the MainControl in the docked form (used for the default caption). + - - - - - - - - - - - - - - - - - - - + TLazDockPage - an entity similar to a TLazDockForm, but forming a page in a notebook of TLazDockPages. - + - - - - + + + + + + + + InsertControl - calls inherited method, then ensures that all parents recognize the MainControl. + + + TWinControl.InsertControl + - - + - - + + + + The DockZone in which this page is located. + The PageControl or notebook in which this page is located (its parent). + @@ -487,194 +810,18 @@ - - - - Page - an individual TLazDockPage in the notebook, referred by its Index. - - - - - - - - - - - - - - - - - - - - - FreeSubComponents - frees and nils the local splitter and page/pages components, ready for destroying the control. - - - - ResetSizes - splits available size of Zone between children. - - - - PaintDockFrame - finds the cursor position and paints the dock frame of the specified size on the nominated canvas. - - - - DefaultDockGrabberSize - returns the default size for the dock grabber. - - - - AdjustDockRect - offset one of the borders of control rect in order to get space for frame. - - - - RemoveControl - destroy child zone and all parents if they does not contain anything else, then removes the dock control. - - - - PaintSite - paint bounds for each control and close button (using the supplied handle). - - - - MessageHandler - checks the state of the mouse and takes the appropriate action: checks whether redraw is needed because of mouse move or change in mouse button status, text needs to be added, etc. - - - - DumpLayout - writes layout of Zone to a file, for debugging purposes etc. - - - - Notification - if the required operation is removal, sets MainControl to nil, then calls inherited Notification. - - - TCustomForm.Notification - - - - - UpdateMainControl - sets MainControl to a new value. - - - - MouseUp - calls inherited MouseUp then finds position and appropriate header. - - TControl.MouseUp - - - - - MouseDown - performs inherited MouseDown, then finds position and appropriate header. - - TControl.MouseDown - - - - - MouseMove - performs inherited MouseMove, then finds position and appropriate header. - - TControl.MouseMove - - - - - MouseLeave - performs inherited MouseLeave, and sets the local store of position to indicate absence of the mouse. - - TControl.MouseLeave - - - - - PaintWindow - calls inherited PaintWindow, then creates new canvas and handle at cursor position, inserts header caption, title and images. - - TCustomControl.PaintWindow - - - - - TrackMouse - finds position of the mouse, which part of the control it occupies (whether header or main part of control), and state of buttons. - - - - Create - constructor for TLazDocForm: calls inherited Create, then fills in the header. - - TCustomForm.Create - - - - - Destroy - destructor for TLazDockForm: removes header then calls inherited Destroy. - - TCustomForm.Destroy - - - - - CloseQuery - calls inherited method, then asks all top level forms if form can close. - - TCustomForm.CloseQuery - - - - - UpdateCaption - brings caption up-to-date if there have been changes. - - - - UpdateMainControlInParents - make sure all parents recognize the presence of MainControl. - - - - FindMainControlCandidate - finds forms and controls in the docktree hierarchy that could act as the MainControl. - - - - FindHeader - identifies the part of the dock form that is the header, and returns a TControl. - - - - InsertControl - calls inherited method then updates the main control. - - TWinControl.InsertControl - - - - - IsDockedControl - checks if control is a child, not a TLazDockSplitter and properly anchor docked; returns True if OK. - - - - ControlHasTitle - returns True if nominated control is visible, is a docked control and has a border spacing greater than zero. - - - - GetTitleRect - returns the coordinates of the title rectangle for the nominated control. - - - - GetTitleOrientation - returns the orientation (horizontal or vertical) of the title in the nominated control. - - - The identity of the MainControl in the docked form (used for the default caption). - - - - InsertControl - calls inherited method, then ensures that all parents recognize the MainControl. - - - TWinControl.InsertControl - - - GetFloatingDockSiteClass - returns a default class of TLazDockForm, overriding the inherited value. + GetFloatingDockSiteClass - returns a default class of TLazDockForm, overriding the inherited value. + TControl.GetFloatingDockSiteClass + + + @@ -689,315 +836,184 @@ - Change - calls inherited method, then ensures that all parents recognize MainControl. + Change - calls inherited method, then ensures that all parents recognize MainControl. + + - TCustomTabControl.Change + TCustomTabControl.Change + + + + Page - an individual TLazDockPage in the notebook, referred by its Index. + + + + + + + + + + + + + + TLazDockSplitter - a splitter used with Lazarus docking components. + + + + + - Create - constructor for TLazDockSplitter: calls inherited Create and initializes -minimum size. - - TCustomSplitter.Create - - - - - TLazDockOwnerComponent - A TComponent owning all automatically created controls of a TCustomAnchoredDockManager, like TLazDockForm. + Create - constructor for TLazDockSplitter: calls inherited Create and initializes minimum size. - - - - Manager - the TCustomAnchoredDockManager for this Owner. - - - - TCustomAnchoredDockManager - implements an LCL TDockManager via anchoring. - -

- TCustomAnchoredDockManager - implements an LCL TDockManager via anchoring. It implements docking, undocking, enlarging, shrinking. The TCustomLazDockingManager component in LDockCtrl uses this docking manager and extends it by layouts that can be stored/restored. -

- - - - - FOwnerComponent - local variable to hold the TLazDockOwnerComponent for this manager. - - - - DeleteSideSplitter - removes a side splitter to make way for a NewAnchorControl with its anchors. - - - - CombineSpiralSplitterPair - cleans up alignment of two adjacent splitters when they don't line up properly. - -

- CombineSpiralSplitterPair - cleans up alignment of two adjacent splitters when they don't line up properly

- 
{  - Anchor all controls anchored to Splitter2 to Splitter1
-   - extend Splitter1
-   - delete Splitter2
-
-   Example:
-
-   Four spiral splitters:
-
-     Before:
-              |
-           A  |
-     ---------|
-       | +--+ |  C
-     B | |  | |
-       | +--+ |
-       | ----------
-       |   D
-
-     The left and right splitter will be combined to one.
-
-     After:
-              |
-           A  |
-       -------|
-              |  C
-            B |
-              |
-              |------
-              |   D
-  }
- - - - - DeletePage - removes the specified page from the notebook. - - - - DeletePages - removes the specified group of pages (notebook) from the Dock Form. - - - - DeleteDockForm - removes the specified dock form. - - - - GetAnchorDepth - returns the number of levels of anchoring associated with the given side of the nominated control. - - - - GetPreferredTitlePosition - returns the most favorable place (top or left side) to put the title of a dock component, given the width and height. - - + - TObject.Create - - - Create - constructor for TCustomAnchoredDockManager: creates the owner component and -initializes splitter size, title height and width. - - - - Destroy - destructor for TCustomAnchoredDockManager: frees and annuls the owner component the calls inherited Destroy. - - - TPersistent.Destroy + TCustomSplitter.Create - - - BeginUpdate - starts the update process by incrementing the update count. - - TDockManager.BeginUpdate - - - - - EndUpdate - ends update process by decrementing the update count. - If Update count is zero or less, raises and exception - - - - GetControlBounds - finds the bounding rectangle of the specified control. - - TDockManager.GetControlBounds - - - - - DisableLayout - placeholder for a virtual procedure to disable the layout of the specified control. - - - - EnableLayout - placeholder for a virtual procedure to enable the layout of the specified control. - - - - DockControl - docks the specified control with the Drop Control, using the alignment rule specified by InsertAt. - - - - - UndockControl - removes a control from a docking form. It breaks all anchors and cleans up. - -

- UndockControl - removes a control from a docking form. It breaks all anchors and cleans up. The created gap will be tried to fill up. It removes TLazDockSplitter, TLazDockPage and TLazDockPages if they are no longer needed. -

-

- Examples: -

-

- Search Order: -

-

- 1. A TLazDockSplitter dividing only two controls: -

- 
-     Before:
-     |-------------
-     | +--+ | +---
-     | |  | | | B
-     | +--+ | +---
-     |-------------
 
-     The splitter will be deleted and the right control will be anchored to the
-     left.
+      
+        
+        
+        
+      
 
-     After:
-     |-------------
-     | +---
-     | | B
-     | +---
-     |-------------
+      
+        
+        
+        
+      
 
-
-

- 2. Four spiral splitters: -

-
-     Before:
-              |
-           A  |
-     ---------|
-       | +--+ |  C
-     B | |  | |
-       | +--+ |
-       | ----------
-       |   D
+      
+        
+        
+        
+      
+      
+        
+      
+      
+        
+      
+      
+        
+      
+      
+        
+      
 
-     The left and right splitter will be combined to one.
+      
+        
+        
+        
+      
+      
+        
+      
+      
+        
+      
+      
+        
+      
+      
+        
+      
 
-     After:
-              |
-           A  |
-       -------|
-              |  C
-            B |
-              |
-              |------
-              |   D
-
-

- 3. No TLazDockSplitter. Control is the only child of a TLazDockPage In this case the page will be deleted. If the TLazDockPages has no children left, it is recursively undocked. -

-

- 4. No TLazDockSplitter, Control is the only child of a TLazDockForm. The TLazDockForm is deleted and the Control is floated. This normally means: A form will simply be placed on the desktop, other controls will be docked into their DockSite. -

-

- 5. Otherwise: this control was not docked. -

- - Raises an exception if the control is already undocked + + + + - - - InsertControl - calls DockControl to perform insertion. - - TCustomAnchoredDockManager.DockControl - TDockManager.InsertControl - + + - - - EnlargeControl - attempts to increase the size of the given control along the specified border, if necessary at the expense of neighboring controls. If Simulate=true then it will only test if control can be enlarged. + + - - - RemoveControl - calls UndockControl to remove the specified control from the docking hierarchy. - - TCustomAnchoredDockManager.UndockControl - TDockManager.RemoveControl - + + - - - ReplaceAnchoredControl - takes away OldControl, puts NewControl in its place, re-establishing all the docking, anchors and alignments. + + + + + - - - GetSplitterWidth - returns the value of the width of the splitter needed to control this docking process. + + - - - GetSplitterHeight - returns the value of the height of the splitter needed to control this docking processGetSplitterHeight - + + - - - SplitterSize - the size of splitter required for this docking process. + + - - - TitleWidth - the width of the title for this docking control. + + - - - TitleHeight - the height of the title for this docking control. + + + + + - - - UpdateTitlePosition - brings title position up to date, reflecting any pending changes. + + - - - PaintSite - (drawing of titles is is actually done by TLazDockForm). - - TLazDockForm.PaintWindow - TDockManager.PaintSite - + + - - - MessageHandler - not implemented. + + - - - PositionDockRect - not implemented. + + - - - ResetBounds - not implemented. + + + + + - - - SetReplacingControl - not implemented. + + - - - LoadFromStream - not implemented. + + - - - SaveToStream - not implemented. + + + + + - - - AutoFreeByControl - always returns False, overriding inherited value. - - TDockManager.AutoFreeByControl - + + - - - CreateForm - makes a form and sets up the dock manager. + + + + + + + + + + + + + + + + + +