Toggling Button State on a Thumbnail Toolbar

In this task, you learn how to use a single toolbar button for two opposing but related commands, Play and Pause.

Note  The Thumbnail Toolbar is not available with Pinned Sites in Internet Explorer 10 on the new Windows UI.

 

  • Methods Used in this Task
    • msSiteModeAddButtonStyle(nButtonID, bstrIconUrl, bstrTooltip)
    • msSiteModeShowButtonStyle(nButtonID, nStyleID)
  • Differences between button styles and button states
  • Defining alternative icons for toolbar buttons
  • Switching the button state
  • Next Steps
  • Related topics

Methods Used in this Task

The following methods are introduced in this topic:

msSiteModeAddButtonStyle(nButtonID, bstrIconUrl, bstrTooltip)

You use the window.external.msSiteModeAddButtonStyle method to define an alternative icon image and tooltip for a specified button.

msSiteModeShowButtonStyle(nButtonID, nStyleID)

You use the window.external.msSiteModeShowButtonStyle method to change the icon image and tooltip of a Thumbnail toolbar button to a predefined button style.

Differences between button styles and button states

Buttons states affect visibility and availability of buttons. If you want to show or hide a button, or change from active to inactive, you change its state. For more information, see Disabling and Hiding Buttons on a Thumbnail Toolbar.

Button styles, on the other hand, can be used to create the following effects:

  • Toggle between opposing but related commands, like Play and Pause
  • Toggle between two up and down states, Favorite or not Favorite, for example
  • Change button commands based on the state of the application

Defining alternative icons for toolbar buttons

In an earlier task, you created a button called "btnPlayPause" that toggles between two audio states: Play and Pause. In this task you learn how that action appears in the Channel9 Podcast Player sample application, as shown in the following screenshots.

To switch between two states, you need to define one alternative "button style" by calling the msSiteModeAddButtonStyle method. This method returns a style ID that can be used to switch between the two button states. To create a new button style, you need the button ID that is returned by the msSiteModeAddThumbBarButton method.

btnPlayPause = window.external.msSiteModeAddThumbBarButton('Images/play.ico', 'Play');

// Add styles
stylePlay = 0;  // Default style ID.
stylePause = window.external.msSiteModeAddButtonStyle(
             btnPlayPause, 'Images/pause.ico', "Pause");

Note  The original icon and tooltip are assigned to style id zero (0). You do not need to add the default style again.

 

Always create a button in its default state. For example, if the audio starts automatically, the default button state should be Pause. On the other hand, if a user must click the button to begin playback, the initial state should be Play.

Switching the button state

When the toolbar button is clicked, the event handler dispatches the event to the "playPause" function, which is defined as shown in the following code example.

function playPause()
{
    var audio = document.getElementById("audio_" + podcastIndex);

    if (audio.paused) {
        audio.play();
    }
    else {
        audio.pause();
    }

    try {
        if (window.external.msIsSiteMode()) {
            var myStyle = audio.paused ? stylePlay : stylePause;
            window.external.msSiteModeShowButtonStyle(btnPlayPause, myStyle);
        }
    }
    catch (e) {
        // Fail silently.
    }
}

Note  Applying a button style will also reset the button state to active and visible. If you wish the button to remain inactive, you need to change the state after setting the button style. For more information, see Disabling and Hiding Buttons on a Thumbnail Toolbar.

 

The code uses the msSiteModeShowButtonStyle method to change the button style based on the state of the audio object. For example, if audio is paused, the button state is set to Play.

Next Steps

When you change a button style, the button remains active and visible regardless of its state or command; the user can still click it. To disable the button, you change its state to inactive. For more information about changing button states, see Disabling and Hiding Buttons on a Thumbnail Toolbar.

Tasks

Creating a Thumbnail Toolbar for a Pinned Site

Disabling and Hiding Buttons on a Thumbnail Toolbar

Responding to Clicks on the Thumbnail Toolbar

Conceptual

How to Create Thumbnail Toolbars

Introduction to Pinned Sites