In this overview, we demonstrate
how to declare a background image and add some simple text and graphics
to a gadget using the three presentation elements in the Sidebar
g namespace (
g:background,
g:image, and
g:text) and the native Sidebar image protocol (gimage).
- Introduction
- Background Images and the G:BACKGROUND Element
- The G:TEXT and G:IMAGE Elements
- The GIMAGE Protocol
Introduction
The Sidebar presentation elements expose their functionality through qualified HTML elements in the Sidebar
g
namespace and the gadget presentation APIs. These elements, along with
all standard HTML elements, are exposed through the gadget Document
Object Model (DOM) and are accessible from gadget script.
The Sidebar supports JPEG, bitmap (BMP), Graphics Interchange Format
(GIF), and Portable Network Graphics (PNG) image types. Only PNG
supports alpha channel transparency.
Note
The Sidebar presentation elements are not available in standard HTML
documents and do not render in external browsers such as Windows
Internet Explorer.
Background Images and the G:BACKGROUND Element
There are a number of methods that can be used to declare a gadget background element and specify its image source.
Generally, the background object and its image source are declared in the gadget HTML file using the
g:background element:
<body>
<g:background id="imgBackground" src="images/background.png">
<span id="gadgetContent">Hello World!</span>
</g:background>
</body>
An alternative is to declare the
g:background as previously described, but specify the image source in Microsoft JScript:
<html>
<head>
<title>Hello World</title>
<script type="text/jscript" language="jscript">
function init()
{
var oBackground = document.getElementById("imgBackground");
oBackground.src = "url(images/background.png)";
}
</script>
</head>
<body onload="init()">
<g:background id="imgBackground">
<span id="gadgetContent">Hello World!</span>
</g:background>
</body>
</html>
Caution When using
background images with alpha channel transparency the following two
methods can result in unpredictable rendering, such as transparent
pixels replaced with magenta, and limitations in functionality. As
such, they are presented here for information purposes only and are not
recommended.
Important For Windows 7, when the new <autoscaleDPI>
element of the gadget manifest is set to true (for high-DPI support)
and the following methods are used, rendering issues can increase
significantly.
The following example uses the
background property to declare the gadget background image:
<html>
<head>
<title>Hello World</title>
<script type="text/jscript" language="jscript">
function init()
{
System.Gadget.background = "images\\background.png";
}
</script>
</head>
<body onload="init()">
<g:background id="imgBackground">
<span id="gadgetContent">Hello World!</span>
</g:background>
</body>
</html>
A similar method uses Cascading Style Sheets (CSS) to update the backgroundImage Property as shown in the following example:
<html>
<head>
<title>Hello World</title>
<script type="text/jscript" language="jscript">
function init()
{
with(document.body.style)
backgroundImage = "images\\background.png";
}
</script>
</head>
<body onload="init()">
<g:background id="imgBackground">
<span id="gadgetContent">Hello World!</span>
</g:background>
</body>
</html>
Finally, just like a standard Web page, the gadget background can simply be declared as an attribute of the
<body> tag and modified with CSS. However, this does not expose the background as a
g:background scripting element.
<html>
<head>
<style>
body{width:120;height:160;font:8 pt Arial;color:white;
filter:progid:DXImageTransform.Microsoft.Gradient(GradientType=1, StartColorStr="#000000",
EndColorStr="#0000FF")}
</style>
</head>
<body bgcolor="red" background="background.jpg">
...
</body>
</html>
When one background image needs to be swapped for another of
different size, such as when a gadget is docked or undocked, it is
recommended that the width of the background element be set to 0. This
forces the platform to recalculate the size of the image and refresh
appropriately.
See the
onUndock or
onDock topics for an example.
The G:TEXT and G:IMAGE Elements
The
g:text and
g:image elements expose gadget text and image functionality respectively.
Note
The g:text and g:image elements can be declared in the gadget HTML file but it is highly recommended that you use the addImageObject and addTextObject methods from JScript instead. This will ensure the element is exposed through the gadget DOM.
The following example demonstrates how to add images and text to the
background layer of a gadget. These objects will appear at the top of
the z-order for the background layer, but below any user interface (UI)
controls.
Caution Other than g:background,
avoid images that render to the absolute edges of a gadget. In
high-DPI, rounding errors can cause a magenta fringe around the border
of the gadget.
// Initialize the gImage object
// DEFAULT_IMG_PATH: the default image path.
function initImage()
{
// Check if the user has already selected an image file to use. If not use default.
if (System.Gadget.Settings.read("imageFile") == "")
{
System.Gadget.Settings.write("imageFile", DEFAULT_IMG_PATH);
}
imageFile = System.Gadget.Settings.read("imageFile");
// Create the image object
oImage = document.getElementById("background").addImageObject("", 0, 0);
}
// Initialize the gText object
function initText()
{
oText = document.getElementById("background").addTextObject("", "Verdana", 10, "blue", 0, 0);
}
function showImage()
{
oImage.src = System.Gadget.Settings.read("imageFile");
}
function showText(newValue)
{
oText.value = newValue;
}
g:image and
g:text objects can also be added to the gadget DOM by declaring them in the gadget HTML file:
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=Unicode" />
<link href="css/Graphic.css" rel="stylesheet" type="text/css" />
<script language="javascript" src="js/graphic.js" type="text/javascript"></script>
</head>
<body>
<g:background
id="imgBackground"
src="images\background.png">
<g:text id="txtTest" blur="20">test</g:text>
<g:image id="imgTest" src="images\aerologo.png"/></div>
</g:background>
</body>
</html>
Note
This method does not expose the objects as g:image or g:text elements. You can locate and assign the objects using the document.getElementById("...") method, but the g:image or g:text methods and properties are not available.
The GIMAGE Protocol
This protocol is useful for adding images to the gadget DOM more efficiently than the standard HTML
<img>
tag. This efficiency results from improved thumbnail handling and image
caching (it will attempt to use thumbnails from the Windows cache if
the requested size is smaller than 256 pixels by 256 pixels) when
compared with requesting an image using the
file:// or
http:// protocols. An added benefit of the
gimage
protocol is that any file other than a standard image file can be
specified as a source, and the icon associated with that file's type is
displayed.
Note
When the gimage protocol is specified, the requested file must be on the local machine and must not contain a server reference.
Despite its name, the
gimage protocol is unrelated to the
g:image element. The image, or associated icon, is returned as a bytestream and, as such, is not exposed to gadget script as a
g:image element. However, the
<img> object is still a member of the gadget DOM and is exposed through standard JScript members.
function findGIMAGE()
{
var oGIMAGE = document.getElementById("imgGIMAGE");
// Get a standard JScript <img> object property.
var srcValue = oGIMAGE.src;
// Undefined G:IMAGE property.
var opacityValue = oGIMAGE.opacity;
}
...
<img id="imgGIMAGE"
src="gimage:///C:\Users\user\AppData\Local\Microsoft\Windows Sidebar\Gadgets\SDK_Graphic.gadget\js\graphic.js" />
Sizing
As stated previously, one of the benefits of the
gimage
protocol is enhanced thumbnail handling and image sizing. Typically, you
would supply the image height and width as a querystring appended to
the
src attribute value or as an inline style.
// --------------------------------------------------------------------
// Add an image to the gadget DOM using the gimage protocol.
// --------------------------------------------------------------------
function addGIMAGE()
{
var heightWidthLoad = "?width=25&height=25";
var oImage = document.createElement("img");
oImage.src = "gimage:///" + System.Gadget.path + "\\images\\aerologo.png" + heightWidthLoad;
oImage.id = "imgGIMAGEx";
document.body.appendChild(oImage);
}
// --------------------------------------------------------------------
// Switch an image using the gimage protocol.
// --------------------------------------------------------------------
function switchGIMAGE(file)
{
// Specify the height, width, and interpolation method.
imgGIMAGE.style.height = 25;
imgGIMAGE.style.width = 25;
imgGIMAGE.style.msInterpolationMode = "bicubic";
imgGIMAGE.src = "gimage:///" + System.Gadget.path + "\\images\\aerologo.png";
}
<!--
Specify gimage details from script.
-->
<img id="imgGIMAGE" src="images/blank.png" height="0" width="0" />
If only one of the height and width is specified, the image is scaled
proportionally; if neither the height or width is specified, the image
is scaled proportionally to 120 pixels by 120 pixels. In either case,
any unfilled areas are rendered as transparent.
Similar posts :
