Tip: Build a quality gadget

Thursday, May 07, 2009 at 3:48 PM

What makes a quality gadget?

• Platform specification: If you create a gadget only for Windows, make sure that the gadget is not installable on Mac or Linux:
  

  <windows minimumGadgetHostVersion="5.1.0.0"/>  <!-- Windows is supported -->
  <mac supported="no"/>                          <!-- No support for Mac -->

  For more information, check the gadget.gmanifest documentation.


• Good performance: The gadget should make optimum use of the hardware and operating system services. The efficiency of software can usually be greatly improved by an intelligent choice of high-level algorithms, rather than using local "tricks" or optimizations that can lead to maintenance problems. Factors that may be of interest are response time and memory requirements.
  
  
• Robustness: The gadget should continue to function in non-standard conditions such as incorrect user input. For example, when the user types something wrong, you can warn the user with a basic message box.
  
  
• Appropriate interface: The gadget should be friendly and inviting to users. The design and choice of the interface should take into account the needs and capabilities of the users. Many times, gadget features are not utilized because the interface is difficult.
  
  
• Documentation: The gadget must link to a website that provides support and information about the gadget. On the website, you can write detailed descriptions about what the gadget can do. And don’t forget to display your email address so the users can easily provide feedback about your gadget, offer to translate it, or report a bug. Try to always include a page with frequently asked questions. One good idea is to add a YouTube video about your gadget on the website to show what it can do.
  

Posted by Stefan Van Damme, Gadget Developer

Tip: Provide a better About dialog

Friday, March 13, 2009 at 9:35 AM

What information must be in a gadget's About dialog? The About dialog certainly needs to display the gadget name. It should also contain:

• The gadget creator's name (your name or your company's name)
  
• A short description of what the gadget can do
  
• The gadget's license, if any (for example, CC-License or Apache License)
  

Optionally, you can add information such as:

• The version number of the gadget
  
• A list of features introduced in this version of the gadget
• A link to your website, so happy customers can get more gadgets from you or contact you

Here's an example of a good About dialog in my Fast shutdown gadget.

Posted by Stefan Van Damme, Gadget Developer

Tip: Use keyboard shortcuts in the Gadget Designer

Monday, February 23, 2009 at 9:48 AM

When writing code in the Google Desktop Gadget Designer, you most likely have used the Ctrl+C and Ctrl+V keyboard shortcuts to copy and paste text.

Here are some other shortcuts to work faster in the Gadget Designer. They work only while editing text such as JavaScript and XML files.

Ctrl+D	Inserts a copy of the current line below the current line
Ctrl+L	Deletes the current line
Ctrl+T	Swaps the current line and the line above it
Ctrl+[0-9]	Switches the current tab. For example, if the Preview window is positioned in the second tab, Ctrl+2 switches to that tab.

Posted by Stefan Van Damme, Gadget Developer

Tip: Automatically update gadget screenshots

Monday, November 03, 2008 at 11:47 AM

When you submit your gadget, you specify URLs for large and small screenshots of the gadget. These screenshots represent your gadget in listings such as the Add gadgets window, online gadget directories, and the web page that's automatically generated for each gadget.

Unfortunately, there was no direct way to update these locations should they ever change — until now. This tip tells you how to update the screenshot URLs.

Add these tags to the gadget.gmanifest of your published .gg file:

<about>
  ...
  <thumbnailUrl>http://mysite.appspot.com/80x60_screen.png</thumbnailUrl>
  <screenshotUrl >http://mysite.appspot.com/300x255_screen.png</screenshotUrl>
  ...
</about>

The gadget gallery has the smarts to pick up these changes and use the URLs you specify to update the images in the gallery. Check out the gadget.gmanifest documentation for more details.

Just a reminder, the small screenshot should be 80x60 pixels. Also, be sure to take a look at this classic tip about submitting better screenshots.

Posted by James Yum, Developer Programs Engineer (Google Desktop Team)

Tip: Extract files from the gadget package

Wednesday, October 08, 2008 at 11:58 PM

Did you know that on Windows you can extract a file that's packaged within your Desktop gadget? The following code extracts a file (called sample.xml in this example) to the temporary folder.

  var tempFile = gadget.storage.extract("sample.xml"); // extract the file
  debug.trace(tempFile);  // tempFile contains the path of the file

All temporary files created by gadget.storage.extract are cleaned up automatically when the gadget is closed.

Note: Only on Windows do Desktop gadgets have access to the file system.

Posted by Stefan Van Damme, Gadget Developer

