plasma-framework/widgets/icon.h

/*
*   Copyright (C) 2007 by Siraj Razick <siraj@kde.org>
*   Copyright (C) 2007 by Riccardo Iaconelli <riccardo@kde.org>
*   Copyright (C) 2007 by Matt Broadstone <mbroadst@gmail.com>
*
*   This program is free software; you can redistribute it and/or modify
*   it under the terms of the GNU Library General Public License version 2 as
*   published by the Free Software Foundation
*
*   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 Library General Public
*   License along with this program; if not, write to the
*   Free Software Foundation, Inc.,
*   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
*/

#ifndef ICON_H
#define ICON_H

#include <QtCore/QObject>
#include <QtGui/QGraphicsTextItem>

#include <plasma/dataengine.h>
#include <plasma/phase.h>
#include <plasma/plasma_export.h>
#include <plasma/widgets/layoutitem.h>

class QAction;
class KUrl;

/**
 * This class provides a generic Icon for the Plasma desktop. An icon, in this
 * sense, is not restricted to just an image, but can also contain text. Currently,
 * the Icon class is primarily used for desktop items, but is designed to be used
 * anywhere an icon is needed in an applet.
 *
 * @author Siraj Razick <siraj@kde.org>
 * @author Matt Broadstone <mbroadst@gmail.com>
 */
namespace Plasma
{

class PLASMA_EXPORT Icon : public QObject, public QGraphicsItem, public LayoutItem
{
    Q_OBJECT
    Q_PROPERTY( QString text READ text WRITE setText )
    Q_PROPERTY( QString infoText READ infoText WRITE setInfoText )
    Q_PROPERTY( QSizeF iconSize READ iconSize WRITE setIconSize )

    public:
        /**
         * Creates a new Plasma::Icon.
         * @param parent the QGraphicsItem this icon is parented to.
        */
        explicit Icon(QGraphicsItem *parent = 0);

        /**
         * Convenience constructor to create a Plasma::Icon with text.
         * @param text the text that will be displayed with this icon.
         * @param parent the QGraphicsItem this icon is parented to.
        */
        explicit Icon(const QString &text, QGraphicsItem *parent = 0);

        /**
         * Creates a new Plasma::Icon with text and an icon.
         * @param icon the icon that will be displayed with this icon.
         * @param text the text that will be displayed with this icon.
         * @param parent The QGraphicsItem this icon is parented to.
        */
        Icon(const QIcon & icon, const QString &text, QGraphicsItem *parent = 0);

        /**
         * Destroys this Plasma::Icon.
        */
        virtual ~Icon();

        /**
         * Returns the text associated with this icon.
        */
        QString text() const;

        /**
         * Sets the text associated with this icon.
         * @param text the text to associate with this icon.
        */
        void setText(const QString &text);

        /**
         * Returns the meta text associated with this icon.
        */
        QString infoText() const;

        /**
         * Sets the additional information to be displayed by
         * this icon.
         * @param text additional meta text associated with this icon.
        */
        void setInfoText(const QString &text);

        /**
         * Sets the graphical icon for this Plasma::Icon.
         * @param icon the QIcon to associate with this icon.
        */
        Q_INVOKABLE void setIcon(const QIcon& icon);

        /**
         * Convenience method to set the icon of this Plasma::Icon
         * using a QString path to the icon.
         * @param icon the path to the icon to associate with this Plasma::Icon.
        */
        Q_INVOKABLE void setIcon(const QString& icon);

        /**
         * Returns the size of this Plasma::Icon's graphical icon.
        */
        QSizeF iconSize() const;

        /**
         * Sets the size of the graphical icon for this Plasma::Icon.
         * @param size the size of the icon.
        */
        void setIconSize(const QSizeF& size);

        /**
         * Convenience method to set the icon size without a QSizeF.
         * @param height the height of the icon.
         * @param width the width of the icon.
        */
        Q_INVOKABLE void setIconSize(int height, int width);


        /**
         * Plasma::Icon allows the user to specify a number of actions
         * (current four) to be displayed around the widget. This method
         * allows for a created QAction (not a KAction!) to be added to 
         * the Plasma::Icon.
         * @param action the QAction to associate with this icon.
        */
        void addAction(QAction* action);

        // Layout stuff - no need to document
        Qt::Orientations expandingDirections() const;

        QSizeF minimumSize() const;
        QSizeF maximumSize() const;

        bool hasHeightForWidth() const;
        qreal heightForWidth(qreal w) const;

        bool hasWidthForHeight() const;
        qreal widthForHeight(qreal h) const;

        QRectF geometry() const;
        void setGeometry(const QRectF& r);

        QSizeF sizeHint() const;
        QRectF boundingRect() const;

    protected:
        void paint(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget = 0);

    Q_SIGNALS:
        /**
         * Indicates when the icon has been pressed.
        */
        void pressed(bool down);

        /**
         * Indicates when the icon has been clicked.
        */
        void clicked();

    protected:
        bool isDown();
        void mousePressEvent(QGraphicsSceneMouseEvent *event);
        void mouseMoveEvent(QGraphicsSceneMouseEvent *event);
        void mouseReleaseEvent(QGraphicsSceneMouseEvent *event);

        void hoverEnterEvent(QGraphicsSceneHoverEvent *event);
        void hoverLeaveEvent(QGraphicsSceneHoverEvent *event);

    public:
        class Private;

        /**
         * @internal
         **/
        void drawActionButtonBase(QPainter* painter, const QSize &size, int element);

    private:
        QPixmap buttonPixmap();
        void init();
        void calculateSize();

        Private * const d;

    private Q_SLOTS:
        void actionDestroyed(QObject* obj);
};

} // namespace Plasma


/*
    // Add these to UrlIcon
    void setUrl(const KUrl& url);
    KUrl url() const;
*/

#endif