Applet Class Reference

from PyKDE4.plasma import *

Inherits: QGraphicsWidget → QObject
Subclasses: Plasma.AppletProtectedThunk, Plasma.Containment, Plasma.GLApplet, Plasma.PopupApplet
Namespace: Plasma

Detailed Description

Applet plasma/applet.h <Plasma/Applet>

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 tutorials on writing Applets using this class.

Enumerations
<anonymous>	{ Type }
BackgroundHint	{ NoBackground, StandardBackground, TranslucentBackground, DefaultBackground }
Signals
	activate ()
	appletDestroyed (Plasma.Applet applet)
	appletTransformedByUser ()
	appletTransformedItself ()
	configNeedsSaving ()
	extenderItemRestored (Plasma.ExtenderItem item)
	geometryChanged ()
	immutabilityChanged (Plasma.ImmutabilityType immutable)
	messageButtonPressed (Plasma.MessageButton button)
	newStatus (Plasma.ItemStatus status)
	releaseVisualFocus ()
	sizeHintChanged (Qt::SizeHint which)
Methods
	__init__ (self, QGraphicsItem parent=0, QString serviceId=QString(), long appletId=0)
	__init__ (self, QGraphicsItem parent, QString serviceId, long appletId, [QVariant] args)
	__init__ (self, QObject parent, [QVariant] args)
	__init__ (self, QString packagePath, long appletId, [QVariant] args)
	__init__ (self, KPluginInfo info, QGraphicsItem parent=0, long appletId=0)
QAction	action (self, QString name)
	addAction (self, QString name, QAction action)
	addAssociatedWidget (self, QWidget widget)
Plasma.AspectRatioMode	aspectRatioMode (self)
QString	associatedApplication (self)
KUrl.List	associatedApplicationUrls (self)
Plasma.Applet.BackgroundHints	backgroundHints (self)
QString	category (self)
KConfigGroup	config (self)
KConfigGroup	config (self, QString group)
	configChanged (self)
Plasma.ConfigLoader	configScheme (self)
bool	configurationRequired (self)
	constraintsEvent (self, Plasma.Constraints constraints)
Plasma.Containment	containment (self)
Plasma.Context	context (self)
[QAction]	contextualActions (self)
	createConfigurationInterface (self, KConfigDialog parent)
QStringList	customCategories (self)
Plasma.DataEngine	dataEngine (self, QString name)
	destroy (self)
bool	destroyed (self)
bool	eventFilter (self, QObject o, QEvent e)
Plasma.Extender	extender (self)
	flushPendingConstraintsEvents (self)
	focusInEvent (self, QFocusEvent event)
QFont	font (self)
Plasma.FormFactor	formFactor (self)
KConfigGroup	globalConfig (self)
KShortcut	globalShortcut (self)
bool	hasAuthorization (self, QString constraint)
bool	hasConfigurationInterface (self)
bool	hasFailedToLaunch (self)
bool	hasValidAssociatedApplication (self)
	hoverEnterEvent (self, QGraphicsSceneHoverEvent event)
	hoverLeaveEvent (self, QGraphicsSceneHoverEvent event)
QString	icon (self)
long	id (self)
Plasma.ImmutabilityType	immutability (self)
	init (self)
	initExtenderItem (self, Plasma.ExtenderItem item)
bool	isBusy (self)
bool	isContainment (self)
bool	isPopupShowing (self)
bool	isPublished (self)
bool	isRegisteredAsDragHandle (self, QGraphicsItem item)
bool	isUserConfiguring (self)
QVariant	itemChange (self, QGraphicsItem::GraphicsItemChange change, QVariant value)
Plasma.Location	location (self)
	lower (self)
QRectF	mapFromView (self, QGraphicsView view, QRect rect)
QRect	mapToView (self, QGraphicsView view, QRectF rect)
	mouseMoveEvent (self, QGraphicsSceneMouseEvent event)
