Create Your Very Own Widget

This Instructable will teach you how to create a basic Yahoo! Widget. By the end of this tutorial, you will have learned some JavaScript and XML.

Some tools you will need to make a widget are:
- A computer with Mac OS X or Windows Xp/Vista
- A text editing program. (Notepad is perfect.)
- An image editing program. (Microsoft Paint is fine.)
- Patience and time.
- Yahoo Widgets
- Widget Converter Widget

Once you have these programs and widgets, you are ready to move on to step two.

Now you will need to create the folder structure to house all the files that make up a widget.
The structure looks like this:
-Widget Name
|
Contents
|
Widget.kon
Main.js
Resources
|
All of the images the widget will use

You can download this widget to automatically create the folder structure
Structure - Reinier Kaper

Set the preferences of a widget by right-clicking on any part of it, and click on preferences.
Change the preferences of Structure to the following:
root: Navigate to your widget folder. (Located in 'My Documents' on Windows)

Now you can click on the widget and a dialog box will pop up, asking you for the name of the widget.

We will start with creating the widget.xml file, which tells the widget engine information about your widget.

Download a template a have created for you to use. Download link below. Place the file in the 'Contents' folder located in the folder titled the name you chose earlier. Open the file with the text editor of you choice and replace YourNameHere with your name. Save and close.

Next we will create the .kon file which is the main file that tells the widget what to do. The .kon file is just an XML file with a renamed extension. Download this basic widget.kon file and also place it in the 'Contents' folder. Again, open up the file with a text editor. The first line signifies that the file is an XML file created with the UTF-8 encoding. The next tag to add is the widget tag; <widget>
Then you declare your settings, like debug; <settings><setting name="debug" value="on"/></settings>. Now you are ready to add your window elements; <window>. Widgets have multiple objects that do certain things and have certain properties. For example the text object,<text ..../>, creates text. Here are a list of some of the properties of the text object:

-name (self-explanitory)
-window (depreciated)
-data (text to display)
-color (self-explanitory)
-size
-font
-hOffset (a.k.a x)
-vOffset (a.k.a. y)
-width
-height

With that said, let's start coding. Add the following code to the kon file, in the <window> tags:

<text>
<name>myText</name>
<data>Hello World!</data>
<color>blue</color>
<font>Arial</font>
<size>18</size>
<alignment>left</alignment>
<vOffset>25</vOffset>
<hOffset>2</hOffset>
</text>

In english, this sets up a text object named myText, that displays "Hello World!" in font Arial, color blue, and size 12.

Save your kon file, and continue to step four.

Double-Click on the kon file and your widget will load. Congratulations! You have created your first widget. But we're not done coding yet. Your probably thinking, "That's all?", right? Continue to step 5 to add some function to your widget.

Now we are going to make the widget display the current time. This will require a timer that updates every minute, and another file. The next file will be a JavaScript file, that will go in the 'Contents' folder.

Open your text editor and create a file called main.js. To add the time, we will use "the Date object". To setup the date object, you create a function. Add this function to the js file:

function updateText()'
{
theTime = new Date();
theHour = String(theTime.getHours());
theMinutes = String(theTime.getMinutes());

myText.data = "The time is: "+ theHour+":"+theMinutes;

print('update');
}

Your widget will not show the time yet, because it doesn't know what to do with the js file. To take care of this, we add this event handler to the Kon file, in the <widget> tags but not in the <window> tags:

<action trigger="onLoad">
include('main.js');
</action>

To make the time update, we need to create a timer, which goes in the Kon file, in the <widget> tags but not in the <window> tags:

<timer name="myTimer" interval="1" onTimerFired="updateText()" ticking="true"/>

Save the files and load the widget. It should show the time. If it doesn't work, download both the kon and js from below and replace with the old ones.

Use the widget converter widget to convert the widget to a .widget file. NOTE: Drag the folder that is titled the name of your widget onto the converter, not the kon file. If you want to go even further with your widget, grab some resources here.

Here are a list of things that you can try to accomplish with your widget:

-Add preferences to control the font using the <preference> tag, and the <type>font</font> sub-tag
-Add some event handlers like onClick using the <onClick> or <onMultiClick> tags.
-Display an image from a local file using the image object


Hope you found this tutorial useful and you will enjoy the endless possibilities of widgets,
Hunter