• Skip to content
  • Skip to link menu
KDE 4.3 API Reference
  • KDE API Reference
  • kdelibs
  • Sitemap
  • Contact Us
 

Plasma

Plasma::Wallpaper

Plasma::Wallpaper Class Reference

The base Wallpaper class. More...

#include <Plasma/Wallpaper>

Inheritance diagram for Plasma::Wallpaper:
QObject

List of all members.

Public Types

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

Signals

void configNeedsSaving ()
void configurationRequired (bool needsConfig)
void configureRequested ()
void renderCompleted (const QImage &image)
void renderHintsChanged ()
void update (const QRectF &exposedArea)

Public Member Functions

QRectF boundingRect () const
bool configurationRequired () const
virtual QWidget * createConfigurationInterface (QWidget *parent)
Q_INVOKABLE DataEngine * dataEngine (const QString &name) const
QString icon () const
bool isInitialized () const
bool isUsingRenderingCache () const
QList< KServiceAction > listRenderingModes () const
virtual void mouseMoveEvent (QGraphicsSceneMouseEvent *event)
virtual void mousePressEvent (QGraphicsSceneMouseEvent *event)
virtual void mouseReleaseEvent (QGraphicsSceneMouseEvent *event)
QString name () const
virtual void paint (QPainter *painter, const QRectF &exposedRect)=0
QString pluginName () const
KServiceAction renderingMode () const
void restore (const KConfigGroup &config)
virtual void save (KConfigGroup &config)
void setBoundingRect (const QRectF &boundingRect)
void setRenderingMode (const QString &mode)
void setResizeMethodHint (Wallpaper::ResizeMethod resizeMethod)
void setTargetSizeHint (const QSizeF &targetSize)
 Wallpaper (QObject *parent=0)
virtual void wheelEvent (QGraphicsSceneWheelEvent *event)
 ~Wallpaper ()

Static Public Member Functions

static KPluginInfo::List listWallpaperInfo (const QString &formFactor=QString())
static Wallpaper * load (const KPluginInfo &info, const QVariantList &args=QVariantList())
static Wallpaper * load (const QString &name, const QVariantList &args=QVariantList())
static PackageStructure::Ptr packageStructure (Wallpaper *paper=0)

Protected Member Functions

bool findInCache (const QString &key, QImage &image, unsigned int lastModified=0)
virtual void init (const KConfigGroup &config)
void insertIntoCache (const QString &key, const QImage &image)
void render (const QString &sourceImagePath, const QSize &size, Wallpaper::ResizeMethod resizeMethod=ScaledResize, const QColor &color=QColor(0, 0, 0))
void setConfigurationRequired (bool needsConfiguring, const QString &reason=QString())
void setUsingRenderingCache (bool useCache)
 Wallpaper (QObject *parent, const QVariantList &args)

Properties

QRectF boundingRect
QString icon
QList< KServiceAction > listRenderingModes
QString name
QString pluginName
KServiceAction renderingMode
bool usingRenderingCache

Detailed Description

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.

Definition at line 54 of file wallpaper.h.


Member Enumeration Documentation

enum Plasma::Wallpaper::ResizeMethod

Various resize modes supported by the built in image renderer.

Enumerator:
ScaledResize 

Scales the image to fit the full area.

CenteredResize 

Centers the image within the area.

ScaledAndCroppedResize 

Scales and crops the image, preserving the aspect ratio.

TiledResize 

Tiles the image to fill the area.

CenterTiledResize 

Tiles the image to fill the area, starting with a centered tile.

MaxpectResize 

Best fit resize.

Definition at line 69 of file wallpaper.h.


Constructor & Destructor Documentation

Plasma::Wallpaper::Wallpaper ( QObject *  parent = 0  )  [explicit]

Default constructor for an empty or null wallpaper.

Definition at line 47 of file wallpaper.cpp.

Plasma::Wallpaper::~Wallpaper (  ) 

Definition at line 72 of file wallpaper.cpp.

Plasma::Wallpaper::Wallpaper ( QObject *  parent,
const QVariantList &  args 
) [protected]

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

Definition at line 55 of file wallpaper.cpp.


Member Function Documentation

