MediaRouteButtonFactory

@UnstableApi
public final class MediaRouteButtonFactory

A factory class to set up a media route button.

Summary

Public methods
static ListenableFuture<Void>

Sets up a media route button with an asynchronous callback, which will not block the caller thread.
static ListenableFuture<MenuItem>
setUpMediaRouteButton(Context context, Menu menu, int menuResourceId)

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

Public methods

setUpMediaRouteButton

public static ListenableFuture<Void> setUpMediaRouteButton(Context context, MediaRouteButton button)

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.
MediaRouteButton button

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.

setUpMediaRouteButton

public static ListenableFuture<MenuItem> setUpMediaRouteButton(Context context, Menu menu, int menuResourceId)

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.
int menuResourceId

The resource ID of the menu item for the media route button.
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.