Containment Class Reference

from PyKDE4.plasma import *

Inherits: Plasma.Applet → QGraphicsWidget → QObject
Namespace: Plasma

Detailed Description

Containment plasma/containment.h <Plasma/Containment>

The base class for plugins that provide backgrounds and applet grouping containers

Containment objects provide the means to group applets into functional sets. They also provide the following:

creation of focussing event - drawing of the background image (which can be interactive) - form factors (e.g. panel, desktop, full screen, etc) - applet layout management

Since containment is actually just a Plasma.Applet, all the techniques used for writing the visual presentation of Applets is applicable to Containtments. Containments are differentiated from Applets by being marked with the ServiceType of Plasma/Containment. Plugins registered with both the Applet and the Containment ServiceTypes can be loaded for us in either situation.

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

Enumerations
Type	{ NoContainmentType, DesktopContainment, PanelContainment, CustomContainment, CustomPanelContainment }
Signals
	addSiblingContainment (Plasma.Containment a0)
	appletAdded (Plasma.Applet applet, QPointF pos)
	appletRemoved (Plasma.Applet applet)
	configureRequested (Plasma.Containment containment)
	contextChanged (Plasma.Context context)
	focusRequested (Plasma.Containment containment)
	screenChanged (int wasScreen, int isScreen, Plasma.Containment containment)
	showAddWidgetsInterface (QPointF pos)
	toolBoxToggled ()
	toolBoxVisibilityChanged (bool a0)
	zoomRequested (Plasma.Containment containment, Plasma.ZoomDirection direction)
Methods
	__init__ (self, QGraphicsItem parent=0, QString serviceId=QString(), long containmentId=0)
	__init__ (self, QObject parent, QVariantList args)
QString	activity (self)
Plasma.Applet	addApplet (self, QString name, QVariantList args=QVariantList(), QRectF geometry=QRectF(-1,-1,-1,-1))
	addApplet (self, Plasma.Applet applet, QPointF pos=QPointF(-1,-1), bool dontInit=1)
	addAssociatedWidget (self, QWidget widget)
	addSiblingContainment (self, Plasma.Containment a0)
	addSiblingContainment (self)
	addToolBoxAction (self, QAction action)
	appletAdded (self, Plasma.Applet applet, QPointF pos)
	appletRemoved (self, Plasma.Applet applet)
Plasma.Applet.List	applets (self)
	clearApplets (self)
	closeToolBox (self)
	configureRequested (self, Plasma.Containment containment)
Plasma.Containment.Type	containmentType (self)
	contextChanged (self, Plasma.Context context)
	contextMenuEvent (self, QGraphicsSceneContextMenuEvent event)
Plasma.Corona	corona (self)
int	desktop (self)
	destroy (self)
	destroy (self, bool confirm)
	dragEnterEvent (self, QGraphicsSceneDragDropEvent event)
	dragMoveEvent (self, QGraphicsSceneDragDropEvent event)
bool	drawWallpaper (self)
	dropEvent (self, QGraphicsSceneDragDropEvent event)
	enableAction (self, QString name, bool enable)
	focusNextApplet (self)
	focusPreviousApplet (self)
	focusRequested (self, Plasma.Containment containment)
	hoverEnterEvent (self, QGraphicsSceneHoverEvent event)
	hoverLeaveEvent (self, QGraphicsSceneHoverEvent event)
	init (self)
QVariant	itemChange (self, QGraphicsItem.GraphicsItemChange change, QVariant value)
	keyPressEvent (self, QKeyEvent event)
	mouseMoveEvent (self, QGraphicsSceneMouseEvent event)
	mousePressEvent (self, QGraphicsSceneMouseEvent event)
	mouseReleaseEvent (self, QGraphicsSceneMouseEvent event)
	openToolBox (self)
	removeAssociatedWidget (self, QWidget widget)
	removeToolBoxAction (self, QAction action)
	resizeEvent (self, QGraphicsSceneResizeEvent event)
	restore (self, KConfigGroup group)
	restoreContents (self, KConfigGroup group)
	save (self, KConfigGroup group)
	saveContents (self, KConfigGroup group)
