This section describes the Mobile SDK Emulator.

The Mobile SDK Emulator is designed to simplify the development of applications that use the Mobile SDK for Windows Apps. By using the emulator developers can test mobilized Windows applications on their development machine without using a physical mobile device and without having to deploy their application in a XenApp environment.

The emulator when launched is responsible for the following:

It simulates a connected XenApp or XenDesktop session as far as the currently executing mobilised windows application is concerned.
And it surfaces the capabilities of a mobile e.g. iPhone 5 or Galaxy S3 etc. Thus it simulates the device that a user might use to access your mobilised Windows application.

Note: The term mobilised Windows application refers to an application that leverages the Mobile SDK for Windows Apps.

Installing and Starting

The emulator is installed as part of the Mobile SDK for Windows Apps.

Once the SDK is installed on your machine the emulator will start automatically whenever a CMP-enabled application is launched.

The emulator is capable of simulating any mobile device supported by the latest Citrix Android or iOS Receivers. It does this by controlling what capabilities it advertises to applications. These capabilities are determined using device template files. This information is exposed to applications via the APIs in the Mobility SDK.

A number of device templates are included with the emulator, and custom templates can be created in order to simulate new devices. More details on templates are provided in the Configuration section later in the document.

The emulator can also be launched manually before the application to be tested is started. This mode of operation will enable the developer to customise settings or select a particular template a priori.

Emulator Interface

The following section details the components of the emulator user interface. The interface is split into two main section: the left and right panels.

Left Panel

The left panel displays the status of the emulated mobile device and allows control over hardware features of the device.

Device Selector

Select from the dropdown list for the virtual device you want to emulate. Devices templates for iPhone 5, iPad 3, Samsung Tablet 10.1 and Samsung S3 are provided.

Emulator Controls

This group of controls change the state of the simulated HDX session:

Toggling the Connection State control simulates a session disconnect/reconnect.
The API Success control can be used to force all API calls in the Mobile SDK to either return success or a generic failure error code. Note: The capability API call will not return an error if this option is unchecked once the HDX session is established as capabilities are determined on session creation.
The Mobile SDK v2 Support control toggles support for the features introduced in version 2 of the Mobile SDK, allowing the application to be tested as though it is running on a server with version 1 or 2 of the SDK.

Device Status

This group of controls displays the state of various emulator features:

Current on-screen keyboard state including selected layout and return key
Current scroll mode
Client-side Citrix Receiver On-Screen Controls

Note: Manipulating the Receiver On-Screen controls is not supported in the latest Android and iOS Receivers.

Device Controls

This group of controls allows the user to interact with the simulated device hardware:

The device orientation buttons (the top 4 buttons) allow the user to simulate the device rotation.
Emulates the user pressing the Back button on a device.
Emulates the user pressing the Home button on a device.
Emulates the user pressing the Menu button on a device.
Emulates the user pressing the Search shortcut keys on the device.

An arrow icon will appear on their hardware buttons to indicate when they have been redirected to the server.

Buttons will be greyed out when they do not exist on the device being emulated.

Right Panel

The right panel shows any pending requests or notifications from the application. Requests for phone calls, SMS messages, media capture, picker controls, user notifications and keyboard will be shown here.

On-screen Keyboard

When the on-screen keyboard is visible this will be displayed as a mock-up overlay on the right panel. Clicking the dismiss button in the lower right-hand side of the keyboard will simulate the user manually dismissing the keyboard.

The mock-up keyboard will always show a QWERTY style keyboard and does not reflect the currently display keyboard layout. The current keyboard layout and return key type is display in the on-screen keyboard status on the left panel, as below.

Note: The keyboard shown on the right panel is only intended as an indicator of keyboard visibility, and does not function as a keyboard.

Orientation

The right panel will accurately reflect the current device and application orientation. When the device is rotated using the controls on the left panel the viewport of the right panel will be rotated to match. Similarly, if the application orientation changes then the contents of the viewport will be rotated to match. This means that if the device and application orientations do not match then the contents of the right panel will be displayed sideways or upside-down, accurately reflecting what the user would see.

If the application is locked to one particular orientation, a padlock will appear next to the orientation control.

Portrait view is illustrated below:

Landscape left view is illustrated below:

The view below illustrates when the application is locked to landscape but the device is rotated to upside down. Note, the application in the screenshot is the window in the background:

Configuration

The emulator is capable of simulating any mobile device that supports the Mobile SDK for Windows Apps. It does this by controlling what capabilities it advertises to applications. These capabilities are determined using device template files. This information is exposed to applications via the APIs in the Mobility SDK.

There are three kinds of information that are included in a device template:

Capabilities determine what features are active in the emulator, and are exposed to applications via the Capability API.
Device Properties help to describe the mobile device, and are exposed via the Device Properties API, but do not control any emulator functionality.
Miscellaneous Properties are not exposed to applications, but are used to control the behaviour of some device features.

Selecting Device Templates

The emulator comes with a number of inbuilt device templates for common Android and iOS devices. Using the drop-down menu at the top of the left panel the user can select a device to emulate.

If the device is changed while an app is connected to the emulator, the emulator will simulate a smooth roam from one device to another by disconnecting the session, changing the device template, and then reconnecting.

Customising Device Templates

In addition to the inbuilt templates the emulator supports the creation of custom device templates to simulate other devices.

Clicking the gear icon next to the device drop-down menu will open the template editor. The inbuilt templates cannot be modified but they can be used as a basis to create new custom templates. To create a new device simply change the name of the template you are editing and click save.

The values stored in the template are spread across three tabs: Capabilities, Device Properties and Miscellaneous Properties.

Using SDK Features

The following details the use of specific features of the Mobile SDK for Windows Apps with the emulator.

Notifications

The Mobile SDK for Windows Apps allows applications to send notifications that will be displayed to the user locally. Multiple message formats are supported, including text, audio, vibration, and hardware light alerts.

When an application sends a user notification request it will appear in the right-hand panel. The information displayed will include the types of notification requested as well as the text of the notification if any was provided.

Media Capture

The Mobile SDK for Windows Apps allows applications to capture media on the client device. The application can request to capture pictures, audio clips or video clips, and the client device will display the native capture UI to allow the user to perform the capture.

When an application sends a media capture request, either via the Media Capture or Take Picture APIs, it will appear in the right-hand panel.

Instead of attempting to capture media, the emulator will simply allow the user to choose from a list of included sample media. If a specific file is required for testing, it can be added to the list via the browse button.

Select an option and click the Capture/Take Picture button to return the result, or click cancel to dismiss the capture request.

Picker Control

The Mobile SDK for Windows Apps allows applications to display a picker/combo box popup control locally on the client device.

When an application sends a picker control request it will appear in the right-hand panel. The information displayed includes the picker title and position, as well as the options to choose. The default selection specified in the request will be highlighted.

Select an option and click the Pick button to return the result, or click cancel to dismiss the picker request.

Phone Calls and SMS

The Mobile SDK for Windows Apps allows applications to request that an SMS message be sent or a phone call initiated. The request will be displayed locally on the client device, where the user can select whether or not to continue.

When an application sends a phone call or SMS request it will appear in the right-hand panel. The information displayed includes the target phone number, and in the case of SMS messages, the message text.