From 3e1130bf571f80dbdd782616a9fb73359ef14ece Mon Sep 17 00:00:00 2001 From: Bryan Petty Date: Wed, 10 Sep 2014 14:52:11 +0000 Subject: [PATCH] Add doxygen docs of wxTaskBarButton. Author: Chaobin Zhang git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@77606 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- include/wx/msw/taskbarbutton.h | 5 +- include/wx/taskbarbutton.h | 4 +- interface/wx/frame.h | 17 +++ interface/wx/taskbarbutton.h | 264 +++++++++++++++++++++++++++++++++ src/msw/taskbarbutton.cpp | 14 +- 5 files changed, 294 insertions(+), 10 deletions(-) create mode 100644 interface/wx/taskbarbutton.h diff --git a/include/wx/msw/taskbarbutton.h b/include/wx/msw/taskbarbutton.h index 2c1f9002fa..9cabaace9d 100644 --- a/include/wx/msw/taskbarbutton.h +++ b/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; diff --git a/include/wx/taskbarbutton.h b/include/wx/taskbarbutton.h index 55edc5697d..3bb7d31599 100644 --- a/include/wx/taskbarbutton.h +++ b/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); diff --git a/interface/wx/frame.h b/interface/wx/frame.h index ae4a9b0ff5..584c6eca01 100644 --- a/interface/wx/frame.h +++ b/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); diff --git a/interface/wx/taskbarbutton.h b/interface/wx/taskbarbutton.h new file mode 100644 index 0000000000..277495ca94 --- /dev/null +++ b/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); +}; diff --git a/src/msw/taskbarbutton.cpp b/src/msw/taskbarbutton.cpp index 51d8437734..102fc8bc42 100644 --- a/src/msw/taskbarbutton.cpp +++ b/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()