Creating a Panel

This tutorial will guide you through creating a simple Desktop Sidebar script-panel.

Desktop Sidebar allows users to develop panels using a scripting language (JScript or VBScript). Such panels are composed only of plain text XML files and you can use any text editor, such as Notepad, to create them.

The tutorial assumes you have basic knowledge of XML and a scripting language - JScript (preferred) or VBScript. The W3Schools XML tutorial is recommended, although it is not strictly required to understand and create Desktop Sidebar panels.

1. Create the Plugin File

Start by creating an XML file with Notepad (or any other text/XML editor). Save the file as MyPanelName with the extension being .dsplugin (the file name you choose now will be the internal identifier of your panel in Desktop Sidebar). This will be your plugin file.

First, write the XML declaration and create a <plugin> element. The <plugin> element tells Desktop Sidebar that this is indeed a plugin file. There is an option attribute to the <plugin> element, called compatible, that specifies the minimum Desktop Sidebar version required to run this panel.

The example below specifies that our plugin supports Desktop Sidebar build 109 and greater.

<?xml version="1.0" encoding="utf-8" ?> <plugin compatible="109" > </plugin>

2. Create a Panel Element

To start describing your panel, add a <panel> element inside the top-level <plugin> element described in step 1. The available attributes for the <panel> element (all of the attributes are optional):

For example:

<?xml version="1.0" encoding="utf-8" ?> <plugin compatible="109"> <panel author="My Name" caption="My Panel" description="Description of the panel." icon="myIcon.bmp" category="news_cat"> </panel> </plugin>

3. Describe the Panel's User Interface Using a Canvas

Now it is time to describe the panel's user interface, which contains controls such as text labels, lists, images and buttons. For that purpose, Desktop Sidebar provides the "canvas" - the ability to describe a panel's UI in textual form, in a simple language remotely similar to HTML.

To declare your canvas, add a <canvas> element inside the <panel> element you added in step 2.

A canvas can use various layouts to position the controls inside the panel. flowlayout is the default and simplest layout. In the flow layout, control are placed one after the other in the panel without any further alignment or sizing.

In the example panel we are creating in this tutorial we will use just one control a textoutput. As its name suggests, this control is used to display text on Desktop Sidebar.

Controls can have many different attributes but for a start we use only the id attribute, which specifies the internal identifier of the control. We will later use this identifier to manipulate control from our code.

For more information, see the Adding User Interface guide.

The following code shows the example panel until now, with the canvas and the textoutput in it.

<?xml version="1.0" encoding="utf-8" ?> <plugin compatible="109" > <panel author="My Name" caption="My Panel" description="Description of the panel." icon="myIcon.bmp" category="news_cat"> <canvas layout="flowlayout" > <textoutput id="main" /> </canvas> </panel> </plugin>

4. Add Runtime Functionality to the Panel

Panels don't just sit in Desktop Sidebar and do nothing! The actions performed by the panel when it's running inside Desktop Sidebar are controlled by the panel's script.

To get started with the panel's script, let's set the text displayed by the textoutput control that we added in step 3:

<script> <![CDATA[ GetControl("main").SetText("Hello World"); ]]> </script>

Our panel now displays Hello World, but let's add some interaction. In order to do something when the text is clicked, we connect the textoutput's click event to a function in the panel's code. To do this, we first have to modify the canvas description:

<textoutput id="main"> <event id="click" action="onClick" /> </textoutput>

Now, add a handler function to the code:

function onClick() { sidebar.MsgBox("Hello from event handler","First Panel",0); }

After we've made these two changes, clicking the text causes the onClick method to get called, and then we display a message box confirming the event handler was executed. Of course, in your real panel you'll want to change this to something more useful than displaying an alert, or even connect to another event such as mouseover or showdetails.

For more information, check out the Accessing User Interface Controls from Code guide.

Complete Panel

Congratulations! You have just completed your first Desktop Sidebar panel! In order to add this panel to Desktop Sidebar please save this file with .dsplugin extension in Desktop Sidebar's installation folder and restart sidebar to allow it to see the changes. You will then be able to add "First Panel" to your sidebar using the Add Panel dialog.

Below is the complete code listing for the sample panel.

<?xml version="1.0" encoding="utf-8" ?> <plugin compatible="109" > <panel author="My Name" caption="My Panel" description="Description of the panel." icon="myIcon.bmp" category="news_cat"> <canvas> <textoutput id="main" > <event id="click" action="onClick" /> </textoutput> </canvas> <script> <![CDATA[ function onClick() { sidebar.MsgBox("Hello World","JScript Panel",0); } GetControl("main").SetText("Hello World"); ]]> </script> </panel> </plugin>