QRectF Plasma::Wallpaper::boundingRect (  )  const

Returns bounding rectangle.

void Plasma::Wallpaper::configNeedsSaving (  )  [signal]

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

Since:
4.3
void Plasma::Wallpaper::configurationRequired ( bool  needsConfig  )  [signal]

Emitted when the state of the wallpaper requiring configuration changes.

Since:
4.3
bool Plasma::Wallpaper::configurationRequired (  )  const
Returns:
true if the wallpaper currently needs to be configured, otherwise, false
Since:
4.3

Definition at line 272 of file wallpaper.cpp.

void Plasma::Wallpaper::configureRequested (  )  [signal]

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

Since:
4.3
QWidget * Plasma::Wallpaper::createConfigurationInterface ( QWidget *  parent  )  [virtual]

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

Definition at line 241 of file wallpaper.cpp.

DataEngine * Plasma::Wallpaper::dataEngine ( const QString &  name  )  const

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

Definition at line 267 of file wallpaper.cpp.

bool Plasma::Wallpaper::findInCache ( const QString &  key,
QImage &  image,
unsigned int  lastModified = 0 
) [protected]

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

Definition at line 371 of file wallpaper.cpp.

QString Plasma::Wallpaper::icon (  )  const

Returns the icon related to this wallpaper.

void Plasma::Wallpaper::init ( const KConfigGroup &  config  )  [protected, virtual]

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

Definition at line 231 of file wallpaper.cpp.

void Plasma::Wallpaper::insertIntoCache ( const QString &  key,
const QImage &  image 
) [protected]

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

Definition at line 391 of file wallpaper.cpp.

bool Plasma::Wallpaper::isInitialized (  )  const
Returns:
true if initialized (usually by calling restore), false otherwise

Definition at line 190 of file wallpaper.cpp.

bool Plasma::Wallpaper::isUsingRenderingCache (  )  const
Returns:
true if disk caching is turned on.
Since:
4.3

Definition at line 291 of file wallpaper.cpp.

QList<KServiceAction> Plasma::Wallpaper::listRenderingModes (  )  const

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

KPluginInfo::List Plasma::Wallpaper::listWallpaperInfo ( const QString &  formFactor = QString()  )  [static]

Returns a list of all known wallpapers.

Returns:
list of wallpapers

Definition at line 77 of file wallpaper.cpp.

Wallpaper * Plasma::Wallpaper::load ( const KPluginInfo &  info,
const QVariantList &  args = QVariantList() 
) [static]

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

Definition at line 122 of file wallpaper.cpp.

Wallpaper * Plasma::Wallpaper::load ( const QString &  name,
const QVariantList &  args = QVariantList() 
) [static]

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:
name the plugin name, as returned by KPluginInfo::pluginName()
args to send the wallpaper extra arguments
Returns:
a pointer to the loaded wallpaper, or 0 on load failure

Definition at line 89 of file wallpaper.cpp.

void Plasma::Wallpaper::mouseMoveEvent ( QGraphicsSceneMouseEvent *  event  )  [virtual]

Mouse move event.

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

Parameters:
event the mouse event object

Definition at line 247 of file wallpaper.cpp.

void Plasma::Wallpaper::mousePressEvent ( QGraphicsSceneMouseEvent *  event  )  [virtual]

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

Definition at line 252 of file wallpaper.cpp.

void Plasma::Wallpaper::mouseReleaseEvent ( QGraphicsSceneMouseEvent *  event  )  [virtual]

Mouse release event.

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

Parameters:
event the mouse event object

Definition at line 257 of file wallpaper.cpp.

QString Plasma::Wallpaper::name (  )  const

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

Returns:
the user-visible name for the wallpaper.
PackageStructure::Ptr Plasma::Wallpaper::packageStructure ( Wallpaper *  paper = 0  )  [static]

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.

Definition at line 130 of file wallpaper.cpp.

virtual void Plasma::Wallpaper::paint ( QPainter *  painter,
const QRectF &  exposedRect 
) [pure virtual]

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 Plasma::Wallpaper::pluginName (  )  const

Returns the plugin name for the wallpaper.

