Using Gadget Designer

With the Gadget Designer application for Windows, you can easily create a Desktop gadget from scratch. Gadget Designer is also useful for modifying existing gadgets, such as when you need to change a gadget's user interface or repackage a gadget.

This tutorial leads you through the process of creating a simple gadget. After completing this tutorial, you should be comfortable using Gadget Designer's major features.

Contents

• Step 1: Download and Install Software
• Step 2: Create a New Gadget
• Step 3: Add a UI Element
• Step 4: Add Event Handling
• Step 5: Get Debugging Output
• Step 6: Customize Strings and Settings
• Step 7: Package the Gadget
• What to Do Next

Step 1: Download and Install Software

Do this:

1. If you're not already running Google Desktop, download Google Desktop and install it.

   Note: During the installation process, a window asks you to choose desktop features. You can change most of the default settings (especially "Improve Google Desktop"!), but make sure the checkbox under Sidebar with Gadgets stays selected.

2. Download the SDK.
3. Unzip the SDK archive and put it somewhere convenient.

Back to top

Step 2: Create a New Gadget

Do this:

1. Launch Gadget Designer:
   1. Navigate to the api\tools folder of the SDK.
   2. Double-click the designer_en.exe file.
      The Gadget Designer application should appear.

   Note: If you see a message warning that the application failed to start because a .dll file could not be found, unzip the SDK again. Then make sure you execute the copy of designer_en.exe that is in the api\tools folder of the unzipped SDK, so that Gadget Designer can find all the files it needs.

2. Choose File > New Gadget...
   A file dialog appears.
3. Choose a name and location for your new gadget folder.
   For example, go to your desktop folder, type My New Gadget in the File name field, and click the Save button.

   Gadget Designer creates a folder for your gadget and populates it with files and folders your gadget is likely to need. A typical setup is shown to the right. If you look at the same folder outside of Gadget Designer, you can see that the Gadget Settings item represents a file named gadget.gmanifest.

4. In Gadget Designer, choose the main.xml tab (at the top of the display area) and then the Source tab (at the bottom).
   You should see XML source code for the gadget.

   <view height="150" width="250" onopen="view_onOpen()">
       <img src="stock_images\background.png"/>
       <script src="main.js" />
   </view>
   

   
   This automatically generated code creates the gadget's main view, which has a size of 250x150 pixels. The view contains a default background image and refers to JavaScript code — specifically, to an event-handling function named view_onOpen() — in a file named main.js. You'll edit main.js later.
5. Choose View > Preview or press F5.
   The gadget runs in the display area at the center of Gadget Designer. In addition to the background image, the gadget has window controls. These controls don't necessarily match what you see when the gadget runs in the sidebar or on the desktop, but they give you access to the gadget's menu.

The Preview tab is a good way to check on your gadget. However, to see how your gadget behaves and looks under normal running conditions, you still need to run the gadget in Google Desktop. You can install and run your gadget in Google Desktop by double-clicking the gadget.gmanifest file in your gadget's folder.

Back to top

Step 3: Add a UI Element

Gadget Designer lets you drag user interface (UI) elements such as labels and buttons into your gadget. You can then use the Properties pane to edit each element's properties so that it looks the way you want.

Do this:

1. In Gadget Designer, choose the main.xml tab (at the top) and then the Designer tab (at the lower left).
   You should see a row of UI elements just below the top tabs.
2. Drag a label element into the center of the gadget.
   
   
   
   
   
   After you add the label, the main.xml tab has an asterisk (*) indicating that the gadget has changed and should be saved.
3. Save the gadget, using File > Save or Ctrl+S.
   The asterisk in the main.xml tab disappears.

   Note: Save often! If you make a mistake, you can use Edit > Undo (or Ctrl+Z) to undo your changes. If you undo too much, use Edit > Redo (or Ctrl+Y) to reapply changes.

4. Use the Properties pane to change the label:
   1. If the label isn't already selected, select it.
      To select the label, either click it in the display area or click the label item in the Elements pane. The Properties pane shows the values of the selected element's properties. For example, the label's align property is initially left.
   2. Click the A-Z icon in the Properties pane to sort the properties alphabetically.
      
   3. Set the value of each of the following label properties.
      
      

      Property	New Value	Explanation
      align	center	Centers the text within the label.
      innerText	Hello World	Sets the text displayed by the label.
      width	100%	Makes the label as wide as the entire gadget.
      x	0	Positions the label at the left edge of the gadget.

      
      To set a property's value, just find the property in the Properties pane, click the cell containing the property's value, and enter the new value. For more information on label properties, see the API reference documentation for label.
5. Run the gadget in the display area by clicking the Preview tab or pressing F5.
   Your work is saved, and you should see an updated view of the gadget.
6. Look at the gadget's code by clicking the main.xml tab and then the Source tab (at the bottom).
   The source code should look something like this:

   <view height="150" width="250" onopen="view_onOpen()">
     <img src="stock_images\background.png"/>
     <label height="16" name="label1" width="100%" x="0" y="58" align="center"
      >Hello World
     </label>
     <script src="main.js" />
   </view>
   

   
   The only difference from the default code is the new label element (shown in orange) that you added.

Besides changing the XML through direct manipulation, as you did in this step, you can also edit the text of the main.xml file in Gadget Designer.

Caution: Don't put comments or JavaScript in main.xml. Because Gadget Designer regenerates the XML, any non-XML markup disappears.

Back to top

Step 4: Add Event Handling

In this step, you add event-handling code to make your gadget respond to user clicks.

Do this:

