Modifying Hello World

One of the best ways to learn about the gadget API is to modify an existing gadget. This tutorial leads you through modifying the Hello World gadget included in the SDK. You'll change the gadget's XML and JavaScript code, making it do a bit of animation. When the code is complete, you'll package the gadget so others can run it. After finishing this tutorial, you should be ready to start exploring the gadget API.

Note: In general, you should use the Gadget Designer when creating a gadget. You won't need the Gadget Designer for this tutorial because you'll just be tweaking the behavior of an existing gadget.

Contents

• Step 1: Download and Install Google Desktop Software
• Step 2: Make a Copy of the Gadget
• Step 3: Run the Gadget
• Step 4: Edit the Main XML File
• Step 5: Edit the JavaScript File
• Step 6: Run the Modified Gadget
• Step 7: Change the Gadget's Metadata
• Step 8: Package the Gadget
• What to Do Next

Step 1: Download and Install Google Desktop Software

This tutorial uses the Hello World sample that's included in the Google Desktop SDK. To run the sample, you must have Google Desktop installed.

Do this:

1. If you're not already running Google Desktop, download Google Desktop and install it.
2. Download the SDK. This tutorial assumes you have the most recent version of the Hello World sample.
3. Unzip the SDK archive and put it somewhere convenient.

Back to top

Step 2: Make a Copy of the Gadget

Do this:

1. Make a copy of the SDK's api/samples/gadgets/HelloWorld folder and name it MyHelloWorld.
2. Put MyHelloWorld in a convenient place, such as your desktop.

Before modifying the files under MyHelloWorld, you should know something about them.

File Name	Type	Description
en/strings.xml	XML file	Defines strings used by the default, English version of this gadget. To define the "Hello World!" string that this gadget displays, en/strings.xml uses the following code: <HELLO_WORLD>Hello World!</HELLO_WORLD>.
background.png	image	The background of the gadget. Using a PNG image lets this gadget be transparent — whatever's underneath the gadget onscreen is visible through the gadget's corners and shadow.
gadget.gmanifest	Google Desktop manifest file	Specifies the gadget's metadata, such as its ID, version, minimum Google Desktop version, name, and description.
icon_large.gif	image	A 32x32-pixel icon associated with the gadget.
icon_small.png	image	A 24x24 version of the gadget's icon, with transparency.
main.js	JavaScript source file	Implements a click-handling function.
main.xml	XML file	Defines the gadget's appearance and specifies which function handles clicks.

Back to top

Step 3: Run the Gadget

The next step is to run your copy of Hello World, both to make sure it works and to see what it does.

Do this:

1. Open your MyHelloWorld folder.
2. Double-click the gadget.gmanifest file. You should see an installation dialog.
   
   If you have any problems running your MyHelloWorld gadget:
   1. In the SDK's api/samples/gadgets folder, open a sample gadget's subfolder, such as MenuItems.
   2. Double-click the sample gadget's gadget.gmanifest file.
   3. If the sample gadget successfully starts, something is wrong with your copy of Hello World. Make sure MyHelloWorld has all the files shown in the table.
   4. If you can't run the sample gadget, reinstall the latest version of Google Desktop from http://desktop.google.com.
3. Click OK in the installation dialog. You should now see the Hello World gadget, either in the Sidebar (if the Sidebar is visible) or on your desktop.
   

4. Click the text inside the gadget. A dialog appears.
   
5. Close the dialog.
6. Close the gadget by moving your cursor over the gadget and clicking the "x" that appears.
   

Now that you've seen what Hello World does, it's time to make it a little more interesting. In the next couple of steps, you'll change the code so that the text spins around once when the user clicks it.

Back to top

Step 4: Edit the Main XML File

Here's the old code in the main.xml file:

<!-- OLD code -->
<view width="250" height="150">
  <script src="main.js" />

  <img src="background.png" />
  <label x="0" y="60" align="center" width="250" size="15" enabled="true"
    onclick="onTextClick();">&HELLO_WORLD;</label>
</view>

The preceding XML code defines the gadget's display: a view containing a background image and a label that displays "Hello World!". The code also specifies that the gadget has scripting code in the file main.js, and that the onTextClick function (defined in main.js) should handle user clicks on the label.

To spin the text, you'll need to add a bit of code to main.xml. The first thing to add is a name (mylabel) for the label, so that the JavaScript code can change the label's properties. A few other changes are needed to make the spinning look good — specifying the label's position differently and defining the point of rotation with pinX and pinY.

Do this:

