MediaRouteButtonFactory

Kotlin |Java

@UnstableApi
class MediaRouteButtonFactory

A factory class to set up a media route button.

Summary

Public functions
`java-static ListenableFuture<Void!>!`	`setUpMediaRouteButton(context: Context!, button: MediaRouteButton!)` Sets up a media route button with an asynchronous callback, which will not block the caller thread.
`java-static ListenableFuture<MenuItem!>!`	`setUpMediaRouteButton(context: Context!, menu: Menu!, menuResourceId: Int)` Sets up a media route button in the action bar menu with an asynchronous callback, which will not block the caller thread.

Public functions

setUpMediaRouteButton

java-static fun setUpMediaRouteButton(context: Context!, button: MediaRouteButton!): ListenableFuture<Void!>!

Sets up a media route button with an asynchronous callback, which will not block the caller thread.

The application can add a MediaRouteButton to their activity layout .xml file. Then the application can set up the media route button as follows.

public class MyActivity extends AppCompatActivity {
    ...
    
    public void onCreate(Bundle savedInstanceState) {
        ...
        MediaRouteButton button = findViewById(R.id.media_route_button);
        ListenableFuture<Void> setUpFuture =
            MediaRouteButtonFactory.setUpMediaRouteButton(this, button);
        Futures.addCallback(
            setUpFuture,
            new FutureCallback<Void>() {
              
              public void onSuccess(Void unused) {
                // Indicate that the media route button is set up successfully.
              }

              
              public void onFailure(Throwable t) {
                // Handle the failure.
              }
            },
            executor);
        ...
    }
}

If setting up the media route button succeeds, the future will resolve to null and indicate that the media route button is set up successfully.

If setting up the media route button fails, the future may fail with an exception. Consumers should handle the failure gracefully, for example by not showing the media route button.

Clicking on the media route button opens a dialog that allows the user to select a remote device for transferring media.

See MediaRouteButton for more details.

Parameters
`context: Context!`	The `Context` for creating the media route button.
`button: MediaRouteButton!`	The `MediaRouteButton` to set up.

Returns
`ListenableFuture<Void!>!`	A `ListenableFuture` that will resolve to null when the media route button is successfully set up. The future may fail with `IllegalStateException` if this method is not called on the main thread.

java-static fun setUpMediaRouteButton(context: Context!, menu: Menu!, menuResourceId: Int): ListenableFuture<MenuItem!>!

Sets up a media route button in the action bar menu with an asynchronous callback, which will not block the caller thread. Returns a ListenableFuture with the menu item of the media route button

The application should define a menu resource to include the androidx.mediarouter.app.MediaRouteActionProvider as the action provider of the menu item.

<menu xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:app="http://schemas.android.com/apk/res-auto">
    <item android:id="@+id/media_route_menu_item"
        android:title="@string/media_route_menu_title"
        app:showAsAction="always"
        app:actionProviderClass="androidx.mediarouter.app.MediaRouteActionProvider"/>
</menu>

Then the application can inflate the /res/menu/sample_media_route_button_menu.xml and set up the media route button in the action bar menu as follows.

public class MyActivity extends AppCompatActivity {
    ...
    
    public boolean onCreateOptionsMenu(Menu menu) {
        ...
        getMenuInflater().inflate(R.menu.sample_media_route_button_menu, menu);
        ListenableFuture<MenuItem> menuItemFuture =
            MediaRouteButtonFactory.setUpMediaRouteButton(this, menu, R.id.media_route_menu_item);
        Futures.addCallback(
            menuItemFuture,
            new FutureCallback<MenuItem>() {
              
              public void onSuccess(MenuItem menuItem) {
                // Do something with the menu item.
              }

              
              public void onFailure(Throwable t) {
                // Handle the failure.
              }
            },
            executor);
        ...
    }
}

If setting up the media route button succeeds, the future will resolve to the menu item of the media route button. The application can do further operations with the menu item, such as showing an introductory overlay to highlight the media route button to users.

If setting up the media route button fails, the future may fail with an exception. Consumers should handle the failure gracefully, for example by not showing the media route button.

The callback of the returned ListenableFuture may be called on a different thread than the caller's thread. If the caller wants to update the UI in the callbacks, it is responsible for forwarding the callback to the UI thread.

Clicking on the media route button opens a dialog that allows the user to select a remote device for transferring media.

See androidx.mediarouter.app.MediaRouteActionProvider for more details.

Parameters
`context: Context!`	The `Context` for creating the media route button.
`menu: Menu!`	The `Menu` to which the menu item with the button will be added.
`menuResourceId: Int`	The resource ID of the menu item for the media route button.

Returns

Returns
`ListenableFuture<MenuItem!>!`	A `ListenableFuture` that resolves to the created `MenuItem` when the media route button is set up successfully. The future may fail with {link IllegalArgumentException} if the menu doesn't contain a menu item with the given `menuResourceId` identifier or the menu item doesn't have a `androidx.mediarouter.app.MediaRouteActionProvider` as its action provider, and may fail with `IllegalStateException` if this method is not called on the main thread.

ListenableFuture<MenuItem!>!

A ListenableFuture that resolves to the created MenuItem when the media route button is set up successfully. The future may fail with {link IllegalArgumentException} if the menu doesn't contain a menu item with the given menuResourceId identifier or the menu item doesn't have a androidx.mediarouter.app.MediaRouteActionProvider as its action provider, and may fail with IllegalStateException if this method is not called on the main thread.