update for bakefile 0.2.6

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

diff --git a/interface/wx/window.h b/interface/wx/window.h
index 03eb0a689431d864c0852f2f6f97e04fe5acd64c..6eb30c66bb72a1fe20f01aababa7efaf0f40e367 100644 (file)
--- a/interface/wx/window.h
+++ b/interface/wx/window.h
@@ -7,32 +7,6 @@
 /////////////////////////////////////////////////////////////////////////////
 
 
 /////////////////////////////////////////////////////////////////////////////
 
 

-/**
-    Background styles. See wxWindow::SetBackgroundStyle().
-*/
-enum wxBackgroundStyle
-{
-    /// Use the default background, as determined by
-    /// the system or the current theme.
-    wxBG_STYLE_SYSTEM,
-
-    /// Use a solid colour for the background, this style is set automatically if you call
-    /// SetBackgroundColour() so you only need to set it explicitly if you had
-    /// changed the background style to something else before.
-    wxBG_STYLE_COLOUR,
-
-    /// Don't draw the background at all, it's supposed that it is drawn by
-    /// the user-defined erase background event handler.
-    /// This style should be used to avoid flicker when the background is entirely
-    /// custom-drawn.
-    wxBG_STYLE_CUSTOM,
-
-    /// The background is (partially) transparent,this style is automatically set if you call
-    /// SetTransparent() which is used to set the transparency level.
-    wxBG_STYLE_TRANSPARENT
-};
-
-

 /**
     Valid values for wxWindow::ShowWithEffect() and wxWindow::HideWithEffect().
 */
 /**
     Valid values for wxWindow::ShowWithEffect() and wxWindow::HideWithEffect().
 */


@@ -83,17 +57,6 @@ enum wxWindowVariant
 };
 
 
 };
 
 

