danbooru-client/src/libdanbooru/danboorupost.h

/*
 * <one line to give the library's name and an idea of what it does.>
 * Copyright 2013  Luca Beltrame <lbeltrame@kde.org>
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License as
 * published by the Free Software Foundation; either version 2 of
 * the License or (at your option) version 3 or any later version
 * accepted by the membership of KDE e.V. (or its successor approved
 * by the membership of KDE e.V.), which shall act as a proxy
 * defined in Section 14 of version 3 of the license.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 *
 */

#ifndef DANBOORUPOST_H
#define DANBOORUPOST_H

/**
 * @brief File containing classes to represent Danbooru posts.
 * @file danboorupost.h
 **/

// Qt

#include <QtCore/QObject>
#include <QtCore/QVariant>
#include <QtCore/QStringList>
#include <QtXml/QXmlStreamAttributes>

// KDE

#include <KUrl>

class QPixmap;


namespace Danbooru {

    /**
     * @brief A class representing a Danbooru post.
     *
     * A Danbooru post is an object that models the posts present in a
     * Danbooru board, that is an image with associated information.
     *
     * In particular, posts contain information on the id, size and dimensions
     * of the image, its tags, "preview url" (URL to the thumbnail) and
     * file URL.
     *
     * This is used directly by the DanbooruService class.
     *
     * @author Luca Beltrame (lbeltrame@kde.org)
     *
     * @see DanbooruService, DanbooruPool
     *
     **/
    class DanbooruPost : public QObject
    {

    Q_OBJECT

    Q_PROPERTY(QPixmap* pixmap READ pixmap WRITE setPixmap)
    Q_PROPERTY(int id READ id)
    Q_PROPERTY(KUrl fileUrl READ fileUrl)
    Q_PROPERTY(QStringList tags READ tags)
    Q_PROPERTY(KUrl thumbnailUrl READ thumbnailUrl)

    private:

        QPixmap* m_pixmap;

        // basic features of a post

        int m_id;
        int m_height;
        int m_width;
        int m_size;

        KUrl m_url;
        KUrl m_thumbnailUrl;
        QStringList m_tags;

    public:

        /**
         * @brief Construct a Danbooru post from a QVariantMap.
         *
         * This form is the easiest to use and should be used when dealing with
         * responses in JSON format. Unfortunately most Danbooru
         * implementations produce broken JSON for some responses.
         *
         * @param postData A QVariantMap from parsed JSON representing the
         *      data from a single post.
         * @param pixmap A QPixmap pointer to the post thumbnail.
         * @param parent A pointer to the parent QObject.
         *
         **/
        explicit DanbooruPost(QVariantMap postData, QPixmap* pixmap = 0,
                              QObject* parent = 0);

        /**
         * @brief Construct a Danbooru post from XML attributes
         *
         * This is an overloaded function which uses XML attributes rather
         * than JSON. It should be used in case the JSON responses aren't
         * complete or broken (for example pools' posts in most Danbooru
         * instances).
         *
         * @param postData A QXmlStreamAttributes instance holding the
         *      attributes for the given post.
         * @param pixmap A QPixmap pointer to the post thumbnail.
         * @param parent A pointer to the parent QObject.
         *
         **/
        explicit DanbooruPost(QXmlStreamAttributes& postData,
                              QPixmap* pixmap = 0,  QObject* parent=0);

        bool operator==(const DanbooruPost&);

        ~DanbooruPost();

        // Post attributes

        /**
         * @return The ID of the post.
         **/
        int id() const;

        /**
         * @return The height in pixels of the post's image.
         **/
        int height() const;

        /**
         * @return The width in pixels of the post's image.
         **/
        int width() const;

        /**
         * @return The size in bytes of the post's image.
         **/
        int size() const;

        /**
         * @return The URL to the post's image.
         **/
        const KUrl fileUrl() const;

        /**
         * @return The tags associated to the post.
         **/
        QStringList tags() const;

        /**
         * @return The URL to the post's thumbnail.
         **/
        const KUrl thumbnailUrl() const;

        /**
         * @return A pointer to the thumbnail's pixmap.
         **/
        QPixmap* pixmap() const;

        /**
         * Set the post's pixmap to a specific QPixmap instance's pointer.
         *
         **/
        void setPixmap(QPixmap* pixmap);

        /**
         * @return A string representation of the post.
         *
         * **/
        const QString toString();

    };

}; // namespace Danbooru

Q_DECLARE_METATYPE(Danbooru::DanbooruPost*)
#endif // DANBOORUPOST_H