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