added wxTopLevelWindow::RequestUserAttention(); documented it and implemented it for MSW

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

include/wx/toplevel.h

@@ -104,6 +104,13 @@ enum
                                wxFULLSCREEN_NOCAPTION
 };
 
+// Styles for RequestUserAttention
+enum
+{
+    wxUSER_ATTENTION_INFO = 1,
+    wxUSER_ATTENTION_ERROR = 2
+};
+
 // ----------------------------------------------------------------------------
 // wxTopLevelWindow: a top level (as opposed to child) window
 // ----------------------------------------------------------------------------
@@ -164,6 +171,11 @@ public:
     // operation is successful.)
     virtual bool SetShape(const wxRegion& WXUNUSED(region)) { return FALSE; }
 
+    // Attracts the users attention to this window if the application is
+    // inactive (should be called when a background event occurs)
+    virtual void RequestUserAttention(int flags = wxUSER_ATTENTION_INFO);
+
+
     // implementation only from now on
     // -------------------------------