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