Modifying your app

Modifying apps for Samsung DeX

This section provides an overview of how to modify apps to launch in Samsung DeX. Please note that due to code variance from app to app, not all use-cases may be covered. Additional Android resources may be required to get specific apps working.

Samsung DeX app modification checklist

The Samsung DeX app modification process is as follows:

  • Determine app requirements.
    Fixed-size Window or Resizable window?
  • Implement code modifications.
    Follow the mandatory requirements.
  • Test the app in Samsung DeX.

App modification overview

The Samsung DeX app modification process is as follows:

Features Requirements
To launch app in Desktop mode in a Multi-window with Fixed window size.
  1. 1.

    Multi-Density (640 dpi, 160 dpi) support.

  2. 2.

    Faketouch support (mouse or touchpad).

To launch app in Resizable Multi-Window in desktop mode.
  1. 1.

    Android N Multi-Window and Explicitly declare, android:resizableActivity="true“ .

  2. 2.

    Handle 7 runtime configuration changes and ‘Keepalive’ declaration in Manifest.

Optional features for rich UI.
  1. 1.

    Mouse right click.

  2. 2.

    Optimize Samsung internet.

  3. 3.

    Mouse-wheel zoom.

  4. 4.

    Mouse Icon change.

  5. 5.

    Scrollbar.

  6. 6.

    Keyboard combination.

  7. 7.

    File drag and drop.

  8. 8.

    Disable presentation class.

  9. 9.

    Disable fixed orientation for camera.

Mandatory requirements (Fixed-size Window in Desktop mode)

Apps must meet these mandatory requirements in order to open in Fixed-size Window in Desktop mode.

  1. 1.

    Apps must support Multi-Density for xxxhdpi (640 dpi) and mdpi (160 dpi).

  2. 2.

    Apps must support mouse or trackpad interaction.

Apps must support Multi-Density

Multi-Density involves configuring apps with different resources so they can adapt to different screen sizes and resolutions. Samsung DeX apps must be able to handle both xxxhdpi (640 dpi) and mdpi (160 dpi) resolutions. This is to ensure that apps can be rendered both in mobile (xxxhdpi) and Samsung DeX (mdpi). This may include adjustments such as:

  • Ensuring layouts are resized to fit the Samsung DeX screen resolution.

  • Ensuring images scale properly to the Samsung DeX screen resolution.

  • Ensuring the correct UI appears in Samsung DeX according to new screen configurations.

For more information, see Androids best practices for supporting different densities and screen sizes.

Tip:

Building a responsive layout from the ground up will ensure that your app provides the best user experience. Sometimes, a pre-existing tablet UI can be used as an easy starting point for layouts in different resolutions.

Here some basic examples illustrating the types of changes necessary support Multi-Density.

Here is an example of how an app declares different density’s in the Manifest.

  1. 1.

    Pixel density: Use dp rather than px to ensure layouts scale properly. For example, the following code shows an example of using dp in the Manifest:

    <TextView
        android:id="@+id/title"
        android:layout_marginTop="20dp"
        android:text="@string/title"/>
  2. 2.

    Image assets: Ensure appropriate image assets exist for different resolutions. For example, the following image shows the asset folders with different images for mdpi and xxxhdpi:

    Figure 2: Mobile mode VS Desktop mode

Apps must support mouse or trackpad interaction

Apps must not declare that touchscreen or Multi-Touch is required in the Manifest. This disables apps from using a mouse in Samsung DeX. Apps should not block faketouch input, otherwise users cannot use apps with a mouse or touchpad.

Keyboard and mouse

If possible, apps should support a Bluetooth or USB keyboard and mouse.

If an app is having issues with mouse and keyboard support in Samsung DeX, check to make sure the mouse and keyboard are not explicitly disabled in the Manifest. To do this, make sure 2 statements are not declared in the Manifest:

  • <uses-configuration android:reqTouchScreen="finger">

  • <uses-feature android:name="android.hardware.touchscreen" android:required="true">

For more details on avoiding explicit declaration of touchscreen, See Android's page on uses-configuration and uses-feature.

Requirements to launch app as resizable window in desktop mode

Apps must meet these mandatory requirements to open in Desktop Mode.

  1. 1.

    Support Android N Multi-Window and explicitly declare android:resizableActivity="true" in the Manifest file.

  2. 2.

    Support 7 runtime configuration changes and explicitly declare that it meets these conditions in the Manifest with <meta-data android:name="com.samsung.android.keepalive.density" android:value="true"/>.

Multi-Window support

Supporting Android N based Multi-Window feature allows apps to be dynamically re-sized in Samsung DeX. For more information on implementing Multi-Window, see Android's Multi-Window reference guide.

Multi-Window is very easy to implement as it is built on top of Androids pre-existing resource system – in which apps can provide multiple resources to change how they appear (layouts, menus, etc). Multi-Window uses these resources to adjust app configurations based on the size of the display window. This allow apps to be re-sized in free-form, just like on a desktop.

