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 \wxheading{See also}
 193
 194 \helpref{wxSplitterWindow::Unsplit}{wxsplitterwindowunsplit}
 195
 196 \membersection{wxSplitterWindow::SetSashPosition}\label{wxsplitterwindowsetsashposition}
 197
 198 \func{void}{SetSashPosition}{\param{int }{position}, \param{const bool}{ redraw = TRUE}}
 199
 200 Sets the sash position.
 201
 202 \wxheading{Parameters}
 203
 204 \docparam{position}{The sash position in pixels.}
 205
 206 \docparam{redraw}{If TRUE, resizes the panes and redraws the sash and border.}
 207
 208 \wxheading{Remarks}
 209
 210 Does not currently check for an out-of-range value.
 211
 212 \wxheading{See also}
 213
 214 \helpref{wxSplitterWindow::GetSashPosition}{wxsplitterwindowgetsashposition}
 215
 216 \membersection{wxSplitterWindow::SetMinimumPaneSize}\label{wxsplitterwindowsetminimumpanesize}
 217
 218 \func{void}{SetMinimumPaneSize}{\param{int }{paneSize}}
 219
 220 Sets the minimum pane size.
 221
 222 \wxheading{Parameters}
 223
 224 \docparam{paneSize}{Minimum pane size in pixels.}
 225
 226 \wxheading{Remarks}
 227
 228 The default minimum pane size is zero, which means that either pane can be reduced to zero by dragging
 229 the sash, thus removing one of the panes. To prevent this behaviour (and veto out-of-range sash dragging),
 230 set a minimum size, for example 20 pixels.
 231
 232 \wxheading{See also}
 233
 234 \helpref{wxSplitterWindow::GetMinimumPaneSize}{wxsplitterwindowgetminimumpanesize}
 235
 236 \membersection{wxSplitterWindow::SetSplitMode}\label{wxsplitterwindowsetsplitmode}
 237
 238 \func{void}{SetSplitMode}{\param{int }{mode}}
 239
 240 Sets the split mode.
 241
 242 \wxheading{Parameters}
 243
 244 \docparam{mode}{Can be wxSPLIT\_VERTICAL or wxSPLIT\_HORIZONTAL.}
 245
 246 \wxheading{Remarks}
 247
 248 Only sets the internal variable; does not update the display.
 249
 250 \wxheading{See also}
 251
 252 \helpref{wxSplitterWindow::GetSplitMode}{wxsplitterwindowgetsplitmode}, \helpref{wxSplitterWindow::SplitVertically}{wxsplitterwindowsplitvertically},\rtfsp
 253 \helpref{wxSplitterWindow::SplitHorizontally}{wxsplitterwindowsplithorizontally}.
 254
 255 \membersection{wxSplitterWindow::SplitHorizontally}\label{wxsplitterwindowsplithorizontally}
 256
 257 \func{bool}{SplitHorizontally}{\param{wxWindow* }{window1}, \param{wxWindow* }{window2},
 258  \param{int}{ sashPosition = -1}}
 259
 260 Initializes the top and bottom panes of the splitter window.
 261
 262 \wxheading{Parameters}
 263
 264 \docparam{window1}{The top pane.}
 265
 266 \docparam{window2}{The bottom pane.}
 267
 268 \docparam{sashPosition}{The initial position of the sash. If the value is -1, a default position
 269 is chosen.}
 270
 271 \wxheading{Return value}
 272
 273 TRUE if successful, FALSE otherwise (the window was already split).
 274
 275 \wxheading{Remarks}
 276
 277 This should be called if you wish to initially view two panes. It can also be called at any subsequent time,
 278 but the application should check that the window is not currently split using \helpref{IsSplit}{wxsplitterwindowissplit}.
 279
 280 \wxheading{See also}
 281
 282 \helpref{wxSplitterWindow::SplitVertically}{wxsplitterwindowsplitvertically}, \helpref{wxSplitterWindow::IsSplit}{wxsplitterwindowissplit},\rtfsp
 283 \helpref{wxSplitterWindow::Unsplit}{wxsplitterwindowunsplit}.
 284
 285 \membersection{wxSplitterWindow::SplitVertically}\label{wxsplitterwindowsplitvertically}
 286
 287 \func{bool}{SplitVertically}{\param{wxWindow* }{window1}, \param{wxWindow* }{window2},
 288  \param{int}{ sashPosition = -1}}
 289
 290 Initializes the left and right panes of the splitter window.
 291
 292 \wxheading{Parameters}
 293
 294 \docparam{window1}{The left pane.}
 295
 296 \docparam{window2}{The right pane.}
 297
 298 \docparam{sashPosition}{The initial position of the sash. If the value is -1, a default position
 299 is chosen.}
 300
 301 \wxheading{Return value}
 302
 303 TRUE if successful, FALSE otherwise (the window was already split).
 304
 305 \wxheading{Remarks}
 306
 307 This should be called if you wish to initially view two panes. It can also be called at any subsequent time,
 308 but the application should check that the window is not currently split using \helpref{IsSplit}{wxsplitterwindowissplit}.
 309
 310 \wxheading{See also}
 311
 312 \helpref{wxSplitterWindow::SplitHorizontally}{wxsplitterwindowsplithorizontally}, \helpref{wxSplitterWindow::IsSplit}{wxsplitterwindowissplit},\rtfsp
 313 \helpref{wxSplitterWindow::Unsplit}{wxsplitterwindowunsplit}.
 314
 315 \membersection{wxSplitterWindow::Unsplit}\label{wxsplitterwindowunsplit}
 316
 317 \func{bool}{Unsplit}{\param{wxWindow* }{toRemove = NULL}}
 318
 319 Unsplits the window.
 320
 321 \wxheading{Parameters}
 322
 323 \docparam{toRemove}{The pane to remove, or NULL to remove the right or bottom pane.}
 324
 325 \wxheading{Return value}
 326
 327 TRUE if successful, FALSE otherwise (the window was not split).
 328
 329 \wxheading{Remarks}
 330
 331 This call will not actually delete the pane being removed; it calls \helpref{OnUnsplit}{wxsplitterwindowonunsplit}\rtfsp
 332 which can be overridden for the desired behaviour. By default, the pane being removed is hidden.
 333
 334 \wxheading{See also}
 335
 336 \helpref{wxSplitterWindow::SplitHorizontally}{wxsplitterwindowsplithorizontally}, \helpref{wxSplitterWindow::SplitVertically}{wxsplitterwindowsplitvertically},\rtfsp
 337 \helpref{wxSplitterWindow::IsSplit}{wxsplitterwindowissplit}, \helpref{wxSplitterWindow::OnUnsplit}{wxsplitterwindowonunsplit}
 338
 339
 340