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