]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/toplevel.h
Make storing non-trivial data in wxThreadSpecificInfo possible.
[wxWidgets.git] / interface / wx / toplevel.h
index 4dcac9e2e395cf3d387da453ed5362ac7c14ceeb..27775eb513c9809363a603ab89c2ae3ac8deae43 100644 (file)
@@ -2,8 +2,7 @@
 // Name:        toplevel.h
 // Purpose:     interface of wxTopLevelWindow
 // Author:      wxWidgets team
-// RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 /**
@@ -34,6 +33,14 @@ enum
                           wxFULLSCREEN_NOCAPTION
 };
 
+#define wxDEFAULT_FRAME_STYLE (wxSYSTEM_MENU |          \
+                               wxRESIZE_BORDER |        \
+                               wxMINIMIZE_BOX |         \
+                               wxMAXIMIZE_BOX |         \
+                               wxCLOSE_BOX |            \
+                               wxCAPTION |              \
+                               wxCLIP_CHILDREN)
+
 /**
     @class wxTopLevelWindow
 
@@ -42,14 +49,71 @@ enum
     directly, but all of its methods are also applicable for the two classes
     above.
 
+    Note that the instances of wxTopLevelWindow are managed by wxWidgets in the
+    internal top level window list.
+
+    @beginEventEmissionTable
+    @event{EVT_MAXIMIZE(id, func)}
+        Process a @c wxEVT_MAXIMIZE event. See wxMaximizeEvent.
+    @event{EVT_MOVE(func)}
+        Process a @c wxEVT_MOVE event, which is generated when a window is moved.
+        See wxMoveEvent.
+    @event{EVT_MOVE_START(func)}
+        Process a @c wxEVT_MOVE_START event, which is generated when the user starts
+        to move or size a window. wxMSW only.
+        See wxMoveEvent.
+    @event{EVT_MOVE_END(func)}
+        Process a @c wxEVT_MOVE_END event, which is generated when the user stops
+        moving or sizing a window. wxMSW only.
+        See wxMoveEvent.
+    @event{EVT_SHOW(func)}
+        Process a @c wxEVT_SHOW event. See wxShowEvent.
+    @endEventTable
+
     @library{wxcore}
     @category{managedwnd}
 
     @see wxDialog, wxFrame
 */
