interface/toplevel.h

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