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