QString	name (self)
Plasma.Package	package (self)
	paintInterface (self, QPainter painter, QStyleOptionGraphicsItem option, QRect contentsRect)
	paintWindowFrame (self, QPainter painter, QStyleOptionGraphicsItem option, QWidget widget)
QString	pluginName (self)
QPoint	popupPosition (self, QSize s)
QPoint	popupPosition (self, QSize s, Qt::AlignmentFlag alignment)
	raise_ (self)
	registerAsDragHandle (self, QGraphicsItem item)
	removeAssociatedWidget (self, QWidget widget)
	resizeEvent (self, QGraphicsSceneResizeEvent event)
	restore (self, KConfigGroup group)
	runAssociatedApplication (self)
	save (self, KConfigGroup group)
	saveState (self, KConfigGroup config)
bool	sceneEventFilter (self, QGraphicsItem watched, QEvent event)
QRect	screenRect (self)
	setAspectRatioMode (self, Plasma.AspectRatioMode a0)
	setAssociatedApplication (self, QString string)
	setAssociatedApplicationUrls (self, KUrl.List urls)
	setBackgroundHints (self, Plasma.Applet.BackgroundHints hints)
	setBusy (self, bool busy)
	setConfigurationRequired (self, bool needsConfiguring, QString reason=QString())
	setCustomCategories (self, QStringList categories)
	setFailedToLaunch (self, bool failed, QString reason=QString())
	setGlobalShortcut (self, KShortcut shortcut)
	setHasConfigurationInterface (self, bool hasInterface)
	setImmutability (self, Plasma.ImmutabilityType immutable)
	setStatus (self, Plasma.ItemStatus stat)
QPainterPath	shape (self)
bool	shouldConserveResources (self)
	showConfigurationInterface (self)
	showConfigurationInterface (self, QWidget widget)
	showMessage (self, QIcon icon, QString message, Plasma.MessageButtons buttons)
QSizeF	sizeHint (self, Qt::SizeHint which, QSizeF constraint=QSizeF())
[QVariant]	startupArguments (self)
Plasma.ItemStatus	status (self)
	timerEvent (self, QTimerEvent event)
int	type (self)
	unpublish (self)
	unregisterAsDragHandle (self, QGraphicsItem item)
	updateConstraints (self, Plasma.Constraints constraints=Plasma.AllConstraints)
QGraphicsView	view (self)
Static Methods
QString	category (KPluginInfo applet)
QString	category (QString appletName)
[KPluginInfo]	listAppletInfo (QString category=QString(), QString parentApp=QString())
[KPluginInfo]	listAppletInfoForMimetype (QString mimetype)
[KPluginInfo]	listAppletInfoForUrl (QUrl url)
QStringList	listCategories (QString parentApp=QString(), bool visibleOnly=1)
Plasma.Applet	load (QString name, long appletId=0, [QVariant] args=QVariantList())
Plasma.Applet	load (KPluginInfo info, long appletId=0, [QVariant] args=QVariantList())
Plasma.Applet	loadPlasmoid (QString path, long appletId=0, [QVariant] args=QVariantList())
KSharedPtr	packageStructure ()

Signal Documentation

activate ( )

Emitted when activation is requested due to, for example, a global keyboard shortcut. By default the wiget is given focus.

Signal syntax:: QObject.connect(source, SIGNAL("activate()"), target_slot)

appletDestroyed	(	Plasma.Applet	applet
	)

Emitted when the applet is deleted

Signal syntax:: QObject.connect(source, SIGNAL("appletDestroyed(Plasma::Applet*)"), target_slot)

appletTransformedByUser ( )

Emitted when the user completes a transformation of the applet.

Signal syntax:: QObject.connect(source, SIGNAL("appletTransformedByUser()"), target_slot)

appletTransformedItself ( )

Emitted when the applet changes its own geometry or transform.

Signal syntax:: QObject.connect(source, SIGNAL("appletTransformedItself()"), target_slot)

configNeedsSaving ( )

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.

Signal syntax:: QObject.connect(source, SIGNAL("configNeedsSaving()"), target_slot)

