]> git.saurik.com Git - wxWidgets.git/blob - contrib/docs/latex/fl/body.tex
test undividable words
[wxWidgets.git] / 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 whilst 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