X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/499b2ed82caa62ec19b400c31aa26be33b1c02d4..c82be69b51b8f8aabb5bd667b063dba399c6d894:/contrib/docs/latex/fl/body.tex

diff --git a/contrib/docs/latex/fl/body.tex b/contrib/docs/latex/fl/body.tex
index 9918813326..0d3cac65f1 100644
--- a/contrib/docs/latex/fl/body.tex
+++ b/contrib/docs/latex/fl/body.tex
@@ -3,9 +3,257 @@
 \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
 \setfooter{\thepage}{}{}{}{}{\thepage}%
 
-\section{What is FL?}
+\section{What is FL?}\label{whatisfl}
 
 This manual describes FL (Frame Layout), a
 class library for managing sophisticated window layout,
-including docking panes.
+with panes that can be moved around the main window
+and customized. FL handles many decoration and dragging
+issues, giving applications the kind of docking facilities
+that Visual C++ and Netscape Navigator possess.
+
+FL was written by Aleksandras Gluchovas, and is heavily used in
+wxWorkshop which he also wrote the bulk of.
+
+{\bf Please note} that this guide is in its infancy, and contributions
+from FL users are very welcome.
+
+The following screenshot (from fl\_demo1) shows a frame with a number of
+bars that can be dragged around. The vertical grippers with
+two lines allow a bar to be dragged in that row, changing the
+ordering of the bar if necessary.
+The dotted grippers (as in Netscape Navigator) allow
+a whole row to be moved, again changing the position of the row
+if required. While moving a bar or row, immediate feedback
+is given as the moving bar displaces other bars.
+
+Other features: the splitter bar shows a dotted thick line as
+it's dragged. Single-clicking on a row handle minimizes it to
+a horizontal tab which is given its own narrow row. This allows
+the user to temporarily hide a row whilst allowing quick access
+to it when required.
+
+A close button (x) hides a bar completely. You can get it back again
+by right-clicking and selecting the appropriate menu item.
+
+A left, right, up or down arrow button expands the pane in that direction.
+
+\center{\image{}{screen01.bmp}}
+
+\section{Compiling and using FL}
+
+FL can be found under the 'contrib' hierarchy, in the following directories:
+
+\begin{verbatim}
+  contrib/src/fl
+  contrib/include/wx/fl
+  contrib/samples/fl
+  contrib/docs/latex/fl
+  docs/html/fl
+  docs/htmlhelp/fl.chm
+  docs/pdf/fl.pdf
+  docs/winhelp/fl.hlp
+\end{verbatim}
+
+To compile FL:
+
+\begin{itemize}\itemsep=0pt
+\item Under Windows using VC++, open the flVC.dsw project
+and compile.
+\item Under Unix, FL should be configured when you configured
+wxWindows. Make FL by changing directory to contrib/src/fl and
+type 'make'. {\bf Note:} there is currently a
+problem with the wxWindows build system that means that
+only the static version of library can be built at present.
+\end{itemize}
+
+To use FL:
+
+\begin{itemize}\itemsep=0pt
+\item Under Windows using VC++, link with fl[d].lib.
+\item Under Unix, link with libfl[d].a.
+\end{itemize}
+
+\section{FL concepts}
+
+These are typical steps when adding FL functionality to your application.
+
+\begin{itemize}\itemsep=0pt
+\item include the appropriate header files;
+\item create a new \helpref{wxFrameLayout}{wxframelayout} passing the top-level frame and the window that
+is interpreted as the main 'client' window;
+\item set an updates manager for optimizing drag operations;
+\item add plugins for implementing various features;
+\item add bars;
+\item enable floating mode for the layout if required;
+\item delete the frame layout in the main frame's destructor.
+\end{itemize}
+
+The following is taken from fl\_demo1 and shows the main code implementing the
+user interface as illustrated in \helpref{What is FL?}{whatisfl}.
+
+\begin{verbatim}
+// fl headers
+#include "wx/fl/controlbar.h"     // core API
+
+// extra plugins
+#include "wx/fl/barhintspl.h"    // bevel for bars with "X"s and grooves
+#include "wx/fl/rowdragpl.h"     // NC-look with draggable rows
+#include "wx/fl/cbcustom.h"      // customization plugin
+#include "wx/fl/hintanimpl.h"
+
+// beauty-care
+#include "wx/fl/gcupdatesmgr.h"  // smooth d&d
+#include "wx/fl/antiflickpl.h"   // double-buffered repaint of decorations
+#include "wx/fl/dyntbar.h"       // auto-layout toolbar
+#include "wx/fl/dyntbarhnd.h"    // control-bar dimension handler for it
+
+MyFrame::MyFrame(wxFrame *frame)
+    : wxFrame( frame, -1, "wxWindows 2.0 wxFrameLayout Test Application", wxDefaultPosition, 
+          wxSize( 700, 500 ), 
+          wxCLIP_CHILDREN | wxMINIMIZE_BOX | wxMAXIMIZE_BOX | 
+          wxTHICK_FRAME   | wxSYSTEM_MENU  | wxCAPTION, 
+          "freimas" )
+{
+    mpClientWnd = CreateTextCtrl( "Client window" );
+    
+    mpLayout = new wxFrameLayout( this, mpClientWnd );
+    
+    mpLayout->SetUpdatesManager( new cbGCUpdatesMgr() );
+    
+    // setup plugins for testing
+    mpLayout->PushDefaultPlugins();
+    
+    mpLayout->AddPlugin( CLASSINFO( cbBarHintsPlugin ) ); // fancy "X"es and bevel for bars
+    mpLayout->AddPlugin( CLASSINFO( cbHintAnimationPlugin ) );
+    mpLayout->AddPlugin( CLASSINFO( cbRowDragPlugin  ) );
+    mpLayout->AddPlugin( CLASSINFO( cbAntiflickerPlugin ) );
+    mpLayout->AddPlugin( CLASSINFO( cbSimpleCustomizationPlugin ) );
+    
+    // drop in some bars
+    cbDimInfo sizes0( 200,45, // when docked horizontally      
+                      200,85, // when docked vertically        
+                      175,35, // when floated                  
+                      FALSE,  // the bar is not fixed-size
+                      4,      // vertical gap (bar border)
+                      4       // horizontal gap (bar border)
+                    ); 
+    
+    cbDimInfo sizes1( 150,35, // when docked horizontally      
+                      150,85, // when docked vertically        
+                      175,35, // when floated                  
+                      TRUE,   // the bar is not fixed-size
+                      4,      // vertical gap (bar border)
+                      4       // horizontal gap (bar border)
+                    ); 
+    
+    cbDimInfo sizes2( 175,45, // when docked horizontally      
+                      175,37, // when docked vertically        
+                      170,35, // when floated                  
+                      TRUE,   // the bar is not fixed-size
+                      4,      // vertical gap (bar border)
+                      4,      // horizontal gap (bar border)
+                      new cbDynToolBarDimHandler()
+                    ); 
+    
+    mpLayout->AddBar( CreateTextCtrl("Hello"),  // bar window
+                      sizes0, FL_ALIGN_TOP,     // alignment ( 0-top,1-bottom, etc)
+                      0,                        // insert into 0th row (vert. position)
+                      0,                        // offset from the start of row (in pixels)
+                      "InfoViewer1",            // name for reference in customization pop-ups
+                      TRUE
+                    );
+    
+    mpLayout->AddBar( CreateTextCtrl("Bye"),    // bar window
+                      sizes0, FL_ALIGN_TOP,     // alignment ( 0-top,1-bottom, etc)
+                      1,                        // insert into 0th row (vert. position)
+                      0,                        // offset from the start of row (in pixels)
+                      "InfoViewer2",            // name for reference in customization pop-ups
+                      TRUE
+                    );
+    
+    mpLayout->AddBar( CreateTextCtrl("Fixed0"), // bar window
+                      sizes1, FL_ALIGN_TOP,     // alignment ( 0-top,1-bottom, etc)
+                      0,                        // insert into 0th row (vert. position)
+                      0,                        // offset from the start of row (in pixels)
+                      "ToolBar1",               // name for reference in customization pop-ups
+                      TRUE
+                    );
+    
+    wxDynamicToolBar* pToolBar = new wxDynamicToolBar();
+    
+    pToolBar->Create( this, -1 );
+    
+    // 1001-1006 ids of command events fired by added tool-buttons
+    
+    pToolBar->AddTool( 1001, BMP_DIR "new.bmp" );
+    pToolBar->AddTool( 1002, BMP_DIR "open.bmp" );
+    pToolBar->AddTool( 1003, BMP_DIR "save.bmp" );
+    
+    pToolBar->AddTool( 1004, BMP_DIR "cut.bmp" );
+    pToolBar->AddTool( 1005, BMP_DIR "copy.bmp" );
+    pToolBar->AddTool( 1006, BMP_DIR "paste.bmp" );   
+    
+    mpLayout->AddBar( pToolBar,             // bar window (can be NULL)
+                      sizes2, FL_ALIGN_TOP, // alignment ( 0-top,1-bottom, etc)
+                      0,                    // insert into 0th row (vert. position)
+                      0,                    // offset from the start of row (in pixels)
+                      "ToolBar2",           // name for reference in customization pop-ups
+                      FALSE
+                    );
+    
+    mpLayout->EnableFloating( TRUE ); // off, thinking about wxGtk...
+}
+
+MyFrame::~MyFrame()
+{
+    if ( mpLayout) 
+        delete mpLayout; // should be destroyed manually
+}
+\end{verbatim}
+
+\section{Controlling dragging behaviour}\label{controllingdragbehav}
+
+Various pane-dragging behaviours are supported. FL can
+show an outline of where the window would be docked
+if you stopped dragging at that point.
+
+This is a list of properties of interest in the cbCommonPaneProperties
+structure:
+
+\begin{verbatim}
+    bool mRealTimeUpdatesOn;     // default: ON
+    bool mOutOfPaneDragOn;       // default: ON
+    bool mExactDockPredictionOn; // default: OFF
+    bool mNonDestructFrictionOn; // default: OFF
+\end{verbatim}
+
+To get behaviour similar to Microsoft's DevStudio drag-ghost behaviour,
+mRealTimeUpdatesOn have to be set to FALSE, for example:
+
+\begin{verbatim}
+    cbCommonPaneProperties props;
+    ....
+    ....
+    props.mRealTimeUpdatesOn = FALSE;
+    fl->SetPaneProperties( props, wxALL_PANES );
+\end{verbatim}
+
+{\it mOutOfPaneDragOn} specifies whether bars can be dragged
+away from this pane. (Note: this may not currently be working.)
+
+{\it mExactDockPredictionOn} is only relevant when {\it mRealTimeUpdatesOn} is FALSE,
+and then the hint rectangle behaves a little jumpily. It tries to show
+exatly how the bar would look and where it would be docked if the dragging finished right
+now, i.e. the final position, with all the 'friction-physics' calculated.
+Otherwise the hint flies smothly above the surface only hinting whether the bar
+will be docked vertically or horizontally if dropped now.
+This is a feature you won't find anywhere else!
+
+{\it mNonDestructFirctionOn} causes the bars not being dragged
+to stay where they are, while the currently dragged one is 'diving'
+through the underlaying panes, docking itself in and out in real time.
+Otherwise the stationary bars would be pushed around messing up the composition permanently.
+This flag is irelevant when {\it mRealTimeUpdatesOn} is FALSE, as the ghost-rect
+does not do any docking until the drag finishes.
 
