| Sign in | Code Home

Google Desktop APIs (Labs)

Frequently Asked Questions

    Getting Started

  1. How do I get started developing gadgets?
  2. Where can I find the Developer Guide?
  3. Where can I go for help?
  4. What platforms do Desktop gadgets run on?
  5. Is there an IDE available?
  6. How can I easily run my gadget while I'm developing it?
  7. How can I learn from existing gadgets?
  8. How do I package and distribute my gadget?
  9. What about [your favorite language here]?
  10. Gotchas!

    11. Gadget Submissions

  11. What are the allowed file types?
  12. The submission form keeps rejecting my gadget
  13. Whoops! I entered an incorrect email address in the submission form.
  14. When will my gadget appear in the Desktop directory?
  15. How do I update my gadget?
  16. What do I do if my download URL changes?
  17. How do I change my gadget's info in the gadget directory?
  18. How do I change my screenshots?
  19. I've submitted a web-based gadget to the iGoogle Content Directory. Will it also be populated in the Desktop directory?
  20. My gadget listing has disappeared!

    21. Using the API

  21. Can I build my gadget using HTML?
  22. Can I disable or squelch the warning dialog?
  23. Can I force my gadget to startup inside or outside the sidebar?
  24. Events handlers like onclick or onmousemove aren't working
  25. How do I generate a GUID or UUID?
  26. Why can't I load or read a file?
  27. Can I distribute my gadget or plugin for commercial use?
  28. How can I create gadget that reads an RSS feed?
  29. How do I open up a webpage in a browser?
  30. Can I read or write to the clipboard?
  31. How can I test web-based gadgets in Google Desktop?
  32. Can Google Desktop auto-update my gadget for my users whenever I release new versions?
  33. How can I use custom fonts?
  34. How do I iterate a collection of UI elements?

    35. Developer Community

  35. How do I update my details on the Developer Hall of Fame?
  36. How is the Hall of Fame ranking calculated?
  37. How often do you update the Hall of Fame rankings?
  38. What are these "New gadget submitted" posts in the developer group?
  39. What is an API Guru?
  40. What is a Student Ambassador?

Getting Started

How do I get started developing gadgets?

First, follow the Modifying Hello World tutorial. It leads you through downloading the SDK, modifying a sample gadget's XML and JavaScript files, and packaging the modified gadget. After finishing the tutorial, you should be ready to start exploring the Desktop gadget API.

Be sure to have an up-to-date copy of the Google Desktop SDK. In it you'll find many sample gadgets demonstrating how to use the API, plus helpful tools such as the Gadget Designer.

Once you're ready to start creating your own gadgets, you can find most of the information you need in the API documentation and the development articles. The documentation includes everything from tutorials to API references. The ever-growing collection of articles has answers to commonly asked questions, plus how-to pages and recommendations for good gadget-writing practices.

Finally, make a habit of visiting the Google Desktop APIs blog, where you can find the latest news for Desktop gadget developers; don't miss the Tips.

Where can I find the Developer Guide?
The Developer Guide can be found at http://code.google.com/apis/desktop/docs/gadgetapi.html.
Where can I go for help?

If you have any questions, visit our developer discussion group.

Search past messages to see if your problem has already been discussed or post a new message to request help.

What platforms do Desktop gadgets run on?

Currently, Desktop gadgets run on Windows, Mac, and Linux. Therefore, aim at all times to write cross-platform gadgets and follow the instructions in the Writing a Cross-Platform Gadget doc.

Is there an IDE available?

Yes, a Gadget Designer is available in the SDK.

The Google Desktop Gadget Designer is an integrated development environment (IDE) that lets you quickly prototype or modify your gadget's UI and test its performance.

Be sure to check out the documentation and tutorial.

How can I easily run my gadget while I'm developing it?

Double-click (i.e. execute) the gadget.gmanifest file located in your gadget's root directory. This starts the gadget.

If you happen to be using the Gadget Designer IDE, you can preview the gadget instantly within the Designer.

How can I learn from existing gadgets?

Perhaps you've found a gadget you really like and want to learn how a certain feature was implemented.

The directory My Documents\My Google Gadgets on your machine contains all the script-based Google Desktop gadgets you've installed.

These .gg files are actually zip archives. Unzip the .gg file (you may need to change the extension to .zip first if your archive utility requires it), and you'll be able to see all the source files.

