adding a app-defined event seems to quit inner eventloops like eg the popup of the...

[wxWidgets.git] / interface / wx / window.h

diff --git a/interface/wx/window.h b/interface/wx/window.h
index ac715f76f78013e6cd58010cffe980b963d301bb..524605b00411608811b084d2405475e8ea8e0712 100644 (file)
--- a/interface/wx/window.h
+++ b/interface/wx/window.h
@@ -50,6 +50,28 @@ enum wxShowEffect
     wxSHOW_EFFECT_EXPAND
 };
 
     wxSHOW_EFFECT_EXPAND
 };
 

+
+
+/**
+    Struct containing all the visual attributes of a control.
+*/
+struct  wxVisualAttributes
+{
+    /// The font used for control label/text inside it.
+    wxFont font;
+
+    /// The foreground colour.
+    wxColour colFg;
+
+    /**
+        The background colour.
+
+        May be wxNullColour if the controls background colour is not solid.
+     */
+    wxColour colBg;
+};
+
+

 /**
     Different window variants, on platforms like eg mac uses different
     rendering sizes.
 /**
     Different window variants, on platforms like eg mac uses different
     rendering sizes.


@@ -218,9 +240,13 @@ enum wxWindowVariant
         See wxKeyEvent.
     @event{EVT_KEY_UP(func)}
         Process a @c wxEVT_KEY_UP event (any key has been released).
         See wxKeyEvent.
     @event{EVT_KEY_UP(func)}
         Process a @c wxEVT_KEY_UP event (any key has been released).

+        See wxKeyEvent.

     @event{EVT_CHAR(func)}
         Process a @c wxEVT_CHAR event.
         See wxKeyEvent.
     @event{EVT_CHAR(func)}
         Process a @c wxEVT_CHAR event.
         See wxKeyEvent.

+    @event{EVT_CHAR_HOOK(func)}
+        Process a @c wxEVT_CHAR_HOOK event.
+        See wxKeyEvent.

     @event{EVT_MOUSE_CAPTURE_LOST(func)}
         Process a @c wxEVT_MOUSE_CAPTURE_LOST event. See wxMouseCaptureLostEvent.
     @event{EVT_MOUSE_CAPTURE_CHANGED(func)}
     @event{EVT_MOUSE_CAPTURE_LOST(func)}
         Process a @c wxEVT_MOUSE_CAPTURE_LOST event. See wxMouseCaptureLostEvent.
     @event{EVT_MOUSE_CAPTURE_CHANGED(func)}


@@ -295,6 +321,13 @@ public:
     virtual ~wxWindow();
 
 
     virtual ~wxWindow();
 
 

+    bool Create(wxWindow *parent,
+                wxWindowID id,
+                const wxPoint& pos = wxDefaultPosition,
+                const wxSize& size = wxDefaultSize,
+                long style = 0,
+                const wxString& name = wxPanelNameStr);
+

     /**
         @name Focus functions
 
     /**
         @name Focus functions
 


@@ -461,10 +494,13 @@ public:
     */
     wxWindow* GetPrevSibling() const;
     /**
     */
     wxWindow* GetPrevSibling() const;
     /**

-        Reparents the window, i.e the window will be removed from its
+        Reparents the window, i.e. the window will be removed from its

         current parent window (e.g. a non-standard toolbar in a wxFrame)
         and then re-inserted into another.
 
         current parent window (e.g. a non-standard toolbar in a wxFrame)
         and then re-inserted into another.
 

+        Notice that currently you need to explicitly call
+        wxNotebook::RemovePage() before reparenting a notebook page.
+

         @param newParent
             New parent.
     */
         @param newParent
             New parent.
     */


@@ -849,6 +885,11 @@ public:
     */
     virtual wxSize GetMinSize() const;
 
     */
     virtual wxSize GetMinSize() const;
 

+    int GetMinWidth() const;
+    int GetMinHeight() const;
+    int GetMaxWidth() const;
+    int GetMaxHeight() const;
+

     /**
         Returns the size of the entire window in pixels, including title bar, border,
         scrollbars, etc.
     /**
         Returns the size of the entire window in pixels, including title bar, border,
         scrollbars, etc.


@@ -894,12 +935,31 @@ public:
     */
     void GetVirtualSize(int* width, int* height) const;
 
     */
     void GetVirtualSize(int* width, int* height) const;
 

