src/plugins/blogique/interfaces/blogique/ibloggingplatform.h
/**********************************************************************
 * LeechCraft - modular cross-platform feature rich internet client.
 * Copyright (C) 2010-2012  Oleg Linkin
 *
 * Distributed under the Boost Software License, Version 1.0.
 * (See accompanying file LICENSE or copy at https://www.boost.org/LICENSE_1_0.txt)
 **********************************************************************/

#pragma once

#include <functional>
#include <QMetaType>
#include <QAction>
#include <interfaces/iadvancedhtmleditor.h>

class QObject;
class QIcon;

namespace LC
{
namespace Blogique
{
	struct InlineTagInserter
	{
		QString TagName_;
		QVariantMap Parameters_;
		std::function<void (QAction*)> ActionCustomizer_;
	};

	/** @brief Represents a blogging platform.
	 *
	 * IBloggingPlatform class represents a single blogging platform with its own set of
	 * accounts.
	 *
	 * When user decides to add a new account within this protocol, the
	 * GetAccountRegistrationWidgets() function is called to get the
	 * list of widgets that should be filled out by the user by the
	 * exact values of his account, and if the user accepts the
	 * registration, RegisterAccount() would be called with those
	 * widgets.
	 *
	 */
	class IBloggingPlatform
	{
	public:
		virtual ~IBloggingPlatform () {}

		/** This enum describes the features that may be supported by a
		 * blogging platform.
		 */
		enum BloggingPlatfromFeature
		{
			/** None of these features are supported by the blogging platform.
			 */
			BPFNone = 0,

			/** This blogging platform provides API for supporting
			 * registering new accounts from client.
			 */
			BPFSupportsRegistration = 1,

			/** This blogging platform supports account profilest with extended
			 * information.
			 */
			BPFSupportsProfiles = 2,

			/** This blogging platform supports variouse posting destinations
			 * such as private blog, communities, etc.
			 */
			BPFSelectablePostDestination = 4,

			/** This blogging platform supports downloading of all posts for
			 * backup in localstorage.
			 */
			BPFSupportsBackup = 8,

			/** This blogging platform only for local blog
			 */
			BPFLocalBlog = 32,

			/** This blogging platform supports post preview in blog style
			 */
			BPFPostPreviewSupport = 64,

			/** This blogging platform supports getting comments
			 */
			BPFSupportComments = 128
		};
		Q_DECLARE_FLAGS (BloggingPlatfromFeatures, BloggingPlatfromFeature)

		/** This enum describes the options that may be selected by the
		 * user when adding a new account.
		 */
		enum AccountAddOption
		{
			/** No custom options.
			 */
			AAONoOptions = 0,

			/** User has chosen to register a new account (if the
			 * protocol advertises BPFSupportsRegistration
			 * feature).
			 */
			AAORegisterNewAccount = 0x01
		};
		Q_DECLARE_FLAGS (AccountAddOptions, AccountAddOption)

		/** @brief Returns the protocol object as a QObject.
		 *
		 * @return Blogging platform object as QObject.
		 */
		virtual QObject* GetQObject () = 0;

		/** Returns the list of features supported by this blogging platform.
		 */
		virtual BloggingPlatfromFeatures GetFeatures () const = 0;

		/** @brief Returns the accounts within this blogging platform.
		 *
		 * Each object in the returned list must implement IAccount.
		 *
		 * @return The list of accounts of this blogging platform.
		 */
		virtual QObjectList GetRegisteredAccounts () = 0;

		/** @brief Returns the pointer to the parent blogging platform plugin
		 * that this blogging platform belongs to.
		 *
		 * @return The parent blogging platform plugin of this blogging platform, which
		 * must implement IBloggingPlatformPlugin.
		 */
		virtual QObject* GetParentBloggingPlatformPlugin () const = 0;

		/** @brief Returns the human-readable name of this blogging platform,
		 * like "LiveJournal" or "Blogger".
		 *
		 * @return Human-readable name of the blogging platform.
		 */
		virtual QString GetBloggingPlatformName () const = 0;

		/** @brief Returns the icon of this blogging platform.
		 *
		 * @return The icon of the blogging platform.
		 */
		virtual QIcon GetBloggingPlatformIcon () const = 0;

		/** @brief Returns the protocol ID, which must be unique among
		 * all the protocols.
		 *
		 * @return The unique ID of this protocol.
		 */
		virtual QByteArray GetBloggingPlatformID () const = 0;

