Add doxygen docs of wxTaskBarButton.

Author: Chaobin Zhang

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

include/wx/msw/taskbarbutton.h

@@ -35,8 +35,9 @@ public:
     virtual bool InsertThumbBarButton(size_t pos,
                                       wxThumbBarButton *button) wxOVERRIDE;
     virtual bool AppendThumbBarButton(wxThumbBarButton *button) wxOVERRIDE;
-    virtual bool RemoveThumbBarButton(wxThumbBarButton *button) wxOVERRIDE;
-    virtual bool RemoveThumbBarButton(int id) wxOVERRIDE;
+    virtual wxThumbBarButton* RemoveThumbBarButton(
+        wxThumbBarButton *button) wxOVERRIDE;
+    virtual wxThumbBarButton* RemoveThumbBarButton(int id) wxOVERRIDE;
 
 private:
     friend class wxFrame;

include/wx/taskbarbutton.h

@@ -84,8 +84,8 @@ public:
     virtual void SetThumbnailContents(const wxWindow *child) = 0;
     virtual bool InsertThumbBarButton(size_t pos, wxThumbBarButton *button) = 0;
     virtual bool AppendThumbBarButton(wxThumbBarButton *button) = 0;
-    virtual bool RemoveThumbBarButton(wxThumbBarButton *button) = 0;
-    virtual bool RemoveThumbBarButton(int id) = 0;
+    virtual wxThumbBarButton* RemoveThumbBarButton(wxThumbBarButton *button) = 0;
+    virtual wxThumbBarButton* RemoveThumbBarButton(int id) = 0;
 
 private:
     wxDECLARE_NO_COPY_CLASS(wxTaskBarButton);

interface/wx/frame.h

@@ -445,6 +445,23 @@ public:
     */
     virtual void SetToolBar(wxToolBar* toolBar);
 
+    /**
+        MSW-specific function for accessing the taskbar button under Windows 7 or later.
+
+        Returns a wxTaskBarButton pointer representing the taskbar button of the
+        window under Windows 7 or later. The returned wxTaskBarButton may be
+        used, if non-@c NULL, to access the functionality including thumbnail
+        representations, thumbnail toolbars, notification and status overlays,
+        and progress indicators.
+
+        The returned pointer must @em not be deleted, it is owned by the frame
+        and will be only deleted when the frame itself is destroyed.
+
+        This function is not available in the other ports by design, any
+        occurrences of it in the portable code must be guarded by
+        @code #ifdef __WXMSW__ @endcode preprocessor guards.
+    */
+    wxTaskBarButton* MSWGetTaskBarButton();
 
     void PushStatusText(const wxString &text, int number = 0);
     void PopStatusText(int number = 0);

interface/wx/taskbarbutton.h

