181 lines
7.4 KiB
C++
181 lines
7.4 KiB
C++
/***************************************************************************
|
|
* Copyright 2008 by Rob Scheepmaker <r.scheepmaker@student.utwente.nl> *
|
|
* *
|
|
* 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) any later version. *
|
|
* *
|
|
* 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, write to the *
|
|
* Free Software Foundation, Inc., *
|
|
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA . *
|
|
***************************************************************************/
|
|
|
|
#ifndef EXTENDER_H
|
|
#define EXTENDER_H
|
|
|
|
#include <QtGui/QGraphicsWidget>
|
|
|
|
#include "plasma/plasma_export.h"
|
|
|
|
namespace Plasma
|
|
{
|
|
class ExtenderPrivate;
|
|
class ExtenderItem;
|
|
class Applet;
|
|
|
|
/**
|
|
* An Extender is a widget that visually extends the normal contents of an applet with
|
|
* additional dynamic widgets called ExtenderItems. These ExtenderItems can be
|
|
* detached by the user and dropped either on another Extender or on the canvas directly.
|
|
*
|
|
* This widget allows using ExtenderItems in your applet. Extender takes care of the presentation
|
|
* of a collection of ExtenderItems and keeps track of ExtenderItems that originate in it.
|
|
*
|
|
* The default Extender implementation displays extender items in a vertical layout with
|
|
* spacers that appear when dropping an ExtenderItem over it.
|
|
*
|
|
* If you wish to have a different presentation of extender items, you can choose to subclass
|
|
* Extender and reimplement the extenderItem* events and, optionally, the saveState function.
|
|
*/
|
|
class PLASMA_EXPORT Extender : public QGraphicsWidget
|
|
{
|
|
Q_OBJECT
|
|
Q_PROPERTY(QString emptyExtenderMessage READ emptyExtenderMessage
|
|
WRITE setEmptyExtenderMessage)
|
|
|
|
public:
|
|
/**
|
|
* Creates an extender. Note that extender expects applet to have a config(), and needs a
|
|
* scene because of that. So you should only instantiate an extender in init() or later, not
|
|
* in an applet's constructor.
|
|
* @param applet The applet this extender is part of. Null is not allowed here.
|
|
*/
|
|
explicit Extender(Applet *applet);
|
|
|
|
~Extender();
|
|
|
|
/**
|
|
* @param emptyExtenderMessage The text to be shown whenever the applet's extender is empty.
|
|
* Defaults to i18n'ed "no items".
|
|
*/
|
|
void setEmptyExtenderMessage(const QString &message);
|
|
|
|
/**
|
|
* @return The text to be shown whenever the applet's layout is empty.
|
|
*/
|
|
QString emptyExtenderMessage() const;
|
|
|
|
/**
|
|
* @returns a list of all extender items (attached AND detached) where the source applet is
|
|
* this applet.
|
|
*/
|
|
QList<ExtenderItem*> items() const;
|
|
|
|
/**
|
|
* @returns a list of all attached extender items.
|
|
*/
|
|
QList<ExtenderItem*> attachedItems() const;
|
|
|
|
/**
|
|
* @returns a list of all detached extender items.
|
|
*/
|
|
QList<ExtenderItem*> detachedItems() const;
|
|
|
|
/**
|
|
* This function can be used for easily determining if a certain item is allready displayed
|
|
* in a extender item somewhere, so your applet doesn't duplicate this item. Say the applet
|
|
* displays 'jobs', from an engine which add's a source for every job. In sourceAdded you
|
|
* could do something like:
|
|
* if (!extenderItem(source)) {
|
|
* //add an extender item monitoring this source.
|
|
* }
|
|
*/
|
|
ExtenderItem *item(const QString &name) const;
|
|
|
|
protected:
|
|
/**
|
|
* Get's called after an item has been added to this extender. The bookkeeping has allready
|
|
* been done when this function get's called. The only thing left to do is put it somewhere
|
|
* appropriate. The default implementation adds the extenderItem to the appropriate place in
|
|
* a QGraphicsLinearLayout.
|
|
* @param item The item that has just been added.
|
|
* @param pos The location the item has been dropped in local coordinates.
|
|
*/
|
|
virtual void itemAddedEvent(ExtenderItem *item, const QPointF &pos);
|
|
|
|
/**
|
|
* Get's called after an item has been removed from this extender. All bookkeeping has
|
|
* allready been done when this function get's called.
|
|
* @param item The item that has just been removed.
|
|
*/
|
|
virtual void itemRemovedEvent(ExtenderItem *item);
|
|
|
|
/**
|
|
* Get's called when an ExtenderItem that get's dragged enters this extender. Default
|
|
* implementation does nothing.
|
|
*/
|
|
virtual void itemHoverEnterEvent(ExtenderItem *item);
|
|
|
|
/**
|
|
* Gets called when an ExtenderItem is hovering over this extender. Implement this function
|
|
* to give some visual feedback about what will happen when the mouse button is released at
|
|
* that position. The default implementation shows a spacer at the appropriate location in
|
|
* the layout.
|
|
* @param item The item that's hovering over this extender. Most usefull for obtaining the
|
|
* size of the spacer.
|
|
* @param pos The location the item is hovering.
|
|
*/
|
|
virtual void itemHoverMoveEvent(ExtenderItem *item, const QPointF &pos);
|
|
|
|
/**
|
|
* Get's called when an ExtenderItem that was previously hovering over this extender moves
|
|
* away from this extender. The default implementation removes any spacer from the layout.
|
|
*/
|
|
virtual void itemHoverLeaveEvent(ExtenderItem *item);
|
|
|
|
/**
|
|
* This function get's called for every extender when plasma exits. Implement this function
|
|
* to store the current state of this extender (position in a layout for example), so this
|
|
* can be restored when applet starts again. The default implementation stores the y
|
|
* coordinate of every extender item in the config field extenderItemPos.
|
|
*/
|
|
virtual void saveState();
|
|
|
|
Q_SIGNALS:
|
|
/**
|
|
* Fires when an extender item is added to this extender.
|
|
*/
|
|
void itemAttached(Plasma::ExtenderItem *);
|
|
|
|
/**
|
|
* Fires when an extender item is removed from this extender.
|
|
*/
|
|
void itemDetached(Plasma::ExtenderItem *);
|
|
|
|
/**
|
|
* Fires when an extender's preferred size changes.
|
|
*/
|
|
void geometryChanged();
|
|
|
|
private:
|
|
ExtenderPrivate* const d;
|
|
|
|
friend class ExtenderPrivate;
|
|
friend class ExtenderItem;
|
|
friend class ExtenderItemPrivate;
|
|
//applet should be able to call saveState();
|
|
friend class Applet;
|
|
|
|
};
|
|
} // Plasma namespace
|
|
|
|
#endif //EXTENDER_H
|
|
|