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.
The version number has been updated to 5.8.*.*
(minimumGoogleDesktopVersion="5.8.0.0").
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.
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)
You can now do more with scrollbars:
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.
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).
Now in addition to setting event handler functions, you can also get them.
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:
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:
|
|
For an example of using both
getZipCode() and getPopularTopics(), see the
PersonalizationAPI sample.
Like basicElement,
view now has an onmousewheel event
that fires when mouse scrolling is complete.
Get the value from the event.wheelDelta property.
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).
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.
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:
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.
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.
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.
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.
The following bug fixes make existing API work better.
view element's
onclose handler are now saved properly.
Previously, they were lost.
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.
The following user-visible changes might affect how you design or implement your gadget.
gddDetailsViewFlagDisableAutoClose
flag.
resizeBorder property
to customize this rectangular resize area.
edit area
inserted a Tab character.