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