Getting started

To begin we'll take the Flickr search form and rename the file so that its file extension is .webapp. Once you have saved the file, double-click it and Sidewinder will open it.

You can run also run this web application directly from our SVN server.

Now that we have a desktop web application that we can work on, we'll start to add some more features.

HOWTO: Running Adobe's Flexstore demo as a desktop application

Open a command prompt, and change to the Sidewinder directory. If you have installed Sidewinder in the default locations, then you can type this:

cd "\program files\sidewinder\viewer 2.0"

Now execute the following command:

swviewer2 http://examples.adobe.com/flex2/inproduct/sdk/flexstore/flexstore.html#meta(width=1010,height=610)

Sidewinder will open as a basic Windows application with the Adobe Flash Flexstore demonstration running inside:

The Flexstore application functions as normal, but it can be treated as a desktop application in its own right, distinct from the browser:

Docking and auto-hiding

To make an application dock itself to one of the edges of the desktop we use the property anchor with a value of true.

We can also indicate where we would like the application to start, by using the position property.

To auto-hide--i.e., slide off the desktop when the user moves their mouse away from the application--we use the property autohide with a value of true.

Setting options in the document

By adding the following settings to the Flickr Search web application we would dock the application to the top right of the screen, and make it auto-hide:

    <link rel="stylesheet" href="flickr.css" type="text/css" />
    <meta name="position" content="top-right" />
    <meta name="anchor" content="true" />
    <meta name="autohide" content="true" />
    <xf:model>

Note that the location of a window with a position of 'top right' and one with a position of 'right top' will be the same. The difference is only apparent when docking; the first will be docked to the top edge, whilst the second will be docked to the right edge. This means that when auto-hiding, a window that is positioned 'top right' will slide off the top, whilst a window that is positioned 'right top' will slide off the right.

The modified application is available here.

Setting options on the command-line

If the webapp is being loaded via the command-line then we can open the basic (unmodified) web application using the following command:

swviewer2 http://svn.x-port.net/svn/public/samples/flickr/flickr.webapp#meta(position=top-right,anchor,autohide)

Transparency

To make windows behind our desktop application 'show through' we can use the property transparency to give Sidewinder the value of a colour that will be set to 'transparent'. This has the effect of allowing any application that is behind our web application to be visible and respond to mouse-clicks--extremely useful if we want to give our application a different shape. The chrome is often removed when using transparency.

By adding the following settings to the Flickr Search web application our application would have none of the usual desktop application chrome, and the entire application would appear to grow and shrink as the user searched:

    <meta name="autohide" content="true" />
    <meta name="height" content="700" />
    <meta name="chrome" content="false" />
    <meta name="transparency" content="fffffe" />
    <style type="text/css">
      body
      {
        background-color : #fffffe;
      }
      html, body
      {
        margin           : 0;
      }
    </style>
    <xf:model>

The modified application is available here.

Alternatively, we can open the basic Flickr web application with the following command:

swviewer2 http://svn.x-port.net/svn/public/samples/flickr/flickr.webapp#meta(position=top-right,anchor,autohide,height=700,chrome=false,transparency=fffffe)

Note however that this won't quite work with the example we've been using, since a background of #fffffe needs to be added.

Opacity

To make windows behind our desktop application partly visible we can use the property opacity. The value given is a percentage, and tells Sidewinder how much of the web application to show, and how much of any application sitting behind. This feature is useful when creating applications such as clocks where we'd like the information to be available all the time, but we don't want to lose screen space.

By adding the following settings to the Flickr Search web application other applications will now be partly visible 'through' our application:

    <meta name="transparency" content="fffffe" />
    <meta name="opacity" content="70" />
    <style type="text/css">

The modified application is available here.

Alternatively, we can open the basic Flickr web application with the following command:

swviewer2 http://svn.x-port.net/svn/public/samples/flickr/flickr.webapp#meta(position=top-right,anchor,autohide,height=700,chrome=false,transparency=fffffe,opacity=70)

Note however that this won't quite work with the example we've been using, since a background of #fffffe needs to be added.

The Renderer object

The Renderer object allows a number of different types of window to be created that in turn incorporate a Sidewinder renderer. Renderers are available for simple text or XHTML, and can be created to stand on their own, or as a dockable child of some parent window.

To create a renderer we simply use the new operator followed by the Create method. Create takes one parameter which is a JavaScript object containing information about how the window should behave. For example, to create an XHTML renderer window that:

• is 850 pixels wide, by 700 high;
• is docked to the top right-hand edge of the display;
• automatically slides off the screen when the user moves their mouse away from the window, and reappears when the user moves their mouse back over the window;
• and is styled to have a title bar, resize borders, close icon and a system menu;

we would write the following script:

var oRenderer = new Renderer;

oRenderer.Create(
  {
    Type         : "xhtml",
    Width        : 850,
    Height       : 700,
    Edge         : "right",
    Position     : "top",
    AutoHide     : true,
    Style        : 0x20001D40
  }
);

(The various parameters, including the Style values, will be explained in more detail in a later section.)

HOWTO: A desktop calendar using Google Calendar

To create a web application that fills a renderer with your Google Calendar, we would do the following:

var oRenderer = new Renderer;

oRenderer.Create(
  {
    Type         : "xhtml",
    Width        : 850,
    Height       : 700,
    Edge         : "right",
    Position     : "top",
    AutoHide     : true,
    Style        : 0x20001D40
  }
);