Tip: Put a gadget in its place

Thursday, October 02, 2008 at 10:34 AM

Help people find your gadget by specifying its category. In your gadget.gmanifest, add a <category> tag containing one or two categories that describe the gadget. Possible values: communication, finance, fun_games, google, holiday, lifestyle, news, sports, technology, tools. Example:

<about>
  <version>4.8.l5.16</version>
  ...
  <category>news,sports</category>
</about>

The gadget directory automatically picks up changes such as these every so often by looking at your hosted gadget files. Go ahead and update your gadgets, and they will be placed in the categories you want.

Have a tip you'd like to share? Send it to gd-developer AT google DOT com. To see all tips, choose the Tips label.

Posted by James Yum, Developer Programs Engineer (Google Desktop Team)

Tip: Improve resizing performance

Wednesday, September 24, 2008 at 8:08 AM

Posted by Benjamin Schirmer, Google Desktop Intern

If your gadget has lots of visual elements, resizing might get very slow. This happens because onsize is triggered often when the user resizes your gadget. Use code like this to improve the performance of resizing:

var resizeTimeout = null;

function view_onSize() {
  clearTimeout(resizeTimeout);
  resizeTimeout  = setTimeout(resizeGadget, 10);
}

function resizeGadget() {
  debug.info('Now I really resize everything');
  ... code to resize and relayout the gadget's contents ...
}

The resizeGadget() function is called only when the user is either finished with resizing or doesn't resize for a few milliseconds. The result is fewer redraws of your gadget and a smoother resizing experience for your user.

Have a tip you'd like to share? Send it to gd-developer AT google DOT com. To see all tips, choose the Tips label.

Tip: Use the string-based listbox methods

Friday, September 05, 2008 at 8:08 AM

Posted by James Yum, Developer Programs Engineer

If you have a listbox or combobox that displays text strings, consider using methods such as appendString() and removeString() instead of appending item elements. Read the 5.5 release notes to see the available methods and examples of their use.

Here is an example that fills a listbox named statesListbox:

var states = ['Alabama', 'Alaska', ... ];

for (var i = 0; i < states.length; ++i) {
  statesListbox.appendString(states[i]);
}

// We are not allowed to ship to California.
statesListbox.removeString('California');

Have a tip you'd like to share? Send it to gd-developer AT google DOT com. To see all tips, choose the Tips label.

Tip: Detect gadgets running in Linux

Thursday, August 21, 2008 at 10:18 AM

Posted by James Yum, Developer Programs Engineer

If you want to detect a Linux user, look for telltale signs such as stacks of O'Reilly books, an anti-MS worldview, and a stuffed penguin collection.

Or you can do this:

function isLinux() {
  return framework.runtime.osName == 'Linux';
}

Have a tip you'd like to share? Send it to gd-developer AT google DOT com. To see all tips, choose the Tips label.

Tip: Embed an SQLite3 database

Thursday, July 17, 2008 at 4:09 PM

Posted by Benjamin Schirmer, Gadget Developer

While saving into the options object is very easy, you sometimes need more power and storage. Here is a tip on how to use an SQLite3 database in a Windows-only gadget.

The first thing you need is the SQLite3 ActiveX object from http://www.assembla.com/wiki/show/litex. Just download the zip archive in the files section. The DLL file is called sqlite3.dll and is in the \litex\bin\ folder of the zip archive. Copy sqlite3.dll into your gadget's root folder. Then open your gadget's gadget.gmanifest in your favorite editor.

Add this after the <about> tag:

  <install>
    <object name="sqlite3"
      clsid="3E22694D-7B92-42A1-89A7-668E2F7AA107"
      src="sqlite3.dll"/>
  </install>

You can then use JavaScript to create a new instance of the sqlite3 object, as shown in the following code:

  var sqlite = new sqlite3();
  debug.trace("SQLite3 version: " + sqlite.version(true));
  sqlite.open(":memory:");  // Open in memory as opposed to disk.
  sqlite.execute("CREATE TABLE Test(a);");
  sqlite.execute("INSERT INTO test VALUES (4);");
  sqlite.close();

Take a look at the LiteX documentation to find all supported functions.

Have a tip you'd like to share? Send it to gd-developer AT google DOT com. To see all tips, choose the Tips label.

Tip: Submit better screenshots

Monday, July 14, 2008 at 11:56 AM

Posted by James Yum, Developer Programs Engineer (Google Desktop Team)

They say a picture is worth a thousand words, but a screenshot can be worth a thousand users. You've worked so hard to create a cool gadget; don't let a bad screenshot get in the way of its adoption.

As you probably know if you've submitted a gadget, the directory requires one small screenshot and one large screenshot of your gadget.

The large screenshot is fairly straightforward and can simply demonstrate the gadget in action, as the following image shows.



Small screenshots are a bit trickier because of the limited area. The best advice I can offer is that the screenshot doesn't need to be 100% faithful. The important thing is to attract attention, while still giving an idea of what the gadget looks like.

Let's look at a few small screenshots from the directory.

	This is just a cropped version of a full screenshot. Most often, this kind of cropping is a sign of laziness. A scrunched picture like this one is an ineffective way to draw in users.
	If you're going to crop the screenshot, try to make the screenshot creative, like this one.
	Here's another good screenshot, a scaled-down version of a full screenshot on an attractive gradient background. We may not all be graphic wizards, but we should all be able to come up with something similar.

By taking a look at the gadget directory, you can see what works and what doesn't for screenshots.

Have a tip you'd like to share? Send it to gd-developer AT google DOT com. To see all tips, choose the Tips label.

Tip: Detect user idleness

Monday, June 30, 2008 at 3:34 PM

Posted by James Yum, Developer Programs Engineer (Google Desktop Team)

You can use framework.system.user.idle to detect whether the user is idle and might be away from the computer.

When the user is idle, you can choose to skip operations such as HTTP requests or audio playback:

if (framework.system.user.idle) {
  // User is idle/away. No need to re-retrieve the content.
} else {
  retrieveContent();
}

Have a tip you'd like to share? Send it to gd-developer AT google DOT com. To see all tips, choose the Tips label.

Tip: Use captions to label your controls

Monday, June 23, 2008 at 3:36 PM

Posted by James Yum, Developer Programs Engineer (Google Desktop Team)

Some controls have a property called caption that conveniently acts as a built-in label for the control. Let's look at some examples:

	<button name="playButton" x="30" y="20" width="64" height="22" image="button_up.png" downImage="button_down.png" overImage="button_over.png" caption="Play" font="Arial" size="9" color="#000000" />
	<radio name="jazzRadio" x="30" y="60" width="60" image="radiobutton.png" checkedImage="radiobutton_checked.png" caption="Jazz" font="Arial" size="9" color="#000000" />
	<checkbox name="classicalCheck" x="30" y="90" width="90" image="checkbox_unchecked.gif" downImage="checkbox_click.gif" checkedImage="checkbox_checked.gif" checkedDownImage="checkbox_click.gif" overImage="checkbox_hover.gif" caption="Classical" font="Arial" size="9" color="#000000" />

You can use all of the properties of label, such as bold and italic, to style the caption. The text labels are considered as part of the control's clickable area, as you'd expect.

Have a tip you'd like to share? Send it to gd-developer AT google DOT com. To see all tips, choose the Tips label.

Tip: Get the source element of an event

Tuesday, June 17, 2008 at 2:56 PM

Posted by Teodor Filimon, Gadget Developer

Sometimes it's very useful to get a reference to the UI element that triggers a certain event. This way, instead of writing individual event-handler functions for every element, you can just work with event.srcElement.

Let's say we have a couple of labels for which we want to create a hover effect. Simple stuff: when the mouse moves over a label, that label's text turns white; when the mouse exits, the text turns black. We can accomplish this behavior by using one function to handle both labels' onmouseover events and another to handle their onmouseout events. The functions look like this:

function _onMouseOver(){
 event.srcElement.color="#FFFFFF";
}

function _onMouseOut(){
 event.srcElement.color="#000000";
}

You can see the results in this sample gadget.

Have a tip you'd like to share? Send it to gd-developer AT google DOT com. To see all tips, choose the Tips label.

Tip: Detect whether Flash is available

Monday, June 09, 2008 at 1:58 PM

Posted by Benjamin Schirmer, Gadget Developer

Before you a embed a Flash movie into your gadget, check whether the Adobe Flash plugin is indeed available on the user's machine. Here's a function that returns true if you can use Flash.

function flashAvailable() {
  if (framework.system.machine.manufacturer == "Apple") {
    // It's pretty safe to just assume that Flash is on the Mac;
    // it's preinstalled with Safari.
    return true;
  }

  var flashCode = "<object x='0' y='0' name='flashCheck'
visible='false' classid='progid:ShockwaveFlash.ShockwaveFlash'
width='1' height='1'><param name='movie' value='none.swf' /></object>";

  var tmpEle = view.appendElement(flashCode);
  if (tmpEle == null) {
    return false;
  } else {
    view.removeElement(tmpEle);
    return true;
  }
}

