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.)