+    /**
+       Return the largest of ClientSize and BestSize (as determined
+       by a sizer, interior children, or other means)
+    */
+    virtual wxSize GetBestVirtualSize() const;
+

     /**
         Returns the size of the left/right and top/bottom borders of this window in x
         and y components of the result respectively.
     */
     virtual wxSize GetWindowBorderSize() const;
 
     /**
         Returns the size of the left/right and top/bottom borders of this window in x
         and y components of the result respectively.
     */
     virtual wxSize GetWindowBorderSize() const;
 

+    /**
+       wxSizer and friends use this to give a chance to a component to recalc
+       its min size once one of the final size components is known. Override
+       this function when that is useful (such as for wxStaticText which can
+       stretch over several lines). Parameter availableOtherDir
+       tells the item how much more space there is available in the opposite
+       direction (-1 if unknown).
+    */
+    virtual bool
+    InformFirstDirection(int direction,
+                         int size,
+                         int availableOtherDir);
+    

     /**
         Resets the cached best size value so it will be recalculated the next time it
         is needed.
     /**
         Resets the cached best size value so it will be recalculated the next time it
         is needed.


@@ -976,6 +1036,11 @@ public:
     */
     void SetClientSize(const wxSize& size);
 
     */
     void SetClientSize(const wxSize& size);
 

+    /**
+        @overload
+    */
+    void SetClientSize(const wxRect& rect);
+

     /**
         This normally does not need to be called by user code.
         It is called when a window is added to a sizer, and is used so the window
     /**
         This normally does not need to be called by user code.
         It is called when a window is added to a sizer, and is used so the window


@@ -1131,9 +1196,12 @@ public:
 
         @see wxTopLevelWindow::SetSizeHints, @ref overview_windowsizing
     */
 
         @see wxTopLevelWindow::SetSizeHints, @ref overview_windowsizing
     */

-    void SetSizeHints( const wxSize& minSize,
-                       const wxSize& maxSize=wxDefaultSize,
-                       const wxSize& incSize=wxDefaultSize);
+    virtual void SetSizeHints( const wxSize& minSize,
+                               const wxSize& maxSize=wxDefaultSize,
+                               const wxSize& incSize=wxDefaultSize);
+    virtual void SetSizeHints( int minW, int minH,
+                               int maxW = -1, int maxH = -1,
+                               int incW = -1, int incH = -1 );

 
     /**
         Sets the virtual size of the window in pixels.
 
     /**
         Sets the virtual size of the window in pixels.


@@ -1197,20 +1265,6 @@ public:
     */
     void CentreOnParent(int direction = wxBOTH);
 
     */
     void CentreOnParent(int direction = wxBOTH);
 

-    /**
-        Centres the window.
-
-        @param direction
-            Specifies the direction for the centring. May be wxHORIZONTAL,
-            wxVERTICAL or wxBOTH. It may also include the wxCENTRE_ON_SCREEN
-            flag.
-
-        @remarks This function is not meant to be called directly by user code,
-                 but via Centre, Center, CentreOnParent, or CenterOnParent.
-                 This function can be overriden to fine-tune centring behaviour.
-    */
-    virtual void DoCentre(int direction);
-

     /**
         This gets the position of the window in pixels, relative to the parent window
         for the child windows or relative to the display origin for the top level windows.
     /**
         This gets the position of the window in pixels, relative to the parent window
         for the child windows or relative to the display origin for the top level windows.


@@ -1272,6 +1326,20 @@ public:
     */
     wxRect GetScreenRect() const;
 
     */
     wxRect GetScreenRect() const;
 

+    /**
+       Get the origin of the client area of the window relative to the
+       window top left corner (the client area may be shifted because of
+       the borders, scrollbars, other decorations...)
+    */
+    virtual wxPoint GetClientAreaOrigin() const;
+
+    /**
+       Get the client rectangle in window (i.e. client) coordinates
+    */
+    wxRect GetClientRect() const;
+
+
+    

     /**
         Moves the window to the given position.
 
     /**
         Moves the window to the given position.
 


@@ -1310,6 +1378,8 @@ public:
     */
     void Move(const wxPoint& pt, int flags = wxSIZE_USE_EXISTING);
 
     */
     void Move(const wxPoint& pt, int flags = wxSIZE_USE_EXISTING);
 

