Ubuntu Wiki

Dev Week -- Widgetcraft -- apachelogger -- Mon, Jul 12th, 2010

(02:02:06 PM) apachelogger: welcome to an intro to widgetcraft. also known as the art of creating plasma widgets.
(02:02:21 PM) apachelogger: this talk is backed up by a set of slides that can be followed at http://docs.google.com/present/view?id=ajk6csn6c2vn_53fj6c47f6
(02:02:35 PM) apachelogger: my name is Harald Sitter, and I wish you a pleasant journey :)
(02:02:54 PM) apachelogger: first off I would like to direct your attention to important sites that will help a lot with writing plasmoids.
(02:03:04 PM) apachelogger: General tutorials on JavaScript Plasma programming are avilailable at: http://techbase.kde.org/Development/Tutorials/Plasma#Plasma_Programming_with_JavaScript
(02:03:13 PM) apachelogger: Information on Plasma packages: http://techbase.kde.org/Projects/Plasma/Package
(02:03:16 PM) mode (-o dholbach) by dholbach
(02:03:26 PM) apachelogger:  And a rather simplified JavaScript API: http://techbase.kde.org/Development/Tutorials/Plasma/JavaScript/API
(02:03:52 PM) apachelogger: in general I probably should mention that the kde techbase is a wonderful resource for KDE programming topics of all kinds with a vast amount of tutorials
(02:04:16 PM) apachelogger: so, lets get started.
(02:04:23 PM) apachelogger: first let me quickly get some terms straight.
(02:04:32 PM) apachelogger: -> Plasma <-
(02:04:43 PM) apachelogger: is the technology underlying the KDE workspace.
(02:05:16 PM) apachelogger: it is available in multiple different versions. on a PC you will have plasma-desktop, on a netbook possibly plasma-netbook and in the future you will be able to run plasma-mobile on your mobile device (e.g. a smart phone)
(02:05:27 PM) apachelogger: \o/ yay for plasma on my mobile ;)
(02:05:49 PM) apachelogger: even though those incarnations of plasma might look different, they all root in teh same base technology and follow the same principles
(02:05:58 PM) apachelogger: next up is -> plasmoid <-
(02:06:13 PM) apachelogger: I have already used that term. Plasmoids are sort of native Plasma Widgets.
(02:06:18 PM) apachelogger: There are also non-native widgets ;)
(02:06:29 PM) apachelogger: For example one can run Mac Widgets or Google Gadgets inside Plasma as well.
(02:06:49 PM) apachelogger: In this talk I will show you how to write Plasmoids in JavaScript using 2 (well, technically 3) example Plasmoids.
(02:07:02 PM) apachelogger: and yes!!!! we will be able to pull this off in the limited time that we got.
(02:07:07 PM) apachelogger: We just need to believe in it :-D
(02:07:28 PM) apachelogger: [endofboringbits]
(02:07:38 PM) apachelogger: Time to move on to the interesting parts ...
(02:07:47 PM) apachelogger: let me show you just how difficult it is to write a plasmoid.
(02:08:01 PM) apachelogger: as with every programming introduction I will start with a "Hello" example.
(02:08:19 PM) apachelogger: if you do not want to write the stuff yourself, you can find a finsihed example at http://people.ubuntu.com/~apachelogger/udw/10.07/hello-doctor/
(02:08:44 PM) apachelogger: as one might judge from the name this hello plasmoid is apachelogger branded and featuring doctor who awesomeness ;)
(02:09:03 PM) apachelogger: first we need to get the structure sorted out a bit - no fun without the politics :/
(02:09:10 PM) apachelogger: I will however try to limit this to the bare minimum
(02:09:11 PM) apachelogger: so
(02:09:20 PM) apachelogger: Any plasmoid *should* at least contain two files.
(02:09:39 PM) apachelogger: One for the "politics" (giving the plasmoid a name and icon) and one for the actual code.
(02:09:57 PM) apachelogger: specficis are in detail explained in the KDE techbase
(02:10:03 PM) apachelogger: (if anyone really cares :P)
(02:10:21 PM) apachelogger: for now you can just trust me and execute the following in a directory of your choice
(02:10:22 PM) apachelogger: mkdir -p hello-doctor/contents/code/
(02:10:23 PM) apachelogger: touch hello-doctor/metadata.desktop
(02:10:23 PM) apachelogger: touch hello-doctor/contents/code/main.js
(02:10:42 PM) apachelogger: these 3 lines will create the most essential directories and the 2 files I was talking about
(02:10:57 PM) apachelogger: Now for the adding of content.
(02:11:12 PM) apachelogger: (please excuse if I am rushing this a bit, but it is rather boring ;))
(02:11:45 PM) apachelogger: open hello-doctor/metadata.desktop in an editor of your choice (be it vi or nano ;)) and add the information seen at http://people.ubuntu.com/~apachelogger/udw/10.07/hello-doctor/metadata.desktop
(02:12:07 PM) apachelogger: most of those files should be pretty self-explaining and are documented in the techbase
(02:12:17 PM) apachelogger: should you have a question about one of those - please ask
(02:12:43 PM) apachelogger: the only thin worth mentioning is that the field X-KDE-PluginInfo-Name *must* be rather unique
(02:13:03 PM) apachelogger: QUESTION: What does X-KDE-PluginInfo-EnabledByDefault=true do?
(02:13:07 PM) apachelogger: no one knows that ;)
(02:13:23 PM) apachelogger: all the information about that field is that you do not need to change it
(02:13:35 PM) ***apachelogger also did not bother to look its function up in the source code....
(02:14:00 PM) apachelogger: once you have made the metadata.desktop suite your needs, save it and let us move on to ... the code :D
(02:14:29 PM) apachelogger: the code goes to hello-doctor/contents/code/main.js (that is actually changable via the desktop file in case you haven't noticed)
(02:14:35 PM) apachelogger: now behold!
(02:14:39 PM) apachelogger: layout = new LinearLayout(plasmoid);
(02:14:39 PM) apachelogger: label = new Label(plasmoid);
(02:14:39 PM) apachelogger: layout.addItem(label);
(02:14:39 PM) apachelogger: label.text = 'Hello Doctor!';
(02:14:54 PM) apachelogger: Yes, four lines of code :P
(02:14:58 PM) apachelogger: I am not kidding you :P
(02:15:45 PM) apachelogger: first we create a layout that belongs to your plasmoid and call it "layout", then we create a label that also belongs to our plasmoid and call it "label".
(02:16:06 PM) apachelogger: we add the label and to our layout and give it a text
(02:16:11 PM) apachelogger: and, well, that is it
(02:16:28 PM) apachelogger: and since it just got mentioned that this is much easier than C++
(02:16:31 PM) apachelogger: indeed it is
(02:16:50 PM) apachelogger: also it is available by default in plasma, so it is as protable as C++
(02:17:18 PM) apachelogger: in the end you should choose a javascript code over C++ for various reasons, if you do not need any of the C++ advantages :)
(02:17:24 PM) apachelogger: thereofre I am also talking about javascript :)
(02:17:35 PM) apachelogger: anyhow
(02:17:38 PM) apachelogger: lets view the plasmoid
(02:17:41 PM) apachelogger: plasmoidviewer ./hello-doctor
(02:17:59 PM) apachelogger: usually this should give you our new plasmoid, if it does not  -> http://people.ubuntu.com/~apachelogger/udw/10.07/hello-doctor.png
(02:18:05 PM) apachelogger: Congratulations, you just have made your first Plasmoid!
(02:18:33 PM) apachelogger: plasmoidviewer is a very useful tool for in-development debugging
(02:19:05 PM) apachelogger: now that we have a plasmoid, it would be very nice to have it packaged, so we can install it in plasma and share it with others
(02:19:32 PM) apachelogger: for general purpose widget management plasma comes with a tool called plasmapkg
(02:20:06 PM) apachelogger: using plasmapkg -i you can install plasmoids to use them in plasma
(02:20:16 PM) apachelogger: packaging them is no magic either
(02:20:20 PM) apachelogger: just create a zip ;)
(02:20:26 PM) apachelogger: cd hello-doctor
(02:20:26 PM) apachelogger: zip -r ../hello-doctor.zip .
(02:20:26 PM) apachelogger: mv ../hello-doctor.zip ../hello-doctor.plasmoid
(02:20:48 PM) apachelogger: that will give you a nice plasmoid package to use with plasmapkg
(02:20:52 PM) apachelogger: and share with your friends
(02:21:25 PM) apachelogger: shadeslayer: mind the period in ./hello-doctor/
(02:21:46 PM) apachelogger: believe it or not, you now know almost everything
(02:22:08 PM) apachelogger: well, the important stuff anyway, lets digg a bit into development
(02:22:35 PM) apachelogger: that we will do with my incredibly awesome superior sweet and unicorny "trollface" plasmoid
(02:23:03 PM) apachelogger: you can either create the basic infrastructure using the commands I gave you for hello-doctor, or just recycle my template http://people.ubuntu.com/~apachelogger/udw/10.07/trollface-template/
(02:23:32 PM) apachelogger: remember to make metadata.desktop suite your needs, if you want
(02:23:45 PM) apachelogger: otherwise lets dive right into trollface/contents/code/main.js
(02:24:05 PM) apachelogger: the template I have provides no more than the code we used for hello-doctor
(02:24:17 PM) apachelogger: building up on that we will make superior awesomeness now
(02:24:25 PM) apachelogger: let me think
(02:24:25 PM) apachelogger: hm
(02:24:36 PM) apachelogger: how about we add a button to that ;)
(02:24:43 PM) apachelogger: one to push ;)
(02:24:48 PM) apachelogger: terribly difficult cod eagain...
(02:24:55 PM) apachelogger: button = new PushButton(plasmoid);
(02:24:55 PM) apachelogger: layout.addItem(button);
(02:24:55 PM) apachelogger: button.text = 'Push me!!!';
(02:25:19 PM) apachelogger: very similar to the label code but with a pushbuton now... just add that at the bottom of your main.js and you should get a button now
(02:25:31 PM) apachelogger: http://people.ubuntu.com/~apachelogger/udw/10.07/hello-doctor-1.png
(02:25:37 PM) apachelogger: looks fancy, eh? ;)
(02:25:46 PM) apachelogger: yeah, I know, not really, but we will get there
(02:25:53 PM) apachelogger: oh hold on!
(02:26:00 PM) apachelogger: oh dear, oh dear! That does not look right at all :/
(02:26:10 PM) apachelogger: I do not know about you, but I really wanted the button under the label
(02:26:14 PM) apachelogger: not next to it
(02:26:37 PM) apachelogger: well, this gives me reason to talk a bit about layouting
(02:26:42 PM) apachelogger: ^ see what I did there
(02:26:54 PM) apachelogger: evil as I am I made myself a topic to talk about :D
(02:27:19 PM) apachelogger: so, our layout is obviously there to help with placement of our items
(02:27:27 PM) apachelogger: for that different layouts can use different rules
(02:27:36 PM) apachelogger: our simple linearlayout supports to ways to layout items
(02:27:44 PM) apachelogger: by vertical or horizontal orientation
(02:27:57 PM) apachelogger: suffice to say, the default is horizontal, hence our button is right of the label
(02:28:11 PM) apachelogger: to change that we add
(02:28:13 PM) apachelogger: layout.orientation = QtVertical;
(02:28:28 PM) apachelogger: now everything should be as intent by the author
(02:28:30 PM) apachelogger: http://people.ubuntu.com/~apachelogger/udw/10.07/hello-doctor-2.png
(02:28:52 PM) apachelogger: be careful though!
(02:29:06 PM) apachelogger: when just adding items ot a layout (i.e. using the addItem() function) they will be listed in order of adding!
(02:29:17 PM) apachelogger: one should keep that in mind for later ;)
(02:29:30 PM) apachelogger: currently our button does not do much though :(
(02:29:32 PM) apachelogger: a bit sad.
(02:29:46 PM) apachelogger: let's add some super feature.
(02:30:04 PM) apachelogger: for this we will introduce a new javascript function. this is done using the function keyword. like this:
(02:30:11 PM) apachelogger: function showTroll()
(02:30:11 PM) apachelogger: {
(02:30:11 PM) apachelogger:     label.visible = false;
(02:30:11 PM) apachelogger: }
(02:30:28 PM) apachelogger: QUESTION: Can we resize that button?
(02:30:31 PM) apachelogger: yes, but a bit later
(02:30:40 PM) apachelogger: QUESTION: im getting http://imagebin.ca/view/RuCn71.html , what have i done wrong?
(02:31:13 PM) apachelogger: broken plasma most likely, what you are seeing here is that for some reason the plasma theme is not rendering properly, which is mostly an indication for running usntable pre-release software :P
(02:31:43 PM) apachelogger: so essenntially the items are there, they are just not drawn properly, goes a bit out of the scope of widgetcraft though :)
(02:31:57 PM) apachelogger: back to my new function showTroll
(02:32:06 PM) apachelogger: it does not do much
(02:32:11 PM) apachelogger: but what it does, man that is epic
(02:32:15 PM) apachelogger: it makes the label invisible
(02:32:18 PM) apachelogger: how scary is that!!!
(02:33:02 PM) apachelogger: now if you add showTroll(); to the bottom of your script the label will never be visible, not a lot of sense ... I just mention that to make you understand what a function is ;)
(02:33:30 PM) apachelogger: what would make a lot more sens is if we could hook up our button with that function
(02:33:35 PM) apachelogger: well *surprise* we can ;)
(02:34:04 PM) apachelogger: Qt has a system called signal and slots, it basically allows us to connect certain events of objects (signals) to functions that will carry out to an effect (slot).
(02:34:09 PM) apachelogger: Suppose my home is a plasmoid.
(02:34:20 PM) apachelogger: Now someone rings the bell, this will trigger that I go to the door and open it.
(02:34:46 PM) apachelogger: In Qt terms this means: someone emits the singal bellRung, this triggers my slot openDoor, and that slot will have as resulting situation that I am standing at my open door
(02:35:20 PM) apachelogger: I hope this clears things up that are going to happen next ... if not, poke devildante he knows all about signals and slots  ;)
(02:35:26 PM) apachelogger: so
(02:35:39 PM) apachelogger: like my home has a bell that can be rung, our plasmoid has a button...
(02:35:46 PM) apachelogger: and well, buttons can be clicked... ;)
(02:35:58 PM) apachelogger: nw we just connect that clicking to the function
(02:36:00 PM) apachelogger: button.clicked.connect(showTroll);
(02:36:08 PM) apachelogger: you can add this anywhere below the creation of the butotn
(02:36:22 PM) apachelogger: if you run the code now and click the button it will hide the label!
(02:36:24 PM) apachelogger: so magic :)
(02:36:54 PM) apachelogger: any questions thus far?
(02:37:17 PM) apachelogger: http://people.ubuntu.com/~apachelogger/udw/10.07/hello-doctor-2-2.png
(02:37:24 PM) apachelogger: the careful observer will notice that there is still space occupied by our label
(02:38:33 PM) apachelogger: this is because we have just made it invisible
(02:38:36 PM) apachelogger: it is still there
(02:39:00 PM) apachelogger: in order to reuse the space we just remove it from the layout
(02:39:07 PM) apachelogger: function showTroll()
(02:39:08 PM) apachelogger: {
(02:39:08 PM) apachelogger:     label.visible = false;
(02:39:08 PM) apachelogger:     layout.removeItem(label);
(02:39:08 PM) apachelogger: }
(02:39:32 PM) apachelogger: using this improved showTroll fucntion the button sould now not only hide the label but also reuse its space
(02:39:39 PM) apachelogger: now
(02:39:47 PM) apachelogger: while we are at it, let us also invert the logic
(02:39:53 PM) apachelogger: we probably want our label back at some point
(02:39:58 PM) apachelogger: function hideTroll()
(02:39:58 PM) apachelogger: {
(02:39:58 PM) apachelogger:     layout.insertItem(0, label);
(02:39:58 PM) apachelogger:     label.visible = true;
(02:39:58 PM) apachelogger: }
(02:40:16 PM) apachelogger: so now we have showTroll and hideTroll
(02:40:26 PM) apachelogger: http://people.ubuntu.com/~apachelogger/udw/10.07/hello-doctor-3.png
...