]> git.saurik.com Git - wxWidgets.git/blame_incremental - interface/wx/splitter.h
Make storing non-trivial data in wxThreadSpecificInfo possible.
[wxWidgets.git] / interface / wx / splitter.h
... / ...
CommitLineData
1/////////////////////////////////////////////////////////////////////////////
2// Name: splitter.h
3// Purpose: interface of wxSplitterWindow
4// Author: wxWidgets team
5// Licence: wxWindows licence
6/////////////////////////////////////////////////////////////////////////////
7
8
9#define wxSP_NOBORDER 0x0000
10#define wxSP_THIN_SASH 0x0000 // NB: the default is 3D sash
11#define wxSP_NOSASH 0x0010
12#define wxSP_PERMIT_UNSPLIT 0x0040
13#define wxSP_LIVE_UPDATE 0x0080
14#define wxSP_3DSASH 0x0100
15#define wxSP_3DBORDER 0x0200
16#define wxSP_NO_XP_THEME 0x0400
17#define wxSP_BORDER wxSP_3DBORDER
18#define wxSP_3D (wxSP_3DBORDER | wxSP_3DSASH)
19
20
21enum wxSplitMode
22{
23 wxSPLIT_HORIZONTAL = 1,
24 wxSPLIT_VERTICAL
25};
26
27enum
28{
29 wxSPLIT_DRAG_NONE,
30 wxSPLIT_DRAG_DRAGGING,
31 wxSPLIT_DRAG_LEFT_DOWN
32};
33
34/**
35 @class wxSplitterWindow
36
37 This class manages up to two subwindows. The current view can be split
38 into two programmatically (perhaps from a menu command), and unsplit
39 either programmatically or via the wxSplitterWindow user interface.
40
41 @beginStyleTable
42 @style{wxSP_3D}
43 Draws a 3D effect border and sash.
44 @style{wxSP_THIN_SASH}
45 Draws a thin sash.
46 @style{wxSP_3DSASH}
47 Draws a 3D effect sash (part of default style).
48 @style{wxSP_3DBORDER}
49 Synonym for wxSP_BORDER.
50 @style{wxSP_BORDER}
51 Draws a standard border.
52 @style{wxSP_NOBORDER}
53 No border (default).
54 @style{wxSP_NO_XP_THEME}
55 Under Windows XP, switches off the attempt to draw the splitter
56 using Windows XP theming, so the borders and sash will take on the
57 pre-XP look.
58 @style{wxSP_PERMIT_UNSPLIT}
59 Always allow to unsplit, even with the minimum pane size other than zero.
60 @style{wxSP_LIVE_UPDATE}
61 Don't draw XOR line but resize the child windows immediately.
62 @endStyleTable
63
64
65 @beginEventEmissionTable{wxSplitterEvent}
66 @event{EVT_SPLITTER_SASH_POS_CHANGING(id, func)}
67 The sash position is in the process of being changed.
68 May be used to modify the position of the tracking bar to properly
69 reflect the position that would be set if the drag were to be completed
70 at this point. Processes a @c wxEVT_SPLITTER_SASH_POS_CHANGING event.
71 @event{EVT_SPLITTER_SASH_POS_CHANGED(id, func)}
72 The sash position was changed. May be used to modify the sash position
73 before it is set, or to prevent the change from taking place.
74 Processes a @c wxEVT_SPLITTER_SASH_POS_CHANGED event.
75 @event{EVT_SPLITTER_UNSPLIT(id, func)}
76 The splitter has been just unsplit. Processes a @c wxEVT_SPLITTER_UNSPLIT event.
77 @event{EVT_SPLITTER_DCLICK(id, func)}
78 The sash was double clicked. The default behaviour is to unsplit the
79 window when this happens (unless the minimum pane size has been set
80 to a value greater than zero). Processes a @c wxEVT_SPLITTER_DOUBLECLICKED event.
81 @endEventTable
82
83
84 @library{wxcore}
85 @category{miscwnd}
86
87 @see wxSplitterEvent, @ref overview_splitterwindow
88*/
89class wxSplitterWindow : public wxWindow
90{
91public:
92 /**
93 Default constructor
94 */
95 wxSplitterWindow();
96
97 /**
98 Constructor for creating the window.
99
100 @param parent
101 The parent of the splitter window.
102 @param id
103 The window identifier.
104 @param pos
105 The window position.
106 @param size
107 The window size.
108 @param style
109 The window style. See wxSplitterWindow.
110 @param name
111 The window name.
112
113 @remarks
114 After using this constructor, you must create either one or two
115 subwindows with the splitter window as parent, and then call one
116 of Initialize(), SplitVertically() and SplitHorizontally() in order
117 to set the pane(s).
118 You can create two windows, with one hidden when not being shown;
119 or you can create and delete the second pane on demand.
120
121 @see Initialize(), SplitVertically(), SplitHorizontally(), Create()
122 */
123 wxSplitterWindow(wxWindow* parent, wxWindowID id = wxID_ANY,
124 const wxPoint& pos = wxDefaultPosition,
125 const wxSize& size = wxDefaultSize,
126 long style = wxSP_3D,
127 const wxString& name = "splitterWindow");
128
129 /**
130 Destroys the wxSplitterWindow and its children.
131 */
132 virtual ~wxSplitterWindow();
133
134 /**
135 Creation function, for two-step construction.
136 See wxSplitterWindow() for details.
137 */
138 bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
139 const wxPoint& point = wxDefaultPosition,
140 const wxSize& size = wxDefaultSize, long style = wxSP_3D,
141 const wxString& name = "splitter");
142
143 /**
144 Returns the current minimum pane size (defaults to zero).
145
146 @see SetMinimumPaneSize()
147 */
148 int GetMinimumPaneSize() const;
149
150 /**
151 Returns the current sash gravity.
152
153 @see SetSashGravity()
154 */
155 double GetSashGravity() const;
156
157 /**
158 Returns the current sash position.
159
160 @see SetSashPosition()
161 */
162 int GetSashPosition() const;
163
164 /**
165 Returns the default sash size in pixels or 0 if it is invisible.
166
167 @see GetDefaultSashSize(), IsSashInvisible()
168 */
169 int GetSashSize() const;
170
171 /**
172 Returns the default sash size in pixels.
173
174 The size of the sash is its width for a vertically split window and its
175 height for a horizontally split one. Its other direction is the same as
176 the client size of the window in the corresponding direction.
177
178 The default sash size is platform-dependent because it conforms to the
179 current platform look-and-feel and cannot be changed.
180
181 @since 2.9.4
182 */
183 int GetDefaultSashSize() const;
184
185 /**
186 Gets the split mode.
187
188 @see SetSplitMode(), SplitVertically(), SplitHorizontally().
189 */
190 wxSplitMode GetSplitMode() const;
191
192 /**
193 Returns the left/top or only pane.
194 */
195 wxWindow* GetWindow1() const;
196
197 /**
198 Returns the right/bottom pane.
199 */
200 wxWindow* GetWindow2() const;
201
202 /**
203 Initializes the splitter window to have one pane.
204 The child window is shown if it is currently hidden.
205
206 @param window
207 The pane for the unsplit window.
208
209 @remarks This should be called if you wish to initially view only a
210 single pane in the splitter window.
211
212 @see SplitVertically(), SplitHorizontally()
213 */
214 void Initialize(wxWindow* window);
215
216 /**
217 Returns @true if the sash is invisible even when the window is split, @false otherwise.
218
219 @remark This is a shortcut for HasFlag(wxSP_NOSASH)
220
221 @see SetSashInvisible()
222
223 @since 2.9.4
224 */
225 bool IsSashInvisible() const;
226
227 /**
228 Returns @true if the window is split, @false otherwise.
229 */
230 bool IsSplit() const;
231
232 /**
233 Application-overridable function called when the sash is double-clicked with
234 the left mouse button.
235
236 @param x
237 The x position of the mouse cursor.
238 @param y
239 The y position of the mouse cursor.
240
241 @remarks The default implementation of this function calls Unsplit if the
242 minimum pane size is zero.
243
244 @see Unsplit()
245 */
246 virtual void OnDoubleClickSash(int x, int y);
247
248 /**
249 Application-overridable function called when the sash position is changed by
250 user. It may return @false to prevent the change or @true to allow it.
251
252 @param newSashPosition
253 The new sash position (always positive or zero)
254
255 @remarks The default implementation of this function verifies that the
256 sizes of both panes of the splitter are greater than
257 minimum pane size.
258 */
259 virtual bool OnSashPositionChange(int newSashPosition);
260
261 /**
262 Application-overridable function called when the window is unsplit, either
263 programmatically or using the wxSplitterWindow user interface.
264
265 @param removed
266 The window being removed.
267
268 @remarks The default implementation of this function simply hides
269 removed. You may wish to delete the window.
270 */
271 virtual void OnUnsplit(wxWindow* removed);
272
273 /**
274 This function replaces one of the windows managed by the wxSplitterWindow with
275 another one. It is in general better to use it instead of calling Unsplit()
276 and then resplitting the window back because it will provoke much less flicker
277 (if any). It is valid to call this function whether the splitter has two
278 windows or only one.
279
280 Both parameters should be non-@NULL and @a winOld must specify one of the
281 windows managed by the splitter. If the parameters are incorrect or the window
282 couldn't be replaced, @false is returned. Otherwise the function will return
283 @true, but please notice that it will not delete the replaced window and you
284 may wish to do it yourself.
285
286 @see GetMinimumPaneSize()
287 */
288 bool ReplaceWindow(wxWindow* winOld, wxWindow* winNew);
289
290 /**
291 Sets the minimum pane size.
292
293 @param paneSize
294 Minimum pane size in pixels.
295
296 @remarks The default minimum pane size is zero, which means that either
297 pane can be reduced to zero by dragging the sash, thus
298 removing one of the panes. To prevent this behaviour
299 (and veto out-of-range sash dragging), set a minimum
300 size, for example 20 pixels. If the wxSP_PERMIT_UNSPLIT
301 style is used when a splitter window is created, the
302 window may be unsplit even if minimum size is non-zero.
303
304 @see GetMinimumPaneSize()
305 */
306 void SetMinimumPaneSize(int paneSize);
307
308 /**
309 Sets the sash gravity.
310
311 @param gravity
312 The sash gravity. Value between 0.0 and 1.0.
313
314 @remarks
315 Gravity is real factor which controls position of sash while resizing
316 wxSplitterWindow. Gravity tells wxSplitterWindow how much will left/top
317 window grow while resizing.
318 Example values:
319 - 0.0: only the bottom/right window is automatically resized
320 - 0.5: both windows grow by equal size
321 - 1.0: only left/top window grows
322 Gravity should be a real value between 0.0 and 1.0.
323 Default value of sash gravity is 0.0.
324 That value is compatible with previous (before gravity was introduced)
325 behaviour of wxSplitterWindow.
326
327 @see GetSashGravity()
328 */
329 void SetSashGravity(double gravity);
330
331 /**
332 Sets the sash position.
333
334 @param position
335 The sash position in pixels.
336 @param redraw
337 If @true, resizes the panes and redraws the sash and border.
338
339 @remarks Does not currently check for an out-of-range value.
340
341 @see GetSashPosition()
342 */
343 void SetSashPosition(int position, bool redraw = true);
344
345 /**
346 Sets the split mode.
347
348 @param mode
349 Can be wxSPLIT_VERTICAL or wxSPLIT_HORIZONTAL.
350
351 @remarks Only sets the internal variable; does not update the display.
352
353 @see GetSplitMode(), SplitVertically(), SplitHorizontally().
354 */
355 void SetSplitMode(int mode);
356
357 /**
358 Sets whether the sash should be invisible, even when the window is
359 split.
360
361 When the sash is invisible, it doesn't appear on the screen at all and,
362 in particular, doesn't allow the user to resize the windows.
363
364 @remarks Only sets the internal variable; does not update the display.
365
366 @param invisible
367 If @true, the sash is always invisible, else it is shown when the
368 window is split.
369
370 @see IsSashInvisible()
371
372 @since 2.9.4
373 */
374 void SetSashInvisible(bool invisible=true);
375
376 /**
377 Initializes the top and bottom panes of the splitter window.
378 The child windows are shown if they are currently hidden.
379
380 @param window1
381 The top pane.
382 @param window2
383 The bottom pane.
384 @param sashPosition
385 The initial position of the sash. If this value is positive,
386 it specifies the size of the upper pane. If it is negative, its
387 absolute value gives the size of the lower pane.
388 Finally, specify 0 (default) to choose the default position
389 (half of the total window height).
390
391 @return @true if successful, @false otherwise (the window was already split).
392
393 @remarks This should be called if you wish to initially view two panes.
394 It can also be called at any subsequent time, but the application
395 should check that the window is not currently split using IsSplit().
396
397 @see SplitVertically(), IsSplit(), Unsplit()
398 */
399 virtual bool SplitHorizontally(wxWindow* window1, wxWindow* window2,
400 int sashPosition = 0);
401
402 /**
403 Initializes the left and right panes of the splitter window.
404 The child windows are shown if they are currently hidden.
405
406 @param window1
407 The left pane.
408 @param window2
409 The right pane.
410 @param sashPosition
411 The initial position of the sash. If this value is positive, it
412 specifies the size of the left pane. If it is negative, it is
413 absolute value gives the size of the right pane.
414 Finally, specify 0 (default) to choose the default position
415 (half of the total window width).
416
417 @return @true if successful, @false otherwise (the window was already split).
418
419 @remarks This should be called if you wish to initially view two panes.
420 It can also be called at any subsequent time, but the
421 application should check that the window is not currently
422 split using IsSplit().
423
424 @see SplitHorizontally(), IsSplit(), Unsplit().
425 */
426 virtual bool SplitVertically(wxWindow* window1, wxWindow* window2,
427 int sashPosition = 0);
428
429 /**
430 Unsplits the window.
431
432 @param toRemove
433 The pane to remove, or @NULL to remove the right or bottom pane.
434
435 @return @true if successful, @false otherwise (the window was not split).
436
437 @remarks This call will not actually delete the pane being removed; it
438 calls OnUnsplit() which can be overridden for the desired
439 behaviour. By default, the pane being removed is hidden.
440
441 @see SplitHorizontally(), SplitVertically(), IsSplit(), OnUnsplit()
442 */
443 bool Unsplit(wxWindow* toRemove = NULL);
444
445 /**
446 Causes any pending sizing of the sash and child panes to take place
447 immediately.
448
449 Such resizing normally takes place in idle time, in order to wait for
450 layout to be completed. However, this can cause unacceptable flicker as
451 the panes are resized after the window has been shown.
452 To work around this, you can perform window layout (for example by
453 sending a size event to the parent window), and then call this function,
454 before showing the top-level window.
455 */
456 void UpdateSize();
457};
458
459
460
461/**
462 @class wxSplitterEvent
463
464 This class represents the events generated by a splitter control.
465
466 Also there is only one event class, the data associated to the different events
467 is not the same and so not all accessor functions may be called for each event.
468 The documentation mentions the kind of event(s) for which the given accessor
469 function makes sense: calling it for other types of events will result
470 in assert failure (in debug mode) and will return meaningless results.
471
472 @beginEventTable{wxSplitterEvent}
473 @event{EVT_SPLITTER_SASH_POS_CHANGING(id, func)}
474 The sash position is in the process of being changed.
475 May be used to modify the position of the tracking bar to properly
476 reflect the position that would be set if the drag were to be completed
477 at this point. Processes a @c wxEVT_SPLITTER_SASH_POS_CHANGING event.
478 @event{EVT_SPLITTER_SASH_POS_CHANGED(id, func)}
479 The sash position was changed. May be used to modify the sash position
480 before it is set, or to prevent the change from taking place.
481 Processes a @c wxEVT_SPLITTER_SASH_POS_CHANGED event.
482 @event{EVT_SPLITTER_UNSPLIT(id, func)}
483 The splitter has been just unsplit. Processes a @c wxEVT_SPLITTER_UNSPLIT event.
484 @event{EVT_SPLITTER_DCLICK(id, func)}
485 The sash was double clicked. The default behaviour is to unsplit the
486 window when this happens (unless the minimum pane size has been set
487 to a value greater than zero). Processes a @c wxEVT_SPLITTER_DOUBLECLICKED event.
488 @endEventTable
489
490 @library{wxcore}
491 @category{events}
492
493 @see wxSplitterWindow, @ref overview_events
494*/
495class wxSplitterEvent : public wxNotifyEvent
496{
497public:
498 /**
499 Constructor. Used internally by wxWidgets only.
500 */
501 wxSplitterEvent(wxEventType eventType = wxEVT_NULL,
502 wxSplitterWindow* splitter = NULL);
503
504 /**
505 Returns the new sash position.
506
507 May only be called while processing
508 @c wxEVT_SPLITTER_SASH_POS_CHANGING and
509 @c wxEVT_SPLITTER_SASH_POS_CHANGED events.
510 */
511 int GetSashPosition() const;
512
513 /**
514 Returns a pointer to the window being removed when a splitter window
515 is unsplit.
516
517 May only be called while processing
518 @c wxEVT_SPLITTER_UNSPLIT events.
519 */
520 wxWindow* GetWindowBeingRemoved() const;
521
522 /**
523 Returns the x coordinate of the double-click point.
524
525 May only be called while processing
526 @c wxEVT_SPLITTER_DOUBLECLICKED events.
527 */
528 int GetX() const;
529
530 /**
531 Returns the y coordinate of the double-click point.
532
533 May only be called while processing
534 @c wxEVT_SPLITTER_DOUBLECLICKED events.
535 */
536 int GetY() const;
537
538 /**
539 In the case of @c wxEVT_SPLITTER_SASH_POS_CHANGED events,
540 sets the new sash position.
541 In the case of @c wxEVT_SPLITTER_SASH_POS_CHANGING events,
542 sets the new tracking bar position so visual feedback during dragging will
543 represent that change that will actually take place. Set to -1 from
544 the event handler code to prevent repositioning.
545
546 May only be called while processing
547 @c wxEVT_SPLITTER_SASH_POS_CHANGING and
548 @c wxEVT_SPLITTER_SASH_POS_CHANGED events.
549
550 @param pos
551 New sash position.
552 */
553 void SetSashPosition(int pos);
554};
555
556
557wxEventType wxEVT_SPLITTER_SASH_POS_CHANGED;
558wxEventType wxEVT_SPLITTER_SASH_POS_CHANGING;
559wxEventType wxEVT_SPLITTER_DOUBLECLICKED;
560wxEventType wxEVT_SPLITTER_UNSPLIT;