introduce wxBG_STYLE_{ERASE,PAINT} and implement their documented semantics in wxGTK

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

include/wx/dcbuffer.h

@@ -219,8 +219,8 @@ public:
     wxAutoBufferedPaintDC(wxWindow* win)
         : wxAutoBufferedPaintDCBase(win)
     {
-        wxASSERT_MSG( win->GetBackgroundStyle() == wxBG_STYLE_CUSTOM,
-            "You need to call SetBackgroundStyle(wxBG_STYLE_CUSTOM) in ctor, "
+        wxASSERT_MSG( win->GetBackgroundStyle() == wxBG_STYLE_PAINT,
+            "You need to call SetBackgroundStyle(wxBG_STYLE_PAINT) in ctor, "
             "and also, if needed, paint the background in wxEVT_PAINT handler."
         );
     }

include/wx/defs.h

@@ -1836,13 +1836,32 @@ enum wxBorder
 /*
  * Background styles. See wxWindow::SetBackgroundStyle
  */
-
 enum wxBackgroundStyle
 {
-  wxBG_STYLE_SYSTEM,
-  wxBG_STYLE_COLOUR,
-  wxBG_STYLE_CUSTOM,
-  wxBG_STYLE_TRANSPARENT
+    // background is erased in the EVT_ERASE_BACKGROUND handler or using the
+    // system default background if no such handler is defined (this is the
+    // default style)
+    wxBG_STYLE_ERASE,
+
+    // background is erased by the system, no EVT_ERASE_BACKGROUND event is
+    // generated at all
+    wxBG_STYLE_SYSTEM,
+
+    // background is erased in EVT_PAINT handler and not erased at all before
+    // it, this should be used if the paint handler paints over the entire
+    // window to avoid flicker
+    wxBG_STYLE_PAINT,
+
+
+    // this is a Mac-only style, don't use in portable code
+    wxBG_STYLE_TRANSPARENT,
+
+    // this style is deprecated and doesn't do anything, don't use
+    wxBG_STYLE_COLOUR,
+
+    // this style is deprecated and is synonymous with wxBG_STYLE_PAINT, use
+    // the new name
+    wxBG_STYLE_CUSTOM = wxBG_STYLE_PAINT
 };
 
 /*

include/wx/window.h

@@ -1032,9 +1032,10 @@ public:
     wxColour GetForegroundColour() const;
 
         // Set/get the background style.
-        // Pass one of wxBG_STYLE_SYSTEM, wxBG_STYLE_COLOUR, wxBG_STYLE_CUSTOM
-    virtual bool SetBackgroundStyle(wxBackgroundStyle style) { m_backgroundStyle = style; return true; }
-    virtual wxBackgroundStyle GetBackgroundStyle() const { return m_backgroundStyle; }
+    virtual bool SetBackgroundStyle(wxBackgroundStyle style)
+        { m_backgroundStyle = style; return true; }
+    wxBackgroundStyle GetBackgroundStyle() const
+        { return m_backgroundStyle; }
 
         // returns true if the control has "transparent" areas such as a
         // wxStaticText and wxCheckBox and the background should be adapted