Release Notes (5.8)

This page describes changes in the 5.8 version of Google Desktop that affect gadget developers. For information about changes in other releases, see Release Notes. For more information about the Desktop Gadget API, see Creating a Gadget and the Gadget API Reference.

Summary of changes

The version number has been updated to 5.8.*.* (minimumGoogleDesktopVersion="5.8.0.0").

1. New features
   1. Full support for Flash
   2. Named color values
   3. Scrollbar improvements
   4. Stopping the options view from closing
   5. Getting event handlers
   6. New personalization API: user data
2. Other API changes
   1. New view event: onmousewheel
   2. New view event: onthemechanged
   3. New view property: resizeBorder
   4. New details view flags
   5. New methods: insertElementInFrontOf() and insertElementBehind()
   6. New basicElement method: showTooltip()
   7. New edit property: detectUrls
   8. Property removed: combobox.itemSelectedColor
3. Changes that don't affect the API
   1. Bug fixes
   2. Other changes in behavior

Back to top

New features

Full support for Flash

Flash is now fully supported in Desktop gadgets. As long as the user has Flash installed, your gadget can play a .swf file from the Internet. You cannot, however, play a .swf file from the gadget's package. Here's an example of using Flash:

<object classid="progid:ShockwaveFlash.ShockwaveFlash"
  width="100%" height="100%"> 
  <param name="movie"
    value="http://www.youtube.com/watch?v=y8Kyi0WNg40"
  /> 
</object> 

For a full example, see the FlashMovie sample.

Named color values

Properties that represent colors can now have named values. You can still use RGB values — for example, label.color = "#FF0000" — but you have the choice of specifying colors using SVG color keywords. Example:

<label color="red">       (XML)
label.color = "red";      (JavaScript)

Scrollbar improvements

You can now do more with scrollbars:

• specify images for automatic scrollbars
• get the size of automatic scrollbars
• make a scrollbar that has a resizable thumb

To set the images used by an element's automatically provided scrollbar, use the new scrollbar property of basicElement to specify values for the image-related properties of the scrollbar element. You can use this feature only in JavaScript code, not in XML. Example:

someDiv.scrollbar.thumbImage = "images/thumb.jpg";
someDiv.scrollbar.thumbOverImage = "images/thumb-over.jpg";
someDiv.scrollbar.thumbDownImage = "images/thumb-down.jpg";
...

The second scrollbar improvement, getting the size of automatic scrollbars, enables you to determine how much space is available for your elements' display. To support this new functionality, internal scrollbars have three new, read-only properties: visible, offsetWidth, and offsetHeight. The visible property returns true if the scrollbar is visible; otherwise, it returns false. The offsetWidth and offsetHeight properties return the scrollbar's size in pixels, even when the scrollbar isn't visible.

You can use these properties only in JavaScript code, not in XML. Example:

availableWidth = someDiv.width;
if (someDiv.scrollbar.visible) {
  availableWidth -= someDiv.scrollbar.offsetWidth;
}

Finally, a new grippyImage property enables a scrollbar thumb that changes size to indicate how much of its container is visible. If grippyImage is set, the thumb has a variable size. Otherwise, the thumb has a fixed size.

The grippy image is the fixed-size part of the scrollbar thumb that indicates that the thumb can be dragged. The scrollbar thumb's appearance is specified by a combination of the the thumb images (which can be resized) and the grippy image.

Stopping the options view from closing

To stop the user from closing an options view, set event.returnValue to false in the onok handler. This technique can be useful if the user has entered invalid data. For an example, see the OptionsDialog sample (online or in the SDK).

Getting event handlers

Now in addition to setting event handler functions, you can also get them.

New personalization API: user data

A new google.pers.data namespace defines methods that give you access to selected information about the user. You can use this information to initialize your gadget so that it reflects the user's likely location and interests.

To use the API, you must put a <personalizationAPI> element in your gadget's gadget.gmanifest file. For example:

<gadget minimumGoogleDesktopVersion="...">
  <about>
  <--! ... usual items such as name, description, and id go here ... -->
  <personalizationAPI />
  </about>
</gadget>

The user data API supports the following methods:

google.pers.data.getZipCode()

Returns a string containing Google Desktop's best guess at the user's US zip code. If no US zip code is applicable, returns an empty string.

google.pers.data.getPopularTopics(numTopics)

Returns the user's most popular topics, as an array of topic IDs (integers). If Google Desktop has no topic IDs for this user, the return value is undefined. The array contains at most numTopics entries. Use toArray() to convert the returned array into a JavaScript array.

Here are the topic IDs that getPopularTopics() can return:

