Allow customizing wxBusyInfo appearance.

Allow customizing wxBusyInfo window by passing wxBusyInfoFlags containing
information about the icon, title, colours and frame transparency to use.

Update the sample to show such "rich" busy info.

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

interface/wx/busyinfo.h

@@ -9,8 +9,13 @@
     @class wxBusyInfo
 
     This class makes it easy to tell your user that the program is temporarily busy.
-    Just create a wxBusyInfo object on the stack, and within the current scope,
-    a message window will be shown.
+
+    Normally the main thread should always return to the main loop to continue
+    dispatching events as quickly as possible, hence this class shouldn't be
+    needed. However if the main thread does need to block, this class provides
+    a simple way to at least show this to the user: just create a wxBusyInfo
+    object on the stack, and within the current scope, a message window will be
+    shown.
 
     For example:
 
@@ -26,6 +31,28 @@
     It works by creating a window in the constructor, and deleting it
     in the destructor.
 
+    This window is rather plain by default but can be customized by passing
+    wxBusyInfo constructor an object of wxBusyInfoFlags class instead of a
+    simple message. Here is an example from the @ref page_samples_dialogs:
+    @code
+        wxBusyInfo info
+            (
+                wxBusyInfoFlags()
+                    .Parent(this)
+                    .Icon(wxArtProvider::GetIcon(wxART_PRINT,
+                                                 wxART_OTHER, wxSize(128, 128)))
+                    .Title("<b>Printing your document</b>")
+                    .Text("Please wait...")
+                    .Foreground(*wxWHITE)
+                    .Background(*wxBLACK)
+                    .Transparency(4*wxALPHA_OPAQUE/5)
+            );
+    @endcode
+    showing that separate title and text can be set, and that simple markup
+    (@ref wxControl::SetLabelMarkup()) can be used in them, and that it's also
+    possible to add an icon and customize the colours and transparency of the
+    window.
+
     You may also want to call wxTheApp->Yield() to refresh the window
     periodically (in case it had been obscured by other windows, for
     example) like this:
@@ -57,7 +84,25 @@ class wxBusyInfo
 {
 public:
     /**
-        Constructs a busy info window as child of @a parent and displays @e msg in it.
+        General constructor.
+
+        This constructor allows to specify all supported attributes by calling
+        the appropriate methods on wxBusyInfoFlags object passed to it as
+        parameter. All of them are optional but usually at least the message
+        should be specified.
+
+        @since 3.1.0
+     */
+    wxBusyInfo(const wxBusyInfoFlags& flags);
+
+    /**
+        Simple constructor specifying only the message and the parent.
+
+        This constructs a busy info window as child of @a parent and displays
+        @a msg in it. It is exactly equivalent to using
+        @code
+            wxBusyInfo(wxBusyInfoFlags().Parent(parent).Label(message))
+        @endcode
 
         @note If @a parent is not @NULL you must ensure that it is not
               closed while the busy info is shown.
@@ -70,3 +115,86 @@ public:
     virtual ~wxBusyInfo();
 };
 
+/**
+    Parameters for wxBusyInfo.
+
+    This class exists only in order to make passing attributes to wxBusyInfo
+    constructor easier and the code doing it more readable.
+
+    All methods of this class return the reference to the object on which they
+    are called, making it possible to chain them together, e.g. typically you
+    would just create a temporary wxBusyInfoFlags object and then call the
+    methods corresponding to the attributes you want to set, before finally
+    passing the result to wxBusyInfo constructor, e.g.:
+    @code
+        wxBusyInfo info
+            (
+                wxBusyInfoFlags()
+                    .Parent(window)
+                    .Icon(icon)
+                    .Title("Some text")
+                    .Text("Some more text")
+                    .Foreground(wxColour(...))
+                    .Background(wxColour(...))
+            );
+    @endcode
+
+    @since 3.1.0
+ */
+class wxBusyInfoFlags
+{
+public:
+    /**
+        Default constructor initializes all attributes to default values.
+
+        Call the other methods to really fill in the object.
+     */
+    wxBusyInfoFlags();
+
+    /// Sets the parent for wxBusyInfo.
+    wxBusyInfoFlags& Parent(wxWindow* parent);
+
+    /// Sets the icon to show in wxBusyInfo.
+    wxBusyInfoFlags& Icon(const wxIcon& icon);
+
+    /**
+        Sets the title, shown prominently in wxBusyInfo window.
+
+        The @a title string may contain markup as described in
+        wxControl::SetLabelMarkup().
+     */
+    wxBusyInfoFlags& Title(const wxString& title);
+
+    /**
+        Sets the more detailed text, shown under the title, if any.
+
+        The @a text string may contain markup as described in
+        wxControl::SetLabelMarkup().
+     */
+    wxBusyInfoFlags& Text(const wxString& text);
+
+    /**
+        Same as Text() but doesn't interpret the string as containing markup.
+
+        This method should be used if the text shown in wxBusyInfo comes from
+        external source and so may contain characters having special meaning in
+        simple markup, e.g. '<'.
+     */
+    wxBusyInfoFlags& Label(const wxString& label);
+
+    /// Sets the foreground colour of the title and text strings.
+    wxBusyInfoFlags& Foreground(const wxColour& foreground);
+
+    /// Sets the background colour of wxBusyInfo window.
+    wxBusyInfoFlags& Background(const wxColour& background);
+
+    /**
+        Sets the transparency of wxBusyInfo window.
+
+        @param alpha Value in wxALPHA_TRANSPARENT (0) to wxALPHA_OPAQUE (255)
+            range.
+
+        @see wxTopLevelWindow::SetTransparent()
+     */
+    wxBusyInfoFlags& Transparency(wxByte alpha);
+};