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