libplasma

Plasma::Applet

Plasma::Applet Class Reference

#include <applet.h>

Inheritance diagram for Plasma::Applet:

[legend]

List of all members.

Detailed Description

The base Applet class.

Applet provides several important roles for add-ons widgets in Plasma.

First, it is the base class for the plugin system and therefore is the interface to applets for host applications. It also handles the life time management of data engines (e.g. all data engines accessed via Applet::dataEngine(const QString&) are properly deref'd on Applet destruction), background painting (allowing for consistent and complex look and feel in just one line of code for applets), loading and starting of scripting support for each applet, providing access to the associated plasmoid package (if any) and access to configuration data.

See techbase.kde.org for tutorial on writing Applets using this class.

Definition at line 58 of file applet.h.


Public Types
enum	{ Type = Plasma::AppletType }
typedef QList< Applet * >	List
typedef QHash< QString, Applet * >	Dict
Public Slots
void	setImmutable (bool immutable)
void	destroy ()
virtual void	showConfigurationInterface ()
void	flushUpdatedConstraints ()
Containment *	containment () const
Signals
void	requestFocus (bool focus)
void	geometryChanged ()
void	configNeedsSaving ()
Public Member Functions
	Applet (QGraphicsItem *parent=0, const QString &serviceId=QString(), uint appletId=0)
	Applet (QObject *parent, const QVariantList &args)
	~Applet ()
virtual void	init ()
uint	id () const
KConfigGroup	config () const
KConfigGroup	config (const QString &group) const
void	save (KConfigGroup *group) const
KConfigGroup	globalConfig () const
ConfigXml *	configXml () const
Q_INVOKABLE DataEngine *	dataEngine (const QString &name) const
const Package *	package () const
void	updateConstraints (Plasma::Constraints constraints=Plasma::AllConstraints)
virtual void	constraintsUpdated (Plasma::Constraints constraints)
virtual FormFactor	formFactor () const
virtual Location	location () const
QRectF	contentRect () const
QSizeF	contentSize () const
void	setContentSize (const QSizeF &size)
void	setContentSize (int width, int height)
virtual QSizeF	contentSizeHint () const
void	setMinimumContentSize (const QSizeF &minSize)
void	setMinimumContentSize (int minWidth, int minHeight)
QSizeF	minimumContentSize () const
void	setMaximumContentSize (const QSizeF &maxSize)
void	setMaximumContentSize (int maxWidth, int maxHeight)
QSizeF	maximumContentSize () const
bool	hasConfigurationInterface ()
virtual void	paintInterface (QPainter painter, const QStyleOptionGraphicsItem option, const QRect &contentsRect)
QString	name () const
QString	pluginName () const
bool	shouldConserveResources () const
QString	icon () const
QString	category () const
QColor	color () const
bool	isImmutable () const
bool	isKioskImmutable () const
bool	drawStandardBackground ()
void	setDrawStandardBackground (bool drawBackground)
bool	failedToLaunch () const
void	setFailedToLaunch (bool failed, const QString &reason=QString())
bool	needsConfiguring () const
void	setNeedsConfiguring (bool needsConfiguring)
int	type () const
QRectF	boundingRect () const
virtual QList< QAction * >	contextActions ()
void	setShadowShown (bool)
bool	isShadowShown () const
virtual QSizeF	sizeHint () const
void	setGeometry (const QRectF &geometry)
void	setIsContainment (bool isContainment)
bool	isContainment () const
void	resetConfigurationObject ()
Static Public Member Functions
static KPluginInfo::List	knownApplets (const QString &category=QString(), const QString &parentApp=QString())
static KPluginInfo::List	knownAppletsForMimetype (const QString &mimetype)
static QStringList	knownCategories (const QString &parentApp=QString(), bool visibleOnly=true)
static Applet *	loadApplet (const QString &name, uint appletId=0, const QVariantList &args=QVariantList())
static Applet *	loadApplet (const KPluginInfo &info, uint appletId=0, const QVariantList &args=QVariantList())
static QString	category (const KPluginInfo &applet)
static QString	category (const QString &appletName)
Protected Slots
void	performSetupConfig ()
void	checkImmutability ()
Protected Member Functions
virtual void	saveState (KConfigGroup *config) const
QString	globalName () const
QString	instanceName () const
void	watchForFocus (QObject *widget, bool watch=true)
void	needsFocus (bool focus)
void	setHasConfigurationInterface (bool hasInterface)
bool	eventFilter (QObject o, QEvent e)
QVariant	itemChange (GraphicsItemChange change, const QVariant &value)
Properties
bool	hasConfigurationInterface
QString	name
QString	category
bool	immutable
bool	drawStandardBackground
bool	failedToLaunch
bool	needsConfiguring
QRectF	boundingRect
QRectF	geometry
bool	shouldConserveResources

Member Typedef Documentation

typedef QList<Applet*> Plasma::Applet::List

Reimplemented in Plasma::Containment.

Definition at line 74 of file applet.h.

typedef QHash<QString, Applet*> Plasma::Applet::Dict

Reimplemented in Plasma::Containment.

Definition at line 75 of file applet.h.

Member Enumeration Documentation

anonymous enum

Enumerator:

Type

Definition at line 504 of file applet.h.

Constructor & Destructor Documentation

Plasma::Applet::Applet	(	QGraphicsItem *	parent = `0`,
		const QString &	serviceId = `QString()`,
		uint	appletId = `0`
	)			`[explicit]`

parent the QGraphicsItem this applet is parented to

servideId the name of the .desktop file containing the information about the widget
appletId a unique id used to differentiate between multiple instances of the same Applet type

Definition at line 309 of file applet.cpp.

Plasma::Applet::Applet	(	QObject *	parent,
		const QVariantList &	args
	)

This constructor is to be used with the plugin loading systems found in KPluginInfo and KService.

The argument list is expected to have two elements: the KService service ID for the desktop entry and an applet ID which must be a base 10 number.

parent a QObject parent; you probably want to pass in 0
args a list of strings containing two entries: the service id and the applet id

Definition at line 320 of file applet.cpp.

Plasma::Applet::~Applet ( )

Definition at line 332 of file applet.cpp.

Member Function Documentation

void Plasma::Applet::init ( ) [virtual]

This method is called once the applet is loaded and added to a Corona.

If the applet requires a QGraphicsScene or has an particularly intensive set of initialization routines to go through, consider implementing it in this method instead of the constructor.

Reimplemented in Plasma::Containment.

Definition at line 338 of file applet.cpp.

uint Plasma::Applet::id ( ) const

Returns:: the id of this applet

Definition at line 342 of file applet.cpp.

KConfigGroup Plasma::Applet::config ( ) const

Returns the KConfigGroup to access the applets configuration.

This config object will write to an instance specific config file named <appletname><instanceid>rc in the Plasma appdata directory.

Definition at line 391 of file applet.cpp.

KConfigGroup Plasma::Applet::config ( const QString & group ) const

Returns a config group with the name provided.

This ensures that the group name is properly namespaced to avoid collision with other applets that may be sharing this config file

Parameters:

group

the name of the group to access

Definition at line 385 of file applet.cpp.

void Plasma::Applet::save ( KConfigGroup * group ) const

Saves state information about this applet.

Definition at line 347 of file applet.cpp.

KConfigGroup Plasma::Applet::globalConfig ( ) const

Returns a KConfigGroup object to be shared by all applets of this type.

This config object will write to an applet-specific config object named plasma_<appletname>rc in the local config directory.

Definition at line 400 of file applet.cpp.

ConfigXml * Plasma::Applet::configXml ( ) const

Returns the config skeleton object from this applet's package, if any.

Returns:: config skeleton object, or 0 if none

Definition at line 434 of file applet.cpp.

DataEngine * Plasma::Applet::dataEngine ( const QString & name ) const

Loads the given DataEngine.

Tries to load the data engine given by name. Each engine is only loaded once, and that instance is re-used on all subsequent requests.

If the data engine was not found, an invalid data engine is returned (see DataEngine::isValid()).

Note that you should not delete the returned engine.

Parameters:

name

Name of the data engine to load

Returns:: pointer to the data engine if it was loaded, or an invalid data engine if the requested engine could not be loaded

Definition at line 439 of file applet.cpp.

const Package * Plasma::Applet::package ( ) const

Accessor for the associated Package object if any.

Generally, only Plasmoids come in a Package.

Returns:: the Package object, or 0 if none

Definition at line 454 of file applet.cpp.

void Plasma::Applet::updateConstraints ( Plasma::Constraints constraints = Plasma::AllConstraints )

Called when any of the geometry constraints have been updated.

This method calls constraintsUpdated, which may be reimplemented, once the Applet has been prepared for updating the constraints.

Parameters:

constraints

the type of constraints that were updated

Definition at line 459 of file applet.cpp.

void Plasma::Applet::constraintsUpdated ( Plasma::Constraints constraints ) [virtual]

Definition at line 464 of file applet.cpp.

FormFactor Plasma::Applet::formFactor ( ) const [virtual]

Returns the current form factor the applet is being displayed in.

See also:: Plasma::FormFactor

Reimplemented in Plasma::Containment.

Definition at line 828 of file applet.cpp.

Location Plasma::Applet::location ( ) const [virtual]

Returns the location of the scene which is displaying applet.

See also:: Plasma::Location

Reimplemented in Plasma::Containment.

Definition at line 859 of file applet.cpp.

QRectF Plasma::Applet::contentRect ( ) const

Returns the rect that the contents are positioned within in local coordinates.

Definition at line 870 of file applet.cpp.

QSizeF Plasma::Applet::contentSize ( ) const

Returns the area within which contents can be painted.

Definition at line 875 of file applet.cpp.

void Plasma::Applet::setContentSize ( const QSizeF & size )

Sets the content size.

Note:: Normally an applet should never call this directly except in the constructor to provide a default size

size the new size of the contents area

Definition at line 886 of file applet.cpp.

void Plasma::Applet::setContentSize	(	int	width,
		int	height
	)

Sets the content size.

Note:: Normally an applet should never call this directly except in the constructor to provide a default size

width the new width of the contents area
height the new height of the contents area

Definition at line 894 of file applet.cpp.

QSizeF Plasma::Applet::contentSizeHint ( ) const [virtual]

Returns an ideal size for the applet's content.

Applets can re-implement this to provide a suitable size based on their contents.

Unlike sizeHint() , contentSizeHint() does not include the size of any borders surrounding the content area.

The default implementation returns the sizeHint() of the applet's layout if it has one, or a null size otherwise.

Definition at line 899 of file applet.cpp.

void Plasma::Applet::setMinimumContentSize ( const QSizeF & minSize )

Sets the minimum size for the content of this applet.

Definition at line 908 of file applet.cpp.

void Plasma::Applet::setMinimumContentSize	(	int	minWidth,
		int	minHeight
	)

Sets the minimum size for the content of this applet.

minWidth the new minimum width of the contents area
minHeight the new minimum height of the contents area

Definition at line 916 of file applet.cpp.

QSizeF Plasma::Applet::minimumContentSize ( ) const

Get the minimum size for the content of this applet.

Definition at line 921 of file applet.cpp.

void Plasma::Applet::setMaximumContentSize ( const QSizeF & maxSize )

Sets the maximum size for the content of this applet.

Definition at line 929 of file applet.cpp.

void Plasma::Applet::setMaximumContentSize	(	int	maxWidth,
		int	maxHeight
	)

Sets the maximum size for the content of this applet.

maxWidth the new maximum width of the contents area
maxHeight the new maximum height of the contents area

Definition at line 937 of file applet.cpp.

QSizeF Plasma::Applet::maximumContentSize ( ) const

Get the minimum size for the content of this applet.

Definition at line 942 of file applet.cpp.

KPluginInfo::List Plasma::Applet::knownApplets	(	const QString &	category = `QString()`,
		const QString &	parentApp = `QString()`
	)			`[static]`

Returns a list of all known applets.

Parameters:

	category	Only applets matchin this category will be returned. Useful in conjunction with knownCategories. If "Misc" is passed in, then applets without a Categories= entry are also returned. If an empty string is passed in, all applets are returned.
	parentApp	the application to filter applets on. Uses the X-KDE-ParentApp entry (if any) in the plugin info. The default value of QString() will result in a list containing only applets not specifically registered to an application.

Returns:: list of applets

Definition at line 1044 of file applet.cpp.

KPluginInfo::List Plasma::Applet::knownAppletsForMimetype ( const QString & mimetype ) [static]

Returns a list of all known applets associated with a certain mimetype.

Returns:: list of applets

Definition at line 1071 of file applet.cpp.

QStringList Plasma::Applet::knownCategories	(	const QString &	parentApp = `QString()`,
		bool	visibleOnly = `true`
	)			`[static]`

Returns a list of all the categories used by installed applets.

Parameters:

parentApp

the application to filter applets on. Uses the X-KDE-ParentApp entry (if any) in the plugin info. The default value of QString() will result in a list containing only applets not specifically registered to an application.

Returns:: list of categories

Parameters:

visibleOnly

true if it should only return applets that are marked as visible

Definition at line 1079 of file applet.cpp.

bool Plasma::Applet::hasConfigurationInterface ( )

Returns:: true if this plasmoid provides a GUI configuration

Applet * Plasma::Applet::loadApplet	(	const QString &	name,
		uint	appletId = `0`,
		const QVariantList &	args = `QVariantList()`
	)			`[static]`

Attempts to load an applet.

Returns a pointer to the applet if successful. The caller takes responsibility for the applet, including deleting it when no longer needed.

Parameters:

	name	the plugin name, as returned by KPluginInfo::pluginName()
	applet	unique ID to assign the applet, or zero to have one assigned automatically.
	args	to send the applet extra arguments

Returns:: a pointer to the loaded applet, or 0 on load failure

Definition at line 1112 of file applet.cpp.

Applet * Plasma::Applet::loadApplet	(	const KPluginInfo &	info,
		uint	appletId = `0`,
		const QVariantList &	args = `QVariantList()`
	)			`[static]`

Attempts to load an applet.

Returns a pointer to the applet if successful. The caller takes responsibility for the applet, including deleting it when no longer needed.

Parameters:

	info	KPluginInfo object for the desired applet
	applet	unique ID to assign the applet, or zero to have one assigned automatically.

Returns:: a pointer to the loaded applet, or 0 on load failure

Definition at line 1154 of file applet.cpp.

void Plasma::Applet::paintInterface	(	QPainter *	painter,
		const QStyleOptionGraphicsItem *	option,
		const QRect &	contentsRect
	)			`[virtual]`

This method is called when the interface should be painted.

Parameters:

	painter	the QPainter to use to do the paintiner
	option	the style options object
	contentsRect	the rect to paint within; automatically adjusted for the background, if any

Definition at line 816 of file applet.cpp.

QString Plasma::Applet::name ( ) const

Returns the user-visible name for the applet, as specified in the .desktop file.

Returns:: the user-visible name for the applet.

QString Plasma::Applet::pluginName ( ) const

Returns the plugin name for the applet.

Definition at line 488 of file applet.cpp.

bool Plasma::Applet::shouldConserveResources ( ) const

Whether the applet should conserve resources.

If true, try to avoid doing stuff which is computationally heavy. Try to conserve power and resources.

Returns:: true if it should conserve resources, false if it does not.

QString Plasma::Applet::icon ( ) const

Returns the icon related to this applet.

Definition at line 479 of file applet.cpp.

QString Plasma::Applet::category ( ) const

Returns the category the applet is in, as specified in the .desktop file.

QColor Plasma::Applet::color ( ) const

Returns the color corresponding to the applet's category.

Definition at line 746 of file applet.cpp.

QString Plasma::Applet::category ( const KPluginInfo & applet ) [static]

Get the category of the given applet.

Parameters:

KPluginInfo object for the applet

Definition at line 511 of file applet.cpp.

QString Plasma::Applet::category ( const QString & appletName ) [static]

Get the category of the given applet.

Parameters:

the

name of the applet

Definition at line 516 of file applet.cpp.

bool Plasma::Applet::isImmutable ( ) const

Returns:: true if this applet is immutable

Definition at line 532 of file applet.cpp.

bool Plasma::Applet::isKioskImmutable ( ) const

Returns:: true if this applet is immutable due to Kiosk settings

Definition at line 539 of file applet.cpp.

bool Plasma::Applet::drawStandardBackground ( )

Returns:: returns whether or not the applet is using the standard background

void Plasma::Applet::setDrawStandardBackground ( bool drawBackground )

Sets whether the applet should automatically draw the standard background.

Defaults to true

Definition at line 561 of file applet.cpp.

bool Plasma::Applet::failedToLaunch ( ) const

If for some reason, the applet fails to get up on its feet (the library couldn't be loaded, necessary hardware support wasn't found, etc.

.) this method returns true

void Plasma::Applet::setFailedToLaunch	(	bool	failed,
		const QString &	reason = `QString()`
	)

Call this method when the applet fails to launch properly.

An optional reason can be provided.

Not that all children items will be deleted when this method is called. If you have pointers to these items, you will need to reset them after calling this method.

Parameters:

	failed	true when the applet failed, false when it succeeded
	reason	an optional reason to show the user why the applet failed to launch

Definition at line 593 of file applet.cpp.

bool Plasma::Applet::needsConfiguring ( ) const

Returns:: true if the applet currently needs to be configured, otherwise, false

void Plasma::Applet::setNeedsConfiguring ( bool needsConfiguring )

When the applet needs to be configured before being usable, this method can be called to show a standard interface prompting the user to configure the applet.

Not that all children items will be deleted when this method is called. If you have pointers to these items, you will need to reset them after calling this method.

Parameters:

needsConfiguring

true if the applet needs to be configured, or false if it doesn't

Definition at line 636 of file applet.cpp.

int Plasma::Applet::type ( ) const

Reimplemented from QGraphicsItem.

Definition at line 703 of file applet.cpp.

QRectF Plasma::Applet::boundingRect ( ) const [virtual]

Reimplemented from QGraphicsItem.

Reimplemented from Plasma::Widget.

QList< QAction * > Plasma::Applet::contextActions ( ) [virtual]

Returns a list of context-related QAction instances.

This is used e.g. within the DesktopView to display a contextmenu.

Returns:: A list of actions. The default implementation returns an empty list.

Definition at line 740 of file applet.cpp.

void Plasma::Applet::setShadowShown ( bool shown )

Sets shadow for the given applet.

Definition at line 1163 of file applet.cpp.

bool Plasma::Applet::isShadowShown ( ) const

Returns true if the given item has a shadow shown.

Definition at line 1191 of file applet.cpp.

QSizeF Plasma::Applet::sizeHint ( ) const [virtual]

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.

Returns:: recommended size for this Plasma::Widget.

Reimplemented from Plasma::Widget.

Definition at line 725 of file applet.cpp.

void Plasma::Applet::setGeometry ( const QRectF & geometry ) [virtual]

Sets the geometry of this Plasma::Applet.

Parameters:

geometry

the geometry to apply to this Plasma::Applet.

Reimplemented from Plasma::Widget.

Definition at line 1242 of file applet.cpp.

void Plasma::Applet::setIsContainment ( bool isContainment )

Sets whether or not this Applet is acting as a Containment.

Definition at line 1279 of file applet.cpp.

bool Plasma::Applet::isContainment ( ) const

Returns:: true if this Applet is currently being used as a Containment, false otherwise

Definition at line 1284 of file applet.cpp.

void Plasma::Applet::resetConfigurationObject ( )

Definition at line 427 of file applet.cpp.

void Plasma::Applet::requestFocus ( bool focus ) [signal]

Emitted when the applet needs to take (or lose) keyboard focus.

An applet should emit this signal to ensure that autohiding elements stay unhidden and other bits of bookkeeping are performed to ensure proper function.

If you call watchForFocus on your applet, then this is handled for the applet and it is not necessary to emit the signal directly.

Parameters:

focus

true if the applet is taking keyboard focus, false if it is giving it up

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

Emitted whenever the applet makes a geometry change, so that views can coordinate themselves with these changes if they desire.

void Plasma::Applet::configNeedsSaving ( ) [signal]

Emitted when an applet has changed values in its configuration and wishes for them to be saved at the next save point.

As this implies disk activity, this signal should be used with care.

Note:: This does not need to be emitted from saveState by individual applets.

void Plasma::Applet::setImmutable ( bool immutable ) [slot]

Sets whether or not this applet is immutable or not.

immutable true if this applet should not be changeable

Definition at line 544 of file applet.cpp.

void Plasma::Applet::destroy ( ) [slot]

Destroys the applet; it will be deleted and configurations reset.

Definition at line 416 of file applet.cpp.

void Plasma::Applet::showConfigurationInterface ( ) [virtual, slot]

Reimplement this slot to show a configuration dialog.

Let the user play with the plasmoid options. Called when the user selects the configure entry from the context menu.

Definition at line 1016 of file applet.cpp.

void Plasma::Applet::flushUpdatedConstraints ( ) [slot]

Sends all pending contraints updates to the applet.

Will usually be called automatically, but can also be called manually if needed.

Definition at line 675 of file applet.cpp.

Containment * Plasma::Applet::containment ( ) const [slot]

Returns:: the Containment, if any, this applet belongs to

Definition at line 834 of file applet.cpp.

void Plasma::Applet::saveState ( KConfigGroup * config ) const [protected, virtual]

Called when a request to save the state of the applet is made during runtime.

Definition at line 373 of file applet.cpp.

QString Plasma::Applet::globalName ( ) const [protected]

Returns the name of the applet.

This will be the same for all instances of this applet.

Definition at line 950 of file applet.cpp.

QString Plasma::Applet::instanceName ( ) const [protected]

Returns a name unique to the instance of this applet.

Useful for being able to refer directly to a particular applet. Combines the global name with the applet id

Definition at line 959 of file applet.cpp.

void Plasma::Applet::watchForFocus	(	QObject *	widget,
		bool	watch = `true`
	)			`[protected]`

Calling this results in an eventFilter being places on the widget.

Parameters:

	widget	the widget to watch for keyboard focus
	watch	whether to start watching the widget, or to stop doing so

Definition at line 964 of file applet.cpp.

void Plasma::Applet::needsFocus ( bool focus ) [protected]

Call this whenever focus is needed or not needed.

You do not have to call this method for widgets that have been registered with watchForFocus

See also:: watchForFocus

Parameters:

focus

whether to or not to request focus

Definition at line 982 of file applet.cpp.

void Plasma::Applet::setHasConfigurationInterface ( bool hasInterface ) [protected]

Sets whether or not this applet provides a user interface for configuring the applet.

It defaults to false, and if true is passed in you should also reimplement showConfigurationInterface()

hasInterface whether or not there is a user interface available

Definition at line 996 of file applet.cpp.

bool Plasma::Applet::eventFilter	(	QObject *	o,
		QEvent *	e
	)			`[protected]`

Reimplemented from QObject.

Definition at line 1001 of file applet.cpp.

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

Reimplemented from QGraphicsItem.

Reimplemented from Plasma::Widget.

Definition at line 1198 of file applet.cpp.

void Plasma::Applet::performSetupConfig ( ) [protected, slot]

libplasma

Plasma::Applet Class Reference

Detailed Description

Public Types

Public Slots

Signals

Public Member Functions

Static Public Member Functions

Protected Slots

Protected Member Functions

Properties

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation