About the Toolbar WebControls Client Behavior

Article
10/23/2013

The Toolbar behavior, one of the Windows Internet Explorer WebControls Client Behaviors, creates a UI container for buttons, drop-down list boxes, and text boxes. You can author the toolbars declaratively through markup or dynamically through script. This element behavior also generates the rich client experience in uplevel browsers (in this case, Microsoft Internet Explorer 5.5 or later) as part of the WebControls Server Controls.

This document includes the following sections.

Introduction
Prerequisites
Toolbar Elements
Writing a Simple Toolbar
Formatting the Toolbar
Using Toolbar Elements with Script
- Creating a Toolbar Dynamically
- Scripting the TOOLBARBUTTON Element
- Scripting the TOOLBARCHECKBUTTON Element
- Scripting the TOOLBARCHECKGROUP Element
- Scripting the TOOLBARDROPDOWNLIST Element
Related Topics

Introduction

With the Toolbar behavior, you can create a functioning toolbar that contains scriptable buttons, drop-down list boxes, and text boxes. You can add a move handle to enable users to drag the toolbar around the screen and even dock it to the screen edges. Toolbars can be oriented horizontally or vertically.

Toolbar is an element behavior. It is a viewlink. This behavior is not lightweight. Its contents are treated as literal content.

Prerequisites

You must download and install the WebControls Client Behaviors at Internet Explorer WebControls Download. The WebControls Client Behaviors require Internet Explorer 5.5 or later.

To make the best use of this article, you should be familiar with the basics of Dynamic HTML (DHTML) and element behaviors. Code samples are written in Microsoft JScript.

You can use this behavior on a Web page by inserting the TOOLBAR custom element into your HTML markup. Properties and methods are accessible through the ID of the custom element.

The TOOLBAR element can contain several types of child elements:

TOOLBARGRIPPER provides a move handle to a toolbar.
TOOLBARBUTTON places a button on a toolbar.
TOOLBARCHECKBUTTON places a button on a toolbar that can show selection.
TOOLBARCHECKGROUP groups TOOLBARCHECKBUTTON elements so that only one button in the group can show selection at one time. TOOLBARCHECKGROUP elements can contain TOOLBARCHECKBUTTON elements.
TOOLBARDROPDOWNLIST provides a drop-down list of options. TOOLBARDROPDOWNLIST elements can contain OPTION elements.
TOOLBARLABEL places text on a toolbar to label other elements, especially TOOLBARDROPDOWNLIST and TOOLBARTEXTBOX.
TOOLBARTEXTBOX places a text input box on a toolbar.
TOOLBARSEPARATOR creates a division bar between other toolbar elements.

This section shows you how to use markup to insert a Toolbar component into an HTML page. The sample shows a simple example of each child element.

As with any element behavior, start by declaring a namespace and then importing the behavior into the namespace.


<HTML XMLNS:tb>
   <HEAD>
      <?IMPORT NAMESPACE="tb" IMPLEMENTATION="toolbar.htc"/>
   </HEAD>

Add the custom element into the page markup where you want the toolbar to appear.


<tb:TOOLBAR></tb:TOOLBAR>

When adding the TOOLBARGRIPPER element, you can also place the MOVEMENT attribute on the TOOLBAR element. In the example, the value move-dock enables the user to drag the toolbar around the screen. When it comes to a screen edge, the toolbar docks to it.

Notice in the rendered example the difference in behavior between the three button types: the TOOLBARBUTTON element, TOOLBARCHECKBUTTON element, and TOOLBARCHECKBUTTON elements wrapped in a TOOLBARCHECKGROUP element.

Also, notice that the VALUE attribute on the TOOLBARTEXTBOX element renders default text.

The example uses the TOOLBARSEPARATOR tag to demarcate areas or groupings on the toolbar.


      <tb:TOOLBAR MOVEMENT="move-dock" >
         <tb:TOOLBARGRIPPER/>
         <tb:TOOLBARBUTTON IMAGEURL="images/tool-mail.gif" TEXT=" Regular button "/>
         <tb:TOOLBARSEPARATOR/>
         <tb:TOOLBARCHECKBUTTON TEXT="Check button"/>
         <tb:TOOLBARSEPARATOR/>
         <tb:TOOLBARCHECKGROUP>
            <tb:TOOLBARCHECKBUTTON TEXT="Button 1"/>
            <tb:TOOLBARCHECKBUTTON TEXT="Button 2"/>
            <tb:TOOLBARCHECKBUTTON TEXT="Button 3"/>
         </tb:TOOLBARCHECKGROUP>
         <tb:TOOLBARSEPARATOR/>
         <tb:TOOLBARDROPDOWNLIST>
            <OPTION VALUE="1">Option 1</OPTION>
            <OPTION VALUE="2">Option 2</OPTION>
            <OPTION VALUE="3">Option 3</OPTION>
            <OPTION VALUE="4">Option 4</OPTION>
         </tb:TOOLBARDROPDOWNLIST>
         <tb:TOOLBARSEPARATOR/>
         <tb:TOOLBARLABEL TEXT="Label for text box:"/>
         <tb:TOOLBARTEXTBOX VALUE="Default text"/>
      </tb:TOOLBAR>

Click this button to see the full example.

Code example: https://samples.msdn.microsoft.com/workshop/samples/webcontrols/toolbar/tbSimpleExample.htm

The state of a toolbar button determines its rendered formatting. Buttons (TOOLBARBUTTON and TOOLBARCHECKBUTTON) have three states.

Default—The button is neither hovered over nor selected.
Hovered—The mouse pointer is over the button and it is not selected.
Selected—The button is selected.

You can define styles for each state. Changing the look of a button to reflect its state is a good UI practice. The style for each state supersedes the one before it. For example, if the mouse pointer is over an unselected button, the HOVERSTYLE applies to the button rather than the DEFAULTSTYLE. Or, if the mouse pointer is over a selected button, the style remains the SELECTEDSTYLE.

Default, hover, and selected styles defined on a TOOLBARCHECKGROUP element are inherited by its child TOOLBARCHECKBUTTON elements.

The other Toolbar elements (TOOLBARGRIPPER, TOOLBARSEPARATOR, TOOLBARTEXTBOX, and TOOLBARDROPDOWNLIST) use only the DEFAULTSTYLE attribute.

There are a variety of ways to use script with the Toolbar behavior. On the most fundamental level, you can have script run when a toolbar button is clicked. On another level, because the child elements of the TOOLBAR element are treated as literal content, you must use script to return them as objects to manipulate. Also, you can create the TOOLBAR and its child elements completely in script.

When scripting, you can get and set attributes on the custom element with dot notation in an assignment statement or with the getAttribute and setAttribute methods. For the child elements, however, you must use the getAttribute and setAttribute methods.

You can import a Toolbar behavior and create the custom element completely through script. First, add a namespace to the document's namespaces collection. Next, import the behavior and assign it to the namespace.


<SCRIPT>
   var tbNS = document.namespaces.add("tb","toolbar.htc");
   tbNS.doImport("toolbar.htc");
   .
   .
   .

Next, create the custom element.


   .
   .
   .
   var oToolbar = document.createElement("tb:TOOLBAR");
   .
   .
   .

You cannot begin using methods and properties of the behavior until the behavior has completely loaded. Attach a function pointer to the Toolbar object to handle the onreadystatechange event. In this example, the function configureBar adds child elements to the Toolbar and sets their properties. When this event returns a value of complete to the readyState property, you can proceed. Finally, append the Toolbar to a page element.


   .
   .
   .
   oToolbar.id = "oTB";
   oToolbar.onreadystatechange = configureBar;
   oDiv.appendChild(oToolbar);
</SCRIPT>

Click this button to see the full example.

Code example: https://samples.msdn.microsoft.com/workshop/samples/webcontrols/toolbar/tbDynaBar.htm

Scripting the TOOLBARBUTTON Element

You can run script when a TOOLBARBUTTON element is clicked by setting a handler for the onclick event on the element. In the following example, the onclick handler on the TOOLBARBUTTON changes the background color of the DIV element.


<SCRIPT>
   function setBackground()
   {
      oDiv.style.backgroundColor = "lightgrey";
   }
</SCRIPT>

