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