UI Guidance

UI Guidance

Controlling Your Application Display

The Windows Bridge for iOS allows developers to control their application display experience. The following options help ensure the best possible application display on targeted devices.

Magnification

Magnification visually scales your application by the amount specified.

Auto-Magnification

Auto magnification sets the magnification factor (above) to the size that matches the size of your window.

FixedWidth

This value defines the internal Islandwood application width, in points. A value of 0 means fit the width to the corresponding width of the Universal Windows Platform window.

FixedHeight

This value defines the internal Islandwood application height, in points. A value of 0 means fit the height to the corresponding width of the Universal Windows Platform window.

SizeUIWindowToFit

This setting causes Project Islandwood to automatically change the size of your application’s UIWindow to match the internal application size. Setting this value to TRUE can be very useful if your application uses auto layout.

Presentation Transformation

Orientation of landscape or portrait.

Aspect Ratio

This parameter has no effect unless at least one of the FixedWidth or FixedHeight parameters is set to 0.

Using device native scale for displaying your application

Native scale is how many pixels per point on the screen. For example, the native scale on a Microsoft Lumia 950 Windows Phone is 4 (or 4x4 pixels). Native scale is predetermined, we only decide on whether or not to use it.

To preserve the best layout experience for iOS developers porting their applications to Windows, the Windows Bridge for iOS uses the native scale of your device to render the layout of your application. The scale reported back to your application is automatically scoped (or clamped) to a value of 1 or 2. In this way you get the best possible layout being displayed without any additional efforts. You can enable or disable this feature if desired.

This capability is determined by the following configuration options:

useHostScaleFactor

Enables/disables the use the native scale.

clampScaletoClosestExpected

Clamps the magnification to the closest value for native scale - 1 or 2.

Configuring Your Application Display

If you look at the UIApplication.h header file, you will see the WOCDisplayMode object class defined. The header file lists several properties that can be altered when designing an optimal display experience.

UIApplication.m

@interface WOCDisplayMode : NSObject

@property (nonatomic) float magnification;
@property (nonatomic) float fixedWidth;
@property (nonatomic) float fixedHeight;
@property (nonatomic) double fixedAspectRatio;
@property (nonatomic) BOOL autoMagnification;
@property (nonatomic) BOOL sizeUIWindowToFit;
@property (nonatomic) BOOL useHostScaleFactor;
@property (nonatomic) BOOL clampScaleToClosestExpected;
@property (nonatomic) WOCOperationMode operationMode;
@property (nonatomic) UIInterfaceOrientation presentationTransform;

In addition, you can access information about the display settings from the following properties. Note these properties are READ-ONLY.

@property (nonatomic, readonly) CGSize currentSize;
@property (nonatomic, readonly) float currentMagnification;
@property (nonatomic, readonly) CGSize hostWindowSize;
@property (nonatomic, readonly) CGSize hostScreenSizePixels;
@property (nonatomic, readonly) float hostScreenScale;
@property (nonatomic, readonly) CGSize hostScreenSizePoints;
@property (nonatomic, readonly) CGSize hostScreenSizeInches;
@property (nonatomic, readonly) float hostScreenDiagonalInches;
@property (nonatomic, readonly) WOCDeviceType hostDeviceType;

- (void)setDisplayPreset:(WOCDisplayPreset)mode;
- (void)updateDisplaySettings;

@end

@interface UIApplication (UIApplicationDisplayMode)

+ (WOCDisplayMode*)displayMode;

@end

You can also change the display settings in the AppDelegate.m file as shown below:

AppDelegate.m

#ifdef WINOBJC

// Tell the WinObjC runtime how to render the application
@implementation UIApplication (UIApplicationInitialStartupMode)

+ (void)setStartupDisplayMode:(WOCDisplayMode*)mode {
    mode.autoMagnification = TRUE;
    mode.sizeUIWindowToFit = TRUE;
    mode.clampScaleToClosestExpected = FALSE;
    mode.fixedWidth = 0;
    mode.fixedHeight = 0;
    mode.magnification = 1.0;
}

@end

#endif

Asset provisioning at different native scales

To ensure your application provides the best display experience, you will need to provide your application assets for display at different native scales.

When you are porting your application from iOS, you should provide assets at x1 (100%) and x2 (200%) scales. When you are thinking about Windows devices and their associated scale factors, 100% will cater for the most common desktop devices and some low end tablet devices. In addition, 200% will cater for higher resolution desktops.

It is also important to keep in mind that designing your assets using vector tools will give the highest quality artwork at any scale. These are also easier to revisit and adjust for devices with varying native scales. A good practice is to design your asset at the highest scale and then scale down the assets as required.

Sample developer guidance for Windows Phone

When you are porting your iOS application to Windows Phone, you can use the following sample to think about the configuration you need for displaying your application. These settings work well for most situations but you can then tweak these values as appropriate to accomplish your desired results.

| Microsoft Lumia 950 |
|-------------------------------------|------------| | Preset Mode | Native | | Auto magnification | True | | Magnification | 1.0 | | Scale | 4.0 | | Fixed Width | 0.0 | | Fixed Height | 0.0 | | SizeUIWindowToFit | True | | UseHostScaleFactor | True | | ClampScaletoClosest | True | | Presentation Transformation | Portrait | | Native Scale | 4.0 | | Native Bounds | 360, 640 | | Host Windows Size (Pts) | 360, 640 | | Host Windows Size (Px) | 1440, 2560 | | Host Screen Scale | 0 | | Host Screen Size (Pts) | 360, 640 |

Sample developer guidance for desktop/PC

When you are porting your iOS application to a Windows desktop (or PC), you can use the following sample settings to think about the configuration you need for displaying your application. These settings work well for most situations but you can then tweak these values as appropriate to accomplish your desired results.

| Dell Optiplex 9010 |
|-------------------------------------|------------| | Preset Mode | Native | | Auto magnification | True | | Magnification | 1.0 | | Scale | 1.0 | | Fixed Width | 0.0 | | Fixed Height | 0.0 | | SizeUIWindowToFit | True | | Presentation Transformation | Portrait | | Native Scale | 1.0 | | Native Bounds | 1017, 900 | | Host Windows Size (Pts) | 1017, 900 | | Host Windows Size (Px) | 1017, 900 | | Host Screen Scale | 1 | | Host Screen Size (Pts) | 1017, 900 |

Sample developer guidance for Surface Pro 4

When you are porting your iOS application to a Microsoft Surface Pro 4, you can use the following sample settings to think about the configuration you need for displaying your application. These settings work well for most situations but you can then tweak these values as appropriate to accomplish your desired results.

| Microsoft Surface Pro 4 | |-------------------------------------|------------| | Preset Mode | Native | | Auto magnification | True | | Magnification | 1.0 | | Scale | 2.0 | | Fixed Width | 0.0 | | Fixed Height | 0.0 | | SizeUIWindowToFit | True | | UseHostScaleFactor | True | | ClampScaletoClosest | True | | Presentation Transformation | Portrait | | Native Scale | 2.0 | | Native Bounds | 964.5, 768 | | Host Windows Size (Pts) | 964.5, 768 | | Host Windows Size (Px) | 1929, 1536 | | Host Screen Scale | 2.0 | | Host Screen Size (Pts) | 954, 768 |