<P>
   <tb:TOOLBAR ID="oTB">
      <tb:TOOLBARGRIPPER/>
      <tb:TOOLBARBUTTON onclick="setBackground()" TEXT="Gray"/>
   </tb:TOOLBAR>
</P>
<DIV ID="oDiv">Every dog has its day. </DIV>

Code example: https://samples.msdn.microsoft.com/workshop/samples/webcontrols/toolbar/tbButtonExample.htm

When a button is clicked, the onbuttonclick event fires. You can identify the clicked button by handling the onbuttonclick event on the TOOLBAR. The srcNode event property returns the button object and the flatIndex event property returns the button's index number. The following example shows how to retrieve both of these properties for the clicked button.


<SCRIPT>
   function identifyClickedButton()
   {
      var oButton = window.event.srcNode;
      var sButtonName = oButton.getAttribute("text");
      oDiv.innerText = "The name of the clicked button is " + sButtonName + ". ";
      var indexNum = window.event.flatIndex;
      oDiv.innerText += "Its index number in the TOOLBAR is " + indexNum + ". ";
      oDiv.style.backgroundColor = sButtonName.toLowerCase();
   }
</SCRIPT>

<P>
<tb:TOOLBAR ID="oTB" onbuttonclick="identifyClickedButton()">
   <tb:TOOLBARGRIPPER/>
   <tb:TOOLBARBUTTON TEXT="Yellow"/>
</tb:TOOLBAR>
</P>
<DIV ID="oDiv"></DIV>

Code example: https://samples.msdn.microsoft.com/workshop/samples/webcontrols/toolbar/tbButtonExample2.htm

You can create a TOOLBARBUTTON dynamically with the createButtonAt method.


<SCRIPT>
   function addButton()
   {
      var oButton = oTB.createButtonAt(oTB.numItems);
      oButton.setAttribute("text","Yellow");
   }

   function changeBGColor()
   {
      var oButton = window.event.srcNode;
      var sButtonName = oButton.getAttribute("text");
      oDiv.style.backgroundColor = sButtonName.toLowerCase();
   }
</SCRIPT>

<tb:TOOLBAR ID="oTB" onbuttonclick="changeBGColor()">
   <tb:TOOLBARGRIPPER/>
</tb:TOOLBAR>
</P>
<DIV ID="oDiv">Every dog has its day. </DIV>
<P><BUTTON onclick="addButton()">Add Button</BUTTON></P>

Code example: https://samples.msdn.microsoft.com/workshop/samples/webcontrols/toolbar/tbButtonExample3.htm

Scripting the TOOLBARCHECKBUTTON Element

The TOOLBARCHECKBUTTON behaves similarly to the TOOLBARBUTTON. You can run script when a TOOLBARCHECKBUTTON element is clicked by setting a handler for the onclick event on the element. In the following example, the onclick handler on the TOOLBARCHECKBUTTON changes the background color of the DIV element.


<SCRIPT>
   function setBackground()
   {
      sBGColor = oDiv.style.backgroundColor;
      if (sBGColor == "lightgrey") {sBGColor = "white";}
      else {sBGColor = "lightgrey";}
      oDiv.style.backgroundColor = sBGColor;
    }
</SCRIPT>

<P>
   <tb:TOOLBAR ID="oTB">
      <tb:TOOLBARGRIPPER/>
      <tb:TOOLBARCHECKBUTTON onclick="setBackground()" TEXT="Gray"/>
   </tb:TOOLBAR>
</P>
<DIV ID="oDiv" STYLE="background-color:white">Every dog has its day. </DIV>

Code example: https://samples.msdn.microsoft.com/workshop/samples/webcontrols/toolbar/tbCheckButtonExample.htm

When a button is clicked, the onbuttonclick event fires. You can identify the clicked button by handling the onbuttonclick event on the TOOLBAR. The srcNode event property returns the button object and the SELECTED property returns a string indicating the button's selected state. The following example shows how to retrieve both of these properties for the clicked button. It sets the background color of the DIV element based on the value of the button's SELECTED property.


<SCRIPT>
   function setBGColor()
   {
      var oButton = window.event.srcNode;
      var sButtonName = oButton.getAttribute("text");
      var sButtonSelected = oButton.getAttribute("selected");
      if (sButtonSelected == "true")
      {oDiv.style.backgroundColor = sButtonName.toLowerCase();}
      else 
      {oDiv.style.backgroundColor = "white";}
   }
