# Widget Emulator

## Introduction

The Widget Emulator (see Figure 1) is a tool enabling you to see how your widget is likely to appear on a small monitor, TV, or handheld device. The emulator runs your widget in a sandbox and will “trick” it in various ways to emulate the important differences between these varying environments.

Figure 1: The Widget Emulator in all its glory.

Strangely enough, the Widget Emulator is a widget itself. It contains a panel on the right where you can set the device parameters, and a screen on the left where your own widget runs in an iFrame.

Despite the emulator’s best efforts to resemble the devices, there will always be aspects that are impossible to emulate. This is due to the enormously complex task that emulation is and the possible device-dependent bugs that exist in any software. The tool should be used while developing your widgets but it is still advised that you test them on a real device before considering them production quality.

## Getting started

Although the Widget Emulator is a widget itself, it is not installed in the usual way. You need to copy your own widget into the emulator and then run the emulator widget from your file system. You can copy multiple widgets into the emulator.

First, get the emulator package.

Extract the contents of the zip file to your hard drive. You will see the following level items:

- emulator_files/
- plugins/
- widgets/
- config.xml
- default_device.js
- index.html

In order to emulate your widget, you need to add your widget to the emulator:

Copy the directory of the widget you wish to emulate into the `widgets` directory of the emulator.

The file structure will typically now look like this:

- emulator_files/
- plugins/
- widgets/
  - mywidget/
    - scripts/
    - style/
    - config.xml
    - index.html
  - dir.js
- config.xml
- default_device.js
- index.html

You need to initialize your widget as an emulated widget. Add the following line of code into the `head` of the `index.html` file of your emulated widget, before your own JavaScript:

    <script type="text/javascript">if(parent.emulator)parent.emulator.begin(window);</script>"

When this code is called, the emulator will override certain functions the emulated widget calls, and provide values consistent with the type of device selected. One example is overriding the reported available screen size.

Finally, you need to register the widget in the emulator. Open the `dir.js` file in the `widgets` directory and add the name of the directory of your widget to the list. (It’s currently not possible to scan a directory for widgets. This will be possible with a public implementation of File I/O.)

Click and drag the config.xml file of the emulator (not the `config.xml` in your emulated widget) to an Opera window to run the emulator.

When the emulator starts, it will display a list of currently ‘installed’ widgets, i.e. those defined in `widgets/dir.js`. Click on your widget to start emulation of it. Clicking the ‘X’ icon inside your widget will return you to the list of installed widgets.

## What is emulated?

Screen size
  JavaScript properties such as `screen.height` and `screen.availHeight` will contain different values than your actual monitor to reflect the screen size of the device being emulated. CSS media queries will evaluate according to the device chosen. This means that if you include, for instance, a stylesheet with `media=“handheld”` then that stylesheet will be applied if you decide to emulate a mobile phone.
Docked mode
  The widget can be put in docked mode, also known as micro mode, to see what it looks like when this mode is enabled on a device.
Frame rate
  The frame rate of your JavaScript animations can be decreased to see how the widget handles slow computers. This only applies to JavaScript making use of `setTimeout` and `setInterval` and not to animated GIFs etc.
Internet connection speed
  The `XMLHttpRequest` object (used in Ajax(Asynchronous JavaScript and XML)) can be made to run slower to mimic the loading times experienced on mobile phones with slow internet connections.
Maximum preferences storage
  The preferences stored by `widget.setPreferenceForKey` are limited to as little as 20KB of storage on some devices with limited hard disk space. In cases where your widget exceeds this value the method will throw an error and the preference will not be stored.

## What is not emulated?

The following is a list of aspects that may differ between actual devices and the emulator.

Fonts
  The fonts used in your widget may not be available on the device. Also, font rendering is usually platform dependent, which could cause lines of text to wrap at slightly different positions than you see in the emulator.
Dragging
  The ability to drag a widget across your screen is usual on desktop, but on other devices this may not be enabled. The emulator does not enable dragging.
Input mechanism
  The experience on a mobile or TV may be quite different if it is not equipped with a pointing device. Also, on-screen keyboards are used on some devices, which can make text input more cumbersome and possibly hide certain events such as `onkeydown`.
