fix syntax error

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

diff --git a/interface/wx/window.h b/interface/wx/window.h
index 42ad351c86b2c892886f743d3519f5c7d6a26493..ab349f24865a748d413bf07886b840b3c2cd69c1 100644 (file)
--- a/interface/wx/window.h
+++ b/interface/wx/window.h
@@ -207,8 +207,9 @@ enum wxUpdateUI
            Under Windows, puts a query button on the caption. When pressed,
            Windows will go into a context-sensitive help mode and wxWidgets
            will send a wxEVT_HELP event if the user clicked on an application window.
            Under Windows, puts a query button on the caption. When pressed,
            Windows will go into a context-sensitive help mode and wxWidgets
            will send a wxEVT_HELP event if the user clicked on an application window.

-           This style cannot be used together with wxMAXIMIZE_BOX or wxMINIMIZE_BOX, so
-           these two styles are automatically turned of if this one is used.
+           This style cannot be used (because of the underlying native behaviour)
+           together with @c wxMAXIMIZE_BOX or @c wxMINIMIZE_BOX, so these two styles
+           are automatically turned off if this one is used.

     @style{wxWS_EX_PROCESS_IDLE}
            This window should always process idle events, even if the mode set
            by wxIdleEvent::SetMode is wxIDLE_PROCESS_SPECIFIED.
     @style{wxWS_EX_PROCESS_IDLE}
            This window should always process idle events, even if the mode set
            by wxIdleEvent::SetMode is wxIDLE_PROCESS_SPECIFIED.


@@ -319,7 +320,7 @@ public:
 
         @remarks This function is currently only implemented under Mac/Carbon.
     */
 
         @remarks This function is currently only implemented under Mac/Carbon.
     */

-    void AlwaysShowScrollbars(bool hflag, bool vflag);
+    virtual void AlwaysShowScrollbars(bool hflag = true, bool vflag = true);

 
     /**
         Sets the cached best size value.
 
     /**
         Sets the cached best size value.


@@ -354,12 +355,12 @@ public:
     /**
         A synonym for Centre().
     */
     /**
         A synonym for Centre().
     */

-    void Center(int direction);
+    void Center(int dir = wxBOTH);

 
     /**
         A synonym for CentreOnParent().
     */
 
     /**
         A synonym for CentreOnParent().
     */

-    void CenterOnParent(int direction);
+    void CenterOnParent(int dir = wxBOTH);

 
     /**
         Centres the window.
 
     /**
         Centres the window.


@@ -545,7 +546,7 @@ public:
     /**
         Destroys all children of a window. Called automatically by the destructor.
     */
     /**
         Destroys all children of a window. Called automatically by the destructor.
     */

-    virtual void DestroyChildren();
+    bool DestroyChildren();

 
     /**
         Returns true if this window is in process of being destroyed.
 
     /**
         Returns true if this window is in process of being destroyed.


@@ -569,27 +570,6 @@ public:
     */
     bool Disable();
 
     */
     bool Disable();
 

-    /**
-        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
-        same size as it would have after a call to Fit().
-
-        The default implementation of this function is designed for use in container
-        windows, such as wxPanel, and works something like this:
-        -# If the window has a sizer then it is used to calculate the best size.
-        -# Otherwise if the window has layout constraints then those are used to
-           calculate the best size.
-        -# Otherwise if the window has children then the best size is set to be large
-           enough to show all the children.
-        -# Otherwise if there are no children then the window's minimal size will be
-           used as its best size.
-        -# Otherwise if there is no minimal size set, then the current size is used
-           for the best size.
-
-        @see @ref overview_windowsizing
-    */
-    virtual wxSize DoGetBestSize() 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


@@ -621,7 +601,11 @@ public:
             If @true, the window is eligible for drop file events.
             If @false, the window will not accept drop file events.
 
             If @true, the window is eligible for drop file events.
             If @false, the window will not accept drop file events.
 

