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 automatically 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 a real value between 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::SetSashSize}\label{wxsplitterwindowsetsashsize}
 335
 336 \func{void}{SetSashSize}{\param{int }{size}}
 337
 338 Sets the sash size. Normally, the sash size is determined according to the metrics
 339 of each platform, but the application can override this, for example to show
 340 a thin sash that the user is not expected to drag. If {\it size} is more -1,
 341 the custom sash size will be used.
 342
 343 \membersection{wxSplitterWindow::SetMinimumPaneSize}\label{wxsplitterwindowsetminimumpanesize}
 344
 345 \func{void}{SetMinimumPaneSize}{\param{int }{paneSize}}
 346
 347 Sets the minimum pane size.
 348
 349 \wxheading{Parameters}
 350
 351 \docparam{paneSize}{Minimum pane size in pixels.}
 352
 353 \wxheading{Remarks}
 354
 355 The default minimum pane size is zero, which means that either pane can be reduced to zero by dragging
 356 the sash, thus removing one of the panes. To prevent this behaviour (and veto out-of-range sash dragging),
 357 set a minimum size, for example 20 pixels. If the wxSP\_PERMIT\_UNSPLIT style
 358 is used when a splitter window is created, the window may be unsplit even
 359 if minimum size is non-zero.
 360
 361 \wxheading{See also}
 362
 363 \helpref{wxSplitterWindow::GetMinimumPaneSize}{wxsplitterwindowgetminimumpanesize}
 364
 365 \membersection{wxSplitterWindow::SetSplitMode}\label{wxsplitterwindowsetsplitmode}
 366
 367 \func{void}{SetSplitMode}{\param{int }{mode}}
 368
 369 Sets the split mode.
 370
 371 \wxheading{Parameters}
 372
 373 \docparam{mode}{Can be wxSPLIT\_VERTICAL or wxSPLIT\_HORIZONTAL.}
 374
 375 \wxheading{Remarks}
 376
 377 Only 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},
 387  \param{int}{ sashPosition = 0}}
 388
 389 Initializes the top and bottom panes of the splitter window.  The
 390 child windows are shown if they are currently hidden.
 391
 392 \wxheading{Parameters}
 393
 394 \docparam{window1}{The top pane.}
 395
 396 \docparam{window2}{The bottom pane.}
 397
 398 \docparam{sashPosition}{The initial position of the sash. If this value is
 399 positive, it specifies the size of the upper pane. If it is negative, its
 400 absolute value gives the size of the lower pane. Finally, specify 0 (default)
 401 to choose the default position (half of the total window height).}
 402
 403 \wxheading{Return value}
 404
 405 true if successful, false otherwise (the window was already split).
 406
 407 \wxheading{Remarks}
 408
 409 This should be called if you wish to initially view two panes. It can also be
 410 called at any subsequent time, but the application should check that the
 411 window is not currently split using \helpref{IsSplit}{wxsplitterwindowissplit}.
 412
 413 \wxheading{See also}
 414
 415 \helpref{wxSplitterWindow::SplitVertically}{wxsplitterwindowsplitvertically}, \helpref{wxSplitterWindow::IsSplit}{wxsplitterwindowissplit},\rtfsp
 416 \helpref{wxSplitterWindow::Unsplit}{wxsplitterwindowunsplit}
 417
 418 \membersection{wxSplitterWindow::SplitVertically}\label{wxsplitterwindowsplitvertically}
 419
 420 \func{bool}{SplitVertically}{\param{wxWindow* }{window1}, \param{wxWindow* }{window2},
 421  \param{int}{ sashPosition = 0}}
 422
 423 Initializes the left and right panes of the splitter window.  The
 424 child windows are shown if they are currently hidden.
 425
 426 \wxheading{Parameters}
 427
 428 \docparam{window1}{The left pane.}
 429
 430 \docparam{window2}{The right pane.}
 431
 432 \docparam{sashPosition}{The initial position of the sash. If this value is
 433 positive, it specifies the size of the left pane. If it is negative, it is
 434 absolute value gives the size of the right pane. Finally, specify 0 (default)
 435 to choose the default position (half of the total window width).}
 436
 437 \wxheading{Return value}
 438
 439 true if successful, false otherwise (the window was already split).
 440
 441 \wxheading{Remarks}
 442
 443 This should be called if you wish to initially view two panes. It can also be called at any subsequent time,
 444 but 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
 455 Unsplits 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
 463 true if successful, false otherwise (the window was not split).
 464
 465 \wxheading{Remarks}
 466
 467 This call will not actually delete the pane being removed; it calls \helpref{OnUnsplit}{wxsplitterwindowonunsplit}\rtfsp
 468 which 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
 475 \membersection{wxSplitterWindow::UpdateSize}\label{wxsplitterwindowupdatesize}
 476
 477 \func{void}{UpdateSize}{\void}
 478
 479 Causes any pending sizing of the sash and child panes to take place
 480 immediately.
 481
 482 Such resizing normally takes place in idle time, in order
 483 to wait for layout to be completed. However, this can cause
 484 unacceptable flicker as the panes are resized after the window has been
 485 shown. To work around this, you can perform window layout (for
 486 example by sending a size event to the parent window), and then
 487 call this function, before showing the top-level window.
 488