← Back to branch summary

~ubuntu-branches/debian/jessie/scummvm/jessie

« back to all changes in this revision

Viewing changes to common/taskbar.h

  • Committer: Package Import Robot
  • Author(s): Moritz Muehlenhoff
  • Date: 2011-11-05 10:29:43 UTC
  • mto: This revision was merged to the branch mainline in revision 25.
  • Revision ID: package-import@ubuntu.com-20111105102943-zfm3dhlvy5b01u7v
Tags: upstream-1.4.0
Import upstream version 1.4.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
common/taskbar.h
 
1
/* ScummVM - Graphic Adventure Engine
 
2
 *
 
3
 * ScummVM is the legal property of its developers, whose names
 
4
 * are too numerous to list here. Please refer to the COPYRIGHT
 
5
 * file distributed with this source distribution.
 
6
 *
 
7
 * This program is free software; you can redistribute it and/or
 
8
 * modify it under the terms of the GNU General Public License
 
9
 * as published by the Free Software Foundation; either version 2
 
10
 * of the License, or (at your option) any later version.
 
11
 *
 
12
 * This program is distributed in the hope that it will be useful,
 
13
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 
14
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 
15
 * GNU General Public License for more details.
 
16
 *
 
17
 * You should have received a copy of the GNU General Public License
 
18
 * along with this program; if not, write to the Free Software
 
19
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 
20
 *
 
21
 */
 
22
 
 
23
#ifndef COMMON_TASKBAR_MANAGER_H
 
24
#define COMMON_TASKBAR_MANAGER_H
 
25
 
 
26
#include "common/scummsys.h"
 
27
#include "common/str.h"
 
28
 
 
29
#if defined(USE_TASKBAR)
 
30
 
 
31
namespace Common {
 
32
 
 
33
/**
 
34
 * The TaskbarManager allows interaction with the ScummVM application icon:
 
35
 *  - in the taskbar on Windows 7 and later
 
36
 *  - in the launcher for Unity
 
37
 *  - in the dock on MacOSX
 
38
 *  - ...
 
39
 *
 
40
 * This allows GUI code and engines to display a progress bar, an overlay icon and/or count
 
41
 * associated with the ScummVM icon as well as add the started engine to the recent items
 
42
 * list (so that the user can start the engine directly in one click).
 
43
 *
 
44
 * Examples of use:
 
45
 *  - Track search progress and found engines when running the Mass Add dialog
 
46
 *  - Add an entry to the recent items when starting an engine
 
47
 *  - Show the current running engine icon as an overlay
 
48
 *
 
49
 * @note functionality will vary between supported platforms (due to API limitations)
 
50
 *       and some of the methods will just be no-ops or approximate the functionality
 
51
 *       as best as possible
 
52
 */
 
53
class TaskbarManager {
 
54
public:
 
55
        /**
 
56
         * Values representing the taskbar progress state
 
57
         */
 
58
        enum TaskbarProgressState {
 
59
                kTaskbarNoProgress = 0,
 
60
                kTaskbarIndeterminate = 1,
 
61
                kTaskbarNormal = 2,
 
62
                kTaskbarError = 4,
 
63
                kTaskbarPaused = 8
 
64
        };
 
65
 
 
66
        TaskbarManager() {}
 
67
        virtual ~TaskbarManager() {}
 
68
 
 
69
        /**
 
70
         * Sets an overlay icon on the taskbar icon
 
71
         *
 
72
         * When an empty name is given, no icon is shown
 
73
         * and the current overlay icon (if any) is removed
 
74
         *
 
75
         * @param  name         Path to the icon
 
76
         * @param  description  The description
 
77
         *
 
78
         * @note on Windows, the icon should be an ICO file
 
79
         */
 
80
        virtual void setOverlayIcon(const String &name, const String &description) {}
 
81
 
 
82
        /**
 
83
         * Sets a progress value on the taskbar icon
 
84
         *
 
85
         * @param  completed  The current progress value.
 
86
         * @param  total      The maximum progress value.
 
87
         */
 
88
        virtual void setProgressValue(int completed, int total) {}
 
89
 
 
90
        /**
 
91
         * Sets the progress state on the taskbar icon
 
92
         *
 
93
         * State can be any of the following:
 
94
         *   - NoProgress: disable display of progress state
 
95
         *   - Indeterminate
 
96
         *   - Normal
 
97
         *   - Error
 
98
         *   - Paused
 
99
         *
 
100
         * @param  state    The progress state
 
101
         */
 
102
        virtual void setProgressState(TaskbarProgressState state) {}
 
103
 
 
104
        /**
 
105
         * Sets the count number associated with the icon as an overlay
 
106
         *
 
107
         * @param  count    The count
 
108
         *
 
109
         * @note Setting a count of 0 will hide the count
 
110
         */
 
111
        virtual void setCount(int count) {}
 
112
 
 
113
        /**
 
114
         * Adds an engine to the recent items list
 
115
         *
 
116
         * Path is automatically set to the current executable path,
 
117
         * an icon name is generated (with fallback to default icon)
 
118
         * and the command line is set to start the engine on click.
 
119
         *
 
120
         * @param  name         The target name.
 
121
         * @param  description  The description.
 
122
         */
 
123
        virtual void addRecent(const String &name, const String &description) {}
 
124
 
 
125
        /**
 
126
         * Notifies the user an error occured through the taskbar icon
 
127
         *
 
128
         * This will for example show the taskbar icon as red (using progress of 100% and an error state)
 
129
         * on Windows, and set the launcher icon in the urgent state on Unity
 
130
         */
 
131
        virtual void notifyError() {}
 
132
 
 
133
        /**
 
134
         * Clears the error notification
 
135
         */
 
136
        virtual void clearError() {}
 
137
};
 
138
 
 
139
}       // End of namespace Common
 
140
 
 
141
#endif
 
142
 
 
143
#endif // COMMON_TASKBAR_MANAGER_H