Displaying Thumbnail Toolbar Buttons on the Thumbnail PreviewFor native Windows applications, users interact with thumbnail toolbar buttons in the taskbar without having to restore or activate the site's window. A pinned site can make use of the same functionality for individual webpages. Each button represents a command that can be executed in the webpage, so users can interact with the webpage while in a minimized state or without activating it. The following screen shot shows how a webpage with multiple video clips uses thumbnail toolbar buttons to control the play, pause, and selection of videos without causing the user to access the page directly.
Figure 10: Thumbnail toolbar buttons to control videoYou can display a maximum of seven buttons in a thumbnail toolbar. Because there is a limited amount of space in which to display thumbnails, as well as a constantly changing number of thumbnails to display, applications are not guaranteed a specific toolbar size. If display space is low, buttons in the toolbar are truncated from right to left as needed. Therefore, an application should prioritize the commands associated with its buttons to ensure that those of highest priority are to the left and are therefore least likely to be truncated.
When a user clicks a thumbnail toolbar button, an event with a specific ID is returned to the webpage for processing. These events are scoped to the domain that created the events. Buttons can be created, displayed, hidden, enabled, or disabled, or their image can be replaced.
Thumbnail toolbar buttons are defined in memory before they are displayed. The following code example uses the
msSiteModeAddThumbBarButton method to create three thumbnail toolbar buttons, passing in the URL of an icon resource file in the first parameter and the (optional) tooltip in the second parameter. The method returns an ID that is used by the system when a thumbnail toolbar button click event is generated.
btn1 = window.external.msSiteModeAddThumbBarButton( 'http://host/images/button1.ico', 'button 1') ;
btn2 = window.external.msSiteModeAddThumbBarButton( 'http://host/images/button2.ico', 'button 2') ;
btn1 = window.external.msSiteModeAddThumbBarButton( 'http://host/images/button3.ico', 'button 3') ;
You capture events generated when the user clicks a thumbnail toolbar button by subscribing to the
msthumbnailclick event with an event handler. The following code example registers an event handler,
handler1, to process all events generated by the thumbnail toolbar buttons.
document.addEventListener('msthumbnailclick', handler1, false) ;
...
function handler1 (btn) {
alert ("addeventlist:thumbnail btn id" + btn.buttonID);
}After being defined, you can instantiate a button only once, by using the
msSiteModeShowThumbBar method.
window.external.msSiteModeShowThumbBar() ;
Use the
msSiteModeUpdateThumbBarButton method to set the state and visibility of a button after the button has been instantiated. The following code example makes button1 disabled and visible, button2 enabled and visible, and button3 enabled but not visible.
window.external.msSiteModeUpdateThumbBarButton(btn1, false, true) ;
window.external.msSiteModeUpdateThumbBarButton(btn2, true, true) ;
window.external.msSiteModeUpdateThumbBarButton(btn3, true, false) ;
Changes to the button state take place immediately; however, changes to the button visibility take place only after the thumbnail preview window is refreshed.
You can define and implement alternate styles to dynamically replace button information already displayed in the thumbnail toolbar. First, define a new style. Use the
msSiteModeAddButtonStyle method to define an alternate icon image and tooltip for the specified button. Each style contains a replacement image and a new tooltip value. The following code example defines
style1 for
btn1 using a new image and tooltip.
style1 = window.external.msSiteModeAddButtonStyle(btn1, 'http://host/images/style1.ico', 'style1') ;
Then, apply defined styles to the already displayed buttons by using the msSiteModeAddButtonStyle method. The following code example applies the previously defined
style1 to
btn1.
window.external.msSiteModeShowButtonStyle(btn1, style1) ;
Your site should hide thumbnail toolbar buttons when a user exits the website’s domain or navigates away to other pages. Similarly, sites should re-instantiate these buttons and make them visible when a user returns to the page.
When re-instantiating these buttons a site should not call the
msSiteModeShowThumbBar method on the same instance as an exception will be triggered. At a minimum the method should be called with a try/catch block around it to ensure the buttons continue to work once they are reinitialized and made visible again. To support this scenario, you can call the
msSiteModeAddThumbBarButton method multiple times to reinitialize your variable with the necessary ids that will be used inside the event handler to deal with the event. Therefore, the
msSiteModeAddThumbBarButton method is guaranteed to return the same button id every time. This allows you to reuse your event handling logic independent of any navigation outside of the page.
source:msdn.microsoft.com
