Release Notes (5.5)

This page describes changes in the 5.5 release 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.7.*.* (minimumGoogleDesktopVersion="5.7.0.0").

Note: In the beta release, the version number was 5.5.*.* (minimumGoogleDesktopVersion="5.5.0.0"). If your gadget requires any features from the Out-of-beta changes section, you should specify a minimum version of at least 5.7.0.0.

New elements and major features

New element: <radio>

The new radio element implements a radio button — a one-of-many set of buttons. The API is exactly the same as the checkbox API.

New element: <combobox>

The new combobox element has much of the same API as listbox. This section lists the combobox API, except for API inherited from basicElement.

Combobox-only properties:

• droplistVisible - true means the dropdown list is visible; false means it isn't (only one element is displayed)
  
• maxDroplistItems - the maximum # of items to show before scrollbar is displayed
  
• type - "dropdown" (the default, editable control) or "droplist" (uneditable)
• value - the value of the edit area; useful only for dropdown mode

Properties shared with listbox: background, itemSeparatorColor, itemSeparator, selectedIndex, selectedItem, itemWidth, itemHeight, itemSelectedColor, itemOverColor

Functions shared with listbox: clearSelection(), appendString(), removeString(), insertStringAt()

Events shared with listbox: onchange

New element: <item>

The new item element replaces listitem. Item elements are used by both combobox and listbox.

New personalization API: ranking engine

Use the ranking engine to help sort items that users can click. For example, a gadget that displays items from an RSS feed can use this feature to sort its links.

For more information, see the Personalization API Developer Guide.

New feature: multiple instances of gadgets

A user can now run a gadget multiple times with different options. This feature is transparent to gadgets; you don't have to write any new code.

Note: If the user removes more than one instance of the gadget and then adds the gadget again, only the most recently removed instance's options are restored.

New button and checkbox feature: built-in text

All button elements can now have built-in text that you can style like a label. You set the displayed text value using the new caption property of a button, checkbox, or radio element. To specify how the text is rendered, you can use all label properties except innerText. Checkbox and radio elements have an additional property, checkboxOnRight, that specifies whether the image is drawn to the left or right of the text.

Here is an example of declaring a button that contains text:

<button height="30" name="button_element" width="65" x="63" y="108"
  image="stock_images\button_up.png"
  downImage="stock_images\button_down.png"
  overImage="stock_images\button_over.png"
  caption="OK" color="#000000" wordwrap="true"
  font="Georgia" size="12" italic="true"/>

Here's an example of setting the button text and font size in JavaScript code:

button_element.caption = "Click Here";
button_element.size = 10;

Checkboxes and radio buttons work the same way. By default, the image is displayed to the left of the text. To display the image to the right of the text, set the checkboxOnRight property to true.

Here's an example of creating a checkbox that displays the image to the right of the text.

<checkbox x="19" y="60"
  image="stock_images\checkbox_up.png"
  overImage="stock_images\checkbox_over.png"
  checkedImage="stock_images\checkbox_checked_up.png"
  checkedDownImage="stock_images\checkbox_checked_down.png"
  checkedOverImage="stock_images\checkbox_checked_over.png"
  caption="This text is on the left"
  font="Georgia"
  checkboxOnRight="true"/>

Back to top

Other API changes

New basicElement and view events: onrclick, onrdblclick

Similar to the onclick and ondblclick events of basicElement and view, except that these new events are for clicks of the right mouse button.

New edit area features: scrolling, readonly, idealBoundingRect

Scrolling feature: An edit area now gets a vertical scrollbar whenever its contents are too tall to be displayed entirely.

readonly property: By default, edit elements are editable. To specify that an edit element is uneditable, set the new readonly property to true. To make it editable, set readonly to false.

idealBoundingRect property: This read-only property contains the ideal size for the current text inside the edit element. This property's value is affected by other properties such as multiline and wordwrap. The following example shows how to use idealBoundingRect.

Assume an edit area defined as follows (in main.xml):

<edit name="editbox" height="75" width="150" x="16" y="30"
  multiline="true" wordwrap="true"/>

Here is some JavaScript code that uses the edit element's idealBoundingRect property:

var idealRect = editbox.idealBoundingRect;
editbox.width = idealRect.width;
editbox.height = idealRect.height;

New listbox methods and property