@@ -0,0 +1,264 @@
+/////////////////////////////////////////////////////////////////////////////
+// Name:        taskbarbutton.h
+// Purpose:     interface of wxTaskBarButton
+// Author:      wxWidgets team
+// Licence:     wxWindows licence
+/////////////////////////////////////////////////////////////////////////////
+
+/**
+    State of the taskbar button.
+*/
+enum WXDLLIMPEXP_CORE wxTaskBarButtonState
+{
+    wxTASKBAR_BUTTON_NO_PROGRESS   = 0,
+    wxTASKBAR_BUTTON_INDETERMINATE = 1,
+    wxTASKBAR_BUTTON_NORMAL        = 2,
+    wxTASKBAR_BUTTON_ERROR         = 4,
+    wxTASKBAR_BUTTON_PAUSED        = 8
+};
+
+/**
+    @class wxThumbBarButton
+
+    A thumbnail toolbar button is a control that displayed in the thumbnail
+    image of a window in a taskbar button flyout.
+
+    @library{wxcore}
+    @category{misc}
+
+    @onlyfor{wxmsw}
+
+    @see wxTaskBarButton
+*/
+class WXDLLIMPEXP_CORE wxThumbBarButton {
+public:
+
+    /**
+        Constructs the thumbnail toolbar button.
+
+        @param id
+            The identifier for the control.
+        @param icon
+            The icon used as the button image.
+        @param tooltip
+            The text of the button's tooltip, displayed when the mouse pointer
+            hovers over the button.
+        @param enable
+            If @true (default), the button is active and available to the user.
+            If @false, the button is disabled. It is present, but has a visual
+            state that indicates that it will not respond to user action.
+        @param dismissOnClick
+            If @true, when the button is clicked, the taskbar button's flyout
+            closes immediately. @false by default.
+        @param hasBackground
+            If @false, the button border is not drawn. @true by default.
+        @param shown
+            If @false, the button is not shown to the user. @true by default.
+        @param interactive
+            If @false, the button is enabled but not interactive; no pressed
+            button state is drawn. This flag is intended for instances where
+            the button is used in a notification. @true by default.
+    */
+    wxThumbBarButton(int id,
+                     const wxIcon& icon,
+                     const wxString& tooltip = wxString(),
+                     bool enable = true,
+                     bool dismissOnClick = false,
+                     bool hasBackground = true,
+                     bool shown = true,
+                     bool interactive = true);
+
+    virtual ~wxThumbBarButton();
+
+    /**
+        Returns the identifier associated with this control.
+    */
+    int GetID() const;
+
+    /**
+        Returns the icon associated with this control.
+    */
+    const wxIcon& GetIcon() const;
+
+    /**
+        Return the tooltip.
+    */
+    const wxString& GetTooltip() const;
+
+    /**
+        Return @true if the button is enabled, @false if it has been disabled.
+    */
+    bool IsEnable() const;
+
+    /**
+        Return @true if the button will dismiss on click.
+    */
+    bool IsDismissOnClick() const;
+
+    /**
+        Return @true if the button has button border.
+    */
+    bool HasBackground() const;
+
+    /**
+        Returns @true if the button is shown, @false if it has been hidden.
+    */
+    bool IsShown() const;
+
+    /**
+        Return @true if the button is interactive.
+    */
+    bool IsInteractive() const;
+};
+
+/**
+    @class wxTaskBarButton
+
+    A taskbar button that associated with the window under Windows 7 or later.
+
+    It is used to access the functionality including thumbnail representations,
+    thumbnail toolbars, notification and status overlays, and progress
+    indicators.
+
+    @note This class is only created and initialized in the internal implementation
+    of wxFrame by design. You can only get the pointer of the instance which
+    associated with the frame by calling wxFrame::MSWGetTaskBarButton().
+
+    @library{wxcore}
+    @category{misc}
+
+    @nativeimpl{wxmsw}
+    @onlyfor{wxmsw}
+
+    @see wxFrame::MSWGetTaskBarButton()
+*/
+class WXDLLIMPEXP_CORE wxTaskBarButton
+{
+public:
+    /**
+        Starts showing a determinate progress indicator.
+
+        Call SetProgressValue() after this call to update the progress
+        indicator.
+
+        If @a range is 0, the progress indicator is dismissed.
+    */
+    virtual void SetProgressRange(int range);
+
+    /**
+        Update the determinate progress indicator.
+
+        @param value Must be in the range from 0 to the argument to the last
+        SetProgressRange() call. When it is equal to the range, the progress
+        bar is dismissed.
+    */
+    virtual void SetProgressValue(int value);
+
+    /**
+        Updates indeterminate progress indicator.
+
+        The first call to this method starts showing the indeterminate progress
+        indicator if it hadn't been shown yet.
+
+        Call SetProgressRange(0) to stop showing the progress indicator.
+    */
+    virtual void PulseProgress();
+
+    /**
+        Show in the taskbar.
+    */
+    virtual void Show(bool show = true);
+
+    /**
+        Hide in the taskbar.
+    */
+    virtual void Hide();
+
+    /**
+        Specifies or updates the text of the tooltip that is displayed
+        when the mouse pointer rests on an individual preview thumbnail
+        in a taskbar button flyout.
+    */
+    virtual void SetThumbnailTooltip(const wxString& tooltip);
+
+    /**
+        Set the state of the progress indicator displayed on a taskbar button.
+
+        @see wxTaskBarButtonState
+    */
+    virtual void SetProgressState(wxTaskBarButtonState state);
+
+    /**
+        Set an overlay icon to indicate application status or a notification top
+        the user.
+
+        @param icon
+            This should be a small icon, measuring 16x16 pixels at 96 dpi. If an
+            overlay icon is already applied to the taskbar button, that existing
+            overlay is replaced. Setting with wxNullIcon to remove.
+        @param description
+            The property holds the description of the overlay for accessibility
+            purposes.
+    */
+    virtual void SetOverlayIcon(const wxIcon& icon,
+                                const wxString& description = wxString());
+
+    /**
+        Selects a portion of a window's client area to display as that window's
+        thumbnail in the taskbar.
+
+        @param  rect
+            The portion inside of the window. Setting with an empty wxRect will
+            restore the default diaplay of the thumbnail.
+    */
+    virtual void SetThumbnailClip(const wxRect& rect);
+
+    /**
+        Selects the child window area to display as that window's thumbnail in
+        the taskbar.
+    */
+    virtual void SetThumbnailContents(const wxWindow *child);
+
+    /**
+        Inserts the given button before the position pos to the taskbar
+        thumbnail toolbar.
+
+        @note The number of buttons is limited to 7.
+
+        @see AppendThumbBarButton()
+    */
+    virtual bool InsertThumbBarButton(size_t pos, wxThumbBarButton *button);
+
+    /**
+        Adds a button to the taskbar thumbnail toolbar.
+
+        @note The number of buttons is limited to 7.
+
+        @see InsertThumbBarButton()
+    */
+    virtual bool AppendThumbBarButton(wxThumbBarButton *button);
+
+    /**
+        Removes the thumbnail toolbar button from the taskbar button but doesn't
+        delete the associated c++ object.
+
+        @param button
+            The thumbnail toolbar button to remove.
+
+        @return A pointer to the button which was detached from the taskbar
+            button.
+    */
+    virtual wxThumbBarButton* RemoveThumbBarButton(wxThumbBarButton *button);
+
+    /**
+        Removes the thumbnail toolbar button from the taskbar button but doesn't
+        delete the associated c++ object.
+
+        @param id
+            The identifier of the thumbnail toolbar button to remove.
+
+        @return A pointer to the button which was detached from the taskbar
+            button.
+    */
+    virtual wxThumbBarButton* RemoveThumbBarButton(int id);
+};

