Edit

Create custom transport controls

MediaPlayerElement has customizable XAML transport controls to manage control of audio and video content within a Windows app. Here, we demonstrate how to customize the MediaTransportControls template. We'll show you how to work with the overflow menu, add a custom button and modify the slider.

Important APIs: MediaPlayerElement, MediaPlayerElement.AreTransportControlsEnabled, MediaTransportControls

Before starting, you should be familiar with the MediaPlayerElement and the MediaTransportControls classes. For more info, see the MediaPlayerElement control guide.

Tip

The examples in this topic are based on the Media Transport Controls sample. You can download the sample to view and run the completed code.

When should you customize the template?

MediaPlayerElement has built-in transport controls that are designed to work well without modification in most video and audio playback apps. They're provided by the MediaTransportControls class and include buttons to play, stop, and navigate media, adjust volume, toggle full screen, cast to a second device, enable captions, switch audio tracks, and adjust the playback rate. MediaTransportControls has properties that let you control whether each button is shown and enabled. You can also set the IsCompact property to specify whether the controls are shown in one row or two.

However, there may be scenarios where you need to further customize the look of the control or change its behavior. Here are some examples:

  • Change the icons, slider behavior, and colors.
  • Move less commonly used command buttons into an overflow menu.
  • Change the order in which commands drop out when the control is resized.
  • Provide a command button that's not in the default set.

Note

The buttons visible on screen will drop out of the built-in transport controls in a predefined order if there is not enough room on screen. To change this ordering or put commands that don't fit into an overflow menu, you will need to customize the controls.

You can customize the appearance of the control by modifying the default template. To modify the control's behavior or add new commands, you can create a custom control that's derived from MediaTransportControls.

Tip

Customizable control templates are a powerful feature of the XAML platform, but there are also consequences that you should take into consideration. When you customize a template, it becomes a static part of your app and therefore will not receive any platform updates that are made to the template by Microsoft. If template updates are made by Microsoft, you should take the new template and re-modify it in order to get the benefits of the updated template.

Template structure

The ControlTemplate is part of the default style. You can copy this default style into your project to modify it. The ControlTemplate is divided into sections similar to other XAML control templates.

  • The first section of the template contains the Style definitions for the various components of the MediaTransportControls.
  • The second section defines the various visual states that are used by the MediaTransportControls.
  • The third section contains the Grid that holds that various MediaTransportControls elements together and defines how the components are laid out.

Note

For more info about modifying templates, see Control templates. You can use a text editor or similar editors in your IDE to open the XAML files in (Program Files)\Windows Kits\10\DesignTime\CommonConfiguration\Neutral\UAP\(SDK version)\Generic. The default style and template for each control is defined in the generic.xaml file. You can find the MediaTransportControls template in generic.xaml by searching for "MediaTransportControls".

In the following sections, you learn how to customize several of the main elements of the transport controls:

  • Slider: allows a user to scrub through their media and also displays progress
  • CommandBar: contains all of the buttons. For more info, see the Anatomy section of the MediaTransportControls reference topic.

Customize the transport controls

If you want to modify only the appearance of the MediaTransportControls, you can create a copy of the default control style and template, and modify that. However, if you also want to add to or modify the functionality of the control, you need to create a new class that derives from MediaTransportControls.

Re-template the control

To customize the MediaTransportControls default style and template

  1. Copy the default style from MediaTransportControls styles and templates into a ResourceDictionary in your project.
  2. Give the Style an x:Key value to identify it, like this.
  1. Add a MediaPlayerElement with MediaTransportControls to your UI.
  2. Set the Style property of the MediaTransportControls element to your custom Style resource, as shown here.

For more info about modifying styles and templates, see Styling controls and Control templates.

Create a derived control

To add to or modify the functionality of the transport controls, you must create a new class that's derived from MediaTransportControls. A derived class called CustomMediaTransportControls is shown in the Media Transport Controls sample and the remaining examples on this page.

To create a new class derived from MediaTransportControls

  1. Add a new class file to your project.
    • In Visual Studio, select Project > Add Class. The Add New Item dialog opens.
    • In the Add New Item dialog, enter a name for the class file, then click Add. (In the Media Transport Controls sample, the class is named CustomMediaTransportControls.)
  2. Modify the class code to derive from the MediaTransportControls class.
public sealed class CustomMediaTransportControls : MediaTransportControls
{
}
  1. Copy the default style for MediaTransportControls into a ResourceDictionary in your project. This is the style and template you modify. (In the Media Transport Controls sample, a new folder called "Themes" is created, and a ResourceDictionary file called generic.xaml is added to it.)
  2. Change the TargetType of the style to the new custom control type. (In the sample, the TargetType is changed to local:CustomMediaTransportControls.)
xmlns:local="using:CustomMediaTransportControls">
...