Note:

If an app launches an activity in another app, the subsequent app must also support Multi-Window. Activities that can be started by other apps will inherit the same multi-window properties as the calling Activity.

To implement Multi-Window in Samsung DeX

SDK 24 and higher: Apps targeting SDK 24 and higher automatically support Multi-Window as a native feature by default. However, apps operating in Samsung DeX Desktop Mode must still explicitly enable Multi-Window in the Manifest to be run in a Resizable Window.

To enable Multi-Window for Samsung DeX, paste this code into the Manifest:

<application
    android:resizeableActivity="true">
</application>

Runtime configuration changes handling .

Runtime configuration changes are important in Android because they are the underlying framework that reloads resources when certain actions are performed. This can include changing the default language, or rotating your device.
In regards to Samsung DeX, a configuration change occurs every time the device is placed into the Samsung DeX Station. If configuration changes are not handled properly, the app will not load correctly when it appears on the monitor. For example, if a full screen video is playing when the device is plugged into the DeX Station, it should not restart back to the beginning, change orientation or exit full screen when cast to the monitor. The transition should be seamless. For full details on handling runtime changes, See Android's page on runtime changes.

Samsung DeX runtime changes

By default, apps are automatically killed when they switch between mobile mode and Samsung DeX. However, some exceptions exist, such as preloaded Samsung Apps. To ensure your app is not automatically closed upon launching in Samsung DeX, a number of Android run time configuration standards must be followed.

Runtime changes that apps need to implement for Samsung DeX: ORIENTATION, SCREEN_LAYOUT, SCREEN_SIZE, SMALLEST_SCREEN_SIZE.

This includes considerations for:

  • Density change between xxxhdpi and mdpi.

  • Resolution change between WQHD and FHD.

  • Orientation change between portrait to landscape.

  • Screen layout change.

  • Screen size change.

  • Smallest screen size change.

  • UI mode change between mobile and desktop.

The image below shows an example of the configuration changes that may be required:

Here, configuration changes are handled dynamically by adding theandroid:configChangesflag to the activity's Manifest. Please note that the actual implementation of the configuration changes will vary from app to app, depending on what type of content is being served. For a useful jump off point on configuration changes, see Androids section on Re-sizing Tasks and Windows.

Keepalive declaration

If an app can handle the above 7 runtime changes and operate in Samsung DeX without issues, it must declare the following "keepalive" declaration in the Manifest:

<application>
    <meta-data android:name="com.samsung.android.keepalive.density" android:value="true"/>
</application>

This manifest declaration identifies to Samsung DeX that app has been tested and runs properly. This prevents Samsung DeX from automatically killing the app when switching between views. The table below shows how an app will behave with or without the Manifest declaration.

"keepalive" declaration in Manifest" App status before switching App status before switching
Yes Foreground
Background
Alive
Alive
No Foreground
Background
Killed and restarted
Killed
Detect Samsung DeX mode

When the display mode is changed from mobile mode to Samsung DeX, its configuration is changed. Use the below system configurations to detect Samsung DeX mode.

  • UI mode : desk

  • Screen layout : xlarge

  • UI mode : desk

  • Density : mdpi

  • Resolution : FHD

  • Orientation: portrait -> landscape

This code snippet shows how to Query the current status of DeX (for 3rd party apps)

import android.content.res.Configuration;
import java.lang.reflect.Field;
import java.lang.Class;

Configuration config = getResources().getConfiguration();
      try {
          Class configClass = config.getClass();
          if(configClass.getField("SEM_DESKTOP_MODE_ENABLED").getInt(configClass)
          == configClass.getField("semDesktopModeEnabled").getInt(config)) {

          // Samsung DeX mode enabled
         }
      } catch(NoSuchFieldException e) {
      } catch(IllegalAccessException e) {
      } catch(IllegalArgumentException e) {
      }

Optional Compatibility features

For the best Desktop experience, apps should meet these optional compatibility features. However, They are not required to launch in Desktop Mode.

Samsung Mobile Browser

Follow these instructions to provide a desktop experience with the Samsung Internet Browser.

  1. By default, open web pages in "Desktop View" instead of "Mobile View"

    Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko)
    SamsungBrowser/$app_ver Chrome/$engine_ver Safari/537.36
    ※ Current values: app_ver = 5.2 , engine_ver = 51.0.2704.106
    
    • User Agent String for Samsung Internet “Desktop View: Based on Chrome Linux UA with additional SamsungBrowser/$ver keyword

  2. Allow users to switch to mobile when needed.

    Mozilla/5.0 (Linux; Android $ver; $model) AppleWebKit/537.36 (KHTML, like Gecko)
    SamsungBrowser/$app_ver Chrome/$engine_ver Mobile Safari/537.36
    ※ Current values: android_ver = 7.0 app_ver = 5.2 , engine_ver = 51.0.2704.106\
    • User Agent String for Samsung Internet "Mobile View"

  3. Support Mouse Events

    • In Samsung DeX mode, mouse events are processed as mouse events (In mobile mode, mouse events are transferred to touch events). However, because Touchpad is a supported input device in Samsung DeX, touch events are also supported.

    • Removing mouse event listeners on touch supported browsers might limit mouse usage on your web site.

  4. Support auto-play

    <video width="320" height="240" controls autoplay> <source src="movie.ogg" type="video/ogg">
    • HTML < video > autoplay attribute works in Desktop Mode (not supported in mobile mode)

