2.1 Scripting Techniques for Script Panels
After you grasp the basic structure of the plugin file and the possibilities in script panels (using the tutorials in How To's for Script Panel Developers), it is time to add functionality to your panel.
This topic will contain numerous common scripting tasks in Desktop Sidebar and describe its API that is available from the script.
A reference for this API can be found here, though it is incomplete and contains incorrect data (the SDK Documentation forum is updated). The use of this reference is to find out the interfaces Desktop Sidebar provides you with and the methods they contain (whenever changes were made after this reference was compiled, they are described in this topic).
Full Version: 2.1 Scripting Techniques for Script Panels
Executing Code when the Panel Starts Up & Introduction to Toplevel Objects
Scripts, not only of Desktop Sidebar panels, are usually divided into methods so they could be reused several times throughout the code and for better readability.
However, the basic level of all scripts is the top level - these statements are executed one by one when the panel is loaded.
So, for example, in JScript, one could write the following code (it is surrounded by the <script> tag as it would be in the panel's code).
This script, put in a panel, will simply display a Message Box with a text and title when the panel starts, and not do anything besides of that.
Note that this also introduced you to the sidebar toplevel object, which contains several methods which can be used to get global Desktop Sidebar settings and access functionality to simplify writing the panel and tightly integrate it into Desktop Sidebar. In this instance we call the MsgBox method to display a modal Message Box window.
There are additional toplevel objects and toplevel methods - these are the members of the ISidebarSite interface. A listing of ISidebarSite's other members can be found in the interface reference - ISidebarSite (NOTE: This reference is obsolete. For most other interfaces, it should be OK. Because of that, and for convenience, the toplevel objects and methods are listed here as well)
Scripts, not only of Desktop Sidebar panels, are usually divided into methods so they could be reused several times throughout the code and for better readability.
However, the basic level of all scripts is the top level - these statements are executed one by one when the panel is loaded.
So, for example, in JScript, one could write the following code (it is surrounded by the <script> tag as it would be in the panel's code).
CODE
<script>
<![CDATA[
sidebar.MsgBox("Hello, Desktop Sidebar Scripting World!", "Title", 0);
]]>
</script>
<![CDATA[
sidebar.MsgBox("Hello, Desktop Sidebar Scripting World!", "Title", 0);
]]>
</script>
This script, put in a panel, will simply display a Message Box with a text and title when the panel starts, and not do anything besides of that.
Note that this also introduced you to the sidebar toplevel object, which contains several methods which can be used to get global Desktop Sidebar settings and access functionality to simplify writing the panel and tightly integrate it into Desktop Sidebar. In this instance we call the MsgBox method to display a modal Message Box window.
There are additional toplevel objects and toplevel methods - these are the members of the ISidebarSite interface. A listing of ISidebarSite's other members can be found in the interface reference - ISidebarSite (NOTE: This reference is obsolete. For most other interfaces, it should be OK. Because of that, and for convenience, the toplevel objects and methods are listed here as well)
- DebugBreak() - method - will break the script and prompt the user to attach a debugger to the Desktop Sidebar process. The .NET Framework SDK contains an excellent debugger for this purpose. Note: this method is not intended for use in released panels.
- DownloadFile(filePath, url, routine, obj) - method - downloads a file from a specific Internet address (url) to a specific path (filePath) in the the computer. When it finishes, it calles the method in the panel's code which is named routine, with obj as the parameters (specify null if not needed).
- GetControl(idctrl) - method - returns the UI control with the specified id.
- SetTimer(routine, interval, obj) and StopTimer() - methods - sets a method timer and stops it, respectively. See the Timers topic below.
- ShowAlert(caption, routine, obj) - method - shows a Desktop Sidebar alert (similar to the one showed from the Newsroom when new headlines are downloaded). When the alert is clicked, calls the method named routine with obj as the parameter.
- canvas - object (ICanvas interface) - the panel's UI - the canvas specification.
- config - object (IPanelConfig) - the panel's settings.
- cookie - object (integer) - the panel's cookie, needed for several operations to identify the panel.
- parent - object (IPanelParent) - the panel's parent object which controls its caption.
- sidebar - object (ISidebar) - Desktop Sidebar in all its glory.
Using Timers to Update Data in Regular Intervals
Use SetTimer and StopTimer.
Note: this article is not finished.
Use SetTimer and StopTimer.
Note: this article is not finished.
Downloading Data from the Internet
Many Desktop Sidebar panels download data from the Internet and display it conveniently in the panel.
There are two ways to download data from the Internet in the script.
TODO: There is also a new RSS API in Desktop Sidebar which can be used by script panels.
1. DownloadFile - a Toplevel Method
This method allows you to download a certain file from the Internet to any location on the user's hard drive.
The method's usage is as follows:
Parameters:
Note: this function cannot be used to download authenticated (password-protected) web pages. Instead, use the XmlHttp method that is described below.
Examples:
This is an example that shows how to download a file to the user's c:\ drive. When the download is finished, a Message Box is shown. If there is an error downloading, a different Message Box is shown.
Following is an example of using DownloadFile to download the file to a temporary location and then open it. In the end, the temporary file is deleted.
2. XmlHttp - an ActiveX Object
Microsoft supplies an object to download data from the Internet via scripting as a part of Windows (note that some users may have to update their MSXML version with a simple download from the Microsoft website).
Like Desktop Sidebar's DownloadFile, this method too is asynchronus - meaning it doesn't block the application while it download the data, but instead calls a specific method when it is finished. The difference between the two is that this method downloads the file straight to the memory (into a variable) instead of into a file on the user's hard drive.
Example:
The following example will try to download a file and display its contents. It will report in case of an error and stop the process.
3. RSS Feeds API
Desktop Sidebar exposes a set of easy-to-use methods and objects to work with RSS feeds and data.
To-do.
Many Desktop Sidebar panels download data from the Internet and display it conveniently in the panel.
There are two ways to download data from the Internet in the script.
TODO: There is also a new RSS API in Desktop Sidebar which can be used by script panels.
1. DownloadFile - a Toplevel Method
This method allows you to download a certain file from the Internet to any location on the user's hard drive.
The method's usage is as follows:
CODE
DownloadFile(filePath, url, routine, obj);
Parameters:
- filePath (string) - specifies the local file path to which to file will be downloaded.
- url (string) - the Internet address from which the file will be downlaoded.
- routine (string) - the name of the method that will be called when the download is finished.
- obj (object) - any object, that will be passed as a parameter when calling routine when the download finishes.
Note: this function cannot be used to download authenticated (password-protected) web pages. Instead, use the XmlHttp method that is described below.
Examples:
This is an example that shows how to download a file to the user's c:\ drive. When the download is finished, a Message Box is shown. If there is an error downloading, a different Message Box is shown.
CODE
//Initiate the download process that will call DownloadFinished() in the end.
DownloadFile("c:\\newfile.html" ,"http://my.site.com/file.html", "DownloadFinished", 0)
function DownloadFinished(success, fileName, param)
{
//If the download succeeded show a success Message Box.
if(success)
{
sidebar.MsgBox("File downloaded to: " + fileName, "Success", 0);
}
else
{
//An error occurred while downloading the file.
sidebar.MsgBox("An error occurred.", "Download Failed", 0);
}
DownloadFile("c:\\newfile.html" ,"http://my.site.com/file.html", "DownloadFinished", 0)
function DownloadFinished(success, fileName, param)
{
//If the download succeeded show a success Message Box.
if(success)
{
sidebar.MsgBox("File downloaded to: " + fileName, "Success", 0);
}
else
{
//An error occurred while downloading the file.
sidebar.MsgBox("An error occurred.", "Download Failed", 0);
}
Following is an example of using DownloadFile to download the file to a temporary location and then open it. In the end, the temporary file is deleted.
CODE
//Initialize the FileSystemObject.
var fso = new ActiveXObject("Scripting.FileSystemObject");
//Get a path for the downloaded file in the Temp folder.
var tempPath = fso.GetSpecialFolder(2).Path + "\\" + fso.GetTempName();
//Initiate the download process that will call downloadFinished() in the end.
DownloadFile(tempPath ,"http://my.site.com/file.html", "downloadFinished", 0)
function downloadFinished(success, fileName, param)
{
//If the download did not succeed show a Message Box and return.
if(!success)
{
sidebar.MsgBox("Error download file.", "Panel Error", 0);
return;
}
//The download succeeded, open the downloaded file and read its contents as text.
var textFile = fso.OpenTextFile(fileName, 1);
var text = textFile.ReadAll();
//Close the file object and delete it (we don't need it anymore).
textFile.Close();
fso.DeleteFile(fileName);
//Display a Message Box with the file's contents.
sidebar.MsgBox("Downloaded file contents:\n" + text, "Download Succeeded", 0);
}
var fso = new ActiveXObject("Scripting.FileSystemObject");
//Get a path for the downloaded file in the Temp folder.
var tempPath = fso.GetSpecialFolder(2).Path + "\\" + fso.GetTempName();
//Initiate the download process that will call downloadFinished() in the end.
DownloadFile(tempPath ,"http://my.site.com/file.html", "downloadFinished", 0)
function downloadFinished(success, fileName, param)
{
//If the download did not succeed show a Message Box and return.
if(!success)
{
sidebar.MsgBox("Error download file.", "Panel Error", 0);
return;
}
//The download succeeded, open the downloaded file and read its contents as text.
var textFile = fso.OpenTextFile(fileName, 1);
var text = textFile.ReadAll();
//Close the file object and delete it (we don't need it anymore).
textFile.Close();
fso.DeleteFile(fileName);
//Display a Message Box with the file's contents.
sidebar.MsgBox("Downloaded file contents:\n" + text, "Download Succeeded", 0);
}
2. XmlHttp - an ActiveX Object
Microsoft supplies an object to download data from the Internet via scripting as a part of Windows (note that some users may have to update their MSXML version with a simple download from the Microsoft website).
Like Desktop Sidebar's DownloadFile, this method too is asynchronus - meaning it doesn't block the application while it download the data, but instead calls a specific method when it is finished. The difference between the two is that this method downloads the file straight to the memory (into a variable) instead of into a file on the user's hard drive.
Example:
The following example will try to download a file and display its contents. It will report in case of an error and stop the process.
CODE
var httpRequest = false;
function makeRequest(url)
{
httpRequest = new ActiveXObject("Microsoft.XMLHTTP");
if (!httpRequest)
{
sidebar.MsgBox("Cannot initialize XMLHTTP object. Please make sure you have the latest version of MSXML installed.", "Panel Error", 0);
return;
}
httpRequest.onReadyStateChange = stateChange;
httpRequest.open("GET", url, true);
httpRequest.send(null);
}
function stateChange()
{
if(httpRequest.readyState == 4)
{
if (httpRequest.status == 200)
{
sidebar.MsgBox("Downloaded text:\n" + httpRequest.responseText, "Success", 0);
} else {
sidebar.MsgBox("Error downloading data.", "Panel Error", 0);
}
}
}
makeRequest("http://my.site.com/file.html");
function makeRequest(url)
{
httpRequest = new ActiveXObject("Microsoft.XMLHTTP");
if (!httpRequest)
{
sidebar.MsgBox("Cannot initialize XMLHTTP object. Please make sure you have the latest version of MSXML installed.", "Panel Error", 0);
return;
}
httpRequest.onReadyStateChange = stateChange;
httpRequest.open("GET", url, true);
httpRequest.send(null);
}
function stateChange()
{
if(httpRequest.readyState == 4)
{
if (httpRequest.status == 200)
{
sidebar.MsgBox("Downloaded text:\n" + httpRequest.responseText, "Success", 0);
} else {
sidebar.MsgBox("Error downloading data.", "Panel Error", 0);
}
}
}
makeRequest("http://my.site.com/file.html");
3. RSS Feeds API
Desktop Sidebar exposes a set of easy-to-use methods and objects to work with RSS feeds and data.
To-do.
This is a "lo-fi" version of our main content. To view the full version with more information, formatting and images, please click here.