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