KDE 4.7 PyKDE API Reference

- KDE's Python API

# Corona Class Reference

`from PyKDE4.plasma import *`

Inherits: QGraphicsScene → QObject
Namespace: Plasma

## Detailed Description

Corona plasma/corona.h <Plasma/Corona>

A QGraphicsScene for Plasma.Applets

## Signals

| availableScreenRegionChanged ()
| configSynced ()
| containmentAdded (Plasma.Containment containment)
| immutabilityChanged (Plasma.ImmutabilityType immutability)
| releaseVisualFocus ()
| screenOwnerChanged (int wasScreen, int isScreen, Plasma.Containment containment)
| shortcutsChanged ()

## Methods

| __init__ (self, QObject parent=0)
QAction | action (self, QString name)
[QAction] | actions (self)
| addAction (self, QString name, QAction action)
KAction | addAction (self, QString name)
Plasma.Containment | addContainment (self, QString name, [QVariant] args=QVariantList())
Plasma.Containment | addContainmentDelayed (self, QString name, [QVariant] args=QVariantList())
| addOffscreenWidget (self, QGraphicsWidget widget)
| addShortcuts (self, KActionCollection newShortcuts)
QString | appletMimeType (self)
QRegion | availableScreenRegion (self, int id)
| clearContainments (self)
KSharedPtr<KSharedConfig> | config (self)
Plasma.ContainmentActionsPluginsConfig | containmentActionsDefaults (self, Plasma.Containment.Type containmentType)
Plasma.Containment | containmentForScreen (self, int screen, int desktop=-1)
Plasma.Containment | containmentForScreen (self, int screen, int desktop, QString defaultPluginIfNonExistent, [QVariant] defaultArgs=QVariantList())
[Plasma.Containment] | containments (self)
QString | defaultContainmentPlugin (self)
Plasma.AbstractDialogManager | dialogManager (self)
| dragEnterEvent (self, QGraphicsSceneDragDropEvent event)
| dragLeaveEvent (self, QGraphicsSceneDragDropEvent event)
| dragMoveEvent (self, QGraphicsSceneDragDropEvent event)
| enableAction (self, QString name, bool enable)
| exportLayout (self, KConfigGroup config, [Plasma.Containment] containments)
[Plasma.Location] | freeEdges (self, int screen)
Plasma.ImmutabilityType | immutability (self)
[Plasma.Containment] | importLayout (self, KConfigBase config)
[Plasma.Containment] | importLayout (self, KConfigGroup config)
| initializeLayout (self, QString config=QString())
| layoutContainments (self)
| loadDefaultLayout (self)
| loadLayout (self, QString config=QString())
| mapAnimation (self, Plasma.Animator.Animation from, Plasma.Animator.Animation to)
| mapAnimation (self, Plasma.Animator.Animation from, QString to)
int | numScreens (self)
[QGraphicsWidget] | offscreenWidgets (self)
QPoint | popupPosition (self, QGraphicsItem item, QSize size)
QPoint | popupPosition (self, QGraphicsItem item, QSize size, Qt::AlignmentFlag alignment)
QString | preferredToolBoxPlugin (self, Plasma.Containment.Type type)
| removeOffscreenWidget (self, QGraphicsWidget widget)
| requestConfigSync (self)
| requireConfigSync (self)
| saveLayout (self, QString config=QString())
QRect | screenGeometry (self, int id)
| setAppletMimeType (self, QString mimetype)
| setContainmentActionsDefaults (self, Plasma.Containment.Type containmentType, Plasma.ContainmentActionsPluginsConfig config)
| setDefaultContainmentPlugin (self, QString name)
| setDialogManager (self, Plasma.AbstractDialogManager manager)
| setImmutability (self, Plasma.ImmutabilityType immutable)
| setPreferredToolBoxPlugin (self, Plasma.Containment.Type type, QString plugin)
| updateShortcuts (self)

## Signal Documentation

availableScreenRegionChanged | ( |  | ) |

This signal inicates that a change in available screen goemetry occurred.

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

configSynced | ( |  | ) |

This signal indicates that the configuration file was flushed to disc.

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

containmentAdded | ( | Plasma.Containment | containment
| ) |  |  |

This signal indicates a new containment has been added to the Corona

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

immutabilityChanged | ( | Plasma.ImmutabilityType | immutability
| ) |  |  |

