Tutorials Mobile

[Samsung DeX] Multi Instance Application on Samsung DeX

Samsung Developer Program

Multi Instance Application on Samsung DeX

Creating application compatible with Samsung DeX is not very demanding, but can lead to extending the usage of app, using external monitor, mouse and keyboard. Below you can find the example of usage of Multi Instance application on Samsung DeX.

Scope:
Multi Instance Application (i.e. messaging app). This application allows to have one main window of users list and multiple windows of user conversations.

Scenario:

When launches the app, it shows the list of users.
- User 1
- User 2
- User 3
- User 4
When user1 is clicked at list, it opens another window for user1 using multi-instance and the window is focused.
When user2 is clicked at list, it opens another window for user2 using multi-instance and the window is focused.
User can manage the user1, user2 and main list windows - resize, focus and close.

Initial Samsung DeX compatibility for Multi Instance Application

To make use of Samsung DeX, the application should comply with a number of Android N's new features. Some code modification may be necessary depending on what SDK version the app targets.

Android N Multi-Window

Supporting Multi-Window allows apps to be dynamically re-sized in Samsung DeX, similar to a desktop environment.

SDK 24 or higher:
android:resizeableActivity="true" should explicitly be declared in application or activity element in Manifest file.

<application
android:icon="@mipmap/ic_launcher"
android:label="@string/app_name"android:resizeableActivity="true"
	...
<activity android:name=".MainActivity">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
</application>

SDK 23 and lower:
Apps targeting SDK 23 and lower may not automatically support Multi-Window. Typically, if an app does not explicitly set a fixed orientation in the Manifest, it will automatically work in Multi-Window mode. To check if you have set a fixed orientation, look for this code in your Manifest attribute: android:screenOrientation=["portrait" | "landscape"]

Multi-Density

To properly work in Samsung DeX, the app must support Android Multi-Density. Multi-Density involves configuring apps with different resources so they can adapt to different screen sizes and resolutions.

Samsung DeX apps must support the following 2 resolutions:
xxxhdpi - 640 dpi
mdpi - 160dpi.

When optimizing an app for Multi-Density, there are 3 specifications apps must generally adhere to:

Pixel density: use dp rather than px.
Text size: use sp instead of pt.
Image assets: ensure you have appropriate image assets for the following resolutions - low (ldpi), medium (mdpi), high (hdpi) and extra-high (xhdpi) density etc.

Support runtime configuration changes

App has to properly handle Android runtime configuration changes. This is to prevent apps from losing their current activity, display state or crashing when a user launches DeX or re-sizes an app in Desktop mode. It can be declared in Manifest.

<application
android:allowBackup="true"
android:configChanges="screenSize|smallestScreenSize|screenLayout|orientation"
        ...
<activity android:name=".MainActivity">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
</application>

Ensuring apps handle run-time changes is a part of following, Android's best practices.
https://developer.android.com/guide/topics/resources/runtime-changes.html

Application flow

MainActivity is main window of application, opened in DeX mode. The window is resizable and can be dismissed.

MainActivity initial window

MainActivity resized window

To launch separate Activity for every user item that will be clicked on the list, build Intent with flags:

Intent.FLAG_ACTIVITY_LAUNCH_ADJACENT,
Intent.FLAG_ACTIVITY_NEW_TASK,
Intent.FLAG_ACTIVITY_MULTIPLE_TASK.

Intent i= new Intent(MainActivity.this, UserConversationActivity.class).setFlags(Intent.FLAG_ACTIVITY_LAUNCH_ADJACENT |
Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_MULTIPLE_TASK);

Focus on windows can be changed by clicking window top bar or by clicking activity icon on task bar.

MainActivity with multiple UserConversationActivities

Tip: To manage focus of previously opened windows (ex. bringing back to front) you should obtain and stash taskId of the launched Activity and bring it back to front every time the user clicks previously opened window.

Changing the focus of window can be done by mouse interaction or clicking the user on MainActivity list.

Tip: Remember that the Activity is recreated every time the window is resized.

Android and Samsung DeX

Samsung DeX is an environment that mimics a window application environment, but works as an Android system and all the Android components undergo their own Android lifecycles. Therefore the window management is a Multi-Window mode on Android. For example: the window can be closed from the DeX mode by clicking "X" button. It disappears from the bottom taskbar, but can be brought back from the Task Manager. Only closing Activity from Task Manager dismisses the window.