include/wx/toplevel.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/toplevel.h
   3 // Purpose:     declares wxTopLevelWindow class, the base class for all
   4 //              top level windows (such as frames and dialogs)
   5 // Author:      Vadim Zeitlin, Vaclav Slavik
   6 // Modified by:
   7 // Created:     06.08.01
   8 // Copyright:   (c) 2001 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
   9 //                       Vaclav Slavik <vaclav@wxwidgets.org>
  10 // Licence:     wxWindows licence
  11 ///////////////////////////////////////////////////////////////////////////////
  12
  13 #ifndef _WX_TOPLEVEL_BASE_H_
  14 #define _WX_TOPLEVEL_BASE_H_
  15
  16 // ----------------------------------------------------------------------------
  17 // headers
  18 // ----------------------------------------------------------------------------
  19
  20 #include "wx/nonownedwnd.h"
  21 #include "wx/iconbndl.h"
  22 #include "wx/containr.h"
  23 #include "wx/weakref.h"
  24
  25 // the default names for various classes
  26 extern WXDLLIMPEXP_DATA_CORE(const char) wxFrameNameStr[];
  27
  28 class WXDLLIMPEXP_FWD_CORE wxTopLevelWindowBase;
  29
  30 // ----------------------------------------------------------------------------
  31 // constants
  32 // ----------------------------------------------------------------------------
  33
  34 /*
  35     Summary of the bits used (some of them are defined in wx/frame.h and
  36     wx/dialog.h and not here):
  37
  38     +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
  39     |15|14|13|12|11|10| 9| 8| 7| 6| 5| 4| 3| 2| 1| 0|
  40     +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
  41       |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
  42       |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  \_ wxCENTRE
  43       |  |  |  |  |  |  |  |  |  |  |  |  |  |  \____ wxFRAME_NO_TASKBAR
  44       |  |  |  |  |  |  |  |  |  |  |  |  |  \_______ wxFRAME_TOOL_WINDOW
  45       |  |  |  |  |  |  |  |  |  |  |  |  \__________ wxFRAME_FLOAT_ON_PARENT
  46       |  |  |  |  |  |  |  |  |  |  |  \_____________ wxFRAME_SHAPED
  47       |  |  |  |  |  |  |  |  |  |  \________________ wxDIALOG_NO_PARENT
  48       |  |  |  |  |  |  |  |  |  \___________________ wxRESIZE_BORDER
  49       |  |  |  |  |  |  |  |  \______________________ wxTINY_CAPTION_VERT
  50       |  |  |  |  |  |  |  \_________________________
  51       |  |  |  |  |  |  \____________________________ wxMAXIMIZE_BOX
  52       |  |  |  |  |  \_______________________________ wxMINIMIZE_BOX
  53       |  |  |  |  \__________________________________ wxSYSTEM_MENU
  54       |  |  |  \_____________________________________ wxCLOSE_BOX
  55       |  |  \________________________________________ wxMAXIMIZE
  56       |  \___________________________________________ wxMINIMIZE
  57       \______________________________________________ wxSTAY_ON_TOP
  58
  59
  60     Notice that the 8 lower bits overlap with wxCENTRE and the button selection
  61     bits (wxYES, wxOK wxNO, wxCANCEL, wxAPPLY, wxCLOSE and wxNO_DEFAULT) which
  62     can be combined with the dialog style for several standard dialogs and
  63     hence shouldn't overlap with any styles which can be used for the dialogs.
  64     Additionally, wxCENTRE can be used with frames also.
  65  */
  66
  67 // style common to both wxFrame and wxDialog
  68 #define wxSTAY_ON_TOP           0x8000
  69 #define wxICONIZE               0x4000
  70 #define wxMINIMIZE              wxICONIZE
  71 #define wxMAXIMIZE              0x2000
  72 #define wxCLOSE_BOX             0x1000  // == wxHELP so can't be used with it
  73
  74 #define wxSYSTEM_MENU           0x0800
  75 #define wxMINIMIZE_BOX          0x0400
  76 #define wxMAXIMIZE_BOX          0x0200
  77
  78 #define wxTINY_CAPTION          0x0080  // clashes with wxNO_DEFAULT
  79 #define wxRESIZE_BORDER         0x0040  // == wxCLOSE
  80
  81 #if WXWIN_COMPATIBILITY_2_8
  82     // HORIZ and VERT styles are equivalent anyhow so don't use different names
  83     // for them
  84     #define wxTINY_CAPTION_HORIZ    wxTINY_CAPTION
  85     #define wxTINY_CAPTION_VERT     wxTINY_CAPTION
  86 #endif
  87
  88 #if WXWIN_COMPATIBILITY_2_6
  89
  90     // deprecated versions defined for compatibility reasons
  91     #define wxRESIZE_BOX            wxMAXIMIZE_BOX
  92     #define wxTHICK_FRAME           wxRESIZE_BORDER
  93
  94     // obsolete styles, unused any more
  95     #define wxDIALOG_MODAL          0
  96     #define wxDIALOG_MODELESS       0
  97     #define wxNO_3D                 0
  98     #define wxUSER_COLOURS          0
  99
 100 #endif // WXWIN_COMPATIBILITY_2_6
 101
 102 // default style
 103 //
 104 // under Windows CE (at least when compiling with eVC 4) we should create
 105 // top level windows without any styles at all for them to appear
 106 // "correctly", i.e. as full screen windows with a "hide" button (same as
 107 // "close" but round instead of squared and just hides the applications
 108 // instead of closing it) in the title bar
 109 #if defined(__WXWINCE__)
 110     #if defined(__SMARTPHONE__)
 111         #define wxDEFAULT_FRAME_STYLE (wxMAXIMIZE)
 112     #elif defined(__WINCE_STANDARDSDK__)
 113         #define wxDEFAULT_FRAME_STYLE (wxMAXIMIZE|wxCLOSE_BOX)
 114     #else
 115         #define wxDEFAULT_FRAME_STYLE (wxNO_BORDER)
 116     #endif
 117 #else // !__WXWINCE__
 118     #define wxDEFAULT_FRAME_STYLE \
 119             (wxSYSTEM_MENU | \
 120              wxRESIZE_BORDER | \
 121              wxMINIMIZE_BOX | \
 122              wxMAXIMIZE_BOX | \
 123              wxCLOSE_BOX | \
 124              wxCAPTION | \
 125              wxCLIP_CHILDREN)
 126 #endif
 127
 128
 129 // Dialogs are created in a special way
 130 #define wxTOPLEVEL_EX_DIALOG        0x00000008
 131
 132 // Styles for ShowFullScreen
 133 // (note that wxTopLevelWindow only handles wxFULLSCREEN_NOBORDER and
 134 //  wxFULLSCREEN_NOCAPTION; the rest is handled by wxTopLevelWindow)
 135 enum
 136 {
 137     wxFULLSCREEN_NOMENUBAR   = 0x0001,
 138     wxFULLSCREEN_NOTOOLBAR   = 0x0002,
 139     wxFULLSCREEN_NOSTATUSBAR = 0x0004,
 140     wxFULLSCREEN_NOBORDER    = 0x0008,
 141     wxFULLSCREEN_NOCAPTION   = 0x0010,
 142
 143     wxFULLSCREEN_ALL         = wxFULLSCREEN_NOMENUBAR | wxFULLSCREEN_NOTOOLBAR |
 144                                wxFULLSCREEN_NOSTATUSBAR | wxFULLSCREEN_NOBORDER |
 145                                wxFULLSCREEN_NOCAPTION
 146 };
 147
 148 // Styles for RequestUserAttention
 149 enum
 150 {
 151     wxUSER_ATTENTION_INFO = 1,
 152     wxUSER_ATTENTION_ERROR = 2
 153 };
 154
 155 // ----------------------------------------------------------------------------
 156 // wxTopLevelWindow: a top level (as opposed to child) window
 157 // ----------------------------------------------------------------------------
 158
 159 class WXDLLIMPEXP_CORE wxTopLevelWindowBase :
 160     public wxNavigationEnabled<wxNonOwnedWindow>
 161 {
 162 public:
 163     // construction
 164     wxTopLevelWindowBase();
 165     virtual ~wxTopLevelWindowBase();
 166
 167     // top level wnd state
 168     // --------------------
 169
 170     // maximize = true => maximize, otherwise - restore
 171     virtual void Maximize(bool maximize = true) = 0;
 172
 173     // undo Maximize() or Iconize()
 174     virtual void Restore() = 0;
 175
 176     // iconize = true => iconize, otherwise - restore
 177     virtual void Iconize(bool iconize = true) = 0;
 178
 179     // return true if the frame is maximized
 180     virtual bool IsMaximized() const = 0;
 181
 182     // return true if the frame is always maximized
 183     // due to native guidelines or current policy
 184     virtual bool IsAlwaysMaximized() const;
 185
 186     // return true if the frame is iconized
 187     virtual bool IsIconized() const = 0;
 188
 189     // get the frame icon
 190     wxIcon GetIcon() const;
 191
 192     // get the frame icons
 193     const wxIconBundle& GetIcons() const { return m_icons; }
 194
 195     // set the frame icon: implemented in terms of SetIcons()
 196     void SetIcon(const wxIcon& icon);
 197
 198     // set the frame icons
 199     virtual void SetIcons(const wxIconBundle& icons) { m_icons = icons; }
 200
 201     // maximize the window to cover entire screen
 202     virtual bool ShowFullScreen(bool show, long style = wxFULLSCREEN_ALL) = 0;
 203
 204     // shows the window, but doesn't activate it. If the base code is being run,
 205     // it means the port doesn't implement this method yet and so alert the user.
 206     virtual void ShowWithoutActivating() {
 207         wxFAIL_MSG("ShowWithoutActivating not implemented on this platform.");
 208     }
 209
 210     // return true if the frame is in fullscreen mode
 211     virtual bool IsFullScreen() const = 0;
 212
 213     // the title of the top level window: the text which the
 214     // window shows usually at the top of the frame/dialog in dedicated bar
 215     virtual void SetTitle(const wxString& title) = 0;
 216     virtual wxString GetTitle() const = 0;
 217
 218     // enable/disable close button [x]
 219     virtual bool EnableCloseButton(bool WXUNUSED(enable) ) { return false; }
 220
 221     // Attracts the users attention to this window if the application is
 222     // inactive (should be called when a background event occurs)
 223     virtual void RequestUserAttention(int flags = wxUSER_ATTENTION_INFO);
 224
 225     // Is this the active frame (highlighted in the taskbar)?
 226     //
 227     // A TLW is active only if it contains the currently focused window.
 228     virtual bool IsActive() { return IsDescendant(FindFocus()); }
 229
 230     // this function may be overridden to return false to allow closing the
 231     // application even when this top level window is still open
 232     //
 233     // notice that the window is still closed prior to the application exit and
 234     // so it can still veto it even if it returns false from here
 235     virtual bool ShouldPreventAppExit() const { return true; }
 236
 237
 238 #if defined(__SMARTPHONE__)
 239     virtual void SetLeftMenu(int id = wxID_ANY, const wxString& label = wxEmptyString, wxMenu *subMenu = NULL) = 0;
 240     virtual void SetRightMenu(int id = wxID_ANY, const wxString& label = wxEmptyString, wxMenu *subMenu = NULL) = 0;
 241 #endif // __SMARTPHONE__
 242
 243     // centre the window on screen: this is just a shortcut
 244     void CentreOnScreen(int dir = wxBOTH) { DoCentre(dir | wxCENTRE_ON_SCREEN); }
 245     void CenterOnScreen(int dir = wxBOTH) { CentreOnScreen(dir); }
 246
 247     // Get the default size for a new top level window. This is used when
 248     // creating a wxTLW under some platforms if no explicit size given.
 249     static wxSize GetDefaultSize();
 250
 251
 252     // default item access: we have a permanent default item which is the one
 253     // set by the user code but we may also have a temporary default item which
 254     // would be chosen if the user pressed "Enter" now but the default action
 255     // reverts to the "permanent" default as soon as this temporary default
 256     // item loses focus
 257
 258     // get the default item, temporary or permanent
 259     wxWindow *GetDefaultItem() const
 260         { return m_winTmpDefault ? m_winTmpDefault : m_winDefault; }
 261
 262     // set the permanent default item, return the old default
 263     wxWindow *SetDefaultItem(wxWindow *win)
 264         { wxWindow *old = GetDefaultItem(); m_winDefault = win; return old; }
 265
 266     // return the temporary default item, can be NULL
 267     wxWindow *GetTmpDefaultItem() const { return m_winTmpDefault; }
 268
 269     // set a temporary default item, SetTmpDefaultItem(NULL) should be called
 270     // soon after a call to SetTmpDefaultItem(window), return the old default
 271     wxWindow *SetTmpDefaultItem(wxWindow *win)
 272         { wxWindow *old = GetDefaultItem(); m_winTmpDefault = win; return old; }
 273
 274     // implementation only from now on
 275     // -------------------------------
 276
 277     // override some base class virtuals
 278     virtual bool Destroy();
 279     virtual bool IsTopLevel() const { return true; }
 280     virtual bool IsTopNavigationDomain() const { return true; }
 281     virtual bool IsVisible() const { return IsShown(); }
 282
 283     // event handlers
 284     void OnCloseWindow(wxCloseEvent& event);
 285     void OnSize(wxSizeEvent& WXUNUSED(event)) { DoLayout(); }
 286
 287     // Get rect to be used to center top-level children
 288     virtual void GetRectForTopLevelChildren(int *x, int *y, int *w, int *h);
 289
 290     // this should go away, but for now it's called from docview.cpp,
 291     // so should be there for all platforms
 292     void OnActivate(wxActivateEvent &WXUNUSED(event)) { }
 293
 294     // do the window-specific processing after processing the update event
 295     virtual void DoUpdateWindowUI(wxUpdateUIEvent& event) ;
 296
 297     // a different API for SetSizeHints
 298     virtual void SetMinSize(const wxSize& minSize);
 299     virtual void SetMaxSize(const wxSize& maxSize);
 300
 301     virtual void OSXSetModified(bool modified) { m_modified = modified; }
 302     virtual bool OSXIsModified() const { return m_modified; }
 303
 304     virtual void SetRepresentedFilename(const wxString& WXUNUSED(filename)) { }
 305
 306 #if wxUSE_MENUS || wxUSE_TOOLBAR
 307     // show help text for the currently selected menu or toolbar item
 308     // (typically in the status bar) or hide it and restore the status bar text
 309     // originally shown before the menu was opened if show == false
 310     virtual void DoGiveHelp(const wxString& WXUNUSED(text), bool WXUNUSED(show))  {}
 311 #endif
 312
 313 protected:
 314     // the frame client to screen translation should take account of the
 315     // toolbar which may shift the origin of the client area
 316     virtual void DoClientToScreen(int *x, int *y) const;
 317     virtual void DoScreenToClient(int *x, int *y) const;
 318
 319     // add support for wxCENTRE_ON_SCREEN
 320     virtual void DoCentre(int dir);
 321
 322     // no need to do client to screen translation to get our position in screen
 323     // coordinates: this is already the case
 324     virtual void DoGetScreenPosition(int *x, int *y) const
 325     {
 326         DoGetPosition(x, y);
 327     }
 328
 329     // test whether this window makes part of the frame
 330     // (menubar, toolbar and statusbar are excluded from automatic layout)
 331     virtual bool IsOneOfBars(const wxWindow *WXUNUSED(win)) const
 332         { return false; }
 333
 334     // check if we should exit the program after deleting this window
 335     bool IsLastBeforeExit() const;
 336
 337     // send the iconize event, return true if processed
 338     bool SendIconizeEvent(bool iconized = true);
 339
 340     // do TLW-specific layout: we resize our unique child to fill the entire
 341     // client area
 342     void DoLayout();
 343
 344     static int WidthDefault(int w) { return w == wxDefaultCoord ? GetDefaultSize().x : w; }
 345     static int HeightDefault(int h) { return h == wxDefaultCoord ? GetDefaultSize().y : h; }
 346
 347
 348     // the frame icon
 349     wxIconBundle m_icons;
 350
 351     // a default window (usually a button) or NULL
 352     wxWindowRef m_winDefault;
 353
 354     // a temporary override of m_winDefault, use the latter if NULL
 355     wxWindowRef m_winTmpDefault;
 356
 357     bool m_modified;
 358
 359     wxDECLARE_NO_COPY_CLASS(wxTopLevelWindowBase);
 360     DECLARE_EVENT_TABLE()
 361 };
 362
 363
 364 // include the real class declaration
 365 #if defined(__WXMSW__)
 366     #include "wx/msw/toplevel.h"
 367     #define wxTopLevelWindowNative wxTopLevelWindowMSW
 368 #elif defined(__WXGTK20__)
 369     #include "wx/gtk/toplevel.h"
 370     #define wxTopLevelWindowNative wxTopLevelWindowGTK
 371 #elif defined(__WXGTK__)
 372     #include "wx/gtk1/toplevel.h"
 373     #define wxTopLevelWindowNative wxTopLevelWindowGTK
 374 #elif defined(__WXX11__)
 375     #include "wx/x11/toplevel.h"
 376     #define wxTopLevelWindowNative wxTopLevelWindowX11
 377 #elif defined(__WXDFB__)
 378     #include "wx/dfb/toplevel.h"
 379     #define wxTopLevelWindowNative wxTopLevelWindowDFB
 380 #elif defined(__WXMAC__)
 381     #include "wx/osx/toplevel.h"
 382     #define wxTopLevelWindowNative wxTopLevelWindowMac
 383 #elif defined(__WXCOCOA__)
 384     #include "wx/cocoa/toplevel.h"
 385     #define wxTopLevelWindowNative wxTopLevelWindowCocoa
 386 #elif defined(__WXPM__)
 387     #include "wx/os2/toplevel.h"
 388     #define wxTopLevelWindowNative wxTopLevelWindowOS2
 389 #elif defined(__WXMOTIF__)
 390     #include "wx/motif/toplevel.h"
 391     #define wxTopLevelWindowNative wxTopLevelWindowMotif
 392 #endif
 393
 394 #ifdef __WXUNIVERSAL__
 395     #include "wx/univ/toplevel.h"
 396 #else // !__WXUNIVERSAL__
 397     class WXDLLIMPEXP_CORE wxTopLevelWindow : public wxTopLevelWindowNative
 398     {
 399     public:
 400         // construction
 401         wxTopLevelWindow() { }
 402         wxTopLevelWindow(wxWindow *parent,
 403                    wxWindowID winid,
 404                    const wxString& title,
 405                    const wxPoint& pos = wxDefaultPosition,
 406                    const wxSize& size = wxDefaultSize,
 407                    long style = wxDEFAULT_FRAME_STYLE,
 408                    const wxString& name = wxFrameNameStr)
 409             : wxTopLevelWindowNative(parent, winid, title,
 410                                      pos, size, style, name)
 411         {
 412         }
 413
 414         DECLARE_DYNAMIC_CLASS_NO_COPY(wxTopLevelWindow)
 415     };
 416 #endif // __WXUNIVERSAL__/!__WXUNIVERSAL__
 417
 418 #endif // _WX_TOPLEVEL_BASE_H_