paweld/lazarus
1
0
Fork 0
mirror of https://gitlab.com/freepascal.org/lazarus/lazarus.git synced 2025-04-24 00:27:06 +02:00
Code Issues Packages Projects Releases Wiki Activity

dockmanager example: added docs

Browse Source 
git-svn-id: trunk@25589 -
This commit is contained in:
dodi 2010-05-23 11:43:11 +00:00
parent f1aac744eb
commit 3a84a0a1c0
9 changed files with 283 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.gitattributes vendored
View File

@ -2854,6 +2854,10 @@ examples/docking/unit1.lfm svneol=native#text/plain
examples/docking/unit1.lrs svneol=native#text/pascal
examples/docking/unit1.pas svneol=native#text/pascal
examples/dockmanager/README.txt svneol=native#text/plain
examples/dockmanager/docs/easydocksite.xml svneol=LF#text/xml eol=lf
examples/dockmanager/docs/fdockbook.xml svneol=LF#text/xml eol=lf
examples/dockmanager/docs/ffloatingsite.xml svneol=LF#text/xml eol=lf
examples/dockmanager/docs/umakesite.xml svneol=LF#text/xml eol=lf
examples/dockmanager/easyedit/easyeditor.lpi svneol=native#text/plain
examples/dockmanager/easyedit/easyeditor.lpr svneol=native#text/plain
examples/dockmanager/easyedit/easyeditor.lrs svneol=native#text/plain

121
examples/dockmanager/docs/easydocksite.xml Normal file
View File

