Android APIs
public final class

DisplayManager

extends Object
java.lang.Object
   ↳ android.hardware.display.DisplayManager

Class Overview

Manages the properties of attached displays.

Get an instance of this class by calling Context.getSystemService() with the argument DISPLAY_SERVICE.

Summary

Nested Classes
interface DisplayManager.DisplayListener Listens for changes in available display devices. 
Constants
String DISPLAY_CATEGORY_PRESENTATION Display category: Presentation displays.
int VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY Virtual display flag: Only show this display's own content; do not mirror the content of another display.
int VIRTUAL_DISPLAY_FLAG_PRESENTATION Virtual display flag: Create a presentation display.
int VIRTUAL_DISPLAY_FLAG_PUBLIC Virtual display flag: Create a public display.
int VIRTUAL_DISPLAY_FLAG_SECURE Virtual display flag: Create a secure display.
Public Methods
VirtualDisplay createVirtualDisplay(String name, int width, int height, int densityDpi, Surface surface, int flags)
Creates a virtual display.
Display getDisplay(int displayId)
Gets information about a logical display.
Display[] getDisplays()
Gets all currently valid logical displays.
Display[] getDisplays(String category)
Gets all currently valid logical displays of the specified category.
void registerDisplayListener(DisplayManager.DisplayListener listener, Handler handler)
Registers an display listener to receive notifications about when displays are added, removed or changed.
void unregisterDisplayListener(DisplayManager.DisplayListener listener)
Unregisters an input device listener.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final String DISPLAY_CATEGORY_PRESENTATION

Added in API level 17

Display category: Presentation displays.

This category can be used to identify secondary displays that are suitable for use as presentation displays such as HDMI or Wireless displays. Applications may automatically project their content to presentation displays to provide richer second screen experiences.

See Also
Constant Value: "android.hardware.display.category.PRESENTATION"

public static final int VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY

Virtual display flag: Only show this display's own content; do not mirror the content of another display.

This flag is used in conjunction with VIRTUAL_DISPLAY_FLAG_PUBLIC. Ordinarily public virtual displays will automatically mirror the content of the default display if they have no windows of their own. When this flag is specified, the virtual display will only ever show its own content and will be blanked instead if it has no windows.

See Also
Constant Value: 8 (0x00000008)

public static final int VIRTUAL_DISPLAY_FLAG_PRESENTATION

Added in API level 19

Virtual display flag: Create a presentation display.

Presentation virtual displays

When this flag is set, the virtual display is registered as a presentation display in the presentation display category. Applications may automatically project their content to presentation displays to provide richer second screen experiences.

Non-presentation virtual displays

When this flag is not set, the virtual display is not registered as a presentation display. Applications can still project their content on the display but they will typically not do so automatically. This option is appropriate for more special-purpose displays.

See Also
Constant Value: 2 (0x00000002)

public static final int VIRTUAL_DISPLAY_FLAG_PUBLIC

Added in API level 19

Virtual display flag: Create a public display.

Public virtual displays

When this flag is set, the virtual display is public.

A public virtual display behaves just like most any other display that is connected to the system such as an HDMI or Wireless display. Applications can open windows on the display and the system may mirror the contents of other displays onto it.

Creating a public virtual display requires the CAPTURE_VIDEO_OUTPUT or CAPTURE_SECURE_VIDEO_OUTPUT permission. These permissions are reserved for use by system components and are not available to third-party applications.

Private virtual displays

When this flag is not set, the virtual display is private as defined by the FLAG_PRIVATE display flag.

A private virtual display belongs to the application that created it. Only the a owner of a private virtual display is allowed to place windows upon it. The private virtual display also does not participate in display mirroring: it will neither receive mirrored content from another display nor allow its own content to be mirrored elsewhere. More precisely, the only processes that are allowed to enumerate or interact with the private display are those that have the same UID as the application that originally created the private virtual display.

See Also
Constant Value: 1 (0x00000001)

public static final int VIRTUAL_DISPLAY_FLAG_SECURE

Added in API level 19

Virtual display flag: Create a secure display.

Secure virtual displays

When this flag is set, the virtual display is considered secure as defined by the FLAG_SECURE display flag. The caller promises to take reasonable measures, such as over-the-air encryption, to prevent the contents of the display from being intercepted or recorded on a persistent medium.

Creating a secure virtual display requires the CAPTURE_SECURE_VIDEO_OUTPUT permission. This permission is reserved for use by system components and is not available to third-party applications.

Non-secure virtual displays

When this flag is not set, the virtual display is considered unsecure. The content of secure windows will be blanked if shown on this display.

See Also
Constant Value: 4 (0x00000004)

Public Methods

public VirtualDisplay createVirtualDisplay (String name, int width, int height, int densityDpi, Surface surface, int flags)

Added in API level 19

Creates a virtual display.

The content of a virtual display is rendered to a Surface provided by the application.

The virtual display should be released when no longer needed. Because a virtual display renders to a surface provided by the application, it will be released automatically when the process terminates and all remaining windows on it will be forcibly removed.

The behavior of the virtual display depends on the flags that are provided to this method. By default, virtual displays are created to be private, non-presentation and unsecure. Permissions may be required to use certain flags.

As of KITKAT_WATCH, the surface may be attached or detached dynamically using setSurface(Surface). Previously, the surface had to be non-null when createVirtualDisplay(String, int, int, int, Surface, int) was called and could not be changed for the lifetime of the display.

Detaching the surface that backs a virtual display has a similar effect to turning off the screen.

Parameters
name The name of the virtual display, must be non-empty.
width The width of the virtual display in pixels, must be greater than 0.
height The height of the virtual display in pixels, must be greater than 0.
densityDpi The density of the virtual display in dpi, must be greater than 0.
surface The surface to which the content of the virtual display should be rendered, or null if there is none initially.
flags A combination of virtual display flags: VIRTUAL_DISPLAY_FLAG_PUBLIC, VIRTUAL_DISPLAY_FLAG_PRESENTATION, VIRTUAL_DISPLAY_FLAG_SECURE, or VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY.
Returns
  • The newly created virtual display, or null if the application could not create the virtual display.
Throws
SecurityException if the caller does not have permission to create a virtual display with the specified flags.

public Display getDisplay (int displayId)

Added in API level 17

Gets information about a logical display. The display metrics may be adjusted to provide compatibility for legacy applications.

Parameters
displayId The logical display id.
Returns
  • The display object, or null if there is no valid display with the given id.

public Display[] getDisplays ()

Added in API level 17

Gets all currently valid logical displays.

Returns
  • An array containing all displays.

public Display[] getDisplays (String category)

Added in API level 17

Gets all currently valid logical displays of the specified category.

When there are multiple displays in a category the returned displays are sorted of preference. For example, if the requested category is DISPLAY_CATEGORY_PRESENTATION and there are multiple presentation displays then the displays are sorted so that the first display in the returned array is the most preferred presentation display. The application may simply use the first display or allow the user to choose.

Parameters
category The requested display category or null to return all displays.
Returns
  • An array containing all displays sorted by order of preference.
See Also

public void registerDisplayListener (DisplayManager.DisplayListener listener, Handler handler)

Added in API level 17

Registers an display listener to receive notifications about when displays are added, removed or changed.

Parameters
listener The listener to register.
handler The handler on which the listener should be invoked, or null if the listener should be invoked on the calling thread's looper.
See Also

public void unregisterDisplayListener (DisplayManager.DisplayListener listener)

Added in API level 17

Unregisters an input device listener.

Parameters
listener The listener to unregister.
See Also