]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/splitter.tex
ugh. Nesting the (per class) plugin sentries can require them to
[wxWidgets.git] / docs / latex / wx / splitter.tex
1 \section{\class{wxSplitterWindow}}\label{wxsplitterwindow}
2
3 \overview{wxSplitterWindow overview}{wxsplitterwindowoverview}
4
5 This class manages up to two subwindows. The current view can be
6 split into two programmatically (perhaps from a menu command), and unsplit
7 either programmatically or via the wxSplitterWindow user interface.
8
9 Appropriate 3D shading for the Windows 95 user interface is an option -
10 this is also recommended for GTK. Optionally, the sash can be made to
11 look more like the native control under MacOS X.
12
13 \wxheading{Window styles}
14
15 \begin{twocollist}\itemsep=0pt
16 \twocolitem{\windowstyle{wxSP\_3D}}{Draws a 3D effect border and sash.}
17 \twocolitem{\windowstyle{wxSP\_3DSASH}}{Draws a 3D effect sash.}
18 \twocolitem{\windowstyle{wxSP\_3DBORDER}}{Draws a 3D effect border.}
19 \twocolitem{\windowstyle{wxSP\_FULLSASH}}{Draws the ends of the sash (so the window can be used without a border).}
20 \twocolitem{\windowstyle{wxSP\_BORDER}}{Draws a thin black border around the window.}
21 \twocolitem{\windowstyle{wxSP\_NOBORDER}}{No border, and a black sash.}
22 \twocolitem{\windowstyle{wxSP\_PERMIT\_UNSPLIT}}{Always allow to
23 unsplit, even with the minimum pane size other than zero.}
24 \twocolitem{\windowstyle{wxSP\_LIVE\_UPDATE}}{Don't draw XOR line but resize the child windows immediately.}
25 \end{twocollist}
26
27 See also \helpref{window styles overview}{windowstyles}.
28
29 \wxheading{Derived from}
30
31 \helpref{wxWindow}{wxwindow}\\
32 \helpref{wxEvtHandler}{wxevthandler}\\
33 \helpref{wxObject}{wxobject}
34
35 \wxheading{Include files}
36
37 <wx/splitter.h>
38
39 \wxheading{Event handling}
40
41 To process input from a splitter control, use the following event handler
42 macros to direct input to member functions that take a
43 \helpref{wxSplitterEvent}{wxsplitterevent} argument.
44
45 \twocolwidtha{10cm}
46 \begin{twocollist}\itemsep=0pt
47 \twocolitem{{\bf EVT\_SPLITTER\_SASH\_POS\_CHANGING(id, func)}}{The sash
48 position is in the process of being changed. May be used to modify the
49 position of the tracking bar to properly reflect the position that
50 would be set if the drag were to be completed at this point. Processes
51 a wxEVT\_COMMAND\_SPLITTER\_SASH\_POS\_CHANGING event.}
52 \twocolitem{{\bf EVT\_SPLITTER\_SASH\_POS\_CHANGED(id, func)}}{The sash
53 position was changed. May be used to modify the sash position before
54 it is set, or to prevent the change from taking place.
55 Processes a wxEVT\_COMMAND\_SPLITTER\_SASH\_POS\_CHANGED event.}
56 \twocolitem{{\bf EVT\_SPLITTER\_UNSPLIT(id, func)}}{The splitter has been just
57 unsplit. Processes a wxEVT\_COMMAND\_SPLITTER\_UNSPLIT event.}
58 \twocolitem{{\bf EVT\_SPLITTER\_DOUBLECLICKED(id, func)}}{The sash was double
59 clicked. The default behaviour is to unsplit the window when this happens
60 (unless the minimum pane size has been set to a value greater than zero).
61 Processes a wxEVT\_COMMAND\_SPLITTER\_DOUBLECLICKED event.}
62 \end{twocollist}%
63
64 \wxheading{See also}
65
66 \helpref{wxSplitterEvent}{wxsplitterevent}
67
68 \latexignore{\rtfignore{\wxheading{Members}}}
69
70 \membersection{wxSplitterWindow::wxSplitterWindow}\label{wxsplitterwindowconstr}
71
72 \func{}{wxSplitterWindow}{\void}
73
74 Default constructor.
75
76 \func{}{wxSplitterWindow}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
77 \param{const wxPoint\& }{point = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
78 \param{long }{style=wxSP\_3D}, \param{const wxString\&}{ name = "splitterWindow"}}
79
80 Constructor for creating the window.
81
82 \wxheading{Parameters}
83
84 \docparam{parent}{The parent of the splitter window.}
85
86 \docparam{id}{The window identifier.}
87
88 \docparam{pos}{The window position.}
89
90 \docparam{size}{The window size.}
91
92 \docparam{style}{The window style. See \helpref{wxSplitterWindow}{wxsplitterwindow}.}
93
94 \docparam{name}{The window name.}
95
96 \wxheading{Remarks}
97
98 After using this constructor, you must create either one or two subwindows
99 with the splitter window as parent, and then call one of \helpref{wxSplitterWindow::Initialize}{wxsplitterwindowinitialize},\rtfsp
100 \helpref{wxSplitterWindow::SplitVertically}{wxsplitterwindowsplitvertically} and \helpref{wxSplitterWindow::SplitHorizontally}{wxsplitterwindowsplithorizontally} in
101 order to set the pane(s).
102
103 You can create two windows, with one hidden when not being shown; or you can
104 create and delete the second pane on demand.
105
106 \wxheading{See also}
107
108 \helpref{wxSplitterWindow::Initialize}{wxsplitterwindowinitialize}, \helpref{wxSplitterWindow::SplitVertically}{wxsplitterwindowsplitvertically},\rtfsp
109 \helpref{wxSplitterWindow::SplitHorizontally}{wxsplitterwindowsplithorizontally},\rtfsp
110 \helpref{wxSplitterWindow::Create}{wxsplitterwindowcreate}
111
112 \membersection{wxSplitterWindow::\destruct{wxSplitterWindow}}
113
114 \func{}{\destruct{wxSplitterWindow}}{\void}
115
116 Destroys the wxSplitterWindow and its children.
117
118 \membersection{wxSplitterWindow::Create}\label{wxsplitterwindowcreate}
119
120 \func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id}, \param{int }{x},\rtfsp
121 \param{const wxPoint\& }{point = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
122 \param{long }{style=wxSP\_3D}, \param{const wxString\&}{ name = "splitterWindow"}}
123
124 Creation function, for two-step construction. See \helpref{wxSplitterWindow::wxSplitterWindow}{wxsplitterwindowconstr} for
125 details.
126
127 \membersection{wxSplitterWindow::GetMinimumPaneSize}\label{wxsplitterwindowgetminimumpanesize}
128
129 \constfunc{int}{GetMinimumPaneSize}{\void}
130
131 Returns the current minimum pane size (defaults to zero).
132
133 \wxheading{See also}
134
135 \helpref{wxSplitterWindow::SetMinimumPaneSize}{wxsplitterwindowsetminimumpanesize}
136
137 \membersection{wxSplitterWindow::GetSashPosition}\label{wxsplitterwindowgetsashposition}
138
139 \func{int}{GetSashPosition}{\void}
140
141 Returns the current sash position.
142
143 \wxheading{See also}
144
145 \helpref{wxSplitterWindow::SetSashPosition}{wxsplitterwindowsetsashposition}
146
147 \membersection{wxSplitterWindow::GetSplitMode}\label{wxsplitterwindowgetsplitmode}
148
149 \constfunc{int}{GetSplitMode}{\void}
150
151 Gets the split mode.
152
153 \wxheading{See also}
154
155 \helpref{wxSplitterWindow::SetSplitMode}{wxsplitterwindowsetsplitmode}, \helpref{wxSplitterWindow::SplitVertically}{wxsplitterwindowsplitvertically},\rtfsp
156 \helpref{wxSplitterWindow::SplitHorizontally}{wxsplitterwindowsplithorizontally}.
157
158 \membersection{wxSplitterWindow::GetWindow1}\label{wxsplitterwindowgetwindow1}
159
160 \constfunc{wxWindow*}{GetWindow1}{\void}
161
162 Returns the left/top or only pane.
163
164 \membersection{wxSplitterWindow::GetWindow2}\label{wxsplitterwindowgetwindow2}
165
166 \constfunc{wxWindow*}{GetWindow2}{\void}
167
168 Returns the right/bottom pane.
169
170 \membersection{wxSplitterWindow::Initialize}\label{wxsplitterwindowinitialize}
171
172 \func{void}{Initialize}{\param{wxWindow* }{window}}
173
174 Initializes the splitter window to have one pane.
175
176 \wxheading{Parameters}
177
178 \docparam{window}{The pane for the unsplit window.}
179
180 \wxheading{Remarks}
181
182 This should be called if you wish to initially view only a single pane in the splitter window.
183
184 \wxheading{See also}
185
186 \helpref{wxSplitterWindow::SplitVertically}{wxsplitterwindowsplitvertically},\rtfsp
187 \helpref{wxSplitterWindow::SplitHorizontally}{wxsplitterwindowsplithorizontally}
188
189 \membersection{wxSplitterWindow::IsSplit}\label{wxsplitterwindowissplit}
190
191 \constfunc{bool}{IsSplit}{\void}
192
193 Returns TRUE if the window is split, FALSE otherwise.
194
195 \membersection{wxSplitterWindow::OnDoubleClickSash}\label{wxsplitterwindowondoubleclicksash}
196
197 \func{virtual void}{OnDoubleClickSash}{\param{int }{x}, \param{int }{y}}
198
199 Application-overridable function called when the sash is double-clicked with
200 the left mouse button.
201
202 \wxheading{Parameters}
203
204 \docparam{x}{The x position of the mouse cursor.}
205
206 \docparam{y}{The y position of the mouse cursor.}
207
208 \wxheading{Remarks}
209
210 The default implementation of this function calls \helpref{Unsplit}{wxsplitterwindowunsplit} if
211 the minimum pane size is zero.
212
213 \wxheading{See also}
214
215 \helpref{wxSplitterWindow::Unsplit}{wxsplitterwindowunsplit}
216
217 \membersection{wxSplitterWindow::OnUnsplit}\label{wxsplitterwindowonunsplit}
218
219 \func{virtual void}{OnUnsplit}{\param{wxWindow* }{removed}}
220
221 Application-overridable function called when the window is unsplit, either
222 programmatically or using the wxSplitterWindow user interface.
223
224 \wxheading{Parameters}
225
226 \docparam{removed}{The window being removed.}
227
228 \wxheading{Remarks}
229
230 The default implementation of this function simply hides {\it removed}. You
231 may wish to delete the window.
232
233 \membersection{wxSplitterWindow::OnSashPositionChange}\label{wxsplitterwindowonsashpositionchange}
234
235 \func{virtual bool}{OnSashPositionChange}{\param{int }{newSashPosition}}
236
237 Application-overridable function called when the sash position is changed by
238 user. It may return FALSE to prevent the change or TRUE to allow it.
239
240 \wxheading{Parameters}
241
242 \docparam{newSashPosition}{The new sash position (always positive or zero)}
243
244 \wxheading{Remarks}
245
246 The default implementation of this function verifies that the sizes of both
247 panes of the splitter are greater than minimum pane size.
248
249 \membersection{wxSplitterWindow::ReplaceWindow}\label{wxsplitterwindowreplacewindow}
250
251 \func{bool}{ReplaceWindow}{\param{wxWindow * }{winOld}, \param{wxWindow * }{winNew}}
252
253 This function replaces one of the windows managed by the wxSplitterWindow with
254 another one. It is in general better to use it instead of calling Unsplit()
255 and then resplitting the window back because it will provoke much less flicker
256 (if any). It is valid to call this function whether the splitter has two
257 windows or only one.
258
259 Both parameters should be non-NULL and {\it winOld} must specify one of the
260 windows managed by the splitter. If the parameters are incorrect or the window
261 couldn't be replaced, FALSE is returned. Otherwise the function will return
262 TRUE, but please notice that it will not delete the replaced window and you
263 may wish to do it yourself.
264
265 \wxheading{See also}
266
267 \helpref{wxSplitterWindow::GetMinimumPaneSize}{wxsplitterwindowgetminimumpanesize}
268
269 \wxheading{See also}
270
271 \helpref{wxSplitterWindow::Unsplit}{wxsplitterwindowunsplit}\\
272 \helpref{wxSplitterWindow::SplitVertically}{wxsplitterwindowsplitvertically}\\
273 \helpref{wxSplitterWindow::SplitHorizontally}{wxsplitterwindowsplithorizontally}
274
275 \membersection{wxSplitterWindow::SetSashPosition}\label{wxsplitterwindowsetsashposition}
276
277 \func{void}{SetSashPosition}{\param{int }{position}, \param{const bool}{ redraw = TRUE}}
278
279 Sets the sash position.
280
281 \wxheading{Parameters}
282
283 \docparam{position}{The sash position in pixels.}
284
285 \docparam{redraw}{If TRUE, resizes the panes and redraws the sash and border.}
286
287 \wxheading{Remarks}
288
289 Does not currently check for an out-of-range value.
290
291 \wxheading{See also}
292
293 \helpref{wxSplitterWindow::GetSashPosition}{wxsplitterwindowgetsashposition}
294
295 \membersection{wxSplitterWindow::SetMinimumPaneSize}\label{wxsplitterwindowsetminimumpanesize}
296
297 \func{void}{SetMinimumPaneSize}{\param{int }{paneSize}}
298
299 Sets the minimum pane size.
300
301 \wxheading{Parameters}
302
303 \docparam{paneSize}{Minimum pane size in pixels.}
304
305 \wxheading{Remarks}
306
307 The default minimum pane size is zero, which means that either pane can be reduced to zero by dragging
308 the sash, thus removing one of the panes. To prevent this behaviour (and veto out-of-range sash dragging),
309 set a minimum size, for example 20 pixels. If the wxSP\_PERMIT\_UNSPLIT style
310 is used when a splitter window is created, the window may be unsplit even
311 if minimum size is non-zero.
312
313 \wxheading{See also}
314
315 \helpref{wxSplitterWindow::GetMinimumPaneSize}{wxsplitterwindowgetminimumpanesize}
316
317 \membersection{wxSplitterWindow::SetSplitMode}\label{wxsplitterwindowsetsplitmode}
318
319 \func{void}{SetSplitMode}{\param{int }{mode}}
320
321 Sets the split mode.
322
323 \wxheading{Parameters}
324
325 \docparam{mode}{Can be wxSPLIT\_VERTICAL or wxSPLIT\_HORIZONTAL.}
326
327 \wxheading{Remarks}
328
329 Only sets the internal variable; does not update the display.
330
331 \wxheading{See also}
332
333 \helpref{wxSplitterWindow::GetSplitMode}{wxsplitterwindowgetsplitmode}, \helpref{wxSplitterWindow::SplitVertically}{wxsplitterwindowsplitvertically},\rtfsp
334 \helpref{wxSplitterWindow::SplitHorizontally}{wxsplitterwindowsplithorizontally}.
335
336 \membersection{wxSplitterWindow::SplitHorizontally}\label{wxsplitterwindowsplithorizontally}
337
338 \func{bool}{SplitHorizontally}{\param{wxWindow* }{window1}, \param{wxWindow* }{window2},
339 \param{int}{ sashPosition = 0}}
340
341 Initializes the top and bottom panes of the splitter window.
342
343 \wxheading{Parameters}
344
345 \docparam{window1}{The top pane.}
346
347 \docparam{window2}{The bottom pane.}
348
349 \docparam{sashPosition}{The initial position of the sash. If this value is
350 positive, it specifies the size of the upper pane. If it is negative, it is
351 absolute value gives the size of the lower pane. Finally, specify 0 (default)
352 to choose the default position (half of the total window height).}
353
354 \wxheading{Return value}
355
356 TRUE if successful, FALSE otherwise (the window was already split).
357
358 \wxheading{Remarks}
359
360 This should be called if you wish to initially view two panes. It can also be
361 called at any subsequent time, but the application should check that the
362 window is not currently split using \helpref{IsSplit}{wxsplitterwindowissplit}.
363
364 \wxheading{See also}
365
366 \helpref{wxSplitterWindow::SplitVertically}{wxsplitterwindowsplitvertically}, \helpref{wxSplitterWindow::IsSplit}{wxsplitterwindowissplit},\rtfsp
367 \helpref{wxSplitterWindow::Unsplit}{wxsplitterwindowunsplit}
368
369 \membersection{wxSplitterWindow::SplitVertically}\label{wxsplitterwindowsplitvertically}
370
371 \func{bool}{SplitVertically}{\param{wxWindow* }{window1}, \param{wxWindow* }{window2},
372 \param{int}{ sashPosition = 0}}
373
374 Initializes the left and right panes of the splitter window.
375
376 \wxheading{Parameters}
377
378 \docparam{window1}{The left pane.}
379
380 \docparam{window2}{The right pane.}
381
382 \docparam{sashPosition}{The initial position of the sash. If this value is
383 positive, it specifies the size of the left pane. If it is negative, it is
384 absolute value gives the size of the right pane. Finally, specify 0 (default)
385 to choose the default position (half of the total window width).}
386
387 \wxheading{Return value}
388
389 TRUE if successful, FALSE otherwise (the window was already split).
390
391 \wxheading{Remarks}
392
393 This should be called if you wish to initially view two panes. It can also be called at any subsequent time,
394 but the application should check that the window is not currently split using \helpref{IsSplit}{wxsplitterwindowissplit}.
395
396 \wxheading{See also}
397
398 \helpref{wxSplitterWindow::SplitHorizontally}{wxsplitterwindowsplithorizontally}, \helpref{wxSplitterWindow::IsSplit}{wxsplitterwindowissplit},\rtfsp
399 \helpref{wxSplitterWindow::Unsplit}{wxsplitterwindowunsplit}.
400
401 \membersection{wxSplitterWindow::Unsplit}\label{wxsplitterwindowunsplit}
402
403 \func{bool}{Unsplit}{\param{wxWindow* }{toRemove = NULL}}
404
405 Unsplits the window.
406
407 \wxheading{Parameters}
408
409 \docparam{toRemove}{The pane to remove, or NULL to remove the right or bottom pane.}
410
411 \wxheading{Return value}
412
413 TRUE if successful, FALSE otherwise (the window was not split).
414
415 \wxheading{Remarks}
416
417 This call will not actually delete the pane being removed; it calls \helpref{OnUnsplit}{wxsplitterwindowonunsplit}\rtfsp
418 which can be overridden for the desired behaviour. By default, the pane being removed is hidden.
419
420 \wxheading{See also}
421
422 \helpref{wxSplitterWindow::SplitHorizontally}{wxsplitterwindowsplithorizontally}, \helpref{wxSplitterWindow::SplitVertically}{wxsplitterwindowsplitvertically},\rtfsp
423 \helpref{wxSplitterWindow::IsSplit}{wxsplitterwindowissplit}, \helpref{wxSplitterWindow::OnUnsplit}{wxsplitterwindowonunsplit}
424