-        @remarks Windows only.
+        @remarks Windows only until version 2.8.9, available on all platforms
+                 since 2.8.10. Cannot be used together with SetDropTarget() on
+                 non-Windows platforms.
+
+        @see SetDropTarget()

     */
     virtual void DragAcceptFiles(bool accept);
 
     */
     virtual void DragAcceptFiles(bool accept);
 


@@ -766,12 +750,6 @@ public:
     */
     wxAccessible* GetAccessible();
 
     */
     wxAccessible* GetAccessible();
 

-    /**
-        @deprecated
-        This method is deprecated, use GetEffectiveMinSize() instead.
-    */
-    wxSize GetAdjustedBestSize() const;
-

     /**
         Returns the background colour of the window.
 
     /**
         Returns the background colour of the window.
 


@@ -860,16 +838,12 @@ public:
     //@{
     /**
         Returns the size of the window 'client area' in pixels.
     //@{
     /**
         Returns the size of the window 'client area' in pixels.

+

         The client area is the area which may be drawn on by the programmer,
         excluding title bar, border, scrollbars, etc.
         Note that if this window is a top-level one and it is currently minimized, the
         return size is empty (both width and height are 0).
 
         The client area is the area which may be drawn on by the programmer,
         excluding title bar, border, scrollbars, etc.
         Note that if this window is a top-level one and it is currently minimized, the
         return size is empty (both width and height are 0).
 

-        @param width
-            Receives the client width in pixels.
-        @param height
-            Receives the client height in pixels.
-

         @see GetSize(), GetVirtualSize()
     */
     void GetClientSize(int* width, int* height) const;
         @see GetSize(), GetVirtualSize()
     */
     void GetClientSize(int* width, int* height) const;


@@ -969,7 +943,7 @@ public:
         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.
     */
         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.
     */

-    void* GetHandle() const;
+    virtual WXWidget GetHandle() const;

 
     /**
         Gets the help text to be used as context-sensitive help for this window.
 
     /**
         Gets the help text to be used as context-sensitive help for this window.


@@ -990,7 +964,7 @@ public:
         @param origin
             Help event origin, see also wxHelpEvent::GetOrigin.
     */
         @param origin
             Help event origin, see also wxHelpEvent::GetOrigin.
     */

