Plasma::Containment Class Reference

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

#include <Plasma/Containment>

Inheritance diagram for Plasma::Containment:

List of all members.

Classes
class	StyleOption
Public Types
enum	Type {   NoContainmentType = -1, DesktopContainment = 0, PanelContainment, CustomContainment = 127,   CustomPanelContainment = 128 }
Public Slots
void	addSiblingContainment ()
void	configChanged ()
void	destroy ()
void	destroy (bool confirm)
void	focusNextApplet ()
void	focusPreviousApplet ()
void	setFormFactor (Plasma::FormFactor formFactor)
void	setLocation (Plasma::Location location)
void	showConfigurationInterface ()
Signals
void	addSiblingContainment (Plasma::Containment *)
void	appletAdded (Plasma::Applet *applet, const QPointF &pos)
void	appletRemoved (Plasma::Applet *applet)
void	configureRequested (Plasma::Containment *containment)
void	contextChanged (Plasma::Context *context)
void	screenChanged (int wasScreen, int isScreen, Plasma::Containment *containment)
void	showAddWidgetsInterface (const QPointF &pos)
void	toolBoxToggled ()
void	toolBoxVisibilityChanged (bool)
void	zoomRequested (Plasma::Containment *containment, Plasma::ZoomDirection direction)
Public Member Functions
	Containment (QGraphicsItem *parent=0, const QString &serviceId=QString(), uint containmentId=0)
	Containment (QObject *parent, const QVariantList &args)
	~Containment ()
QString	activity () const
void	addApplet (Applet *applet, const QPointF &pos=QPointF(-1,-1), bool dontInit=true)
Applet *	addApplet (const QString &name, const QVariantList &args=QVariantList(), const QRectF &geometry=QRectF(-1,-1,-1,-1))
void	addAssociatedWidget (QWidget *widget)
void	addToolBoxAction (QAction *action)
Applet::List	applets () const
void	clearApplets ()
void	closeToolBox ()
QString	containmentActions (const QString &trigger)
KConfigGroup	containmentActionsConfig ()
QStringList	containmentActionsTriggers ()
Type	containmentType () const
Context *	context () const
Corona *	corona () const
int	desktop () const
bool	drawWallpaper ()
void	enableAction (const QString &name, bool enable)
void	init ()
bool	isToolBoxOpen () const
int	lastDesktop () const
int	lastScreen () const
void	openToolBox ()
void	removeAssociatedWidget (QWidget *widget)
void	removeToolBoxAction (QAction *action)
void	restore (KConfigGroup &group)
void	save (KConfigGroup &group) const
int	screen () const
void	setActivity (const QString &activity)
void	setContainmentActions (const QString &trigger, const QString &pluginName)
void	setScreen (int screen, int desktop=-1)
void	setToolBoxOpen (bool open)
void	setWallpaper (const QString &pluginName, const QString &mode=QString())
void	showContextMenu (const QPointF &containmentPos, const QPoint &screenPos)
virtual void	showDropZone (const QPoint pos)
Plasma::Wallpaper *	wallpaper () const
Static Public Member Functions
static KPluginInfo::List	listContainments (const QString &category=QString(), const QString &parentApp=QString())
static KPluginInfo::List	listContainmentsForMimetype (const QString &mimetype)
static KPluginInfo::List	listContainmentsOfType (const QString &type, const QString &category=QString(), const QString &parentApp=QString())
static QStringList	listContainmentTypes ()
Protected Member Functions
void	contextMenuEvent (QGraphicsSceneContextMenuEvent *event)
void	dragEnterEvent (QGraphicsSceneDragDropEvent *event)
void	dragLeaveEvent (QGraphicsSceneDragDropEvent *event)
void	dragMoveEvent (QGraphicsSceneDragDropEvent *event)
void	dropEvent (QGraphicsSceneDragDropEvent *event)
QVariant	itemChange (GraphicsItemChange change, const QVariant &value)
void	keyPressEvent (QKeyEvent *event)
void	mouseMoveEvent (QGraphicsSceneMouseEvent *event)
void	mousePressEvent (QGraphicsSceneMouseEvent *event)
void	mouseReleaseEvent (QGraphicsSceneMouseEvent *event)
void	resizeEvent (QGraphicsSceneResizeEvent *event)
virtual void	restoreContents (KConfigGroup &group)
virtual void	saveContents (KConfigGroup &group) const
bool	sceneEventFilter (QGraphicsItem *watched, QEvent *event)
void	setContainmentType (Containment::Type type)
void	setDrawWallpaper (bool drawWallpaper)
void	setToolBox (AbstractToolBox *toolBox)
AbstractToolBox *	toolBox () const
const QGraphicsItem *	toolBoxItem () const
void	wheelEvent (QGraphicsSceneWheelEvent *event)