@ -0,0 +1,121 @@
<?xml version="1.0"?>
<fpdoc-descriptions>
<package name="EasyDockMgr">
<module name="EasyDockSite">
<element name="TEasyDockManager">
<short>A docking manager base class, implementing some default functionality.</short>
</element>
<element name="TCustomDockMaster">
<short>The DockMaster base class, managing docking and screen layout issues in an application.</short>
<descr>
<p>The global DockLoader variable represents the installed DockMaster singleton.</p>
<p>It provides means to make forms dockable on all platforms (MakeDockable), and to save and reload screen layouts.</p>
</descr>
</element>
<element name="TCustomDockMaster.TryCreateControls">
<short>Indicates whether the DockMaster should try to create docked controls himself, when a layout is restored.</short>
</element>
<element name="TCustomDockMaster.MakeDockable">
<short>Makes a form dockable, on all platforms.</short>
<descr>
<p>All docking-related properties of the given form are set to appropriate values.</p>
<p>fWrap indicates whether the form shall be wrapped into a FloatHost site. The Result is that FloatHost form, always Nil in the default implementation.</p>
<p>fVisible indicates whether the form shall be made visible immediately. Leave the form invisible when otherwise further customization would cause the form to flicker.</p>
</descr>
</element>
<element name="TCustomDockMaster.SaveControl">
<short>Returns an string, containing all required information for reloading the control later.</short>
<descr>
<p>The content of the string is not restricted in any way, it only must be understood by ReloadControl.</p>
<p>
<ol>
<li>When the control is a TCustomDockSite, its SaveSite method can provide the string;</li>
<li>else an installed AppLoadStore callback can provide the string;</li>
<li>else an OnSave handler can provide the string.</li>
<li>When no string has been provided so far, a default control-descriptor string is created.</li>
</ol>
</p>
</descr>
</element>
<element name="TCustomDockMaster.ReloadControl">
<short>Provides a docked control when a layout is restored.</short>
<descr>
<p>The descriptor string is parsed into ControlDescriptor, accessible to the subsequently called procedures.</p>
<p>
<ol>
<li>When the string begins with a CustomDockSiteID, it is passed to TCustomDockSite.ReloadSite.</li>
<li>Else an AppLoadStore or OnRestore handler is invoked, if installed.</li>
<li>When no control has been provided, FindOwnedComponent is invoked.</li>
<li>When TryCreateControls is True, the control is created from its registered ClassName.</li>
<li>As a last resort the site.ReloadDockedControl is invoked.</li>
</ol>
</p>
</descr>
</element>
<element name="TCustomDockMaster.OnSave">
<short>Application handler for SaveControl.</short>
</element>
<element name="TCustomDockMaster.OnRestore">
<short>Application handler for ReloadControl.</short>
</element>
<element name="TCustomDockMaster.ControlDescriptor">
<short>Descriptor of the control, that currently shall be restored.</short>
</element>
<element name="TCustomDockSite">
<short>A general persistent docksite.</short>
</element>
<element name="TCustomDockSite.ReloadSite">
<short>Restores a docksite from its description.</short>
<descr>This is a class function, because it will create and return a new docksite.</descr>
</element>
<element name="TCustomDockSite.SaveSite">
<short>Returns the docksite descriptor as a string.</short>
<descr>The string begins with the CustomDockSiteID, to distinguish a docksite from any other docked control. The rest is added by SaveToStream.</descr>
</element>
<element name="TCustomDockSite.LoadFromStream">
<short>Reloads the docked controls from a stream.</short>
<descr>
<p>The DockManager is asked to restore the docked controls.</p>
<p>Unmanaged docksites must overwrite this method, to process their own descriptor string.</p>
</descr>
</element>
<element name="TCustomDockSite.SaveToStream">
<short>Saves the docksite description to the stream.</short>
<descr>
<p>The description actually is saved by the DockManager.</p>
<p>Unmanaged docksites must overwrite this method, to provide their own descriptor string.</p>
</descr>
</element>
<element name="CustomDockSiteID">
<short>The marker for an docksite layout descriptor.</short>
<descr>
<p>This marker is used in layout descriptor strings, to distinguish docksites from other controls.</p>
<p>Default descriptor strings start with the control name, so that values in the range 2..32 can be used as markers for special docksites, like custom docksites (1) or notebooks (2). These non-standard markers must be handled by application specific loaders, e.g. DockMaster.OnRestore handlers.</p>
</descr>
</element>
<element name="TOnReloadControl">
<short>Event handler type for the DockMaster OnReload event.</short>
<descr>
<p>The handler creates the docked control from the descriptor in AName.</p>
<p>AOwner is the default owner for the new control.</p>
<p>When the handler returns Nil, the DockMaster tries to create the control by default procedures. I.e. an application specific handler must only handle non-standard situations.</p>
</descr>
</element>
<element name="TOnSaveControl">
<short>Event handler type for the DockMaster OnSave event.</short>
<descr>
<p>The handler must handle all non-standard situations, when a specific control requires special construction or configuration. When an empty string is returned, the DockMaster creates an standard descriptor for the control.</p>
<p>The result is a descriptor string, that is passed to the OnReload handler when the layout is restored later. It's suggested to prefix the string with a special marker byte, in the range 3..32.</p>
</descr>
<seealso>
<link id="CustomDockSiteID"/>
<link id="TOnReloadControl"/>
</seealso>
</element>
<element name="TDockSiteClass">
<short>Class type of a persistent docksite.</short>
<descr>Docksites derived from this type are handled automatically be the DockMaster, when a docking layout is saved and reloaded.</descr>
</element>
</module>
</package>
</fpdoc-descriptions>

20
examples/dockmanager/docs/fdockbook.xml Normal file
View File

@ -0,0 +1,20 @@
<?xml version="1.0"?>
<fpdoc-descriptions>
<package name="EasyDockMgr">
<module name="fDockBook">
<element name="TEasyDockBook">
<short>The default docking notebook.</short>
</element>
<element name="TEasyDockBook.Clear">
<short>Handle removal of all docked clients, on destruction.</short>
<descr>When the notebook is destroyed, the remaining docked clients are made visible.</descr>
</element>
<element name="TEasyDockBook.LoadFromStream">
<short>Reloads all docked pages.</short>
</element>
<element name="TEasyDockBook.SaveToStream">
<short>Saves the current layout.</short>
</element>
</module>
</package>
</fpdoc-descriptions>

30
examples/dockmanager/docs/ffloatingsite.xml Normal file
View File

