1 /////////////////////////////////////////////////////////////////////////////
2 // Name:        include/taskbarbutton.h
3 // Purpose:     Defines wxTaskBarButton class for manipulating buttons on the
4 //              windows taskbar.
5 // Author:      Chaobin Zhang <zhchbin@gmail.com>
6 // Created:     2014-04-30
7 // Copyright:   (c) 2014 wxWidgets development team
8 // Licence:     wxWindows licence
9 /////////////////////////////////////////////////////////////////////////////
10 
11 #ifndef _WX_TASKBARBUTTON_H_
12 #define _WX_TASKBARBUTTON_H_
13 
14 #include "wx/defs.h"
15 
16 #if wxUSE_TASKBARBUTTON
17 
18 #include "wx/icon.h"
19 #include "wx/string.h"
20 
21 class WXDLLIMPEXP_FWD_CORE wxTaskBarButton;
22 class WXDLLIMPEXP_FWD_CORE wxTaskBarJumpListCategory;
23 class WXDLLIMPEXP_FWD_CORE wxTaskBarJumpList;
24 class WXDLLIMPEXP_FWD_CORE wxTaskBarJumpListImpl;
25 
26 // ----------------------------------------------------------------------------
27 // wxTaskBarButton: define wxTaskBarButton interface.
28 // ----------------------------------------------------------------------------
29 
30 /**
31     State of the task bar button.
32 */
33 enum wxTaskBarButtonState
34 {
35     wxTASKBAR_BUTTON_NO_PROGRESS   = 0,
36     wxTASKBAR_BUTTON_INDETERMINATE = 1,
37     wxTASKBAR_BUTTON_NORMAL        = 2,
38     wxTASKBAR_BUTTON_ERROR         = 4,
39     wxTASKBAR_BUTTON_PAUSED        = 8
40 };
41 
42 class WXDLLIMPEXP_CORE wxThumbBarButton : public wxObject
43 {
44 public:
wxThumbBarButton()45     wxThumbBarButton() : m_taskBarButtonParent(NULL)
46     { }
47 
48     wxThumbBarButton(int id,
49                      const wxIcon& icon,
50                      const wxString& tooltip = wxString(),
51                      bool enable = true,
52                      bool dismissOnClick = false,
53                      bool hasBackground = true,
54                      bool shown = true,
55                      bool interactive = true);
56 
57     bool Create(int id,
58                 const wxIcon& icon,
59                 const wxString& tooltip = wxString(),
60                 bool enable = true,
61                 bool dismissOnClick = false,
62                 bool hasBackground = true,
63                 bool shown = true,
64                 bool interactive = true);
GetID()65     int GetID() const { return m_id; }
GetIcon()66     const wxIcon& GetIcon() const { return m_icon; }
GetTooltip()67     const wxString& GetTooltip() const { return m_tooltip; }
68 
IsEnable()69     bool IsEnable() const { return m_enable; }
70     void Enable(bool enable = true);
Disable()71     void Disable() { Enable(false); }
72 
IsDismissOnClick()73     bool IsDismissOnClick() const { return m_dismissOnClick; }
74     void EnableDismissOnClick(bool enable = true);
DisableDimissOnClick()75     void DisableDimissOnClick() { EnableDismissOnClick(false); }
76 
HasBackground()77     bool HasBackground() const { return m_hasBackground; }
78     void SetHasBackground(bool has = true);
79 
IsShown()80     bool IsShown() const { return m_shown; }
81     void Show(bool shown = true);
Hide()82     void Hide() { Show(false); }
83 
IsInteractive()84     bool IsInteractive() const { return m_interactive; }
85     void SetInteractive(bool interactive = true);
86 
SetParent(wxTaskBarButton * parent)87     void SetParent(wxTaskBarButton *parent) { m_taskBarButtonParent = parent; }
GetParent()88     wxTaskBarButton* GetParent() const { return m_taskBarButtonParent; }
89 
90 private:
91     bool UpdateParentTaskBarButton();
92 
93     int m_id;
94     wxIcon m_icon;
95     wxString m_tooltip;
96     bool m_enable;
97     bool m_dismissOnClick;
98     bool m_hasBackground;
99     bool m_shown;
100     bool m_interactive;
101     wxTaskBarButton *m_taskBarButtonParent;
102 
103     wxDECLARE_DYNAMIC_CLASS(wxThumbBarButton);
104 };
105 
106 class WXDLLIMPEXP_CORE wxTaskBarButton
107 {
108 public:
109     // Factory function, may return NULL if task bar buttons are not supported
110     // by the current system.
111     static wxTaskBarButton* New(wxWindow* parent);
112 
~wxTaskBarButton()113     virtual ~wxTaskBarButton() { }
114 
115     // Operations:
116     virtual void SetProgressRange(int range) = 0;
117     virtual void SetProgressValue(int value) = 0;
118     virtual void PulseProgress() = 0;
119     virtual void Show(bool show = true) = 0;
120     virtual void Hide() = 0;
121     virtual void SetThumbnailTooltip(const wxString& tooltip) = 0;
122     virtual void SetProgressState(wxTaskBarButtonState state) = 0;
123     virtual void SetOverlayIcon(const wxIcon& icon,
124                                 const wxString& description = wxString()) = 0;
125     virtual void SetThumbnailClip(const wxRect& rect) = 0;
126     virtual void SetThumbnailContents(const wxWindow *child) = 0;
127     virtual bool InsertThumbBarButton(size_t pos, wxThumbBarButton *button) = 0;
128     virtual bool AppendThumbBarButton(wxThumbBarButton *button) = 0;
129     virtual bool AppendSeparatorInThumbBar() = 0;
130     virtual wxThumbBarButton* RemoveThumbBarButton(wxThumbBarButton *button) = 0;
131     virtual wxThumbBarButton* RemoveThumbBarButton(int id) = 0;
132     virtual void Realize() = 0;
133 
134 protected:
wxTaskBarButton()135     wxTaskBarButton() { }
136 
137 private:
138     wxDECLARE_NO_COPY_CLASS(wxTaskBarButton);
139 };
140 
141 enum wxTaskBarJumpListItemType
142 {
143     wxTASKBAR_JUMP_LIST_SEPARATOR,
144     wxTASKBAR_JUMP_LIST_TASK,
145     wxTASKBAR_JUMP_LIST_DESTINATION
146 };
147 
148 class WXDLLIMPEXP_CORE wxTaskBarJumpListItem
149 {
150 public:
151     wxTaskBarJumpListItem(wxTaskBarJumpListCategory *parentCategory = NULL,
152         wxTaskBarJumpListItemType type = wxTASKBAR_JUMP_LIST_SEPARATOR,
153         const wxString& title = wxEmptyString,
154         const wxString& filePath = wxEmptyString,
155         const wxString& arguments = wxEmptyString,
156         const wxString& tooltip = wxEmptyString,
157         const wxString& iconPath = wxEmptyString,
158         int iconIndex = 0);
159 
160     wxTaskBarJumpListItemType GetType() const;
161     void SetType(wxTaskBarJumpListItemType type);
162     const wxString& GetTitle() const;
163     void SetTitle(const wxString& title);
164     const wxString& GetFilePath() const;
165     void SetFilePath(const wxString& filePath);
166     const wxString& GetArguments() const;
167     void SetArguments(const wxString& arguments);
168     const wxString& GetTooltip() const;
169     void SetTooltip(const wxString& tooltip);
170     const wxString& GetIconPath() const;
171     void SetIconPath(const wxString& iconPath);
172     int GetIconIndex() const;
173     void SetIconIndex(int iconIndex);
174     wxTaskBarJumpListCategory* GetCategory() const;
175     void SetCategory(wxTaskBarJumpListCategory *category);
176 
177 private:
178     wxTaskBarJumpListCategory *m_parentCategory;
179     wxTaskBarJumpListItemType m_type;
180     wxString m_title;
181     wxString m_filePath;
182     wxString m_arguments;
183     wxString m_tooltip;
184     wxString m_iconPath;
185     int      m_iconIndex;
186 
187     wxDECLARE_NO_COPY_CLASS(wxTaskBarJumpListItem);
188 };
189 
190 typedef wxVector<wxTaskBarJumpListItem*> wxTaskBarJumpListItems;
191 
192 class WXDLLIMPEXP_CORE wxTaskBarJumpListCategory
193 {
194 public:
195     wxTaskBarJumpListCategory(wxTaskBarJumpList *parent = NULL,
196                               const wxString& title = wxEmptyString);
197     virtual ~wxTaskBarJumpListCategory();
198 
199     wxTaskBarJumpListItem* Append(wxTaskBarJumpListItem *item);
200     void Delete(wxTaskBarJumpListItem *item);
201     wxTaskBarJumpListItem* Remove(wxTaskBarJumpListItem *item);
202     wxTaskBarJumpListItem* FindItemByPosition(size_t pos) const;
203     wxTaskBarJumpListItem* Insert(size_t pos, wxTaskBarJumpListItem *item);
204     wxTaskBarJumpListItem* Prepend(wxTaskBarJumpListItem *item);
205     void SetTitle(const wxString& title);
206     const wxString& GetTitle() const;
207     const wxTaskBarJumpListItems& GetItems() const;
208 
209 private:
210     friend class wxTaskBarJumpListItem;
211 
212     void Update();
213 
214     wxTaskBarJumpList *m_parent;
215     wxTaskBarJumpListItems m_items;
216     wxString m_title;
217 
218     wxDECLARE_NO_COPY_CLASS(wxTaskBarJumpListCategory);
219 };
220 
221 typedef wxVector<wxTaskBarJumpListCategory*> wxTaskBarJumpListCategories;
222 
223 class WXDLLIMPEXP_CORE wxTaskBarJumpList
224 {
225 public:
226     wxTaskBarJumpList(const wxString& appID = wxEmptyString);
227     virtual ~wxTaskBarJumpList();
228     void ShowRecentCategory(bool shown = true);
229     void HideRecentCategory();
230     void ShowFrequentCategory(bool shown = true);
231     void HideFrequentCategory();
232 
233     wxTaskBarJumpListCategory& GetTasks() const;
234     const wxTaskBarJumpListCategory& GetFrequentCategory() const;
235     const wxTaskBarJumpListCategory& GetRecentCategory() const;
236     const wxTaskBarJumpListCategories& GetCustomCategories() const;
237 
238     void AddCustomCategory(wxTaskBarJumpListCategory* category);
239     wxTaskBarJumpListCategory* RemoveCustomCategory(const wxString& title);
240     void DeleteCustomCategory(const wxString& title);
241 
242 private:
243     friend class wxTaskBarJumpListCategory;
244 
245     void Update();
246     wxTaskBarJumpListImpl *m_jumpListImpl;
247 
248     wxDECLARE_NO_COPY_CLASS(wxTaskBarJumpList);
249 };
250 
251 #endif // wxUSE_TASKBARBUTTON
252 
253 #endif  // _WX_TASKBARBUTTON_H_
254