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