contrib/docs/latex/fl/body.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        body.tex
   3 %% Purpose:     FL documenation
   4 %% Author:      wxWidgets Team
   5 %% Modified by:
   6 %% Created:
   7 %% RCS-ID:      $Id$
   8 %% Copyright:   (c) wxWidgets Team
   9 %% License:     wxWindows license
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \chapter{Introduction}\label{introduction}
  13 \pagenumbering{arabic}%
  14 \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
  15 \setfooter{\thepage}{}{}{}{}{\thepage}%
  16
  17 \section{What is FL?}\label{whatisfl}
  18
  19 This manual describes FL (Frame Layout), a
  20 class library for managing sophisticated window layout,
  21 with panes that can be moved around the main window
  22 and customized. FL handles many decoration and dragging
  23 issues, giving applications the kind of docking facilities
  24 that Visual C++ and Netscape Navigator possess.
  25
  26 FL was written by Aleksandras Gluchovas, and is heavily used in
  27 wxWorkshop which he also wrote the bulk of.
  28
  29 {\bf Please note} that this guide is in its infancy, and contributions
  30 from FL users are very welcome.
  31
  32 The following screenshot (from fl\_demo1) shows a frame with a number of
  33 bars that can be dragged around. The vertical grippers with
  34 two lines allow a bar to be dragged in that row, changing the
  35 ordering of the bar if necessary.
  36 The dotted grippers (as in Netscape Navigator) allow
  37 a whole row to be moved, again changing the position of the row
  38 if required. While moving a bar or row, immediate feedback
  39 is given as the moving bar displaces other bars.
  40
  41 Other features: the splitter bar shows a dotted thick line as
  42 it's dragged. Single-clicking on a row handle minimizes it to
  43 a horizontal tab which is given its own narrow row. This allows
  44 the user to temporarily hide a row while allowing quick access
  45 to it when required.
  46
  47 A close button (x) hides a bar completely. You can get it back again
  48 by right-clicking and selecting the appropriate menu item.
  49
  50 A left, right, up or down arrow button expands the pane in that direction.
  51
  52 \center{\image{}{screen01.bmp}}
  53
  54 \section{Compiling and using FL}
  55
  56 FL can be found under the 'contrib' hierarchy, in the following directories:
  57
  58 \begin{verbatim}
  59   contrib/src/fl
  60   contrib/include/wx/fl
  61   contrib/samples/fl
  62   contrib/docs/latex/fl
  63   docs/html/fl
  64   docs/htmlhelp/fl.chm
  65   docs/pdf/fl.pdf
  66   docs/winhelp/fl.hlp
  67 \end{verbatim}
  68
  69 To compile FL:
  70
  71 \begin{itemize}\itemsep=0pt
  72 \item Under Windows using VC++, open the flVC.dsw project
  73 and compile.
  74 \item Under Unix, FL should be configured when you configured
  75 wxWindows. Make FL by changing directory to contrib/src/fl and
  76 type 'make'. {\bf Note:} there is currently a
  77 problem with the wxWindows build system that means that
  78 only the static version of library can be built at present.
  79 \end{itemize}
  80
  81 To use FL:
  82
  83 \begin{itemize}\itemsep=0pt
  84 \item Under Windows using VC++, link with fl[d].lib.
  85 \item Under Unix, link with libfl[d].a.
  86 \end{itemize}
  87
  88 \section{FL concepts}
  89
  90 These are typical steps when adding FL functionality to your application.
  91
  92 \begin{itemize}\itemsep=0pt
  93 \item include the appropriate header files;
  94 \item create a new \helpref{wxFrameLayout}{wxframelayout} passing the top-level frame and the window that
  95 is interpreted as the main 'client' window;
  96 \item set an updates manager for optimizing drag operations;
  97 \item add plugins for implementing various features;
  98 \item add bars;
  99 \item enable floating mode for the layout if required;
 100 \item delete the frame layout in the main frame's destructor.
 101 \end{itemize}
 102
 103 The following is taken from fl\_demo1 and shows the main code implementing the
 104 user interface as illustrated in \helpref{What is FL?}{whatisfl}.
 105
 106 \begin{verbatim}
 107 // fl headers
 108 #include "wx/fl/controlbar.h"     // core API
 109
 110 // extra plugins
 111 #include "wx/fl/barhintspl.h"    // bevel for bars with "X"s and grooves
 112 #include "wx/fl/rowdragpl.h"     // NC-look with draggable rows
 113 #include "wx/fl/cbcustom.h"      // customization plugin
 114 #include "wx/fl/hintanimpl.h"
 115
 116 // beauty-care
 117 #include "wx/fl/gcupdatesmgr.h"  // smooth d&d
 118 #include "wx/fl/antiflickpl.h"   // double-buffered repaint of decorations
 119 #include "wx/fl/dyntbar.h"       // auto-layout toolbar
 120 #include "wx/fl/dyntbarhnd.h"    // control-bar dimension handler for it
 121
 122 MyFrame::MyFrame(wxFrame *frame)
 123     : wxFrame( frame, wxID_ANY, "wxWindows 2.0 wxFrameLayout Test Application", wxDefaultPosition,
 124           wxSize( 700, 500 ),
 125           wxCLIP_CHILDREN | wxMINIMIZE_BOX | wxMAXIMIZE_BOX |
 126           wxRESIZE_BORDER | wxSYSTEM_MENU  | wxCAPTION,
 127           "freimas" )
 128 {
 129     mpClientWnd = CreateTextCtrl( "Client window" );
 130
 131     mpLayout = new wxFrameLayout( this, mpClientWnd );
 132
 133     mpLayout->SetUpdatesManager( new cbGCUpdatesMgr() );
 134
 135     // setup plugins for testing
 136     mpLayout->PushDefaultPlugins();
 137
 138     mpLayout->AddPlugin( CLASSINFO( cbBarHintsPlugin ) ); // fancy "X"es and bevel for bars
 139     mpLayout->AddPlugin( CLASSINFO( cbHintAnimationPlugin ) );
 140     mpLayout->AddPlugin( CLASSINFO( cbRowDragPlugin  ) );
 141     mpLayout->AddPlugin( CLASSINFO( cbAntiflickerPlugin ) );
 142     mpLayout->AddPlugin( CLASSINFO( cbSimpleCustomizationPlugin ) );
 143
 144     // drop in some bars
 145     cbDimInfo sizes0( 200,45, // when docked horizontally
 146                       200,85, // when docked vertically
 147                       175,35, // when floated
 148                       FALSE,  // the bar is not fixed-size
 149                       4,      // vertical gap (bar border)
 150                       4       // horizontal gap (bar border)
 151                     );
 152
 153     cbDimInfo sizes1( 150,35, // when docked horizontally
 154                       150,85, // when docked vertically
 155                       175,35, // when floated
 156                       TRUE,   // the bar is not fixed-size
 157                       4,      // vertical gap (bar border)
 158                       4       // horizontal gap (bar border)
 159                     );
 160
 161     cbDimInfo sizes2( 175,45, // when docked horizontally
 162                       175,37, // when docked vertically
 163                       170,35, // when floated
 164                       TRUE,   // the bar is not fixed-size
 165                       4,      // vertical gap (bar border)
 166                       4,      // horizontal gap (bar border)
 167                       new cbDynToolBarDimHandler()
 168                     );
 169
 170     mpLayout->AddBar( CreateTextCtrl("Hello"),  // bar window
 171                       sizes0, FL_ALIGN_TOP,     // alignment ( 0-top,1-bottom, etc)
 172                       0,                        // insert into 0th row (vert. position)
 173                       0,                        // offset from the start of row (in pixels)
 174                       "InfoViewer1",            // name for reference in customization pop-ups
 175                       TRUE
 176                     );
 177
 178     mpLayout->AddBar( CreateTextCtrl("Bye"),    // bar window
 179                       sizes0, FL_ALIGN_TOP,     // alignment ( 0-top,1-bottom, etc)
 180                       1,                        // insert into 0th row (vert. position)
 181                       0,                        // offset from the start of row (in pixels)
 182                       "InfoViewer2",            // name for reference in customization pop-ups
 183                       TRUE
 184                     );
 185
 186     mpLayout->AddBar( CreateTextCtrl("Fixed0"), // bar window
 187                       sizes1, FL_ALIGN_TOP,     // alignment ( 0-top,1-bottom, etc)
 188                       0,                        // insert into 0th row (vert. position)
 189                       0,                        // offset from the start of row (in pixels)
 190                       "ToolBar1",               // name for reference in customization pop-ups
 191                       TRUE
 192                     );
 193
 194     wxDynamicToolBar* pToolBar = new wxDynamicToolBar();
 195
 196     pToolBar->Create( this, -1 );
 197
 198     // 1001-1006 ids of command events fired by added tool-buttons
 199
 200     pToolBar->AddTool( 1001, BMP_DIR "new.bmp" );
 201     pToolBar->AddTool( 1002, BMP_DIR "open.bmp" );
 202     pToolBar->AddTool( 1003, BMP_DIR "save.bmp" );
 203
 204     pToolBar->AddTool( 1004, BMP_DIR "cut.bmp" );
 205     pToolBar->AddTool( 1005, BMP_DIR "copy.bmp" );
 206     pToolBar->AddTool( 1006, BMP_DIR "paste.bmp" );
 207
 208     mpLayout->AddBar( pToolBar,             // bar window (can be NULL)
 209                       sizes2, FL_ALIGN_TOP, // alignment ( 0-top,1-bottom, etc)
 210                       0,                    // insert into 0th row (vert. position)
 211                       0,                    // offset from the start of row (in pixels)
 212                       "ToolBar2",           // name for reference in customization pop-ups
 213                       FALSE
 214                     );
 215
 216     mpLayout->EnableFloating( TRUE ); // off, thinking about wxGtk...
 217 }
 218
 219 MyFrame::~MyFrame()
 220 {
 221     if ( mpLayout)
 222         delete mpLayout; // should be destroyed manually
 223 }
 224 \end{verbatim}
 225
 226 \section{Controlling dragging behaviour}\label{controllingdragbehav}
 227
 228 Various pane-dragging behaviours are supported. FL can
 229 show an outline of where the window would be docked
 230 if you stopped dragging at that point.
 231
 232 This is a list of properties of interest in the cbCommonPaneProperties
 233 structure:
 234
 235 \begin{verbatim}
 236     bool mRealTimeUpdatesOn;     // default: ON
 237     bool mOutOfPaneDragOn;       // default: ON
 238     bool mExactDockPredictionOn; // default: OFF
 239     bool mNonDestructFrictionOn; // default: OFF
 240 \end{verbatim}
 241
 242 To get behaviour similar to Microsoft's DevStudio drag-ghost behaviour,
 243 mRealTimeUpdatesOn have to be set to FALSE, for example:
 244
 245 \begin{verbatim}
 246     cbCommonPaneProperties props;
 247     ....
 248     ....
 249     props.mRealTimeUpdatesOn = FALSE;
 250     fl->SetPaneProperties( props, wxALL_PANES );
 251 \end{verbatim}
 252
 253 {\it mOutOfPaneDragOn} specifies whether bars can be dragged
 254 away from this pane. (Note: this may not currently be working.)
 255
 256 {\it mExactDockPredictionOn} is only relevant when {\it mRealTimeUpdatesOn} is FALSE,
 257 and then the hint rectangle behaves a little jumpily. It tries to show
 258 exatly how the bar would look and where it would be docked if the dragging finished right
 259 now, i.e. the final position, with all the 'friction-physics' calculated.
 260 Otherwise the hint flies smothly above the surface only hinting whether the bar
 261 will be docked vertically or horizontally if dropped now.
 262 This is a feature you won't find anywhere else!
 263
 264 {\it mNonDestructFirctionOn} causes the bars not being dragged
 265 to stay where they are, while the currently dragged one is 'diving'
 266 through the underlaying panes, docking itself in and out in real time.
 267 Otherwise the stationary bars would be pushed around messing up the composition permanently.
 268 This flag is irelevant when {\it mRealTimeUpdatesOn} is FALSE, as the ghost-rect
 269 does not do any docking until the drag finishes.