]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/splitter.h
reviewed, updated and corrected wxGrid docs
[wxWidgets.git] / interface / wx / splitter.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: splitter.h
e54c96f1 3// Purpose: interface of wxSplitterWindow
23324ae1
FM
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
9/**
10 @class wxSplitterWindow
7c913512 11
23324ae1 12 @ref overview_wxsplitterwindowoverview "wxSplitterWindow overview"
7c913512 13
23324ae1
FM
14 This class manages up to two subwindows. The current view can be
15 split into two programmatically (perhaps from a menu command), and unsplit
16 either programmatically or via the wxSplitterWindow user interface.
7c913512 17
23324ae1 18 @beginStyleTable
8c6791e4 19 @style{wxSP_3D}
23324ae1 20 Draws a 3D effect border and sash.
278f584f
VZ
21 @style{wxSP_THIN_SASH}
22 Draws a thin sash.
8c6791e4 23 @style{wxSP_3DSASH}
278f584f 24 Draws a 3D effect sash (part of default style).
8c6791e4 25 @style{wxSP_3DBORDER}
23324ae1 26 Synonym for wxSP_BORDER.
8c6791e4 27 @style{wxSP_BORDER}
23324ae1 28 Draws a standard border.
8c6791e4 29 @style{wxSP_NOBORDER}
23324ae1 30 No border (default).
8c6791e4 31 @style{wxSP_NO_XP_THEME}
23324ae1
FM
32 Under Windows XP, switches off the attempt to draw the splitter
33 using Windows XP theming, so the borders and sash will take on the
34 pre-XP look.
8c6791e4 35 @style{wxSP_PERMIT_UNSPLIT}
23324ae1
FM
36 Always allow to unsplit, even with the minimum pane size other than
37 zero.
8c6791e4 38 @style{wxSP_LIVE_UPDATE}
23324ae1
FM
39 Don't draw XOR line but resize the child windows immediately.
40 @endStyleTable
7c913512 41
23324ae1
FM
42 @library{wxcore}
43 @category{miscwnd}
7c913512 44
e54c96f1 45 @see wxSplitterEvent
23324ae1
FM
46*/
47class wxSplitterWindow : public wxWindow
48{
49public:
671600d8
RR
50 /**
51 Default constructor
52 */
53 wxSplitterWindow();
54
23324ae1
FM
55 /**
56 Constructor for creating the window.
3c4f71cc 57
7c913512 58 @param parent
4cc4bfaf 59 The parent of the splitter window.
7c913512 60 @param id
4cc4bfaf 61 The window identifier.
7c913512 62 @param pos
4cc4bfaf 63 The window position.
7c913512 64 @param size
4cc4bfaf 65 The window size.
7c913512 66 @param style
4cc4bfaf 67 The window style. See wxSplitterWindow.
7c913512 68 @param name
4cc4bfaf 69 The window name.
3c4f71cc 70
23324ae1 71 @remarks After using this constructor, you must create either one or two
4cc4bfaf
FM
72 subwindows with the splitter window as parent, and then
73 call one of Initialize(),
74 SplitVertically() and
75 SplitHorizontally() in order to set the
76 pane(s).
3c4f71cc 77
4cc4bfaf
FM
78 @see Initialize(), SplitVertically(),
79 SplitHorizontally(), Create()
23324ae1 80 */
7c913512
FM
81 wxSplitterWindow(wxWindow* parent, wxWindowID id,
82 const wxPoint& point = wxDefaultPosition,
83 const wxSize& size = wxDefaultSize,
4cc4bfaf 84 long style = wxSP_3D,
7c913512 85 const wxString& name = "splitterWindow");
23324ae1
FM
86
87 /**
88 Destroys the wxSplitterWindow and its children.
89 */
90 ~wxSplitterWindow();
91
92 /**
93 Creation function, for two-step construction. See wxSplitterWindow() for
94 details.
95 */
96 bool Create(wxWindow* parent, wxWindowID id,
97 const wxPoint& point = wxDefaultPosition,
98 const wxSize& size = wxDefaultSize,
4cc4bfaf 99 long style = wxSP_3D,
23324ae1
FM
100 const wxString& name = "splitterWindow");
101
102 /**
103 Returns the current minimum pane size (defaults to zero).
3c4f71cc 104
4cc4bfaf 105 @see SetMinimumPaneSize()
23324ae1 106 */
328f5751 107 int GetMinimumPaneSize() const;
23324ae1
FM
108
109 /**
110 Returns the current sash gravity.
3c4f71cc 111
4cc4bfaf 112 @see SetSashGravity()
23324ae1
FM
113 */
114 double GetSashGravity();
115
116 /**
117 Returns the current sash position.
3c4f71cc 118
4cc4bfaf 119 @see SetSashPosition()
23324ae1
FM
120 */
121 int GetSashPosition();
122
123 /**
124 Gets the split mode.
3c4f71cc 125
4cc4bfaf
FM
126 @see SetSplitMode(), SplitVertically(),
127 SplitHorizontally().
23324ae1 128 */
328f5751 129 int GetSplitMode() const;
23324ae1
FM
130
131 /**
132 Returns the left/top or only pane.
133 */
328f5751 134 wxWindow* GetWindow1() const;
23324ae1
FM
135
136 /**
137 Returns the right/bottom pane.
138 */
328f5751 139 wxWindow* GetWindow2() const;
23324ae1
FM
140
141 /**
142 Initializes the splitter window to have one pane. The child window is
143 shown if it is currently hidden.
3c4f71cc 144
7c913512 145 @param window
4cc4bfaf 146 The pane for the unsplit window.
3c4f71cc 147
23324ae1 148 @remarks This should be called if you wish to initially view only a
4cc4bfaf 149 single pane in the splitter window.
3c4f71cc 150
4cc4bfaf 151 @see SplitVertically(), SplitHorizontally()
23324ae1
FM
152 */
153 void Initialize(wxWindow* window);
154
155 /**
156 Returns @true if the window is split, @false otherwise.
157 */
328f5751 158 bool IsSplit() const;
23324ae1
FM
159
160 /**
161 Application-overridable function called when the sash is double-clicked with
162 the left mouse button.
3c4f71cc 163
7c913512 164 @param x
4cc4bfaf 165 The x position of the mouse cursor.
7c913512 166 @param y
4cc4bfaf 167 The y position of the mouse cursor.
3c4f71cc 168
23324ae1 169 @remarks The default implementation of this function calls Unsplit if the
4cc4bfaf 170 minimum pane size is zero.
3c4f71cc 171
4cc4bfaf 172 @see Unsplit()
23324ae1
FM
173 */
174 virtual void OnDoubleClickSash(int x, int y);
175
176 /**
7c913512 177 Application-overridable function called when the sash position is changed by
23324ae1 178 user. It may return @false to prevent the change or @true to allow it.
3c4f71cc 179
7c913512 180 @param newSashPosition
4cc4bfaf 181 The new sash position (always positive or zero)
3c4f71cc 182
23324ae1 183 @remarks The default implementation of this function verifies that the
4cc4bfaf
FM
184 sizes of both panes of the splitter are greater than
185 minimum pane size.
23324ae1
FM
186 */
187 virtual bool OnSashPositionChange(int newSashPosition);
188
189 /**
190 Application-overridable function called when the window is unsplit, either
191 programmatically or using the wxSplitterWindow user interface.
3c4f71cc 192
7c913512 193 @param removed
4cc4bfaf 194 The window being removed.
3c4f71cc 195
23324ae1 196 @remarks The default implementation of this function simply hides
4cc4bfaf 197 removed. You may wish to delete the window.
23324ae1
FM
198 */
199 virtual void OnUnsplit(wxWindow* removed);
200
201 /**
202 This function replaces one of the windows managed by the wxSplitterWindow with
203 another one. It is in general better to use it instead of calling Unsplit()
204 and then resplitting the window back because it will provoke much less flicker
205 (if any). It is valid to call this function whether the splitter has two
206 windows or only one.
4cc4bfaf 207 Both parameters should be non-@NULL and @a winOld must specify one of the
23324ae1
FM
208 windows managed by the splitter. If the parameters are incorrect or the window
209 couldn't be replaced, @false is returned. Otherwise the function will return
210 @true, but please notice that it will not delete the replaced window and you
211 may wish to do it yourself.
3c4f71cc 212
4cc4bfaf 213 @see GetMinimumPaneSize()
23324ae1 214 */
4cc4bfaf 215 bool ReplaceWindow(wxWindow* winOld, wxWindow* winNew);
23324ae1
FM
216
217 /**
218 Sets the minimum pane size.
3c4f71cc 219
7c913512 220 @param paneSize
4cc4bfaf 221 Minimum pane size in pixels.
3c4f71cc 222
23324ae1 223 @remarks The default minimum pane size is zero, which means that either
4cc4bfaf
FM
224 pane can be reduced to zero by dragging the sash, thus
225 removing one of the panes. To prevent this behaviour
226 (and veto out-of-range sash dragging), set a minimum
227 size, for example 20 pixels. If the wxSP_PERMIT_UNSPLIT
228 style is used when a splitter window is created, the
229 window may be unsplit even if minimum size is non-zero.
3c4f71cc 230
4cc4bfaf 231 @see GetMinimumPaneSize()
23324ae1
FM
232 */
233 void SetMinimumPaneSize(int paneSize);
234
235 /**
7c913512 236 Sets the sash gravity.
3c4f71cc 237
7c913512 238 @param gravity
4cc4bfaf 239 The sash gravity. Value between 0.0 and 1.0.
3c4f71cc 240
4cc4bfaf 241 @see GetSashGravity()
23324ae1
FM
242 */
243 void SetSashGravity(double gravity);
244
245 /**
246 Sets the sash position.
3c4f71cc 247
7c913512 248 @param position
4cc4bfaf 249 The sash position in pixels.
7c913512 250 @param redraw
4cc4bfaf 251 If @true, resizes the panes and redraws the sash and border.
3c4f71cc 252
23324ae1 253 @remarks Does not currently check for an out-of-range value.
3c4f71cc 254
4cc4bfaf 255 @see GetSashPosition()
23324ae1 256 */
4cc4bfaf 257 void SetSashPosition(int position, const bool redraw = true);
23324ae1
FM
258
259 /**
260 Sets the sash size. Normally, the sash size is determined according to the
261 metrics
262 of each platform, but the application can override this, for example to show
4cc4bfaf 263 a thin sash that the user is not expected to drag. If @a size is more -1,
23324ae1
FM
264 the custom sash size will be used.
265 */
266 void SetSashSize(int size);
267
268 /**
269 Sets the split mode.
3c4f71cc 270
7c913512 271 @param mode
4cc4bfaf 272 Can be wxSPLIT_VERTICAL or wxSPLIT_HORIZONTAL.
3c4f71cc 273
23324ae1 274 @remarks Only sets the internal variable; does not update the display.
3c4f71cc 275
4cc4bfaf
FM
276 @see GetSplitMode(), SplitVertically(),
277 SplitHorizontally().
23324ae1
FM
278 */
279 void SetSplitMode(int mode);
280
281 /**
282 Initializes the top and bottom panes of the splitter window. The
283 child windows are shown if they are currently hidden.
3c4f71cc 284
7c913512 285 @param window1
4cc4bfaf 286 The top pane.
7c913512 287 @param window2
4cc4bfaf 288 The bottom pane.
7c913512 289 @param sashPosition
4cc4bfaf
FM
290 The initial position of the sash. If this value is
291 positive, it specifies the size of the upper pane. If it is negative, its
292 absolute value gives the size of the lower pane. Finally, specify 0
293 (default)
294 to choose the default position (half of the total window height).
3c4f71cc 295
d29a9a8a 296 @return @true if successful, @false otherwise (the window was already
4cc4bfaf 297 split).
3c4f71cc 298
23324ae1 299 @remarks This should be called if you wish to initially view two panes.
4cc4bfaf
FM
300 It can also be called at any subsequent time, but the
301 application should check that the window is not
302 currently split using IsSplit.
3c4f71cc 303
4cc4bfaf
FM
304 @see SplitVertically(), IsSplit(),
305 Unsplit()
23324ae1
FM
306 */
307 bool SplitHorizontally(wxWindow* window1, wxWindow* window2,
308 int sashPosition = 0);
309
310 /**
311 Initializes the left and right panes of the splitter window. The
312 child windows are shown if they are currently hidden.
3c4f71cc 313
7c913512 314 @param window1
4cc4bfaf 315 The left pane.
7c913512 316 @param window2
4cc4bfaf 317 The right pane.
7c913512 318 @param sashPosition
4cc4bfaf
FM
319 The initial position of the sash. If this value is
320 positive, it specifies the size of the left pane. If it is negative, it is
321 absolute value gives the size of the right pane. Finally, specify 0
322 (default)
323 to choose the default position (half of the total window width).
3c4f71cc 324
d29a9a8a 325 @return @true if successful, @false otherwise (the window was already
4cc4bfaf 326 split).
3c4f71cc 327
23324ae1 328 @remarks This should be called if you wish to initially view two panes.
4cc4bfaf
FM
329 It can also be called at any subsequent time, but the
330 application should check that the window is not
331 currently split using IsSplit.
3c4f71cc 332
4cc4bfaf
FM
333 @see SplitHorizontally(), IsSplit(),
334 Unsplit().
23324ae1
FM
335 */
336 bool SplitVertically(wxWindow* window1, wxWindow* window2,
337 int sashPosition = 0);
338
339 /**
340 Unsplits the window.
3c4f71cc 341
7c913512 342 @param toRemove
4cc4bfaf 343 The pane to remove, or @NULL to remove the right or bottom pane.
3c4f71cc 344
d29a9a8a 345 @return @true if successful, @false otherwise (the window was not split).
3c4f71cc 346
23324ae1 347 @remarks This call will not actually delete the pane being removed; it
4cc4bfaf
FM
348 calls OnUnsplit which can be overridden for the desired
349 behaviour. By default, the pane being removed is hidden.
3c4f71cc 350
4cc4bfaf
FM
351 @see SplitHorizontally(), SplitVertically(),
352 IsSplit(), OnUnsplit()
23324ae1 353 */
4cc4bfaf 354 bool Unsplit(wxWindow* toRemove = NULL);
23324ae1
FM
355
356 /**
357 Causes any pending sizing of the sash and child panes to take place
358 immediately.
23324ae1
FM
359 Such resizing normally takes place in idle time, in order
360 to wait for layout to be completed. However, this can cause
361 unacceptable flicker as the panes are resized after the window has been
362 shown. To work around this, you can perform window layout (for
363 example by sending a size event to the parent window), and then
364 call this function, before showing the top-level window.
365 */
366 void UpdateSize();
367};
368
369
e54c96f1 370
23324ae1
FM
371/**
372 @class wxSplitterEvent
7c913512 373
23324ae1
FM
374 This class represents the events generated by a splitter control. Also there is
375 only one event class, the data associated to the different events is not the
376 same and so not all accessor functions may be called for each event. The
377 documentation mentions the kind of event(s) for which the given accessor
378 function makes sense: calling it for other types of events will result
379 in assert failure (in debug mode) and will return meaningless results.
7c913512 380
23324ae1
FM
381 @library{wxcore}
382 @category{events}
7c913512 383
e54c96f1 384 @see wxSplitterWindow, @ref overview_eventhandlingoverview
23324ae1
FM
385*/
386class wxSplitterEvent : public wxNotifyEvent
387{
388public:
389 /**
390 Constructor. Used internally by wxWidgets only.
391 */
4cc4bfaf
FM
392 wxSplitterEvent(wxEventType eventType = wxEVT_NULL,
393 wxSplitterWindow* splitter = NULL);
23324ae1
FM
394
395 /**
396 Returns the new sash position.
23324ae1
FM
397 May only be called while processing
398 wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING and
399 wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED events.
400 */
328f5751 401 int GetSashPosition() const;
23324ae1
FM
402
403 /**
404 Returns a pointer to the window being removed when a splitter window
405 is unsplit.
23324ae1
FM
406 May only be called while processing
407 wxEVT_COMMAND_SPLITTER_UNSPLIT events.
408 */
328f5751 409 wxWindow* GetWindowBeingRemoved() const;
23324ae1
FM
410
411 /**
412 Returns the x coordinate of the double-click point.
23324ae1
FM
413 May only be called while processing
414 wxEVT_COMMAND_SPLITTER_DOUBLECLICKED events.
415 */
328f5751 416 int GetX() const;
23324ae1
FM
417
418 /**
419 Returns the y coordinate of the double-click point.
23324ae1
FM
420 May only be called while processing
421 wxEVT_COMMAND_SPLITTER_DOUBLECLICKED events.
422 */
328f5751 423 int GetY() const;
23324ae1
FM
424
425 /**
426 In the case of wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED events,
427 sets the new sash position. In the case of
428 wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING events, sets the new
429 tracking bar position so visual feedback during dragging will
430 represent that change that will actually take place. Set to -1 from
431 the event handler code to prevent repositioning.
23324ae1
FM
432 May only be called while processing
433 wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING and
434 wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED events.
3c4f71cc 435
7c913512 436 @param pos
4cc4bfaf 437 New sash position.
23324ae1
FM
438 */
439 void SetSashPosition(int pos);
440};
e54c96f1 441