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     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     virtual void Iconize(bool iconize = true);
 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     virtual void Maximize(bool maximize = true);
 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     wxWindow* 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         @note In wxMSW, @a icon must be either 16x16 or 32x32 icon.
 226
 227         @see wxIcon, SetIcons()
 228     */
 229     void SetIcon(const wxIcon& icon);
 230
 231     /**
 232         Sets several icons of different sizes for this window: this allows to
 233         use different icons for different situations (e.g. task switching bar,
 234         taskbar, window title bar) instead of scaling, with possibly bad looking
 235         results, the only icon set by SetIcon().
 236
 237         @param icons
 238             The icons to associate with this window.
 239
 240         @note In wxMSW, @a icons must contain a 16x16 or 32x32 icon,
 241               preferably both.
 242
 243         @see wxIconBundle
 244     */
 245     virtual void SetIcons(const wxIconBundle& icons);
 246
 247     /**
 248         Sets action or menu activated by pressing left hardware button on the
 249         smart phones. Unavailable on full keyboard machines.
 250
 251         @param id
 252             Identifier for this button.
 253         @param label
 254             Text to be displayed on the screen area dedicated to this hardware
 255             button.
 256         @param subMenu
 257             The menu to be opened after pressing this hardware button.
 258
 259         @see SetRightMenu().
 260     */
 261     void SetLeftMenu(int id = wxID_ANY,
 262                      const wxString& label = wxEmptyString,
 263                      wxMenu* subMenu = NULL);
 264
 265     /**
 266         A simpler interface for setting the size hints than SetSizeHints().
 267     */
 268     virtual void SetMaxSize(const wxSize& size);
 269
 270     /**
 271         A simpler interface for setting the size hints than SetSizeHints().
 272     */
 273     virtual void SetMinSize(const wxSize& size);
 274
 275     /**
 276         Sets action or menu activated by pressing right hardware button on the
 277         smart phones. Unavailable on full keyboard machines.
 278
 279         @param id
 280             Identifier for this button.
 281         @param label
 282             Text to be displayed on the screen area dedicated to this hardware
 283             button.
 284         @param subMenu
 285             The menu to be opened after pressing this hardware button.
 286
 287         @see SetLeftMenu().
 288     */
 289     void SetRightMenu(int id = wxID_ANY,
 290                       const wxString& label = wxEmptyString,
 291                       wxMenu* subMenu = NULL);
 292
 293     /**
 294         If the platform supports it, sets the shape of the window to that
 295         depicted by @a region. The system will not display or respond to any
 296         mouse event for the pixels that lie outside of the region. To reset the
 297         window to the normal rectangular shape simply call SetShape() again with
 298         an empty wxRegion. Returns @true if the operation is successful.
 299     */
 300     virtual bool SetShape(const wxRegion& region);
 301
 302     /**
 303         Allows specification of minimum and maximum window sizes, and window
 304         size increments. If a pair of values is not set (or set to -1), no
 305         constraints will be used.
 306
 307         @param minW
 308             The minimum width.
 309         @param minH
 310             The minimum height.
 311         @param maxW
 312             The maximum width.
 313         @param maxH
 314             The maximum height.
 315         @param incW
 316             Specifies the increment for sizing the width (GTK/Motif/Xt only).
 317         @param incH
 318             Specifies the increment for sizing the height (GTK/Motif/Xt only).
 319
 320         @remarks Notice that this function not only prevents the user from
 321                  resizing the window outside the given bounds but it also
 322                  prevents the program itself from doing it using
 323                  wxWindow::SetSize().
 324
 325     */
 326     virtual void SetSizeHints(int minW, int minH,
 327                               int maxW = -1, int maxH = -1,
 328                               int incW = -1, int incH = -1);
 329
 330     /**
 331         Allows specification of minimum and maximum window sizes, and window
 332         size increments. If a pair of values is not set (or set to -1), no
 333         constraints will be used.
 334
 335         @param minSize
 336             The minimum size of the window.
 337         @param maxSize
 338             The maximum size of the window.
 339         @param incSize
 340             Increment size (only taken into account under X11-based ports such
 341             as wxGTK/wxMotif/wxX11).
 342
 343         @remarks Notice that this function not only prevents the user from
 344                  resizing the window outside the given bounds but it also
 345                  prevents the program itself from doing it using
 346                  wxWindow::SetSize().
 347     */
 348     void SetSizeHints(const wxSize& minSize,
 349                       const wxSize& maxSize = wxDefaultSize,
 350                       const wxSize& incSize = wxDefaultSize);
 351
 352     /**
 353         Sets the window title.
 354
 355         @param title
 356             The window title.
 357
 358         @see GetTitle()
 359     */
 360     virtual void SetTitle(const wxString& title);
 361
 362     /**
 363         If the platform supports it will set the window to be translucent.
 364
 365         @param alpha
 366             Determines how opaque or transparent the window will be, if the
 367             platform supports the opreration. A value of 0 sets the window to be
 368             fully transparent, and a value of 255 sets the window to be fully
 369             opaque.
 370     */
 371     virtual bool SetTransparent(wxByte alpha);
 372
 373     /**
 374         This virtual function is not meant to be called directly but can be
 375         overridden to return @false (it returns @true by default) to allow the
 376         application to close even if this, presumably not very important, window
 377         is still opened. By default, the application stays alive as long as
 378         there are any open top level windows.
 379     */
 380     virtual bool ShouldPreventAppExit() const;
 381
 382     /**
 383         Depending on the value of @a show parameter the window is either shown
 384         full screen or restored to its normal state. @a style is a bit list
 385         containing some or all of the following values, which indicate what
 386         elements of the window to hide in full-screen mode:
 387
 388         - @c ::wxFULLSCREEN_NOMENUBAR
 389         - @c ::wxFULLSCREEN_NOTOOLBAR
 390         - @c ::wxFULLSCREEN_NOSTATUSBAR
 391         - @c ::wxFULLSCREEN_NOBORDER
 392         - @c ::wxFULLSCREEN_NOCAPTION
 393         - @c ::wxFULLSCREEN_ALL (all of the above)
 394
 395         This function has not been tested with MDI frames.
 396
 397         @note Showing a window full screen also actually @ref wxWindow::Show()
 398               "Show()"s the window if it isn't shown.
 399
 400         @see IsFullScreen()
 401     */
 402     virtual bool ShowFullScreen(bool show, long style = wxFULLSCREEN_ALL);
 403
 404     /**
 405         This method is specific to wxUniversal port.
 406
 407         Use native or custom-drawn decorations for this window only. Notice that
 408         to have any effect this method must be called before really creating the
 409         window, i.e. two step creation must be used:
 410
 411         @code
 412         MyFrame *frame = new MyFrame;       // use default ctor
 413         frame->UseNativeDecorations(false); // change from default "true"
 414         frame->Create(parent, title, ...);  // really create the frame
 415         @endcode
 416
 417         @see UseNativeDecorationsByDefault(),
 418              IsUsingNativeDecorations()
 419     */
 420     void UseNativeDecorations(bool native = true);
 421
 422     /**
 423         This method is specific to wxUniversal port.
 424
 425         Top level windows in wxUniversal port can use either system-provided
 426         window decorations (i.e. title bar and various icons, buttons and menus
 427         in it) or draw the decorations themselves. By default the system
 428         decorations are used if they are available, but this method can be
 429         called with @a native set to @false to change this for all windows
 430         created after this point.
 431
 432         Also note that if @c WXDECOR environment variable is set, then custom
 433         decorations are used by default and so it may make sense to call this
 434         method with default argument if the application can't use custom
 435         decorations at all for some reason.
 436
 437         @see UseNativeDecorations()
 438     */
 439     void UseNativeDecorationsByDefault(bool native = true);
 440 };
 441