		/** @brief Returns the widgets used for account addition.
		 *
		 * The widgets from the returned list are shown in the account
		 * addition wizard in the same order they appear in the returned
		 * list.
		 *
		 * If the user accepts registering the account, the
		 * RegisterAccount () method would be called with the same set of
		 * widgets in the same order as returned from this function.
		 *
		 * The ownership is transferred to the caller.
		 *
		 * @param[in] options The options selected by the user to
		 * perform the account addition.
		 * @param[in] accName The name of the account being registered
		 * hint.
		 *
		 * @return The widgets to be shown and filled by the user.
		 *
		 * @sa RegisterAccount()
		 */
		virtual QList<QWidget*> GetAccountRegistrationWidgets (AccountAddOptions, const QString& accName) = 0;

		/** @brief Adds an account with the given name and widgets.
		 *
		 * The list of widgets is the same (and in the same order) as
		 * returned from the GetAccountRegistrationWidgets() function.
		 * If this method is called, the widgets were shown to the user,
		 * and the user has accepted the account registration, so the
		 * widgets would be filled by the user to contain the required
		 * values. One could use qobject_cast to cast each widget in the
		 * list to the exact widget type and then use the values filled
		 * by the user.
		 *
		 * If the account is added successfully, the accountAdded()
		 * signal should be emitted, otherwise nothing should be done.
		 *
		 * @note Since ownership of the widgets is transferred to the
		 * caller, one shouldn't delete widgets in this method, and one
		 * shouldn't store them to use after this function has returned.
		 *
		 * @param[in] name The name of the account to be registered.
		 * @param[in] widgets The list of widgets returned from the
		 * GetAccountRegistrationWidgets() and filled by the user.
		 *
		 * @sa GetAccountRegistrationWidgets()
		 */
		virtual void RegisterAccount (const QString& name, const QList<QWidget*>& widgets) = 0;

		/** @brief Removes the given account.
		 *
		 * This function shouldn't ask anything from the user, just
		 * remove the account.
		 *
		 * If the account is not registered, this function should do
		 * nothing.
		 *
		 * After the removal, the accountRemoved() signal is expected to
		 * be emitted.
		 *
		 * @param[in] account The account to remove.
		 */
		virtual void RemoveAccount (QObject *account) = 0;

		/** @brief Returns specific editor actions.
		 *
		 * This function returns specific editor actions such as LJ-cut,
		 * LJ-user, etc
		 *
		 * @return The List of actions witch should be added to editor widget.
		 */
		virtual QList<QAction*> GetEditorActions () const = 0;

		virtual QList<InlineTagInserter> GetInlineTagInserters () const = 0;

		/** @brief Returns the widgets used for extended posting features.
		 *
		 * The widgets from the returned list are shown in the side dockwidget
		 * in the same order they appear in the returned list.
		 *
		 * Each widget in list should implement IBlogiqueSideWidget.
		 *
		 * The ownership is transferred to the caller.
		 *
		 * @return The List of widgets witch should be added to dockbar.
		 *
		 * @sa IBlogiqueSideWidget
		 */
		virtual QList<QWidget*> GetBlogiqueSideWidgets () const = 0;

		virtual IAdvancedHTMLEditor::CustomTags_t GetCustomTags () const = 0;
	protected:
		/** @brief Notifies about new account.
		 *
		 * This signal should be emitted whenever a new account appears
		 * in this blogging platform.
		 *
		 * @note This function is expected to be a signal.
		 *
		 * @param[out] account The newly added account, which must
		 * implement IAccount.
		 */
		virtual void accountAdded (QObject *account) = 0;

		/** @brief Notifies about an account having been removed.
		 *
		 * This signal should be emitted whenever an already registered
		 * account is removed, for example, as the result of the call to
		 * RemoveAccount().
		 *
		 * @note This function is expected to be a signal.
		 *
		 * @param[out] account The just removed account, which must
		 * implement IAccount.
		 */
		virtual void accountRemoved (QObject *account) = 0;

		/** @brief Notifies about an account have finished validating data.
		 *
		 * This signal should be emitted whenever an account
		 * finished validation.
		 *
		 * @note This function is expected to be a signal.
		 *
		 * @param[out] account The account, which must implement IAccount.
		 */

		virtual void accountValidated (QObject *account, bool validated) = 0;

		virtual void insertTag (const QString& tag) = 0;
	};
}
}

Q_DECLARE_OPERATORS_FOR_FLAGS (LC::Blogique::IBloggingPlatform::BloggingPlatfromFeatures)
Q_DECLARE_OPERATORS_FOR_FLAGS (LC::Blogique::IBloggingPlatform::AccountAddOptions)
Q_DECLARE_INTERFACE (LC::Blogique::IBloggingPlatform,
		"org.Deviant.LeechCraft.Blogique.IBloggingPlatform/1.0")