extenderItemRestored	(	Plasma.ExtenderItem	item
	)

Emitted when an ExtenderItem in a scripting applet needs to be initialized

Signal syntax:: QObject.connect(source, SIGNAL("extenderItemRestored(Plasma::ExtenderItem*)"), target_slot)

geometryChanged ( )

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

Signal syntax:: QObject.connect(source, SIGNAL("geometryChanged()"), target_slot)

immutabilityChanged	(	Plasma.ImmutabilityType	immutable
	)

Emitted when the immutability changes

Since:: 4.4

Signal syntax:: QObject.connect(source, SIGNAL("immutabilityChanged(Plasma::ImmutabilityType)"), target_slot)

messageButtonPressed	(	Plasma.MessageButton	button
	)

Emitted when the user clicked on a button of the message overlay

See also:: showMessage

See also:: Plasma.MessageButton

Since:: 4.3

Signal syntax:: QObject.connect(source, SIGNAL("messageButtonPressed(const Plasma::MessageButton)"), target_slot)

newStatus	(	Plasma.ItemStatus	status
	)

Emitted when the applet status changes

Since:: 4.4

Signal syntax:: QObject.connect(source, SIGNAL("newStatus(Plasma::ItemStatus)"), target_slot)

releaseVisualFocus ( )

This signal indicates that an application launch, window creation or window focus event was triggered. This is used, for instance, to ensure that the Dashboard view in Plasma Desktop hides when such an event is triggered by an item it is displaying.

Signal syntax:: QObject.connect(source, SIGNAL("releaseVisualFocus()"), target_slot)

sizeHintChanged	(	Qt::SizeHint	which
	)

Emitted by Applet subclasses when they change a sizeHint and wants to announce the change

Signal syntax:: QObject.connect(source, SIGNAL("sizeHintChanged(Qt::SizeHint)"), target_slot)

Method Documentation

__init__	(	self,
		QGraphicsItem	parent=0,
		QString	serviceId=QString(),
		long	appletId=0
	)

Parameters:

	parent	the QGraphicsItem this applet is parented to
	serviceId	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

__init__	(	self,
		QGraphicsItem	parent,
		QString	serviceId,
		long	appletId,
		[QVariant]	args
	)

Parameters:

	parent	the QGraphicsItem this applet is parented to
	serviceId	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
	args	a list of strings containing two entries: the service id and the applet id

Since:: 4.3

