KDE 4.7 PyKDE API Reference

- KDE's Python API

# Wallpaper Class Reference

`from PyKDE4.plasma import *`

Inherits: QObject
Namespace: Plasma

## Detailed Description

Wallpaper plasma/wallpaper.h <Plasma/Wallpaper>

The base Wallpaper class

"Wallpapers" are components that paint the background for Containments that do not provide their own background rendering.

Wallpaper plugins are registered using .desktop files. These files should be named using the following naming scheme:

plasma-wallpaper-<pluginname>.desktop

If a wallpaper plugin provides more than on mode (e.g. Single Image, Wallpaper) it should include a Actions= entry in the .desktop file, listing the possible actions. An actions group should be included to provide for translatable names.

## Enumerations

ResizeMethod | { ScaledResize, CenteredResize, ScaledAndCroppedResize, TiledResize, CenterTiledResize, MaxpectResize }

## Signals

| configNeedsSaving ()
| configurationRequired (bool needsConfig)
| configureRequested ()
| renderCompleted (QImage image)
| renderHintsChanged ()
| update (QRectF exposedArea)
| urlDropped (KUrl url)

## Methods

| __init__ (self, QObject parent=0)
| __init__ (self, QObject parent, [QVariant] args)
| addUrls (self, KUrl.List urls)
QRectF | boundingRect (self)
bool | configurationRequired (self)
[QAction] | contextualActions (self)
QWidget | createConfigurationInterface (self, QWidget parent)
Plasma.DataEngine | dataEngine (self, QString name)
bool | findInCache (self, QString key, QImage image, long lastModified=0)
QString | icon (self)
| init (self, KConfigGroup config)
| insertIntoCache (self, QString key, QImage image)
bool | isInitialized (self)
bool | isPreviewing (self)
bool | isUsingRenderingCache (self)
[KServiceAction] | listRenderingModes (self)
| mouseMoveEvent (self, QGraphicsSceneMouseEvent event)
| mousePressEvent (self, QGraphicsSceneMouseEvent event)
| mouseReleaseEvent (self, QGraphicsSceneMouseEvent event)
QString | name (self)
bool | needsPreviewDuringConfiguration (self)
Plasma.Package | package (self)
| paint (self, QPainter painter, QRectF exposedRect)
QString | pluginName (self)
| render (self, QString sourceImagePath, QSize size, Plasma.Wallpaper.ResizeMethod resizeMethod=Plasma.Wallpaper.ScaledResize, QColor color=QColor(0,0,0))
KServiceAction | renderingMode (self)
| restore (self, KConfigGroup config)
| save (self, KConfigGroup config)
| setBoundingRect (self, QRectF boundingRect)
| setConfigurationRequired (self, bool needsConfiguring, QString reason=QString())
| setContextualActions (self, [QAction] actions)
| setPreviewDuringConfiguration (self, bool preview)
| setPreviewing (self, bool previewing)
| setRenderingMode (self, QString mode)
| setResizeMethodHint (self, Plasma.Wallpaper.ResizeMethod resizeMethod)
| setTargetSizeHint (self, QSizeF targetSize)
| setUrls (self, KUrl.List urls)
| setUsingRenderingCache (self, bool useCache)
bool | supportsMimetype (self, QString mimetype)
| wheelEvent (self, QGraphicsSceneWheelEvent event)

## Static Methods

[KPluginInfo] | listWallpaperInfo (QString formFactor=QString())
[KPluginInfo] | listWallpaperInfoForMimetype (QString mimetype, QString formFactor=QString())
Plasma.Wallpaper | load (QString name, [QVariant] args=QVariantList())
Plasma.Wallpaper | load (KPluginInfo info, [QVariant] args=QVariantList())
KSharedPtr<Plasma::PackageStructure> | packageStructure (Plasma.Wallpaper paper=0)

## Signal Documentation

configNeedsSaving | ( |  | ) |

Emitted when the configuration of the wallpaper needs to be saved to disk.

Since:
  4.3

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

configurationRequired | ( | bool | needsConfig
| ) |  |  |

