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