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