bool	sceneEventFilter (self, QGraphicsItem watched, QEvent event)
int	screen (self)
	screenChanged (self, int wasScreen, int isScreen, Plasma.Containment containment)
	setActivity (self, QString activity)
	setContainmentType (self, Plasma.Containment.Type type)
	setDrawWallpaper (self, bool drawWallpaper)
	setFormFactor (self, Plasma.FormFactor formFactor)
	setLocation (self, Plasma.Location location)
	setScreen (self, int screen, int desktop=-1)
	setToolBoxOpen (self, bool open)
	setWallpaper (self, QString pluginName, QString mode=QString())
	showAddWidgetsInterface (self, QPointF pos)
	showConfigurationInterface (self)
	showContextMenu (self, QPointF containmentPos, QPoint screenPos)
	showDropZone (self, QPoint pos)
QGraphicsItem	toolBoxItem (self)
	toolBoxToggled (self)
	toolBoxVisibilityChanged (self, bool a0)
Plasma.Wallpaper	wallpaper (self)
	wheelEvent (self, QGraphicsSceneWheelEvent event)
	zoomRequested (self, Plasma.Containment containment, Plasma.ZoomDirection direction)
Static Methods
QStringList	listContainmentTypes ()
KPluginInfo.List	listContainments (QString category=QString(), QString parentApp=QString())
KPluginInfo.List	listContainmentsForMimetype (QString mimetype)
KPluginInfo.List	listContainmentsOfType (QString type, QString category=QString(), QString parentApp=QString())

Method Documentation

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

Parameters:

	parent	the QGraphicsItem this applet is parented to
	serviceId	the name of the .desktop file containing the information about the widget
	containmentId	a unique id used to differentiate between multiple instances of the same Applet type

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

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

QString activity ( self )

Returns:: the current activity associated with this activity

Plasma.Applet addApplet	(	self,
		QString	name,
		QVariantList	args=QVariantList(),
		QRectF	geometry=QRectF(-1,-1,-1,-1)
	)

Adds an applet to this Containment

Parameters:

	name	the plugin name for the applet, as given by KPluginInfo.pluginName()
	args	argument list to pass to the plasmoid
	geometry	where to place the applet, or to auto-place it if an invalid is provided

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

addApplet	(	self,
		Plasma.Applet	applet,
		QPointF	pos=QPointF(-1,-1),
		bool	dontInit=1
	)

Add an existing applet to this Containment

If dontInit is true, the pending constraints are not flushed either. So it is your responsibility to call both init() and flushPendingConstraints() on the applet.

Parameters:

	applet	the applet that should be added
	pos	the containment-relative position
	dontInit	if true, init() will not be called on the applet

addAssociatedWidget	(	self,
		QWidget	widget
	)

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

addSiblingContainment	(	self,
		Plasma.Containment	a0
	)

Emitted when the containment wants a new containment to be created. Usually only used for desktop containments.

Signal syntax:: QObject.connect(source, SIGNAL("addSiblingContainment(Containment*)"), target_slot)

addSiblingContainment ( self )

Tells the corona to create a new desktop containment

addToolBoxAction	(	self,
		QAction	action
	)

Add an action to the toolbox

appletAdded	(	self,
		Plasma.Applet	applet,
		QPointF	pos
	)

This signal is emitted when a new applet is created by the containment

Signal syntax:: QObject.connect(source, SIGNAL("appletAdded(Applet*, const QPointF&)"), target_slot)

appletRemoved	(	self,
		Plasma.Applet	applet
	)

This signal is emitted when an applet is destroyed

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

Plasma.Applet.List applets ( self )

Returns:: the applets currently in this Containment

clearApplets ( self )

Removes all applets from this Containment

closeToolBox ( self )

Closes Containment's toolbox

configureRequested	(	self,
		Plasma.Containment	containment
	)

Emitted when the user wants to configure/change containment.

Signal syntax:: QObject.connect(source, SIGNAL("configureRequested(Containment*)"), target_slot)

Plasma.Containment.Type containmentType ( self )

Returns the type of containment

contextChanged	(	self,
		Plasma.Context	context
	)

The activity associated to this containemnt has changed

Signal syntax:: QObject.connect(source, SIGNAL("contextChanged(Context*)"), target_slot)

