/*!****************************************************************************
 *
 *  SPDX-FileCopyrightText: 2008 Szymon Tomasz Stefanek <pragma@kvirc.net>
 *
 *  SPDX-License-Identifier: GPL-2.0-or-later
 *
 *******************************************************************************/

#pragma once

#include <QList>
#include <QString>

#include <ctime> // for time_t

#include <KMime/Headers>

#include <Akonadi/MessageStatus>

#include "core/model.h"
#include "messagelist_export.h"

namespace MessageList
{
namespace Core
{
class ItemPrivate;

/*!
 * \class MessageList::Core::Item
 * \inmodule MessageList
 * \inheaderfile MessageList/Item
 *
 * A single item of the MessageList tree managed by MessageList::Model.
 *
 * This class stores basic information needed in all the subclasses which
 * at the moment of writing are MessageItem and GroupHeaderItem.
 */
class MESSAGELIST_EXPORT Item
{
    friend class Model;
    friend class ModelPrivate;

public:
    /*!
     * \enum Type
     * \brief The type of the Item.
     */
    enum Type : uint8_t {
        GroupHeader, ///< This item is a GroupHeaderItem
        Message, ///< This item is a MessageItem
        InvisibleRoot ///< This item is just Item and it's the only InvisibleRoot per Model.
    };

    /*!
     * \enum InitialExpandStatus
     * \brief Specifies the initial expand status for the item that should be applied
     * when it's attached to the viewable tree. Needed as a workaround for
     * QTreeView limitations in handling item expansion.
     */
    enum InitialExpandStatus : uint8_t {
        ExpandNeeded, ///< Must expand when this item becomes viewable
        NoExpandNeeded, ///< No expand needed at all
        ExpandExecuted ///< Item already expanded
    };

protected:
    /*!
     * \brief Creates an Item. Only derived classes and MessageList::Model should access this.
     * \param type The type of the item.
     */
    Item(Type type);
    /*!
     * \brief Creates an Item with private data.
     * \param type The type of the item.
     * \param dd Pointer to private data.
     */
    Item(Type type, ItemPrivate *dd);

public:
    /*!
     * \brief Destroys the Item. Should be protected just like the constructor but the QList<>
     * helpers need to access it, so it's public actually.
     */
    virtual ~Item();

    /*!
     * \brief Returns the type of this item. The Type can be set only in the constructor.
     * \return The type of this item.
     */
    [[nodiscard]] Type type() const;

    /*!
     * \brief The initial expand status we have to honor when attaching to the viewable root.
     * \return The initial expand status.
     */
    [[nodiscard]] InitialExpandStatus initialExpandStatus() const;

    /*!
     * \brief Set the initial expand status we have to honor when attaching to the viewable root.
     * \param initialExpandStatus The initial expand status to set.
     */
    void setInitialExpandStatus(InitialExpandStatus initialExpandStatus);

    /*!
     * \brief Is this item attached to the viewable root ?
     * \return True if item is viewable.
     */
    [[nodiscard]] bool isViewable() const;

    /*!
     * \brief Return true if Item pointed by it is an ancestor of this item (that is,
     * if it is its parent, parent of its parent, parent of its parent of its parent etc...
     * \param it The item to check.
     * \return True if it is an ancestor.
     */
    [[nodiscard]] bool hasAncestor(const Item *it) const;

    /*!
     * \brief Makes this item viewable, that is, notifies its existence to any listener
     * attached to the "rowsInserted()" signal, most notably QTreeView.
     *
     * This will also make all the children viewable.
     * \param model The model.
     * \param bViewable Whether the item should be viewable.
     */
    void setViewable(Model *model, bool bViewable);

    /*!
     * \brief Return the list of child items. May be null.
     * \return List of child items or null.
     */
    [[nodiscard]] QList<Item *> *childItems() const;

