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     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     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     bool IsActive() const;
 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     bool IsFullScreen();
 157
 158     /**
 159         Returns @true if the window is iconized.
 160     */
 161     bool IsIconized() const;
 162
 163     /**
 164         Returns @true if the window is maximized.
 165     */
 166     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     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     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     void SetMaxSize(const wxSize& size);
 264
 265     /**
 266         A simpler interface for setting the size hints than SetSizeHints().
 267     */
 268     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     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 incW
 303             Specifies the increment for sizing the width (GTK/Motif/Xt only).
 304         @param incH
 305             Specifies the increment for sizing the height (GTK/Motif/Xt only).
 306
 307         @remarks Notice that this function not only prevents the user from
 308                  resizing the window outside the given bounds but it also
 309                  prevents the program itself from doing it using
 310                  wxWindow::SetSize().
 311
 312     */
 313     virtual void SetSizeHints(int minW, int minH, int maxW = -1,
 314                               int maxH = -1,
 315                               int incW = -1,
 316                               int incH = -1);
 317
 318     /**
 319         Allows specification of minimum and maximum window sizes, and window
 320         size increments. If a pair of values is not set (or set to -1), no
 321         constraints will be used.
 322
 323         @param incSize
 324             Increment size (only taken into account under X11-based ports such
 325             as wxGTK/wxMotif/wxX11).
 326
 327         @remarks Notice that this function not only prevents the user from
 328                  resizing the window outside the given bounds but it also
 329                  prevents the program itself from doing it using
 330                  wxWindow::SetSize().
 331     */
 332     void SetSizeHints(const wxSize& minSize,
 333                       const wxSize& maxSize = wxDefaultSize,
 334                       const wxSize& incSize = wxDefaultSize);
 335
 336     /**
 337         Sets the window title.
 338
 339         @param title
 340             The window title.
 341
 342         @see GetTitle()
 343     */
 344     virtual void SetTitle(const wxString& title);
 345
 346     /**
 347         If the platform supports it will set the window to be translucent.
 348
 349         @param alpha
 350             Determines how opaque or transparent the window will be, if the
 351             platform supports the opreration. A value of 0 sets the window to be
 352             fully transparent, and a value of 255 sets the window to be fully
 353             opaque.
 354     */
 355     virtual bool SetTransparent(int alpha);
 356
 357     /**
 358         This virtual function is not meant to be called directly but can be
 359         overridden to return @false (it returns @true by default) to allow the
 360         application to close even if this, presumably not very important, window
 361         is still opened. By default, the application stays alive as long as
 362         there are any open top level windows.
 363     */
 364     virtual bool ShouldPreventAppExit() const;
 365
 366     /**
 367         Depending on the value of @a show parameter the window is either shown
 368         full screen or restored to its normal state. @a style is a bit list
 369         containing some or all of the following values, which indicate what
 370         elements of the window to hide in full-screen mode:
 371
 372         - @c ::wxFULLSCREEN_NOMENUBAR
 373         - @c ::wxFULLSCREEN_NOTOOLBAR
 374         - @c ::wxFULLSCREEN_NOSTATUSBAR
 375         - @c ::wxFULLSCREEN_NOBORDER
 376         - @c ::wxFULLSCREEN_NOCAPTION
 377         - @c ::wxFULLSCREEN_ALL (all of the above)
 378
 379         This function has not been tested with MDI frames.
 380
 381         @note Showing a window full screen also actually @ref wxWindow::Show()
 382               "Show()"s the window if it isn't shown.
 383
 384         @see IsFullScreen()
 385     */
 386     bool ShowFullScreen(bool show, long style = wxFULLSCREEN_ALL);
 387
 388     /**
 389         This method is specific to wxUniversal port.
 390
 391         Use native or custom-drawn decorations for this window only. Notice that
 392         to have any effect this method must be called before really creating the
 393         window, i.e. two step creation must be used:
 394
 395         @code
 396         MyFrame *frame = new MyFrame;       // use default ctor
 397         frame->UseNativeDecorations(false); // change from default "true"
 398         frame->Create(parent, title, ...);  // really create the frame
 399         @endcode
 400
 401         @see UseNativeDecorationsByDefault(),
 402              IsUsingNativeDecorations()
 403     */
 404     void UseNativeDecorations(bool native = true);
 405
 406     /**
 407         This method is specific to wxUniversal port.
 408
 409         Top level windows in wxUniversal port can use either system-provided
 410         window decorations (i.e. title bar and various icons, buttons and menus
 411         in it) or draw the decorations themselves. By default the system
 412         decorations are used if they are available, but this method can be
 413         called with @a native set to @false to change this for all windows
 414         created after this point.
 415
 416         Also note that if @c WXDECOR environment variable is set, then custom
 417         decorations are used by default and so it may make sense to call this
 418         method with default argument if the application can't use custom
 419         decorations at all for some reason.
 420
 421         @see UseNativeDecorations()
 422     */
 423     void UseNativeDecorationsByDefault(bool native = true);
 424 };
 425