bool appendString(str): Creates an item element with a single child — a label with the inner text specified by str — and then adds the item as the last one in the listbox. The return value is true if appending the item succeeded; otherwise, it's false.

bool insertStringAt(str, index): Similar to appendString, but you can specify the index for the new item. If the index is too large or less than zero, the insertion fails (returning false) and no item is created.

void removeString(str): Searches for the first (lowest-indexed) item element that has one child (a label), and whose child has inner text exactly equal to str; removes that item, if it is found.

itemSeparatorColor: If itemSeparator is true, then the value of itemSeparatorColor is used as the color of the line between items.

Assume a listbox named "lb" is declared as follows:

<listbox height="100%" name="lb" width="100%" onclick="onclick();" 
         itemWidth="200" itemHeight="50"
         autoscroll="true" multiSelect="true"
         itemSeparatorColor="#ff0000" itemSeparator="true">
  <item><label>item 1</label></item>
  <item><label>item 2</label></item>
</listbox>

The preceding code uses the itemSeparatorColor property to change the color of the lines between items to red.

Here are examples of using the new methods:

//Add an item named "item 3" to the end of the listbox.
var success = lb.appendString("item 3");

//Insert an item named "item 4" at the beginning (index 0) of the listbox.
var success = lb.insertStringAt("item 4", 0);

//Remove the first item element that has only one child (a label)
//that has inner text exactly equal to "item 3".
lb.removeString("item 3");

Note: Although all the examples in this section use listbox, this API is also supported by combobox.

New view methods: removeAllElements(), prompt()

void removeAllElements(): Matches basicElement.removeAllElements().

string prompt(str, str): Shows a dialog asking the user to enter text. Here are examples of using the prompt() method:

var textEnteredByUser =
  view.prompt("Please enter your name", "Superman");

var textEnteredByUser =
  view.prompt("Please enter your name", "");

The first parameter is the prompt shown in the dialog. The second parameter is the default text in the edit field. The return value is the text in the edit field.

New img properties: colorMultiply, cropMaintainAspect

colorMultiply: Permits changing the color of an image at runtime. Use this feature when you need multiple colors of the same image — for example, in a gadget where the user can choose between several ribbon colors.

The value of colorMultiply is a hexadecimal number, with two digits each for red, green, and blue, in that order. The two digits let you decrease or increase the saturation of the corresponding color, where 00 means the color should be eliminated, 80 means the color should remain the same, FF means the color should be twice as intense. Here are some examples of how the two digits are interpreted:

• 00: Remove the color value. Example: 60 -> 0
• 40: Halve the color value. Example: 60 -> 30
• 80: Don't change the color value. Example: 60 -> 60
• FF: Double the color value. Example: 60 -> C0

Here's an example of using the colorMultiply property in main.xml to show only the green channel of an image, without changing the green channel's value:

<img src="test.png" colorMultiply="#008000" />

The following JavaScript code uses the colorMultiply property to display a grayscale image in any one of four colors:

var tints = [
  "#3797ff",  // blue
  "#c91f9e",  // pink 
  "#c01515",  // red 
  "#ddbf12",  // yellow 
];
...
//Make an image blue:
anImg.colorMultiply = tints[0];

cropMaintainAspect: Cropping can make images look great in slideshows. Possible values of the cropMaintainAspect property are "false" (the default), "true", or "photo". A value of "true" maintains the aspect ratio and crops all four sides so that the image fits in the display rectangle. The "photo" value is like "true", except that the top of the photo isn't cropped, since important features such as faces are usually towards the top of a photo. Here's an example of using cropMaintainAspect to crop a photo image:

<img width="100" height="150" cropMaintainAspect="photo"/>

New framework object: runtime

The runtime object has the following read-only properties:

appName

"Google Desktop"

appVersion

The running version of Google Desktop. Example: "5.5.708.16558". In future releases, this property will be useful for conditionally using new API while still supporting older versions.

osName

The name of the computer's operating system (OS). Possible values: "windows vista", "windows server 2003", "windows xp", or "windows 2000". If the OS doesn't fall into any of those categories, an empty string is returned.

osVersion

The operating system version. Example: "5.1.2.0" for Microsoft Windows XP (also known as Windows NT 5.1), Service Pack 2. The format is as follows:

majorVersion.minorVersion.majorServicePackVersion.minorServicePackVersion

Here's an example of using the runtime object:

var os = runtime.osName;

