Adds a button to the Thumbnail Toolbar.
HRESULT msSiteModeAddThumbBarButton( BSTR bstrIconURL, BSTR bstrTooltip, VARIANT *pvarButtonID );
- [in] Absolute or relative URL of an icon resource file.
- [in] The button name, which is displayed as a tooltip on hover.
- [out, retval] VARIANT of type VT_I4 that receives the ID of the new button.
Returns one of the following values.
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.
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 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, 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 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).