@ -0,0 +1,30 @@
<?xml version="1.0"?>
<fpdoc-descriptions>
<package name="EasyDockMgr">
<module name="fFloatingSite">
<element name="TFloatingSite">
<short>The default floathost site, used by the DockMaster.</short>
</element>
<element name="TFloatingSite.FormClose">
<short>When the form is closed, all docked clients are undocked and hidden.</short>
</element>
<element name="TFloatingSite.FormDockDrop">
<short>When a control is docked, the Caption is updated accordingly.</short>
</element>
<element name="TFloatingSite.FormUnDock">
<short>Destroys the form on undock of the last client.</short>
</element>
<element name="TFloatingSite.Loaded">
<short>Installs and configures the DockManager.</short>
<descr>
<p>Unless configured otherwise, an EasyTree dockmanager is installed.</p>
<p>HideSingleHeader determines whether a dockheader for a single docked control is shown.</p>
<p>HeaderStyle determines the dockheader style.</p>
</descr>
</element>
<element name="TFloatingSite.UpdateCaption">
<short>Shows the DockCaptions of all the docked controls.</short>
</element>
</module>
</package>
</fpdoc-descriptions>

91
examples/dockmanager/docs/umakesite.xml Normal file
View File

@ -0,0 +1,91 @@
<?xml version="1.0"?>
<fpdoc-descriptions>
<package name="EasyDockMgr">
<module name="uMakeSite">
<element name="TDockMaster">
<short>A DockMaster with extended capabilities, ready for use in any application.</short>
<descr>
<p>This DockMaster allows to make forms dockable, and to add elastic docksites to forms. It defines the event handlers, installed in such controls.</p>
</descr>
</element>
<element name="TDockMaster.FormEndDock">
<short>OnEndDock handler for dockable forms.</short>
<descr>
<p>This handler immediately wraps a floating form into a floathost site, to keep it dockable on all platforms.</p>
</descr>
</element>
<element name="TDockMaster.ReloadForm">
<short>Reload a dockable form from an layout descriptor.</short>
<descr>
<p>When a form of the given name already exists on the Screen, all other parameters are ignored and this form is returned.</p>
<p>Otherwise the Factory is asked to provide the requested form.</p>
<p>When no form has been retrieved so far, AName is assumed to contain an standard form name, from which the form can be created. An eventually existing instance number is stripped from AName, and the result is prefixed by an 'T' for the classname of the form. This ClassName must have been registered, otherwise no form can be created. The new form is named as AName.</p>
<p>When AName is the empty string, a default form is created (for demonstration/debugging purposes).</p>
<p>When fVisible is True, the new form is made visible immediately.</p>
</descr>
</element>
<element name="TDockMaster.Factory">
<short>The default owner of all dockable forms.</short>
<descr>
<p>When not Nil, the Factory is asked to reload a form.</p>
</descr>
</element>
<element name="TDockMaster.ForIDE">
<short>An experimental switch, intended to make the DockMaster work for the Lazarus IDE.</short>
</element>
<element name="TDockMaster.WrapDockable">
<short>Internal function to wrap a floating form into a floathost site.</short>
</element>
<element name="TDockMaster.Create">
<short>This constructor installs the DockMaster singleton.</short>
</element>
<element name="DockMaster">
<short>The enhanced DockMaster singleton, otherwise same as DockLoader (retyped).</short>
</element>
<element name="TDockMaster.AddElasticSites">
<short>Adds elastic docksites to a form.</short>
<descr>
<p>Elastic docksites are normally invisible panels, that enlarge as soon as someting is docked into them. The user can make the form grow accordingly, so that the docked control looks like attached to the form - depending on where exactly the control is docked.</p>
<p>Elastic docksites are persistent, i.e. are saved and restored together with a screen layout.</p>
<p>Sides is the set of form sides, on which elastic sites shall be added.</p>
<p>Elastic sites should not be added to dockable forms, else docking into docked forms may cause trouble.</p>
</descr>
</element>
<element name="TDockMaster.CreateDockable">
<short>Creates a dockable form from its name.</short>
<descr>The form is created by <link id="TDockMaster.ReloadForm">ReloadForm</link>, then made dockable by <link id="TDockMaster.MakeDockable">MakeDockable</link>
</descr>
</element>
<element name="TDockMaster.MakeDockable">
<short>Make a control dockable.</short>
<descr>
<p>The control (typically a form) is made dockable on all platforms.</p>
<p>fWrap indicates that the control shall have a floathost site (required on most platforms).</p>
<p>fVisible indicates whether the control shall be made visible. Leave False when otherwise flicker will occur.</p>
</descr>
</element>
<element name="TDockMaster.DumpSites">
<short>Debug feature for console applications.</short>
</element>
<element name="TDockMaster.LoadFromStream">
<short>Reloads a layout from a stream.</short>
</element>
<element name="TDockMaster.SaveToStream">
<short>Saves the current screen layout to a stream.</short>
</element>
<element name="TDockMaster.ReloadDockedControl">
<short>Reloads a docked control from its descriptor string.</short>
<descr>
<p>First a form of the given name is searched on Screen, before <link id="easydocksite.TCustomDockMaster.ReloadControl">ReloadControl</link> is tried.</p>
<p>When nothing has been reloaded, and TryCreateControls is True, then a form is created by <link id="TDockMaster.ReloadForm">ReloadForm</link>.</p>
</descr>
</element>
<element name="TDockMaster.LoadFromFile">
<short>Restores a screen layout from a file.</short>
</element>
<element name="TDockMaster.SaveToFile">
<short>Saves the current screen layout as an file.</short>
</element>
</module>
</package>
</fpdoc-descriptions>

