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