Keep in mind not all gadgets are the script-based .gg type. Some gadgets you have installed may be older, non-script gadgets or web-based gadgets.

How do I package and distribute my gadget?

Google Desktop gadgets are packaged as .gg files.

A .gg file is simply a zip archive with a .gg extension. You can zip up all your gadget files and subdirectories and then rename the zipped file so it has the .gg suffix.

Or you can use the Gadget Designer tool to build the package for you. The menu command for this is "Project -> Build Package".

To submit your gadget, visit http://desktop.google.com/pluginsubmit.

Your gadget must be approved before it shows up on the directory, so be sure to follow all the listed guidelines.

What about [your favorite language here]?

JavaScript is the preferred language for Google Desktop gadgets. VBScript gadgets do exist, but are uncommon.

It is possible to write gadgets in C#, VB.NET, C or C++, but there are convincing reasons not to:

  • Remember, gadgets can run on Linux and Mac. Only JavaScript gadgets are supported on those platforms.
  • You'll need to be familiar with COM/ActiveX. This requirement further complicates .NET development, as you will need to write COM interop code. In addition, you will need to register with the Google Desktop registrar and implement the necessary COM interfaces.
  • It takes longer to write a non-script gadget. Development cycles will require a compilation and DLL registration step.
  • The Google Desktop team has phased out non-script gadget support. Finding support and sufficient documentation will be difficult. Also, there are fewer existing gadgets and developers to learn from.
  • You will need to write your own installer program. This leads to another point: users are less likely to try your gadget since it requires they run an installer.
  • If you need advanced functionality (system calls, Win32 API) you can always create a hybrid gadget.

There are no plans to support Java.

Gotchas!
  • Gadget icon dimensions are 32x32 for the large icon and 24x24 for the small.
  • Your gadget must have a unique ID defined in the <id> tag of gadget.gmanifest. So be careful if you are creating a new gadget based off an old gadget; you won't be able to run both at the same time!
    You can generate an ID 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].
  • Watch out for Thumbs.db or backup files in your .gg file.
  • In general, UI objects should specify a width and height.

Gadget Submissions

What are the allowed file types?

For submission type Desktop gadget, you can only submit .gg files. Executables (.exe) or zip files are no longer accepted.

Executables (.exe) or zip files are allowed for types Indexing Plug-in and Separate application that integrates with Google Desktop.

The submission form keeps rejecting my gadget
Fix any problems reported by the webpage. If you have trouble understanding the messages, please read the gmanifest documentation. Most problems are related to an invalid gmanifest.
Whoops! I entered an incorrect email address in the submission form.
Send an email to gd-developer AT google DOT com.
When will my gadget appear in the Desktop directory?
Assuming your gadget does not have any issues, please wait up to four weeks for it to appear in the directory. If your gadget hasn't been published after four weeks, please send an email to gd-developer AT google DOT com.
How do I update my gadget?

To update your gadget, simply re-upload the new version to the same URL. Also, make sure to increment your version number so that it appears in the Updates section of users' Add Gadgets dialog.

What do I do if my download URL changes?
If you've changed the download link for your gadget, please send an email to gd-developer AT google DOT com from the same email address you specified in the submission form.
How do I change my gadget's info in the gadget directory?

To change the information for your gadget, simply modify the metadata in your hosted gadget's gmanifest file. Our server will pick up changes to your hosted gadget file and update the displayed information in the directory. To read more about what information is contained in the gmanifest file, please visit the following page:

http://code.google.com/apis/desktop/docs/script.html#gmanifest

How do I change my screenshots?

Once your gadget is published, you can update its images in two ways. You can change the values of thumbnailUrl and screenshotUrl in the gmanifest for your gadget's published .gg file. Or you can just update the images, while retaining the same URLs.

I've submitted a web-based gadget to the iGoogle Content Directory. Will it also be populated in the Desktop directory?

Gadgets are brought into the listings depending on their popularity in iGoogle and usability in Google Desktop.

By usability, we mean if your gadget does not work well in Google Desktop for whatever reason, it won't be added.

My gadget listing has disappeared!

If a gadget's download link is broken for several consecutive weeks, the gadget may be removed from the gallery automatically. We cannot restore the gadget for you. Please submit it again — and fix the download link, of course.

Using the API

Can I build my gadget using HTML?

No, the gadget API uses XML and JavaScript. It is not HTML based.