void Plasma::Wallpaper::render ( const QString &  sourceImagePath,
const QSize &  size,
Wallpaper::ResizeMethod  resizeMethod = ScaledResize,
const QColor &  color = QColor(0, 0, 0) 
) [protected]

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

Definition at line 313 of file wallpaper.cpp.

void Plasma::Wallpaper::renderCompleted ( const QImage &  image  )  [signal]

Emitted when a wallpaper image render is completed.

Since:
4.3
void Plasma::Wallpaper::renderHintsChanged (  )  [signal]

For internal use only.

KServiceAction Plasma::Wallpaper::renderingMode (  )  const
Returns:
the currently active rendering mode
void Plasma::Wallpaper::restore ( const 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

Definition at line 225 of file wallpaper.cpp.

void Plasma::Wallpaper::save ( KConfigGroup &  config  )  [virtual]

This method is called when settings need to be saved.

Parameters:
config Config group to save settings

Definition at line 236 of file wallpaper.cpp.

void Plasma::Wallpaper::setBoundingRect ( const QRectF &  boundingRect  ) 

Sets bounding rectangle.

Definition at line 195 of file wallpaper.cpp.

void Plasma::Wallpaper::setConfigurationRequired ( bool  needsConfiguring,
const QString &  reason = QString() 
) [protected]

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

Definition at line 277 of file wallpaper.cpp.

void Plasma::Wallpaper::setRenderingMode ( const 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.

Definition at line 206 of file wallpaper.cpp.

void Plasma::Wallpaper::setResizeMethodHint ( 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.

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

Definition at line 301 of file wallpaper.cpp.

void Plasma::Wallpaper::setTargetSizeHint ( const QSizeF &  targetSize  ) 

Definition at line 307 of file wallpaper.cpp.

void Plasma::Wallpaper::setUsingRenderingCache ( bool  useCache  )  [protected]

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

Definition at line 296 of file wallpaper.cpp.

void Plasma::Wallpaper::update ( const QRectF &  exposedArea  )  [signal]

This signal indicates that wallpaper needs to be repainted.

void Plasma::Wallpaper::wheelEvent ( QGraphicsSceneWheelEvent *  event  )  [virtual]

Mouse wheel event.

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

Parameters:
event the wheel event object

Definition at line 262 of file wallpaper.cpp.


Property Documentation

QRectF Plasma::Wallpaper::boundingRect [read, write]

Definition at line 57 of file wallpaper.h.

QString Plasma::Wallpaper::icon [read]

Definition at line 60 of file wallpaper.h.

QList< KServiceAction > Plasma::Wallpaper::listRenderingModes [read]

Definition at line 62 of file wallpaper.h.

QString Plasma::Wallpaper::name [read]

Definition at line 58 of file wallpaper.h.

QString Plasma::Wallpaper::pluginName [read]

Definition at line 59 of file wallpaper.h.

KServiceAction Plasma::Wallpaper::renderingMode [read]

Definition at line 61 of file wallpaper.h.

bool Plasma::Wallpaper::usingRenderingCache [read, write]

Definition at line 63 of file wallpaper.h.


The documentation for this class was generated from the following files:
  • wallpaper.h
  • wallpaper.cpp

Plasma

Skip menu "Plasma"
  • Main Page
  • Namespace List
  • Class Hierarchy
  • Alphabetical List
  • Class List
  • File List
  • Namespace Members
  • Class Members
  • Related Pages

kdelibs

Skip menu "kdelibs"
  • DNSSD
  • Interfaces
  •   KHexEdit
  •   KMediaPlayer
  •   KSpeech
  •   KTextEditor
  • Kate
  • kconf_update
  • KDE3Support
  •   KUnitTest
  • KDECore
  • KDED
  • KDEsu
  • KDEUI
  • KDocTools
  • KFile
  • KHTML
  • KImgIO
  • KInit
  • kio
  • KIOSlave
  • KJS
  •   KJS-API
  •   WTF
  • kjsembed
  • KNewStuff
  • KParts
  • KPty
  • Kross
  • KUtils
  • Nepomuk
  • Plasma
  • Solid
  • Sonnet
  • ThreadWeaver
Generated for kdelibs by doxygen 1.6.1
This website is maintained by Adriaan de Groot and Allen Winter.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal