Added in API level 17

Summary: Nested Classes | Constants | Methods | Inherited Methods

DisplayManager

---

Kotlin |Java

public final class DisplayManager
extends Object

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

---

Manages the properties of attached displays.

Summary

Nested classes
interface	DisplayManager.DisplayListener Listens for changes in available display devices.

Constants
String	DISPLAY_CATEGORY_PRESENTATION Display category: Presentation displays.
int	MATCH_CONTENT_FRAMERATE_ALWAYS Refresh rate switches between all refresh rates are allowed even if they have visual interruptions for the user.
int	MATCH_CONTENT_FRAMERATE_NEVER No mode switching is allowed.
int	MATCH_CONTENT_FRAMERATE_SEAMLESSS_ONLY Only refresh rate switches without visual interruptions are allowed.
int	MATCH_CONTENT_FRAMERATE_UNKNOWN Match content frame rate user preference is unknown.
int	VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR Virtual display flag: Allows content to be mirrored on private displays when no content is being shown.
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.
VirtualDisplay	createVirtualDisplay(VirtualDisplayConfig config) Creates a virtual display.
VirtualDisplay	createVirtualDisplay(String name, int width, int height, int densityDpi, Surface surface, int flags, VirtualDisplay.Callback callback, Handler handler) Creates a virtual display.
VirtualDisplay	createVirtualDisplay(VirtualDisplayConfig config, Handler handler, VirtualDisplay.Callback callback) 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.
HdrConversionMode	getHdrConversionMode() Returns the HdrConversionMode of the device, which is set by the user.
int	getMatchContentFrameRateUserPreference() Returns the user preference for "Match content frame rate".
void	registerDisplayListener(DisplayManager.DisplayListener listener, Handler handler) Registers a display listener to receive notifications about when displays are added, removed or changed.
void	unregisterDisplayListener(DisplayManager.DisplayListener listener) Unregisters a display listener.

Inherited methods

From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Constants

DISPLAY_CATEGORY_PRESENTATION

Added in API level 17

public static final String DISPLAY_CATEGORY_PRESENTATION

Display category: Presentation displays.

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

See also:

• Presentation
• Display.FLAG_PRESENTATION
• getDisplays(String)

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

MATCH_CONTENT_FRAMERATE_ALWAYS

Added in API level 31

public static final int MATCH_CONTENT_FRAMERATE_ALWAYS

Refresh rate switches between all refresh rates are allowed even if they have visual interruptions for the user.

Constant Value: 2 (0x00000002)

MATCH_CONTENT_FRAMERATE_NEVER

Added in API level 31

public static final int MATCH_CONTENT_FRAMERATE_NEVER

No mode switching is allowed.

Constant Value: 0 (0x00000000)

MATCH_CONTENT_FRAMERATE_SEAMLESSS_ONLY

Added in API level 31

public static final int MATCH_CONTENT_FRAMERATE_SEAMLESSS_ONLY

Only refresh rate switches without visual interruptions are allowed.

Constant Value: 1 (0x00000001)

MATCH_CONTENT_FRAMERATE_UNKNOWN

Added in API level 31

public static final int MATCH_CONTENT_FRAMERATE_UNKNOWN

Match content frame rate user preference is unknown.

Constant Value: -1 (0xffffffff)

VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR

Added in API level 21

public static final int VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR

Virtual display flag: Allows content to be mirrored on private displays when no content is being shown.

This flag is mutually exclusive with VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY. If both flags are specified then the own-content only behavior will be applied.

The behavior of this flag is implied whenever VIRTUAL_DISPLAY_FLAG_PUBLIC is set and VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY has not been set. This flag is only required to override the default behavior when creating a private display.

Creating an auto-mirroing 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. Alternatively, an appropriate MediaProjection may be used to create an auto-mirroring virtual display.

See also:

• createVirtualDisplay(VirtualDisplayConfig)

Constant Value: 16 (0x00000010)

VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY

Added in API level 20

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.

This flag is mutually exclusive with VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR. If both flags are specified then the own-content only behavior will be applied.

This behavior of this flag is implied whenever neither VIRTUAL_DISPLAY_FLAG_PUBLIC nor VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR have been set. This flag is only required to override the default behavior when creating a public display.

See also:

• createVirtualDisplay(VirtualDisplayConfig)

Constant Value: 8 (0x00000008)

VIRTUAL_DISPLAY_FLAG_PRESENTATION

Added in API level 19

public static final int VIRTUAL_DISPLAY_FLAG_PRESENTATION

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:

• Presentation
• createVirtualDisplay(VirtualDisplayConfig)
• DISPLAY_CATEGORY_PRESENTATION
• Display.FLAG_PRESENTATION

Constant Value: 2 (0x00000002)

VIRTUAL_DISPLAY_FLAG_PUBLIC

Added in API level 19

