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 \wxheading{Window styles}
  10
  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.}
  22 \end{twocollist}
  23
  24 See 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
  32 \wxheading{Include files}
  33
  34 <wx/splitter.h>
  35
  36 \wxheading{Event handling}
  37
  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.
  41
  42 \twocolwidtha{10cm}
  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.}
  59 \end{twocollist}%
  60
  61 \wxheading{See also}
  62
  63 \helpref{wxSplitterEvent}{wxsplitterevent}
  64
  65 \latexignore{\rtfignore{\wxheading{Members}}}
  66
  67 \membersection{wxSplitterWindow::wxSplitterWindow}\label{wxsplitterwindowctor}
  68
  69 \func{}{wxSplitterWindow}{\void}
  70
  71 Default constructor.
  72
  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"}}
  76
  77 Constructor 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
  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).
  99
 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.
 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
 109 \membersection{wxSplitterWindow::\destruct{wxSplitterWindow}}\label{wxsplitterwindowdtor}
 110
 111 \func{}{\destruct{wxSplitterWindow}}{\void}
 112
 113 Destroys the wxSplitterWindow and its children.
 114
 115 \membersection{wxSplitterWindow::Create}\label{wxsplitterwindowcreate}
 116
 117 \func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id}, \rtfsp
 118 \param{const wxPoint\& }{point = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
 119 \param{long }{style=wxSP\_3D}, \param{const wxString\&}{ name = "splitterWindow"}}
 120
 121 Creation function, for two-step construction. See \helpref{wxSplitterWindow::wxSplitterWindow}{wxsplitterwindowctor} for
 122 details.
 123
 124 \membersection{wxSplitterWindow::GetMinimumPaneSize}\label{wxsplitterwindowgetminimumpanesize}
 125
 126 \constfunc{int}{GetMinimumPaneSize}{\void}
 127
 128 Returns the current minimum pane size (defaults to zero).
 129
 130 \wxheading{See also}
 131
 132 \helpref{wxSplitterWindow::SetMinimumPaneSize}{wxsplitterwindowsetminimumpanesize}
 133
 134 \membersection{wxSplitterWindow::GetSashGravity}\label{wxsplitterwindowgetsashgravity}
 135
 136 \func{double}{GetSashGravity}{\void}
 137
 138 Returns the current sash gravity.
 139
 140 \wxheading{See also}
 141
 142 \helpref{wxSplitterWindow::SetSashGravity}{wxsplitterwindowsetsashgravity}
 143
 144 \membersection{wxSplitterWindow::GetSashPosition}\label{wxsplitterwindowgetsashposition}
 145
 146 \func{int}{GetSashPosition}{\void}
 147
 148 Returns 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
 158 Gets 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
 169 Returns the left/top or only pane.
 170
 171 \membersection{wxSplitterWindow::GetWindow2}\label{wxsplitterwindowgetwindow2}
 172
 173 \constfunc{wxWindow*}{GetWindow2}{\void}
 174
 175 Returns the right/bottom pane.
 176
 177 \membersection{wxSplitterWindow::Initialize}\label{wxsplitterwindowinitialize}
 178
 179 \func{void}{Initialize}{\param{wxWindow* }{window}}
 180
 181 Initializes the splitter window to have one pane.  The child window is
 182 shown if it is currently hidden.
 183
 184 \wxheading{Parameters}
 185
 186 \docparam{window}{The pane for the unsplit window.}
 187
 188 \wxheading{Remarks}
 189
 190 This 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
 195 \helpref{wxSplitterWindow::SplitHorizontally}{wxsplitterwindowsplithorizontally}
 196
 197 \membersection{wxSplitterWindow::IsSplit}\label{wxsplitterwindowissplit}
 198
 199 \constfunc{bool}{IsSplit}{\void}
 200
 201 Returns true if the window is split, false otherwise.
 202
 203 \membersection{wxSplitterWindow::OnDoubleClickSash}\label{wxsplitterwindowondoubleclicksash}
 204
 205 \func{virtual void}{OnDoubleClickSash}{\param{int }{x}, \param{int }{y}}
 206
 207 Application-overridable function called when the sash is double-clicked with
 208 the 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
 218 The default implementation of this function calls \helpref{Unsplit}{wxsplitterwindowunsplit} if
 219 the 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
 229 Application-overridable function called when the window is unsplit, either
 230 programmatically or using the wxSplitterWindow user interface.
 231
 232 \wxheading{Parameters}
 233
 234 \docparam{removed}{The window being removed.}
 235
 236 \wxheading{Remarks}
 237
 238 The default implementation of this function simply hides {\it removed}. You
 239 may wish to delete the window.
 240
 241 \membersection{wxSplitterWindow::OnSashPositionChange}\label{wxsplitterwindowonsashpositionchange}
 242
 243 \func{virtual bool}{OnSashPositionChange}{\param{int }{newSashPosition}}
 244
 245 Application-overridable function called when the sash position is changed by
 246 user. It may return false to prevent the change or true to allow it.
 247
 248 \wxheading{Parameters}
 249
 250 \docparam{newSashPosition}{The new sash position (always positive or zero)}
 251
 252 \wxheading{Remarks}
 253
 254 The default implementation of this function verifies that the sizes of both
 255 panes of the splitter are greater than minimum pane size.
 256
 257 \membersection{wxSplitterWindow::ReplaceWindow}\label{wxsplitterwindowreplacewindow}
 258
 259 \func{bool}{ReplaceWindow}{\param{wxWindow * }{winOld}, \param{wxWindow * }{winNew}}
 260
 261 This function replaces one of the windows managed by the wxSplitterWindow with
 262 another one. It is in general better to use it instead of calling Unsplit()
 263 and 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
 265 windows or only one.
 266
 267 Both parameters should be non-NULL and {\it winOld} must specify one of the
 268 windows managed by the splitter. If the parameters are incorrect or the window
 269 couldn't be replaced, false is returned. Otherwise the function will return
 270 true, but please notice that it will not delete the replaced window and you
 271 may wish to do it yourself.
 272
 273 \wxheading{See also}
 274
 275 \helpref{wxSplitterWindow::GetMinimumPaneSize}{wxsplitterwindowgetminimumpanesize}
 276
 277 \wxheading{See also}
 278
 279 \helpref{wxSplitterWindow::Unsplit}{wxsplitterwindowunsplit}\\
 280 \helpref{wxSplitterWindow::SplitVertically}{wxsplitterwindowsplitvertically}\\
 281 \helpref{wxSplitterWindow::SplitHorizontally}{wxsplitterwindowsplithorizontally}
 282
 283 \membersection{wxSplitterWindow::SetSashGravity}\label{wxsplitterwindowsetsashgravity}
 284
 285 \func{void}{SetSashGravity}{\param{double }{gravity}}
 286
 287 Sets 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}
 295 Gravity is real factor which controls position of sash while resizing wxSplitterWindow.
 296 Gravity tells wxSplitterWindow how much will left/top window grow while resizing.
 297
 298 Example values:
 299 \begin{itemize}\itemsep=0pt
 300 \item{ 0.0  - only the bottom/right window is automaticaly resized}
 301 \item{ 0.5  - both windows grow by equal size}
 302 \item{ 1.0  - only left/top window grows}
 303 \end{itemize}
 304
 305 Gravity should be real value betwwen 0.0 and 1.0.
 306
 307 Default 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
 314 \membersection{wxSplitterWindow::SetSashPosition}\label{wxsplitterwindowsetsashposition}
 315
 316 \func{void}{SetSashPosition}{\param{int }{position}, \param{const bool}{ redraw = true}}
 317
 318 Sets the sash position.
 319
 320 \wxheading{Parameters}
 321
 322 \docparam{position}{The sash position in pixels.}
 323
 324 \docparam{redraw}{If true, resizes the panes and redraws the sash and border.}
 325
 326 \wxheading{Remarks}
 327
 328 Does not currently check for an out-of-range value.
 329
 330 \wxheading{See also}
 331
 332 \helpref{wxSplitterWindow::GetSashPosition}{wxsplitterwindowgetsashposition}
 333
 334 \membersection{wxSplitterWindow::SetMinimumPaneSize}\label{wxsplitterwindowsetminimumpanesize}
 335
 336 \func{void}{SetMinimumPaneSize}{\param{int }{paneSize}}
 337
 338 Sets the minimum pane size.
 339
 340 \wxheading{Parameters}
 341
 342 \docparam{paneSize}{Minimum pane size in pixels.}
 343
 344 \wxheading{Remarks}
 345
 346 The default minimum pane size is zero, which means that either pane can be reduced to zero by dragging
 347 the sash, thus removing one of the panes. To prevent this behaviour (and veto out-of-range sash dragging),
 348 set a minimum size, for example 20 pixels. If the wxSP\_PERMIT\_UNSPLIT style
 349 is used when a splitter window is created, the window may be unsplit even
 350 if minimum size is non-zero.
 351
 352 \wxheading{See also}
 353
 354 \helpref{wxSplitterWindow::GetMinimumPaneSize}{wxsplitterwindowgetminimumpanesize}
 355
 356 \membersection{wxSplitterWindow::SetSplitMode}\label{wxsplitterwindowsetsplitmode}
 357
 358 \func{void}{SetSplitMode}{\param{int }{mode}}
 359
 360 Sets the split mode.
 361
 362 \wxheading{Parameters}
 363
 364 \docparam{mode}{Can be wxSPLIT\_VERTICAL or wxSPLIT\_HORIZONTAL.}
 365
 366 \wxheading{Remarks}
 367
 368 Only sets the internal variable; does not update the display.
 369
 370 \wxheading{See also}
 371
 372 \helpref{wxSplitterWindow::GetSplitMode}{wxsplitterwindowgetsplitmode}, \helpref{wxSplitterWindow::SplitVertically}{wxsplitterwindowsplitvertically},\rtfsp
 373 \helpref{wxSplitterWindow::SplitHorizontally}{wxsplitterwindowsplithorizontally}.
 374
 375 \membersection{wxSplitterWindow::SplitHorizontally}\label{wxsplitterwindowsplithorizontally}
 376
 377 \func{bool}{SplitHorizontally}{\param{wxWindow* }{window1}, \param{wxWindow* }{window2},
 378  \param{int}{ sashPosition = 0}}
 379
 380 Initializes the top and bottom panes of the splitter window.  The
 381 child windows are shown if they are currently hidden.
 382
 383 \wxheading{Parameters}
 384
 385 \docparam{window1}{The top pane.}
 386
 387 \docparam{window2}{The bottom pane.}
 388
 389 \docparam{sashPosition}{The initial position of the sash. If this value is
 390 positive, it specifies the size of the upper pane. If it is negative, it is
 391 absolute value gives the size of the lower pane. Finally, specify 0 (default)
 392 to choose the default position (half of the total window height).}
 393
 394 \wxheading{Return value}
 395
 396 true if successful, false otherwise (the window was already split).
 397
 398 \wxheading{Remarks}
 399
 400 This should be called if you wish to initially view two panes. It can also be
 401 called at any subsequent time, but the application should check that the
 402 window is not currently split using \helpref{IsSplit}{wxsplitterwindowissplit}.
 403
 404 \wxheading{See also}
 405
 406 \helpref{wxSplitterWindow::SplitVertically}{wxsplitterwindowsplitvertically}, \helpref{wxSplitterWindow::IsSplit}{wxsplitterwindowissplit},\rtfsp
 407 \helpref{wxSplitterWindow::Unsplit}{wxsplitterwindowunsplit}
 408
 409 \membersection{wxSplitterWindow::SplitVertically}\label{wxsplitterwindowsplitvertically}
 410
 411 \func{bool}{SplitVertically}{\param{wxWindow* }{window1}, \param{wxWindow* }{window2},
 412  \param{int}{ sashPosition = 0}}
 413
 414 Initializes the left and right panes of the splitter window.  The
 415 child windows are shown if they are currently hidden.
 416
 417 \wxheading{Parameters}
 418
 419 \docparam{window1}{The left pane.}
 420
 421 \docparam{window2}{The right pane.}
 422
 423 \docparam{sashPosition}{The initial position of the sash. If this value is
 424 positive, it specifies the size of the left pane. If it is negative, it is
 425 absolute value gives the size of the right pane. Finally, specify 0 (default)
 426 to choose the default position (half of the total window width).}
 427
 428 \wxheading{Return value}
 429
 430 true if successful, false otherwise (the window was already split).
 431
 432 \wxheading{Remarks}
 433
 434 This should be called if you wish to initially view two panes. It can also be called at any subsequent time,
 435 but the application should check that the window is not currently split using \helpref{IsSplit}{wxsplitterwindowissplit}.
 436
 437 \wxheading{See also}
 438
 439 \helpref{wxSplitterWindow::SplitHorizontally}{wxsplitterwindowsplithorizontally}, \helpref{wxSplitterWindow::IsSplit}{wxsplitterwindowissplit},\rtfsp
 440 \helpref{wxSplitterWindow::Unsplit}{wxsplitterwindowunsplit}.
 441
 442 \membersection{wxSplitterWindow::Unsplit}\label{wxsplitterwindowunsplit}
 443
 444 \func{bool}{Unsplit}{\param{wxWindow* }{toRemove = NULL}}
 445
 446 Unsplits the window.
 447
 448 \wxheading{Parameters}
 449
 450 \docparam{toRemove}{The pane to remove, or NULL to remove the right or bottom pane.}
 451
 452 \wxheading{Return value}
 453
 454 true if successful, false otherwise (the window was not split).
 455
 456 \wxheading{Remarks}
 457
 458 This call will not actually delete the pane being removed; it calls \helpref{OnUnsplit}{wxsplitterwindowonunsplit}\rtfsp
 459 which can be overridden for the desired behaviour. By default, the pane being removed is hidden.
 460
 461 \wxheading{See also}
 462
 463 \helpref{wxSplitterWindow::SplitHorizontally}{wxsplitterwindowsplithorizontally}, \helpref{wxSplitterWindow::SplitVertically}{wxsplitterwindowsplitvertically},\rtfsp
 464 \helpref{wxSplitterWindow::IsSplit}{wxsplitterwindowissplit}, \helpref{wxSplitterWindow::OnUnsplit}{wxsplitterwindowonunsplit}
 465
 466 \membersection{wxSplitterWindow::UpdateSize}\label{wxsplitterwindowupdatesize}
 467
 468 \func{void}{UpdateSize}{\void}
 469
 470 Causes any pending sizing of the sash and child panes to take place
 471 immediately.
 472
 473 Such resizing normally takes place in idle time, in order
 474 to wait for layout to be completed. However, this can cause
 475 unacceptable flicker as the panes are resized after the window has been
 476 shown. To work around this, you can perform window layout (for
 477 example by sending a size event to the parent window), and then
 478 call this function, before showing the top-level window.
 479