+    void SetPosition(const wxPoint& pt);
+

     //@}
 
 
     //@}
 
 


@@ -1557,7 +1627,7 @@ public:
         @endWxPerlOnly
     */
     void GetTextExtent(const wxString& string,
         @endWxPerlOnly
     */
     void GetTextExtent(const wxString& string,

-                        int* w, int* h,
+                       int* w, int* h,

                        int* descent = NULL,
                        int* externalLeading = NULL,
                        const wxFont* font = NULL) const;
                        int* descent = NULL,
                        int* externalLeading = NULL,
                        const wxFont* font = NULL) const;


@@ -1576,6 +1646,11 @@ public:
     */
     const wxRegion& GetUpdateRegion() const;
 
     */
     const wxRegion& GetUpdateRegion() const;
 

+    /**
+       Get the update rectangle bounding box in client coords
+    */
+    wxRect GetUpdateClientRect() const;
+

     /**
         Returns @true if this window background is transparent (as, for example,
         for wxStaticText) and should show the parent window background.
     /**
         Returns @true if this window background is transparent (as, for example,
         for wxStaticText) and should show the parent window background.


@@ -1625,13 +1700,18 @@ public:
 
     /**
         Sets the background colour of the window.
 
     /**
         Sets the background colour of the window.

+
+        Notice that as with SetForegroundColour(), setting the background
+        colour of a native control may not affect the entire control and could
+        be not supported at all depending on the control and platform.
+

         Please see InheritAttributes() for explanation of the difference between
         this method and SetOwnBackgroundColour().
 
         @param colour
             The colour to be used as the background colour; pass
             wxNullColour to reset to the default colour.
         Please see InheritAttributes() for explanation of the difference between
         this method and SetOwnBackgroundColour().
 
         @param colour
             The colour to be used as the background colour; pass
             wxNullColour to reset to the default colour.

-            Note that you may want to use wxSystemSettings::GetColour() to retrieve 
+            Note that you may want to use wxSystemSettings::GetColour() to retrieve

             a suitable colour to use rather than setting an hard-coded one.
 
         @remarks The background colour is usually painted by the default
             a suitable colour to use rather than setting an hard-coded one.
 
         @remarks The background colour is usually painted by the default


@@ -1678,11 +1758,57 @@ public:
         @c wxBG_STYLE_PAINT is a simpler and more efficient solution to the same
         problem.
 
         @c wxBG_STYLE_PAINT is a simpler and more efficient solution to the same
         problem.
 

+
+        Under wxGTK and wxOSX, you can use ::wxBG_STYLE_TRANSPARENT to obtain
+        full transparency of the window background. Note that wxGTK supports
+        this only since GTK 2.12 with a compositing manager enabled, call
+        IsTransparentBackgroundSupported() to check whether this is the case.
+
+        Also, on order for @c SetBackgroundStyle(wxBG_STYLE_TRANSPARENT) to
+        work, it must be called before Create(). If you're using your own
+        wxWindow-derived class you should write your code in the following way:
+        @code
+            class MyWidget : public wxWindow
+            {
+            public:
+                MyWidget(wxWindow* parent, ...)
+                    : wxWindow() // Use default ctor here!
+                {
+                    // Do this first:
+                    SetBackgroundStyle(wxBG_STYLE_TRANSPARENT);
+
+                    // And really create the window afterwards:
+                    Create(parent, ...);
+                }
+            };
+        @endcode
+

         @see SetBackgroundColour(), GetForegroundColour(),
         @see SetBackgroundColour(), GetForegroundColour(),

-             SetTransparent()
+             SetTransparent(), IsTransparentBackgroundSupported()

     */
     virtual bool SetBackgroundStyle(wxBackgroundStyle style);
 
     */
     virtual bool SetBackgroundStyle(wxBackgroundStyle style);
 

