Plasma user interface basics

The only two UI widget we'll use are Labels, a Layout to arrange them and the applet itself.

The applet itself is represented by a global object named plasmoid. We gonna take a look at what properties it has to offer

for(var k in plasmoid) {
  print(k);
}

objectName
aspectRatioMode
formFactor
location
currentActivity
shouldConserveResources
activeConfig
busy
backgroundHints
immutable
userConfiguring
apiVersion
status
rect
size
associatedApplication
layout
sender
destroyed(QObject*)
destroyed()
releaseVisualFocus()
configNeedsSaving()
formFactorChanged()
locationChanged()
contextChanged()
immutableChanged()
statusChanged()
gc()
formFactor()
aspectRatioMode()
setAspectRatioMode(AspectRatioMode)
setFailedToLaunch(bool,QString)
setFailedToLaunch(bool)
isBusy()
setBusy(bool)
backgroundHints()
setBackgroundHints(BackgroundHints)
setConfigurationRequired(bool,QString)
setConfigurationRequired(bool)
size()
rect()
setActionSeparator(QString)
setAction(QString,QString,QString,QString)
setAction(QString,QString,QString)
setAction(QString,QString)
removeAction(QString)
action(QString)
resize(qreal,qreal)
setMinimumSize(qreal,qreal)
setPreferredSize(qreal,qreal)
activeConfig()
setActiveConfig(QString)
readConfig(QString)
writeConfig(QString,QVariant)
file(QString)
file(QString,QString)
include(QString)
debug(QString)
findChild(QString)
extender()
downloadedFiles()
update(QRectF)
update()
listAddons
loadAddon
addEventListener
removeEventListener
hasExtension
__qt_scope__

From the number of properties alone you can tell that it must be important :P.

And it is. The P in this graph

            P
           / \
          /   \
         /     \
        /       \
       O         O
      / \       /|\
     /   \     / | \
    O     O   O  O  O

represents plasmoid. It is the root object of our applet. All other elemets in it are represented by an O. If the applet is destroyed (by closing the window of shutting plasma down) it starts a cleanup cascade. It tells its immediate children to kill their children and so on.

Besizes that role it has some methods that control the outer dimensions and orientation of the applet. For example

plasmoid.resize(300, 30);

The object graph for this applet is rather simple

            P

We gonna change that now.

This code

l = new Label(plasmoid) // adds it as child of plasmoid
l.text = "Hello World";

puts a label l object into the graph

            P
            |
            |
            l

The result

This looks broken, doesn't it? A label on its own doesn't know what to do with itself.

The label needs some guidance, which will be delivered by a layout L

            P
            |
            |
            L
            |
            |
            l

layout = new LinearLayout(plasmoid); // add it as child of plasmoid

l = new Label()
l.text = "Hello World";
layout.addItem(l); // inserts it as child of layout

The result is

That looks a lot better. However, I cheated. You'll see prabably this:

That is a lovely little bug that only occurs when the applet is run via plasmoidviewer. You can fix it buy resizing the plasmoid a tiny bit. Actually, we can do that in the script itself

layout = new LinearLayout(plasmoid); // add it as child of plasmoid

l = new Label()
l.text = "Hello World";
layout.addItem(l); // inserts it as cild of layout

// ugly little hack to work around layout issue when using plasmoidviewer
plasmoid.resize(201, 200)
plasmoid.resize(200, 200)

I'll use that trick from now on, but won't actually include it in the code listings.

This code

layout = new LinearLayout(plasmoid); // add it as child of plasmoid

labels = [];
for(var i = 0; i < 4; i++) {
  l = new Label()
  l.text = "l" + i;
  layout.addItem(l); // inserts it as cild of layout

  labels.push(l); // for later usage
}

builds this object graph

           P
           |
           L
           |
     o---o---o---o
     |   |   |   |
    l0  l1  l2  l3

The resulting applet is