</SCRIPT>

<tb:TOOLBAR ID="oTB" onbuttonclick="setBGColor()">
   <tb:TOOLBARGRIPPER/>
   <tb:TOOLBARCHECKBUTTON TEXT="Yellow"/>
</tb:TOOLBAR>
</P>
<DIV ID="oDiv">Every dog has its day. </DIV>

Code example: https://samples.msdn.microsoft.com/workshop/samples/webcontrols/toolbar/tbCheckButtonExample2.htm

You can create a TOOLBARCHECKBUTTON dynamically with the createCheckButtonAt method.


<SCRIPT>
   function addButton()
   {
      var oButton = oTB.createCheckButtonAt(oTB.numItems);
      oButton.setAttribute("text","Yellow");
   }
    
   function changeBGColor()
   {
      var oButton = window.event.srcNode;
      var sButtonName = oButton.getAttribute("text");
      var sButtonSelected = oButton.getAttribute("selected");
      if (sButtonSelected == "true")
      {oDiv.style.backgroundColor = sButtonName.toLowerCase();}
      else 
      {oDiv.style.backgroundColor = "white";}
   }
</SCRIPT>

<tb:TOOLBAR ID="oTB" onbuttonclick="changeBGColor()">
    <tb:TOOLBARGRIPPER/>
</tb:TOOLBAR>
</P>
<DIV ID="oDiv">Every dog has its day. </DIV>
<P><BUTTON onclick="addButton()">Add Button</BUTTON></P>

Code example: https://samples.msdn.microsoft.com/workshop/samples/webcontrols/toolbar/tbCheckButtonExample3.htm

Scripting the TOOLBARCHECKGROUP Element

You can force one of the TOOLBARCHECKBUTTON elements in a TOOLBARCHECKGROUP to always be selected by setting the FORCESELECTION attribute on the TOOLBARCHECKGROUP element to true.


<SCRIPT>
   function setBackground(sColor)
   {
      sBGColor = oDiv.style.backgroundColor;
      if (sBGColor != sColor) {sBGColor = sColor;}
      oDiv.style.backgroundColor = sBGColor;
    }
</SCRIPT>

<tb:TOOLBAR ID="oTB">
   <tb:TOOLBARGRIPPER/>
   <tb:TOOLBARCHECKGROUP FORCESELECTION="true">
      <tb:TOOLBARCHECKBUTTON onclick="setBackground('white')" TEXT="White"/>
      <tb:TOOLBARCHECKBUTTON onclick="setBackground('yellow')" TEXT="Yellow"/>
      <tb:TOOLBARCHECKBUTTON onclick="setBackground('mistyrose')" TEXT="Rose"/>
   </tb:TOOLBARCHECKGROUP>
</tb:TOOLBAR>
</P>
<DIV ID="oDiv" STYLE="background-color:white">Every dog has its day. </DIV>

Code example: https://samples.msdn.microsoft.com/workshop/samples/webcontrols/toolbar/tbCheckGroupExample.htm

The oncheckchange event fires when a TOOLBARCHECKBUTTON has changed its state from selected to unselected and vice versa. The SELECTED attribute returns a string value of true if the TOOLBARCHECKBUTTON is selected.

In the following example, the oncheckchange event is handled on the TOOLBAR by the setColor method. The event fires twice every time a TOOLBARCHECKBUTTON in the TOOLBARCHECKGROUP is clicked: once for the button changing to an unselected state and once more for the clicked button, which has changed to a selected state. In the following example, only the clicked button should change the background color. The script filters the buttons on the SELECTED attribute to determine which one was clicked.


<SCRIPT>
   function setColor()
   {
      var oButton = window.event.srcNode;
      sButtonType = oButton.getAttribute("id");
      if (sButtonType == "foreground")
      {
         if (oDiv.style.color != "white")
         { oDiv.style.color = "white"; }
         else
         { oDiv.style.color = "black"; }
      }
      else if (sButtonType == "background")
      {
         sButtonSelected = oButton.getAttribute("selected");
         if (sButtonSelected == "true")
         {
            sColor = oButton.getAttribute("text").toLowerCase();
            oDiv.style.backgroundColor = sColor;
         }
      }
   }
