X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/86381d4297f0225448823369a0df73ba67664078..50d4763f1710f6e45ac6af7112d1ce9effe93bc4:/interface/wx/window.h

diff --git a/interface/wx/window.h b/interface/wx/window.h
index 192ce514f6..524605b004 100644
--- a/interface/wx/window.h
+++ b/interface/wx/window.h
@@ -53,18 +53,21 @@ enum wxShowEffect
 
 
 /**
-   struct containing all the visual attributes of a control
+    Struct containing all the visual attributes of a control.
 */
 struct  wxVisualAttributes
 {
-    // the font used for control label/text inside it
+    /// The font used for control label/text inside it.
     wxFont font;
 
-    // the foreground colour
+    /// The foreground colour.
     wxColour colFg;
 
-    // the background colour, may be wxNullColour if the controls background
-    // colour is not solid
+    /**
+        The background colour.
+
+        May be wxNullColour if the controls background colour is not solid.
+     */
     wxColour colBg;
 };
 
@@ -1697,13 +1700,18 @@ public:
 
     /**
         Sets the background colour of the window.
+
+        Notice that as with SetForegroundColour(), setting the background
+        colour of a native control may not affect the entire control and could
+        be not supported at all depending on the control and platform.
+
         Please see InheritAttributes() for explanation of the difference between
         this method and SetOwnBackgroundColour().
 
         @param colour
             The colour to be used as the background colour; pass
             wxNullColour to reset to the default colour.
-            Note that you may want to use wxSystemSettings::GetColour() to retrieve 
+            Note that you may want to use wxSystemSettings::GetColour() to retrieve
             a suitable colour to use rather than setting an hard-coded one.
 
         @remarks The background colour is usually painted by the default
@@ -1750,11 +1758,57 @@ public:
         @c wxBG_STYLE_PAINT is a simpler and more efficient solution to the same
         problem.
 
+
+        Under wxGTK and wxOSX, you can use ::wxBG_STYLE_TRANSPARENT to obtain
+        full transparency of the window background. Note that wxGTK supports
+        this only since GTK 2.12 with a compositing manager enabled, call
+        IsTransparentBackgroundSupported() to check whether this is the case.
+
+        Also, on order for @c SetBackgroundStyle(wxBG_STYLE_TRANSPARENT) to
+        work, it must be called before Create(). If you're using your own
+        wxWindow-derived class you should write your code in the following way:
+        @code
+            class MyWidget : public wxWindow
+            {
+            public:
+                MyWidget(wxWindow* parent, ...)
+                    : wxWindow() // Use default ctor here!
+                {
+                    // Do this first:
+                    SetBackgroundStyle(wxBG_STYLE_TRANSPARENT);
+
+                    // And really create the window afterwards:
+                    Create(parent, ...);
+                }
+            };
+        @endcode
+
         @see SetBackgroundColour(), GetForegroundColour(),
-             SetTransparent()
+             SetTransparent(), IsTransparentBackgroundSupported()
     */
     virtual bool SetBackgroundStyle(wxBackgroundStyle style);
 
+    /**
+        Checks whether using transparent background might work.
+
+        If this function returns @false, calling SetBackgroundStyle() with
+        ::wxBG_STYLE_TRANSPARENT is not going to work. If it returns @true,
+        setting transparent style should normally succeed.
+
+        Notice that this function would typically be called on the parent of a
+        window you want to set transparent background style for as the window
+        for which this method is called must be fully created.
+
+        @param reason
+            If not @NULL, a reason message is provided if transparency is not
+            supported.
+
+        @return @true if background transparency is supported.
+
+        @since 2.9.4
+    */
+    virtual bool IsTransparentBackgroundSupported(wxString *reason = NULL) const;
+
     /**
         Sets the font for this window. This function should not be called for the
         parent window if you don't want its font to be inherited by its children,
@@ -1780,6 +1834,13 @@ public:
 
     /**
         Sets the foreground colour of the window.
+
+        The meaning of foreground colour varies according to the window class;
+        it may be the text colour or other colour, or it may not be used at
+        all. Additionally, not all native controls support changing their
+        foreground colour so this method may change their colour only partially
+        or even not at all.
+
         Please see InheritAttributes() for explanation of the difference between
         this method and SetOwnForegroundColour().
 
@@ -1787,9 +1848,6 @@ public:
             The colour to be used as the foreground colour; pass
             wxNullColour to reset to the default colour.
 
-        @remarks The meaning of foreground colour varies according to the window class;
-                 it may be the text colour or other colour, or it may not be used at all.
-
         @return @true if the colour was really changed, @false if it was already set
                 to this colour and nothing was done.
 
@@ -3033,7 +3091,7 @@ public:
     /**
         Returns the platform-specific handle of the physical window.
         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.
+        @b Widget for Motif or @b GtkWidget for GTK.
 
         @beginWxPerlOnly
         This method will return an integer in wxPerl.