X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/499b2ed82caa62ec19b400c31aa26be33b1c02d4..6ed506b9d7ef628ec7f924bc9bf50d112e19f271:/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.