]>
Commit | Line | Data |
---|---|---|
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 | @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 | @beginEventEmissionTable{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_events | |
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 |