msSiteModeAddThumbBarButton method

Article
08/15/2017

Adds a button to the Thumbnail Toolbar.

Syntax

*object.*msSiteModeAddThumbBarButton(bstrIconURL, bstrTooltip, pvarButtonID)

Parameters

bstrIconURL [in]
Type: BSTR

Absolute or relative URL of an icon resource file.
bstrTooltip [in]
Type: BSTR

The button name, which is displayed as a tooltip on hover.
pvarButtonID [out, retval]
Type: VARIANT

Variant of type Integer that receives the ID of the new button.

Return value

Type: Variant

Variant of type Integer that receives the ID of the new button.

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 HTMLDocumentEvents4::onmsthumbnailclick event. The IDOMSiteModeEvent::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 IShellUIHelper4::msSiteModeShowThumbBar method. After the Thumbnail Toolbar has been created, you can hide or disable individual buttons with IShellUIHelper4::msSiteModeUpdateThumbBarButton. You can also change the icon and tooltip of a button with a button style. (See IShellUIHelper4::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 IShellUIHelper4::msSiteModeUpdateThumbBarButton during the page HTMLWindowEvents::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 IShellUIHelper4::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>