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