Presentation
open class Presentation : Dialog
kotlin.Any | ||
↳ | android.app.Dialog | |
↳ | android.app.Presentation |
Base class for presentations.
A presentation is a special kind of dialog whose purpose is to present content on a secondary display. A Presentation
is associated with the target Display
at creation time and configures its context and resource configuration according to the display's metrics.
Notably, the Context
of a presentation is different from the context of its containing Activity
. It is important to inflate the layout of a presentation and load other resources using the presentation's own context to ensure that assets of the correct size and density for the target display are loaded.
A presentation is automatically canceled (see Dialog#cancel()
) when the display to which it is attached is removed. An activity should take care of pausing and resuming whatever content is playing within the presentation whenever the activity itself is paused or resumed.
Choosing a presentation display
Before showing a Presentation
it's important to choose the Display
on which it will appear. Choosing a presentation display is sometimes difficult because there may be multiple displays attached. Rather than trying to guess which display is best, an application should let the system choose a suitable presentation display.
There are two main ways to choose a Display
.
Using the media router to choose a presentation display
The easiest way to choose a presentation display is to use the MediaRouter
API. The media router service keeps track of which audio and video routes are available on the system. The media router sends notifications whenever routes are selected or unselected or when the preferred presentation display of a route changes. So an application can simply watch for these notifications and show or dismiss a presentation on the preferred presentation display automatically.
The preferred presentation display is the display that the media router recommends that the application should use if it wants to show content on the secondary display. Sometimes there may not be a preferred presentation display in which case the application should show its content locally without using a presentation.
Here's how to use the media router to create and show a presentation on the preferred presentation display using android.media.MediaRouter.RouteInfo#getPresentationDisplay()
.
MediaRouter mediaRouter = (MediaRouter) context.getSystemService(Context.MEDIA_ROUTER_SERVICE); MediaRouter.RouteInfo route = mediaRouter.getSelectedRoute(MediaRouter.ROUTE_TYPE_LIVE_VIDEO); if (route != null) { Display presentationDisplay = route.getPresentationDisplay(); if (presentationDisplay != null) { Presentation presentation = new MyPresentation(context, presentationDisplay); presentation.show(); } }
The following sample code from ApiDemos
demonstrates how to use the media router to automatically switch between showing content in the main activity and showing the content in a presentation when a presentation display is available.
Using the display manager to choose a presentation display
Another way to choose a presentation display is to use the DisplayManager
API directly. The display manager service provides functions to enumerate and describe all displays that are attached to the system including displays that may be used for presentations.
The display manager keeps track of all displays in the system. However, not all displays are appropriate for showing presentations. For example, if an activity attempted to show a presentation on the main display it might obscure its own content (it's like opening a dialog on top of your activity). Creating a presentation on the main display will result in android.view.WindowManager.InvalidDisplayException
being thrown when invoking show()
.
Here's how to identify suitable displays for showing presentations using DisplayManager#getDisplays(String)
and the DisplayManager#DISPLAY_CATEGORY_PRESENTATION
category.
DisplayManager displayManager = (DisplayManager) context.getSystemService(Context.DISPLAY_SERVICE); Display[] presentationDisplays = displayManager.getDisplays(DisplayManager.DISPLAY_CATEGORY_PRESENTATION); if (presentationDisplays.length > 0) { // If there is more than one suitable presentation display, then we could consider // giving the user a choice. For this example, we simply choose the first display // which is the one the system recommends as the preferred presentation display. Display display = presentationDisplays[0]; Presentation presentation = new MyPresentation(context, presentationDisplay); presentation.show(); }
The following sample code from ApiDemos
demonstrates how to use the display manager to enumerate displays and show content on multiple presentation displays simultaneously.
Summary
Inherited constants | |
---|---|
Public constructors | |
---|---|
Presentation(outerContext: Context!, display: Display!) Creates a new presentation that is attached to the specified display using the default theme. |
|
Presentation(outerContext: Context!, display: Display!, theme: Int) Creates a new presentation that is attached to the specified display using the optionally specified theme. |
Public methods | |
---|---|
open Display! |
Gets the |
open Resources! |
Gets the |
open Unit |
Called by the system when the properties of the |
open Unit |
Called by the system when the |
open Unit |
show() Inherited from |
Protected methods | |
---|---|
open Unit |
onStart() |
open Unit |
onStop() |
Inherited functions | |
---|---|
Public constructors
Presentation
Presentation(
outerContext: Context!,
display: Display!)
Creates a new presentation that is attached to the specified display using the default theme.
Parameters | |
---|---|
outerContext |
Context!: The context of the application that is showing the presentation. The presentation will create its own context (see getContext() ) based on this context and information about the associated display. |
display |
Display!: The display to which the presentation should be attached. |
Presentation
Presentation(
outerContext: Context!,
display: Display!,
theme: Int)
Creates a new presentation that is attached to the specified display using the optionally specified theme.
Parameters | |
---|---|
outerContext |
Context!: The context of the application that is showing the presentation. The presentation will create its own context (see getContext() ) based on this context and information about the associated display. From android.os.Build.VERSION_CODES#S , the presentation will create its own window context based on this context, information about the associated display. Customizing window type by getWindow#setType(int) causes the mismatch of the window and the created window context, which leads to android.view.WindowManager.InvalidDisplayException when invoking show() . |
display |
Display!: The display to which the presentation should be attached. |
theme |
Int: A style resource describing the theme to use for the window. See Style and Theme Resources for more information about defining and using styles. This theme is applied on top of the current theme in outerContext. If 0, the default presentation theme will be used. |
Public methods
getDisplay
open fun getDisplay(): Display!
Gets the Display
that this presentation appears on.
Return | |
---|---|
Display! |
The display. |
getResources
open fun getResources(): Resources!
Gets the Resources
that should be used to inflate the layout of this presentation. This resources object has been configured according to the metrics of the display that the presentation appears on.
Return | |
---|---|
Resources! |
The presentation resources object. |
onDisplayChanged
open fun onDisplayChanged(): Unit
Called by the system when the properties of the Display
to which the presentation is attached have changed.
See Also
onDisplayRemoved
open fun onDisplayRemoved(): Unit
Called by the system when the Display
to which the presentation is attached has been removed. The system automatically calls cancel
to dismiss the presentation after sending this event.
See Also
show
open fun show(): Unit
Inherited from Dialog#show
. Will throw android.view.WindowManager.InvalidDisplayException
if the specified secondary Display
can't be found or if it does not have Display#FLAG_PRESENTATION
set.