src/msw/taskbarbutton.cpp

@@ -194,7 +194,7 @@ bool wxTaskBarButtonImpl::InsertThumbBarButton(size_t pos,
     return InitOrUpdateThumbBarButtons();
 }
 
-bool wxTaskBarButtonImpl::RemoveThumbBarButton(wxThumbBarButton *button)
+wxThumbBarButton* wxTaskBarButtonImpl::RemoveThumbBarButton(wxThumbBarButton *button)
 {
     for ( wxThumbBarButtons::iterator iter = m_thumbBarButtons.begin();
           iter != m_thumbBarButtons.end();
@@ -203,14 +203,15 @@ bool wxTaskBarButtonImpl::RemoveThumbBarButton(wxThumbBarButton *button)
         if ( button == *iter )
         {
             m_thumbBarButtons.erase(iter);
-            return InitOrUpdateThumbBarButtons();
+            InitOrUpdateThumbBarButtons();
+            return *iter;
         }
     }
 
-    return false;
+    return NULL;
 }
 
-bool wxTaskBarButtonImpl::RemoveThumbBarButton(int id)
+wxThumbBarButton* wxTaskBarButtonImpl::RemoveThumbBarButton(int id)
 {
     for ( wxThumbBarButtons::iterator iter = m_thumbBarButtons.begin();
           iter != m_thumbBarButtons.end();
@@ -219,11 +220,12 @@ bool wxTaskBarButtonImpl::RemoveThumbBarButton(int id)
         if ( id == (*iter)->GetID() )
         {
             m_thumbBarButtons.erase(iter);
-            return InitOrUpdateThumbBarButtons();
+            InitOrUpdateThumbBarButtons();
+            return *iter;
         }
     }
 
-    return false;
+    return NULL;
 }
 
 bool wxTaskBarButtonImpl::InitOrUpdateThumbBarButtons()