msSiteModeAddThumbBarButton Method

  • Article

New for Windows Internet Explorer 9

Adds a button to the Thumbnail Toolbar.

Syntax

uiButtonID = window.external.msSiteModeAddThumbBarButton(bstrIconURL, bstrTooltip)

Parameters

bstrIconURL Required. Absolute or relative URL of an icon resource file.
bstrTooltip Required. The button name, which is displayed as a tooltip on hover.

Return Value

Integer that receives the ID of the new button.

Possible Exceptions

Permission denied (0x80070005) The current page is not a pinned site.
Invalid procedure call or argument (0x800A0005) The Thumbnail Toolbar is full, or parameters exceed allowable lengths. Also, the Thumbnail Toolbar cannot be updated after it is shown.
Not implemented (0x80004001) This method is not supported on Windows CE.

Remarks

The Thumbnail Toolbar lets you create interactive controls that supplement the behavior of your webpage. When a button is clicked, the webpage receives an onmsthumbnailclick event. The buttonID attribute of the event returns the ID of the button that was clicked. It's up to you to decide if the interaction stays local or if it is communicated back to the website.

A Thumbnail Toolbar can hold up to seven buttons. You cannot add more buttons after calling the msSiteModeShowThumbBar method. After the Thumbnail Toolbar has been created, you can hide or disable individual buttons with msSiteModeUpdateThumbBarButton. You can also change the icon and tooltip of a button with a button style. (See msSiteModeAddButtonStyle.)

The same toolbar and buttons are used for the lifetime of a tab, even if the user navigates between pages. To support this scenario, the following apply:

  • If this method is called with an icon URL and tooltip that were previously added or added as a style, even from a page you navigated away from, the same button ID is returned. This allows you to run the same code on different pages without having to check whether the buttons have already been created previously.
  • If this method is called after the Thumbnail Toolbar is shown, icon URLs and tooltips that match existing buttons are allowed. However, if the icon URL and tooltip do not match an existing button or button style, an "Invalid procedure call or argument" exception is thrown.
  • Unless you are sure that the Thumbnail Toolbar is appropriate for all pages of your site, you should consider disabling or hiding the buttons by calling msSiteModeUpdateThumbBarButton during the page onunload event. You will need to show the buttons again when the next page is loaded.

The icon resource must define at least one 16x16 pixel icon at 96 dots per inch (dpi).

Examples

The following example adds two buttons to the Thumbnail Toolbar and responds when they are clicked.

var btn1, btn2;

function init()
{
    document.addEventListener('msthumbnailclick', processSelection, false);
    
    btn1 = window.external.msSiteModeAddThumbBarButton('Images/play.ico', 'Play');
    btn2 = window.external.msSiteModeAddThumbBarButton('Images/stop.ico', 'Stop');
    
    window.external.msSiteModeShowThumbBar();
}

function processSelection(btn)
{
   if (btn.buttonID == btn1) 
   {
       // Play video
   }
   else if (btn.buttonID == btn2) 
   {
       // Stop video
   }
}

The following example uses the msSiteModeUpdateThumbBarButton method to hide the toolbar when the page is unloaded.

function hideButtons() {
    window.external.msSiteModeUpdateThumbBarButton(btnPrev, true, false);
    window.external.msSiteModeUpdateThumbBarButton(btnPlayPause, true, false);
    window.external.msSiteModeUpdateThumbBarButton(btnNext, true, false);
}

<body onunload="hideButtons()"> ... </body>

Applies To

external

See Also

msSiteModeShowThumbBar, msSiteModeUpdateThumbBarButton