msSiteModeAddThumbBarButton method

  • Article

Adds a button to the Thumbnail Toolbar.

This method is not supported for Windows apps using JavaScript.

 

Syntax

HRESULT retVal = 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 VT_I4 that receives the ID of the new button.

Return value

Type: HRESULT

This method can return one of these values.

Return code Description
S_OK

The operation completed successfully.
E_ACCESSDENIED

The current page is not a pinned site.
E_INVALIDARG

The Thumbnail Toolbar is full, or parameters exceed allowable lengths. Also, the Thumbnail Toolbar cannot be updated after it is shown.
E_NOTIMPL

This method is not supported on Windows CE.

 

Standards information

There are no standards that apply here.

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, E_FAIL is returned.
  • 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).

See also

Reference

IShellUIHelper4::msSiteModeShowThumbBar

IShellUIHelper4::msSiteModeUpdateThumbBarButton