1c067fe3c1
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@38477 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
270 lines
10 KiB
TeX
270 lines
10 KiB
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.
|