File indexing completed on 2019-07-28 10:35:14

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