public static final int VIRTUAL_DISPLAY_FLAG_PUBLIC

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 external 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 that isn't restricted to own-content only implicitly creates an auto-mirroring display. See VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR for restrictions on who is allowed to create an auto-mirroring display.

Private virtual displays

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

A private virtual display belongs to the application that created it. Only the a owner of a private virtual display and the apps that are already on that display are 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 or as the activities that are already on that display.

See also:

• createVirtualDisplay(VirtualDisplayConfig)
• VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY
• VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR

Constant Value: 1 (0x00000001)

VIRTUAL_DISPLAY_FLAG_SECURE

Added in API level 19

public static final int VIRTUAL_DISPLAY_FLAG_SECURE

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 Display#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:

• Display.FLAG_SECURE
• createVirtualDisplay(VirtualDisplayConfig)

Constant Value: 4 (0x00000004)

Public methods

createVirtualDisplay

Added in API level 19

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

Creates a virtual display.

Parameters
name	String: This value cannot be null.
width	int: Value is 1 or greater
height	int: Value is 1 or greater
densityDpi	int: Value is 1 or greater
surface	Surface: This value may be null.
flags	int: Value is either 0 or a combination of VIRTUAL_DISPLAY_FLAG_PUBLIC, VIRTUAL_DISPLAY_FLAG_PRESENTATION, VIRTUAL_DISPLAY_FLAG_SECURE, VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY, VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR, android.hardware.display.DisplayManager.VIRTUAL_DISPLAY_FLAG_CAN_SHOW_WITH_INSECURE_KEYGUARD, android.hardware.display.DisplayManager.VIRTUAL_DISPLAY_FLAG_SUPPORTS_TOUCH, android.hardware.display.DisplayManager.VIRTUAL_DISPLAY_FLAG_ROTATES_WITH_CONTENT, android.hardware.display.DisplayManager.VIRTUAL_DISPLAY_FLAG_DESTROY_CONTENT_ON_REMOVAL, android.hardware.display.DisplayManager.VIRTUAL_DISPLAY_FLAG_SHOULD_SHOW_SYSTEM_DECORATIONS, android.hardware.display.DisplayManager.VIRTUAL_DISPLAY_FLAG_TRUSTED, android.hardware.display.DisplayManager.VIRTUAL_DISPLAY_FLAG_OWN_DISPLAY_GROUP, android.hardware.display.DisplayManager.VIRTUAL_DISPLAY_FLAG_ALWAYS_UNLOCKED, android.hardware.display.DisplayManager.VIRTUAL_DISPLAY_FLAG_TOUCH_FEEDBACK_DISABLED, android.hardware.display.DisplayManager.VIRTUAL_DISPLAY_FLAG_OWN_FOCUS, and android.hardware.display.DisplayManager.VIRTUAL_DISPLAY_FLAG_STEAL_TOP_FOCUS_DISABLED

Returns
VirtualDisplay

See also:

• createVirtualDisplay(String, int, int, int, Surface, int, VirtualDisplay.Callback, Handler)

createVirtualDisplay

Added in API level 34

public VirtualDisplay createVirtualDisplay (VirtualDisplayConfig config)

Creates a virtual display.

Parameters
config	VirtualDisplayConfig: This value cannot be null.

Returns
VirtualDisplay	This value may be null.

See also:

• createVirtualDisplay(VirtualDisplayConfig, Handler, VirtualDisplay.Callback)

createVirtualDisplay

Added in API level 21