contextMenuEvent	(	self,
		QGraphicsSceneContextMenuEvent	event
	)

Plasma.Corona corona ( self )

Returns the Corona (if any) that this Containment is hosted by

int desktop ( self )

Returns:: the viewport (e.g. virtual desktop) this Containment is associated with.

destroy ( self )

Destroys this containment and all its applets (after a confirmation dialog); it will be removed nicely and deleted. Its configuration will also be deleted.

destroy	(	self,
		bool	confirm
	)

Destroys this containment and all its applets (after a confirmation dialog); it will be removed nicely and deleted. Its configuration will also be deleted.

@arg confirm whether or not confirmation from the user should be requested

dragEnterEvent	(	self,
		QGraphicsSceneDragDropEvent	event
	)

@sa QGraphicsItem.dragEnterEvent()

dragMoveEvent	(	self,
		QGraphicsSceneDragDropEvent	event
	)

@sa QGraphicsItem.dragMoveEvent()

bool drawWallpaper ( self )

Return whether wallpaper is painted or not.

dropEvent	(	self,
		QGraphicsSceneDragDropEvent	event
	)

@sa QGraphicsItem.dropEvent()

enableAction	(	self,
		QString	name,
		bool	enable
	)

convenience function - enables or disables an action by name

Parameters:

	name	the name of the action in our collection
	enable	true to enable, false to disable

focusNextApplet ( self )

switch keyboard focus to the next of our applets

focusPreviousApplet ( self )

switch keyboard focus to the previous one of our applets

focusRequested	(	self,
		Plasma.Containment	containment
	)

Signal syntax:: QObject.connect(source, SIGNAL("focusRequested(Containment*)"), target_slot)

hoverEnterEvent	(	self,
		QGraphicsSceneHoverEvent	event
	)

hoverLeaveEvent	(	self,
		QGraphicsSceneHoverEvent	event
	)

init ( self )

Reimplemented from Applet

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

keyPressEvent	(	self,
		QKeyEvent	event
	)

QStringList listContainmentTypes ( )

Returns:: a list of all known types of Containments on this system

KPluginInfo.List listContainments	(	QString	category=QString(),
		QString	parentApp=QString()
	)

Returns a list of all known containments.

Parameters:

	category	Only containments matching this category will be returned. Useful in conjunction with knownCategories. If "Miscelaneous" 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.List listContainmentsForMimetype	(	QString	mimetype
	)

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

Returns:: list of applets

KPluginInfo.List listContainmentsOfType	(	QString	type,
		QString	category=QString(),
		QString	parentApp=QString()
	)

Returns a list of all known Containments that match the parameters.

Parameters:

	type	Only Containments with this string in X-Plasma-ContainmentCategories in their .desktop files will be returned. Common values are panel and desktop
	category	Only applets matchin this category will be returned. Useful in conjunction with knownCategories. If "Miscelaneous" 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

mouseMoveEvent	(	self,
		QGraphicsSceneMouseEvent	event
	)

mousePressEvent	(	self,
		QGraphicsSceneMouseEvent	event
	)

mouseReleaseEvent	(	self,
		QGraphicsSceneMouseEvent	event
	)

openToolBox ( self )

Open the Containment's toolbox

removeAssociatedWidget	(	self,
		QWidget	widget
	)

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

removeToolBoxAction	(	self,
		QAction	action
	)

Remove an action from the toolbox

resizeEvent	(	self,
		QGraphicsSceneResizeEvent	event
	)

@sa QGraphicsItem.resizeEvent()

restore	(	self,
		KConfigGroup	group
	)

@sa Applet.restore(KConfigGroup &)

restoreContents	(	self,
		KConfigGroup	group
	)

Called when the contents of the containment should be loaded. By default this loads all previously saved Applets

Parameters:

group

the KConfigGroup to save settings under

save	(	self,
		KConfigGroup	group
	)

@sa Applet.save(KConfigGroup &)

saveContents	(	self,
		KConfigGroup	group
	)

Called when the contents of the containment should be saved. By default this saves all loaded Applets

Parameters:

group

the KConfigGroup to save settings under

bool sceneEventFilter	(	self,
		QGraphicsItem	watched,
		QEvent	event
	)

