• Skip to content
  • Skip to link menu
KDE 4.2 API Reference
  • KDE API Reference
  • kdelibs
  • Sitemap
  • Contact Us
 

Plasma

Plasma::Extender

Plasma::Extender Class Reference

Extends applets to allow detachable parts. More...

#include <Plasma/Extender>

Inheritance diagram for Plasma::Extender:

Inheritance graph
[legend]

List of all members.


Public Types

enum  Appearance { NoBorders = 0, BottomUpStacked = 1, TopDownStacked = 2 }

Signals

void geometryChanged ()
void itemAttached (Plasma::ExtenderItem *)
void itemDetached (Plasma::ExtenderItem *)

Public Member Functions

Appearance appearance () const
QList< ExtenderItem * > attachedItems () const
QList< ExtenderItem * > detachedItems () const
QString emptyExtenderMessage () const
 Extender (Applet *applet)
ExtenderItem * item (const QString &name) const
QList< ExtenderItem * > items () const
void setAppearance (Appearance appearance)
void setEmptyExtenderMessage (const QString &message)
 ~Extender ()

Protected Member Functions

virtual FrameSvg::EnabledBorders enabledBordersForItem (ExtenderItem *item) const
virtual void itemAddedEvent (ExtenderItem *item, const QPointF &pos)
QVariant itemChange (GraphicsItemChange change, const QVariant &value)
virtual void itemHoverEnterEvent (ExtenderItem *item)
virtual void itemHoverLeaveEvent (ExtenderItem *item)
virtual void itemHoverMoveEvent (ExtenderItem *item, const QPointF &pos)
virtual void itemRemovedEvent (ExtenderItem *item)
void mousePressEvent (QGraphicsSceneMouseEvent *event)
void resizeEvent (QGraphicsSceneResizeEvent *event)
virtual void saveState ()

Properties

QString emptyExtenderMessage

Detailed Description

Extends applets to allow detachable parts.

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.

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.

Definition at line 63 of file extender.h.


Member Enumeration Documentation

enum Plasma::Extender::Appearance

Description on how to render the extender's items.

Enumerator:
NoBorders  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 the applet containing this extender.

BottomUpStacked  Draws no borders on the topmost extenderitem, but draws the left, top and right border on subsequent items.

When margins of the containing dialog are set to 0, except for the top margin, this leads to the 'stacked' look, recommended for extenders of applet's contained in a panel at the bottom of the screen.

TopDownStacked  Draws no borders on the bottom extenderitem, but draws the left, bottom and right border on subsequent items.

When margins of the containing dialog are set to 0, except for the bottom margin, this leads to the 'stacked' look, recommended for extenders of applet's contained in a panel at the top of the screen.

Definition at line 72 of file extender.h.


Constructor & Destructor Documentation

Plasma::Extender::Extender ( Applet *  applet  )  [explicit]

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. The constructor also takes care of restoring ExtenderItems that were contained in this extender before, so ExtenderItems are persistent between sessions.

Parameters:
applet The applet this extender is part of. Null is not allowed here.

Definition at line 73 of file extender.cpp.

Plasma::Extender::~Extender (  ) 

Definition at line 98 of file extender.cpp.


Member Function Documentation

Extender::Appearance Plasma::Extender::appearance (  )  const

Returns:
the current way of rendering extender items that is used.

Definition at line 178 of file extender.cpp.

QList< ExtenderItem * > Plasma::Extender::attachedItems (  )  const

Returns:
a list of all attached extender items.

Definition at line 139 of file extender.cpp.

QList< ExtenderItem * > Plasma::Extender::detachedItems (  )  const

Returns:
a list of all detached extender items.

Definition at line 144 of file extender.cpp.

QString Plasma::Extender::emptyExtenderMessage (  )  const

Returns:
The text to be shown whenever the applet's layout is empty.

FrameSvg::EnabledBorders Plasma::Extender::enabledBordersForItem ( ExtenderItem *  item  )  const [protected, virtual]

This function get's called on every item to determine which background border's to render.

Parameters:
item the item for which it's position or extender has changed.
Returns:
the borders that have to be enabled on it's background.

Definition at line 302 of file extender.cpp.

void Plasma::Extender::geometryChanged (  )  [signal]

Fires when an extender's preferred size changes.

ExtenderItem * Plasma::Extender::item ( const QString &  name  )  const