5
examples/dockmanager/package/easydocksite.pas
View File

@ -273,7 +273,7 @@ type
TOnReloadControl = function(const CtrlName: string; ASite: TWinControl): TControl of object;
TOnSaveControl = function(ACtrl: TControl): string of object;
(* TDockMaster base class, contains function for layout save/load controls.
(* TDockMaster base class, contains functions for layout save/load controls.
The default implementation is for use by both a DockManager and a (unmanaged) DockSite.
Unless overridden, it handles in this sequence:
1) TCustomDockSite (notebooks...)
@ -284,8 +284,7 @@ type
Customization is provided by OnSave/Restore handlers.
Further customization is feasable using the AppLoadStore variable (below).
At the time of an call, DockLoader contains the full control description
(ControlDescriptor)
At the time of an call, ControlDescriptor holds the full control description.
The DockLoader variable is initialized to a default TCustomDockMaster instance,
owned by Application. It can be overridden by the application.

6
examples/dockmanager/package/fdockbook.pas
View File

@ -224,7 +224,10 @@ end;
procedure TEasyDockBook.DoAddDockClient(Client: TControl; const ARect: TRect);
begin
if False then inherited DoAddDockClient(Client, ARect);
(* Make the docked client visible in our dedicated panel.
It seemed to be necessary to separate this from the OnDockDrop handler?
*)
//if False then inherited DoAddDockClient(Client, ARect);
Client.Parent := pnlDock;
end;
@ -233,7 +236,6 @@ procedure TEasyDockBook.FormDockDrop(Sender: TObject; Source: TDragDockObject;
var
btn: TTabButton;
begin
{ TODO : set Parent in DoAddDockClient }
//Source.Control.Parent := pnlDock; //overwrite DoAddDockClient behaviour???
btn := TTabButton.Create(Tabs);

8
examples/dockmanager/package/ffloatingsite.pas
View File

@ -138,10 +138,10 @@ begin
(* Check for undock last client, if allowed kill empty docksite.
Refresh caption after undock.
Shit: in both cases the docking management does the opposite of what it should do :-(
When the last control is dragged away, it's hosted in a *new* site.
When a second control is dragged away, the entire site is moved.
Shit: in both cases the docking management does the opposite of what it should do:
When the last control is dragged away, it's hosted in a *new* site.
When a second control is dragged away, the entire site is moved.
:-(
Fix: disallow TControls to become floating.
*)

8
examples/dockmanager/package/umakesite.pas
View File

@ -25,7 +25,8 @@ Default floating sites are owned by Application,
{$DEFINE ownPanels} //elastic panels owned by DockMaster?
{.$DEFINE appDockMgr} //using special AppDockManager?
{.$DEFINE NeedHost} //request float host?
{.$DEFINE NeedHost} //request float host?
{.$DEFINE TestForm} //enable special debug form
interface
@ -112,6 +113,7 @@ type
TWinControlAccess = class(TWinControl) end;
TControlAccess = class(TControl) end;
{$IFDEF TestForm}
{ TExampleForm }
TExampleForm = class(TForm)
@ -134,6 +136,10 @@ begin
LineTo(ClientWidth-1,ClientHeight-1);
end;
end;
{$ELSE}
type
TExampleForm = TForm;
{$ENDIF}
{ TDockMaster }