interface/wx/toplevel.h

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