oRenderer.Load("http://calendar.google.com");
oRenderer.Show();

This application would open a large window, docked to the top of your display, and that automatically hides when the mouse is moved away. The window will contain your Google Calendar login page, and once you have logged in your calendar will be available by moving the mouse to the top edge of the display.

HOWTO: Technorati Mini as a desktop application

The blog-monitoring site Technorati has a useful feature they've called Technorati Mini which allows a user to create a small browser window containing search results, which updates itself every minute--an ideal candidate for a Sidewinder desktop application.

To turn this into a desktop application that docks to the left side of your desktop, and saves real estate by autohiding, we would use the following JavaScript:

var oRenderer = new Renderer;

oRenderer.Create(
    {
        Type         : "xhtml",

        Width        : 310,
        Height       : 470,

        Edge         : "left",
        AutoHide     : true,

	Position     : "top",

	Opacity      : 70,

        Style        : 0x20001D40
    }
);

oRenderer.Load("http://www.technorati.com/mini/index.html?s=cheese");
oRenderer.Show();

The renderer-request-newwindow event

A common use of Sidewinder is to host web applications that were designed to run in a web browser. Often these applications create new browser windows in order to provide part of their functionality, but in many situations it would be useful to have control over the creation of these windows and control their position, whether they dock or autohide, and so on.

Sidewinder allows us to do this via the renderer-request-newwindow event, which is dispatched whenever the hosted web application requests a new window. A scripted application can register for this event and when triggered, create a renderer object which will be returned to the web application. This renderer can have all of the usual features, such as autohide, opacity and so on.

To register for the event, we need an EventListener with a handleEvent function:

function handleEvent(event)
{
  ...
}

var listener = new EventListener;

listener.SetHandler(handleEvent);
koolim = new Renderer(
  {
    Type     : "xhtml",
    Title    : "Sidewinder: Kool IM",
    Style    : 0x00000040|0x00000800|0x00001000|0x00400000|0x20000000,
    Edge     : "right",
    Position : "middle",
    AutoHide : true,
    Width    : 256
  }
);
koolim.Create();
koolim.addEventListener("renderer-request-newwindow", listener, true);

Now, whenever any web application hosted by this renderer requests a new window (using window.open) our event handler will be invoked. To provide a renderer to be used by the web application, we implement the handleEvent method.

First we create some global variables, so that the JavaScript engine doesn't remove our windows when the function returns:

var message;
var listener;
var koolim;
var listener;
var param;

The handleEvent method itself first creates a renderer:

function handleEvent(event)
{
  message = new Renderer(
    {
      Type     : "xhtml",
      Title    : "Sidewinder: Message",
      Style    : 0x00000040|0x00000800|0x00001000|0x00400000|0x20000000,
      Edge     : "left",
      Position : "top",
      AutoHide : true,
      Width    : 298,
      Height   : 298
    }
  );
  message.Create();
  message.Show();

before returning it to Sidewinder via the Event object.

  event.parameter.objectValue = message.GetRenderingImplementation();
}

The parameters to the renderer can be set as required. For example, the position of the window could be set, based on how many previous windows had been opened.

HOWTO: KoolIM as a desktop chat application

To illustrate the use of the renderer-request-newwindow event, we'll create a desktop application that uses the KoolIM chat client.

KoolIM is a very impressive web application that allows you to chat with people via any of the popular chat protocols. The KoolIM servers do all the work of translating the protocols, which means that the user interface need only communicate over HTTP to the KoolIM servers. It's therefore possible to build chat clients with HTML, which means that users do not need to install any special software and can use chat almost anywhere.

Since KoolIM supports so many protocols it's a strong candidate to be used as your main chat software, although it is limited to some extent by the browser. We can improve things somewhat by adding a renderer-request-newwindow handler that creates a new renderer whenever the KoolIM web application tries to open a new window, but since we have total control over the renderer object, we'll create one that docks to the left side of the screen, and automatically hides when the mouse is moved away.

The first part of our application just sets up some global variables so that the objects we create don't get deleted when our functions exit:

var message;
var listener;
var koolim;
var listener;

Next we create an event handler, that will create a new renderer object when triggered, and will return the renderer as part of the Event object:

function handleEvent(event)
{
  message = new Renderer(
    {
      Type     : "xhtml",
      Title    : "Sidewinder: Message",
      Style    : 0x00000040|0x00000800|0x00001000|0x00400000|0x20000000,
      Edge     : "left",
      Position : "top",
      AutoHide : true,
      Width    : 298,
      Height   : 298
    }
  );
  message.Create();
  message.Show();

  event.param.objectValue = message.GetRenderingImplementation();
}

The main function itself needs to create the main renderer:

function main()
{
  koolim = new Renderer(
    {
      Type     : "xhtml",
      Title    : "Sidewinder: Kool IM",
      Style    : 0x00000040|0x00000800|0x00001000|0x00400000|0x20000000,
      Edge     : "right",
      Position : "middle",
      AutoHide : true,
      Width    : 256
    }
  );
  koolim.Create();

before creating an EventListener object and registering for the 'new window' event:

  listener = new EventListener;
  listener.SetHandler(handleEvent);
  koolim.addEventListener("renderer-request-newwindow", listener, true);

Finally, we're ready to open the KoolIM web application:

  koolim.Load("http://web1.koolim.com/client5/html/webim.html");
  koolim.Show();
}

main();

(For detailed information on how to use the script below, see Using JavaScript to create internet-facing desktop applications.)