Emitted when the state of the wallpaper requiring configuration changes.

Since:
  4.3

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

configureRequested | ( |  | ) |

Emitted when the user wants to configure/change the wallpaper.

Since:
  4.3

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

renderCompleted | ( | QImage | image
| ) |  |  |

Emitted when a wallpaper image render is completed.

Since:
  4.3

Signal syntax:
  `QObject.connect(source, SIGNAL("renderCompleted(const QImage&)"), target_slot)`

renderHintsChanged | ( |  | ) |

Internal:

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

update | ( | QRectF | exposedArea
| ) |  |  |

This signal indicates that wallpaper needs to be repainted.

Signal syntax:
  `QObject.connect(source, SIGNAL("update(const QRectF&)"), target_slot)`

urlDropped | ( | KUrl | url
| ) |  |  |

Emitted when a URL matching X-Plasma-DropMimeTypes is dropped on the wallpaper

Parameters:

  | url | the URL of the dropped file

Since:
  4.4

Signal syntax:
  `QObject.connect(source, SIGNAL("urlDropped(const KUrl&)"), target_slot)`

## Method Documentation

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

Default constructor for an empty or null wallpaper

__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 one element: the KService service ID for the desktop entry.

Parameters:

  | parent | a QObject parent; you probably want to pass in 0
  | args | a list of strings containing one entry: the service id

addUrls | ( | self, |
|  | KUrl.List | urls
| ) |  |  |

This method is invoked by setUrls(KUrl.List) Can be Overriden by Plugins which want to support setting Image URLs Will be changed to virtual method in libplasma2/KDE5

Since:
  4.7

QRectF boundingRect | ( |  | self ) |

Returns bounding rectangle

bool configurationRequired | ( |  | self ) |

Emitted when the state of the wallpaper requiring configuration changes.

Since:
  4.3

[QAction] contextualActions | ( |  | self ) |

Returns a list of wallpaper contextual actions (nothing by default)

QWidget createConfigurationInterface | ( | self, |
|  | QWidget | parent
| ) |  |  |

Returns a widget that can be used to configure the options (if any) associated with this wallpaper. It will be deleted by the caller when it complete. The default implementation returns a null pointer.

