1 \section{\class{wxSplitterWindow
}}\label{wxsplitterwindow
}
3 \overview{wxSplitterWindow overview
}{wxsplitterwindowoverview
}
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.
9 \wxheading{Window styles
}
11 \begin{twocollist
}\itemsep=
0pt
12 \twocolitem{\windowstyle{wxSP
\_3D}}{Draws a
3D effect border and sash.
}
13 \twocolitem{\windowstyle{wxSP
\_3DSASH}}{Draws a
3D effect sash.
}
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).
}
17 \twocolitem{\windowstyle{wxSP
\_NO\_XP\_THEME}}{Under Windows XP, switches off the attempt to draw the
18 splitter using Windows XP theming, so the borders and sash will take on the pre-XP look.
}
19 \twocolitem{\windowstyle{wxSP
\_PERMIT\_UNSPLIT}}{Always allow to
20 unsplit, 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.
}
24 See also
\helpref{window styles overview
}{windowstyles
}.
26 \wxheading{Derived from
}
28 \helpref{wxWindow
}{wxwindow
}\\
29 \helpref{wxEvtHandler
}{wxevthandler
}\\
30 \helpref{wxObject
}{wxobject
}
32 \wxheading{Include files
}
36 \wxheading{Event handling
}
38 To process input from a splitter control, use the following event handler
39 macros to direct input to member functions that take a
40 \helpref{wxSplitterEvent
}{wxsplitterevent
} argument.
43 \begin{twocollist
}\itemsep=
0pt
44 \twocolitem{{\bf EVT
\_SPLITTER\_SASH\_POS\_CHANGING(id, func)
}}{The sash
45 position is in the process of being changed. May be used to modify the
46 position of the tracking bar to properly reflect the position that
47 would be set if the drag were to be completed at this point. Processes
48 a wxEVT
\_COMMAND\_SPLITTER\_SASH\_POS\_CHANGING event.
}
49 \twocolitem{{\bf EVT
\_SPLITTER\_SASH\_POS\_CHANGED(id, func)
}}{The sash
50 position was changed. May be used to modify the sash position before
51 it is set, or to prevent the change from taking place.
52 Processes a wxEVT
\_COMMAND\_SPLITTER\_SASH\_POS\_CHANGED event.
}
53 \twocolitem{{\bf EVT
\_SPLITTER\_UNSPLIT(id, func)
}}{The splitter has been just
54 unsplit. Processes a wxEVT
\_COMMAND\_SPLITTER\_UNSPLIT event.
}
55 \twocolitem{{\bf EVT
\_SPLITTER\_DCLICK(id, func)
}}{The sash was double
56 clicked. 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).
58 Processes a wxEVT
\_COMMAND\_SPLITTER\_DOUBLECLICKED event.
}
63 \helpref{wxSplitterEvent
}{wxsplitterevent
}
65 \latexignore{\rtfignore{\wxheading{Members
}}}
67 \membersection{wxSplitterWindow::wxSplitterWindow
}\label{wxsplitterwindowctor
}
69 \func{}{wxSplitterWindow
}{\void}
73 \func{}{wxSplitterWindow
}{\param{wxWindow*
}{ parent
},
\param{wxWindowID
}{ id
},
\rtfsp
74 \param{const wxPoint\&
}{point = wxDefaultPosition
},
\param{const wxSize\&
}{size = wxDefaultSize
},
\rtfsp
75 \param{long
}{style=wxSP
\_3D},
\param{const wxString\&
}{ name = "splitterWindow"
}}
77 Constructor for creating the window.
79 \wxheading{Parameters
}
81 \docparam{parent
}{The parent of the splitter window.
}
83 \docparam{id
}{The window identifier.
}
85 \docparam{pos
}{The window position.
}
87 \docparam{size
}{The window size.
}
89 \docparam{style
}{The window style. See
\helpref{wxSplitterWindow
}{wxsplitterwindow
}.
}
91 \docparam{name
}{The window name.
}
95 After using this constructor, you must create either one or two subwindows
96 with 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
98 order to set the pane(s).
100 You can create two windows, with one hidden when not being shown; or you can
101 create and delete the second pane on demand.
105 \helpref{wxSplitterWindow::Initialize
}{wxsplitterwindowinitialize
},
\helpref{wxSplitterWindow::SplitVertically
}{wxsplitterwindowsplitvertically
},
\rtfsp
106 \helpref{wxSplitterWindow::SplitHorizontally
}{wxsplitterwindowsplithorizontally
},
\rtfsp
107 \helpref{wxSplitterWindow::Create
}{wxsplitterwindowcreate
}
109 \membersection{wxSplitterWindow::
\destruct{wxSplitterWindow
}}\label{wxsplitterwindowdtor
}
111 \func{}{\destruct{wxSplitterWindow
}}{\void}
113 Destroys the wxSplitterWindow and its children.
115 \membersection{wxSplitterWindow::Create
}\label{wxsplitterwindowcreate
}
117 \func{bool
}{Create
}{\param{wxWindow*
}{ parent
},
\param{wxWindowID
}{ id
},
\param{int
}{x
},
\rtfsp
118 \param{const wxPoint\&
}{point = wxDefaultPosition
},
\param{const wxSize\&
}{size = wxDefaultSize
},
\rtfsp
119 \param{long
}{style=wxSP
\_3D},
\param{const wxString\&
}{ name = "splitterWindow"
}}
121 Creation function, for two-step construction. See
\helpref{wxSplitterWindow::wxSplitterWindow
}{wxsplitterwindowctor
} for
124 \membersection{wxSplitterWindow::GetMinimumPaneSize
}\label{wxsplitterwindowgetminimumpanesize
}
126 \constfunc{int
}{GetMinimumPaneSize
}{\void}
128 Returns the current minimum pane size (defaults to zero).
132 \helpref{wxSplitterWindow::SetMinimumPaneSize
}{wxsplitterwindowsetminimumpanesize
}
134 \membersection{wxSplitterWindow::GetSashGravity
}\label{wxsplitterwindowgetsashgravity
}
136 \func{double
}{GetSashGravity
}{\void}
138 Returns the current sash gravity.
142 \helpref{wxSplitterWindow::SetSashGravity
}{wxsplitterwindowsetsashgravity
}
144 \membersection{wxSplitterWindow::GetSashPosition
}\label{wxsplitterwindowgetsashposition
}
146 \func{int
}{GetSashPosition
}{\void}
148 Returns the current sash position.
152 \helpref{wxSplitterWindow::SetSashPosition
}{wxsplitterwindowsetsashposition
}
154 \membersection{wxSplitterWindow::GetSplitMode
}\label{wxsplitterwindowgetsplitmode
}
156 \constfunc{int
}{GetSplitMode
}{\void}
162 \helpref{wxSplitterWindow::SetSplitMode
}{wxsplitterwindowsetsplitmode
},
\helpref{wxSplitterWindow::SplitVertically
}{wxsplitterwindowsplitvertically
},
\rtfsp
163 \helpref{wxSplitterWindow::SplitHorizontally
}{wxsplitterwindowsplithorizontally
}.
165 \membersection{wxSplitterWindow::GetWindow1
}\label{wxsplitterwindowgetwindow1
}
167 \constfunc{wxWindow*
}{GetWindow1
}{\void}
169 Returns the left/top or only pane.
171 \membersection{wxSplitterWindow::GetWindow2
}\label{wxsplitterwindowgetwindow2
}
173 \constfunc{wxWindow*
}{GetWindow2
}{\void}
175 Returns the right/bottom pane.
177 \membersection{wxSplitterWindow::Initialize
}\label{wxsplitterwindowinitialize
}
179 \func{void
}{Initialize
}{\param{wxWindow*
}{window
}}
181 Initializes the splitter window to have one pane.
183 \wxheading{Parameters
}
185 \docparam{window
}{The pane for the unsplit window.
}
189 This should be called if you wish to initially view only a single pane in the splitter window.
193 \helpref{wxSplitterWindow::SplitVertically
}{wxsplitterwindowsplitvertically
},
\rtfsp
194 \helpref{wxSplitterWindow::SplitHorizontally
}{wxsplitterwindowsplithorizontally
}
196 \membersection{wxSplitterWindow::IsSplit
}\label{wxsplitterwindowissplit
}
198 \constfunc{bool
}{IsSplit
}{\void}
200 Returns true if the window is split, false otherwise.
202 \membersection{wxSplitterWindow::OnDoubleClickSash
}\label{wxsplitterwindowondoubleclicksash
}
204 \func{virtual void
}{OnDoubleClickSash
}{\param{int
}{x
},
\param{int
}{y
}}
206 Application-overridable function called when the sash is double-clicked with
207 the left mouse button.
209 \wxheading{Parameters
}
211 \docparam{x
}{The x position of the mouse cursor.
}
213 \docparam{y
}{The y position of the mouse cursor.
}
217 The default implementation of this function calls
\helpref{Unsplit
}{wxsplitterwindowunsplit
} if
218 the minimum pane size is zero.
222 \helpref{wxSplitterWindow::Unsplit
}{wxsplitterwindowunsplit
}
224 \membersection{wxSplitterWindow::OnUnsplit
}\label{wxsplitterwindowonunsplit
}
226 \func{virtual void
}{OnUnsplit
}{\param{wxWindow*
}{removed
}}
228 Application-overridable function called when the window is unsplit, either
229 programmatically or using the wxSplitterWindow user interface.
231 \wxheading{Parameters
}
233 \docparam{removed
}{The window being removed.
}
237 The default implementation of this function simply hides
{\it removed
}. You
238 may wish to delete the window.
240 \membersection{wxSplitterWindow::OnSashPositionChange
}\label{wxsplitterwindowonsashpositionchange
}
242 \func{virtual bool
}{OnSashPositionChange
}{\param{int
}{newSashPosition
}}
244 Application-overridable function called when the sash position is changed by
245 user. It may return false to prevent the change or true to allow it.
247 \wxheading{Parameters
}
249 \docparam{newSashPosition
}{The new sash position (always positive or zero)
}
253 The default implementation of this function verifies that the sizes of both
254 panes of the splitter are greater than minimum pane size.
256 \membersection{wxSplitterWindow::ReplaceWindow
}\label{wxsplitterwindowreplacewindow
}
258 \func{bool
}{ReplaceWindow
}{\param{wxWindow *
}{winOld
},
\param{wxWindow *
}{winNew
}}
260 This function replaces one of the windows managed by the wxSplitterWindow with
261 another one. It is in general better to use it instead of calling Unsplit()
262 and then resplitting the window back because it will provoke much less flicker
263 (if any). It is valid to call this function whether the splitter has two
266 Both parameters should be non-NULL and
{\it winOld
} must specify one of the
267 windows managed by the splitter. If the parameters are incorrect or the window
268 couldn't be replaced, false is returned. Otherwise the function will return
269 true, but please notice that it will not delete the replaced window and you
270 may wish to do it yourself.
274 \helpref{wxSplitterWindow::GetMinimumPaneSize
}{wxsplitterwindowgetminimumpanesize
}
278 \helpref{wxSplitterWindow::Unsplit
}{wxsplitterwindowunsplit
}\\
279 \helpref{wxSplitterWindow::SplitVertically
}{wxsplitterwindowsplitvertically
}\\
280 \helpref{wxSplitterWindow::SplitHorizontally
}{wxsplitterwindowsplithorizontally
}
282 \membersection{wxSplitterWindow::SetSashGravity
}\label{wxsplitterwindowsetsashgravity
}
284 \func{void
}{SetSashGravity
}{\param{double
}{gravity
}}
286 Sets the sash gravity.
288 \wxheading{Parameters
}
290 \docparam{gravity
}{The sash gravity. Value between
0.0 and
1.0.
}
294 Gravity is real factor which controls position of sash while resizing wxSplitterWindow.
295 Gravity tells wxSplitterWindow how much will left/top window grow while resizing.
298 \begin{itemize
}\itemsep=
0pt
299 \item{ 0.0 - only the bottom/right window is automaticaly resized
}
300 \item{ 0.5 - both windows grow by equal size
}
301 \item{ 1.0 - only left/top window grows
}
304 Gravity should be real value betwwen
0.0 and
1.0.
306 Default value of sash gravity is
0.0. That value is compatible with previous
307 (before gravity was introduced) behaviour of wxSplitterWindow.
311 \helpref{wxSplitterWindow::GetSashGravity
}{wxsplitterwindowgetsashgravity
}
313 \membersection{wxSplitterWindow::SetSashPosition
}\label{wxsplitterwindowsetsashposition
}
315 \func{void
}{SetSashPosition
}{\param{int
}{position
},
\param{const bool
}{ redraw = true
}}
317 Sets the sash position.
319 \wxheading{Parameters
}
321 \docparam{position
}{The sash position in pixels.
}
323 \docparam{redraw
}{If true, resizes the panes and redraws the sash and border.
}
327 Does not currently check for an out-of-range value.
331 \helpref{wxSplitterWindow::GetSashPosition
}{wxsplitterwindowgetsashposition
}
333 \membersection{wxSplitterWindow::SetMinimumPaneSize
}\label{wxsplitterwindowsetminimumpanesize
}
335 \func{void
}{SetMinimumPaneSize
}{\param{int
}{paneSize
}}
337 Sets the minimum pane size.
339 \wxheading{Parameters
}
341 \docparam{paneSize
}{Minimum pane size in pixels.
}
345 The default minimum pane size is zero, which means that either pane can be reduced to zero by dragging
346 the sash, thus removing one of the panes. To prevent this behaviour (and veto out-of-range sash dragging),
347 set a minimum size, for example
20 pixels. If the wxSP
\_PERMIT\_UNSPLIT style
348 is used when a splitter window is created, the window may be unsplit even
349 if minimum size is non-zero.
353 \helpref{wxSplitterWindow::GetMinimumPaneSize
}{wxsplitterwindowgetminimumpanesize
}
355 \membersection{wxSplitterWindow::SetSplitMode
}\label{wxsplitterwindowsetsplitmode
}
357 \func{void
}{SetSplitMode
}{\param{int
}{mode
}}
361 \wxheading{Parameters
}
363 \docparam{mode
}{Can be wxSPLIT
\_VERTICAL or wxSPLIT
\_HORIZONTAL.
}
367 Only sets the internal variable; does not update the display.
371 \helpref{wxSplitterWindow::GetSplitMode
}{wxsplitterwindowgetsplitmode
},
\helpref{wxSplitterWindow::SplitVertically
}{wxsplitterwindowsplitvertically
},
\rtfsp
372 \helpref{wxSplitterWindow::SplitHorizontally
}{wxsplitterwindowsplithorizontally
}.
374 \membersection{wxSplitterWindow::SplitHorizontally
}\label{wxsplitterwindowsplithorizontally
}
376 \func{bool
}{SplitHorizontally
}{\param{wxWindow*
}{window1
},
\param{wxWindow*
}{window2
},
377 \param{int
}{ sashPosition =
0}}
379 Initializes the top and bottom panes of the splitter window.
381 \wxheading{Parameters
}
383 \docparam{window1
}{The top pane.
}
385 \docparam{window2
}{The bottom pane.
}
387 \docparam{sashPosition
}{The initial position of the sash. If this value is
388 positive, it specifies the size of the upper pane. If it is negative, it is
389 absolute value gives the size of the lower pane. Finally, specify
0 (default)
390 to choose the default position (half of the total window height).
}
392 \wxheading{Return value
}
394 true if successful, false otherwise (the window was already split).
398 This should be called if you wish to initially view two panes. It can also be
399 called at any subsequent time, but the application should check that the
400 window is not currently split using
\helpref{IsSplit
}{wxsplitterwindowissplit
}.
404 \helpref{wxSplitterWindow::SplitVertically
}{wxsplitterwindowsplitvertically
},
\helpref{wxSplitterWindow::IsSplit
}{wxsplitterwindowissplit
},
\rtfsp
405 \helpref{wxSplitterWindow::Unsplit
}{wxsplitterwindowunsplit
}
407 \membersection{wxSplitterWindow::SplitVertically
}\label{wxsplitterwindowsplitvertically
}
409 \func{bool
}{SplitVertically
}{\param{wxWindow*
}{window1
},
\param{wxWindow*
}{window2
},
410 \param{int
}{ sashPosition =
0}}
412 Initializes the left and right panes of the splitter window.
414 \wxheading{Parameters
}
416 \docparam{window1
}{The left pane.
}
418 \docparam{window2
}{The right pane.
}
420 \docparam{sashPosition
}{The initial position of the sash. If this value is
421 positive, it specifies the size of the left pane. If it is negative, it is
422 absolute value gives the size of the right pane. Finally, specify
0 (default)
423 to choose the default position (half of the total window width).
}
425 \wxheading{Return value
}
427 true if successful, false otherwise (the window was already split).
431 This should be called if you wish to initially view two panes. It can also be called at any subsequent time,
432 but the application should check that the window is not currently split using
\helpref{IsSplit
}{wxsplitterwindowissplit
}.
436 \helpref{wxSplitterWindow::SplitHorizontally
}{wxsplitterwindowsplithorizontally
},
\helpref{wxSplitterWindow::IsSplit
}{wxsplitterwindowissplit
},
\rtfsp
437 \helpref{wxSplitterWindow::Unsplit
}{wxsplitterwindowunsplit
}.
439 \membersection{wxSplitterWindow::Unsplit
}\label{wxsplitterwindowunsplit
}
441 \func{bool
}{Unsplit
}{\param{wxWindow*
}{toRemove = NULL
}}
445 \wxheading{Parameters
}
447 \docparam{toRemove
}{The pane to remove, or NULL to remove the right or bottom pane.
}
449 \wxheading{Return value
}
451 true if successful, false otherwise (the window was not split).
455 This call will not actually delete the pane being removed; it calls
\helpref{OnUnsplit
}{wxsplitterwindowonunsplit
}\rtfsp
456 which can be overridden for the desired behaviour. By default, the pane being removed is hidden.
460 \helpref{wxSplitterWindow::SplitHorizontally
}{wxsplitterwindowsplithorizontally
},
\helpref{wxSplitterWindow::SplitVertically
}{wxsplitterwindowsplitvertically
},
\rtfsp
461 \helpref{wxSplitterWindow::IsSplit
}{wxsplitterwindowissplit
},
\helpref{wxSplitterWindow::OnUnsplit
}{wxsplitterwindowonunsplit
}
463 \membersection{wxSplitterWindow::UpdateSize
}\label{wxsplitterwindowupdatesize
}
465 \func{void
}{UpdateSize
}{\void}
467 Causes any pending sizing of the sash and child panes to take place
470 Such resizing normally takes place in idle time, in order
471 to wait for layout to be completed. However, this can cause
472 unacceptable flicker as the panes are resized after the window has been
473 shown. To work around this, you can perform window layout (for
474 example by sending a size event to the parent window), and then
475 call this function, before showing the top-level window.