1. Introduction
2. Getting started
3. What is emulated?
4. What is not emulated?
5. User Interface
6. Default Presets

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.

Important note:
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:

First, download 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 starts:

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