-class wxTopLevelWindow : public wxWindow
+class wxTopLevelWindow : public wxNonOwnedWindow
 {
 public:
+    /**
+        Default ctor.
+    */
+    wxTopLevelWindow();
+
+    /**
+        Constructor creating the top level window.
+    */
+    wxTopLevelWindow(wxWindow *parent,
+                    wxWindowID id,
+                    const wxString& title,
+                    const wxPoint& pos = wxDefaultPosition,
+                    const wxSize& size = wxDefaultSize,
+                    long style = wxDEFAULT_FRAME_STYLE,
+                    const wxString& name = wxFrameNameStr);
+
+    /**
+        Destructor. Remember that wxTopLevelWindows do not get immediately
+        destroyed when the user (or the app) closes them; they have a
+        @b delayed destruction.
+
+        See @ref overview_windowdeletion for more info.
+    */
+    virtual ~wxTopLevelWindow();
+
+    /**
+        Creates the top level window.
+    */
+    bool Create(wxWindow *parent,
+                wxWindowID id,
+                const wxString& title,
+                const wxPoint& pos = wxDefaultPosition,
+                const wxSize& size = wxDefaultSize,
+                long style = wxDEFAULT_FRAME_STYLE,
+                const wxString& name = wxFrameNameStr);
+
     /**
         Returns @true if the platform supports making the window translucent.
 
@@ -60,7 +124,7 @@ public:
     /**
         A synonym for CentreOnScreen().
     */
-    void CenterOnScreen(int direction);
+    void CenterOnScreen(int direction = wxBOTH);
 
     /**
         Centres the window on screen.
@@ -84,7 +148,7 @@ public:
         (including GTK+) where the window manager may not support this operation
         and there is no way to find out.
     */
-    bool EnableCloseButton(bool enable = true);
+    virtual bool EnableCloseButton(bool enable = true);
 
     /**
         Returns a pointer to the button which is the default for this window, or
@@ -93,13 +157,26 @@ public:
     */
     wxWindow* GetDefaultItem() const;
 
+    /**
+        Get the default size for a new top level window.
+
+        This is used internally by wxWidgets on some platforms to determine the
+        default size for a window created using ::wxDefaultSize so it is not
+        necessary to use it when creating a wxTopLevelWindow, however it may be
+        useful if a rough estimation of the window size is needed for some
+        other reason.
+
+        @since 2.9.2
+     */
+    static wxSize GetDefaultSize();
+
     /**
         Returns the standard icon of the window. The icon will be invalid if it
         hadn't been previously set by SetIcon().
 
         @see GetIcons()
     */
-    const wxIcon GetIcon() const;
+    wxIcon GetIcon() const;
 
     /**
         Returns all icons associated with the window, there will be none of them
@@ -108,14 +185,14 @@ public:
 
         @see wxIconBundle
     */
-    const wxIconBundle GetIcons() const;
+    const wxIconBundle& GetIcons() const;
 
     /**
         Gets a string containing the window title.
 
         @see SetTitle()
     */
-    wxString GetTitle() const;
+    virtual wxString GetTitle() const;
 
     /**
         Unique to the wxWinCE port. Responds to showing/hiding SIP (soft input
@@ -133,10 +210,10 @@ public:
 
         @see IsIconized(), Maximize(), wxIconizeEvent.
     */
-    void Iconize(bool iconize);
+    virtual void Iconize(bool iconize = true);
 
     /**
-        Returns @true if this window is currently active, i.e. if the user is
+        Returns @true if this window is currently active, i.e.\ if the user is
         currently working with it.
     */
     virtual bool IsActive();
@@ -153,17 +230,17 @@ public:
 
         @see ShowFullScreen()
     */
-    bool IsFullScreen();
+    virtual bool IsFullScreen() const;
 
     /**
         Returns @true if the window is iconized.
     */
-    bool IsIconized() const;
+    virtual bool IsIconized() const;
 
     /**
         Returns @true if the window is maximized.
     */
-    bool IsMaximized() const;
+    virtual bool IsMaximized() const;
 
     /**
         This method is specific to wxUniversal port.
@@ -176,6 +253,12 @@ public:
     */
     bool IsUsingNativeDecorations() const;
 
+    /**
+        See wxWindow::SetAutoLayout(): when auto layout is on, this function gets
+        called automatically when the window is resized.
+    */
+    virtual bool Layout();
+
     /**
         Maximizes or restores the window.
 
@@ -184,7 +267,34 @@ public:
 
         @see Iconize()
     */
-    void Maximize(bool maximize);
+    virtual void Maximize(bool maximize = true);
+
+    /**
+        MSW-specific function for accessing the system menu.
+
+        Returns a wxMenu pointer representing the system menu of the window
+        under MSW. The returned wxMenu may be used, if non-@c NULL, to add
+        extra items to the system menu. The usual @c wxEVT_MENU
+        events (that can be processed using @c EVT_MENU event table macro) will
+        then be generated for them. All the other wxMenu methods may be used as
+        well but notice that they won't allow you to access any standard system
+        menu items (e.g. they can't be deleted or modified in any way
+        currently).
+
+        Notice that because of the native system limitations the identifiers of
+        the items added to the system menu must be multiples of 16, otherwise
+        no events will be generated for them.
+
+        The returned pointer must @em not be deleted, it is owned by the window
+        and will be only deleted when the window itself is destroyed.
+
+        This function is not available in the other ports by design, any
+        occurrences of it in the portable code must be guarded by
+        @code #ifdef __WXMSW__ @endcode preprocessor guards.
+
+        @since 2.9.3
+     */
+    wxMenu *MSWGetSystemMenu() const;
 
     /**
         Use a system-dependent way to attract users attention to the window when
@@ -210,8 +320,13 @@ public:
 
         @see GetDefaultItem()
     */
-    void SetDefaultItem(wxWindow* win);
+    wxWindow* SetDefaultItem(wxWindow* win);
+
+    
+    wxWindow*  SetTmpDefaultItem(wxWindow * win);
+    wxWindow* GetTmpDefaultItem() const;
 
+    
     /**
         Sets the icon for this window.
 
@@ -222,7 +337,9 @@ public:
                  reference counting, the copy is very quick. It is safe to
                  delete @a icon after calling this function.
 
-        @see wxIcon
+        @note In wxMSW, @a icon must be either 16x16 or 32x32 icon.
+
+        @see wxIcon, SetIcons()
     */
     void SetIcon(const wxIcon& icon);
 
@@ -235,7 +352,10 @@ public:
         @param icons
             The icons to associate with this window.
 
-        @see wxIconBundle.
+        @note In wxMSW, @a icons must contain a 16x16 or 32x32 icon,
+              preferably both.
+
+        @see wxIconBundle
     */
     virtual void SetIcons(const wxIconBundle& icons);
 
@@ -275,7 +395,7 @@ public:
             Identifier for this button.
         @param label
             Text to be displayed on the screen area dedicated to this hardware
-            button. 
+            button.
         @param subMenu
             The menu to be opened after pressing this hardware button.
 
@@ -285,20 +405,19 @@ public:
                       const wxString& label = wxEmptyString,
                       wxMenu* subMenu = NULL);
 
