interface/wx/toplevel.h

   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         Changes the default item for the panel, usually @a win is a button.
 320
 321         @see GetDefaultItem()
 322     */
 323     wxWindow* SetDefaultItem(wxWindow* win);
 324
 325
 326     wxWindow*  SetTmpDefaultItem(wxWindow * win);
 327     wxWindow* GetTmpDefaultItem() const;
 328
 329
 330     /**
 331         Sets the icon for this window.
 332
 333         @param icon
 334             The wxIcon to associate with this window.
 335
 336         @remarks The window takes a 'copy' of @a icon, but since it uses
 337                  reference counting, the copy is very quick. It is safe to
 338                  delete @a icon after calling this function.
 339
 340         @note In wxMSW, @a icon must be either 16x16 or 32x32 icon.
 341
 342         @see wxIcon, SetIcons()
 343     */
 344     void SetIcon(const wxIcon& icon);
 345
 346     /**
 347         Sets several icons of different sizes for this window: this allows to
 348         use different icons for different situations (e.g. task switching bar,
 349         taskbar, window title bar) instead of scaling, with possibly bad looking
 350         results, the only icon set by SetIcon().
 351
 352         @param icons
 353             The icons to associate with this window.
 354
 355         @note In wxMSW, @a icons must contain a 16x16 or 32x32 icon,
 356               preferably both.
 357
 358         @see wxIconBundle
 359     */
 360     virtual void SetIcons(const wxIconBundle& icons);
 361
 362     /**
 363         Sets action or menu activated by pressing left hardware button on the
 364         smart phones. Unavailable on full keyboard machines.
 365
 366         @param id
 367             Identifier for this button.
 368         @param label
 369             Text to be displayed on the screen area dedicated to this hardware
 370             button.
 371         @param subMenu
 372             The menu to be opened after pressing this hardware button.
 373
 374         @see SetRightMenu().
 375     */
 376     void SetLeftMenu(int id = wxID_ANY,
 377                      const wxString& label = wxEmptyString,
 378                      wxMenu* subMenu = NULL);
 379
 380     /**
 381         A simpler interface for setting the size hints than SetSizeHints().
 382     */
 383     virtual void SetMaxSize(const wxSize& size);
 384
 385     /**
 386         A simpler interface for setting the size hints than SetSizeHints().
 387     */
 388     virtual void SetMinSize(const wxSize& size);
 389
 390     /**
 391         Sets action or menu activated by pressing right hardware button on the
 392         smart phones. Unavailable on full keyboard machines.
 393
 394         @param id
 395             Identifier for this button.
 396         @param label
 397             Text to be displayed on the screen area dedicated to this hardware
 398             button.
 399         @param subMenu
 400             The menu to be opened after pressing this hardware button.
 401
 402         @see SetLeftMenu().
 403     */
 404     void SetRightMenu(int id = wxID_ANY,
 405                       const wxString& label = wxEmptyString,
 406                       wxMenu* subMenu = NULL);
 407
 408     /**
 409         Allows specification of minimum and maximum window sizes, and window
 410         size increments. If a pair of values is not set (or set to -1), no
 411         constraints will be used.
 412
 413         @param minW
 414             The minimum width.
 415         @param minH
 416             The minimum height.
 417         @param maxW
 418             The maximum width.
 419         @param maxH
 420             The maximum height.
 421         @param incW
 422             Specifies the increment for sizing the width (GTK/Motif/Xt only).
 423         @param incH
 424             Specifies the increment for sizing the height (GTK/Motif/Xt only).
 425
 426         @remarks Notice that this function not only prevents the user from
 427                  resizing the window outside the given bounds but it also
 428                  prevents the program itself from doing it using
 429                  wxWindow::SetSize().
 430
 431     */
 432     virtual void SetSizeHints(int minW, int minH,
 433                               int maxW = -1, int maxH = -1,
 434                               int incW = -1, int incH = -1);
 435
 436     /**
 437         Allows specification of minimum and maximum window sizes, and window
 438         size increments. If a pair of values is not set (or set to -1), no
 439         constraints will be used.
 440
 441         @param minSize
 442             The minimum size of the window.
 443         @param maxSize
 444             The maximum size of the window.
 445         @param incSize
 446             Increment size (only taken into account under X11-based ports such
 447             as wxGTK/wxMotif/wxX11).
 448
 449         @remarks Notice that this function not only prevents the user from
 450                  resizing the window outside the given bounds but it also
 451                  prevents the program itself from doing it using
 452                  wxWindow::SetSize().
 453     */
 454     void SetSizeHints(const wxSize& minSize,
 455                       const wxSize& maxSize = wxDefaultSize,
 456                       const wxSize& incSize = wxDefaultSize);
 457
 458     /**
 459         Sets the window title.
 460
 461         @param title
 462             The window title.
 463
 464         @see GetTitle()
 465     */
 466     virtual void SetTitle(const wxString& title);
 467
 468     /**
 469         If the platform supports it will set the window to be translucent.
 470
 471         @param alpha
 472             Determines how opaque or transparent the window will be, if the
 473             platform supports the operation. A value of 0 sets the window to be
 474             fully transparent, and a value of 255 sets the window to be fully
 475             opaque.
 476     */
 477     virtual bool SetTransparent(wxByte alpha);
 478
 479     /**
 480         This virtual function is not meant to be called directly but can be
 481         overridden to return @false (it returns @true by default) to allow the
 482         application to close even if this, presumably not very important, window
 483         is still opened. By default, the application stays alive as long as
 484         there are any open top level windows.
 485     */
 486     virtual bool ShouldPreventAppExit() const;
 487
 488     /**
 489         This function sets the wxTopLevelWindow's modified state on OS X,
 490         which currently draws a black dot in the wxTopLevelWindow's close button.
 491         On other platforms, this method does nothing.
 492
 493         @see OSXIsModified()
 494     */
 495     virtual void OSXSetModified(bool modified);
 496
 497     /**
 498         Returns the current modified state of the wxTopLevelWindow on OS X.
 499         On other platforms, this method does nothing.
 500
 501         @see OSXSetModified()
 502     */
 503     virtual bool OSXIsModified() const;
 504
 505     /**
 506         Sets the file name represented by this wxTopLevelWindow.
 507
 508         Under OS X, this file name is used to set the "proxy icon", which
 509         appears in the window title bar near its title, corresponding to this
 510         file name. Under other platforms it currently doesn't do anything but
 511         it is harmless to call it now and it might be implemented to do
 512         something useful in the future so you're encouraged to use it for any
 513         window representing a file-based document.
 514
 515         @since 2.9.4
 516     */
 517     virtual void SetRepresentedFilename(const wxString& filename);
 518
 519     /**
 520         Show the wxTopLevelWindow, but do not give it keyboard focus. This can be
 521         used for pop up or notification windows that should not steal the current
 522         focus.
 523      */
 524     virtual void ShowWithoutActivating();
 525
 526     /**
 527         Depending on the value of @a show parameter the window is either shown
 528         full screen or restored to its normal state. @a style is a bit list
 529         containing some or all of the following values, which indicate what
 530         elements of the window to hide in full-screen mode:
 531
 532         - @c ::wxFULLSCREEN_NOMENUBAR
 533         - @c ::wxFULLSCREEN_NOTOOLBAR
 534         - @c ::wxFULLSCREEN_NOSTATUSBAR
 535         - @c ::wxFULLSCREEN_NOBORDER
 536         - @c ::wxFULLSCREEN_NOCAPTION
 537         - @c ::wxFULLSCREEN_ALL (all of the above)
 538
 539         This function has not been tested with MDI frames.
 540
 541         @note Showing a window full screen also actually @ref wxWindow::Show()
 542               "Show()"s the window if it isn't shown.
 543
 544         @see IsFullScreen()
 545     */
 546     virtual bool ShowFullScreen(bool show, long style = wxFULLSCREEN_ALL);
 547
 548     /**
 549         This method is specific to wxUniversal port.
 550
 551         Use native or custom-drawn decorations for this window only. Notice that
 552         to have any effect this method must be called before really creating the
 553         window, i.e. two step creation must be used:
 554
 555         @code
 556         MyFrame *frame = new MyFrame;       // use default ctor
 557         frame->UseNativeDecorations(false); // change from default "true"
 558         frame->Create(parent, title, ...);  // really create the frame
 559         @endcode
 560
 561         @see UseNativeDecorationsByDefault(),
 562              IsUsingNativeDecorations()
 563     */
 564     void UseNativeDecorations(bool native = true);
 565
 566     /**
 567         This method is specific to wxUniversal port.
 568
 569         Top level windows in wxUniversal port can use either system-provided
 570         window decorations (i.e. title bar and various icons, buttons and menus
 571         in it) or draw the decorations themselves. By default the system
 572         decorations are used if they are available, but this method can be
 573         called with @a native set to @false to change this for all windows
 574         created after this point.
 575
 576         Also note that if @c WXDECOR environment variable is set, then custom
 577         decorations are used by default and so it may make sense to call this
 578         method with default argument if the application can't use custom
 579         decorations at all for some reason.
 580
 581         @see UseNativeDecorations()
 582     */
 583     void UseNativeDecorationsByDefault(bool native = true);
 584 };
 585