Don't use wxWindow::ClearBackground() in the image sample and explain why.

Painting on both wxPaintDC and wxClientDC simultaneously doesn't work well,
e.g. under Windows the client DC can be actually erased after we finished
painting the window contents, overwriting it.

Simply use wxDC::Clear() instead of wxWindow::ClearBackground() to avoid this
and document the danger of using ClearBackground() from EVT_PAINT handler.

Closes #10700.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@64277 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

interface/wx/window.h

@@ -1423,8 +1423,14 @@ public:
     //@{
 
     /**
-        Clears the window by filling it with the current background colour. Does not
-        cause an erase background event to be generated.
+        Clears the window by filling it with the current background colour.
+
+        Does not cause an erase background event to be generated.
+
+        Notice that this uses wxClientDC to draw on the window and the results
+        of doing it while also drawing on wxPaintDC for this window are
+        undefined. Hence this method shouldn't be used from EVT_PAINT handlers,
+        just use wxDC::Clear() on the wxPaintDC you already use there instead.
     */
     virtual void ClearBackground();
 

samples/image/image.cpp

@@ -185,11 +185,8 @@ private:
     {
         wxPaintDC dc(this);
 
-#ifndef __WXOSX__
-        // on OSX the immediate Update from within ClearBackground leads to a recursion
         if ( GetMenuBar()->IsChecked(ID_PAINT_BG) )
-            ClearBackground();
-#endif
+            dc.Clear();
 
         dc.SetUserScale(m_zoom, m_zoom);