If you need to display HTML in your gadget, consider using an HTML details view or developing an web-based gadget, which are supported by Google Desktop.

Can I disable or squelch the warning dialog?
No.
Can I force my gadget to startup inside or outside the sidebar?
There is currently no API to specify startup location.
Events handlers like onclick or onmousemove aren't working

In order for an element to process events, its enabled property must be set to true. For example, here is an image that properly sets up an onclick handler: 

  <img src="red.jpg" enabled="true" onclick="onClick();" />
How do I generate a GUID or UUID?

Please refer to this discussion:

http://groups.google.com/group/Google-Desktop-Developer/browse_thread/thread/92cd05a05974b385/fbd986c14305fe24

Why can't I load or read a file?

You must escape the backslash character in JavaScript strings. For example: 

var path = "c:\\foo\\bar.txt";
Can I distribute my gadget or plugin for commercial use?

According to the Google Desktop API Terms & Conditions, any Plug-Ins (or gadgets) created using the API can be distributed or sold for commercial use:

"You may use, display and/or distribute your Plug-Ins commercially as well as non-commercially. In any case, your Plug-Ins must comply with these API Terms and Conditions, including the Prohibited Actions section below."

However, Google Desktop itself or its APIs cannot be distributed or sold for commercial use without prior written consent from Google:

"However, the APIs are made available to you for your non-commercial use only, meaning, that you may use it at work or at home, but, except for distributions for internal business and/or personal use to your employees or contractors in compliance with the Google Desktop Terms and Conditions and the APIs Terms and Conditions, you may not display, distribute or otherwise make Google Desktop or the APIs available to any third party without Google's prior written consent."

How can I create gadget that reads an RSS feed?
Check out the Creating an RSS gadget tutorial. You'll have a working RSS gadget within minutes.
How do I open up a webpage in a browser? 
framework.openUrl('http://desktop.google.com/');
Can I read or write to the clipboard?
Not at this time.
How can I test web-based gadgets in Google Desktop?

To manually add an web-based gadget to the Google Desktop sidebar:

  1. Open the Add gadgets dialog
  2. Enter the full URL of the gadget into the search box. For example, http://coolgadgets.googlepages.com/krad-gadget.xml

    The search box has a limit of 100 characters. If your URL exceeds that, you can use a service such as http://tinyurl.com/ as a workaround.

  3. Execute the search, and the gadget should show up in the results

NOTE: The gadget must be publicly hosted. This will not work if the gadget is on your file system, internal webserver, etc. Since the gadget already needs to be publicly hosted to work with the iGoogle page, this shouldn't be an issue.

Can Google Desktop auto-update my gadget for my users whenever I release new versions?
Not at this time.
How can I use custom fonts?

The DigitalClockFont sample in the SDK uses a custom font to achieve the LCD number effect; the comments within the code may provide some insight.

Also, refer to the section of the following document where the <install> tag is discussed:

http://code.google.com/apis/desktop/docs/script.html#gmanifest

How do I iterate a collection of UI elements?
Please refer to this tip on the developer blog.

Developer Community

How do I update my details on the Developer Hall of Fame?

Send an email to gd-developer AT google DOT com with the following:

  • Name
  • Location (e.g. Montreal, Quebec, Canada)
  • Website
  • Short bio
  • Quote (e.g. "I think therefore I am")
  • 100x120 image of yourself
How is the Hall of Fame ranking calculated?

This is a secret, more tightly guarded than the PageRank algorithm. Only one person on the planet knows, and he/she will hold the secret to the grave.

Some HOF optimization consultants speculate that the ranking is based on the following:

How often do you update the Hall of Fame rankings?
Approximately every two weeks.
What are these "New gadget submitted" posts in the developer group?

These are gadgets that have submitted but have not been released yet. Please feel free to try them out and assist the author. Or just use them to spy on the competition!

DISCLAIMER: Google has not tested or verified the features or security of the gadgets. Please direct all questions to the software's author.

What is an API Guru?

API Gurus watch the developer group, answering questions and providing valuable feedback.

Interested in becoming an API Guru? Send an email to gd-developer AT google DOT com.

What is a Student Ambassador?

Student Ambassadors have volunteered to be the contact point for Desktop developers at a particular school or university. If you like organizing events such as programming contests and technical talks, becoming an ambassador is a great opportunity to help your fellow students and develop leadership skills.

Interested in becoming a Student Ambassador? Send an email to gd-developer AT google DOT com.