gddTopicIdUnknown (-1) gddTopicIdBusiness (0) gddTopicIdFinance (1) gddTopicIdNews (2) gddTopicIdKids (3) gddTopicIdGames (4) gddTopicIdHealth (5) gddTopicIdTravel (6) gddTopicIdScience (7) gddTopicIdShopping (8) gddTopicIdComputers (9)

gddTopicIdTechnology (10) gddTopicIdProgrammer (11) gddTopicIdWeblogs (12) gddTopicIdSocial (13) gddTopicIdSports (14) gddTopicIdEntertainment (15) gddTopicIdMovies (16) gddTopicIdTV (17) gddTopicIdCareers (18) gddTopicIdWeather (19) gddTopicIdRealestate (20)

For an example of using both getZipCode() and getPopularTopics(), see the PersonalizationAPI sample.

Back to top

Other API changes

New view event: onmousewheel

Like basicElement, view now has an onmousewheel event that fires when mouse scrolling is complete. Get the value from the event.wheelDelta property.

New view event: onthemechanged

As the first step in supporting themes, you can register a handler for a view's onthemechanged event. Currently, the only time this event fires is when the view's default font size changes, which happens when the user chooses a new font size (using the sidebar menu).

New view property: resizeBorder

In 5.8, views don't necessarily have a resize border (for a main view) or frame (for a details view). You can use the new resizeBorder property of view to customize the view's rectangular resize area. To define a non-rectangular resize border, use regular UI elements (such as img) and the hitTest property.

Note: For information on removing the frame from a details view, see the description of gddDetailsViewFlagNoFrame in the New details view flags section.

The following code results in a default resize border of 8 pixels:

<view resizable="true">

The next code snippet results in a resize border of 10 pixels on the left, 20 pixels on the top, 30 pixels on the right, and 40 pixels on the bottom of the view's area:

<view resizable="true" resizeBorder="10 20 30 40">

The format of the resizeBorder string value is any of the following:

"left top right bottom"
"all"
"leftAndRight topAndBottom"

Each item is an integer indicating the size, in pixels, of the specified edge or edges of the resize border. The format is similar to borders in HTML, except that no px suffix is present because values are always in pixels.

New details view flags

You now have two more flags you can use when calling plugin.showDetailsView(). In addition to the existing details view flags, you can use the following:

gddDetailsViewFlagDisableAutoClose

The details view should remain visible even after the user switches focus to another application. This flag is necessary when the details view isn't optional — when the details view is running a game or requires user input, for example. The user can still manually close the details view. This flag is necessary because, as of 5.8, details views close automatically. For more information, see Other changes in behavior

gddDetailsViewFlagNoFrame

Removes the default frame that appears around a details view.

New methods: insertElementInFrontOf() and insertElementBehind()

Two new methods, insertElementInFrontOf() and insertElementBehind() have been added to view and basicElement. Both methods have the same arguments as the pre-existing insertElement method; they just specify how the operation affects the Z-order (visual stacking order) of elements. Use insertElementInFrontOf() to create a new element that appears on top of the specified element (if they overlap). Use insertElementBehind() to create a new element that appears underneath the specified element.

New basicElement method: showTooltip()

By invoking this method, you cause the element's tooltip to appear. Previously, the tooltip would appear only when the user moused over the element.

New edit property: detectUrls

Setting this property to false prevents the edit element from making links out of apparent URLs. By default this property is true, and URLs are clickable links.

Property removed: combobox.itemSelectedColor

The itemSelectedColor property has been removed from combobox. (It's still available in listbox.) A combo box doesn't use this highlight color, so it doesn't need this property.

Back to top

Changes that don't affect the API

Bug fixes

The following bug fixes make existing API work better.

• Gadget options set in a view element's onclose handler are now saved properly. Previously, they were lost.
• Setting a view element's width or height property from inside the view's onsizing handler sets the gadget's size. Previously, values set in onsizing were ignored. Most gadgets should see no change in their behavior. Note that the recommended way to change the size within onsizing is to set event.width and event.height.

Other changes in behavior

The following user-visible changes might affect how you design or implement your gadget.

• A details view now closes automatically if the user switches focus to another application. If you want the details view to remain open, use the new gddDetailsViewFlagDisableAutoClose flag.
• Undocked gadgets no longer show a resize frame on mouse hover.
• For both undocked gadgets and details views, if the view has no frame and is resizable, it gets a default 8-pixel area on all sides for resizing. You can use the new resizeBorder property to customize this rectangular resize area.
• Pressing Tab (or Shift+Tab) in any element with the keyboard focus now moves the focus to the next (or previous) focusable element in the element hierarchy. Previously, pressing Tab in an edit area inserted a Tab character.

Back to top