APR
14
2008

New Plasma Widgets Design

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