# 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 it’s glory.

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

The developer console also comes embedded in the emulator to make it possible to debug a live widget.

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.

## Known issues

- The emulator will occasionally report that a valid widget cannot be opened. Try reloading the emulator if this is the case.
- The information area appears clipped when using devices with very small screens.

## 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:

First, get the emulator package.

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

- emulator_files/
- widget/
- config.xml
- index.html

The `widget/` directory needs to contain the widget you wish to emulate. By default, the My Opera widget is included in the package. Copy the contents of the widget you wish to emulate into the `widget` directory of the emulator, as shown in Figure 2.

Figure 2: Make sure you put your widget inside the emulator correctly.

The file structure will typically now look like this:

- emulator_files/
- widget/
  - scripts/
  - style/
  - config.xml
  - index.html
- config.xml
- index.html

You need to initialize your widget as an emulated widget. Add the following line of code into the `head` of your `widget/index.html` file, 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.

Click and drag the config.xml file of the emulator (not `widget/config.xml`) to an Opera window to run the emulator with the emulated widget displayed inside it.

## 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 3 is a full-scale screenshot of the emulator running the My Opera widget in a mobile environment. The features are discussed further below:

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

1. The main panel is what you will first be presented with. You control the emulated device from this area. The close button on this panel will close the emulator.
2. The emulated device is where you can view your own widget running. This area not only displays your widget but also displays a toolbar and fake desktop environment. When running as a mobile the screen on the device will come equipped with scrollbars if your widget does not fit on the screen.
3. The device list displays a list of saved devices. You can remove any by pressing their remove button or add more by clicking the New button.
4. The emulated toolbar sits on top of the information area. This has a refresh and close button which act upon your emulated widget. The main reason this toolbar exists is so you are aware that your widget may not necessarily have access to the entire screen; always check for `screen.availHeight` instead of `screen.height` (similarly for width).
5. Below the toolbar is an information area. Here you can view the current device settings and the current properties of the widget, including a list of all preferences currently set by `widget.preferenceForKey`.

## Default Presets

The widget comes with several devices automatically saved. We believe these are a good starting point for testing your widget. They are:

Preset | Media-type | Screen size (px) | Connection | Storage | Framerate
--- | --- | --- | --- | --- | ---
Desktop | desktop | 640×480 | 256kbps | 20MB | Fast
QVGA Landscape Mobile | handheld | 240×320 | 16kbps | 20kB | Slower
QVGA Portrait Mobile | handheld | 320×240 | 16kbps | 20kB | Slow
TV | tv | 800×480 | 32kbps | 200kB | Fast