File indexing completed on 2020-10-01 13:12:06
0001 /* 0002 This file is part of Choqok, the KDE micro-blogging client 0003 0004 Copyright (C) 2008-2012 Mehrdad Momeny <mehrdad.momeny@gmail.com> 0005 0006 This program is free software; you can redistribute it and/or 0007 modify it under the terms of the GNU General Public License as 0008 published by the Free Software Foundation; either version 2 of 0009 the License or (at your option) version 3 or any later version 0010 accepted by the membership of KDE e.V. (or its successor approved 0011 by the membership of KDE e.V.), which shall act as a proxy 0012 defined in Section 14 of version 3 of the license. 0013 0014 This program is distributed in the hope that it will be useful, 0015 but WITHOUT ANY WARRANTY; without even the implied warranty of 0016 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 0017 GNU General Public License for more details. 0018 0019 You should have received a copy of the GNU General Public License 0020 along with this program; if not, see http://www.gnu.org/licenses/ 0021 */ 0022 0023 #ifndef MICROBLOG_H 0024 #define MICROBLOG_H 0025 0026 #include <QMenu> 0027 #include <QString> 0028 0029 #include "account.h" 0030 #include "choqok_export.h" 0031 #include "choqoktypes.h" 0032 #include "choqokuiglobal.h" 0033 #include "plugin.h" 0034 0035 class ChoqokEditAccountWidget; 0036 0037 namespace Choqok 0038 { 0039 namespace UI 0040 { 0041 class PostWidget; 0042 class TimelineWidget; 0043 class MicroBlogWidget; 0044 class ComposerWidget; 0045 } 0046 /** 0047 \brief Base class for MicroBlog plugins 0048 Every MicroBlog plugin should subclass this they can subclass UI classes to use too, and implement: 0049 @ref createNewAccount() To create a new account for this microblog, can use @ref Choqok::Account or a subclass of it, 0050 @ref createEditAccountWidget() To create a widget/dialog to show to user for create/edit account, 0051 @ref createMicroBlogWidget() To create a @ref MicroBlogWidget to show on MainWindow 0052 @ref createTimelineWidget() To create a @ref TimelineWidget to show on MicroBlogWidget 0053 0054 Additionally should implement this functions: 0055 @ref createPost() @ref abortCreatePost() @ref fetchPost() @ref removePost() @ref updateTimelines() @ref profileUrl() 0056 0057 @author Mehrdad Momeny \<mehrdad.momeny@gmail.com\> 0058 */ 0059 class CHOQOK_EXPORT MicroBlog : public Plugin 0060 { 0061 Q_OBJECT 0062 public: 0063 virtual ~MicroBlog(); 0064 0065 /** 0066 @brief Return a KMenu contain microblog specific actions. 0067 Can use for search facilities, or other things 0068 Will add to a button on top of @ref MicroBlogWidget of account/microblog 0069 */ 0070 virtual QMenu *createActionsMenu(Account *theAccount, QWidget *parent = UI::Global::mainWindow()); 0071 0072 /** 0073 Enumeration for possible errors. 0074 */ 0075 enum ErrorType { 0076 /** A server side error. */ 0077 ServerError, 0078 /** An error on communication with server */ 0079 CommunicationError, 0080 /** A parsing error. */ 0081 ParsingError, 0082 /** An error on authentication. */ 0083 AuthenticationError, 0084 /** An error where the method called is not supported by this object. */ 0085 NotSupportedError, 0086 /** Any other miscellaneous error. */ 0087 OtherError 0088 }; 0089 0090 /** 0091 Enumeration for levels of errors. 0092 This could use for user feedback! 0093 For @ref Critical errors will show a messagebox, 0094 For @ref Normal will show a knotify. 0095 For @ref Low just show a message in statusBar 0096 */ 0097 enum ErrorLevel { 0098 Low = 0, 0099 Normal, 0100 Critical 0101 }; 0102 0103 /** 0104 * @brief Create a new Account 0105 * 0106 * This method is called during the loading of the config file. 0107 * @param alias - the alias name to create the account with. 0108 * 0109 * you don't need to register the account to the AccountManager in this function. 0110 * 0111 * @return The new @ref Account object created by this function 0112 */ 0113 virtual Account *createNewAccount(const QString &alias); 0114 0115 /** 0116 * @brief Create a new EditAccountWidget 0117 * 0118 * @return A new @ref ChoqokEditAccountWidget to be shown in the account part of the configurations. 0119 * 0120 * @param account is the Account to edit. If it's nullptr, then we create a new account 0121 * @param parent The parent of the 'to be returned' widget 0122 */ 0123 virtual ChoqokEditAccountWidget *createEditAccountWidget(Choqok::Account *account, QWidget *parent) = 0; 0124 0125 /** 0126 * @brief Create a MicroBlogWidget for this Account 0127 * The returned MicroBlogWidget will show on Mainwindow. and manage of this microblog account will give to it 0128 * Every MicroBlog plugin should reimplement this. 0129 * 0130 * @return A new MicroBlogWidget to use. 0131 * 0132 * @param account account to use. 0133 * @param parent The parent of the 'to be returned' widget 0134 */ 0135 virtual UI::MicroBlogWidget *createMicroBlogWidget(Choqok::Account *account, QWidget *parent); 0136 0137 /** 0138 * @brief Create a ComposerWidget to use in MicroBlogWidget 0139 * 0140 * @return A new ComposerWidget to use. 0141 * 0142 * @param account account to use. 0143 * @param parent The parent of the 'to be returned' widget 0144 */ 0145 virtual UI::ComposerWidget *createComposerWidget(Choqok::Account *account, QWidget *parent); 0146 0147 /** 0148 * @brief Create a TimelineWidget to use in MicroBlogWidget 0149 * 0150 * @return A new TimelineWidget to use. 0151 * 0152 * @param account account to use. 0153 * @param timelineName Name of timeline 0154 * @param parent The parent of the 'to be returned' widget 0155 */ 0156 virtual UI::TimelineWidget *createTimelineWidget(Choqok::Account *account, const QString &timelineName, 0157 QWidget *parent); 0158 0159 /** 0160 * @brief Create a PostWidget to contain one post in TimelineWidget 0161 * 0162 * @return A new PostWidget to use. 0163 * 0164 * @param account account to use. 0165 * @param post Post object. 0166 * @param parent The parent of the 'to be returned' widget 0167 */ 0168 virtual UI::PostWidget *createPostWidget(Choqok::Account *account, 0169 Choqok::Post *post, QWidget *parent); 0170 0171 /** 0172 @brief Save a specific timeline! 0173 @Note Implementation of this is optional, i.e. One microblog may don't have timeline backup 0174 0175 @see loadTimeline() 0176 */ 0177 virtual void saveTimeline(Choqok::Account *account, const QString &timelineName, 0178 const QList<UI::PostWidget *> &timeline); 0179 /** 0180 @brief Load a specific timeline! 0181 @Note Implementation of this is optional, i.e. One microblog may don't have timeline backup 0182 0183 @see saveTimeline() 0184 */ 0185 virtual QList<Post *> loadTimeline(Choqok::Account *account, const QString &timelineName); 0186 0187 /** 0188 \brief Create a new post 0189 0190 @see postCreated() 0191 @see abortCreatePost() 0192 */ 0193 virtual void createPost(Choqok::Account *theAccount, Choqok::Post *post); 0194 0195 /** 0196 \brief Abort all requests! 0197 */ 0198 virtual void abortAllJobs(Choqok::Account *theAccount); 0199 0200 /** 0201 \brief Abort all createPost jobs 0202 \see abortAllJobs() 0203 */ 0204 virtual void abortCreatePost(Choqok::Account *theAccount, Choqok::Post *post = nullptr); 0205 /** 0206 \brief Fetch a post 0207 0208 @see postFetched() 0209 */ 0210 virtual void fetchPost(Choqok::Account *theAccount, Choqok::Post *post); 0211 0212 /** 0213 \brief Remove a post 0214 0215 @see postRemoved() 0216 */ 0217 virtual void removePost(Choqok::Account *theAccount, Choqok::Post *post); 0218 0219 /** 0220 Request to update all timelines of account! 0221 They will arrive in several signals! with timelineDataReceived() signal! 0222 0223 @see timelineDataReceived() 0224 */ 0225 virtual void updateTimelines(Choqok::Account *theAccount); 0226 0227 /** 0228 return Url to account page on service (Some kind of blog homepage) 0229 */ 0230 virtual QUrl profileUrl(Choqok::Account *account, const QString &username) const; 0231 0232 /** 0233 Provide a Web link for post with id @p postId 0234 */ 0235 virtual QUrl postUrl(Choqok::Account *account, const QString &username, const QString &postId) const; 0236 0237 /** 0238 Return a list of timelines supported by this account! 0239 It will use to show timelines! and result of timelineDataReceived() signal will be based on these! 0240 0241 @see timelineInfo() 0242 @see timelineDataReceived() 0243 */ 0244 QStringList timelineNames() const; 0245 0246 /** 0247 Checks if @p timeline is valid for this blog! i.e. there is an entry for it at timelineTypes() list. 0248 @return True if the timeline is valid, false if not! 0249 */ 0250 bool isValidTimeline(const QString &timelineName); 0251 0252 /** 0253 @Return information about an specific timeline 0254 */ 0255 virtual TimelineInfo *timelineInfo(const QString &timelineName); 0256 0257 /** 0258 Return service homepage Url 0259 */ 0260 QString homepageUrl() const; 0261 0262 /** 0263 Returns a user readable name of blog/service type! (e.g. Identica) 0264 */ 0265 QString serviceName() const; 0266 0267 static QString errorString(ErrorType type); 0268 0269 Q_SIGNALS: 0270 0271 /** 0272 emit when data for a timeline received! @p type specifies the type of timeline as specifies in timelineTypes() 0273 */ 0274 void timelineDataReceived(Choqok::Account *theAccount, const QString &timelineName, 0275 QList<Choqok::Post *> data); 0276 0277 /** 0278 emit when a post successfully created! 0279 */ 0280 void postCreated(Choqok::Account *theAccount, Choqok::Post *post); 0281 0282 /** 0283 emit when a post successfully fetched! 0284 */ 0285 void postFetched(Choqok::Account *theAccount, Choqok::Post *post); 0286 0287 /** 0288 emit when a post successfully removed! 0289 */ 0290 void postRemoved(Choqok::Account *theAccount, Choqok::Post *post); 0291 0292 /** 0293 emit when an error occurred the @p errorMessage will specify the error. 0294 */ 0295 void error(Choqok::Account *theAccount, Choqok::MicroBlog::ErrorType error, 0296 const QString &errorMessage, Choqok::MicroBlog::ErrorLevel level = Normal); 0297 0298 /** 0299 emit when an error occurred on Post manipulation. e.g. On Creation! 0300 */ 0301 void errorPost(Choqok::Account *theAccount, Choqok::Post *post, 0302 Choqok::MicroBlog::ErrorType error, const QString &errorMessage, 0303 Choqok::MicroBlog::ErrorLevel level = Normal); 0304 0305 /** 0306 emit when microblog plugin is going to unload, and @ref Choqok::TimelineWidget should save their timelines 0307 */ 0308 void saveTimelines(); 0309 0310 protected: 0311 0312 MicroBlog(const QString &componentName, QObject *parent = nullptr); 0313 0314 virtual void setTimelineNames(const QStringList &); 0315 void addTimelineName(const QString &); 0316 void setServiceName(const QString &); 0317 void setServiceHomepageUrl(const QString &); 0318 0319 protected Q_SLOTS: 0320 void slotConfigChanged(); 0321 0322 private: 0323 class Private; 0324 Private *const d; 0325 }; 0326 0327 } 0328 0329 #endif