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