To signal that settings have changed connect to settingsChanged(bool modified) in parent.

     connect(this, SIGNAL(settingsChanged(bool), parent, SLOT(settingsChanged(bool)))

Emit settingsChanged(true) when the settings are changed and false when the original state is restored.

Implementation detail note: for best visual results, use a QGridLayout with two columns, with the option labels in column 0

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

Since:
  4.3

bool findInCache | ( | self, |
|  | QString | key,
|  | QImage | image,
|  | long | lastModified=0
| ) |  |  |

Tries to load pixmap with the specified key from cache.

Parameters:

  | key | the name to use in the cache for this image
  | image | the image object to populate with the resulting data if found
  | lastModified | if non-zero, the time stamp is also checked on the file, and must be newer than the timestamp to be loaded

Returns:
  true when pixmap was found and loaded from cache, false otherwise

Since:
  4.3

QString icon | ( |  | self ) |

Returns the icon related to this wallpaper

init | ( | self, |
|  | KConfigGroup | config
| ) |  |  |

This method is called once the wallpaper is loaded or mode is changed.

The mode can be retrieved using the renderingMode() method.

Parameters:

  | config | Config group to load settings

insertIntoCache | ( | self, |
|  | QString | key,
|  | QImage | image
| ) |  |  |

Insert specified pixmap into the cache if usingRenderingCache. If the cache already contains pixmap with the specified key then it is overwritten.

Parameters:

  | key | the name use in the cache for this image; if the image is specific to this wallpaper plugin, consider including the name() as part of the cache key to avoid collisions with other plugins.
  | image | the image to store in the cache; passing in a null image will cause the cached image to be removed from the cache

Since:
  4.3

bool isInitialized | ( |  | self ) |

Returns:
  true if initialized (usually by calling restore), false otherwise

bool isPreviewing | ( |  | self ) |

Returns:
  true if in preview mode, such as in a configuation dialog

Since:
  4.5

bool isUsingRenderingCache | ( |  | self ) |

Returns:
  true if disk caching is turned on.

Since:
  4.3

[KServiceAction] listRenderingModes | ( |  | self ) |

Returns modes the wallpaper has, as specified in the .desktop file.

mouseMoveEvent | ( | self, |
|  | QGraphicsSceneMouseEvent | event
| ) |  |  |

Mouse move event. To prevent further propagation of the event, the event must be accepted.

Parameters:

  | event | the mouse event object

mousePressEvent | ( | self, |
|  | QGraphicsSceneMouseEvent | event
| ) |  |  |

Mouse press event. To prevent further propagation of the even, and to receive mouseMoveEvents, the event must be accepted.

Parameters:

  | event | the mouse event object

mouseReleaseEvent | ( | self, |
|  | QGraphicsSceneMouseEvent | event
| ) |  |  |

Mouse release event. To prevent further propagation of the event, the event must be accepted.

Parameters:

  | event | the mouse event object

QString name | ( |  | self ) |

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

Returns:
  the user-visible name for the wallpaper.

bool needsPreviewDuringConfiguration | ( |  | self ) |

Returns:
  true if the wallpaper needs a live preview in the configuration UI

Since:
  4.6

Plasma.Package package | ( |  | self ) |

Accessor for the associated Package object if any.

Returns:
  the Package object, or 0 if none

paint | ( | self, |
|  | QPainter | painter,
|  | QRectF | exposedRect
| ) |  |  |

Abstract method:
  This method is abstract and can be overridden but not called directly.

This method is called when the wallpaper should be painted.

Parameters:

  | painter | the QPainter to use to do the painting
  | exposedRect | the rect to paint within

QString pluginName | ( |  | self ) |

Returns the plugin name for the wallpaper

render | ( | self, |
|  | QString | sourceImagePath,
|  | QSize | size,
|  | Plasma.Wallpaper.ResizeMethod | resizeMethod=Plasma.Wallpaper.ScaledResize,
|  | QColor | color=QColor(0,0,0)
| ) |  |  |

Renders the wallpaper asyncronously with the given parameters. When the rendering is complete, the renderCompleted signal is emitted.

Parameters:

  | sourceImagePath | the path to the image file on disk. Common image formats such as PNG, JPEG and SVG are supported
  | size | the size to render the image as

  resizeMethod

  the method to use when resizing the image to fit size,
  See also:
    ResizeMethod
  Parameters:

    | color | the color to use to pad the rendered image if it doesn't take up the entire size with the given ResizeMethod

  Since:
    4.3

KServiceAction renderingMode | ( |  | self ) |

Returns:
  the currently active rendering mode

restore | ( | self, |
|  | KConfigGroup | config
| ) |  |  |

This method should be called once the wallpaper is loaded or mode is changed.

Parameters:

  | config | Config group to load settings

See also:
  init

save | ( | self, |
|  | KConfigGroup | config
| ) |  |  |

This method is called when settings need to be saved.

Parameters:

  | config | Config group to save settings

setBoundingRect | ( | self, |
|  | QRectF | boundingRect
| ) |  |  |

Sets bounding rectangle

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

When the wallpaper needs to be configured before being usable, this method can be called to denote that action is required

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

Since:
  4.3

setContextualActions | ( | self, |
|  | [QAction] | actions
| ) |  |  |

Sets the contextual actions for this wallpaper.

Parameters:

  | actions | A list of contextual actions for this wallpaper

Since:
  4.4

setPreviewDuringConfiguration | ( | self, |
|  | bool | preview
| ) |  |  |

Sets whether the configuration user interface of the wallpaper should have a live preview rendered by a Wallpaper instance. note: this is just an hint, the configuration user interface can choose to ignore it

Parameters:

  | preview | true if a preview should be shown

Since:
  4.6

setPreviewing | ( | self, |
|  | bool | previewing
| ) |  |  |

Puts the wallpaper into preview mode

Since:
  4.5

setRenderingMode | ( | self, |
|  | QString | mode
| ) |  |  |

Sets the rendering mode for this wallpaper.

Parameters:

  | mode | One of the modes supported by the plugin, or an empty string for the default mode.

setResizeMethodHint | ( | self, |
|  | Plasma.Wallpaper.ResizeMethod | resizeMethod
| ) |  |  |

Allows one to set rendering hints that may differ from the actualities of the Wallpaper's current state, allowing for better selection of papers from packages, for instance.

Parameters:

  | resizeMethod | The resize method to assume will be used for future wallpaper scaling; may later be changed by calls to render()

Since:
  4.3

setTargetSizeHint | ( | self, |
|  | QSizeF | targetSize
| ) |  |  |

Allows one to set rendering hints that may differ from the actualities of the Wallpaper's current state, allowing for better selection of papers from packages, for instance.

Parameters:

  | targetSize | The size to assume will be used for future wallpaper scaling

Since:
  4.3

setUrls | ( | self, |
|  | KUrl.List | urls
| ) |  |  |

Sets the urls for the wallpaper

Parameters:

  | urls | Urls of the selected images

Since:
  4.7

setUsingRenderingCache | ( | self, |
|  | bool | useCache
| ) |  |  |

Sets whether or not to cache on disk the results of calls to render. If the wallpaper changes often or is innexpensive to render, then it's probably best not to cache them.

The default is not to cache.

See also:
  render

Parameters:

  | useCache | true to cache rendered papers on disk, false not to cache

Since:
  4.3

bool supportsMimetype | ( | self, |
|  | QString | mimetype
| ) |  |  |

Returns:
  true if the mimetype is supported by this wallpaper and can be used in renderering. Uses the MimeType= entry from the .desktop file, and can include mimetypes that may not be suitable for drag-and-drop purposes.

Since:
  4.7

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

Mouse wheel event. To prevent further propagation of the event, the event must be accepted.

Parameters:

  | event | the wheel event object

## Static Method Documentation

[KPluginInfo] listWallpaperInfo | ( | QString | formFactor=QString()
| ) |  |  |

Returns a list of all known wallpapers.

Parameters:

  | formFactor | the format of the wallpaper being search for (e.g. desktop)

Returns:
  list of wallpapers

[KPluginInfo] listWallpaperInfoForMimetype | ( | QString | mimetype,
|  | QString | formFactor=QString()
| ) |  |  |

Returns a list of all known wallpapers that can accept the given mimetype

Parameters:

  | mimetype | the mimetype to search for
  | formFactor | the format of the wallpaper being search for (e.g. desktop)

Returns:
  list of wallpapers

Plasma.Wallpaper load | ( | QString | name,
|  | [QVariant] | args=QVariantList()
| ) |  |  |

Attempts to load a wallpaper

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

Parameters:

  | info | KPluginInfo object for the desired wallpaper
  | args | to send the wallpaper extra arguments

Returns:
  a pointer to the loaded wallpaper, or 0 on load failure

Plasma.Wallpaper load | ( | KPluginInfo | info,
|  | [QVariant] | args=QVariantList()
| ) |  |  |

Attempts to load a wallpaper

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

Parameters:

  | info | KPluginInfo object for the desired wallpaper
  | args | to send the wallpaper extra arguments

Returns:
  a pointer to the loaded wallpaper, or 0 on load failure

KSharedPtr<Plasma::PackageStructure> packageStructure | ( | Plasma.Wallpaper | paper=0
| ) |  |  |

Returns the Package specialization for wallpapers. May be queried for 'preferred' which will return the preferred wallpaper image path given the associated Wallpaper object, if any.

Parameters:

  | paper | the Wallpaper object to associated the PackageStructure with, which will then use the Wallpaper object to define things such as default size and resize methods.

## Enumeration Documentation

ResizeMethod

Various resize modes supported by the built in image renderer

Enumerator:

  ScaledResize |
  CenteredResize |
  ScaledAndCroppedResize |
  TiledResize |
  CenterTiledResize |
  MaxpectResize |