KDE 4.6 PyKDE API Reference

- KDE's Python API

# 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)
| 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, [QVariant] args)
| __init__ (self, QString packagePath, long appletId, [QVariant] args)
QString | activity (self)
Plasma.Applet | addApplet (self, QString name, [QVariant] 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)
| addToolBoxAction (self, QAction action)
[Plasma.Applet] | applets (self)
| clearApplets (self)
| closeToolBox (self)
| configChanged (self)
QString | containmentActions (self, QString trigger)
KConfigGroup | containmentActionsConfig (self)
QStringList | containmentActionsTriggers (self)
Plasma.Containment.Type | containmentType (self)
Plasma.Context | context (self)
| contextMenuEvent (self, QGraphicsSceneContextMenuEvent event)
Plasma.Corona | corona (self)
int | desktop (self)
| destroy (self)
| destroy (self, bool confirm)
| dragEnterEvent (self, QGraphicsSceneDragDropEvent event)
| dragLeaveEvent (self, QGraphicsSceneDragDropEvent event)
| dragMoveEvent (self, QGraphicsSceneDragDropEvent event)
bool | drawWallpaper (self)
| dropEvent (self, QGraphicsSceneDragDropEvent event)
| enableAction (self, QString name, bool enable)
| focusNextApplet (self)
| focusPreviousApplet (self)
| init (self)
bool | isToolBoxOpen (self)
QVariant | itemChange (self, QGraphicsItem.GraphicsItemChange change, QVariant value)
| keyPressEvent (self, QKeyEvent event)
int | lastDesktop (self)
int | lastScreen (self)
| 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)
| setActivity (self, QString activity)
| setContainmentActions (self, QString trigger, QString pluginName)
| 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)
| setToolBox (self, Plasma.AbstractToolBox toolBox)
| setToolBoxOpen (self, bool open)
| setWallpaper (self, QString pluginName, QString mode=QString())
| showConfigurationInterface (self)
| showContextMenu (self, QPointF containmentPos, QPoint screenPos)
| showDropZone (self, QPoint pos)
Plasma.AbstractToolBox | toolBox (self)
QGraphicsItem | toolBoxItem (self)
Plasma.Wallpaper | wallpaper (self)
| wheelEvent (self, QGraphicsSceneWheelEvent event)

## Static Methods

QStringList | listContainmentTypes ()
[KPluginInfo] | listContainments (QString category=QString(), QString parentApp=QString())
[KPluginInfo] | listContainmentsForMimetype (QString mimetype)
[KPluginInfo] | listContainmentsOfType (QString type, QString category=QString(), QString parentApp=QString())

## Signal Documentation

addSiblingContainment | ( | Plasma.Containment | a0
| ) |  |  |

Tells the corona to create a new desktop containment

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

appletAdded | ( | 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(Plasma::Applet*, const QPointF&)"), target_slot)`

appletRemoved | ( | Plasma.Applet | applet
| ) |  |  |

This signal is emitted when an applet is destroyed

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

configureRequested | ( | Plasma.Containment | containment
| ) |  |  |

Emitted when the user wants to configure/change containment.

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

contextChanged | ( | Plasma.Context | context
| ) |  |  |

The context associated to this containment has changed

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

screenChanged | ( | 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, Plasma::Containment*)"), target_slot)`

showAddWidgetsInterface | ( | 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)`

toolBoxToggled | ( |  | ) |

Emitted when the user clicks on the toolbox

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

toolBoxVisibilityChanged | ( | bool | a0
| ) |  |  |

Emitted when the toolbox is hidden or shown

Since:
  4.3

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

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

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

Deprecated:

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

## 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,
|  | [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

QString activity | ( |  | self ) |

Returns:
  the current activity name associated with this containment

Plasma.Applet addApplet | ( | self, |
|  | QString | name,
|  | [QVariant] | args=QVariantList(),
|  | QRectF | geometry=QRectF(-1,-1,-1,-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

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

Tells the corona to create a new desktop containment

addToolBoxAction | ( | self, |
|  | QAction | action
| ) |  |  |

Add an action to the toolbox

[Plasma.Applet] applets | ( |  | self ) |

Returns:
  the applets currently in this Containment

clearApplets | ( |  | self ) |

Removes all applets from this Containment

closeToolBox | ( |  | self ) |

Closes Containment's toolbox

configChanged | ( |  | self ) |

Called when applet configuration values have changed. @sa Applet.configChanged()

QString containmentActions | ( | self, |
|  | QString | trigger
| ) |  |  |

Returns:
  the plugin name for the given trigger

Since:
  4.4

KConfigGroup containmentActionsConfig | ( |  | self ) |

Returns:
  the config group that containmentactions plugins go in

Since:
  4.6

QStringList containmentActionsTriggers | ( |  | self ) |

Returns:
  a list of all triggers that have a containmentactions plugin associated

Since:
  4.4

Plasma.Containment.Type containmentType | ( |  | self ) |

Returns the type of containment

Plasma.Context context | ( |  | self ) |

Returns:
  the context for this containment

Since:
  4.5

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.

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

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

dragLeaveEvent | ( | self, |
|  | QGraphicsSceneDragDropEvent | event
| ) |  |  |

@sa QGraphicsItem.dragLeaveEvent()

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

init | ( |  | self ) |

Reimplemented from Applet

bool isToolBoxOpen | ( |  | self ) |

Returns:
  true if the toolbox is open

Since:
  4.5

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

keyPressEvent | ( | self, |
|  | QKeyEvent | event
| ) |  |  |

int lastDesktop | ( |  | self ) |

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

Since:
  4.5

int lastScreen | ( |  | self ) |

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

Since:
  4.5

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

setActivity | ( | self, |
|  | QString | activity
| ) |  |  |

Sets the current activity by name

Parameters:

  | activity | the name of the activity

setContainmentActions | ( | self, |
|  | QString | trigger,
|  | 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

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

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

setToolBox | ( | self, |
|  | Plasma.AbstractToolBox | toolBox
| ) |  |  |

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

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.

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

Plasma.AbstractToolBox toolBox | ( |  | self ) |

Returns:
  the ToolBox

Since:
  4.4

QGraphicsItem toolBoxItem | ( |  | self ) |

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

Plasma.Wallpaper wallpaper | ( |  | self ) |

Return wallpaper plugin.

wheelEvent | ( | self, |
|  | QGraphicsSceneWheelEvent | event
| ) |  |  |

## Static Method Documentation

QStringList listContainmentTypes | ( |  | ) |

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

[KPluginInfo] 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 "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

[KPluginInfo] listContainmentsForMimetype | ( | QString | mimetype
| ) |  |  |

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

Returns:
  list of applets

[KPluginInfo] 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 "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

## Enumeration Documentation

Type

Enumerator:

  None = 0 |
  UnknownType = 1 |
  Directory = 2 |
  File = 4 |
  NetworkLocation = 8 |
  Executable = 16 |
  ShellCommand = 32 |
  Help = 64 |
  FileSystem = Directory|File|Executable|ShellCommand |