+    /**
+        Checks whether using transparent background might work.
+
+        If this function returns @false, calling SetBackgroundStyle() with
+        ::wxBG_STYLE_TRANSPARENT is not going to work. If it returns @true,
+        setting transparent style should normally succeed.
+
+        Notice that this function would typically be called on the parent of a
+        window you want to set transparent background style for as the window
+        for which this method is called must be fully created.
+
+        @param reason
+            If not @NULL, a reason message is provided if transparency is not
+            supported.
+
+        @return @true if background transparency is supported.
+
+        @since 2.9.4
+    */
+    virtual bool IsTransparentBackgroundSupported(wxString *reason = NULL) const;
+

     /**
         Sets the font for this window. This function should not be called for the
         parent window if you don't want its font to be inherited by its children,
     /**
         Sets the font for this window. This function should not be called for the
         parent window if you don't want its font to be inherited by its children,


@@ -1708,6 +1834,13 @@ public:
 
     /**
         Sets the foreground colour of the window.
 
     /**
         Sets the foreground colour of the window.

+
+        The meaning of foreground colour varies according to the window class;
+        it may be the text colour or other colour, or it may not be used at
+        all. Additionally, not all native controls support changing their
+        foreground colour so this method may change their colour only partially
+        or even not at all.
+

         Please see InheritAttributes() for explanation of the difference between
         this method and SetOwnForegroundColour().
 
         Please see InheritAttributes() for explanation of the difference between
         this method and SetOwnForegroundColour().
 


@@ -1715,9 +1848,6 @@ public:
             The colour to be used as the foreground colour; pass
             wxNullColour to reset to the default colour.
 
             The colour to be used as the foreground colour; pass
             wxNullColour to reset to the default colour.
 

-        @remarks The meaning of foreground colour varies according to the window class;
-                 it may be the text colour or other colour, or it may not be used at all.
-

         @return @true if the colour was really changed, @false if it was already set
                 to this colour and nothing was done.
 
         @return @true if the colour was really changed, @false if it was already set
                 to this colour and nothing was done.
 


@@ -1777,6 +1907,10 @@ public:
     */
     virtual void SetThemeEnabled(bool enable);
 
     */
     virtual void SetThemeEnabled(bool enable);
 

+    /**
+     */
+    virtual bool GetThemeEnabled() const;
+

     /**
         Returns @true if the system supports transparent windows and calling
         SetTransparent() may succeed. If this function returns @false, transparent
     /**
         Returns @true if the system supports transparent windows and calling
         SetTransparent() may succeed. If this function returns @false, transparent


@@ -2010,7 +2144,7 @@ public:
 
     /**
         Sets the style of the window. Please note that some styles cannot be changed
 
     /**
         Sets the style of the window. Please note that some styles cannot be changed

-        after the window creation and that Refresh() might need to be be called
+        after the window creation and that Refresh() might need to be called

         after changing the others for the change to take place immediately.
 
         See @ref overview_windowstyles "Window styles" for more information about flags.
         after changing the others for the change to take place immediately.
 
         See @ref overview_windowstyles "Window styles" for more information about flags.


@@ -2088,13 +2222,13 @@ public:
                  control. See also wxNavigationKeyEvent and
                  HandleAsNavigationKey.
     */
                  control. See also wxNavigationKeyEvent and
                  HandleAsNavigationKey.
     */

-    bool Navigate(int flags = IsForward);
+    bool Navigate(int flags = wxNavigationKeyEvent::IsForward);

 
     /**
         Performs a keyboard navigation action inside this window.
         See Navigate() for more information.
     */
 
     /**
         Performs a keyboard navigation action inside this window.
         See Navigate() for more information.
     */

-    bool NavigateIn(int flags = IsForward);
+    bool NavigateIn(int flags = wxNavigationKeyEvent::IsForward);

 
     //@}
 
 
     //@}
 


@@ -2334,7 +2468,7 @@ public:
 
         @see GetToolTip(), wxToolTip
     */
 
         @see GetToolTip(), wxToolTip
     */

-    void SetToolTip(const wxString& tip);
+    void SetToolTip(const wxString& tipString);

 
     /**
         @overload
 
     /**
         @overload


@@ -2714,7 +2848,7 @@ public:
 
 
     /**
 
 
     /**

-        @name Constraints, sizers and window layouting functions
+        @name Constraints, sizers and window layout functions

     */
     //@{
 
     */
     //@{
 


