The Cartman Widget example

Published on Sunday, September 18, 2005 By Brad Wardell In DesktopX Tutorials
Our friends at OSX-E have a great widget tutorial for Konfabulator put together by Herd, talented widget author.

It's a very well written tutorial that walks the user through how to create a widget for Konfabulator.  Since its release, Konfabulator has gotten a lot of great publicity on its ability to create widgets. As the product manager of its primary Windows competitor, DesktopX, I can appreciate Konfabulator as both a technology and as a popular phenomenon.  Its existence has forced us to get a lot better at our own marketing and developer support.

DesktopX precedes Konfabulator by years.  But being a Windows-only product, we haven't gotten anywhere near the press that Konfabulator received so often times Mac users believe that user created mini-applets on the desk originated with it. 

DesktopX is object-oriented in nature.  Users make their creations with objects. When they are done, they can export their creations as widgets or as entire desktops.  For that reason DesktopX has a disadvantage -- it seems more complicated than Konfabulator to a new user.  Because it can be used to create a lot more kinds of things and its development aspects are part of the environment, it can come across as more complicated. 

DesktopX 3 Pro adds one further wrinkle, users can export their creations also as gadgets. Gadgets are identical to widgets but require no additional downloads to make them work. They are independent programs. 

What's really cool about Herd's Konfabulator tutorial is not just that it's well written, but it illustrates what's involved in creating even a simple Konfabulator widget. So for the purposes of an apples and apples comparison, I'm going to create nearly the same widget with DesktopX and walk you through how you'd create the Cartman widget with it.

Cartman: The Widget!

Tools Needed:

  • A drawing program (something capable of making PNG images with per pixel translucency).
  • A web browser or Acrboat reader for reading the DesktopX reference manual.
  • Patience!

Prerequisites to understanding this tutorial:

  • Very basic programming experience -- any language will suffice.
  • The ability to learn a fairly straight forward GUI interface.
  • Some math - just enough to figure out how often you want Cartman to blink or smile and such.

DesktopX: No XML it's all GUI or Programming - whichever you prefer

The most significant difference between DesktopX 3 and Konfabulator from a widget creation point of view is that with Konfabulator you define your widget in XML.  With DesktopX 3, you can either use the DesktopX GUI to create objects and object states (which is what I am going to do here because I prefer that) or you can do everything in JavaScript.  There is no XML writing involved in creating a DesktopX widget.

JavaScript in DesktopX

DesktopX supports Windows Scripting Host.  So any scripting language you have installed on your computer you can use. However, since Windows supports JavaScript and vbScript out of the box, it's generally best to use those.

Both vbScript and JavaScript are quite rich in what functionality they provide. For instance, I use the random function (Math.random). That's not part of DesktopX. That's a feature of JavaScript.

Coding in DesktopX

DesktopX includes a built in editor. You don't have to use it but it has an intellisense type feature that allows you to browse the various DesktopX classes.  Example, type Object. (object-dot) and upon hitting the period key a context sensitive list of object methods appear that let you know what's available.  You can always code in your favorite editor and paste it in though. DesktopX will also highlight mistakes you made on the fly.

So let's get started. Our goal is to create a little Eric Cartman (from the popular TV show "South Park") that sits on your desktop and makes faces on occasion. Nothing very fancy but enough to walk you through the basics.  Since the thrust of this tutorial is to contrast how one creates widgets in Konfabulator, I strongly recommend reading Herd's excellent tutorial as he is really the one who put this together and this is a derivative of it.  The goal is to provide an apples to apples comparison.

Step #1: Create the Cartman object.

When you load up DesktopX, it adds itself to your system tray. Right click on it and choose "new object". You will then see this.

 

Step #2: Change the image

So then I press the "Change" button and change its image.

 

Step #3: Create the eye and mouth objects

Repeating what you did to create the first object, create the face and eye objects. Essentially, the Cartman tutorial creates a widget that is Cartman with random changes to his eyes and mouth.

 

Step #4 Add the states

We have images for Cartman blinking, Cartman looking mad, etc.  I could create these states in Javascript but I prefer to add them to the actual object as I find it makes debugging easier to explicitly create states in the GUI.  Very easy to do though. Just press the add button, name your state, and then choose the image.

