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

interface/wx/defs.h

@@ -136,28 +136,54 @@ enum wxBorder
 
 
 /**
-    Background styles. See wxWindow::SetBackgroundStyle().
+    Background styles.
+
+    @see wxWindow::SetBackgroundStyle()
 */
 enum wxBackgroundStyle
 {
-    /// Use the default background, as determined by
-    /// the system or the current theme.
+    /**
+        Default background style value indicating that the background may be
+        erased in the user-defined EVT_ERASE_BACKGROUND handler.
+
+        If no such handler is defined (or if it skips the event), the effect of
+        this style is the same as wxBG_STYLE_SYSTEM. If an empty handler (@em
+        not skipping the event) is defined, the effect is the same as
+        wxBG_STYLE_PAINT, i.e. the background is not erased at all until
+        EVT_PAINT handler is executed.
+
+        This is the only background style value for which erase background
+        events are generated at all.
+     */
+    wxBG_STYLE_ERASE,
+
+    /**
+        Use the default background, as determined by the system or the current
+        theme.
+
+        If the window has been assigned a non-default background colour, it
+        will be used for erasing its background. Otherwise the default
+        background (which might be a gradient or a pattern) will be used.
+
+        EVT_ERASE_BACKGROUND event will not be generated at all for windows
+        with this style.
+     */
     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,
+    /**
+        Indicates that the background is only erased in the user-defined
+        EVT_PAINT handler.
 
-    /// 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,
+        Using this style avoids flicker which would result from redrawing the
+        background twice if the EVT_PAINT handler entirely overwrites it. It
+        must not be used however if the paint handler leaves any parts of the
+        window unpainted as their contents is then undetermined. Only use it if
+        you repaint the whole window in your handler.
 
-    /// 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
+        EVT_ERASE_BACKGROUND event will not be generated at all for windows
+        with this style.
+     */
+    wxBG_STYLE_PAINT
 };
 
 

interface/wx/window.h

@@ -1418,12 +1418,12 @@ public:
 
     /**
         Returns the background style of the window.
-        The background style can be one of the wxBackgroundStyle.
 
         @see SetBackgroundColour(), GetForegroundColour(),
              SetBackgroundStyle(), SetTransparent()
     */
     virtual wxBackgroundStyle GetBackgroundStyle() const;
+
     /**
         Returns the character height for this window.
     */
@@ -1583,8 +1583,28 @@ public:
     virtual bool SetBackgroundColour(const wxColour& colour);
 
     /**
-        Sets the background style of the window. see GetBackgroundStyle() for
-        the description of the possible style values.
+        Sets the background style of the window.
+
+        The default background style is wxBG_STYLE_ERASE which indicates that
+        the window background may be erased in EVT_ERASE_BACKGROUND handler.
+        This is a safe compatibility default however you may want to change it
+        to wxBG_STYLE_SYSTEM if you don't define any erase background event
+        handlers at all to avoid unnecessary generation of erase background
+        events and always let system erase the background. And you should
+        change the background style to wxBG_STYLE_PAINT if you define an
+        EVT_PAINT handler which completely overwrites the window background as
+        in this case erasing it previously, either in EVT_ERASE_BACKGROUND
+        handler or in the system default handler, would result in flicker as
+        the background pixels will be repainted twice every time the window is
+        redrawn. Do ensure that the background is entirely erased by your
+        EVT_PAINT handler in this case however as otherwise garbage may be left
+        on screen.
+
+        Notice that in previous versions of wxWidgets a common way to work
+        around the above mentioned flickering problem was to define an empty
+        EVT_ERASE_BACKGROUND handler. Setting background style to
+        wxBG_STYLE_PAINT is a simpler and more efficient solution to the same
+        problem.
 
         @see SetBackgroundColour(), GetForegroundColour(),
              SetTransparent()