</SCRIPT>

<tb:TOOLBAR ID="oTB" oncheckchange="setColor()">
   <tb:TOOLBARGRIPPER/>
   <tb:TOOLBARLABEL DEFAULTSTYLE="font-Weight:bold" TEXT="Foreground (checkbutton):"/>
   <tb:TOOLBARCHECKBUTTON TEXT="White" ID="foreground"/>
   <tb:TOOLBARSEPARATOR/>
   <tb:TOOLBARLABEL DEFAULTSTYLE="font-Weight:bold" TEXT="Background (checkgroup):"/>
   <tb:TOOLBARCHECKGROUP FORCESELECTION="true">
      <tb:TOOLBARCHECKBUTTON TEXT="White" ID="background"/>
      <tb:TOOLBARCHECKBUTTON TEXT="Yellow" ID="background"/>
      <tb:TOOLBARCHECKBUTTON TEXT="Gray" ID="background"/>
   </tb:TOOLBARCHECKGROUP>
</tb:TOOLBAR>
</P>
<DIV ID="oDiv" STYLE="background-color:white">Every dog has its day. </DIV>

Code example: https://samples.msdn.microsoft.com/workshop/samples/webcontrols/toolbar/tbCheckGroupExample2.htm

Scripting the TOOLBARDROPDOWNLIST Element

You can determine which OPTION element in a TOOLBARDROPDOWNLIST is selected through script. First, handle the onchange event on the TOOLBARDROPDOWNLIST element. You must do several things in the handler function.

Read through the toolbar objects until you find the ToolbarDropDownList object.
Get the index number of the selected Option.
Retrieve the indexed Option object from the ToolbarDropDownList object's Options collection.
Get the Value attribute of the Option object.

The script for doing this is shown in the following example.


<SCRIPT>
   function setBackground()
   {
      // Retrieve the ToolbarDropDownList object.
      var oDropDownList = getDropDownListObj();
      // Get the index number of the selected option.
      var index = oDropDownList.getAttribute("selectedIndex");
      // Retrieve the selected option from the Options collection.
      var selectedOption = oDropDownList.getOptions().item(index);
      // Get the Value attribute for the selected option.
      var sColor = selectedOption.getAttribute("value");
      var sBGColor = oDiv.style.backgroundColor;
      // Set the DIV's background color to the value of the selected option.
      if (sBGColor != sColor) {sBGColor = sColor;}
      oDiv.style.backgroundColor = sBGColor;
   }

   function getDropDownListObj()
   {
      var oItem = null;
      var oList = null;
      // Cycle through all the toolbar items until the dropdownlist object is found.
      for (i=0;i<oTB.numItems;i++)
      {
         oItem = oTB.getItem(i);
         if (oItem.getType()=="dropdownlist")
         {
            oList = oItem;
            return oList;
         }
      }
   }    
</SCRIPT>

<tb:TOOLBAR ID="oTB">
   <tb:TOOLBARGRIPPER/>
   <tb:TOOLBARDROPDOWNLIST onchange="setBackground()">
      <OPTION VALUE="white">White</OPTION>
      <OPTION VALUE="yellow">Yellow</OPTION>
      <OPTION VALUE="mistyrose">Rose</OPTION>
   </tb:TOOLBARCHECKGROUP>
</tb:TOOLBAR>
</P>
<DIV ID="oDiv" STYLE="background-color:white">Every dog has its day. </DIV>

Code example: https://samples.msdn.microsoft.com/workshop/samples/webcontrols/toolbar/tbDropDownListExample.htm

About the Toolbar WebControls Client Behavior

Introduction

Prerequisites

Toolbar Elements

Writing a Simple Toolbar

Formatting the Toolbar

Using Toolbar Elements with Script

Creating a Toolbar Dynamically

Scripting the TOOLBARBUTTON Element

Scripting the TOOLBARCHECKBUTTON Element

Scripting the TOOLBARCHECKGROUP Element

Scripting the TOOLBARDROPDOWNLIST Element

Related Topics

Additional resources