Do this for the eyes and the mouth.

 

Step #5: Name your objects

So far I've made 3 objects. I'm going to be doing things to two of them (the eyes and the mouth). So I'm going to name my objects so that I can refer to them in script. I name one of them "eyes" and the other "mouth". This is done on the summary tab.

 

Step #6: Write the code

I choose my main Cartman object and click on properties and then press the "new" script.

 

Which brings up the editor. To make sure this is truly apples and apples, I change my language to "javascript" (make sure you remove the VB script code in there before you choose Javascript).

 

The Java-Script I've written is a little bit different than from the tutorial since DesktopX's needs are different.  The first part is the constructor:

//Called when the script is executed
function Object_OnScriptEnter()
{
  DesktopX.Object("Eyes").Width = 75
  DesktopX.Object("Eyes").Height = 41
  DesktopX.Object("Mouth").Width = 46
  DesktopX.Object("Mouth").Height = 21
  Object.SetTimer(12,800);
}

What is happening:

  • In Herd's tutorial, he resizes the images to be 70% of what they originally were. While I could do that, I prefer to know precisely the size I'm dealing with so I resized the eyes and mouth to be a specific size. 

  • I am accessing the other objects through the DesktopX class. I type DesktopX.Object and then the name of the object I want to access and then use its methods to manipulate it.

  • The last thing I do is I create a timer.  Every 800ms I call timer 12 which calls a function called DoFace():

//Called by the timer trigger every 800ms.
function doFace()
{
  i = Math.round(Math.abs(Math.random()*30));
  if(i==4)DesktopX.Object("Eyes").State = "closed";
  if(i==5)DesktopX.Object("Eyes").State = "drowsy";
  if(i==6)DesktopX.Object("Eyes").State = "hng";

  i = Math.round(Math.abs(Math.random()*40));
  DesktopX.Object("Mouth").State = "Default";
  if(i==0)DesktopX.Object("Mouth").State = "grr";
  if(i==1)DesktopX.Object("Mouth").State = "down";
  if(i==2)DesktopX.Object("Mouth").State = "smile";
}

What is happening:

  • I am using the JavaScript math function to generate a random number between 0 and 29. I then do a standard IF THEN statement to change the state of my objects based on the result.

  • I want my eyes to blink or whatever on occasion. Therefore, I played with this number until I found a value that seemed life like (I originally did the 5 second one but I wanted it to be random). 

Step 7: Group them together

So at this point my objects would be separated and doing their thing which looks strange. So I drag and drop them together to create my Cartman. Then I drag select them all, choose group and give them a name.

 

Step 8: Export them as a widget..

Select Export

 

Since I'm using DesktopX Pro I can export it as a stand-alone program.

 

 

And Finally..

 

There's my stand alone Cartman. 

 

Conclusions

I didn't bother to create a properties dialog for the gadget to change settings but that would have been a couple more lines (I can do that if anyone is interested).  The goal is to let people see how widget/gadget creation in DesktopX compares to doing the same in Konfabulator.  Mind you, I could have done the whole thing in VB Script or JavaScript without ever using the GUI, I just find it a little easier to deal with graphics in the GUI and have the code handle logic.  

For the aspiring software developer, the ability to use DesktopX 3 to rapidly develop a mini-application entirely in JavaScript or vbScript has some significant advantages we feel.  And for artists who are not as familiar with coding, having a fairly straight forward GUI available to create and put together objects makes creating mini-applications more approachable.

You can learn more about DesktopX 3.0 at http://www.desktopx.net.  The standard version of DesktopX 3.0 is $24.95 and allows you to export widgets that can be run by anyone who has DesktopX installed.  For $69.95 you can purchase DesktopX 3.0 Pro which allows you to export your creations as stand-alone programs.

For Windows Vista developers, DesktopX Pro becomes particularly interesting as Windows Vista will have native support for gadgets and Microsoft has embraced the gadget concept.

Files

Cartman.zip (521K) - yes, it's a stand alone program, no other files needed.

 

Special Thanks

A big thanks to Herd who created the Konfabulator tutorial that this tutorial is based on. My technical writing skills pale in comparison as is obvious but hopefully I have been able to do justice to his fine tutorial concept.