-/**
-    Flags which can be used in wxWindow::UpdateWindowUI().
-*/
-enum wxUpdateUI
-{
-    wxUPDATE_UI_NONE,
-    wxUPDATE_UI_RECURSE,
-    wxUPDATE_UI_FROMIDLE  /**<  Invoked from On(Internal)Idle */
-};
-
-

 /**
     @class wxWindow
 
 /**
     @class wxWindow
 


@@ -188,16 +151,17 @@ enum wxUpdateUI
 
     @beginExtraStyleTable
     @style{wxWS_EX_VALIDATE_RECURSIVELY}
 
     @beginExtraStyleTable
     @style{wxWS_EX_VALIDATE_RECURSIVELY}

-           By default, Validate/TransferDataTo/FromWindow() only work on
-           direct children of the window (compatible behaviour). Set this flag
-           to make them recursively descend into all subwindows.
+           By default, wxWindow::Validate(), wxWindow::TransferDataTo() and
+           wxWindow::TransferDataFromWindow() only work on
+           direct children of the window (compatible behaviour).
+           Set this flag to make them recursively descend into all subwindows.

     @style{wxWS_EX_BLOCK_EVENTS}
            wxCommandEvents and the objects of the derived classes are
            forwarded to the parent window and so on recursively by default.
            Using this flag for the given window allows to block this
            propagation at this window, i.e. prevent the events from being
            propagated further upwards. Dialogs have this flag on by default
     @style{wxWS_EX_BLOCK_EVENTS}
            wxCommandEvents and the objects of the derived classes are
            forwarded to the parent window and so on recursively by default.
            Using this flag for the given window allows to block this
            propagation at this window, i.e. prevent the events from being
            propagated further upwards. Dialogs have this flag on by default

-           for the reasons explained in the @ref overview_eventhandling "Event Handling Overview".
+           for the reasons explained in the @ref overview_events.

     @style{wxWS_EX_TRANSIENT}
            Don't use this window as an implicit parent for the other windows:
            this must be used with transient windows as otherwise there is the
     @style{wxWS_EX_TRANSIENT}
            Don't use this window as an implicit parent for the other windows:
            this must be used with transient windows as otherwise there is the


@@ -206,23 +170,76 @@ enum wxUpdateUI
     @style{wxWS_EX_CONTEXTHELP}
            Under Windows, puts a query button on the caption. When pressed,
            Windows will go into a context-sensitive help mode and wxWidgets
     @style{wxWS_EX_CONTEXTHELP}
            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.
+           will send a @c wxEVT_HELP event if the user clicked on an application window.

            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
            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.
+           by wxIdleEvent::SetMode is @c wxIDLE_PROCESS_SPECIFIED.

     @style{wxWS_EX_PROCESS_UI_UPDATES}
            This window should always process UI update events, even if the
     @style{wxWS_EX_PROCESS_UI_UPDATES}
            This window should always process UI update events, even if the

-           mode set by wxUpdateUIEvent::SetMode is wxUPDATE_UI_PROCESS_SPECIFIED.
+           mode set by wxUpdateUIEvent::SetMode is @c wxUPDATE_UI_PROCESS_SPECIFIED.

     @endExtraStyleTable
 
     @endExtraStyleTable
 

+    @beginEventEmissionTable
+    @event{EVT_ACTIVATE(id, func)}
+        Process a @c wxEVT_ACTIVATE event. See wxActivateEvent.
+    @event{EVT_CHILD_FOCUS(func)}
+        Process a @c wxEVT_CHILD_FOCUS event. See wxChildFocusEvent.
+    @event{EVT_CONTEXT_MENU(func)}
+        A right click (or other context menu command depending on platform) has been detected.
+        See wxContextMenuEvent.
+    @event{EVT_HELP(id, func)}
+        Process a @c wxEVT_HELP event. See wxHelpEvent.
+    @event{EVT_HELP_RANGE(id1, id2, func)}
+        Process a @c wxEVT_HELP event for a range of ids. See wxHelpEvent.
+    @event{EVT_DROP_FILES(func)}
+        Process a @c wxEVT_DROP_FILES event. See wxDropFilesEvent.
+    @event{EVT_ERASE_BACKGROUND(func)}
+        Process a @c wxEVT_ERASE_BACKGROUND event. See wxEraseEvent.
+    @event{EVT_SET_FOCUS(func)}
+        Process a @c wxEVT_SET_FOCUS event. See wxFocusEvent.
+    @event{EVT_KILL_FOCUS(func)}
+        Process a @c wxEVT_KILL_FOCUS event. See wxFocusEvent.
+    @event{EVT_IDLE(func)}
+        Process a @c wxEVT_IDLE event. See wxIdleEvent.
+    @event{EVT_JOY_*(func)}
+        Processes joystick events. See wxJoystickEvent.
+    @event{EVT_KEY_DOWN(func)}
+        Process a @c wxEVT_KEY_DOWN event (any key has been pressed).
+        See wxKeyEvent.
+    @event{EVT_KEY_UP(func)}
+        Process a @c wxEVT_KEY_UP event (any key has been released).
+    @event{EVT_CHAR(func)}
+        Process a @c wxEVT_CHAR 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)}
+        Process a @c wxEVT_MOUSE_CAPTURE_CHANGED event. See wxMouseCaptureChangedEvent.
+    @event{EVT_MOUSE_*(func)}
+        See wxMouseEvent.
+    @event{EVT_PAINT(func)}
+        Process a @c wxEVT_PAINT event. See wxPaintEvent.
+    @event{EVT_POWER_*(func)}
+        The system power state changed. See wxPowerEvent.
+    @event{EVT_SCROLLWIN_*(func)}
+        Process scroll events. See wxScrollWinEvent.
+    @event{EVT_SET_CURSOR(func)}
+        Process a @c wxEVT_SET_CURSOR event. See wxSetCursorEvent.
+    @event{EVT_SHOW(func)}
+        Process a @c wxEVT_SHOW event. See wxShowEvent.
+    @event{EVT_SIZE(func)}
+        Process a @c wxEVT_SIZE event. See wxSizeEvent.
+    @event{EVT_SYS_COLOUR_CHANGED(func)}
+        Process a @c wxEVT_SYS_COLOUR_CHANGED event. See wxSysColourChangedEvent.
+    @endEventTable
+

     @library{wxcore}
     @category{miscwnd}
 
     @library{wxcore}
     @category{miscwnd}
 

-    @see @ref overview_eventhandling "Event handling overview",
-         @ref overview_windowsizing "Window sizing overview"
+    @see @ref overview_events, @ref overview_windowsizing

 */
 class wxWindow : public wxEvtHandler
 {
 */
 class wxWindow : public wxEvtHandler
 {


@@ -453,6 +470,9 @@ public:
 
     /**
         @name Scrolling and scrollbars functions
 
     /**
         @name Scrolling and scrollbars functions

+
+        Note that these methods don't work with native controls which don't use
+        wxWidgets scrolling framework (i.e. don't derive from wxScrolledWindow).

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


@@ -474,7 +494,7 @@ public:
     /**
         Returns the built-in scrollbar position.
 
     /**
         Returns the built-in scrollbar position.
 

-        @see See SetScrollbar()
+        @see SetScrollbar()

     */
     virtual int GetScrollPos(int orientation) const;
 
     */
     virtual int GetScrollPos(int orientation) const;
 


@@ -649,6 +669,8 @@ public:
 
     /**
         Sets the cached best size value.
 
     /**
         Sets the cached best size value.

+
+        @see GetBestSize()

     */
     void CacheBestSize(const wxSize& size) const;
 
     */
     void CacheBestSize(const wxSize& size) const;
 


@@ -721,6 +743,11 @@ public:
         control label is not truncated. For windows containing subwindows (typically
         wxPanel), the size returned by this function will be the same as the size
         the window would have had after calling Fit().
         control label is not truncated. For windows containing subwindows (typically
         wxPanel), the size returned by this function will be the same as the size
         the window would have had after calling Fit().

+
+        Note that when you write your own widget you need to overload the
+        DoGetBestSize() function instead of this (non-virtual!) function.
+
+        @see CacheBestSize(), @ref overview_windowsizing

     */
     wxSize GetBestSize() const;
 
     */
     wxSize GetBestSize() const;
 


@@ -746,9 +773,12 @@ public:
         This is the value used by sizers to determine the appropriate
         ammount of space to allocate for the widget.
 
         This is the value used by sizers to determine the appropriate
         ammount of space to allocate for the widget.
 

+        This is the method called by any wxSizer when they query the size
+        of a certain window or control.
+

         @see GetBestSize(), SetInitialSize(), @ref overview_windowsizing
     */
         @see GetBestSize(), SetInitialSize(), @ref overview_windowsizing
     */

-    wxSize GetEffectiveMinSize() const;
+    virtual wxSize GetEffectiveMinSize() const;

 
     /**
         Returns the maximum size of window's client area.
 
     /**
         Returns the maximum size of window's client area.


@@ -757,7 +787,7 @@ public:
         possible size as well as the upper bound on window's size settable using
         SetClientSize().
 
         possible size as well as the upper bound on window's size settable using
         SetClientSize().
 

-        @see GetMaxSize()
+        @see GetMaxSize(), @ref overview_windowsizing

     */
     virtual wxSize GetMaxClientSize() const;
 
     */
     virtual wxSize GetMaxClientSize() const;
 


@@ -767,7 +797,7 @@ public:
         This is an indication to the sizer layout mechanism that this is the maximum
         possible size as well as the upper bound on window's size settable using SetSize().
 
         This is an indication to the sizer layout mechanism that this is the maximum
         possible size as well as the upper bound on window's size settable using SetSize().
 

-        @see GetMaxClientSize()
+        @see GetMaxClientSize(), @ref overview_windowsizing

     */
     virtual wxSize GetMaxSize() const;
 
     */
     virtual wxSize GetMaxSize() const;
 


@@ -778,7 +808,7 @@ public:
         It normally just returns the value set by SetMinClientSize(), but it can be
         overridden to do the calculation on demand.
 
         It normally just returns the value set by SetMinClientSize(), but it can be
         overridden to do the calculation on demand.
 

-        @see GetMinSize()
+        @see GetMinSize(), @ref overview_windowsizing

     */
     virtual wxSize GetMinClientSize() const;
 
     */
     virtual wxSize GetMinClientSize() const;
 


@@ -789,7 +819,7 @@ public:
         This method normally just returns the value set by SetMinSize(), but it
         can be overridden to do the calculation on demand.
 
         This method normally just returns the value set by SetMinSize(), but it
         can be overridden to do the calculation on demand.
 

-        @see GetMinClientSize()
+        @see GetMinClientSize(), @ref overview_windowsizing

     */
     virtual wxSize GetMinSize() const;
 
     */
     virtual wxSize GetMinSize() const;
 


@@ -805,7 +835,7 @@ public:
         @param height
             Receives the window height.
 
         @param height
             Receives the window height.
 

-        @see GetClientSize(), GetVirtualSize()
+        @see GetClientSize(), GetVirtualSize(), @ref overview_windowsizing

     */
     void GetSize(int* width, int* height) const;
 
     */
     void GetSize(int* width, int* height) const;
 


@@ -818,6 +848,8 @@ 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
         SetVirtualSize() it will return the size set with that method.
         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 the size set with that method.

+
+        @see @ref overview_windowsizing

     */
     wxSize GetVirtualSize() const;
 
     */
     wxSize GetVirtualSize() const;
 


@@ -840,8 +872,11 @@ public:
     /**
         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.

+
+        @see CacheBestSize()

     */
     void InvalidateBestSize();
     */
     void InvalidateBestSize();

+

     /**
         Posts a size event to the window.
 
     /**
         Posts a size event to the window.
 


@@ -900,6 +935,8 @@ 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.

+
+        @see @ref overview_windowsizing

     */
     virtual void SetClientSize(int width, int height);
 
     */
     virtual void SetClientSize(int width, int height);
 


@@ -936,7 +973,12 @@ public:
         Sets the maximum client size of the window, to indicate to the sizer
         layout mechanism that this is the maximum possible size of its client area.
 
         Sets the maximum client size of the window, to indicate to the sizer
         layout mechanism that this is the maximum possible size of its client area.
 

-        @see SetMaxSize()
+        Note that this method is just a shortcut for:
+        @code
+        SetMaxSize(ClientToWindowSize(size));
+        @endcode
+
+        @see SetMaxSize(), @ref overview_windowsizing

     */
     virtual void SetMaxClientSize(const wxSize& size);
 
     */
     virtual void SetMaxClientSize(const wxSize& size);
 


@@ -944,7 +986,7 @@ public:
         Sets the maximum size of the window, to indicate to the sizer layout mechanism
         that this is the maximum possible size.
 
         Sets the maximum size of the window, to indicate to the sizer layout mechanism
         that this is the maximum possible size.
 

-        @see SetMaxClientSize()
+        @see SetMaxClientSize(), @ref overview_windowsizing

     */
     virtual void SetMaxSize(const wxSize& size);
 
     */
     virtual void SetMaxSize(const wxSize& size);
 


@@ -960,7 +1002,12 @@ public:
         prevent the program from explicitly making the window smaller than the
         specified size.
 
         prevent the program from explicitly making the window smaller than the
         specified size.
 

-        @see SetMinSize()
+        Note that this method is just a shortcut for:
+        @code
+        SetMinSize(ClientToWindowSize(size));
+        @endcode
+
+        @see SetMinSize(), @ref overview_windowsizing

     */
     virtual void SetMinClientSize(const wxSize& size);
 
     */
     virtual void SetMinClientSize(const wxSize& size);
 


@@ -976,7 +1023,7 @@ public:
         SetSize(), it just ensures that it won't become smaller than this size
         during the automatic layout.
 
         SetSize(), it just ensures that it won't become smaller than this size
         during the automatic layout.
 

-        @see SetMinClientSize()
+        @see SetMinClientSize(), @ref overview_windowsizing

     */
     virtual void SetMinSize(const wxSize& size);
 
     */
     virtual void SetMinSize(const wxSize& size);
 


@@ -1021,7 +1068,7 @@ public:
                  should be supplied by wxWidgets, or that the current value of the
                  dimension should be used.
 
                  should be supplied by wxWidgets, or that the current value of the
                  dimension should be used.
 

-        @see Move()
+        @see Move(), @ref overview_windowsizing

     */
     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);


@@ -1032,7 +1079,7 @@ public:
 
         @remarks This form must be used with non-default width and height values.
 
 
         @remarks This form must be used with non-default width and height values.
 

-        @see Move()
+        @see Move(), @ref overview_windowsizing

     */
     virtual void SetSize(const wxRect& rect);
 
     */
     virtual void SetSize(const wxRect& rect);
 


@@ -1051,7 +1098,7 @@ public:
         (such as wxDialog or wxFrame) is discouraged.
         Please use SetMinSize() and SetMaxSize() instead.
 
         (such as wxDialog or wxFrame) is discouraged.
         Please use SetMinSize() and SetMaxSize() instead.
 

-        @see wxTopLevelWindow::SetSizeHints
+        @see wxTopLevelWindow::SetSizeHints, @ref overview_windowsizing

     */
     void SetSizeHints( const wxSize& minSize,
                        const wxSize& maxSize=wxDefaultSize,
     */
     void SetSizeHints( const wxSize& minSize,
                        const wxSize& maxSize=wxDefaultSize,


@@ -1059,6 +1106,8 @@ public:
 
     /**
         Sets the virtual size of the window in pixels.
 
     /**
         Sets the virtual size of the window in pixels.

+
+        @see @ref overview_windowsizing

     */
     void SetVirtualSize(int width, int height);
 
     */
     void SetVirtualSize(int width, int height);
 


@@ -1687,14 +1736,26 @@ public:
         @code
         GetEventHandler()->SafelyProcessEvent(event);
         @endcode
         @code
         GetEventHandler()->SafelyProcessEvent(event);
         @endcode

+
+        @see ProcessWindowEvent()

     */
     bool HandleWindowEvent(wxEvent& event) const;
 
     */
     bool HandleWindowEvent(wxEvent& event) const;
 

+    /**
+        Convenient wrapper for ProcessEvent().
+
+        This is the same as writing @code GetEventHandler()->ProcessEvent(event);
+        @endcode but more convenient. Notice that ProcessEvent() itself can't
+        be called for wxWindow objects as it ignores the event handlers
+        associated with the window, use this function instead.
+    */
+    bool ProcessWindowEvent(wxEvent& event);
+

     /**
         Removes and returns the top-most event handler on the event handler stack.
 
         E.g. in the case of:
     /**
         Removes and returns the top-most event handler on the event handler stack.
 
         E.g. in the case of:

-            @image html overview_eventhandling_winstack.png
+            @image html overview_events_winstack.png

         when calling @c W->PopEventHandler(), the event handler @c A will be
         removed and @c B will be the first handler of the stack.
 
         when calling @c W->PopEventHandler(), the event handler @c A will be
         removed and @c B will be the first handler of the stack.
 


@@ -1706,7 +1767,7 @@ public:
             If this is @true, the handler will be deleted after it is removed
             (and the returned value will be @NULL).
 
             If this is @true, the handler will be deleted after it is removed
             (and the returned value will be @NULL).
 

-        @see @ref overview_eventhandling_processing
+        @see @ref overview_events_processing

     */
     wxEvtHandler* PopEventHandler(bool deleteHandler = false);
 
     */
     wxEvtHandler* PopEventHandler(bool deleteHandler = false);
 


@@ -1729,7 +1790,7 @@ public:
             W->PushEventHandler(B);
         @endcode
         you will end up with the following situation:
             W->PushEventHandler(B);
         @endcode
         you will end up with the following situation:

-            @image html overview_eventhandling_winstack.png
+            @image html overview_events_winstack.png

 
         Note that you can use wxWindow::PopEventHandler to remove the event handler.
 
 
         Note that you can use wxWindow::PopEventHandler to remove the event handler.
 


@@ -1738,13 +1799,15 @@ public:
             It must not be part of a wxEvtHandler chain; an assert will fail
             if it's not unlinked (see wxEvtHandler::IsUnlinked).
 
             It must not be part of a wxEvtHandler chain; an assert will fail
             if it's not unlinked (see wxEvtHandler::IsUnlinked).
 

-        @see @ref overview_eventhandling_processing
+        @see @ref overview_events_processing

     */
     void PushEventHandler(wxEvtHandler* handler);
 
     /**
     */
     void PushEventHandler(wxEvtHandler* handler);
 
     /**

-        Find the given @a handler in the windows event handler stack and unlinks
-        (but not delete) it. See wxEvtHandler::Unlink() for more info.
+        Find the given @a handler in the windows event handler stack and
+        removes (but does not delete) it from the stack.
+
+        See wxEvtHandler::Unlink() for more info.

 
         @param handler
             The event handler to remove, must be non-@NULL and
 
         @param handler
             The event handler to remove, must be non-@NULL and


@@ -1768,7 +1831,7 @@ public:
         @param handler
             Specifies the handler to be set. Cannot be @NULL.
 
         @param handler
             Specifies the handler to be set. Cannot be @NULL.
 

-        @see @ref overview_eventhandling_processing
+        @see @ref overview_events_processing

     */
     void SetEventHandler(wxEvtHandler* handler);
 
     */
     void SetEventHandler(wxEvtHandler* handler);
 


@@ -2319,6 +2382,12 @@ public:
     */
     virtual wxString GetLabel() const;
 
     */
     virtual wxString GetLabel() const;
 

+    /**
+        Returns the layout direction for this window,
+        Note that @c wxLayout_Default is returned if layout direction is not supported.
+    */
+    virtual wxLayoutDirection GetLayoutDirection() const;
+

     /**
         Returns the window's name.
 
     /**
         Returns the window's name.
 


@@ -2357,6 +2426,11 @@ public:
     */
     virtual void SetLabel(const wxString& label);
 
     */
     virtual void SetLabel(const wxString& label);
 

+    /**
+        Sets the layout direction for this window.
+    */
+    virtual void SetLayoutDirection(wxLayoutDirection dir);
+

     /**
         Sets the window's name.
 
     /**
         Sets the window's name.
 


@@ -2377,7 +2451,6 @@ public:
     */
     void SetWindowVariant(wxWindowVariant variant);
 
     */
     void SetWindowVariant(wxWindowVariant variant);
 

-

     /**
         Gets the accelerator table for this window. See wxAcceleratorTable.
     */
     /**
         Gets the accelerator table for this window. See wxAcceleratorTable.
     */


@@ -2892,7 +2965,7 @@ public:
         are concerned). This may be necessary if you have called
         wxUpdateUIEvent::SetMode() or wxUpdateUIEvent::SetUpdateInterval() to limit
         the overhead that wxWidgets incurs by sending update UI events in idle time.
         are concerned). This may be necessary if you have called
         wxUpdateUIEvent::SetMode() or wxUpdateUIEvent::SetUpdateInterval() to limit
         the overhead that wxWidgets incurs by sending update UI events in idle time.

-        @a flags should be a bitlist of one or more of the wxUpdateUI enumeration.
+        @a flags should be a bitlist of one or more of the ::wxUpdateUI enumeration.

 
         If you are calling this function from an OnInternalIdle or OnIdle
         function, make sure you pass the wxUPDATE_UI_FROMIDLE flag, since
 
         If you are calling this function from an OnInternalIdle or OnIdle
         function, make sure you pass the wxUPDATE_UI_FROMIDLE flag, since


@@ -3087,18 +3160,29 @@ protected:
      */
     void SendDestroyEvent();
 
      */
     void SendDestroyEvent();
 

-    //@{

     /**
     /**

-        This function is public in wxEvtHandler but is protected in wxWindow because
-        for wxWindows you should always use this function on the pointer returned
-        by GetEventHandler() and not on the wxWindow object itself.
+        This function is public in wxEvtHandler but protected in wxWindow
+        because for wxWindows you should always call ProcessEvent() on the
+        pointer returned by GetEventHandler() and not on the wxWindow object
+        itself.
+
+        For convenience, a ProcessWindowEvent() method is provided as a synonym
+        for @code GetEventHandler()->ProcessEvent() @endcode.

 
         Note that it's still possible to call these functions directly on the
 
         Note that it's still possible to call these functions directly on the

-        wxWindow object (e.g. downcasting it to wxEvtHandler) but doing that
-        will create subtle bugs when windows with event handlers pushed on them
-        are involved.
+        wxWindow object (e.g. casting it to wxEvtHandler) but doing that will
+        create subtle bugs when windows with event handlers pushed on them are
+        involved.
+
+        This holds also for all other wxEvtHandler functions.

     */
     virtual bool ProcessEvent(wxEvent& event);
     */
     virtual bool ProcessEvent(wxEvent& event);

+
+    //@{
+    /**
+        See ProcessEvent() for more info about why you shouldn't use this function
+        and the reason for making this function protected in wxWindow.
+    */

     bool SafelyProcessEvent(wxEvent& event);
     virtual void QueueEvent(wxEvent *event);
     virtual void AddPendingEvent(const wxEvent& event);
     bool SafelyProcessEvent(wxEvent& event);
     virtual void QueueEvent(wxEvent *event);
     virtual void AddPendingEvent(const wxEvent& event);