From e5289a924ce49b528cb05228855662b77dc33e88 Mon Sep 17 00:00:00 2001 From: kirkpatc Date: Mon, 10 Aug 2009 18:10:21 +0000 Subject: [PATCH] FPDoc - descriptions have been added for the classes in LDockTree git-svn-id: trunk@21160 - --- docs/xml/lcl/ldocktree.xml | 733 ++++++++++++++++++++++++++++++++++--- 1 file changed, 673 insertions(+), 60 deletions(-) diff --git a/docs/xml/lcl/ldocktree.xml b/docs/xml/lcl/ldocktree.xml index 33cd92648e..d378a0bbc3 100644 --- a/docs/xml/lcl/ldocktree.xml +++ b/docs/xml/lcl/ldocktree.xml @@ -7,7 +7,7 @@ ==================================================================== --> - + This unit defines TLazDockTree, the default TDockTree for the LCL @@ -47,28 +47,34 @@ - + + TLazDockPages a notebook in which each page is a TLazDockPage + - + + TLazDockPage - an entity similar to a TLazDockForm, but forming a page in a notebook of TLazDockPages + - + + TLazDockSplitter - a spltter used with Lazarus Docking components - + + TLazDockZone - a zone for docking in a Lazarus form @@ -93,50 +99,59 @@ - + + Destroy - destructor for TLazDockZone; frees subcomponents then calls inherited Destroy + - + + 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 - + + + - + The Splitter to be use to control the docking of this Zone - + The Pages (as in a Notebook) included in the dock zone - + A Page in the Notebook included in the Dock Zone - + + TLazDockTree - a tree of TLazDockZones found in a docked window @@ -149,91 +164,170 @@ - + + UndockControlForDocking - frees anchors from parent and sibling controls - + + + - + + 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 - + + + - + + AnchorDockLayout - sets up anchors between all docked controls and helper controls - + + + - + + 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 + - - + + 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.
+  It automatically changes the tree, so that the parent of the new TDockZone
+  will have the Orientation for InsertAt.
+
+  Example 1:
+
+    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)
+ - + + + - + + + - + + + - + + 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 + - + + + - + + + - + + + @@ -242,36 +336,59 @@ - + + + - + + + - + + + - + + GetAnchorControl - find a control to anchor the Zone's Side - + + + - + + + - + + + - + + + - + + AutoFreeDockSite - determines whether the dock site is free - - + + TLazDockForm - the default DockSite for a TLazDockTree and for TCustomAnchoredDockManager + +

+ TLazDockForm - the default DockSite for a TLazDockTree and for TCustomAnchoredDockManager

+ 
Note: There are two docking managers:
+      TLazDockTree uses TLazDockZone to allow docking in rows and columns.
+      TCustomAnchoredDockManager does not use TLazDockZone and allows arbitrary layouts.
+ @@ -320,13 +437,13 @@ - + The DockZone in which this page is located - + The PageControl or notebook in which this page is located (its parent) @@ -345,7 +462,9 @@ - + + + @@ -354,9 +473,13 @@ - + + + - + + + @@ -365,32 +488,44 @@ - + + + - + + Create - constructor for TLazDockPages: sets PageClass as TLazDockPage, then calls inherited Create + - + + TCustomNotebook.Create + - + + + - + + Page - an individual TLazDockPage in the notebook, referred by its Index + - + + + - + - + @@ -408,6 +543,484 @@ + + + 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 MouseDpwn, 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 recognise the presence of MainControl + + + + FindMainControlCandidate - finds forms and controls in the docktree heirarchy 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 greter than zero + + + + GetTitleRect - returns the coordinates of the title retangle for the nominated control + + + + GetTitleOrientation - retrns the orientation (horizozntal 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 recognise the MainControl + + + TWinControl.InsertControl + + + + + GetFloatingDockSiteClass - returns a default class of TLazDockForm, overriding the inherited value + + TControl.GetFloatingDockSiteClass + + + + + Change - calls inherited method, then ensures that all parents recognise MainControl + + TCustomNotebook.Change + + + + + Create - constructor for TLazDockSplitter: calls inherited Create and initialises minimum size + + TCustomSplitter.Create + + + + + TLazDockOwnerComponent - A TComponent owning all automatically created controls of a TCustomAnchoredDockManager, like TLazDockForm + + + + + 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 favourable 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 initialises splitter size, title height and width + + + + Destroy - destructor for TCustomAnchoredDockManager: frees and annuls the owner component the calls inherited Destroy + + + TPersistent.Destroy + + + + + BeginUpdate - starts the update process by incrementing the update count + + TDockManager.BeginUpdate + + + + + EndUpdate - ends update process by decreenting 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 - laceholder 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 childs 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 neighbouring 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 heirarchy + + 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 cotrol + + + + 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 +