External.cancelNavigate method

Article
06/20/2023

[The feature associated with this page, Windows Media Player SDK, is a legacy feature. It has been superseded by MediaPlayer. MediaPlayer has been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use MediaPlayer instead of Windows Media Player SDK, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]

Note

This topic describes functionality designed for use by online stores. Use of this functionality outside the context of an online store is not supported.

The cancelNavigate method informs Windows Media Player that it should not display a new discovery page even though the view has changed in the Player.

Syntax

External.cancelNavigate()

Parameters

This method has no parameters.

Return value

This method does not return a value.

Remarks

When the view changes in Windows Media Player, the Player calls the online store's plug-in to determine which discovery page to display next. In some cases, however, the online store might want the Player to continue displaying the existing discovery page. The following process determines whether the Player displays a new discovery page:

An action by the user, either in the Player's user interface or on the discovery page, requests that the Player change its view.
The Player calls the plug-in's GetTemplate method to determine which discovery page to display next. The Player stores the URL of the new discovery page but does not display the new discovery page at this time.
The Player raises the OnViewChange event.
If the OnViewChange event handler on the discovery page calls cancelNavigate, the Player does not display the new discovery page (determined in step 2). Instead, it continues to display the existing discovery page. If the OnViewChange event handler does not call cancelNavigate, the Player does display the new discovery page.

For example, suppose the Player is currently displaying the view of an album with a certain track selected. Also assume that the current discovery page is the page that represents the entire album. If the user clicks a different track from the same album, the Player's view changes slightly to show that the new track is selected. But there is no need to display a new discovery page. The discovery page that represents the entire album is still the appropriate page for the Player to display.

Requirements

Requirement	Value
Version	Windows Media Player 11.
DLL	Wmp.dll