This function can be used for easily determining if a certain item is already 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 (!item(source)) { //add an extender item monitoring this source. }

Definition at line 157 of file extender.cpp.

void Plasma::Extender::itemAddedEvent ( ExtenderItem *  item,
const QPointF &  pos 
) [protected, virtual]

Get's called after an item has been added to this extender.

The bookkeeping has already 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.

Parameters:
item The item that has just been added.
pos The location the item has been dropped in local coordinates.

Definition at line 214 of file extender.cpp.

void Plasma::Extender::itemAttached ( Plasma::ExtenderItem *   )  [signal]

Fires when an extender item is added to this extender.

QVariant Plasma::Extender::itemChange ( GraphicsItemChange  change,
const QVariant &  value 
) [protected]

Reimplemented from QGraphicsWidget.

Definition at line 190 of file extender.cpp.

void Plasma::Extender::itemDetached ( Plasma::ExtenderItem *   )  [signal]

Fires when an extender item is removed from this extender.

void Plasma::Extender::itemHoverEnterEvent ( ExtenderItem *  item  )  [protected, virtual]

Get's called when an ExtenderItem that get's dragged enters this extender.

Default implementation does nothing.

Definition at line 251 of file extender.cpp.

void Plasma::Extender::itemHoverLeaveEvent ( ExtenderItem *  item  )  [protected, virtual]

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.

Definition at line 285 of file extender.cpp.

void Plasma::Extender::itemHoverMoveEvent ( ExtenderItem *  item,
const QPointF &  pos 
) [protected, virtual]

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.

Parameters:
item The item that's hovering over this extender. Most useful for obtaining the size of the spacer.
pos The location the item is hovering.

Definition at line 256 of file extender.cpp.

void Plasma::Extender::itemRemovedEvent ( ExtenderItem *  item  )  [protected, virtual]

Get's called after an item has been removed from this extender.

All bookkeeping has already been done when this function get's called.

Parameters:
item The item that has just been removed.

Definition at line 236 of file extender.cpp.

QList< ExtenderItem * > Plasma::Extender::items (  )  const

Returns:
a list of all extender items (attached AND detached) where the source applet is this applet.

Definition at line 118 of file extender.cpp.

void Plasma::Extender::mousePressEvent ( QGraphicsSceneMouseEvent *  event  )  [protected]

Reimplemented from QGraphicsWidget.

Definition at line 205 of file extender.cpp.

void Plasma::Extender::resizeEvent ( QGraphicsSceneResizeEvent *  event  )  [protected]

Reimplemented from QGraphicsWidget.

Reimplemented from QGraphicsWidget.

Definition at line 199 of file extender.cpp.

void Plasma::Extender::saveState (  )  [protected, virtual]

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.

Definition at line 183 of file extender.cpp.

void Plasma::Extender::setAppearance ( Appearance  appearance  ) 

Use this function to instruct the extender on how to render it's items.

Usually you will want to call this function in your applet's constraintsEvent, allthough this is already done for you when using PopupApplet at base class for your applet. Defaults to NoBorders.

Definition at line 168 of file extender.cpp.

void Plasma::Extender::setEmptyExtenderMessage ( const QString &  message  ) 

Parameters:
message The text to be shown whenever the applet's extender is empty. Defaults to i18n'ed "no items".

Definition at line 104 of file extender.cpp.


Property Documentation

QString Plasma::Extender::emptyExtenderMessage [read, write]

Definition at line 66 of file extender.h.


The documentation for this class was generated from the following files:
  • extender.h
  • extender.cpp

Plasma

Skip menu "Plasma"
  • Main Page
  • Namespace List
  • Class Hierarchy
  • Alphabetical List
  • Class List
  • File List
  • Namespace Members
  • Class Members
  • Related Pages

kdelibs

Skip menu "kdelibs"
  • DNSSD
  • Interfaces
  •   KHexEdit
  •   KMediaPlayer
  •   KSpeech
  •   KTextEditor
  • Kate
  • kconf_update
  • KDE3Support
  •   KUnitTest
  • KDECore
  • KDED
  • KDEsu
  • KDEUI
  • KDocTools
  • KFile
  • KHTML
  • KImgIO
  • KInit
  • kio
  • KIOSlave
  • KJS
  •   KJS-API
  •   WTF
  • kjsembed
  • KNewStuff
  • KParts
  • Kross
  • KUtils
  • Nepomuk
  • Plasma
  • Solid
  • Sonnet
  • ThreadWeaver
Generated for kdelibs by doxygen 1.5.7
This website is maintained by Adriaan de Groot and Allen Winter.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal