/* * Copyright (C) 2007 by Alexander Wiedenbruch * and Matias Valdenegro * * 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 WIDGET_H_ #define WIDGET_H_ #include #include #include #include #include namespace Plasma { class Layout; /** * Base class for all Widgets in Plasma. * * @author Alexander Wiedenbruch * @author Matias Valdenegro * * Widgets are the basis for User Interfaces inside Plasma. * Widgets are rectangular, but can be in any visible shape by just using transparency to mask * out non-rectangular areas. * * To implement a Widget, just subclass Plasma::Widget and implement at minimum, sizeHint() and paint() */ class PLASMA_EXPORT Widget : public QObject, public QGraphicsItem, public LayoutItem { Q_OBJECT Q_PROPERTY( Qt::Orientations expandingDirections READ expandingDirections ) Q_PROPERTY( QSizeF minimumSize READ minimumSize WRITE setMinimumSize ) Q_PROPERTY( QSizeF maximumSize READ maximumSize WRITE setMaximumSize ) Q_PROPERTY( QRectF geometry READ geometry WRITE setGeometry ) Q_PROPERTY( QRectF localGeometry READ localGeometry ) Q_PROPERTY( QSizeF sizeHint READ sizeHint ) Q_PROPERTY( QSizeF size READ size WRITE setSize ) public: /** * Creates a new Plasma::Widget. * @param parent the QGraphicsItem this icon is parented to. */ explicit Widget(QGraphicsItem *parent = 0); /** * Destroys a Plasma::Widget. */ virtual ~Widget(); /** * This method is used by Plasma::Layout to determine which directions the * widget naturally expands. * @return bitmask with the directions that this Widget can be expanded. */ virtual Qt::Orientations expandingDirections() const; /** * Sets the minimum size of the Widget. * @param size the size to set as the minimum size. */ void setMinimumSize(const QSizeF& size); /** * @return minimum size of the Widget. */ QSizeF minimumSize() const; /** * Sets the maximum size of the Widget. * @param size the size to set as the maximum size. */ void setMaximumSize(const QSizeF& size); /** * @return maximum size of the Widget. */ QSizeF maximumSize() const; /** * This method is used by Plasma::Layout to determine whether this widget * can provide a height value given a width value. * @return whether or not this Widget has heightForWidth. */ virtual bool hasHeightForWidth() const; /** * This method is used by Plasma::Layout to determine a height value * given a width value. * @param width the width to use to determine height. * @return height calculated using width given. */ virtual qreal heightForWidth(qreal width) const; /** * This method is used by Plasma::Layout to determine whether this widget * can provide a width value given a height value. * @return whether or not this Widget has widthForHeight. */ virtual bool hasWidthForHeight() const; /** * This method is used by Plasma::Layout to determine a width value * given a height value. * @param height the width to use to determine width. * @return width calculated using height given. */ virtual qreal widthForHeight(qreal h) const; /** * @return geometry of this widget. */ QRectF geometry() const; /** * @return geometry of this widget in local coordinates. */ QRectF localGeometry() const; /** * Sets the geometry of this Widget. */ /** * Sets the geometry of this Plasma::Widget * @param geometry the geometry to apply to this Plasma::Widget. */ void setGeometry(const QRectF &geometry); /** * This method is used to notify any containing Plasma::Layout that it should * reset its geometry. */ // NOTE: this is a completely broken concept -MB Q_INVOKABLE void updateGeometry(); /** * Invalidate current geometry of this Plasma::Widget as well as its * parent if it exists. */ Q_INVOKABLE virtual void invalidate(); /** * Returns the recommended size for this widget. Note that this size is not * necessarily only the size for the widget, but might also include margins etc. * @return recommended size for this Plasma::Widget. */ virtual QSizeF sizeHint() const; /** * Sets the size of this Plasma::Widget. * @param size the size of this Plasma::Widget */ void setSize(const QSizeF &size); /** * @return the size of this Plasma::Widget */ QSizeF size() const; /** * Reimplemented from QGraphicsItem * @return the bounding rectangle for this Plasma::Widget */ virtual QRectF boundingRect() const; /** * Resizes this Plasma::Widget. * @param size the new size of this Plasma::Widget. */ Q_INVOKABLE void resize(const QSizeF &size); /** * Convenience method for resizing this Plasma::Widget * @param width the new width. * @param height the new height. */ Q_INVOKABLE void resize(qreal width, qreal height); /** * @return this Plasma::Widget's parent, returns a null pointer if * none exist. */ Q_INVOKABLE Widget *parent() const; /** * Sets the parent of this Plasma::Widget; * @param widget the widget to reparent to. */ Q_INVOKABLE void reparent(Widget *widget); /** * Add another Plasma::Widget as a child of this one. * @param widget the widget to reparent to this Plasma::Widget. */ Q_INVOKABLE void addChild(Widget *widget); protected: /** * Paints the widget * @param painter the QPainter to use to paint. * @param option the style option used to give specific info on the item being dawn. * @param widget the parent QWidget (most likely the Corona) */ virtual void paintWidget(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget = 0); private: void paint(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget = 0); class Private; Private *const d; }; } // Plasma namespace #endif