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