---

Detailed Description

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.

Definition at line 72 of file containment.h.

---

Member Enumeration Documentation

enum Plasma::Containment::Type

Enumerator:

NoContainmentType
DesktopContainment	A desktop containment.
PanelContainment	A desktop panel.
CustomContainment	A containment that is neither a desktop nor a panel but something application specific.
CustomPanelContainment	A customized desktop panel.

Reimplemented from Plasma::Applet.

Definition at line 99 of file containment.h.

---

Constructor & Destructor Documentation

Plasma::Containment::Containment	(	QGraphicsItem *	parent = 0,
		const QString &	serviceId = QString(),
		uint	containmentId = 0
	)		[explicit]

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

Definition at line 115 of file containment.cpp.

Plasma::Containment::Containment	(	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.

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

Definition at line 129 of file containment.cpp.

Plasma::Containment::~Containment

(

)

Definition at line 151 of file containment.cpp.

---

Member Function Documentation

QString Plasma::Containment::activity

(

)

const

Returns:

the current activity name associated with this containment

Definition at line 2023 of file containment.cpp.

Applet * Plasma::Containment::addApplet	(	const QString &	name,
		const QVariantList &	args = QVariantList(),
		const 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

Definition at line 851 of file containment.cpp.

void Plasma::Containment::addApplet	(	Applet *	applet,
		const QPointF &	pos = QPointF(-1, -1),
		bool	dontInit = true
	)

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

Definition at line 857 of file containment.cpp.

void Plasma::Containment::addAssociatedWidget

(

QWidget *

widget

)

[virtual]

associate actions with this widget, including ones added after this call.

needed to make keyboard shortcuts work.

Reimplemented from Plasma::Applet.

Definition at line 1818 of file containment.cpp.

void Plasma::Containment::addSiblingContainment

(

Plasma::Containment *

)

[signal]

Emitted when the containment wants a new containment to be created.

Usually only used for desktop containments.

void Plasma::Containment::addSiblingContainment

(

)

[slot]

Tells the corona to create a new desktop containment.

Definition at line 837 of file containment.cpp.

void Plasma::Containment::addToolBoxAction

(

QAction *

action

)

Add an action to the toolbox.

Definition at line 1773 of file containment.cpp.

void Plasma::Containment::appletAdded	(	Plasma::Applet *	applet,
		const QPointF &	pos
	)		[signal]

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

void Plasma::Containment::appletRemoved

(

Plasma::Applet *

applet

)

[signal]

This signal is emitted when an applet is destroyed.

Applet::List Plasma::Containment::applets

(

)

const

Returns:

the applets currently in this Containment

Definition at line 959 of file containment.cpp.

void Plasma::Containment::clearApplets

(

)

Removes all applets from this Containment.

Definition at line 842 of file containment.cpp.

void Plasma::Containment::closeToolBox

(

)

Closes Containment's toolbox.

Definition at line 1810 of file containment.cpp.

void Plasma::Containment::configChanged

(

)

[virtual, slot]

Called when applet configuration values have changed.

Reimplemented from superclass.

See also:

Applet::configChanged()

Reimplemented from Plasma::Applet.

Definition at line 2113 of file containment.cpp.

void Plasma::Containment::configureRequested

(

Plasma::Containment *

containment

)

[signal]

Emitted when the user wants to configure/change containment.

QString Plasma::Containment::containmentActions

(

const QString &

trigger

)

Returns:

the plugin name for the given trigger

Since:

4.4

Definition at line 1982 of file containment.cpp.

KConfigGroup Plasma::Containment::containmentActionsConfig

(

)

Returns:

the config group that containmentactions plugins go in

Since:

4.6

Definition at line 2523 of file containment.cpp.

QStringList Plasma::Containment::containmentActionsTriggers

(

)

Returns:

a list of all triggers that have a containmentactions plugin associated

Since:

4.4

Definition at line 1977 of file containment.cpp.

Containment::Type Plasma::Containment::containmentType

(

)

const

Returns the type of containment.

Definition at line 509 of file containment.cpp.

Context * Plasma::Containment::context

(

)

const

Returns:

the context for this containment

Since:

4.5

Reimplemented from Plasma::Applet.

Definition at line 2028 of file containment.cpp.

void Plasma::Containment::contextChanged

(

Plasma::Context *

context

)

[signal]

The context associated to this containment has changed.

void Plasma::Containment::contextMenuEvent

(

QGraphicsSceneContextMenuEvent *

event

)

[protected]

Definition at line 623 of file containment.cpp.

Corona * Plasma::Containment::corona

(

)

const

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

Definition at line 533 of file containment.cpp.

int Plasma::Containment::desktop

(

)

const

Returns:

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

Definition at line 1080 of file containment.cpp.

void Plasma::Containment::destroy

(

)

[virtual, slot]

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

Its configuration will also be deleted.

Reimplemented from Plasma::Applet.

Definition at line 2103 of file containment.cpp.

void Plasma::Containment::destroy

(

bool

confirm

)

[slot]

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

Its configuration will also be deleted.

• confirm whether or not confirmation from the user should be requested

Definition at line 2150 of file containment.cpp.

void Plasma::Containment::dragEnterEvent

(

QGraphicsSceneDragDropEvent *

event

)

[protected]

Reimplemented from superclass.

See also:

QGraphicsItem::dragEnterEvent()

Definition at line 1156 of file containment.cpp.

void Plasma::Containment::dragLeaveEvent

(

QGraphicsSceneDragDropEvent *

event

)

[protected]

Reimplemented from superclass.

See also:

QGraphicsItem::dragLeaveEvent()

Definition at line 1204 of file containment.cpp.

void Plasma::Containment::dragMoveEvent

(

QGraphicsSceneDragDropEvent *

event

)

[protected]

Reimplemented from superclass.

See also:

QGraphicsItem::dragMoveEvent()

Definition at line 1225 of file containment.cpp.

bool Plasma::Containment::drawWallpaper

(

)

Return whether wallpaper is painted or not.

Definition at line 1860 of file containment.cpp.

void Plasma::Containment::dropEvent

(

QGraphicsSceneDragDropEvent *

event

)

[protected]

Reimplemented from superclass.

See also:

QGraphicsItem::dropEvent()

Definition at line 1239 of file containment.cpp.

void Plasma::Containment::enableAction	(	const 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

Definition at line 1764 of file containment.cpp.

void Plasma::Containment::focusNextApplet

(

)

[slot]

switch keyboard focus to the next of our applets

Definition at line 2077 of file containment.cpp.

void Plasma::Containment::focusPreviousApplet

(

)

[slot]

switch keyboard focus to the previous one of our applets

Definition at line 2090 of file containment.cpp.

void Plasma::Containment::init

(

)

[virtual]

Reimplemented from Applet.

Reimplemented from Plasma::Applet.

Definition at line 159 of file containment.cpp.

bool Plasma::Containment::isToolBoxOpen

(

)

const

Returns:

true if the toolbox is open

Since:

4.5

Definition at line 1797 of file containment.cpp.

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

Reimplemented from QGraphicsItem.

Reimplemented from Plasma::Applet.

Definition at line 1741 of file containment.cpp.

void Plasma::Containment::keyPressEvent

(

QKeyEvent *

event

)

[protected]

Definition at line 1649 of file containment.cpp.

int Plasma::Containment::lastDesktop

(

)

const

Returns:

the viewport (e.g. virtual desktop) this Containment was associated with last time it had a screen

Since:

4.5

Definition at line 1085 of file containment.cpp.

int Plasma::Containment::lastScreen

(

)

const

Returns:

the last screen number this containment had only returns -1 if it's never ever been on a screen

Since:

4.5

Definition at line 1075 of file containment.cpp.

KPluginInfo::List Plasma::Containment::listContainments	(	const QString &	category = QString(),
		const QString &	parentApp = QString()
	)		[static]

Returns a list of all known containments.

Parameters:

category	Only containments matching this category will be returned. Useful in conjunction with knownCategories. If "Miscellaneous" 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 1090 of file containment.cpp.

KPluginInfo::List Plasma::Containment::listContainmentsForMimetype

(

const QString &

mimetype

)

[static]

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

Returns:

list of applets

Definition at line 1133 of file containment.cpp.

KPluginInfo::List Plasma::Containment::listContainmentsOfType	(	const QString &	type,
		const QString &	category = QString(),
		const QString &	parentApp = QString()
	)		[static]

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 "Miscellaneous" 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 1097 of file containment.cpp.

QStringList Plasma::Containment::listContainmentTypes

(

)

[static]

Returns:

a list of all known types of Containments on this system

Definition at line 1141 of file containment.cpp.

void Plasma::Containment::mouseMoveEvent

(

QGraphicsSceneMouseEvent *

event

)

[protected]

manage the mouse movement to drag the applet around

Reimplemented from Plasma::Applet.

Definition at line 538 of file containment.cpp.

void Plasma::Containment::mousePressEvent

(

QGraphicsSceneMouseEvent *

event

)

[protected]

Definition at line 554 of file containment.cpp.

void Plasma::Containment::mouseReleaseEvent

(

QGraphicsSceneMouseEvent *

event

)

[protected]

Definition at line 582 of file containment.cpp.

void Plasma::Containment::openToolBox

(

)

Open the Containment's toolbox.

Definition at line 1802 of file containment.cpp.

void Plasma::Containment::removeAssociatedWidget

(

QWidget *

widget

)

[virtual]

un-associate actions from this widget, including ones added after this call.

needed to make keyboard shortcuts work.

Reimplemented from Plasma::Applet.

Definition at line 1832 of file containment.cpp.

void Plasma::Containment::removeToolBoxAction

(

QAction *

action

)

Remove an action from the toolbox.

Definition at line 1781 of file containment.cpp.

void Plasma::Containment::resizeEvent

(

QGraphicsSceneResizeEvent *

event

)

[protected]

Reimplemented from superclass.

See also:

QGraphicsItem::resizeEvent()

Reimplemented from Plasma::Applet.

Definition at line 1632 of file containment.cpp.

void Plasma::Containment::restore

(

KConfigGroup &

group

)

[virtual]

Reimplemented from superclass.

See also:

Applet::restore(KConfigGroup &)

Reimplemented from Plasma::Applet.

Definition at line 301 of file containment.cpp.

void Plasma::Containment::restoreContents

(

KConfigGroup &

group

)

[protected, virtual]

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

Definition at line 481 of file containment.cpp.

void Plasma::Containment::save

(

KConfigGroup &

group

)

const [virtual]

Reimplemented from superclass.

See also:

Applet::save(KConfigGroup &)

Reimplemented from Plasma::Applet.

Definition at line 410 of file containment.cpp.

void Plasma::Containment::saveContents

(

KConfigGroup &

group

)

const [protected, virtual]

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

Definition at line 455 of file containment.cpp.

bool Plasma::Containment::sceneEventFilter	(	QGraphicsItem *	watched,
		QEvent *	event
	)		[protected]

scene event filter; used to manage applet dragging

Reimplemented from Plasma::Applet.

Definition at line 1691 of file containment.cpp.

int Plasma::Containment::screen

(

)

const

Returns:

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

Definition at line 1070 of file containment.cpp.

void Plasma::Containment::screenChanged	(	int	wasScreen,
		int	isScreen,
		Plasma::Containment *	containment
	)		[signal]

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

void Plasma::Containment::setActivity

(

const QString &

activity

)

Sets the current activity by name.

Parameters:

activity

the name of the activity

Definition at line 1988 of file containment.cpp.

void Plasma::Containment::setContainmentActions	(	const QString &	trigger,
		const QString &	pluginName
	)

Sets a containmentactions plugin.

Parameters:

trigger	the mouse button (and optional modifier) to associate the plugin with
pluginName	the name of the plugin to attempt to load. blank = set no plugin.

Since:

4.4

Definition at line 1932 of file containment.cpp.

void Plasma::Containment::setContainmentType

(

Containment::Type

type

)

[protected]

Sets the type of this containment.

Definition at line 514 of file containment.cpp.

void Plasma::Containment::setDrawWallpaper

(

bool

drawWallpaper

)

[protected]

Sets whether wallpaper is painted or not.

Definition at line 1846 of file containment.cpp.

void Plasma::Containment::setFormFactor

(

Plasma::FormFactor

formFactor

)

[slot]

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.

Definition at line 776 of file containment.cpp.

void Plasma::Containment::setLocation

(

Plasma::Location

location

)

[slot]

Informs the Corona as to what position it is in.

This is informational only, as the Corona doesn't change its actual location. This is, however, passed on to Applets that may be managed by this Corona.

Parameters:

location

the new location of this Corona

Definition at line 800 of file containment.cpp.

void Plasma::Containment::setScreen	(	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

Definition at line 964 of file containment.cpp.

void Plasma::Containment::setToolBox

(

AbstractToolBox *

toolBox

)

[protected]

Sets a custom ToolBox if there was an old one it will be deleted and the new one won't have any actions in it.

Parameters:

item	the new toolbox item

Since:

4.4

Definition at line 1619 of file containment.cpp.

void Plasma::Containment::setToolBoxOpen

(

bool

open

)

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

• open true to open the ToolBox, false to close it

Definition at line 1788 of file containment.cpp.

void Plasma::Containment::setWallpaper	(	const QString &	pluginName,
		const 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.

Definition at line 1865 of file containment.cpp.

void Plasma::Containment::showAddWidgetsInterface

(

const QPointF &

pos

)

[signal]

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

void Plasma::Containment::showConfigurationInterface

(

)

[virtual, slot]

Reimplemented from superclass.

See also:

Applet::showConfigurationInterface()

Reimplemented from Plasma::Applet.

Definition at line 2108 of file containment.cpp.

void Plasma::Containment::showContextMenu	(	const QPointF &	containmentPos,
		const QPoint &	screenPos
	)

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

Definition at line 611 of file containment.cpp.

void Plasma::Containment::showDropZone

(

const QPoint

pos

)

[virtual]

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

Definition at line 605 of file containment.cpp.

AbstractToolBox * Plasma::Containment::toolBox

(

)

const [protected]

Returns:

the ToolBox

Since:

4.4

Definition at line 1627 of file containment.cpp.

const QGraphicsItem * Plasma::Containment::toolBoxItem

(

)

const [protected]

Returns:

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

Definition at line 1613 of file containment.cpp.

void Plasma::Containment::toolBoxToggled

(

)

[signal]

Emitted when the user clicks on the toolbox.

void Plasma::Containment::toolBoxVisibilityChanged

(

bool

)

[signal]

Emitted when the toolbox is hidden or shown.

Since:

4.3

Plasma::Wallpaper * Plasma::Containment::wallpaper

(

)

const

Return wallpaper plugin.

Definition at line 1927 of file containment.cpp.

void Plasma::Containment::wheelEvent

(

QGraphicsSceneWheelEvent *

event

)

[protected]

Definition at line 1661 of file containment.cpp.

void Plasma::Containment::zoomRequested	(	Plasma::Containment *	containment,
		Plasma::ZoomDirection	direction
	)		[signal]

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

Deprecated:

---

The documentation for this class was generated from the following files:

• containment.h
• containment.cpp