alecs/plasma-framework
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Documentation++

Browse Source 
svn path=/trunk/KDE/kdebase/workspace/libs/plasma/; revision=875470
This commit is contained in:
Rob Scheepmaker 2008-10-24 14:49:32 +00:00
parent 415a1c213d
commit 16883d6243
2 changed files with 59 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
extender.h
View File

@ -48,6 +48,17 @@ class Applet;
* *
* If you wish to have a different presentation of extender items, you can choose to subclass * 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. * Extender and reimplement the extenderItem* events and, optionally, the saveState function.
*
* To use an Extender in you applet, you'll have to instantiate one. A call to extender() in your
* applet will create an extender on your applet if you haven't got one already. Every applet can
* contain only one extender. Think of it as a decorator that adds some functionality to applets
* that require it. Never instantiate an Extender before init() in your applet. This won't work
* correctly since a scene is required when an Extender is instantiated.
*
* As soon as an Extender is instantiated, ExtenderItems contained previously in this Extender are
* restored using the initExtenderItem function from the applet the items originally came from. For
* more information on how this works and how to use ExtenderItems in general, see the ExtenderItem
* API documentation.
*/ */
class PLASMA_EXPORT Extender : public QGraphicsWidget class PLASMA_EXPORT Extender : public QGraphicsWidget
{ {
@ -59,27 +70,29 @@ class PLASMA_EXPORT Extender : public QGraphicsWidget
* Description on how to render the extender's items. * Description on how to render the extender's items.
*/ */
enum Appearance { enum Appearance {
NoBorders = 0, /** Draws no borders on the extender's items. When placed in an applet NoBorders = 0, /**< Draws no borders on the extender's items. When placed in an applet
on the desktop, use this setting and use the standard margins of on the desktop, use this setting and use the standard margins of
the applet containing this extender. */ the applet containing this extender. */
BottomUpStacked = 1, /** Draws no borders on the topmost extenderitem, but draws the BottomUpStacked = 1, /**< Draws no borders on the topmost extenderitem, but draws the
left, top and right border on subsequent items. When margins left, top and right border on subsequent items. When margins
of the containing dialog are set to 0, except for the top of the containing dialog are set to 0, except for the top
margin, this leads to the 'stacked' look, recommended for margin, this leads to the 'stacked' look, recommended for
extenders of applet's contained in a panel at the bottom of extenders of applet's contained in a panel at the bottom of
the screen. */ the screen. */
TopDownStacked = 2 /** Draws no borders on the bottom extenderitem, but draws the TopDownStacked = 2 /**< Draws no borders on the bottom extenderitem, but draws the
left, bottom and right border on subsequent items. When margins left, bottom and right border on subsequent items. When margins
of the containing dialog are set to 0, except for the bottom of the containing dialog are set to 0, except for the bottom
margin, this leads to the 'stacked' look, recommended for margin, this leads to the 'stacked' look, recommended for
extenders of applet's contained in a panel at the top of extenders of applet's contained in a panel at the top of
the screen. */ the screen. */
}; };
/** /**
* Creates an extender. Note that extender expects applet to have a config(), and needs a * 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 * scene because of that. So you should only instantiate an extender in init() or later, not
* in an applet's constructor. * in an applet's constructor.
* The constructor also takes care of restoring ExtenderItems that were contained in this
* extender before, so ExtenderItems are persistent between sessions.
* @param applet The applet this extender is part of. Null is not allowed here. * @param applet The applet this extender is part of. Null is not allowed here.
*/ */
explicit Extender(Applet *applet); explicit Extender(Applet *applet);
@ -87,7 +100,7 @@ class PLASMA_EXPORT Extender : public QGraphicsWidget
~Extender(); ~Extender();
/** /**
* @param emptyExtenderMessage The text to be shown whenever the applet's extender is empty. * @param message The text to be shown whenever the applet's extender is empty.
* Defaults to i18n'ed "no items". * Defaults to i18n'ed "no items".
*/ */
void setEmptyExtenderMessage(const QString &message); void setEmptyExtenderMessage(const QString &message);
@ -194,12 +207,12 @@ class PLASMA_EXPORT Extender : public QGraphicsWidget
virtual PanelSvg::EnabledBorders enabledBordersForItem(ExtenderItem *item) const; virtual PanelSvg::EnabledBorders enabledBordersForItem(ExtenderItem *item) const;
/** /**
* @reimplemented from QGraphicsWidget * Reimplemented from QGraphicsWidget
*/ */
QVariant itemChange(GraphicsItemChange change, const QVariant &value); QVariant itemChange(GraphicsItemChange change, const QVariant &value);
/** /**
* @reimplemented from QGraphicsWidget * Reimplemented from QGraphicsWidget
*/ */
void resizeEvent(QGraphicsSceneResizeEvent *event); void resizeEvent(QGraphicsSceneResizeEvent *event);

30
extenderitem.h
View File

@ -42,6 +42,34 @@ class ExtenderItemPrivate;
* This class wraps around a QGraphicsWidget and provides drag&drop handling, a draghandle, * This class wraps around a QGraphicsWidget and provides drag&drop handling, a draghandle,
* title and ability to display qactions as a row of icon, ability to expand, collapse, return * title and ability to display qactions as a row of icon, ability to expand, collapse, return
* to source and tracks configuration associated with this item for you. * to source and tracks configuration associated with this item for you.
*
* Typical usage of ExtenderItems in your applet could look something like this:
*
* @code
* ExtenderItem *item = new ExtenderItem(extender());
* //name can be used to later access this item through extender()->item(name):
* item->setName("networkmonitoreth0");
* item->config().writeEntry("device", "eth0");
* initExtenderItem(item);
* @endcode
*
* You'll then need to implement the initExtenderItem function. Having this function in your applet
* makes sure that detached extender items get restored after plasma is restarted, just like applets
* are. That is also the reason that we write an entry in item->config().
* In this function you should instantiate a QGraphicsWidget or QGraphicsItem and call the
* setWidget function on the ExtenderItem. This is the only correct way of adding actual content to
* a extenderItem. An example:
*
* @code
* void MyApplet::initExtenderItem(Plasma::ExtenderItem *item)
* {
* QGraphicsWidget *myNetworkMonitorWidget = new NetworkMonitorWidget(item);
* dataEngine("networktraffic")->connectSource(item->config().readEntry("device", ""),
* myNetworkMonitorWidget);
* item->setWidget(myNetworkMonitorWidget);
* }
* @endcode
*
*/ */
class PLASMA_EXPORT ExtenderItem : public QGraphicsWidget class PLASMA_EXPORT ExtenderItem : public QGraphicsWidget
{ {
@ -59,8 +87,6 @@ class PLASMA_EXPORT ExtenderItem : public QGraphicsWidget
/** /**
* The constructor takes care of adding this item to an extender. * The constructor takes care of adding this item to an extender.
* @param hostExtender The extender where the extender item belongs to. * @param hostExtender The extender where the extender item belongs to.
* TODO: extenderItemId might not be necesarry in the constructor if I rewrite some
* stuff.
* @param extenderItemId the id of the extender item. Use the default 0 to assign a new, * @param extenderItemId the id of the extender item. Use the default 0 to assign a new,
* unique id to this extender item. * unique id to this extender item.
*/ */