wxWidgets/contrib/docs/latex/fl/body.tex

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Name:        body.tex
%% Purpose:     FL documenation
%% Author:      wxWidgets Team
%% Modified by:
%% Created:
%% RCS-ID:      $Id$
%% Copyright:   (c) wxWidgets Team
%% License:     wxWindows license
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\chapter{Introduction}\label{introduction}
\pagenumbering{arabic}%
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

\section{What is FL?}\label{whatisfl}

This manual describes FL (Frame Layout), a
class library for managing sophisticated window layout,
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 while 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, wxID_ANY, "wxWindows 2.0 wxFrameLayout Test Application", wxDefaultPosition,
          wxSize( 700, 500 ),
          wxCLIP_CHILDREN | wxMINIMIZE_BOX | wxMAXIMIZE_BOX |
          wxRESIZE_BORDER | 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.