workspace/plasma/design/wallpaper

   1 Wallpapers
   2 ==========
   3
   4 Overview
   5 --------
   6 "Wallpapers" are components that paint the background for Containments that
   7 do not provide their own background rendering.
   8
   9 Timeline
  10 --------
  11 Introduced in: libplasma 2.1 (KDE 4.2.0)
  12
  13 Component Type
  14 --------------
  15 Wallpapers are plugins of ServiceType Plasma/Wallpaper.
  16
  17 Component Description
  18 ---------------------
  19 Wallpaper plugins are registered using .desktop files. These files should be
  20 named using the following naming scheme:
  21
  22     plasma-wallpaper-<pluginname>.desktop
  23
  24 If a wallpaper plugin provides more than on mode (e.g. Single Image, Wallpaper)
  25 it should include a Actions= entry in the .desktop file, listing the possible
  26 actions. An actions group should be included to provide for translatable names.
  27
  28 Example:
  29
  30 > Actions=SingleImage,Slideshow
  31 >
  32 > [Desktop Action SingleImage]
  33 > Name=Image
  34 > Icon=image-jpg
  35
  36 All other entries should follow the standard .desktop specification,
  37 supplemented by the standard KPluginInfo keys.
  38
  39 If a wallpaper plugin should be constrained to a specific set of FormFactors,
  40 include a list of those FormFactors using the X-Plasma-FormFactors key.
  41
  42 Defined categories for wallpapers include:
  43  * Single Image
  44  * Slideshow
  45  * Animated
  46  * OpenGL
  47  * Interactive
  48
  49 Component API
  50 -------------
  51 Subclasses: QObject
  52
  53 *** Key Properties ***
  54
  55 boundingRect: the geometry to paint the wallpaper into
  56 formFactors: the Plasma::FormFactors this wallpaper supports (e.g. Planar)
  57
  58 *** Key Methods ***
  59
  60 The update(QRectF) signal must be emitted whenever the wallpaper needs a repaint.
  61 This might happen in response to the wallpaper changing (such as in a slidshow)
  62 or due to an animation update. Keeping the exposed area to a minimum is important.
  63
  64 Painting is done in the paint(QPainter *painter, const QRectF &exposed area)
  65 method, and will be called when a paint operation should be done, either due to
  66 an external event or in response to an update request from the wallpaper.
  67
  68 A configuration UI can optionally be provided by overloading the configuration
  69 method.
  70
  71 Containment Interface
  72 ---------------------
  73 The Containment class supports loading and using a wallpaper plugin.
  74 Subclasses need do nothing to get this support, and can opt out of
  75 wallpaper support by calling setDrawWallpaper(false).
  76
  77 When a wallpaper plugin is used, Wallpaper::paint is called from
  78 Applet::paint.
  79
  80 The Wallpaper plugin to use is set using the setWallpaper(const QString &pluginName)
  81 method.
  82
  83 User Configuration
  84 ------------------
  85 It is up to the host application to provide a configuration interface, such
  86 as a dialog, to the user to embed the wallpaper config in.
  87
  88 *** Plasma Desktop Implementation ***
  89
  90 A setting dialog is provided by the View (DesktopView, PanelView, etc).
  91
  92 This dialog allows selecting both the Containment type for
  93 the current Activity associated with the view as well as selecting the
  94 Wallpaper plugin for the Containment.
  95
  96 Future Work
  97 -----------
  98 * Wallpapers should be ScriptEngine-able
  99 * Ability to define which wallpapers a Containment is compatible with?