New Plasma Widgets Design

Monday, 14 April 2008  |  Rich

This is the draft design for a new widget API for plasma, it will be appearing on techbase later, but here's what we're thinking.

General Notes

The intention of this API is to provide a very simple way for users to create plasma applets. The API can be used both for scripting and from C++. For the simple javascript API, this API will be all that is provided allowing us to run untrusted applets as they will not have access to any dangerous facilities.

From C++ or more advanced scripting APIs (such as the 'full' Javascript bindings) you can gain access to a pointer to the underlying Qt widget contained within the QGraphicsProxy allowing you to access all of its methods. For most simple uses however, this should be unnecessary as you can do most of the customisation using the Qt stylesheet facilities.

All widgets have a stylesheet, which is a string property containing a Qt stylesheet. This allows for simple but powerful configuration of the widgets - for example you can configure the alignment of the text in the label using the text-align property, or the font using the font property. Using this you can do some extremely advanced interfaces without having to learn how Qt works.

A nice side effect of the way this API is defined is that it is possible to implement the simple widget API inside a web browser using HTML, javascript and HTML stylesheets to provide the implementation.

API Reference

Label

Constructors

  • Label(Widget)

Properties

  • Widget parent
  • String text
  • String image
  • String stylesheet
  • QWidget nativeWidget

Note that the image property is a string and specifies the name of the image within the plasmoid package. The image can be either a bitmap (in any supported format) or an SVG image.

PushButton

Constructors

  • PushButton(Widget)

Properties

  • Widget parent
  • String text
  • String image
  • String stylesheet
  • QWidget nativeWidget

Signals

  • clicked()

CheckBox

  • CheckBox(Widget)

Properties

  • Widget parent
  • String text
  • String image
  • String stylesheet
  • bool checked
  • QWidget nativeWidget

Signals

  • toggled(bool)

RadioButton

  • RadioButton(Widget)

Properties

  • Widget parent
  • String text
  • String image
  • String stylesheet
  • bool checked
  • QWidget nativeWidget

Signals

  • toggled(bool)

Note that a RadioButton must exist within a ButtonGroup, the group box ensures that only one radio button is set at any one time.

Widgets To Do

  • WebContent
  • GroupBox
  • ButtonGroup
  • ComboBox
  • LineEdit
  • TextEdit
  • Meter
  • Graph
  • Throbber
  • Simplified versions of the QGraphicsLayout classes

Non-Widgets To Do

  • URLOpenner