1. In Gadget Designer, choose the main.xml tab and then the Designer tab.
2. Double-click the gadget's label in the display area.
   A new tab opens that contains the code for the gadget's JavaScript file (main.js), and that includes the skeleton of a function (label1_onclick()) to handle click events. If you go back to the main.xml tab and look at the label's properties, you can see that the enabled property is now set to True, and the onclick property is set to label1_onclick().
3. Add the code shown in orange to main.js:

   function view_onOpen() {
   }
   
   function label1_onclick() {
     view.alert("hello world!");
   }
   

   
   This code responds to click events by bringing up a dialog box containing the text, "hello world!".
4. Save your changes (Ctrl+S).
5. Click the Preview tab or press F5.
6. Click the label.
   You should see the following dialog.

Clicks are just one kind of event supported by all elements. To learn about other events such as focus events, read the basicElement API reference. Gadget Designer makes it especially easy to register handlers for click events, but it's simple to register any other kind of event handler. Just make sure the element's enabled property is true, add a function to main.js that reacts to the event, and connect the function by setting the value of an event property (such as onfocusin) in main.xml.

Back to top

Step 5: Get Debugging Output

Your gadget can produce debugging strings using the gadget.debug object. The Debug Console lets you view these strings

Do this:

1. Return to viewing main.js, either by clicking the main.js tab or by double-clicking main.js in the Gadget Explorer.
2. Add the code shown in orange to the view_onOpen() method:

   function view_onOpen() {
     debug.info("starting...");
   }
   

   
   This code creates a message whenever the gadget starts up and is in debug mode. Ordinary users won't see this message.
3. Save your changes (Ctrl+S).
4. In the View menu, make sure the Debug Console item is selected.
   
   
   A series of buttons and a text area appear at the bottom of the Gadget Designer window.
   
5. Make sure the Info checkbox is selected.
6. Click the Preview tab or press F5.
   At the bottom of the Gadget Designer window you should see a line containing the message level ("Info: ") and the string that you specified to the debug.info method ("starting..."). If Show message times is selected, the line also contains the time when the message was created.
   

A gadget's debugging strings are generated only when the gadget is in debug mode. To execute a gadget in debug mode, preview the gadget in Gadget Designer or double-click the gadget's gadget.gmanifest file.

Back to top

Step 6: Customize Strings and Settings

In this step, you customize your gadget's standard strings — no more "New Gadget" in window titles! You also specify settings for the gadget.gmanifest file.

Do this:

1. In the Gadget Explorer (at the left of the main window), open the en folder and double-click strings.xml.
   A new tab named strings.xml appears, and the editable contents of the strings.xml file appear in the display area. This file defines default strings for the elements GADGET_NAME, GADGET_DESCRIPTION, and GADGET_ABOUT_TEXT, which are used for gadget settings.
   
2. Edit strings.xml to customize the strings for this gadget, as shown below in orange.

   <strings>
     <GADGET_NAME>Hello World</GADGET_NAME>
     <GADGET_DESCRIPTION>The canonical first program</GADGET_DESCRIPTION>
     <GADGET_ABOUT_TEXT>Hello World
   © 2008
   This gadget puts up an alert when you click the label.</GADGET_ABOUT_TEXT>
   </strings>
   

   Defining user-visible strings in strings.xml helps make your gadget easier to translate.
3. Save your changes (Ctrl+S).
4. Click the Preview tab or press F5.
   The title of the gadget shown in the display area changes to "Hello World". If you open the gadget's menu and choose About..., you see the new About text that you specified.
5. Double-click the Gadget Settings item in the Gadget Explorer or press F3.
   A window appears that has contents like this:
   
   The Name, Short Description, and About Dialog Text fields are the only ones that can refer to elements (such as GADGET_NAME) defined in the strings.xml file. All other fields must have either no value or the actual string value. See The about element for details.
6. Enter values for at least the Author and Email fields. Examples: Jo Wu, jowu.feedback+MyNewGadget@gmail.com
   These fields correspond to the required author and authorEmail elements in the gadget.gmanifest file. Providing good values for these elements helps you get credit and feedback for all of the gadgets you develop! For information about these and other fields, see What Goes into a gadget.gmanifest File.

You're almost done.

Back to top

Step 7: Package the Gadget

A finished gadget needs to be packaged into a single file for distribution. In this step, you use Gadget Designer to create the gadget's .gg file. Users can then double-click the .gg file to run the gadget.

Do this:

1. Outside Gadget Designer, go to the folder stock_images.
2. Delete every file from stock_images except for background.png
   Removing unnecessary files makes your gadget's .gg file smaller, reducing gadget download time.
3. Back in Gadget Designer, choose Gadget > Build Package or press F7.
   A dialog appears, telling you where Gadget has placed your gadget's .gg file.
4. Outside Gadget Designer, move the .gg file out of your gadget's folder, and double-click the .gg file to run the gadget.
   Your gadget should run and look something like this:

Back to top

What to Do Next

This tutorial introduced you to all the major features of Gadget Designer, from creating a gadget to implementing, debugging, and packaging it.

If you want to keep on playing with the gadget you just created, here are some ideas:

• Experiment with debugging output. For example, try using debug.error() and debug.warning(), and try unselecting checkboxes in the Debug Console.
• Use api\tools\gdpconsole.exe instead of Gadget Designer to view debugging output. Remember to run the gadget in debug mode by double-clicking the .gmanifest file.
• Test your gadget on a Mac.

Here are some ideas for when you're ready to move on from this gadget:

• If you haven't already completed the Modifying Hello World tutorial, do so. Don't miss that tutorial's What to Do Next section.
• See the Gadget Design and Testing guidelines.
• Read articles.

Back to top