Have a tip you'd like to share? Send it to gd-developer AT google DOT com. To see all tips, choose the Tips label.

Tip: Write good descriptions

Tuesday, May 27, 2008 at 10:31 AM

Posted by James Yum, Developer Programs Engineer (Google Desktop Team)

The <description> tag in the gadget.gmanifest provides the content that's displayed in the gadget installation dialog.

Perhaps more importantly, that content is also used for the description text in the gadget gallery and the Add gadgets dialog, which people read when browsing for gadgets. You can see this description highlighted in the following screenshot.



Since this description is used in the gallery, it needs to be clear and correct. A bad description can confuse users or scare them away. Before you submit your gadget, run the description text through a spell checker. Also, try to envision it through the eyes of a user. If you need help, feel free to consult the developer group, just as you would for a technical issue.

Have a tip you'd like to share? Send it to gd-developer AT google DOT com. To see all tips, choose the Tips label.

Tip: Use opacity to highlight buttons

Wednesday, May 07, 2008 at 8:52 AM

By Stefan Van Damme, Gadget Developer

Using opacity, you can make buttons that light up when you mouse over them. This effect can improve the usability and appearance of a gadget that has several buttons close together.



Implementing this opacity effect for a button takes just two easy steps:

Step 1: Paste the following code into main.xml within the <view> element.

<button height="30" name="button" image="image.png"
  opacity="200"
  onmouseout="makeTransparent()"
  onmouseover="makeOpaque()"/>

Step 2: Now paste the following code into main.js.

function makeTransparent() {
  button.opacity = 200; //transparent (0 would be invisible)
}

function makeOpaque() {
  button.opacity = 255; //completely opaque
}

I used this technique in my Expression Tools, Windows Dock, and Fast Shutdown gadgets.

Have a tip you'd like to share? Send it to gd-developer AT google DOT com. To see all tips, choose the Tips label.

Tip: View script errors and debug statements on the Mac

Friday, May 02, 2008 at 9:24 AM

Posted by James Yum, Developer Programs Engineer (Google Desktop Team)

On Windows, you can view debug statements using either gdpconsole or the Gadget Designer. As for exceptions and script errors, those happily pop up in an error dialog.

On the Mac, you can view those same messages in the console log. Here's how:

1. Open Console.app, located under Macintosh HD > Applications > Utilities
   
2. Click the Logs button in the toolbar to open the logs list
   
3. Select console.log in the logs list
   

Have a tip you'd like to share? Send it to gd-developer AT google DOT com. To see all tips, choose the Tips label.

Tip: Open default browser from the HTML details view

Wednesday, April 23, 2008 at 4:34 PM

Posted by Benjamin Schirmer, Gadget Developer

When you use the HTML details view to display information, on Windows every link inside is opened using Internet Explorer, even if the user has another browser like Firefox or Opera set as their default browser. However, you can fix this with a few lines of code in your gadget.

The following link opens the Google web page in Internet Explorer in Windows — even if another browser is set as the default.

<a target="_blank" href="http://www.google.com">Go to Google</a>

To remedy this, open the URL using JavaScript and the onclick event.

<a target="_self" href="#"
   onclick="window.external.openUrl('http://www.google.com');">
  Go to Google</a>

This executes the openUrl method on the external object with the parameter of the URL you want to visit. What does this external object look like? Here is the JavaScript code that defines the external object and assigns it to the details view. This should be run before the details view is opened.

var externalObject = new Object();
externalObject.openUrl = function(url) {
  framework.openUrl( url );
};
mydetailsview.external = externalObject;

Now all your links will be opened in the default browser. Just don't forget to escape the URL!

Have a tip you'd like to share? Send it to gd-developer AT google DOT com. To see all tips, choose the Tips label.

Tip: Open URLs with framework.openUrl

Wednesday, April 16, 2008 at 4:06 PM

Posted by James Yum, Developer Programs Engineer (Google Desktop Team)

I'd bet good money that most Desktop gadget developers could recognize and understand this code snippet:

  var obj = new ActiveXObject('WScript.Shell');
  obj.run('http://desktop.google.com/');

Those days are over, as the latest Google Desktop release added an API for opening a URL in a browser:

  framework.openUrl('http://desktop.google.com/');

This is documented in the 5.5 release notes, but we wrote this tip in case you missed it. :)

Have a tip you'd like to share? Send it to gd-developer AT google DOT com. To see all tips, choose the Tips label.