__init__	(	self,
		QObject	parent,
		[QVariant]	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.

Parameters:

	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

__init__	(	self,
		QString	packagePath,
		long	appletId,
		[QVariant]	args
	)

Internal:: This constructor is to be used with the Package loading system.

Parameters:

	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

Since:: 4.3

__init__	(	self,
		KPluginInfo	info,
		QGraphicsItem	parent=0,
		long	appletId=0
	)

Parameters:

	parent	the QGraphicsItem this applet is parented to
	info	the plugin information object for this Applet
	appletId	a unique id used to differentiate between multiple instances of the same Applet type

Since:: 4.6

QAction action	(	self,
		QString	name
	)

Returns the QAction with the given name from our collection

addAction	(	self,
		QString	name,
		QAction	action
	)

Adds the action to our collection under the given name

addAssociatedWidget	(	self,
		QWidget	widget
	)

associate actions with this widget, including ones added after this call. needed to make keyboard shortcuts work.

Plasma.AspectRatioMode aspectRatioMode ( self )

Returns:: the preferred aspect ratio mode for placement and resizing

QString associatedApplication ( self )

Returns:: the application associated to this applet

Since:: 4.4

KUrl.List associatedApplicationUrls ( self )

Returns:: the urls associated to this applet

Since:: 4.4

Plasma.Applet.BackgroundHints backgroundHints ( self )

Returns:: BackgroundHints flags combination telling if the standard background is shown and if it has a drop shadow

QString category ( self )

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

KConfigGroup config ( self )

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

KConfigGroup config	(	self,
		QString	group
	)

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

configChanged ( self )

Called when applet configuration values have changed.

Plasma.ConfigLoader configScheme ( self )

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

Returns:: config skeleton object, or 0 if none

bool configurationRequired ( self )

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

constraintsEvent	(	self,
		Plasma.Constraints	constraints
	)

Called when any of the constraints for the applet have been updated. These constraints range from notifying when the applet has officially "started up" to when geometry changes to when the form factor changes.

Each constraint that has been changed is passed in the constraints flag. All of the constraints and how they work is documented in the

See also:: Plasma.Constraints enumeration.

On applet creation, this is always called prior to painting and can be used as an opportunity to layout the widget, calculate sizings, etc.

Do not call update() from this method; an update() will be triggered at the appropriate time for the applet.

Parameters:

constraints

the type of constraints that were updated

@property constraint

Plasma.Containment containment ( self )

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

Plasma.Context context ( self )

Returns the workspace context which the applet is operating in

[QAction] contextualActions ( self )

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.

createConfigurationInterface	(	self,
		KConfigDialog	parent
	)

Reimplement this method so provide a configuration interface, parented to the supplied widget. Ownership of the widgets is passed to the parent widget.

Typically one would add custom pages to the config dialog parent and then connect to the applyClicked() and okClicked() signals or parent to react on config changes:

 connect(parent, SIGNAL(applyClicked()), this, SLOT(myConfigAccepted()));
 connect(parent, SIGNAL(okClicked()), this, SLOT(myConfigAccepted()));

With this approach it makes sense to store the custom pages in member variables to make their fields accessible from the myConfigAccepted() slot.

Use config() to store your configuration.

Parameters:

parent

the dialog which is the parent of the configuration widgets

QStringList customCategories ( self )

Returns:: the list of custom categories known to libplasma

Since:: 4.3

Plasma.DataEngine dataEngine	(	self,
		QString	name
	)

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 <em>not</em> 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

destroy ( self )

Destroys the applet; it will be removed nicely and deleted. Its configuration will also be deleted.

bool destroyed ( self )

Returns:: true if destroy() was called; useful for Applets which should avoid certain tasks if they are about to be deleted permanently

bool eventFilter	(	self,
		QObject	o,
		QEvent	e
	)

Internal:: event filter; used for focus watching

Plasma.Extender extender ( self )

Returns:: the extender of this applet.

flushPendingConstraintsEvents ( self )

Sends all pending contraints updates to the applet. Will usually be called automatically, but can also be called manually if needed.

focusInEvent	(	self,
		QFocusEvent	event
	)

Reimplemented from QGraphicsItem

QFont font ( self )

Returns:: the font currently set for this widget

Plasma.FormFactor formFactor ( self )

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

See also:: Plasma.FormFactor

KConfigGroup globalConfig ( self )

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.

KShortcut globalShortcut ( self )

Returns:: the global shortcut associated with this wiget, or an empty shortcut if no global shortcut is associated.

bool hasAuthorization	(	self,
		QString	constraint
	)

Returns true if the applet is allowed to perform functions covered by the given constraint eg. hasAuthorization("FileDialog") returns true if applets are allowed to show filedialogs.

Since:: 4.3

bool hasConfigurationInterface ( self )

Returns:: true if this plasmoid provides a GUI configuration

bool hasFailedToLaunch ( self )

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

bool hasValidAssociatedApplication ( self )

Returns:: true if the applet has a valid associated application or urls

Since:: 4.4

hoverEnterEvent	(	self,
		QGraphicsSceneHoverEvent	event
	)

Reimplemented from QGraphicsLayoutItem

hoverLeaveEvent	(	self,
		QGraphicsSceneHoverEvent	event
	)

Reimplemented from QGraphicsLayoutItem

QString icon ( self )

Returns the icon related to this applet

long id ( self )

Returns:: the id of this applet

Plasma.ImmutabilityType immutability ( self )

Returns:: The type of immutability of this applet

init ( self )

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.

Note: paintInterface may get called before init() depending on initialization order. Painting is managed by the canvas (QGraphisScene), and may schedule a paint event prior to init() being called.

initExtenderItem	(	self,
		Plasma.ExtenderItem	item
	)

Gets called when an extender item has to be initialized after a plasma restart. If you create ExtenderItems in your applet, you should implement this function to again create the widget that should be shown in this extender item. This function might look something like this:

 SuperCoolWidget *widget = new SuperCoolWidget();
 dataEngine("engine")->connectSource(item->config("dataSourceName"), widget);
 item->setWidget(widget);

You can also add one or more custom qactions to this extender item in this function.

Note that by default, not all ExtenderItems are persistent. Only items that are detached, will have their configuration stored when plasma exits.

bool isBusy ( self )

Returns:: true if the applet is busy and is showing an indicator widget for that

bool isContainment ( self )

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

bool isPopupShowing ( self )

Returns:: true is there is a popup assoiated with this Applet showing, such as the dialog of a PopupApplet. May be reimplemented for custom popup implementations.

bool isPublished ( self )

bool isRegisteredAsDragHandle	(	self,
		QGraphicsItem	item
	)

Parameters:

item

the item to look for if it is registered or not

Returns:: true if it is registered, false otherwise

bool isUserConfiguring ( self )

Returns:: true when the configuration interface is being shown

Since:: 4.5

QVariant itemChange	(	self,
		QGraphicsItem::GraphicsItemChange	change,
		QVariant	value
	)

Reimplemented from QGraphicsItem

Plasma.Location location ( self )

Returns the location of the scene which is displaying applet.

See also:: Plasma.Location

lower ( self )

Causes this applet to lower below all the other applets.

QRectF mapFromView	(	self,
		QGraphicsView	view,
		QRect	rect
	)

Maps a QRect from a view's coordinates to local coordinates.

Parameters:

	view	the view from which rect should be mapped
	rect	the rect to be mapped

QRect mapToView	(	self,
		QGraphicsView	view,
		QRectF	rect
	)

Maps a QRectF from local coordinates to a view's coordinates.

Parameters:

	view	the view to which rect should be mapped
	rect	the rect to be mapped

mouseMoveEvent	(	self,
		QGraphicsSceneMouseEvent	event
	)

Internal:: manage the mouse movement to drag the applet around

QString name ( self )

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

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

Plasma.Package package ( self )

Accessor for the associated Package object if any. Generally, only Plasmoids come in a Package.

Returns:: the Package object, or 0 if none

paintInterface	(	self,
		QPainter	painter,
		QStyleOptionGraphicsItem	option,
		QRect	contentsRect
	)

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

paintWindowFrame	(	self,
		QPainter	painter,
		QStyleOptionGraphicsItem	option,
		QWidget	widget
	)

QString pluginName ( self )

Returns the plugin name for the applet

QPoint popupPosition	(	self,
		QSize	s
	)

Since:: 4.4 Reccomended position for a popup window like a menu or a tooltip given its size

Parameters:

	s	size of the popup
	alignment	alignment of the popup, valid flags are Qt.AlignLeft, Qt.AlignRight and Qt.AlignCenter

Returns:: reccomended position

QPoint popupPosition	(	self,
		QSize	s,
		Qt::AlignmentFlag	alignment
	)

Since:: 4.4 Reccomended position for a popup window like a menu or a tooltip given its size

Parameters:

	s	size of the popup
	alignment	alignment of the popup, valid flags are Qt.AlignLeft, Qt.AlignRight and Qt.AlignCenter

Returns:: reccomended position

raise_ ( self )

Causes this applet to raise above all other applets.

registerAsDragHandle	(	self,
		QGraphicsItem	item
	)

Register the widgets that manage mouse clicks but you still want to be able to drag the applet around when holding the mouse pointer on that widget.

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

Parameters:

item

the item to watch for mouse move

removeAssociatedWidget	(	self,
		QWidget	widget
	)

un-associate actions from this widget, including ones added after this call. needed to make keyboard shortcuts work.

resizeEvent	(	self,
		QGraphicsSceneResizeEvent	event
	)

Reimplemented from QGraphicsItem

restore	(	self,
		KConfigGroup	group
	)

Restores state information about this applet saved previously in save(KConfigGroup&).

This method does not need to be reimplmented by Applet subclasses, but can be useful for Applet specializations (such as Containment) to do so.

runAssociatedApplication ( self )

Open the application associated to this applet, if it's not set but some urls are, open those urls with the proper application for their mimetype

See also:: setAssociatedApplication()

See also:: setAssociatedApplicationUrls()

Since:: 4.4

save	(	self,
		KConfigGroup	group
	)

Saves state information about this applet that will be accessed when next instantiated in the restore(KConfigGroup&) method.

This method does not need to be reimplmented by Applet subclasses, but can be useful for Applet specializations (such as Containment) to do so.

Applet subclasses may instead want to reimplement saveState().

saveState	(	self,
		KConfigGroup	config
	)

When called, the Applet should write any information needed as part of the Applet's running state to the configuration object in config() and/or globalConfig().

Applets that always sync their settings/state with the config objects when these settings/states change do not need to reimplement this method.

bool sceneEventFilter	(	self,
		QGraphicsItem	watched,
		QEvent	event
	)

Internal:: scene event filter; used to manage applet dragging

QRect screenRect ( self )

This method returns screen coordinates for the widget; this method can be somewhat expensive and should ONLY be called when screen coordinates are required. For example when positioning top level widgets on top of the view to create the appearance of unit. This should NOT be used for popups (@see popupPosition) or for normal widget use (use Plasma. widgets or QGraphicsProxyWidget instead).

Returns:: a rect of the applet in screen coordinates.

setAspectRatioMode	(	self,
		Plasma.AspectRatioMode	a0
	)

Sets the preferred aspect ratio mode for placement and resizing

setAssociatedApplication	(	self,
		QString	string
	)

Sets an application associated to this applet, that will be regarded as a full view of what is represented in the applet

Parameters:

string

the name of the application. it can be

a name understood by KService.serviceByDesktopName

(e.g. "konqueror")

a command in $PATH

or an absolute path to an executable

Since:: 4.4

setAssociatedApplicationUrls	(	self,
		KUrl.List	urls
	)

Sets a list of urls associated to this application, they will be used as parameters for the associated application

See also:: setAssociatedApplication()

Parameters:

urls

setBackgroundHints	(	self,
		Plasma.Applet.BackgroundHints	hints
	)

Sets the BackgroundHints for this applet

See also:: BackgroundHint

Parameters:

hints

the BackgroundHint combination for this applet

setBusy	(	self,
		bool	busy
	)

Shows a busy indicator that overlays the applet

Parameters:

busy

show or hide the busy indicator

setConfigurationRequired	(	self,
		bool	needsConfiguring,
		QString	reason=QString()
	)

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

Parameters:

	needsConfiguring	true if the applet needs to be configured, or false if it doesn't
	reason	a translated message for the user explaining that the applet needs configuring; this should note what needs to be configured

setCustomCategories	(	self,
		QStringList	categories
	)

Sets the list of custom categories that are used in addition to the default set of categories known to libplasma for Applets.

Parameters:

categories

a list of categories

Since:: 4.3

setFailedToLaunch	(	self,
		bool	failed,
		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

setGlobalShortcut	(	self,
		KShortcut	shortcut
	)

Sets the global shorcut to associate with this widget.

setHasConfigurationInterface	(	self,
		bool	hasInterface
	)

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 createConfigurationInterface()

Parameters:

hasInterface

whether or not there is a user interface available

setImmutability	(	self,
		Plasma.ImmutabilityType	immutable
	)

Sets the immutability type for this applet (not immutable, user immutable or system immutable)

Parameters:

immutable

the new immutability type of this applet

setStatus	(	self,
		Plasma.ItemStatus	stat
	)

sets the status for this applet

Since:: 4.4

QPainterPath shape ( self )

Reimplemented from QGraphicsItem

bool shouldConserveResources ( self )

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.

showConfigurationInterface ( self )

Actually show your custom configuration interface Use this only if you reimplemented showConfigurationInterface()

Parameters:

widget

the widget representing your configuration interface

Since:: 4.5

showConfigurationInterface	(	self,
		QWidget	widget
	)

Actually show your custom configuration interface Use this only if you reimplemented showConfigurationInterface()

Parameters:

widget

the widget representing your configuration interface

Since:: 4.5

showMessage	(	self,
		QIcon	icon,
		QString	message,
		Plasma.MessageButtons	buttons
	)

Shows a message as an overlay of the applet: the message has an icon, text and (optional) buttons

Parameters:

	icon	the icon that will be shown
	message	the message string that will be shown. If the message is empty nothng will be shown and if there was a message already it will be hidden
	buttons	an OR combination of all the buttons needed

See also:: Plasma.MessageButtons

See also:: messageButtonPressed

Since:: 4.3

QSizeF sizeHint	(	self,
		Qt::SizeHint	which,
		QSizeF	constraint=QSizeF()
	)

Reimplemented from QGraphicsLayoutItem

[QVariant] startupArguments ( self )

Returns:: the list of arguments which the applet was called with

Since:: KDE4.3

Plasma.ItemStatus status ( self )

Returns:: the status of the applet

Since:: 4.4

timerEvent	(	self,
		QTimerEvent	event
	)

Reimplemented from QObject

int type ( self )

Reimplemented from QGraphicsItem

unpublish ( self )

unregisterAsDragHandle	(	self,
		QGraphicsItem	item
	)

Unregister a widget registered with registerAsDragHandle.

Parameters:

item

the item to unregister

updateConstraints	(	self,
		Plasma.Constraints	constraints=Plasma.AllConstraints
	)

Called when any of the geometry constraints have been updated. This method calls constraintsEvent, which may be reimplemented, once the Applet has been prepared for updating the constraints.

Parameters:

constraints

the type of constraints that were updated

QGraphicsView view ( self )

Returns the view this widget is visible on, or 0 if none can be found.

Warning:: do NOT assume this will always return a view! a null view probably means that either plasma isn't finished loading, or your applet is on an activity that's not being shown anywhere.

Static Method Documentation

QString category	(	KPluginInfo	applet
	)

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

QString category	(	QString	appletName
	)

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

[KPluginInfo] listAppletInfo	(	QString	category=QString(),
		QString	parentApp=QString()
	)

Returns a list of all known applets. This may skip applets based on security settings and ExcludeCategories in the application's config.

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

[KPluginInfo] listAppletInfoForMimetype	(	QString	mimetype
	)

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

Returns:: list of applets

[KPluginInfo] listAppletInfoForUrl	(	QUrl	url
	)

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

Since:: 4.4

Returns:: list of applets

QStringList listCategories	(	QString	parentApp=QString(),
		bool	visibleOnly=1
	)

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

Plasma.Applet load	(	QString	name,
		long	appletId=0,
		[QVariant]	args=QVariantList()
	)

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
	appletId	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

Plasma.Applet load	(	KPluginInfo	info,
		long	appletId=0,
		[QVariant]	args=QVariantList()
	)

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
	appletId	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

Plasma.Applet loadPlasmoid	(	QString	path,
		long	appletId=0,
		[QVariant]	args=QVariantList()
	)

Attempts to load an applet from a package

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

Parameters:

	path	the path to the package
	appletId	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

Since:: 4.3

KSharedPtr packageStructure ( )

Returns:: a package structure representing an Applet

Enumeration Documentation

anonymous

Enumerator:

Type

BackgroundHint

Description on how draw a background for the applet

Enumerator:

NoBackground = 0
StandardBackground = 1
TranslucentBackground = 2
DefaultBackground = StandardBackground

Applet Class Reference

Detailed Description

Enumerations

Signals

Methods

Static Methods

Signal Documentation

Method Documentation

Static Method Documentation

Enumeration Documentation

Modules