Mouse Right Click

Enabling mouse right-click allows for easier interaction with apps. For example, it can be useful for showing desktop-like action such as a contextual menu.

If an app uses the EditTextView of the Google API, it does not need to implement additional features for using mouse right click. In EditTextview, the following actions are available:

  1. 1.

    Mouse right-click: show Contextual Menu.

  2. 2.

    Mouse left-double click on text: select the text.

If an app is not using EditTextView of the Google API, this code snippet enable mouse right click.

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.activity_main);
  layout_main = (RelativeLayout) findViewById(R.id.layout_main);
  registerForContextMenu(layout_main);
}

@Override
public void onCreateContextMenu(ContextMenu menu,
                    View v, ContextMenu.ContextMenuInfo menuInfo){
  if (v.getId() == R.id.layout_main) {
	  menu.setHeaderTitle("Context Menu Test");
	  menu.add(Menu.NONE, ONE, Menu.NONE, "Menu 1");
  }
  super.onCreateContextMenu(menu, v, menuInfo);
}

@Override
public boolean onTouchEvent(MotionEvent event) {
  if (event.getAction() == MotionEvent.ACTION_DOWN &&
	   event.getButtonState() == MotionEvent.BUTTON_SECONDARY) {

	  layout_main.showContextMenu(event.getX(), event.getY());
  }
  return super.onTouchEvent(event);
}

Mouse-wheel zoom

Enabling mouse-wheel zoom allows for easier interaction with apps that require Multi-Touch zoom (pinch zoom in and out) to operate efficiently. For example, maps or games. To enable Multi-Touch, an app must receive the wheel up/down eventMotionEvent.ACTION_SCROLL in Activity.dispatchTouchEvent(MotionEvent event) and apply the pinch-zoom function of the app with step by step information of the wheel scroll.

For example:final float vScroll = event.getAxisValue(MotionEvent.AXIS_VSCROLL);
- vScroll is -1.0, wheel down.
- vScroll is 1.0, wheel up.

@Override public boolean onGenericMotion(View v, MotionEvent event) {
	int action = event.getAction();
	int actionCode = action & MotionEvent.ACTION MASK;

	for (int i = 0; i < event.getPointerCount(); i++) {
		float x = event.getX(i);
		float y = event.getY(i);
		float p = event.getPressure(i);
		int pid = event.getPointerld(i);

		if (actionCode == MotionEvent.ACTION_SCROLL) {
			float wheelX = event.getAxisValue(MotionEvent.AXIS_HSCROLL, i);
			float wheelY = event.getAxisValue(MotionEvent.AXIS_VSCROLL, i);
			SOLMain.mcNativeTouch(actionCode, wheelX, wheelY, p, pid);

			return true;
		}
	}
}
	

Mouse Icon change

This allows the mouse icon to change when pointed at a clickable object. To change the mouse icon, set android:state_hovered="true" on the required views.

For example:

App/res/drawable/tw_list_selector_material_light.xml
<selector xmlns:android="http://schemas.android.com/apk/res/android">
    <item android:state_hovered="true" android:state_finger_hovered="true">
      <nine-patch android:src="@drawable/tw_list_hover_holo_light" />
    </item>

See Android's Pointer Icon , Set Pointer Icon and Resolve Pointer Icon reference guides for more details.

Mouse app scroll bar

Mouse scrolling works automatically if apps use ListView, GridView, or ScrollView / HorizontalScrollView of the Google SDK. See Android's App Scroll Bar reference guide for more details

Keyboard shortcuts

Keyboard shortcuts provide enhanced multi-tasking usability in apps. See Android's Keyboard Input reference guide for more details.

Drag and drop files

Drag and dropping files in Android allows you to easily move files between views. See Android Drag-Drop , Drag on listener and Drag events reference guides for more details.

Disable presentation class on Samsung DeX mode

Presentation class allows an app to show content on a secondary display. This may not be ideal for Samsung DeX apps, and can be disabled if needed. See Android's App Presentation reference guide for more details.

Disable fixed orientation for camera

If an app requires fixed orientation for camera use, it may not translate well to Samsung DeX Desktop mode. Fixed orientation for camera can be disabled, if needed. See Android's Camera reference guide for more details.