-    /**
-        If the platform supports it, sets the shape of the window to that
-        depicted by @a region. The system will not display or respond to any
-        mouse event for the pixels that lie outside of the region. To reset the
-        window to the normal rectangular shape simply call SetShape() again with
-        an empty wxRegion. Returns @true if the operation is successful.
-    */
-    virtual bool SetShape(const wxRegion& region);
-
     /**
         Allows specification of minimum and maximum window sizes, and window
         size increments. If a pair of values is not set (or set to -1), no
         constraints will be used.
 
+        @param minW
+            The minimum width.
+        @param minH
+            The minimum height.
+        @param maxW
+            The maximum width.
+        @param maxH
+            The maximum height.
         @param incW
             Specifies the increment for sizing the width (GTK/Motif/Xt only).
         @param incH
@@ -310,16 +429,19 @@ public:
                  wxWindow::SetSize().
 
     */
-    virtual void SetSizeHints(int minW, int minH, int maxW = -1,
-                              int maxH = -1,
-                              int incW = -1,
-                              int incH = -1);
+    virtual void SetSizeHints(int minW, int minH,
+                              int maxW = -1, int maxH = -1,
+                              int incW = -1, int incH = -1);
 
     /**
         Allows specification of minimum and maximum window sizes, and window
         size increments. If a pair of values is not set (or set to -1), no
         constraints will be used.
 
+        @param minSize
+            The minimum size of the window.
+        @param maxSize
+            The maximum size of the window.
         @param incSize
             Increment size (only taken into account under X11-based ports such
             as wxGTK/wxMotif/wxX11).
@@ -348,11 +470,11 @@ public:
 
         @param alpha
             Determines how opaque or transparent the window will be, if the
-            platform supports the opreration. A value of 0 sets the window to be
+            platform supports the operation. A value of 0 sets the window to be
             fully transparent, and a value of 255 sets the window to be fully
             opaque.
     */
-    virtual bool SetTransparent(int alpha);
+    virtual bool SetTransparent(wxByte alpha);
 
     /**
         This virtual function is not meant to be called directly but can be
@@ -362,7 +484,45 @@ public:
         there are any open top level windows.
     */
     virtual bool ShouldPreventAppExit() const;
+    
+    /**
+        This function sets the wxTopLevelWindow's modified state on OS X,
+        which currently draws a black dot in the wxTopLevelWindow's close button.
+        On other platforms, this method does nothing.
+        
+        @see OSXIsModified()
+    */
+    virtual void OSXSetModified(bool modified);
+    
+    /**
+        Returns the current modified state of the wxTopLevelWindow on OS X.
+        On other platforms, this method does nothing.
+        
+        @see OSXSetModified()
+    */
+    virtual bool OSXIsModified() const;
+
+    /**
+        Sets the file name represented by this wxTopLevelWindow.
+
+        Under OS X, this file name is used to set the "proxy icon", which
+        appears in the window title bar near its title, corresponding to this
+        file name. Under other platforms it currently doesn't do anything but
+        it is harmless to call it now and it might be implemented to do
+        something useful in the future so you're encouraged to use it for any
+        window representing a file-based document.
+
+        @since 2.9.4
+    */
+    virtual void SetRepresentedFilename(const wxString& filename);
 
+    /**
+        Show the wxTopLevelWindow, but do not give it keyboard focus. This can be
+        used for pop up or notification windows that should not steal the current
+        focus.
+     */
+    virtual void ShowWithoutActivating();
+    
     /**
         Depending on the value of @a show parameter the window is either shown
         full screen or restored to its normal state. @a style is a bit list
@@ -383,7 +543,7 @@ public:
 
         @see IsFullScreen()
     */
-    bool ShowFullScreen(bool show, long style = wxFULLSCREEN_ALL);
+    virtual bool ShowFullScreen(bool show, long style = wxFULLSCREEN_ALL);
 
     /**
         This method is specific to wxUniversal port.
@@ -417,7 +577,7 @@ public:
         decorations are used by default and so it may make sense to call this
         method with default argument if the application can't use custom
         decorations at all for some reason.
-        
+
         @see UseNativeDecorations()
     */
     void UseNativeDecorationsByDefault(bool native = true);