Omnis Technical Note TNWE0026 August 2010
Creating a Stand-Alone Windows Mobile Emulator
for Omnis Studio 5
by Jason Gissing
If you are developing Mobile applications in Omnis, it is always a good idea to create an emulation environment. If you don't own a Windows Mobile device, it will open up the ability for you to test your mobile forms. If you already own such a device, setting up the emulator is still a good idea as it will allow you to test your application on a wide range of setups and screen sizes.
Microsoft provides, for free, everything you need to get your emulator up and running.
1) Install Virtual PC 2007
Before you install Microsoft's Device Emulator, you need to install a driver to enable the emulator to access your network. Microsoft no longer provides this driver as a standalone download, so you must download and install Microsoft Virtual PC 2007
2) Install Standalone Device Emulator
You are now able to install Microsoft Device Emulator 3.0
3) Download & Install Emulator Images
You now need to download some device images to run in the emulator. Omnis Studio 5.0 supports Windows Mobile 5.0 - 6.1. As such, you may want to download a range of images for the various versions of Windows Mobile. You should install the "Professional" versions of the files, as the "Standard" versions don't support touch-screen.
When installing these images, you may receive an error regarding Visual Studio - this can safely be ignored as we are setting up a stand-alone emulator.
4) Running The Emulator
Running the images:
You can't just run the emulator directly - it requires the image file and various other command-line arguments to be passed to it. More details on this are provided in section 6, but initially you should be able to run your images using one of the following methods:
- The image installers should create Start Menu shortcuts, which will run the various images in the emulator. However, there often seems to be issues with the installer creating these shortcuts. Running the installer again and repairing the installation should fix this, however.
- An alternative is to download and extract the provided Mobile_Emulator_Framework.zip to your machine. This provides a simple framework, containing .bat scripts to run the 5.0 and 6.1 images. If you installed to the default locations these should work immediately - otherwise you may just need to change the paths which some of the variables in the .bat files point to.
Enable File Explorer:
When you run an image for the first time, File Explorer is not initially available to you. To enable it on your start menu, go to Start -> Settings -> General -> Menus and enable File Explorer. Note that you may need to disable other start menu shortcuts first.
If you want to transfer files to the emulated device you can either:
- Specify a shared folder by adding the argument "/s <SharedFolderPath>" to your emulator's shortcut, or specify it in the Emulator's File -> Configure menu. The shared folder will appear in the File Manager under 'Storage Card'.
- Access the image's files directly using ActiveSync/Mobile Device Center (see section 5).
Enable Network Connection:
Go to the emulator's File -> Configure -> Network menu, and ensure the network adapter is enabled. Then on the toolbar of your emulator's screen, you should see a transmission icon (as shown). Click it, then select Connect.
Switching Screen Orientation: You can change the screen's orientation by simply pressing the emulated device's "App Launch 2" button. In the default skins this is a calendar button to the top-right of the direction pad.
5) Install ActiveSync/Windows Mobile Device Center
If you want to test your forms in your emulator without creating and installing your own .cab file, you need to install and open ActiveSync (Win XP) or Windows Mobile Device Center (Vista). In the connection settings of which, you must make sure to allow DMA connections.
After opening your emulator, open the Device Emulator Manager (dvcemumanager.exe, in the same directory as your device emulator). You should see an entry for the currently open image - right click it and select "cradle":
ActiveSync/Mobile Device Center should now let you connect to the emulated device. While it is connected here, you can test your forms from Omnis, using Ctrl-T (Once you've set your $webbrowser preference to Windows Mobile).
6) Customise Images
You have the ability to customise a great deal of the emulation. You are able to create your own skins to modify the appearance and screen size, and you can add many start-up parameters to modify many aspects of the emulator's behaviour.
If you look in the directory you installed your images (INSTALLDIRECTORY\PocketPC\Deviceemulation for 6.0/6.1 images, INSTALLDIRECTORY for 5.0 images) you will find an xml file and set of 3 pictures for each 'device'. One of the pictures is without buttons pressed, and another where they are pressed. The other picture provides a mask to map the positions of the various buttons - they are defined by color.
The XML file defines our skin, and is where we customise it. If you open this up, you can see that you can set the position and size of the display, as well as the 3 pictures it uses, and the colors (in hexadecimal) which map to functional buttons in the emulator.
So by creating your own pictures, and editing the xml files, you can easily create your own skins and screen sizes to emulate. Please refer to the Device Emulator Skin XML Schema Reference for further information.
The actual image files (of type .bin for 6.0/6.1 or .nb0 for 5.0) are in the same, or the parallel '0409' directory, by default. If you create a custom skin, we recommend you use the image which is the same as, or closest to, the screen size you want to emulate.
To run the images in the emulator, various pieces of information are passed to it as command-line arguments.
As such, it makes sense to create your own shortcuts or batch scripts for your custom skins, to which we can append these arguments. You may like to use the shortcuts created by the image installer, or the .bat files in Mobile_Emulator_Framework.zip, as a starting point.
The shortcut's "Target" must, at a minimum, contain the path to the emulator (DeviceEmulator.exe) followed by the image file. It can then be followed by any of the following arguments:
You are most likely to need /s, /memsize and /skin. The memsize must be divisible by 8; it is recommended to use 128 or 256. If you don't specify a save-state filename (/s or /defaultsave) it won't save the state, and you will be forced to boot a fresh OS install each time.
Once you have created a saved state (a .dess file), it may be worthwhile creating a shortcut which passes that to the emulator. You don't need to add any other arguments, as these are all remembered as part of the state information.
So it needs only to adhere to the format: EmulatorPath /s SavestateFilePath
Alternatively, you could add functionality to a .bat script to check for and load a saved state if it's present, as is done in the example framework.