public VirtualDisplay createVirtualDisplay (String name, 
                int width, 
                int height, 
                int densityDpi, 
                Surface surface, 
                int flags, 
                VirtualDisplay.Callback callback, 
                Handler handler)

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 Build.VERSION_CODES.KITKAT_WATCH, the surface may be attached or detached dynamically using VirtualDisplay#setSurface. Previously, the surface had to be non-null when createVirtualDisplay(VirtualDisplayConfig) 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	String: The name of the virtual display, must be non-empty. This value cannot be null.
width	int: The width of the virtual display in pixels, must be greater than 0. Value is 1 or greater
height	int: The height of the virtual display in pixels, must be greater than 0. Value is 1 or greater
densityDpi	int: The density of the virtual display in dpi, must be greater than 0. Value is 1 or greater
surface	Surface: The surface to which the content of the virtual display should be rendered, or null if there is none initially.
flags	int: A combination of virtual display flags: VIRTUAL_DISPLAY_FLAG_PUBLIC, VIRTUAL_DISPLAY_FLAG_PRESENTATION, VIRTUAL_DISPLAY_FLAG_SECURE, VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY, or VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR. Value is either 0 or a combination of VIRTUAL_DISPLAY_FLAG_PUBLIC, VIRTUAL_DISPLAY_FLAG_PRESENTATION, VIRTUAL_DISPLAY_FLAG_SECURE, VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY, VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR, android.hardware.display.DisplayManager.VIRTUAL_DISPLAY_FLAG_CAN_SHOW_WITH_INSECURE_KEYGUARD, android.hardware.display.DisplayManager.VIRTUAL_DISPLAY_FLAG_SUPPORTS_TOUCH, android.hardware.display.DisplayManager.VIRTUAL_DISPLAY_FLAG_ROTATES_WITH_CONTENT, android.hardware.display.DisplayManager.VIRTUAL_DISPLAY_FLAG_DESTROY_CONTENT_ON_REMOVAL, android.hardware.display.DisplayManager.VIRTUAL_DISPLAY_FLAG_SHOULD_SHOW_SYSTEM_DECORATIONS, android.hardware.display.DisplayManager.VIRTUAL_DISPLAY_FLAG_TRUSTED, android.hardware.display.DisplayManager.VIRTUAL_DISPLAY_FLAG_OWN_DISPLAY_GROUP, android.hardware.display.DisplayManager.VIRTUAL_DISPLAY_FLAG_ALWAYS_UNLOCKED, android.hardware.display.DisplayManager.VIRTUAL_DISPLAY_FLAG_TOUCH_FEEDBACK_DISABLED, android.hardware.display.DisplayManager.VIRTUAL_DISPLAY_FLAG_OWN_FOCUS, and android.hardware.display.DisplayManager.VIRTUAL_DISPLAY_FLAG_STEAL_TOP_FOCUS_DISABLED
callback	VirtualDisplay.Callback: Callback to call when the state of the VirtualDisplay changes This value may be null.
handler	Handler: The handler on which the listener should be invoked, or null if the listener should be invoked on the calling thread's looper.

Returns
VirtualDisplay	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.

createVirtualDisplay

Added in API level 34

public VirtualDisplay createVirtualDisplay (VirtualDisplayConfig config, 
                Handler handler, 
                VirtualDisplay.Callback callback)

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 Build.VERSION_CODES.KITKAT_WATCH, the surface may be attached or detached dynamically using VirtualDisplay#setSurface. Previously, the surface had to be non-null when createVirtualDisplay(VirtualDisplayConfig) 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
config	VirtualDisplayConfig: The configuration of the virtual display, must be non-null.
handler	Handler: The handler on which the listener should be invoked, or null if the listener should be invoked on the calling thread's looper.
callback	VirtualDisplay.Callback: Callback to call when the state of the VirtualDisplay changes This value may be null.

Returns
VirtualDisplay	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 flags specified in the configuration.

getDisplay

Added in API level 17

public Display getDisplay (int displayId)

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

Parameters
displayId	int: The logical display id.

Returns
Display	The display object, or null if there is no valid display with the given id.

getDisplays

Added in API level 17

public Display[] getDisplays ()

Gets all currently valid logical displays.

Returns
Display[]	An array containing all displays.

getDisplays

Added in API level 17

public Display[] getDisplays (String category)

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	String: The requested display category or null to return all displays.

Returns
Display[]	An array containing all displays sorted by order of preference.

See also:

• DISPLAY_CATEGORY_PRESENTATION

getHdrConversionMode

Added in API level 34

public HdrConversionMode getHdrConversionMode ()

Returns the HdrConversionMode of the device, which is set by the user. When HdrConversionMode#getConversionMode is HdrConversionMode#HDR_CONVERSION_SYSTEM, the HdrConversionMode#getPreferredHdrOutputType depicts the systemPreferredHdrOutputType. The HDR conversion mode chosen by user which considers the app override is returned. Apps can override HDR conversion using WindowManager.LayoutParams.setHdrConversionEnabled(boolean).

Returns
HdrConversionMode	This value cannot be null.

getMatchContentFrameRateUserPreference

Added in API level 31

public int getMatchContentFrameRateUserPreference ()

Returns the user preference for "Match content frame rate".

Never: Even if the app requests it, the device will never try to match its output to the original frame rate of the content.

Seamless: If the app requests it, the device will match its output to the original frame rate of the content, ONLY if the display can transition seamlessly.

Always: If the app requests it, the device will match its output to the original frame rate of the content. This may cause the screen to go blank for a second when exiting or entering a video playback.

Returns
int	Value is MATCH_CONTENT_FRAMERATE_UNKNOWN, MATCH_CONTENT_FRAMERATE_NEVER, MATCH_CONTENT_FRAMERATE_SEAMLESSS_ONLY, or MATCH_CONTENT_FRAMERATE_ALWAYS

registerDisplayListener

Added in API level 17

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

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

Parameters
listener	DisplayManager.DisplayListener: The listener to register.
handler	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:

• unregisterDisplayListener(DisplayListener)

unregisterDisplayListener

Added in API level 17

public void unregisterDisplayListener (DisplayManager.DisplayListener listener)

Unregisters a display listener.

Parameters
listener	DisplayManager.DisplayListener: The listener to unregister.

See also:

• registerDisplayListener(DisplayListener, Handler)