Information

Created By	Salesforce Service User

Approval Process Status	Published

Objective

Description

Display for Mobile Devices

Coordinate system
Overriding the device's DPI (Android and iOS only)
Fonts
Colors
Spinner images
Alternative images
Theme Support (Android only)

Coordinate system

When using dialog units as the form units of measurements, the dialog units are converted to pixels using the metrics of the form’s font. Since mobile devices do not support Windows fonts, the metrics of the default font (which is 5x13) is used.

In addition, mobile devices are available in various resolutions and sizes. To have the same appearance on all of the devices, the dimensions of the form and controls are multiplied by a factor, which is the device Dot Per Inch (DPI) divided by Windows DPI (96).

So, when converting between dialog units and pixels, the mobile client uses the following formula:

X in pixels = X in dialog units * 5 * (mobile device's DPI / 96)

Y in pixels = Y in dialog units * 13 * (mobile device's DPI / 96)

Note:

Although Windows calculations are based on 96 DPI, the actual screens’ DPI is a bit different, so the sizes seen in Windows will not be exactly the same as seen on the mobile devices.
You can override the device's DPI, as described below.

Overriding the device's DPI (Android and iOS only)

The Magic xpa client relies on the DPI information defined in the device in order to display the controls in the same size on all of the devices. However, there are some devices, such as the HP Slate 21, that return an incorrect DPI value and, therefore, the controls do not appear properly on those devices.

You can override the device's DPI values and define the correct value by changing the following files:

For Android devices: The custom_dpi.xml file in the RIAModules\Android\Source\app\src\main\res\values folder.
For iOS devices: The custom_dpi.txt file in the RIAModules\iOS\Source\MagicApp folder. (Since version: 3.2a)

In these files, you need to add an entry with the device model in lower case letters without spaces and the DPI value. If the device name contains a hyphen (-), it should be replaced with an underscore (_).

Note: For Android devices, you can get the device model from the Android Settings screen or by evaluating the ClientOSEnvGet ('device_model') function.

Since version: 2.4b for Android, 3.2a for iOS

Fonts

Each device has a set of available fonts that are usually different from the fonts found on a Windows desktop. Since it is not possible to select mobile fonts using the Windows fonts dialog box, in order to enter these fonts into the font table, you need to directly edit the fonts table file (such as fnt_rnt.eng) using a text editor. Example font table entries:

Android Droid Serif font:	Android font,Serif,14,0,0
Android Bold Droid Serif font:	Android bold font,Serif,14,0,0,Bold
iOS Helvetica font:	iOS font,Helvetica,14,0,0
iOS Helvetica font:	iOS bold font,Helvetica-Bold,14,0,0

On Android devices you need to send the font family name and the style of the font you want.
The system will find a matching font for you. For example, to use a Droid Serif font use: "Android Serif bold,Serif,12,0,0".
If the font defined in the font table is not found on the mobile device, the default font will be used with the size defined in the font table.
On Android devices you can see the font list in the System/Fonts folder in the device file system.

Colors

The mobile device RIA client uses the same color table as other interfaces, but it does not support the “System” colors available on Windows.

If a system color is used for the form or control, then the device default color for the form or control will be shown. If you want to use a specific color, you need to implicitly define the foreground and background colors. One exception is that for Table and Group controls, when a system color is used, a white color will be used as the background of the control (Since version: 3.0).

On Android and iOS devices:

On Edit controls – To see the border you must use a color with a non-system color.
On Combo Box controls – When a color is used, no border or other drawing is shown. To see the arrow you must use a color with a system color (to get the device default).

On Android devices:

On Combo Box controls – When a color is used, both the border and the item arrow are shown. (Since version: 3.2b)
On Table controls and controls attached to a Table control – Using a transparent color is not recommended since it will slow down performance.
On Table controls – Using an Alternate color is not recommended since it will slow down performance.

For Android devices, you can change the native color of the underline that appears with an Edit control that has focus.

On mobile devices: (Since version: 3.0)

The Tab color affects the foreground and background color of the Tab control header (unlike Windows desktop).
The Tab color does not affect the Tab area background. The screen color is defined according to the form's color, gradient and wallpaper.
If the Tab color is a system color or a transparent color, the Tab color will have the same color as the Title Bar Color property (FG and BG).
For Android devices, the line under the current tab will have the same color as the color of the tab's text, that is, the tab's FG color.

You can maintain multiple color files – one for each mobile platform. If you want a different set of colors for each platform, create a separate color file and put it in a subfolder with the name of the platform under the folder containing the defined color file.

For example: If the runtime color file is Support\clr_rnt.eng, then you can put the Android color file under Support\Android\ clr_rnt.eng and the iOS color file under Support\iOS\clr_rnt.eng.

At runtime, the appropriate color file will be used automatically, if it exists. There is no need to define this file implicitly.

Since version: 2.3

Native color controls are drawn with the operating system's default theme color. On Android devices, you can change this color for some objects.

To change the native color of the following objects:

Underline color for an Edit control that has focus
Check Box color
Combo Box rectangle color

Add the following line to the AppTheme style section in the themes.xml file located under the RIAModules\Android\Source\res\values folder: <item name="colorAccent">#hexColor</item>
Where hexColor is the desired RGB color value. For example, to get a yellow color, use: <item name="colorAccent">#ffff00</item>
1. Generic Java libraries
  
  Simply put the library in your application's libs folder (for example, at RIAModules\Android\Source\libs)s
2. Android Java libraries
  
  Android libraries must be re-built as part of your application.
  
  The MgxpaRC library is an example of an Android library that exists in your Android application.
  
  If you need to add your third-party Android library to the application, you can put the library in a subfolder under your application's folder (for example, at RIAModules\Android\Source\mylib) and add a reference to it in the build.xml file, which is located at RIAModules\Android\Source. For example: <property name="android.library.reference.2" value="mylibraryapp" />

To change the navigation drawer indication icon color:

Add the following line to the AppTheme style section in the themes.xml file located under the RIAModules\Android\Source\app\src\main\res\values folder: <item name="drawerArrowStyle">@style/MyDrawerArrowToggle</item>
Add a new style section that provides the color:

<item name="color">#hexColor</item>

</style>

Where hexColor is the desired RGB color value.

Since version: 3.0

Spinner images

On Android and iOS devices, the SetCrsr function is used to show a spinner image (for example, before calling a Batch or non-interactive task that takes a long time to execute).

Alternative images

The Android and iOS RIA mobile clients support alternative images for different screen densities.

You can define different images in different resolutions and place them in specific subfolders on the server as defined below. The RIA client will automatically retrieve the matching image according to the device’s characteristics.

Note:

The ServerFileToClient function uses the same algorithm, so if you need to fetch images (or any file in general), it will be done according to the same rules.
You can see the device characteristics used in this mechanism using the ClientOSEnvGet() function with the value of 'device_resource-folder'.

On Android devices:

The search will be done according to the platform (Android), screen size (for example: normal, large), screen aspect (for example: long, not long) and the screen pixel density (dpi) (for example: hdpi).

The search is done in different combinations of these parameters according to the Android algorithm, so you do not have to define images according to all of these parameters.

Refer to: http://developer.android.com/guide/topics/resources/providing-resources.html#AlternativeResources.

For example, if the image file is defined to be at c:\images\a.jpg, then for an Android device defined as large screen size, not long aspect ratio and hdpi pixel density, you can place the image in any subfolder that does not contradict with any of the device’s characteristics, for example: c:\images\Android\, c:\images\Android\large\, c:\images\Android\large\hdpi\, c:\images\Android\hdpi\.

On iOS devices:

The search will be done according to the platform (iOS), device modifier (for example: ~iPad, ~iPhone) and the high resolution indicator (for example: @2).

If the image is not found in the specific subfolders, it will be searched for in the parent folder and so on until reaching the original folder.

For example, if the image file is defined to be at c:\images\a.jpg, then for an iPad 3 device (identified as an iOS platform, ~iPad device modifier and @2 high resolution indicator), the server will fetch the a.jpg file from c:\images\iOS\~ipad\@2\.

If the file is not found there, the server will fetch the file from c:\images\iOS\~ipad\, if the file is still not found, the server will fetch the file from c:\images\iOS\ and if the file is still not found, the server will fetch the file from the original location: c:\images\.