XAML Elements of the MediaPlayer Skin

Introduction

The MediaPlayer control can reference pre-built and customized XAML media skins (media player UI). By design, these media skins support UI features such as control buttons, captions, and chapters. The MediaPlayer control applies behaviors to these media-skin elements based on their name, such as PlayButton, CaptionText and ChapterArea. All elements in a media skin are optional except the VideoWindow element. Behavior for the elements is automatically applied at run time by client script of the MediaPlayer control.

XAML Elements

Media skins for the MediaPlayer control contain XAML elements that the control can reference. Elements have specific behaviors associated with them. For example, the BufferingArea element is displayed when media buffering occurs and hidden when buffering has stopped. Each group of elements has behaviors that are applied to all child elements in that group.

Element type	Named elements
Any	FullScreenVideoWindow BufferingArea PlayerControls FullScreenArea PlayButton StartButton PlayPauseButton PlaySymbol PauseSymbol StopButton PauseButton MuteButton MuteOffSymbol MuteOnSymbol FullScreenButton extButton PreviousButton VolumeUpButton VolumeDownButton CaptionToggleButton CaptionOnSymbol CaptionOffSymbol
Image	PlaceholderImage
MediaElement	VideoWindow
TextBlock	TotalTimeText CurrentTimeText CaptionText CaptionArea BufferingText FullScreenCaptionText FullScreenCaptionArea
Canvas	TimeSlider TimeThumb VolumeSlider VolumeThumb ChapterArea ChapterToggleButton ChapterArea_ScrollNext ChapterArea_ScrollPrevious DownloadProgressSlider DownloadProgressText
Storyboard	BufferingArea_Buffering

XAML Element Behavior

At run time, the MediaControl parses the XAML of the media skin to match UI elements to storyboards. Elements and storyboards are matched based on a naming convention. For example, if a PlayPauseButton element is found, the MediaPlayer control tries to find the PlayPauseButton_MouseEnter storyboard. If an operation is performed on the element but there is no corresponding storyboard action, a default behavior might be applied, depending on the available default action for the element.

The following table shows the common actions for storyboard elements.

Storyboard action	Description	Default action
element_MouseEnter	Called when the mouse pointer enters the boundaries of the element.	None
element_MouseLeave	Called when the mouse pointer leaves the boundaries of the element.	None
element_Show	Called when the player must show the element.	Visibility is set to Visible.
element_Hide	Called when the player must hide the element.	Visibility is set to Collapsed.
element_Enable	Called when the player must enable the element.	None
element_Disable	Called when the player must disable the element.	None

When an element is in disabled state, it does not respond to mouse events. For example, if the PlayPauseButton is in a disabled state because no media file is loaded, the MouseEnter and MouseLeave storyboards will not be called when the mouse pointer enters and leaves the boundaries of the element.

Button Element Behavior

In addition to the storyboards for all elements, buttons have additional behavior that you can implement, as described in the following table.

Storyboard action	Description
element_MouseDown	Called when the left mouse button is pressed while the mouse pointer is over the element.
element_MouseUp	Called when the left mouse button has been pressed and is released while the mouse pointer is over the element.

Some buttons have support for symbols that are toggled when the button is clicked. For example, the PlayPauseButton supports PlaySymbol and PauseSymbol, and if these exist, they are shown and hidden as appropriate when the button is clicked. Showing and hiding the symbols is performed according to the Show and Hide storyboards. That is, when the element switches from play to pause, the PlaySymbol_Hide and PauseSymbol_Show storyboards are called if they exist. If they do not exist, the default show and hide behavior is applied.

TextBlock Element Behavior

The MediaPlayer control can set the Text property of the TextBlock element. The Text value of the TextBlock element is automatically centered horizontally and vertically. TextBlock elements in some skins have background attributes associated with them. For example, the CaptionText element supports the CaptionArea element. If a caption area exists in a skin, it is resized to fit the Text value when the text is changed, which provides a background color for the text.

Slider Element Behavior

Slider elements can be vertical or horizontal, which is dictated by the dimensions of the Slider element. Slider elements are horizontal if the width is larger than the height, or vertical if the height is larger than the width. Slider elements require a Thumb element that displays the value of the slider and that provides a UI element that the user can drag to set a new value.

The MediaPlayer control can assign a value to a slider which positions the Thumb element at the desired position relative to the slider's width or height. If an element_Highlight canvas exists in the skin, the MediaPlayer control also sets its width or height so that the highlight canvas encompasses the area between the zero (lowest) position of the slider and the current position of the Thumb element.

ImageList Element Behavior

An ImageList element is canvas that has specialized behavior to make it behave like a dynamic list of images. This is used for the chapter area display when media chapters are defined. The XAML defines an ImageList as a canvas with many items that it contains, such as named element_ScrollItem1, element_ScrollItem2, and so on. Any number of elements can be defined, but there must be at least two. The last ScrollItem serves as an overflow item and should be at first out of view, hidden by another canvas or by clipping the region.

ImageList elements have additional behavior.

Storyboard action	Description
element_ScrollAnimationStoryboard	Called when the ImageList element of the chapter area is scrolled to the left or right.
element_ScrollAnimation	An animation in the storyboard to which the To and From values are assigned.

Because the element can contain more images than it displays, items might be wrapped around at run time. For example, when the user scrolls to the right, such as by clicking the ScrollNext button, the overflow item scrolls into view, and the first item scrolls out of view to the left. The next scroll operation to the right causes the now left-most item to be scrolled into view on the right side, and so on. One item always remains out of view and scrolls into view while another scrolls out of view, maintaining the illusion that there are an unlimited number of scroll items in the XAML.

Each ScrollItem element can contain additional elements, as listed in the following table.

Element	Description
ScrollItemX_Image	An Image element.
ScrollItemX_Title	A TextBlock element.

If the number of items bound to the list is less than the number of scroll items that is defined in the ImageList element, the extra scroll items are hidden, according to the display behavior described previously.

ProgressBar Element Behavior

The MediaPlayer control uses a ProgressBar element to indicate progress as a media file is downloaded. The bar is set to the corresponding percentage of its authored width. If the TextBlock canvas exists, its text is set to the download percentage amount (without the percent sign).

BufferingArea_Buffering Storyboard Behavior

If the MediaPlayer control skin contains a BufferingArea_Buffering storyboard, the storyboard is used to indicate when buffering is occurring. In addition, the BufferingArea canvas is shown when buffering is occurring and hidden when buffering has stopped.

This topic is ASP.NET Extensions documentation and is unsupported by Microsoft. Blank topics are included as placeholders and existing content is subject to change in future releases.