@@ -2757,7 +2891,7 @@ public:
         This method calls SetSizer() and then wxSizer::SetSizeHints which sets the initial
         window size to the size needed to accommodate all sizer elements and sets the
         size hints which, if this window is a top level one, prevent the user from
         This method calls SetSizer() and then wxSizer::SetSizeHints which sets the initial
         window size to the size needed to accommodate all sizer elements and sets the
         size hints which, if this window is a top level one, prevent the user from

-        resizing it to be less than this minimial size.
+        resizing it to be less than this minimal size.

     */
     void SetSizerAndFit(wxSizer* sizer, bool deleteOld = true);
 
     */
     void SetSizerAndFit(wxSizer* sizer, bool deleteOld = true);
 


@@ -2784,7 +2918,6 @@ public:
     */
     void SetConstraints(wxLayoutConstraints* constraints);
 
     */
     void SetConstraints(wxLayoutConstraints* constraints);
 

-

     /**
         Invokes the constraint-based layout algorithm or the sizer-based algorithm
         for this window.
     /**
         Invokes the constraint-based layout algorithm or the sizer-based algorithm
         for this window.


@@ -2814,6 +2947,8 @@ public:
     */
     void SetAutoLayout(bool autoLayout);
 
     */
     void SetAutoLayout(bool autoLayout);
 

+    bool GetAutoLayout() const;
+

     //@}
 
 
     //@}
 
 


@@ -2913,6 +3048,22 @@ public:
     */
     //@{
 
     */
     //@{
 

+    wxHitTest HitTest(wxCoord x, wxCoord y) const;
+    wxHitTest HitTest(const wxPoint& pt) const;
+
+    /**
+       Get the window border style from the given flags: this is different from
+       simply doing flags & wxBORDER_MASK because it uses GetDefaultBorder() to
+       translate wxBORDER_DEFAULT to something reasonable
+    */
+    wxBorder GetBorder(long flags) const;
+
+    /**
+       Get border for the flags of this window
+    */
+    wxBorder GetBorder() const;
+
+    

     /**
         Does the window-specific updating after processing the update event.
         This function is called by UpdateWindowUI() in order to check return
     /**
         Does the window-specific updating after processing the update event.
         This function is called by UpdateWindowUI() in order to check return


@@ -2940,7 +3091,7 @@ public:
     /**
         Returns the platform-specific handle of the physical window.
         Cast it to an appropriate handle, such as @b HWND for Windows,
     /**
         Returns the platform-specific handle of the physical window.
         Cast it to an appropriate handle, such as @b HWND for Windows,

-        @b Widget for Motif, @b GtkWidget for GTK or @b WinHandle for PalmOS.
+        @b Widget for Motif or @b GtkWidget for GTK.

 
         @beginWxPerlOnly
         This method will return an integer in wxPerl.
 
         @beginWxPerlOnly
         This method will return an integer in wxPerl.


@@ -2997,6 +3148,8 @@ public:
     */
     virtual bool IsDoubleBuffered() const;
 
     */
     virtual bool IsDoubleBuffered() const;
 

+    void SetDoubleBuffered(bool on);
+

     /**
         Returns @true if the window is retained, @false otherwise.
 
     /**
         Returns @true if the window is retained, @false otherwise.
 


@@ -3030,6 +3183,7 @@ public:
     */
     virtual void MakeModal(bool modal = true);
 
     */
     virtual void MakeModal(bool modal = true);
 

+    

     /**
         This virtual function is normally only used internally, but
         sometimes an application may need it to implement functionality
     /**
         This virtual function is normally only used internally, but
         sometimes an application may need it to implement functionality


@@ -3266,6 +3420,20 @@ public:
 
 protected:
 
 
 protected:
 

+    /**
+        Centres the window.
+
+        @param direction
+            Specifies the direction for the centring. May be wxHORIZONTAL,
+            wxVERTICAL or wxBOTH. It may also include the wxCENTRE_ON_SCREEN
+            flag.
+
+        @remarks This function is not meant to be called directly by user code,
+                 but via Centre, Center, CentreOnParent, or CenterOnParent.
+                 This function can be overridden to fine-tune centring behaviour.
+    */
+    virtual void DoCentre(int direction);
+

     /**
         Gets the size which best suits the window: for a control, it would be
         the minimal size which doesn't truncate the control, for a panel - the
     /**
         Gets the size which best suits the window: for a control, it would be
         the minimal size which doesn't truncate the control, for a panel - the