Adding a Customized View to the View Selector

From RAD Studio
Jump to: navigation, search

Go Up to Using FireMonkey Views


You can create and add new views to the View Selector in the Form Designer if the available views do not cover the specifications of your target device.

Display Specifications for the Available Views

View File MinPhysicalSize   MaxPhysicalSize   MinLogicalSize   MaxLogicalSize   PPI

Windows Desktop

System.Win.Devices

Surface Pro

System.Win.Devices

Android 3.5" Phone

System.Android.Devices

(800,500)

(1000,600)

(400,250)

(500,300)

320

Android 4" Phone

System.Android.Devices

(1280,800)

(1360,850)

(640,400)

(680,425)

320

Android 5" Phone

System.Android.Devices

(1708,960)

(1920,1200)

(854,480)

(960,600)

320

Android 7" Tablet

System.Android.Devices

(1708,960)

(1920,1200)

(854,480)

(960,600)

320

Android 10" Tablet

System.Android.Devices

(2400,1500)

(2560,1600)

(1200,750)

(1280,800)

320

Google Glass

System.Android.Devices

(640,360)

(640,360)

(427,240)

(427,240)

30

Sony SmartWatch 3

System.Android.Devices

(320,320)

(240,240)

283

Motorola Moto 360

System.Android.Devices

(320,290)

(240,218)

205

iPhone 3.5"

System.iOS.Devices

(480,320)

(480,320)

163

iPhone 4"

System.iOS.Devices

(1136,640)

(568,320)

326

iPhone 4.7"

System.iOS.Devices

(1334, 750)

(667, 375)

326

iPhone 5.5"

System.iOS.Devices

(2208, 1242)

(736, 414)

489

iPad

System.iOS.Devices

(2048,1536)

(1024,768)

264

macOS Desktop

System.Mac.Devices

Note: The devices with only the MaxPhysicalSize and MaxLogicalSize are defined with the real exact dimensions.

Adding an Android View for a Specific Device

To create a new view you need to:

The following example shows how to create a view for an Android device with the following display specifications:

  • Model = MyPhone
  • Diagonal (in) = 4.5
  • Resolution = 720 x 1280 pixels
  • Pixel density = 326 ppi
  • Css pixel ratio = xhdpi (2.0x)

You can find the specifications for a specific device on the manufacturer's website, on the datasheet.

Adding the Device Preset for the New View

To enable the view in the View Selector and customize its form, you need to add the device preset from the Device Manager or from the DevicePresets.xml file:

Note: If you add a device preset from the Device Manager, you need to go to C:\Users\<username>\AppData\Roaming\Embarcadero\BDS\23.0, open DevicePresets.xml, and copy the automatically generated name written between the <Name></Name> tags. This name needs to match the name of the view used in the view package.
Warning: We recommend to carefully check the modifications on the DevicePresets.xml file. Please revise the xml tags to ensure that they are properly cased. Otherwise the designer could not understand them and behave unexpectedly.
  1. Go to C:\Users\<username>\AppData\Roaming\Embarcadero\BDS\23.0.
  2. Note: This is a hidden folder. If you are not able to see it, make active the Show hidden files, folders, and drivers on the Folder Options dialog box in the Windows Control Panel.
  3. Open the file with a text editor.
  4. Inside the <MobileDevices RepositoryVersion="3"> tag, add a new MobileDevice element as follows:
  5.   <MobileDevice>
        <Name>TestView</Name> <!-- Same unique ID used in the creation package if you are registering a new View -->
        <Displayname>My Android Phone</Displayname> <!-- Name to show in the Device Manager, View Selector and Multi-Device Preview -->
        <DevicePlatform>3</DevicePlatform>
        <FormFactor>2</FormFactor>
        <UserData>True</UserData>
        <Portrait Enabled="True" Width="360" Height="640" Top="61" Left="44" StatusbarHeight="25" StatusBarPos="0" Artwork="ARTWORK_PATH"/>
        <UpsideDown Enabled="True" Width="360" Height="640" Top="68" Left="47" StatusbarHeight="25" StatusBarPos="0" Artwork="ARTWORK_PATH"/>
        <LandscapeLeft Enabled="True" Width="640" Height="360" Top="44" Left="68" StatusbarHeight="25" StatusBarPos="0" Artwork="ARTWORK_PATH"/>
        <LandscapeRight Enabled="True" Width="640" Height="360" Top="47" Left="61" StatusbarHeight="25" StatusBarPos="0" Artwork="ARTWORK_PATH"/>
      </MobileDevice>
    
    Notes:
    • You need to replace ARTWORK_PATH with the correct path to your artwork.
    • If you want to define a device preset with a non-rectangular shape, use the Mask field.

    For further information, see the DevicePresets.xml Elements.

  6. Restart the IDE for the changes to take effect.

