Added in API level 17

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 Display that this presentation appears on.

open Resources!

Gets the Resources that should be used to inflate the layout of this presentation.

open Unit

Called by the system when the properties of the Display to which the presentation is attached have changed.

open Unit

Called by the system when the Display to which the presentation is attached has been removed.

open Unit

Inherited from Dialog#show.

Protected methods
open Unit

open Unit

Inherited functions

Public constructors

Presentation

Added in API level 17
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

Added in API level 17
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

Added in API level 17
open fun getDisplay(): Display!

Gets the Display that this presentation appears on.

Return
Display! The display.

getResources

Added in API level 17
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

Added in API level 17
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

Added in API level 17
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

Added in API level 17
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.

Protected methods

onStart

Added in API level 17
protected open fun onStart(): Unit

onStop

Added in API level 17
protected open fun onStop(): Unit