    /*!
     * \brief Returns the child item at position idx or 0 if idx is out of the allowable range.
     * \param idx The index of the child item.
     * \return The child item at the given index or nullptr.
     */
    [[nodiscard]] Item *childItem(int idx) const;

    /*!
     * Returns the first child item, if any.
     */
    [[nodiscard]] Item *firstChildItem() const;

    /*!
     * Returns the item that is visually below the specified child if this item.
     * Note that the returned item may belong to a completely different subtree.
     */
    [[nodiscard]] Item *itemBelowChild(Item *child);

    /*!
     * Returns the item that is visually above the specified child if this item.
     * Note that the returned item may belong to a completely different subtree.
     */
    [[nodiscard]] Item *itemAboveChild(Item *child);

    /*!
     * Returns the deepest item in the subtree originating at this item.
     */
    [[nodiscard]] Item *deepestItem();

    /*!
     * Returns the item that is visually below this item in the tree.
     * Note that the returned item may belong to a completely different subtree.
     */
    [[nodiscard]] Item *itemBelow();

    /*!
     * Returns the item that is visually above this item in the tree.
     * Note that the returned item may belong to a completely different subtree.
     */
    [[nodiscard]] Item *itemAbove();

    /*!
     * Debug helper. Dumps the structure of this subtree.
     */
    void dump(const QString &prefix);

    /*!
     * Returns the number of children of this Item.
     */
    [[nodiscard]] int childItemCount() const;

    /*!
     * Convenience function that returns true if this item has children.
     */
    [[nodiscard]] bool hasChildren() const;

    /*!
     * A structure used with MessageList::Item::childItemStats().
     * Contains counts of total and unread messages in a subtree.
     */
    class ChildItemStats
    {
    public:
        unsigned int mTotalChildCount; // total
        unsigned int mUnreadChildCount; // unread only
    public:
        ChildItemStats()
            : mTotalChildCount(0)
            , mUnreadChildCount(0)
        {
        }
    };

    /*!
     * Gathers statistics about child items.
     * For performance purposes assumes that this item has children.
     * You MUST check it before calling it.
     */
    void childItemStats(ChildItemStats &stats) const;

    /*!
     * Returns the actual index of the child Item item or -1 if
     * item is not a child of this Item.
     */
    int indexOfChildItem(Item *item) const;

    /*!
     * Sets the cached guess for the index of this item in the parent's child list.
     *
     * This is used to speed up the index lookup with the following algorithm:
     * Ask the parent if this item is at the position specified by index guess (this costs ~O(1)).
     * If the position matches we have finished, if it doesn't then perform
     * a linear search via indexOfChildItem() (which costs ~O(n)).
     */
    void setIndexGuess(int index);

    /*!
     * Returns the parent Item in the tree, or 0 if this item isn't attached to the tree.
     * Please note that even if this item has a non-zero parent, it can be still non viewable.
     * That is: the topmost parent of this item may be not attached to the viewable root.
     */
    [[nodiscard]] Item *parent() const;

    /*!
     * Sets the parent for this item. You should also take care of inserting
     * this item in the parent's child list.
     */
    void setParent(Item *pParent);

    /*!
     * Returns the topmost parent item that is not a Root item (that is, is a Message or GroupHeader).
     */
    [[nodiscard]] Item *topmostNonRoot();

    /*!
     * Returns the status associated to this Item.
     */
    const Akonadi::MessageStatus &status() const;

    /*!
     * Sets the status associated to this Item.
     */
    void setStatus(Akonadi::MessageStatus status);

    /*!
     * Returns a string describing the status e.g: "Read, Forwarded, Important"
     */
    [[nodiscard]] QString statusDescription() const;

    /*!
     * Returns the size of this item (size of the Message, mainly)
     */
    size_t size() const;

    /*!
     * Sets the size of this item (size of the Message, mainly)
     */
    void setSize(size_t size);

    /*!
     * A string with a text rappresentation of size(). This is computed on-the-fly
     * and not cached.
     */
    [[nodiscard]] QString formattedSize() const;