After restarting the IDE, the new device preset is displayed in the Device Manager and the Multi-Device Preview.

Create a New Package

  1. Select File > New > Package - Delphi or C++Builder.
  2. In the Projects Window, right-click the <project_name.bpl>.
  3. Select Add New > Unit.
  4. Add the following code to the unit:
  • Delphi:
unit Unit1;

interface

implementation

uses

  system.Devices, system.Types, system.SysUtils;

const
  ViewName = 'TestView'; // The unique name of the view, it has to be the same name as the one written between <Name></Name> tags of the DevicePreset.xml file.

initialization

  TDeviceinfo.AddDevice(TDeviceinfo.TDeviceClass.Phone, ViewName,
    TSize.Create(1216, 684), TSize.Create(1216 div 2, 684 div 2), // MinPhysicalSize(max, min), MinLogicalSize(max, min)
    TSize.Create(1280, 720), TSize.Create(1280 div 2, 720 div 2), // MaxPhysicalSize(max,min), MaxLogicalSize(max,min)
    TOSVersion.TPlatform.pfAndroid, 326); //Select the platform and the pixel density.

finalization

  TDeviceinfo.RemoveDevice(ViewName); // To unregister the view after unistalling the package.

end.
  • C++:

Add this code to the .cpp file:

#include "Unit1.h"
#include <System.Devices.hpp>
// ---------------------------------------------------------------------------
#pragma package(smart_init)

void initdevice() {

    TDeviceInfo::AddDevice(TDeviceInfo::TDeviceClass::Phone, "TestView", // The unique name of the view, it has to be the same name as the one written between <Name></Name> tags of the DevicePreset.xml file.
        TSize(1216, 684), TSize(1216 / 2, 684 / 2), TSize(1280, 720),
        TSize(1280 / 2, 720 / 2), TOSVersion::TPlatform::pfAndroid, 326);
}

Add this code to the .h file:

void initdevice();
#pragma startup initdevice 42
  1. Before installing the package close any open project on the Designer.
  2. In the Projects Window, right-click the <project_name.bpl>.
  3. Click Install.
  4. An Information message appears informing you that the package has been installed.
  5. Restart the IDE for the changes to take effect.

After restarting the IDE, the new device preset is displayed in the Device Manager, Multi-Device Preview as well as in the View Selector.

Using the New View

After adding the device preset, installing the package, and restarting the IDE, the view is available in the View Selector. It appears with the display name defined in the xml file.

CustomizedView.png

In order to use the customized view when you run the multi-device project in the corresponding device, you need to do the following:

  • Reference the unit of the view from your project, for example, adding the .pas unit to your project.
Warning: Referencing the unit of the view in your project registers the view even if it is not needed.

When you run the project, an algorithm selects the most appropriate view for the selected device. If the customized view is the most appropriate view for the target device, it launches this view. The system ignores the views that are not compatible with the target platform.

Removing Customized Views

You need the following code to unregister a customized view from the View Selector (added to the package in the Create a New Package step).

const
    ViewName = 'TestView';

finalization
    TDeviceinfo.RemoveDevice(TestView);

To remove a customized view from the View selector:

  1. Close all the forms before uninstalling a package containing customized views.
  2. Go to Component > Install Packages....
  3. Select the package you want to remove.
  4. Click Remove.

After removing the package, if you do not need that device preset anymore, you may delete the device preset by deleting the device preset from the Device Manager or by deleting its related information from the DevicePresets.xml as added in the previous steps.

Note: You might need to restart the IDE for the changes to take effect.

See Also