FileDocCategorySizeDatePackage
DisplayManager.javaAPI DocAndroid 5.1 API22275Thu Mar 12 22:22:10 GMT 2015android.hardware.display

DisplayManager

public final class DisplayManager extends Object
Manages the properties of attached displays.

Get an instance of this class by calling {@link android.content.Context#getSystemService(java.lang.String) Context.getSystemService()} with the argument {@link android.content.Context#DISPLAY_SERVICE}.

Fields Summary
private static final String
TAG
private static final boolean
DEBUG
private final android.content.Context
mContext
private final DisplayManagerGlobal
mGlobal
private final Object
mLock
private final android.util.SparseArray
mDisplays
private final ArrayList
mTempDisplays
public static final String
ACTION_WIFI_DISPLAY_STATUS_CHANGED
Broadcast receiver that indicates when the Wifi display status changes.

The status is provided as a {@link WifiDisplayStatus} object in the {@link #EXTRA_WIFI_DISPLAY_STATUS} extra.

This broadcast is only sent to registered receivers and can only be sent by the system.

public static final String
EXTRA_WIFI_DISPLAY_STATUS
Contains a {@link WifiDisplayStatus} object.
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 HDMI or Wireless displays. Applications may automatically project their content to presentation displays to provide richer second screen experiences.

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 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 that isn't restricted to own-content only implicitly creates an auto-mirroring display. See {@link #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 {@link 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 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.

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 {@link #DISPLAY_CATEGORY_PRESENTATION 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.

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 {@link 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 {@link android.Manifest.permission#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.

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 {@link #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 {@link #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 {@link #VIRTUAL_DISPLAY_FLAG_PUBLIC} nor {@link #VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR} have been set. This flag is only required to override the default behavior when creating a public display.

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 {@link #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 {@link #VIRTUAL_DISPLAY_FLAG_PUBLIC} is set and {@link #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 {@link android.Manifest.permission#CAPTURE_VIDEO_OUTPUT} or {@link android.Manifest.permission#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 {@link MediaProjection} may be used to create an auto-mirroring virtual display.

Constructors Summary
public DisplayManager(android.content.Context context)

hide


      
       
        mContext = context;
        mGlobal = DisplayManagerGlobal.getInstance();
Methods Summary
private voidaddAllDisplaysLocked(java.util.ArrayList displays, int[] displayIds)

        for (int i = 0; i < displayIds.length; i++) {
            Display display = getOrCreateDisplayLocked(displayIds[i], true /*assumeValid*/);
            if (display != null) {
                displays.add(display);
            }
        }
private voidaddPresentationDisplaysLocked(java.util.ArrayList displays, int[] displayIds, int matchType)

        for (int i = 0; i < displayIds.length; i++) {
            Display display = getOrCreateDisplayLocked(displayIds[i], true /*assumeValid*/);
            if (display != null
                    && (display.getFlags() & Display.FLAG_PRESENTATION) != 0
                    && display.getType() == matchType) {
                displays.add(display);
            }
        }
public voidconnectWifiDisplay(java.lang.String deviceAddress)
Connects to a Wifi display. The results are sent as a {@link #ACTION_WIFI_DISPLAY_STATUS_CHANGED} broadcast.

Automatically remembers the display after a successful connection, if not already remembered.

Requires {@link android.Manifest.permission#CONFIGURE_WIFI_DISPLAY}.

param
deviceAddress The MAC address of the device to which we should connect.
hide

        mGlobal.connectWifiDisplay(deviceAddress);
public VirtualDisplaycreateVirtualDisplay(java.lang.String name, int width, int height, int densityDpi, android.view.Surface surface, int flags)
Creates a virtual display.

see
#createVirtualDisplay(String, int, int, int, Surface, int, VirtualDisplay.Callback)

        return createVirtualDisplay(name, width, height, densityDpi, surface, flags, null, null);
public VirtualDisplaycreateVirtualDisplay(java.lang.String name, int width, int height, int densityDpi, android.view.Surface surface, int flags, VirtualDisplay.Callback callback, android.os.Handler handler)
Creates a virtual display.

The content of a virtual display is rendered to a {@link Surface} provided by the application.

The virtual display should be {@link VirtualDisplay#release 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 {@link android.os.Build.VERSION_CODES#KITKAT_WATCH}, the surface may be attached or detached dynamically using {@link VirtualDisplay#setSurface}. Previously, the surface had to be non-null when {@link #createVirtualDisplay} 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.

param
name The name of the virtual display, must be non-empty.
param
width The width of the virtual display in pixels, must be greater than 0.
param
height The height of the virtual display in pixels, must be greater than 0.
param
densityDpi The density of the virtual display in dpi, must be greater than 0.
param
surface The surface to which the content of the virtual display should be rendered, or null if there is none initially.
param
flags A combination of virtual display flags: {@link #VIRTUAL_DISPLAY_FLAG_PUBLIC}, {@link #VIRTUAL_DISPLAY_FLAG_PRESENTATION}, {@link #VIRTUAL_DISPLAY_FLAG_SECURE}, {@link #VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY}, or {@link #VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR}.
param
callback Callback to call when the state of the {@link VirtualDisplay} changes
param
handler The handler on which the listener should be invoked, or null if the listener should be invoked on the calling thread's looper.
return
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.

        return createVirtualDisplay(null,
                name, width, height, densityDpi, surface, flags, callback, handler);
public VirtualDisplaycreateVirtualDisplay(android.media.projection.MediaProjection projection, java.lang.String name, int width, int height, int densityDpi, android.view.Surface surface, int flags, VirtualDisplay.Callback callback, android.os.Handler handler)

hide

        return mGlobal.createVirtualDisplay(mContext, projection,
                name, width, height, densityDpi, surface, flags, callback, handler);
public voiddisconnectWifiDisplay()
Disconnects from the current Wifi display. The results are sent as a {@link #ACTION_WIFI_DISPLAY_STATUS_CHANGED} broadcast.

hide

        mGlobal.disconnectWifiDisplay();
public voidforgetWifiDisplay(java.lang.String deviceAddress)
Forgets a previously remembered Wifi display.

Automatically disconnects from the display if currently connected to it.

Requires {@link android.Manifest.permission#CONFIGURE_WIFI_DISPLAY}.

param
deviceAddress The MAC address of the device to forget.
hide

        mGlobal.forgetWifiDisplay(deviceAddress);
public android.view.DisplaygetDisplay(int displayId)
Gets information about a logical display. The display metrics may be adjusted to provide compatibility for legacy applications.

param
displayId The logical display id.
return
The display object, or null if there is no valid display with the given id.

        synchronized (mLock) {
            return getOrCreateDisplayLocked(displayId, false /*assumeValid*/);
        }
public android.view.Display[]getDisplays()
Gets all currently valid logical displays.

return
An array containing all displays.

        return getDisplays(null);
public android.view.Display[]getDisplays(java.lang.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 {@link #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.

param
category The requested display category or null to return all displays.
return
An array containing all displays sorted by order of preference.
see
#DISPLAY_CATEGORY_PRESENTATION

        final int[] displayIds = mGlobal.getDisplayIds();
        synchronized (mLock) {
            try {
                if (category == null) {
                    addAllDisplaysLocked(mTempDisplays, displayIds);
                } else if (category.equals(DISPLAY_CATEGORY_PRESENTATION)) {
                    addPresentationDisplaysLocked(mTempDisplays, displayIds, Display.TYPE_WIFI);
                    addPresentationDisplaysLocked(mTempDisplays, displayIds, Display.TYPE_HDMI);
                    addPresentationDisplaysLocked(mTempDisplays, displayIds, Display.TYPE_OVERLAY);
                    addPresentationDisplaysLocked(mTempDisplays, displayIds, Display.TYPE_VIRTUAL);
                }
                return mTempDisplays.toArray(new Display[mTempDisplays.size()]);
            } finally {
                mTempDisplays.clear();
            }
        }
private android.view.DisplaygetOrCreateDisplayLocked(int displayId, boolean assumeValid)

        Display display = mDisplays.get(displayId);
        if (display == null) {
            display = mGlobal.getCompatibleDisplay(displayId,
                    mContext.getDisplayAdjustments(displayId));
            if (display != null) {
                mDisplays.put(displayId, display);
            }
        } else if (!assumeValid && !display.isValid()) {
            display = null;
        }
        return display;
public WifiDisplayStatusgetWifiDisplayStatus()
Gets the current Wifi display status. Watch for changes in the status by registering a broadcast receiver for {@link #ACTION_WIFI_DISPLAY_STATUS_CHANGED}.

return
The current Wifi display status.
hide

        return mGlobal.getWifiDisplayStatus();
public voidpauseWifiDisplay()

hide

        mGlobal.pauseWifiDisplay();
public voidregisterDisplayListener(android.hardware.display.DisplayManager$DisplayListener listener, android.os.Handler handler)
Registers an display listener to receive notifications about when displays are added, removed or changed.

param
listener The listener to register.
param
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
#unregisterDisplayListener

        mGlobal.registerDisplayListener(listener, handler);
public voidrenameWifiDisplay(java.lang.String deviceAddress, java.lang.String alias)
Renames a Wifi display.

The display must already be remembered for this call to succeed. In other words, we must already have successfully connected to the display at least once and then not forgotten it.

Requires {@link android.Manifest.permission#CONFIGURE_WIFI_DISPLAY}.

param
deviceAddress The MAC address of the device to rename.
param
alias The alias name by which to remember the device, or null or empty if no alias should be used.
hide

        mGlobal.renameWifiDisplay(deviceAddress, alias);
public voidresumeWifiDisplay()

hide

        mGlobal.resumeWifiDisplay();
public voidstartWifiDisplayScan()
Starts scanning for available Wifi displays. The results are sent as a {@link #ACTION_WIFI_DISPLAY_STATUS_CHANGED} broadcast.

Calls to this method nest and must be matched by an equal number of calls to {@link #stopWifiDisplayScan()}.

Requires {@link android.Manifest.permission#CONFIGURE_WIFI_DISPLAY}.

hide

        mGlobal.startWifiDisplayScan();
public voidstopWifiDisplayScan()
Stops scanning for available Wifi displays.

Requires {@link android.Manifest.permission#CONFIGURE_WIFI_DISPLAY}.

hide

        mGlobal.stopWifiDisplayScan();
public voidunregisterDisplayListener(android.hardware.display.DisplayManager$DisplayListener listener)
Unregisters a display listener.

param
listener The listener to unregister.
see
#registerDisplayListener

        mGlobal.unregisterDisplayListener(listener);