contrib/docs/latex/fl/body.tex

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