New system feature: user.idle

The read-only idle property is true if the user has done nothing for a while and might be away from the computer. Otherwise, it's false. Here's an example of using this property:

if (system.user.idle) {
  //Stop animation.
}

New constants: gddElementMaxOpacity, gddElementMinOpacity

These constants are useful for specifying opacity without needing to know that maximum opacity is 255, and minimum (complete transparency) is 0. For example, use the following code to make an item 80% opaque (slightly transparent):

someElement.opacity = .8 * gddElementMaxOpacity;

New options method: encryptValue()

Invoke this method to encrypt an item's value. Once encryptValue() is called for an item, the value of the item is stored in encrypted form. The value is automatically decrypted when it is retrieved. In a pre-beta release of Google Desktop 5.5, this method was called secureValue().

options.putValue("name", value);
options.encryptValue("name"); //encrypt the value

//Later:
var value = options.getValue("name"); //automatically decrypted
...
options.putValue("name", value); //automatically encrypted
//no need to call encryptValue again

Note: If you remove an item and then re-add it, the item is no longer secure.

Deprecated element: <listitem>

Use <item> instead.

Back to top

Changes that don't affect the API

New feature: keyboard support added to listbox

Listboxes can now be used without the mouse. (Comboboxes also support keyboard access.) For example, you can use the arrow keys to navigate through the items in a listbox or combobox, or press Escape to hide a drop-down list.

Scrolling improvements: mouse wheel support, containers in details and options views

Previously, the mousewheel was ignored; now scrollbars react to the mousewheel. Containers in details and options views now support scrolling.

Dock detection improvement: view onundock event

When a gadget is loaded in floating mode (on the desktop, rather than in the sidebar), the view onundock event is now fired.

Size of options store limited to 1MB

The options object now limits storage of all items, combined, to 1MB.

Back to top

Out-of-beta changes

The Google Desktop 5.5 out-of-beta release introduced some new features, API, and bug fixes.

New method and feature: opening a URL in an external browser

Your gadgets can now open URLs in an external browser, with no need for ActiveX. This feature is implemented automatically by the edit element, which displays URLs as links and responds to user clicks on links. You can use this feature anywhere else in your gadget by calling the new framework method openUrl(). For example:

//In a handler for a user-initiated event, such as a click:
framework.openUrl("http://code.google.com/apis/desktop/");

Name and Arguments	Description	Returns
openUrl(string httpOrHttpsUrl)	Opens the specified HTTP or HTTPS URL in an external browser. If no scheme name is specified, "http://" is inserted before the string.	void

New gadget.gmanifest element: <platform>

You can now specify the platforms your gadget has been tested against. See The platform Element in the gadget.gmanifest documentation.

New gadget.debug level: info

Previously, Gadget Designer let you see four levels of gadget debugging information, but the gadget.debug object provided only three levels. With the addition of info(), the gadget.debug API matches Gadget Designer. The following table shows the four levels.

Method	Gadget Designer message level
gadget.debug.trace()	Trace (used to be called Debug)
gadget.debug.info()	Info
gadget.debug.warning()	Warning
gadget.debug.error()	Error

New edit methods: select(), selectAll()

Two new methods let you programmatically select the characters in an edit element.

Name and Arguments	Description	Returns
select(integer start, integer end)	Selects the specified characters in the edit box. The first character has index 0. Use -1 to indicate the last character.	void
selectAll()	Selects all characters in the edit box.	void

Combobox improvement: clicking the selected item

Previously, when the user clicked the already selected item in a combobox, the dropdown remained visible. Now the dropdown collapses.

Combobox and listbox improvements: item width and special keys

Item width: The default width of item elements is now 100%. This change makes creating listboxes and comboboxes simpler because, in normal use, you don't have to set the width of items.

Special keys: Previously, left-arrow, right-arrow, and delete did not work inside an editable combobox or listbox. Now they do.

Change to <script> element

A gadget no longer loads if it has a <script> element (a subelement of <view>) that points to a non-existent file.

Change to Personalization API hierarchy

Use google.pers.ranking instead of pers.ranking. You can find example code in the Personalization API Developer Guide.

Bug fix: contentarea in div

Previously, when a contentarea was contained in a div, user actions might result in the wrong content item being highlighted or selected. Now the proper item is highlighted or selected, even when the content area is in a div.

Back to top