1/*
2 Copyright (c) 2010 Tobias Koenig <tokoe@kde.org>
3
4 This library is free software; you can redistribute it and/or modify it
5 under the terms of the GNU Library General Public License as published by
6 the Free Software Foundation; either version 2 of the License, or (at your
7 option) any later version.
8
9 This library is distributed in the hope that it will be useful, but WITHOUT
10 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
12 License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to the
16 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
17 02110-1301, USA.
18*/
19
20#ifndef AKONADI_AGENTACTIONMANAGER_H
21#define AKONADI_AGENTACTIONMANAGER_H
22
23#include "akonadi_export.h"
24
25#include <akonadi/agentinstance.h>
26
27#include <QtCore/QObject>
28
29class KAction;
30class KActionCollection;
31class KLocalizedString;
32class QItemSelectionModel;
33class QWidget;
34
35namespace Akonadi {
36
37/**
38 * @short Manages generic actions for agent and agent instance views.
39 *
40 * @author Tobias Koenig <tokoe@kde.org>
41 * @since 4.6
42 */
43class AKONADI_EXPORT AgentActionManager : public QObject
44{
45 Q_OBJECT
46public:
47 /**
48 * Describes the supported actions.
49 */
50 enum Type {
51 CreateAgentInstance, ///< Creates an agent instance
52 DeleteAgentInstance, ///< Deletes the selected agent instance
53 ConfigureAgentInstance, ///< Configures the selected agent instance
54 LastType ///< Marks last action
55 };
56
57 /**
58 * Describes the text context that can be customized.
59 */
60 enum TextContext {
61 DialogTitle, ///< The window title of a dialog
62 DialogText, ///< The text of a dialog
63 MessageBoxTitle, ///< The window title of a message box
64 MessageBoxText, ///< The text of a message box
65 MessageBoxAlternativeText, ///< An alternative text of a message box
66 ErrorMessageTitle, ///< The window title of an error message
67 ErrorMessageText ///< The text of an error message
68 };
69
70 /**
71 * Creates a new agent action manager.
72 *
73 * @param actionCollection The action collection to operate on.
74 * @param parent The parent widget.
75 */
76 explicit AgentActionManager(KActionCollection *actionCollection, QWidget *parent = 0);
77
78 /**
79 * Destroys the agent action manager.
80 */
81 ~AgentActionManager();
82
83 /**
84 * Sets the agent selection @p model based on which the actions should operate.
85 * If none is set, all actions will be disabled.
86 * @param model model based on which actions should operate
87 */
88 void setSelectionModel(QItemSelectionModel *model);
89
90 /**
91 * Sets the mime type filter that will be used when creating new agent instances.
92 */
93 void setMimeTypeFilter(const QStringList &mimeTypes);
94
95 /**
96 * Sets the capability filter that will be used when creating new agent instances.
97 */
98 void setCapabilityFilter(const QStringList &capabilities);
99
100 /**
101 * Creates the action of the given type and adds it to the action collection
102 * specified in the constructor if it does not exist yet. The action is
103 * connected to its default implementation provided by this class.
104 * @param type action type
105 */
106 KAction *createAction(Type type);
107
108 /**
109 * Convenience method to create all standard actions.
110 * @see createAction()
111 */
112 void createAllActions();
113
114 /**
115 * Returns the action of the given type, 0 if it has not been created (yet).
116 */
117 KAction *action(Type type) const;
118
119 /**
120 * Sets whether the default implementation for the given action @p type
121 * shall be executed when the action is triggered.
122 *
123 * @param intercept If @c false, the default implementation will be executed,
124 * if @c true no action is taken.
125 *
126 * @since 4.6
127 */
128 void interceptAction(Type type, bool intercept = true);
129
130 /**
131 * Returns the list of agent instances that are currently selected.
132 * The list is empty if no agent instance is currently selected.
133 *
134 * @since 4.6
135 */
136 Akonadi::AgentInstance::List selectedAgentInstances() const;
137
138 /**
139 * Sets the @p text of the action @p type for the given @p context.
140 *
141 * @param type action type
142 * @param context context of the given action
143 * @param text text for the given action type
144 *
145 * @since 4.6
146 */
147 void setContextText(Type type, TextContext context, const QString &text);
148
149 /**
150 * Sets the @p text of the action @p type for the given @p context.
151 *
152 * @since 4.8
153 * @param type action type
154 * @param context context of the given action type
155 * @param text localized text for the given action type
156 */
157 void setContextText(Type type, TextContext context, const KLocalizedString &text);
158
159Q_SIGNALS:
160 /**
161 * This signal is emitted whenever the action state has been updated.
162 * In case you have special needs for changing the state of some actions,
163 * connect to this signal and adjust the action state.
164 */
165 void actionStateUpdated();
166
167private:
168 //@cond PRIVATE
169 class Private;
170 Private *const d;
171
172 Q_PRIVATE_SLOT(d, void updateActions())
173
174 Q_PRIVATE_SLOT(d, void slotCreateAgentInstance())
175 Q_PRIVATE_SLOT(d, void slotDeleteAgentInstance())
176 Q_PRIVATE_SLOT(d, void slotConfigureAgentInstance())
177
178 Q_PRIVATE_SLOT(d, void slotAgentInstanceCreationResult(KJob *))
179 //@endcond
180};
181
182}
183
184#endif
185