    /*!
     * Returns the date of this item
     */
    time_t date() const;

    /*!
     * Sets the date of this item
     */
    void setDate(time_t date);

    /*!
     * A string with a text rappresentation of date() obtained via Manager. This is computed on-the-fly
     * and not cached.
     */
    [[nodiscard]] QString formattedDate() const;

    /*!
     * Returns the maximum date in the subtree originating from this item.
     * This is kept up-to-date by MessageList::Model.
     */
    time_t maxDate() const;

    /*!
     * Sets the maximum date in the subtree originating from this item.
     */
    void setMaxDate(time_t date);

    /*!
     * A string with a text rappresentation of maxDate() obtained via Manager. This is computed on-the-fly
     * and not cached.
     */
    [[nodiscard]] QString formattedMaxDate() const;

    /*!
     * Recompute the maximum date from the current children list.
     * Return true if the current max date changed and false otherwise.
     */
    bool recomputeMaxDate();

    /*!
     * Returns the sender associated to this item.
     */
    [[nodiscard]] const QString &sender() const;

    /*!
     * Sets the sender associated to this item.
     */
    void setSender(const QString &sender);

    /*!
     * Display sender.
     */
    [[nodiscard]] QString displaySender() const;

    /*!
     * Returns the receiver associated to this item.
     */
    const QString &receiver() const;

    /*!
     * Sets the sender associated to this item.
     */
    void setReceiver(const QString &receiver);

    /*!
     * Display receiver.
     */
    [[nodiscard]] QString displayReceiver() const;

    /*!
     * Returns the sender or the receiver, depending on the underlying StorageModel settings.
     */
    const QString &senderOrReceiver() const;

    /*!
     * Display sender or receiver.
     */
    [[nodiscard]] QString displaySenderOrReceiver() const;

    /*!
     * Returns whether sender or receiver is supposed to be displayed.
     */
    bool useReceiver() const;

    /*!
     * Returns the subject associated to this Item.
     */
    const QString &subject() const;

    /*!
     * Sets the subject associated to this Item.
     */
    void setSubject(const QString &subject);

    /*!
     * Returns the folder associated to this Item.
     */
    const QString &folder() const;

    /*!
     * Sets the folder associated to this Item.
     */
    void setFolder(const QString &folder);

    /*!
     * This is meant to be called right after the constructor.
     * It sets up several items at once (so even if not inlined it's still a single call)
     * and it skips some calls that can be avoided at constructor time.
     */
    void initialSetup(time_t date, size_t size, const QString &sender, const QString &receiver, bool useReceiver);

    void setItemId(qint64 id);
    [[nodiscard]] qint64 itemId() const;

    void setParentCollectionId(qint64 id);
    [[nodiscard]] qint64 parentCollectionId() const;

    /*!
     * This is meant to be called right after the constructor for MessageItem objects.
     * It sets up several items at once (so even if not inlined it's still a single call).
     */
    void setSubjectAndStatus(const QString &subject, Akonadi::MessageStatus status);

    /*!
     * Appends an Item to this item's child list.
     * The Model is used for beginInsertRows()/endInsertRows() calls.
     */
    int appendChildItem(Model *model, Item *child);

    /*!
     * Appends a child item without inserting it via the model.
     * This is useful in ThemeEditor which doesn't use a custom model for the items.
     * You shouldn't need to use this function...
     */
    void rawAppendChildItem(Item *child);

    /*!
     * Removes a child from this item's child list without deleting it.
     * The Model is used for beginRemoveRows()/endRemoveRows() calls.
     */
    void takeChildItem(Model *model, Item *child);

    /*!
     * Kills all the child items without emitting any signal, recursively.
     * It should be used only when MessageList::Model is reset() afterwards.
     */
    void killAllChildItems();

protected:
    ItemPrivate *const d_ptr;
    Q_DECLARE_PRIVATE(Item)
};
} // namespace Core
} // namespace MessageList