int screen ( self )

Returns:: the screen number this containment is serving as the desktop for or -1 if none

screenChanged	(	self,
		int	wasScreen,
		int	isScreen,
		Plasma.Containment	containment
	)

This signal indicates that a containment has been newly associated (or dissociated) with a physical screen.

Parameters:

	wasScreen	the screen it was associated with
	isScreen	the screen it is now associated with
	containment	the containment switching screens

Signal syntax:: QObject.connect(source, SIGNAL("screenChanged(int, int, Containment*)"), target_slot)

setActivity	(	self,
		QString	activity
	)

Sets the current activity by name

Parameters:

activity

the name of the activity; if it doesn't exist in the semantic store, it will be created.

setContainmentType	(	self,
		Plasma.Containment.Type	type
	)

Sets the type of this containment.

setDrawWallpaper	(	self,
		bool	drawWallpaper
	)

Sets whether wallpaper is painted or not.

setFormFactor	(	self,
		Plasma.FormFactor	formFactor
	)

Sets the form factor for this Containment. This may cause changes in both the arrangement of Applets as well as the display choices of individual Applets.

setLocation	(	self,
		Plasma.Location	location
	)

Informs the Corona as to what position it is in. This is informational only, as the Corona doesn't change it's actual location. This is, however, passed on to Applets that may be managed by this Corona.

Parameters:

location

the new location of this Corona

setScreen	(	self,
		int	screen,
		int	desktop=-1
	)

Sets the physical screen this Containment is associated with.

Parameters:

	screen	the screen number this containment is the desktop for, or -1 if it is not serving as the desktop for any screen
	desktop	the virtual desktop to also associate this this screen with

setToolBoxOpen	(	self,
		bool	open
	)

Sets the open or closed state of the Containment's toolbox

@arg open true to open the ToolBox, false to close it

setWallpaper	(	self,
		QString	pluginName,
		QString	mode=QString()
	)

Sets wallpaper plugin.

Parameters:

	pluginName	the name of the wallpaper to attempt to load
	mode	optional mode or the wallpaper plugin (e.g. "Slideshow"). These values are pugin specific and enumerated in the plugin's .desktop file.

showAddWidgetsInterface	(	self,
		QPointF	pos
	)

Emitted when the containment requests an add widgets dialog is shown. Usually only used for desktop containments.

Parameters:

pos

where in the containment this request was made from, or an invalid position (QPointF()) is not location specific

Signal syntax:: QObject.connect(source, SIGNAL("showAddWidgetsInterface(const QPointF&)"), target_slot)

showConfigurationInterface ( self )

@sa Applet.showConfigurationInterface()

showContextMenu	(	self,
		QPointF	containmentPos,
		QPoint	screenPos
	)

Shows the context menu for the containment directly, bypassing Applets altogether.

showDropZone	(	self,
		QPoint	pos
	)

Shows a visual clue for drag and drop The default implementation does nothing, reimplement in containments that need it

Parameters:

pos

point where to show the drop target; if an invalid point is passed in the drop zone should not be shown

QGraphicsItem toolBoxItem ( self )

Returns:: the toolbox associated with this containment, or a null pointer if none

toolBoxToggled ( self )

Emitted when the user clicks on the toolbox

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

toolBoxVisibilityChanged	(	self,
		bool	a0
	)

Emitted when the toolbox is hidden or shown

Since:: 4.3

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

Plasma.Wallpaper wallpaper ( self )

Return wallpaper plugin.

wheelEvent	(	self,
		QGraphicsSceneWheelEvent	event
	)

zoomRequested	(	self,
		Plasma.Containment	containment,
		Plasma.ZoomDirection	direction
	)

Emitted when the containment requests zooming in or out one step.

Signal syntax:: QObject.connect(source, SIGNAL("zoomRequested(Containment*, ZoomDirection)"), target_slot)

Enumeration Documentation

Type

Enumerator:

NoContainmentType = -1
DesktopContainment = 0
PanelContainment
CustomContainment = 127
CustomPanelContainment = 128

Containment Class Reference

Detailed Description

Enumerations

Signals

Methods

Static Methods

Method Documentation

Enumeration Documentation

Modules