Device Manager

From RAD Studio
Jump to: navigation, search

Go Up to Form Designer Options


Device manager.png

Tools > Options > User Interface > Form Designer > Device Manager

The Device Manager shows a grid with the device presets. The device presets are the list of available devices to use at design time for example in the Multi-Device Preview Window. These devices can be used as views of your multi-device project if the view has been registered by installing the package of such view. By default, only generic devices have registered views. See how you can create your own views.

From this page you can add, edit, and delete a device preset. You cannot edit or delete built-in device presets, you can only edit or delete device presets that you add yourself to the Device Manager.

The Device Manager manages the DevicePresets.xml file, when you add, edit, or delete a device preset from the Device Manager, the DevicePresets.xml file updates automatically to reflect such changes. You can also add, edit, or delete devices directly from the DevicePresets.xml file.

You can double-click a device in the list to edit it. You can use the context menu or the buttons to access other actions.

Buttons and Context Menu

At the bottom of the page, you can find the buttons to manage the device presets. If you right-click anywhere in the page, a context menu pops up.

By using the buttons or the context menu, you can do one of the following actions:

Item Description
Add Opens the New device settings editor to create a new device preset.
Edit Opens the Device Settings Window editor to edit the selected device preset.
Note: This action is disabled when you select a built-in device preset. You cannot edit built-in device presets.
Delete Deletes the selected device preset. See Deleting a Device Preset.
Note: This action is disabled when you select a built-in device preset. You cannot delete built-in device presets. RAD Studio asks you for confirmation before it actually deletes the selected device preset.

DevicePresets.xml

The DevicePresets.xml file defines the device presets information, these devices can be used at design time.

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.

This file allows you to edit the following device information:

  • A friendly name for your view
  • Available orientations
  • Display size for each orientation
  • Status bar position and size
  • Image for the device frame

To add a new device preset to the DevicePresets.xml file:

  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>
    
    Note: You need to replace ARTWORK_PATH with the correct path to your artwork.
    Warning: If you are adding a customized view to the view selector, you need to ensure that the name added between the <Name></Name> tags matches the ViewName of the package of that view.
  6. Restart the IDE for the changes to take effect.

DevicePresets.xml Elements

Each MobileDevice element may use any combination of the following elements:

Element Description Example
Name Identifier used to create the package to add a new view.
Warning: The name must be unique, if you add a new device preset with the same name as an already existing device preset, the existing device preset is overwritten by the new one when the DevicePresets.xml file gets updated by the IDE.
<Name>TestView</Name>
Displayname Friendly name to display where necessary, like for example in the View Selector, the Device Manager, and the Multi-Device Preview.
<Displayname>My Android Phone</Displayname>
DevicePlatform Platform of the device.
Number Definition
0 Windows
1 macOS
2 iOS
3 Android
<DevicePlatform>3</DevicePlatform>
FormFactor Form factor of the device.
Number Definition
0 Desktop
2 Phone
3 Tablet
4 Media Player
5 Automotive
6 Industrial
7 Embedded
8 Watch
9 Glasses
Note: When selecting Desktop as form factor, there is no need to configure any of the orientation since these are not enabled for this particular form factor.
<FormFactor>2</FormFactor>
UserData Determines whether the device can be edited from the Device Manager.
<UserData>True</UserData>
Portrait

UpsideDown
LandscapeLeft
LandscapeRight

Orientation definition.

You may use any combination of these four elements. Use each element as a self-closed XML tag (<Tag />), and use any combination of the following attributes on each tag:

Property Definition
Enabled Set this property to True if you want to use this orientation.
Width

Height

Measures (in pixels) of the form. Represents the available area.
Top

Left

Represents the most top left corner of the available area. It is the offset from the origin of the screen.
StatusbarHeight The height of the status bar.

Default: 0.

StatusBarPos The position of the status bar, 0 meaning on top.

Default: 0.

Value Position
0 Top
1 Bottom
2 Left
3 Right
Artwork The fully qualified path to the file. When the field is empty, a slim black frame appears by default.
Mask The fully qualified path to the Mask file. It is an optional field that is used to apply a mask to the Artwork in order to define non-rectangular shapes in customized views. Therefore, the Mask defines the visible and non-visible parts of the Artwork on the form. When the field is empty, no mask is aplyied to the Artwork.

To apply a Mask to the Artwork take the following steps:

  • Make the Mask the same size as the form ( Width and Height).
  • Add transparency to the background and to the screen area of the device on the Artwork.
  • Make the visible part of the form transparent on the Mask.
  • Make the non-visible part of the form white (#FFFFFFF) on the Mask.
<Portrait
    Enabled="True"
    Width="360"
    Height="640"
    Top="61"
    Left="44"
    StatusbarHeight="25"
    StatusBarPos="0"
    Artwork="$(BDS)\ObjRepos\en\Devices\images\Android35.cpng"
    Mask="$(BDS)\ObjRepos\en\Devices\images\AndroidMask35.cpng"
    />

After saving new changes in the Device Manager, the DevicePresets.xml file updates when the IDE closes to include the <Thumbnail></Thumbnail> tags. The <Thumbnail></Thumbnail> tags are automatically generated to include the location of the thumbnail images of the device presets used in the Device Manager and the Multi-Device Preview. You should not edit or delete the <Thumbnail></Thumbnail> tags.

See Also