# MediaRouteButtonFactory

Artifact: [androidx.media3:media3-cast](https://developer.android.com/jetpack/androidx/releases/media3) [View Source](https://cs.android.com/search?q=file:androidx/media3/cast/MediaRouteButtonFactory.java+class:androidx.media3.cast.MediaRouteButtonFactory)

*** ** * ** ***


```
@MainThread
@UnstableApi
class MediaRouteButtonFactory
```

<br />

*** ** * ** ***

A factory class to set up a media route button.

Must be called on the main thread.

## Summary

| ### Public functions |
|---|---|
| `java-static https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<https://developer.android.com/reference/java/lang/Void.html!>!` | `@https://checkerframework.org/api/com/google/errorprone/annotations/CanIgnoreReturnValue.html https://developer.android.com/reference/kotlin/androidx/media3/cast/MediaRouteButtonFactory#setUpMediaRouteButton(android.content.Context,androidx.mediarouter.app.MediaRouteButton)(context: https://developer.android.com/reference/android/content/Context.html!, button: https://developer.android.com/reference/kotlin/androidx/mediarouter/app/MediaRouteButton!)` Sets up a media route button with an asynchronous callback, which will not block the caller thread. |
| `java-static https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<https://developer.android.com/reference/android/view/MenuItem.html!>!` | `@https://checkerframework.org/api/com/google/errorprone/annotations/CanIgnoreReturnValue.html https://developer.android.com/reference/kotlin/androidx/media3/cast/MediaRouteButtonFactory#setUpMediaRouteButton(android.content.Context,android.view.Menu,int)(context: https://developer.android.com/reference/android/content/Context.html!, menu: https://developer.android.com/reference/android/view/Menu.html!, menuResourceId: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)` 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

```
@CanIgnoreReturnValue
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 `https://developer.android.com/reference/kotlin/androidx/mediarouter/app/MediaRouteButton` to their activity layout .xml file. Then the application can set up the media route button as follows.

```kotlin
public class MyActivity extends AppCompatActivity {
    ...
    &#64;Override
    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>() {
              &#64;Override
              public void onSuccess(Void unused) {
                // Indicate that the media route button is set up successfully.
              }

              &#64;Override
              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.

The method must be called on the main thread. The returned `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` 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 `https://developer.android.com/reference/kotlin/androidx/mediarouter/app/MediaRouteButton` for more details.

| Parameters |
|---|---|
| `context: https://developer.android.com/reference/android/content/Context.html!` | The `https://developer.android.com/reference/android/content/Context.html` for creating the media route button. |
| `button: https://developer.android.com/reference/kotlin/androidx/mediarouter/app/MediaRouteButton!` | The `https://developer.android.com/reference/kotlin/androidx/mediarouter/app/MediaRouteButton` to set up. |

| Returns |
|---|---|
| `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<https://developer.android.com/reference/java/lang/Void.html!>!` | A `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` that will resolve to null when the media route button is successfully set up. The future may fail with `https://developer.android.com/reference/java/lang/IllegalStateException.html` if this method is failed to set a `https://developer.android.com/reference/kotlin/androidx/mediarouter/media/MediaRouteSelector` to the media route button. The completer of the returned `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` may be called on a different thread than the caller's thread. |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | If the media route button is null. |
| `https://developer.android.com/reference/java/lang/IllegalStateException.html` | If any of the following conditions occur: - This method is not called on the main thread. - The `https://developer.android.com/reference/kotlin/androidx/media3/cast/Cast` has not been initialized via `https://developer.android.com/reference/kotlin/androidx/media3/cast/Cast#initialize()` before this method is called. |

### setUpMediaRouteButton

```
@CanIgnoreReturnValue
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 `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` with the menu item of the media route button

The application should define a menu resource to include the `https://developer.android.com/reference/kotlin/androidx/mediarouter/app/MediaRouteActionProvider` as the action provider of the menu item.

```kotlin
<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.

```kotlin
public class MyActivity extends AppCompatActivity {
    ...
    &#64;Override
    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>() {
              &#64;Override
              public void onSuccess(MenuItem menuItem) {
                // Do something with the menu item.
              }

              &#64;Override
              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 method must be called on the main thread. The callback of the returned `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` 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 `https://developer.android.com/reference/kotlin/androidx/mediarouter/app/MediaRouteActionProvider` for more details.

| Parameters |
|---|---|
| `context: https://developer.android.com/reference/android/content/Context.html!` | The `https://developer.android.com/reference/android/content/Context.html` for creating the media route button. |
| `menu: https://developer.android.com/reference/android/view/Menu.html!` | The `https://developer.android.com/reference/android/view/Menu.html` to which the menu item with the button will be added. |
| `menuResourceId: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | The resource ID of the menu item for the media route button. |

| Returns |
|---|---|
| `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<https://developer.android.com/reference/android/view/MenuItem.html!>!` | A `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` that resolves to the created `https://developer.android.com/reference/android/view/MenuItem.html` when the media route button is set up successfully. The future may fail with `https://developer.android.com/reference/java/lang/IllegalStateException.html` if this method is failed to set a `https://developer.android.com/reference/kotlin/androidx/mediarouter/media/MediaRouteSelector` to the menu item. The completer of the returned `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` may be called on a different thread than the caller's thread. |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | if the menu doesn't contain a menu item with the given ` menuResourceId` identifier or the menu item doesn't have a `https://developer.android.com/reference/kotlin/androidx/mediarouter/app/MediaRouteActionProvider` as its action provider. |
| `https://developer.android.com/reference/java/lang/IllegalStateException.html` | If any of the following condition occurs: - This method is not called on the main thread. - The `https://developer.android.com/reference/kotlin/androidx/media3/cast/Cast` has not been initialized via `https://developer.android.com/reference/kotlin/androidx/media3/cast/Cast#initialize()` before this method is called. |