1/*
2 Copyright (c) 2008 Volker Krause <vkrause@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_AGENTINSTANCECREATEJOB_H
21#define AKONADI_AGENTINSTANCECREATEJOB_H
22
23#include "akonadi_export.h"
24
25#include <akonadi/agenttype.h>
26
27#include <kjob.h>
28
29namespace Akonadi {
30
31class AgentInstance;
32class AgentInstanceCreateJobPrivate;
33
34/**
35 * @short Job for creating new agent instances.
36 *
37 * This class encapsulates the procedure of creating a new agent instance
38 * and optionally configuring it immediately.
39 *
40 * @code
41 *
42 * MyClass::MyClass( QWidget *parent )
43 * : QWidget( parent )
44 * {
45 * // Get agent type object
46 * Akonadi::AgentType type = Akonadi::AgentManager::self()->type( "akonadi_vcard_resource" );
47 *
48 * Akonadi::AgentInstanceCreateJob *job = new Akonadi::AgentInstanceCreateJob( type );
49 * connect( job, SIGNAL(result(KJob*)),
50 * this, SLOT(slotCreated(KJob*)) );
51 *
52 * // use this widget as parent for the config dialog
53 * job->configure( this );
54 *
55 * job->start();
56 * }
57 *
58 * ...
59 *
60 * void MyClass::slotCreated( KJob *job )
61 * {
62 * Akonadi::AgentInstanceCreateJob *createJob = static_cast<Akonadi::AgentInstanceCreateJob*>( job );
63 *
64 * qDebug() << "Created agent instance:" << createJob->instance().identifier();
65 * }
66 *
67 * @endcode
68 *
69 * @author Volker Krause <vkrause@kde.org>
70 */
71class AKONADI_EXPORT AgentInstanceCreateJob : public KJob
72{
73 Q_OBJECT
74
75public:
76 /**
77 * Creates a new agent instance create job.
78 *
79 * @param type The type of the agent to create.
80 * @param parent The parent object.
81 */
82 explicit AgentInstanceCreateJob(const AgentType &type, QObject *parent = 0);
83
84 /**
85 * Creates a new agent instance create job.
86 *
87 * @param typeId The identifier of type of the agent to create.
88 * @param parent The parent object.
89 * @since 4.5
90 */
91 explicit AgentInstanceCreateJob(const QString &typeId, QObject *parent = 0);
92
93 /**
94 * Destroys the agent instance create job.
95 */
96 ~AgentInstanceCreateJob();
97
98 /**
99 * Setup the job to show agent configuration dialog once the agent instance
100 * has been successfully started.
101 * @param parent The parent window for the configuration dialog.
102 */
103 void configure(QWidget *parent = 0);
104
105 /**
106 * Returns the AgentInstance object of the newly created agent instance.
107 */
108 AgentInstance instance() const;
109
110 /**
111 * Starts the instance creation.
112 */
113 void start();
114
115private:
116 //@cond PRIVATE
117 friend class Akonadi::AgentInstanceCreateJobPrivate;
118 AgentInstanceCreateJobPrivate *const d;
119
120 Q_PRIVATE_SLOT(d, void agentInstanceAdded(const Akonadi::AgentInstance &))
121 Q_PRIVATE_SLOT(d, void doConfigure())
122 Q_PRIVATE_SLOT(d, void timeout())
123 Q_PRIVATE_SLOT(d, void emitResult())
124 Q_PRIVATE_SLOT(d, void configurationDialogAccepted())
125 Q_PRIVATE_SLOT(d, void configurationDialogRejected())
126 //@endcond
127};
128
129}
130
131#endif
132