DPI(Dots per inch)
  Desktop monitors often have a resolution of around 96 DPI, which is a measure of how densely packed the pixels are on the screen. Handheld devices often have screens with a much higher DPI, while televisions usually have a lower value. The emulator does not make adjustments for this, which means that a widget running on an actual device may appear smaller or larger than in the emulator.
Color Depth
  Some devices have screens with a color depth lower than 24 bit. These devices will dither images in widgets at runtime, but the emulator does not demonstrate this. If you want to control exactly how your images look on these devices you have the option of dithering your own images before packaging your widgets.

## User Interface

Figure 2: The Widget Emulator, with the main parts of the interface illustrated

1. Device list: This shows a list of your emulated devices. Click on the arrows to move one device up or down in the list, or click on the list itself to expand the full list and choose a device. The “I” icon will show or hide the device information panel.
2. Device information panel: This panel shows information about your current device, for example its screen dimensions and which plugins are enabled for it. Click on the edit icon in the upper left corner to edit the list of devices.
3. Emulated device: This is the main part of the emulator showing how your widget looks on the emulated device. This will display a widget manager when you begin. Click on one of the widget to start it.
4. Emulated toolbar: The emulated toolbar allows you to reduce your widget to a docked state or closing it entirely. When closed, the widget manager will reappeared.
5. Widget information panel: This panel shows information about the widget you are currently emulating, such as its position on the screen and the size of its preference store.

## Emulator devices

The Widget Emulator comes with a set of devices which simulate characteristics of devices such as mobile phones, TVs and a desktop computer. Each device varies with respect to for example screen resolution, availability of features like a dock, user agent and so on.

The default devices provided are:

Preset | Media-type | Screen size (px) | Connection | Storage | Framerate
--- | --- | --- | --- | --- | ---
Desktop | screen | 800×600 | 256kbps | 2MB | Fast
VGA Mobile | screen | 640×480 | 16kbps | 20kB | Slower
QVGA Mobile | screen | 320×240 | 16kbps | 20kB | Slower
WVGA Mobile | screen | 800×480 | 16kbps | 20kB | Slower
TV | tv | 800×480 | 32kbps | 200kB | Fast

## How to add devices

There are two ways of adding devices: By using the device panel in the emulator and by editing the file default_devices.js in the root of the emulator directory.

### Adding a device in the emulator

Figure 3. The panel for adding devices

Perform the following steps:

1. Click the blue “I” icon to display the device panel. This panel displays information about the current device.
2. Click edit icon in the upper left corner of the panel. This will display all currently defined devices.
3. Click “New” beneath the list of devices. This will expand the panel with a UI for creating a new device.
4. Fill in relevant values, such as device name, user agent and so on.

Note that by adding devices this way, they will not be stored in the `default_devices.js` file. The devices will be saved in the preference store of the emulator.

### Editing default_devices.js

The devices are stored in the file default_devices.js

1. Browse to the installation directory of the emulator.
2. Open the `default_devices.js` file in your favorite text editor.
3. Add or edit entries as needed.

An entry can look something like this:

     {
        title: 'Desktop',
        media: 'screen',
        screen: [800, 600],
        storage: 2097152, // 2MB storage
        rotatable: true,
        chrome: null,
        dock: null,
        useragent: null,
        plugins: ['Network Security']
      },

Here’s a quick explanation of the properties:

title
  Name of the device.
media
  The media type the device identifies itself with, one of ‘screen’, ‘handheld’ or ‘tv’.
screen
  An array with two numbers, the dimensions of the screen of the device.
storage
  A number, the number of bytes available for preference data storage.
rotatable
  A boolean, whether or not the device’s screen can be rotated, i.e. if the resolution event is fired.
chrome
  An array with four numbers, corresponding to the number of pixels the device chrome takes up, in the order of top, right, bottom and left.
dock
  An array with two values, denoting the dimensions of the dock, or null if docking is not supported.
useragent
  A string with the User Agent string the device identifies itself with, or null for the default.
plugins
  An array of strings, the names of plugins that should be enabled for the device.