1. Open MyHelloWorld/main.xml in a text editor that can handle UNIX-style line endings. (WordPad works; NotePad doesn't.)
2. Edit the file so that it has the following code. (Changes are highlighted in orange.)

<!-- NEW code -->
<view width="250" height="150">
  <script src="main.js" />

  <img src="background.png" />
  <label x="125" y="70" align="center" width="250" size="15" enabled="true"
    name="mylabel" pinX="125" pinY="8"
    onclick="onTextClick();">&HELLO_WORLD;</label>
</view>

Back to top

Step 5: Edit the JavaScript File

Here's the old code in the main.js file:

// OLD code
function onTextClick() {
  view.alert(HELLO_WORLD);
}

This code defines an event handler that displays a dialog. The event handler is called whenever the user clicks the text in the gadget.

Do this:

1. Open MyHelloWorld/main.js in a text editor.
2. Edit the file so that it has the following code. (Changes are highlighted in orange.)

// NEW code
function onTextClick() {
  view.beginAnimation(doRotation, 0, 360, 500);
}
function doRotation() {
  mylabel.rotation = event.value;
}

This code makes the text spin clockwise exactly once, taking half a second (500 milliseconds) to do so. It does this by setting the angle (rotation) of the label multiple times, starting with an angle of 0 degrees and increasing to a final angle of 360 degrees.

The beginAnimation method kicks off the animation by setting up a timer that repeatedly does two things: sets event.value and then calls doRotation. The doRotation function changes the text's angle by setting the label's rotation property to event.value.

Back to top

Step 6: Run the Modified Gadget

Now that you've edited the main.js and main.xml files, you can run your gadget!

Do this:

1. Double-click your gadget's gadget.gmanifest file.
2. Click OK in the installation dialog.
3. Click the text in the gadget.

The "Hello World!" text will spin completely around once, as caught midway through in this figure:

Back to top

Step 7: Update the Gadget's Metadata

Now that your gadget is working, you need to update its metadata. The most important string to change is your gadget's ID. For both your gadget and the original gadget to run at the same time, each one needs to have a unique ID.

Do this:

1. Open MyHelloWorld/gadget.gmanifest in a text editor.
2. Generate a unique identifier for your gadget using a command such as uuidgen, Guidgen.exe, or Uuidgen.exe. If you don't have any of those tools, search the Web for [uuid generator].
3. Change the <id> value in gadget.gmanifest to be the unique identifier you just generated.
4. Optionally change the <author> value in gadget.gmanifest.
5. Save your work.
6. Open MyHelloWorld/en/strings.xml in your text editor.
7. Update strings.xml with the gadget's new name, description, copyright, website, and about information.
8. Save your work.

Back to top

Step 8: Package the Gadget

So far, you've been running your gadget by double-clicking its gadget.gmanifest file. That's fine while you're debugging, but a finished gadget needs to be packaged into a single file for distribution. In this step, you'll create a .gg package — a ZIP archive of the files that define your gadget's appearance and behavior. You can then double-click the .gg file to run the gadget.

Do this:

1. Remove any unnecessary files from the MyHelloWorld folder. For example, remove automatically created backup and Thumbs.db files.
2. Create a ZIP archive of the files and folders that are inside the MyHelloWorld folder. On Windows, you can do this by selecting everything in the MyHelloWorld folder, right-clicking a file, and choosing Send To > Compressed (zipped) Folder.

   Note: The structure of the ZIP file should match the MyHelloWorld folder's structure. For example, gadget.gmanifest and main.xml should be at the top level of the ZIP file, not in a folder.

3. Change the ZIP file's name to MyHelloWorld.gg and put it in a convenient place, outside of the MyHelloWorld folder.
4. Double-click the .gg file. If your gadget starts running, you're done!

Back to top

What to Do Next

If you want to keep on playing with Hello World, here are some ideas:

• Run the gadget and observe what Google Desktop handles automatically:
  • Start the gadget with the Sidebar visible, and then with it hidden. See what happens when you drag the gadget into and out of the Sidebar.
  • Observe what happens to the gadget when it's in the Sidebar and you resize the Sidebar or the gadget.
  • When the gadget is on the desktop, choose different Zoom levels from the gadget's menu.
• Experiment with the background image:
  • Change the background image by substituting a different file for background.png.
  • Delete the background image by removing the <img> element from main.xml. The gadget will still appear, but clicking on the text won't usually work. (A label must be on top of a colored div or an image for the label to detect clicks on its background.)
• Look at the label reference documentation, and then modify MyHelloWorld's label. For example:
  • Play with label properties.
  • Write an event handler or two. For example:
    • Make the text's color change when the cursor hovers over it.
    • Move the text whenever the user right-clicks.
• Look at the view reference documentation, and then change the resize behavior of MyHelloWorld's view.
• Add sound.
• Translate Hello World into another language. You can find translation information in Internationalization.

Here are some ideas for when you're ready to move on from Hello World:

• Modify another gadget.
• Follow another tutorial.
• Read Creating a Gadget.
• Browse the Gadget API Reference.

Back to top