-    virtual wxString GetHelpTextAtPoint(const wxPoint point,
+    virtual wxString GetHelpTextAtPoint(const wxPoint& point,

                                         wxHelpEvent::Origin origin) const;
 
     /**
                                         wxHelpEvent::Origin origin) const;
 
     /**


@@ -1002,7 +976,7 @@ public:
 
         @see SetId(), @ref overview_windowids
     */
 
         @see SetId(), @ref overview_windowids
     */

-    int GetId() const;
+    wxWindowID GetId() const;

 
     /**
         Generic way of getting a label from any window, for
 
     /**
         Generic way of getting a label from any window, for


@@ -1241,14 +1215,11 @@ public:
             Return value for external leading (optional).
         @param font
             Font to use instead of the current window font (optional).
             Return value for external leading (optional).
         @param font
             Font to use instead of the current window font (optional).

-        @param use16
-            If @true, string contains 16-bit characters. The default is @false.

     */
     virtual void GetTextExtent(const wxString& string, int* w, int* h,
                                int* descent = NULL,
                                int* externalLeading = NULL,
     */
     virtual void GetTextExtent(const wxString& string, int* w, int* h,
                                int* descent = NULL,
                                int* externalLeading = NULL,

-                               const wxFont* font = NULL,
-                               bool use16 = false) const;
+                               const wxFont* font = NULL) const;

 
     /**
         Gets the dimensions of the string as it would be drawn on the
 
     /**
         Gets the dimensions of the string as it would be drawn on the


@@ -1267,7 +1238,7 @@ public:
 
         @see wxRegion, wxRegionIterator
     */
 
         @see wxRegion, wxRegionIterator
     */

-    virtual wxRegion GetUpdateRegion() const;
+    const wxRegion& GetUpdateRegion() const;

 
     /**
         Returns a pointer to the current validator for the window, or @NULL if
 
     /**
         Returns a pointer to the current validator for the window, or @NULL if


@@ -1279,7 +1250,12 @@ public:
     /**
         This gets the virtual size of the window in pixels.
         By default it returns the client size of the window, but after a call to
     /**
         This gets the virtual size of the window in pixels.
         By default it returns the client size of the window, but after a call to

-        SetVirtualSize() it will return that size.
+        SetVirtualSize() it will return the size set with that method.
+    */
+    wxSize GetVirtualSize() const;
+
+    /**
+        Like the other GetVirtualSize() overload but uses pointers instead.

 
         @param width
             Receives the window virtual width.
 
         @param width
             Receives the window virtual width.


@@ -1287,7 +1263,6 @@ public:
             Receives the window virtual height.
     */
     void GetVirtualSize(int* width, int* height) const;
             Receives the window virtual height.
     */
     void GetVirtualSize(int* width, int* height) const;

-    wxSize GetVirtualSize() const;

     //@}
 
     /**
     //@}
 
     /**


@@ -1398,7 +1373,7 @@ public:
         @since 2.9.0
     */
     virtual bool HideWithEffect(wxShowEffect effect,
         @since 2.9.0
     */
     virtual bool HideWithEffect(wxShowEffect effect,

-                                unsigned timeout = 0);
+                                unsigned int timeout = 0);

 
     /**
         This function is (or should be, in case of custom controls) called during
 
     /**
         This function is (or should be, in case of custom controls) called during


@@ -1465,9 +1440,9 @@ public:
         only redrawing those areas, which have been exposed.
     */
     bool IsExposed(int x, int y) const;
         only redrawing those areas, which have been exposed.
     */
     bool IsExposed(int x, int y) const;

-    const bool IsExposed(wxPoint amp;pt) const;
-    const bool IsExposed(int x, int y, int w, int h) const;
-    const bool IsExposed(wxRect amp;rect) const;
+    bool IsExposed(wxPoint& pt) const;
+    bool IsExposed(int x, int y, int w, int h) const;
+    bool IsExposed(wxRect& rect) const;

     //@}
 
     /**
     //@}
 
     /**


@@ -1528,16 +1503,21 @@ public:
         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.
 

-        See SetAutoLayout(): when auto layout is on, this function gets called automatically
-        when the window is resized.
+        This function does not get called automatically when the window is resized
+        because lots of windows deriving from wxWindow does not need this functionality.
+        If you want to have Layout() called automatically, you should derive
+        from wxPanel (see wxPanel::Layout).

 
         @see @ref overview_windowsizing
     */
 
         @see @ref overview_windowsizing
     */

-    void Layout();
+    virtual bool Layout();

 
     /**
         Lowers the window to the bottom of the window hierarchy (Z-order).
 
 
     /**
         Lowers the window to the bottom of the window hierarchy (Z-order).
 

+        @remarks
+        This function only works for wxTopLevelWindow-derived classes.
+

         @see Raise()
     */
     virtual void Lower();
         @see Raise()
     */
     virtual void Lower();


@@ -1546,12 +1526,12 @@ public:
         Disables all other windows in the application so that
         the user can only interact with this window.
 
         Disables all other windows in the application so that
         the user can only interact with this window.
 

-        @param flag
+        @param modal

             If @true, this call disables all other windows in the application so that
             the user can only interact with this window. If @false, the effect is
             reversed.
     */
             If @true, this call disables all other windows in the application so that
             the user can only interact with this window. If @false, the effect is
             reversed.
     */

-    virtual void MakeModal(bool flag);
+    virtual void MakeModal(bool modal = true);

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


@@ -1560,6 +1540,8 @@ public:
             Required x position.
         @param y
             Required y position.
             Required x position.
         @param y
             Required y position.

+        @param flags
+            See SetSize() for more info about this parameter.

 
         @remarks Implementations of SetSize can also implicitly implement the
                  Move() function, which is defined in the base wxWindow class as the call:
 
         @remarks Implementations of SetSize can also implicitly implement the
                  Move() function, which is defined in the base wxWindow class as the call:


@@ -1569,13 +1551,15 @@ public:
 
         @see SetSize()
     */
 
         @see SetSize()
     */

-    void Move(int x, int y);
+    void Move(int x, int y, int flags = wxSIZE_USE_EXISTING);

 
     /**
         Moves the window to the given position.
 
         @param pt
             wxPoint object representing the position.
 
     /**
         Moves the window to the given position.
 
         @param pt
             wxPoint object representing the position.

+        @param flags
+            See SetSize() for more info about this parameter.

 
         @remarks Implementations of SetSize() can also implicitly implement the
                  Move() function, which is defined in the base wxWindow class as the call:
 
         @remarks Implementations of SetSize() can also implicitly implement the
                  Move() function, which is defined in the base wxWindow class as the call:


@@ -1585,7 +1569,7 @@ public:
 
         @see SetSize()
     */
 
         @see SetSize()
     */

-    void Move(const wxPoint& pt);
+    void Move(const wxPoint& pt, int flags = wxSIZE_USE_EXISTING);

 
     /**
         Moves this window in the tab navigation order after the specified @e win.
 
     /**
         Moves this window in the tab navigation order after the specified @e win.


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

-    bool Navigate(int flags = wxNavigationKeyEvent::IsForward);
+    bool Navigate(int flags = 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 = wxNavigationKeyEvent::IsForward);
+    bool NavigateIn(int flags = IsForward);

 
     /**
         Create a new ID or range of IDs that are not currently in use.
 
     /**
         Create a new ID or range of IDs that are not currently in use.


@@ -1708,14 +1692,10 @@ public:
         processed as usually. If the coordinates are not specified, current mouse
         cursor position is used.
 
         processed as usually. If the coordinates are not specified, current mouse
         cursor position is used.
 

-        @param menu
-            Menu to pop up.
-        @param pos
-            The position where the menu will appear.
-        @param x
-            Required x position for the menu to appear.
-        @param y
-            Required y position for the menu to appear.
+        @a menu is the menu to pop up.
+
+        The position where the menu will appear can be specified either as a
+        wxPoint @a pos or by two integers (@a x and @a y).

 
         @remarks Just before the menu is popped up, wxMenu::UpdateUI is called to
                  ensure that the menu items are in the correct state.
 
         @remarks Just before the menu is popped up, wxMenu::UpdateUI is called to
                  ensure that the menu items are in the correct state.


@@ -1771,7 +1751,9 @@ public:
 
     /**
         Raises the window to the top of the window hierarchy (Z-order).
 
     /**
         Raises the window to the top of the window hierarchy (Z-order).

-        In current version of wxWidgets this works both for managed and child windows.
+
+        @remarks
+        This function only works for wxTopLevelWindow-derived classes.

 
         @see Lower()
     */
 
         @see Lower()
     */


@@ -1833,8 +1815,8 @@ public:
 
         @see UnregisterHotKey()
     */
 
         @see UnregisterHotKey()
     */

-    bool RegisterHotKey(int hotkeyId, int modifiers,
-                        int virtualKeyCode);
+    virtual bool RegisterHotKey(int hotkeyId, int modifiers,
+                                int virtualKeyCode);

 
     /**
         Releases mouse input captured with CaptureMouse().
 
     /**
         Releases mouse input captured with CaptureMouse().


@@ -1883,7 +1865,6 @@ public:
     */
     virtual bool Reparent(wxWindow* newParent);
 
     */
     virtual bool Reparent(wxWindow* newParent);
 

-    //@{

     /**
         Converts from screen to client window coordinates.
 
     /**
         Converts from screen to client window coordinates.
 


@@ -1891,12 +1872,16 @@ public:
             Stores the screen x coordinate and receives the client x coordinate.
         @param y
             Stores the screen x coordinate and receives the client x coordinate.
             Stores the screen x coordinate and receives the client x coordinate.
         @param y
             Stores the screen x coordinate and receives the client x coordinate.

+    */
+    void ScreenToClient(int* x, int* y) const;
+
+    /**
+        Converts from screen to client window coordinates.
+

         @param pt
         @param pt

-            The screen position for the second form of the function.
+            The screen position.

     */
     */

-    virtual void ScreenToClient(int* x, int* y) const;
-    virtual wxPoint ScreenToClient(const wxPoint& pt) const;
-    //@}
+    wxPoint ScreenToClient(const wxPoint& pt) const;

 
     /**
         Scrolls the window by the given number of lines down (if @a lines is
 
     /**
         Scrolls the window by the given number of lines down (if @a lines is


@@ -1945,7 +1930,7 @@ public:
                               const wxRect* rect = NULL);
 
     /**
                               const wxRect* rect = NULL);
 
     /**

-        This function sends a dummy @ref overview_wxsizeevent "size event" to
+        This function sends a dummy @ref wxSizeEvent "size event" to

         the window allowing it to re-layout its children positions.
 
         It is sometimes useful to call this function after adding or deleting a
         the window allowing it to re-layout its children positions.
 
         It is sometimes useful to call this function after adding or deleting a


@@ -2003,8 +1988,9 @@ public:
         updated when its size changes.
 
         @param autoLayout
         updated when its size changes.
 
         @param autoLayout

-            Set this to @true if you wish the Layout function to be
-            called automatically when the window is resized.
+            Set this to @true if you wish the Layout() function to be
+            called automatically when the window is resized
+            (really happens only if you derive from wxPanel or wxTopLevelWindow).

 
         @see SetConstraints()
     */
 
         @see SetConstraints()
     */


@@ -2043,7 +2029,7 @@ public:
         @see SetBackgroundColour(), GetForegroundColour(),
              SetTransparent()
     */
         @see SetBackgroundColour(), GetForegroundColour(),
              SetTransparent()
     */

-    virtual void SetBackgroundStyle(wxBackgroundStyle style);
+    virtual bool SetBackgroundStyle(wxBackgroundStyle style);

 
     /**
         This method is only implemented by ports which have support for
 
     /**
         This method is only implemented by ports which have support for


@@ -2070,13 +2056,6 @@ public:
         than SetSize(), since the application need not worry about what dimensions
         the border or title bar have when trying to fit the window around panel
         items, for example.
         than SetSize(), since the application need not worry about what dimensions
         the border or title bar have when trying to fit the window around panel
         items, for example.

-
-        @param width
-            The required client area width.
-        @param height
-            The required client area height.
-        @param size
-            The required client size.

     */
     virtual void SetClientSize(int width, int height);
     virtual void SetClientSize(const wxSize& size);
     */
     virtual void SetClientSize(int width, int height);
     virtual void SetClientSize(const wxSize& size);


@@ -2119,7 +2098,7 @@ public:
 
         @see ::wxSetCursor, wxCursor
     */
 
         @see ::wxSetCursor, wxCursor
     */

-    virtual void SetCursor(const wxCursor& cursor);
+    virtual bool SetCursor(const wxCursor& cursor);

 
     /**
         Associates a drop target with this window.
 
     /**
         Associates a drop target with this window.


@@ -2213,7 +2192,7 @@ public:
         @see GetForegroundColour(), SetBackgroundColour(),
              GetBackgroundColour(), ShouldInheritColours()
     */
         @see GetForegroundColour(), SetBackgroundColour(),
              GetBackgroundColour(), ShouldInheritColours()
     */

-    virtual void SetForegroundColour(const wxColour& colour);
+    virtual bool SetForegroundColour(const wxColour& colour);

 
     /**
         Sets the help text to be used as context-sensitive help for this window.
 
     /**
         Sets the help text to be used as context-sensitive help for this window.


@@ -2234,13 +2213,7 @@ public:
 
         @see GetId(), @ref overview_windowids
     */
 
         @see GetId(), @ref overview_windowids
     */

-    void SetId(int id);
-
-    /**
-        Sets the initial window size if none is given (i.e. at least one of the
-        components of the size passed to ctor/Create() is wxDefaultCoord).
-    */
-    virtual void SetInitialBestSize(const wxSize& size);
+    void SetId(wxWindowID winid);

 
     /**
         A @e smart SetSize that will fill in default size components with the
 
     /**
         A @e smart SetSize that will fill in default size components with the


@@ -2354,7 +2327,7 @@ public:
     /**
         @deprecated use wxDC::SetPalette instead.
     */
     /**
         @deprecated use wxDC::SetPalette instead.
     */

-    virtual void SetPalette(wxPalette* palette);
+    void SetPalette(const wxPalette& pal);

 
     /**
         Sets the position of one of the built-in scrollbars.
 
     /**
         Sets the position of one of the built-in scrollbars.


@@ -2458,8 +2431,8 @@ public:
 
         @see Move()
     */
 
         @see Move()
     */

-    virtual void SetSize(int x, int y, int width, int height,
-                         int sizeFlags = wxSIZE_AUTO);
+    void SetSize(int x, int y, int width, int height,
+                 int sizeFlags = wxSIZE_AUTO);

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


@@ -2629,7 +2602,7 @@ public:
         @see HideWithEffect()
     */
     virtual bool ShowWithEffect(wxShowEffect effect,
         @see HideWithEffect()
     */
     virtual bool ShowWithEffect(wxShowEffect effect,

-                                unsigned timeout = 0);
+                                unsigned int timeout = 0);

 
     /**
         Reenables window updating after a previous call to Freeze().
 
     /**
         Reenables window updating after a previous call to Freeze().


@@ -2696,7 +2669,7 @@ public:
 
         @see RegisterHotKey()
     */
 
         @see RegisterHotKey()
     */

-    bool UnregisterHotKey(int hotkeyId);
+    virtual bool UnregisterHotKey(int hotkeyId);

 
     /**
         Unreserve an ID or range of IDs that was reserved by NewControlId().
 
     /**
         Unreserve an ID or range of IDs that was reserved by NewControlId().


@@ -2789,6 +2762,38 @@ public:
             The new y position for the cursor.
     */
     virtual void WarpPointer(int x, int y);
             The new y position for the cursor.
     */
     virtual void WarpPointer(int x, int y);

+
+
+protected:
+
+    /**
+        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
+        same size as it would have after a call to Fit().
+
+        The default implementation of this function is designed for use in container
+        windows, such as wxPanel, and works something like this:
+        -# If the window has a sizer then it is used to calculate the best size.
+        -# Otherwise if the window has layout constraints then those are used to
+           calculate the best size.
+        -# Otherwise if the window has children then the best size is set to be large
+           enough to show all the children.
+        -# Otherwise if there are no children then the window's minimal size will be
+           used as its best size.
+        -# Otherwise if there is no minimal size set, then the current size is used
+           for the best size.
+
+        @see @ref overview_windowsizing
+    */
+    virtual wxSize DoGetBestSize() const;
+
+
+    /**
+        Sets the initial window size if none is given (i.e. at least one of the
+        components of the size passed to ctor/Create() is wxDefaultCoord).
+        @deprecated @todo provide deprecation description
+    */
+    virtual void SetInitialBestSize(const wxSize& size);

 };
 
 
 };