emitted when immutability changes. this is for use by things that don't get contraints events, like plasmaapp. it's NOT for containments or applets or any of the other stuff on the scene. if your code's not in shells/ it probably shouldn't be using it.

Signal syntax:
  `QObject.connect(source, SIGNAL("immutabilityChanged(Plasma::ImmutabilityType)"), 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 hides when such an event is triggered by an item it is displaying.

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

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

shortcutsChanged | ( |  | ) |

Since:
  4.3 emitted when the user changes keyboard shortcut settings connect to this if you've put some extra shortcuts in your app that are NOT in corona's actioncollection. if your code's not in shells/ it probably shouldn't be using this function.

See also:
  addShortcuts

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

## Method Documentation

__init__ | ( | self, |
|  | QObject | parent=0
| ) |  |  |

QAction action | ( | self, |
|  | QString | name
| ) |  |  |

Returns the QAction with the given name from our collection

[QAction] actions | ( |  | self ) |

Returns all the actions in our collection

addAction | ( | self, |
|  | QString | name,
|  | QAction | action
| ) |  |  |

Since:
  4.3 Creates an action in our collection under the given name

Returns:
  the new action FIXME I'm wrapping so much of kactioncollection API now, maybe I should just expose the collection itself :P

KAction addAction | ( | self, |
|  | QString | name
| ) |  |  |

Since:
  4.3 Creates an action in our collection under the given name

Returns:
  the new action FIXME I'm wrapping so much of kactioncollection API now, maybe I should just expose the collection itself :P

Plasma.Containment addContainment | ( | self, |
|  | QString | name,
|  | [QVariant] | args=QVariantList()
| ) |  |  |

Adds a Containment to the Corona

Parameters:

  | name | the plugin name for the containment, as given by KPluginInfo.pluginName(). If an empty string is passed in, the default containment plugin will be used (usually DesktopContainment). If the string literal "null" is passed in, then no plugin will be loaded and a simple Containment object will be created instead.
  | args | argument list to pass to the containment

Returns:
  a pointer to the containment on success, or 0 on failure. Failure can be caused by too restrictive of an Immutability type, as containments cannot be added when widgets are locked, or if the requested containment plugin can not be located or successfully loaded.

Plasma.Containment addContainmentDelayed | ( | self, |
|  | QString | name,
|  | [QVariant] | args=QVariantList()
| ) |  |  |

Loads a containment with delayed initialization, primarily useful for implementations of loadDefaultLayout. The caller is responsible for all initializating, saving and notification of a new containment.

Parameters:

  | name | the plugin name for the containment, as given by KPluginInfo.pluginName(). If an empty string is passed in, the defalt containment plugin will be used (usually DesktopContainment). If the string literal "null" is passed in, then no plugin will be loaded and a simple Containment object will be created instead.
  | args | argument list to pass to the containment

Returns:
  a pointer to the containment on success, or 0 on failure. Failure can be caused by the Immutability type being too restrictive, as containments can't be added when widgets are locked, or if the requested containment plugin can not be located or successfully loaded.

See also:
  addContainment

addOffscreenWidget | ( | self, |
|  | QGraphicsWidget | widget
| ) |  |  |

Adds a widget in the topleft quadrant in the scene. Widgets in the topleft quadrant are normally never shown unless you specifically aim a view at it, which makes it ideal for toplevel views etc.

Parameters:

  | widget | the widget to add.

addShortcuts | ( | self, |
|  | KActionCollection | newShortcuts
| ) |  |  |

Since:
  4.3 Adds a set of actions to the shortcut config dialog. don't use this on actions in the corona's own actioncollection, those are handled automatically. this is for stuff outside of that.

QString appletMimeType | ( |  | self ) |

The current mime type of Drag/Drop items.

QRegion availableScreenRegion | ( | self, |
|  | int | id
| ) |  |  |

Returns the available region for a given screen. The available region excludes panels and similar windows. Valid screen ids are 0 to numScreens()-1. By default this method returns a rectangular region equal to screenGeometry(id); subclasses that need another behavior should override this method.

clearContainments | ( |  | self ) |

Clear the Corona from all applets.

KSharedPtr<KSharedConfig> config | ( |  | self ) |

Returns the config file used to store the configuration for this Corona

Plasma.ContainmentActionsPluginsConfig containmentActionsDefaults | ( | self, |
|  | Plasma.Containment.Type | containmentType
| ) |  |  |

Since:
  4.4 Returns the default containmentactions plugins for the given containment type

Plasma.Containment containmentForScreen | ( | self, |
|  | int | screen,
|  | int | desktop=-1
| ) |  |  |

Returns the Containment for a given physical screen and desktop, creating one if none exists

Parameters:

  | screen | number of the physical screen to locate
  | desktop | the virtual desktop) to locate; if < 0 then it will simply return the first Containment associated with screen
  | defaultPluginIfNonExistent | the plugin to load by default; "null" is an empty Containment and "default" creates the default plugin
  | defaultArgs | optional arguments to pass in when creating a Containment if needed

Since:
  4.6

Plasma.Containment containmentForScreen | ( | self, |
|  | int | screen,
|  | int | desktop,
|  | QString | defaultPluginIfNonExistent,
|  | [QVariant] | defaultArgs=QVariantList()
| ) |  |  |

Returns the Containment for a given physical screen and desktop, creating one if none exists

Parameters:

  | screen | number of the physical screen to locate
  | desktop | the virtual desktop) to locate; if < 0 then it will simply return the first Containment associated with screen
  | defaultPluginIfNonExistent | the plugin to load by default; "null" is an empty Containment and "default" creates the default plugin
  | defaultArgs | optional arguments to pass in when creating a Containment if needed

Since:
  4.6

[Plasma.Containment] containments | ( |  | self ) |

Returns:
  all containments on this Corona

QString defaultContainmentPlugin | ( |  | self ) |

Returns:
  the default containment plugin type

Since:
  4.7

Plasma.AbstractDialogManager dialogManager | ( |  | self ) |

Returns:
  the AbstractDialogManager that will show dialogs used by applets, like configuration dialogs

Since:
  4.5

dragEnterEvent | ( | self, |
|  | QGraphicsSceneDragDropEvent | event
| ) |  |  |

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

dragMoveEvent | ( | self, |
|  | QGraphicsSceneDragDropEvent | event
| ) |  |  |

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

exportLayout | ( | self, |
|  | KConfigGroup | config,
|  | [Plasma.Containment] | containments
| ) |  |  |

Exports a set of containments to a config file.

Parameters:

  | config | the config group to save to
  | containments | the list of containments to save

Since:
  4.6

[Plasma.Location] freeEdges | ( | self, |
|  | int | screen
| ) |  |  |

This method is useful in order to retrieve the list of available screen edges for panel type containments.

Parameters:

  | screen | the id of the screen to look for free edges.

Returns:
  a list of free edges not filled with panel type containments.

Plasma.ImmutabilityType immutability | ( |  | self ) |

Returns:
  The type of immutability of this Corona

[Plasma.Containment] importLayout | ( | self, |
|  | KConfigBase | config
| ) |  |  |

Imports an applet layout from a config file. The results will be added to the current set of Containments.

Parameters:

  | config | the name of the config file to load from, or the default config file if QString()

Returns:
  the list of containments that were loaded

Since:
  4.6

[Plasma.Containment] importLayout | ( | self, |
|  | KConfigGroup | config
| ) |  |  |

Imports an applet layout from a config file. The results will be added to the current set of Containments.

Parameters:

  | config | the name of the config file to load from, or the default config file if QString()

Returns:
  the list of containments that were loaded

Since:
  4.6

initializeLayout | ( | self, |
|  | QString | config=QString()
| ) |  |  |

Initializes the layout from a config file. This will first clear any existing Containments, load a layout from the requested configuration file, request the default layout if needed and update immutability.

Parameters:

  | config | the name of the config file to load from, or the default config file if QString()

layoutContainments | ( |  | self ) |

Since:
  4.5 Layout the containments on this corona. The default implementation organizes them in a grid-like view, but subclasses can reimplement this slot to provide their own layout.

loadDefaultLayout | ( |  | self ) |

Loads the default (system wide) layout for this user

loadLayout | ( | self, |
|  | QString | config=QString()
| ) |  |  |

Load applet layout from a config file. The results will be added to the current set of Containments.

Parameters:

  | config | the name of the config file to load from, or the default config file if QString()

mapAnimation | ( | self, |
|  | Plasma.Animator.Animation | from,
|  | Plasma.Animator.Animation | to
| ) |  |  |

Maps a loadable animation to one of the semantic animations. Used to control things such as what animation is used to make a Plasma.Appear appear in a containment.

Parameters:

  | from | the animation to map a new value to
  | to | the animation value to map to from; this must map to a Javascript animation

Since:
  4.5

mapAnimation | ( | self, |
|  | Plasma.Animator.Animation | from,
|  | QString | to
| ) |  |  |

Maps a loadable animation to one of the semantic animations. Used to control things such as what animation is used to make a Plasma.Appear appear in a containment.

Parameters:

  | from | the animation to map a new value to
  | to | the animation value to map to from; this must map to a Javascript animation

Since:
  4.5

int numScreens | ( |  | self ) |

Returns the number of screens available to plasma. Subclasses should override this method as the default implementation returns a meaningless value.

[QGraphicsWidget] offscreenWidgets | ( |  | self ) |

Returns:
  the list of all offscreen widgets

Since:
  4.3

QPoint popupPosition | ( | self, |
|  | QGraphicsItem | item,
|  | QSize | size
| ) |  |  |

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

Parameters:

  | item | the item that the popup should appear adjacent to (an applet, say)
  | size | 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, |
|  | QGraphicsItem | item,
|  | QSize | size,
|  | Qt::AlignmentFlag | alignment
| ) |  |  |

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

Parameters:

  | item | the item that the popup should appear adjacent to (an applet, say)
  | size | size of the popup
  | alignment | alignment of the popup, valid flags are Qt.AlignLeft, Qt.AlignRight and Qt.AlignCenter

Returns:
  reccomended position

QString preferredToolBoxPlugin | ( | self, |
|  | Plasma.Containment.Type | type
| ) |  |  |

Returns the name of the preferred plugin to be used as containment toolboxes. CustomContainments and CustomPanelContainments can still override it as their liking. It's also not guaranteed that the plugin will actually exist.

Parameters:

  | type | the containment type of which we want to know the associated toolbox plugin

Since:
  4.6

removeOffscreenWidget | ( | self, |
|  | QGraphicsWidget | widget
| ) |  |  |

Removes a widget from the topleft quadrant in the scene.

Parameters:

  | widget | the widget to remove.

requestConfigSync | ( |  | self ) |

Schedules a flush-to-disk synchronization of the configuration state at the next convenient moment.

requireConfigSync | ( |  | self ) |

Schedules a time sensitive flush-to-disk synchronization of the configuration state. Since this method does not provide any sort of event compression, it should only be used when an *immediate* disk sync is *absolutely* required. Otherwise, use

See also:
  requestConfigSync() which does do event compression.

saveLayout | ( | self, |
|  | QString | config=QString()
| ) |  |  |

Save applets layout to file

Parameters:

  | config | the file to save to, or the default config file if QString()

QRect screenGeometry | ( | self, |
|  | int | id
| ) |  |  |

Returns the geometry of a given screen. Valid screen ids are 0 to numScreen()-1, or -1 for the full desktop geometry. Subclasses should override this method as the default implementation returns a meaningless value.

setAppletMimeType | ( | self, |
|  | QString | mimetype
| ) |  |  |

Sets the mimetype of Drag/Drop items. Default is text/x-plasmoidservicename

setContainmentActionsDefaults | ( | self, |
|  | Plasma.Containment.Type | containmentType,
|  | Plasma.ContainmentActionsPluginsConfig | config
| ) |  |  |

Since:
  4.4 Sets the default containmentactions plugins for the given containment type

setDefaultContainmentPlugin | ( | self, |
|  | QString | name
| ) |  |  |

Sets the default containment plugin to try and load

Since:
  4.7

setDialogManager | ( | self, |
|  | Plasma.AbstractDialogManager | manager
| ) |  |  |

Parameters:

  | the | AbstractDialogManager implementaion

Since:
  4.5

setImmutability | ( | self, |
|  | Plasma.ImmutabilityType | immutable
| ) |  |  |

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

Parameters:

  | immutable | the new immutability type of this applet

setPreferredToolBoxPlugin | ( | self, |
|  | Plasma.Containment.Type | type,
|  | QString | plugin
| ) |  |  |

Returns:
  The preferred toolbox plugin name for a given containment type.

Parameters:

  | type | the containment type of which we want to know the preferred toolbox plugin.
  | plugin | the toolbox plugin name

Since:
  4.6

updateShortcuts | ( |  | self ) |

Since:
  4.3 Updates keyboard shortcuts for all the corona's actions. If you've added actions to the corona you'll need to call this for them to be configurable.