]>
Commit | Line | Data |
---|---|---|
1 | ///////////////////////////////////////////////////////////////////////////// | |
2 | // Name: toplevel.h | |
3 | // Purpose: interface of wxTopLevelWindow | |
4 | // Author: wxWidgets team | |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows licence | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | /** | |
10 | Styles used with wxTopLevelWindow::RequestUserAttention(). | |
11 | */ | |
12 | enum | |
13 | { | |
14 | wxUSER_ATTENTION_INFO = 1, ///< Requests user attention, | |
15 | wxUSER_ATTENTION_ERROR = 2 ///< Results in a more drastic action. | |
16 | }; | |
17 | ||
18 | /** | |
19 | Styles used with wxTopLevelWindow::ShowFullScreen(). | |
20 | */ | |
21 | enum | |
22 | { | |
23 | wxFULLSCREEN_NOMENUBAR = 0x0001, ///< Don't display the menu bar. | |
24 | wxFULLSCREEN_NOTOOLBAR = 0x0002, ///< Don't display toolbar bars. | |
25 | wxFULLSCREEN_NOSTATUSBAR = 0x0004, ///< Don't display the status bar. | |
26 | wxFULLSCREEN_NOBORDER = 0x0008, ///< Don't display any border. | |
27 | wxFULLSCREEN_NOCAPTION = 0x0010, ///< Don't display a caption. | |
28 | ||
29 | /** | |
30 | Combination of all above, will display the least possible. | |
31 | */ | |
32 | wxFULLSCREEN_ALL = wxFULLSCREEN_NOMENUBAR | wxFULLSCREEN_NOTOOLBAR | | |
33 | wxFULLSCREEN_NOSTATUSBAR | wxFULLSCREEN_NOBORDER | | |
34 | wxFULLSCREEN_NOCAPTION | |
35 | }; | |
36 | ||
37 | /** | |
38 | @class wxTopLevelWindow | |
39 | ||
40 | wxTopLevelWindow is a common base class for wxDialog and wxFrame. It is an | |
41 | abstract base class meaning that you never work with objects of this class | |
42 | directly, but all of its methods are also applicable for the two classes | |
43 | above. | |
44 | ||
45 | Note that the instances of wxTopLevelWindow are managed by wxWidgets in the | |
46 | internal top level window list. | |
47 | ||
48 | @beginEventEmissionTable | |
49 | @event{EVT_MAXIMIZE(id, func)} | |
50 | Process a @c wxEVT_MAXIMIZE event. See wxMaximizeEvent. | |
51 | @event{EVT_MOVE(func)} | |
52 | Process a @c wxEVT_MOVE event, which is generated when a window is moved. | |
53 | See wxMoveEvent. | |
54 | @event{EVT_MOVE_START(func)} | |
55 | Process a @c wxEVT_MOVE_START event, which is generated when the user starts | |
56 | to move or size a window. wxMSW only. | |
57 | See wxMoveEvent. | |
58 | @event{EVT_MOVE_END(func)} | |
59 | Process a @c wxEVT_MOVE_END event, which is generated when the user stops | |
60 | moving or sizing a window. wxMSW only. | |
61 | See wxMoveEvent. | |
62 | @event{EVT_SHOW(func)} | |
63 | Process a @c wxEVT_SHOW event. See wxShowEvent. | |
64 | @endEventTable | |
65 | ||
66 | @library{wxcore} | |
67 | @category{managedwnd} | |
68 | ||
69 | @see wxDialog, wxFrame | |
70 | */ | |
71 | class wxTopLevelWindow : public wxWindow | |
72 | { | |
73 | public: | |
74 | /** | |
75 | Default ctor. | |
76 | */ | |
77 | wxTopLevelWindow(); | |
78 | ||
79 | /** | |
80 | Constructor creating the top level window. | |
81 | */ | |
82 | wxTopLevelWindow(wxWindow *parent, | |
83 | wxWindowID id, | |
84 | const wxString& title, | |
85 | const wxPoint& pos = wxDefaultPosition, | |
86 | const wxSize& size = wxDefaultSize, | |
87 | long style = wxDEFAULT_FRAME_STYLE, | |
88 | const wxString& name = wxFrameNameStr); | |
89 | ||
90 | /** | |
91 | Destructor. Remember that wxTopLevelWindows do not get immediately | |
92 | destroyed when the user (or the app) closes them; they have a | |
93 | @b delayed destruction. | |
94 | ||
95 | See @ref overview_windowdeletion for more info. | |
96 | */ | |
97 | virtual ~wxTopLevelWindow(); | |
98 | ||
99 | /** | |
100 | Creates the top level window. | |
101 | */ | |
102 | bool Create(wxWindow *parent, | |
103 | wxWindowID id, | |
104 | const wxString& title, | |
105 | const wxPoint& pos = wxDefaultPosition, | |
106 | const wxSize& size = wxDefaultSize, | |
107 | long style = wxDEFAULT_FRAME_STYLE, | |
108 | const wxString& name = wxFrameNameStr); | |
109 | ||
110 | /** | |
111 | Returns @true if the platform supports making the window translucent. | |
112 | ||
113 | @see SetTransparent() | |
114 | */ | |
115 | virtual bool CanSetTransparent(); | |
116 | ||
117 | /** | |
118 | A synonym for CentreOnScreen(). | |
119 | */ | |
120 | void CenterOnScreen(int direction); | |
121 | ||
122 | /** | |
123 | Centres the window on screen. | |
124 | ||
125 | @param direction | |
126 | Specifies the direction for the centering. May be @c wxHORIZONTAL, | |
127 | @c wxVERTICAL or @c wxBOTH. | |
128 | ||
129 | @see wxWindow::CentreOnParent() | |
130 | */ | |
131 | void CentreOnScreen(int direction = wxBOTH); | |
132 | ||
133 | /** | |
134 | Enables or disables the Close button (most often in the right upper | |
135 | corner of a dialog) and the Close entry of the system menu (most often | |
136 | in the left upper corner of the dialog). | |
137 | ||
138 | Currently only implemented for wxMSW and wxGTK. | |
139 | ||
140 | Returns @true if operation was successful. This may be wrong on X11 | |
141 | (including GTK+) where the window manager may not support this operation | |
142 | and there is no way to find out. | |
143 | */ | |
144 | virtual bool EnableCloseButton(bool enable = true); | |
145 | ||
146 | /** | |
147 | Returns a pointer to the button which is the default for this window, or | |
148 | @c @NULL. The default button is the one activated by pressing the Enter | |
149 | key. | |
150 | */ | |
151 | wxWindow* GetDefaultItem() const; | |
152 | ||
153 | /** | |
154 | Get the default size for a new top level window. | |
155 | ||
156 | This is used internally by wxWidgets on some platforms to determine the | |
157 | default size for a window created using ::wxDefaultSize so it is not | |
158 | necessary to use it when creating a wxTopLevelWindow, however it may be | |
159 | useful if a rough estimation of the window size is needed for some | |
160 | other reason. | |
161 | ||
162 | @since 2.9.2 | |
163 | */ | |
164 | static wxSize GetDefaultSize(); | |
165 | ||
166 | /** | |
167 | Returns the standard icon of the window. The icon will be invalid if it | |
168 | hadn't been previously set by SetIcon(). | |
169 | ||
170 | @see GetIcons() | |
171 | */ | |
172 | wxIcon GetIcon() const; | |
173 | ||
174 | /** | |
175 | Returns all icons associated with the window, there will be none of them | |
176 | if neither SetIcon() nor SetIcons() had been called before. Use | |
177 | GetIcon() to get the main icon of the window. | |
178 | ||
179 | @see wxIconBundle | |
180 | */ | |
181 | const wxIconBundle& GetIcons() const; | |
182 | ||
183 | /** | |
184 | Gets a string containing the window title. | |
185 | ||
186 | @see SetTitle() | |
187 | */ | |
188 | virtual wxString GetTitle() const; | |
189 | ||
190 | /** | |
191 | Unique to the wxWinCE port. Responds to showing/hiding SIP (soft input | |
192 | panel) area and resize window accordingly. Override this if you want to | |
193 | avoid resizing or do additional operations. | |
194 | */ | |
195 | virtual bool HandleSettingChange(WXWPARAM wParam, | |
196 | WXLPARAM lParam); | |
197 | ||
198 | /** | |
199 | Iconizes or restores the window. | |
200 | ||
201 | @param iconize | |
202 | If @true, iconizes the window; if @false, shows and restores it. | |
203 | ||
204 | @see IsIconized(), Maximize(), wxIconizeEvent. | |
205 | */ | |
206 | virtual void Iconize(bool iconize = true); | |
207 | ||
208 | /** | |
209 | Returns @true if this window is currently active, i.e. if the user is | |
210 | currently working with it. | |
211 | */ | |
212 | virtual bool IsActive(); | |
213 | ||
214 | /** | |
215 | Returns @true if this window is expected to be always maximized, either | |
216 | due to platform policy or due to local policy regarding particular | |
217 | class. | |
218 | */ | |
219 | virtual bool IsAlwaysMaximized() const; | |
220 | ||
221 | /** | |
222 | Returns @true if the window is in fullscreen mode. | |
223 | ||
224 | @see ShowFullScreen() | |
225 | */ | |
226 | virtual bool IsFullScreen() const; | |
227 | ||
228 | /** | |
229 | Returns @true if the window is iconized. | |
230 | */ | |
231 | virtual bool IsIconized() const; | |
232 | ||
233 | /** | |
234 | Returns @true if the window is maximized. | |
235 | */ | |
236 | virtual bool IsMaximized() const; | |
237 | ||
238 | /** | |
239 | This method is specific to wxUniversal port. | |
240 | ||
241 | Returns @true if this window is using native decorations, @false if we | |
242 | draw them ourselves. | |
243 | ||
244 | @see UseNativeDecorations(), | |
245 | UseNativeDecorationsByDefault() | |
246 | */ | |
247 | bool IsUsingNativeDecorations() const; | |
248 | ||
249 | /** | |
250 | See wxWindow::SetAutoLayout(): when auto layout is on, this function gets | |
251 | called automatically when the window is resized. | |
252 | */ | |
253 | virtual bool Layout(); | |
254 | ||
255 | /** | |
256 | Maximizes or restores the window. | |
257 | ||
258 | @param maximize | |
259 | If @true, maximizes the window, otherwise it restores it. | |
260 | ||
261 | @see Iconize() | |
262 | */ | |
263 | virtual void Maximize(bool maximize = true); | |
264 | ||
265 | /** | |
266 | Use a system-dependent way to attract users attention to the window when | |
267 | it is in background. | |
268 | ||
269 | @a flags may have the value of either @c ::wxUSER_ATTENTION_INFO | |
270 | (default) or @c ::wxUSER_ATTENTION_ERROR which results in a more drastic | |
271 | action. When in doubt, use the default value. | |
272 | ||
273 | ||
274 | @note This function should normally be only used when the application | |
275 | is not already in foreground. | |
276 | ||
277 | This function is currently implemented for Win32 where it flashes | |
278 | the window icon in the taskbar, and for wxGTK with task bars | |
279 | supporting it. | |
280 | ||
281 | */ | |
282 | virtual void RequestUserAttention(int flags = wxUSER_ATTENTION_INFO); | |
283 | ||
284 | /** | |
285 | Changes the default item for the panel, usually @a win is a button. | |
286 | ||
287 | @see GetDefaultItem() | |
288 | */ | |
289 | wxWindow* SetDefaultItem(wxWindow* win); | |
290 | ||
291 | ||
292 | wxWindow* SetTmpDefaultItem(wxWindow * win); | |
293 | wxWindow* GetTmpDefaultItem() const; | |
294 | ||
295 | ||
296 | /** | |
297 | Sets the icon for this window. | |
298 | ||
299 | @param icon | |
300 | The wxIcon to associate with this window. | |
301 | ||
302 | @remarks The window takes a 'copy' of @a icon, but since it uses | |
303 | reference counting, the copy is very quick. It is safe to | |
304 | delete @a icon after calling this function. | |
305 | ||
306 | @note In wxMSW, @a icon must be either 16x16 or 32x32 icon. | |
307 | ||
308 | @see wxIcon, SetIcons() | |
309 | */ | |
310 | void SetIcon(const wxIcon& icon); | |
311 | ||
312 | /** | |
313 | Sets several icons of different sizes for this window: this allows to | |
314 | use different icons for different situations (e.g. task switching bar, | |
315 | taskbar, window title bar) instead of scaling, with possibly bad looking | |
316 | results, the only icon set by SetIcon(). | |
317 | ||
318 | @param icons | |
319 | The icons to associate with this window. | |
320 | ||
321 | @note In wxMSW, @a icons must contain a 16x16 or 32x32 icon, | |
322 | preferably both. | |
323 | ||
324 | @see wxIconBundle | |
325 | */ | |
326 | virtual void SetIcons(const wxIconBundle& icons); | |
327 | ||
328 | /** | |
329 | Sets action or menu activated by pressing left hardware button on the | |
330 | smart phones. Unavailable on full keyboard machines. | |
331 | ||
332 | @param id | |
333 | Identifier for this button. | |
334 | @param label | |
335 | Text to be displayed on the screen area dedicated to this hardware | |
336 | button. | |
337 | @param subMenu | |
338 | The menu to be opened after pressing this hardware button. | |
339 | ||
340 | @see SetRightMenu(). | |
341 | */ | |
342 | void SetLeftMenu(int id = wxID_ANY, | |
343 | const wxString& label = wxEmptyString, | |
344 | wxMenu* subMenu = NULL); | |
345 | ||
346 | /** | |
347 | A simpler interface for setting the size hints than SetSizeHints(). | |
348 | */ | |
349 | virtual void SetMaxSize(const wxSize& size); | |
350 | ||
351 | /** | |
352 | A simpler interface for setting the size hints than SetSizeHints(). | |
353 | */ | |
354 | virtual void SetMinSize(const wxSize& size); | |
355 | ||
356 | /** | |
357 | Sets action or menu activated by pressing right hardware button on the | |
358 | smart phones. Unavailable on full keyboard machines. | |
359 | ||
360 | @param id | |
361 | Identifier for this button. | |
362 | @param label | |
363 | Text to be displayed on the screen area dedicated to this hardware | |
364 | button. | |
365 | @param subMenu | |
366 | The menu to be opened after pressing this hardware button. | |
367 | ||
368 | @see SetLeftMenu(). | |
369 | */ | |
370 | void SetRightMenu(int id = wxID_ANY, | |
371 | const wxString& label = wxEmptyString, | |
372 | wxMenu* subMenu = NULL); | |
373 | ||
374 | /** | |
375 | If the platform supports it, sets the shape of the window to that | |
376 | depicted by @a region. The system will not display or respond to any | |
377 | mouse event for the pixels that lie outside of the region. To reset the | |
378 | window to the normal rectangular shape simply call SetShape() again with | |
379 | an empty wxRegion. Returns @true if the operation is successful. | |
380 | */ | |
381 | virtual bool SetShape(const wxRegion& region); | |
382 | ||
383 | /** | |
384 | Allows specification of minimum and maximum window sizes, and window | |
385 | size increments. If a pair of values is not set (or set to -1), no | |
386 | constraints will be used. | |
387 | ||
388 | @param minW | |
389 | The minimum width. | |
390 | @param minH | |
391 | The minimum height. | |
392 | @param maxW | |
393 | The maximum width. | |
394 | @param maxH | |
395 | The maximum height. | |
396 | @param incW | |
397 | Specifies the increment for sizing the width (GTK/Motif/Xt only). | |
398 | @param incH | |
399 | Specifies the increment for sizing the height (GTK/Motif/Xt only). | |
400 | ||
401 | @remarks Notice that this function not only prevents the user from | |
402 | resizing the window outside the given bounds but it also | |
403 | prevents the program itself from doing it using | |
404 | wxWindow::SetSize(). | |
405 | ||
406 | */ | |
407 | virtual void SetSizeHints(int minW, int minH, | |
408 | int maxW = -1, int maxH = -1, | |
409 | int incW = -1, int incH = -1); | |
410 | ||
411 | /** | |
412 | Allows specification of minimum and maximum window sizes, and window | |
413 | size increments. If a pair of values is not set (or set to -1), no | |
414 | constraints will be used. | |
415 | ||
416 | @param minSize | |
417 | The minimum size of the window. | |
418 | @param maxSize | |
419 | The maximum size of the window. | |
420 | @param incSize | |
421 | Increment size (only taken into account under X11-based ports such | |
422 | as wxGTK/wxMotif/wxX11). | |
423 | ||
424 | @remarks Notice that this function not only prevents the user from | |
425 | resizing the window outside the given bounds but it also | |
426 | prevents the program itself from doing it using | |
427 | wxWindow::SetSize(). | |
428 | */ | |
429 | void SetSizeHints(const wxSize& minSize, | |
430 | const wxSize& maxSize = wxDefaultSize, | |
431 | const wxSize& incSize = wxDefaultSize); | |
432 | ||
433 | /** | |
434 | Sets the window title. | |
435 | ||
436 | @param title | |
437 | The window title. | |
438 | ||
439 | @see GetTitle() | |
440 | */ | |
441 | virtual void SetTitle(const wxString& title); | |
442 | ||
443 | /** | |
444 | If the platform supports it will set the window to be translucent. | |
445 | ||
446 | @param alpha | |
447 | Determines how opaque or transparent the window will be, if the | |
448 | platform supports the operation. A value of 0 sets the window to be | |
449 | fully transparent, and a value of 255 sets the window to be fully | |
450 | opaque. | |
451 | */ | |
452 | virtual bool SetTransparent(wxByte alpha); | |
453 | ||
454 | /** | |
455 | This virtual function is not meant to be called directly but can be | |
456 | overridden to return @false (it returns @true by default) to allow the | |
457 | application to close even if this, presumably not very important, window | |
458 | is still opened. By default, the application stays alive as long as | |
459 | there are any open top level windows. | |
460 | */ | |
461 | virtual bool ShouldPreventAppExit() const; | |
462 | ||
463 | /** | |
464 | This function sets the wxTopLevelWindow's modified state on OS X, | |
465 | which currently draws a black dot in the wxTopLevelWindow's close button. | |
466 | On other platforms, this method does nothing. | |
467 | ||
468 | @see OSXIsModified() | |
469 | */ | |
470 | virtual void OSXSetModified(bool modified); | |
471 | ||
472 | /** | |
473 | Returns the current modified state of the wxTopLevelWindow on OS X. | |
474 | On other platforms, this method does nothing. | |
475 | ||
476 | @see OSXSetModified() | |
477 | */ | |
478 | virtual bool OSXIsModified() const; | |
479 | ||
480 | /** | |
481 | Depending on the value of @a show parameter the window is either shown | |
482 | full screen or restored to its normal state. @a style is a bit list | |
483 | containing some or all of the following values, which indicate what | |
484 | elements of the window to hide in full-screen mode: | |
485 | ||
486 | - @c ::wxFULLSCREEN_NOMENUBAR | |
487 | - @c ::wxFULLSCREEN_NOTOOLBAR | |
488 | - @c ::wxFULLSCREEN_NOSTATUSBAR | |
489 | - @c ::wxFULLSCREEN_NOBORDER | |
490 | - @c ::wxFULLSCREEN_NOCAPTION | |
491 | - @c ::wxFULLSCREEN_ALL (all of the above) | |
492 | ||
493 | This function has not been tested with MDI frames. | |
494 | ||
495 | @note Showing a window full screen also actually @ref wxWindow::Show() | |
496 | "Show()"s the window if it isn't shown. | |
497 | ||
498 | @see IsFullScreen() | |
499 | */ | |
500 | virtual bool ShowFullScreen(bool show, long style = wxFULLSCREEN_ALL); | |
501 | ||
502 | /** | |
503 | This method is specific to wxUniversal port. | |
504 | ||
505 | Use native or custom-drawn decorations for this window only. Notice that | |
506 | to have any effect this method must be called before really creating the | |
507 | window, i.e. two step creation must be used: | |
508 | ||
509 | @code | |
510 | MyFrame *frame = new MyFrame; // use default ctor | |
511 | frame->UseNativeDecorations(false); // change from default "true" | |
512 | frame->Create(parent, title, ...); // really create the frame | |
513 | @endcode | |
514 | ||
515 | @see UseNativeDecorationsByDefault(), | |
516 | IsUsingNativeDecorations() | |
517 | */ | |
518 | void UseNativeDecorations(bool native = true); | |
519 | ||
520 | /** | |
521 | This method is specific to wxUniversal port. | |
522 | ||
523 | Top level windows in wxUniversal port can use either system-provided | |
524 | window decorations (i.e. title bar and various icons, buttons and menus | |
525 | in it) or draw the decorations themselves. By default the system | |
526 | decorations are used if they are available, but this method can be | |
527 | called with @a native set to @false to change this for all windows | |
528 | created after this point. | |
529 | ||
530 | Also note that if @c WXDECOR environment variable is set, then custom | |
531 | decorations are used by default and so it may make sense to call this | |
532 | method with default argument if the application can't use custom | |
533 | decorations at all for some reason. | |
534 | ||
535 | @see UseNativeDecorations() | |
536 | */ | |
537 | void UseNativeDecorationsByDefault(bool native = true); | |
538 | }; | |
539 |