CXP Developer Guide > Tutorials > Chapter 2: All About Menus Next: Chapter 3: Special Buttons
(Previous: Chapter 1: All About Buttons)

Chapter 2: All About Menus




2.1 Create a Drop Down Menu


A useful feature for browser toolbars is to have menus with menu items that navigate to web pages when clicked. To add a button with a menu to the toolbar you can use the appendButton() method of the toolbar object with type "menu". The image below shows a new menu button on the toolbar, followed by the sample code that creates the menu button with two menu items that link to a web page. 

function OnToolbarInit()
{
    ...
    // Add a menu button with a label and a tooltip.
    var btnMenu = toolbar.appendButton("menu");
    btnMenu.label = "Drop down menu";
    btnMenu.tooltip = "Click button to show menu";

    // Add a menu item with a label.
    var option1 = btnMenu.menu.appendMenuItem();
    option1.label = "Candeo Technologies";
    // When it's clicked, navigate to the Candeo web site.
    option1.oncommand = "toolbar.navigate('http://www.candeo.com/')";

    // Add another menu item with a label.
    var option2 = btnMenu.menu.appendMenuItem();
    option2.label = "Yahoo!";
    // When it's clicked, navigate to the Yahoo! web site.
    option2.oncommand = "toolbar.navigate('http://www.yahoo.com/')";
    ...
}

A menu button is created by setting the type parameter of the toolbar.appendButton() method to "menu", as shown above. The button object can then be used to specify various properties for the menu button. In the above example, we set the button object's label property, which sets the menu button's label text. A menu item is created by calling appendMenuItem() on the menu, as shown above. Clicking anywhere on the button will cause the menu to be shown. When you create a menu button in this way, the default action that occurs when a user clicks the button is to show the button's menu.

There is a second type of button that shows a menu by default. It is a two-part button, and you create it by setting the type parameter to "menu-button" when you invoke toolbar.appendButton(). What distinguishes a menu-button button from a normal menu button is that a menu-button button displays a vertical divider when it is hot (under the mouse cursor). This divider indicates that the button is composed of two parts. The left part contains your image and/or label, and clicking on this part will trigger the button's oncommand action. The right part contains just a drop down arrow, and clicking this part will trigger the button's onmenucommand action (which by default shows the button's menu).

Please refer to the button object section of the CXP API Reference for more information on working with toolbar menu buttons and menu-button buttons.


2.2 Create a Menu with Check Mark Menu Items


A check mark item can be added to a menu button. A check mark next to a particular menu item indicates that the item is selected. The image below shows a new menu button on the toolbar with two check mark menu items, followed by the sample code that creates the check mark menu item. 

function ToggleCheckedState()
{
    // Toggle the state of the check mark menu item.
    toolbar.srcElement.checked = !toolbar.srcElement.checked;
}

function OnToolbarInit()
{
    ...
    // Add a menu button with a label and a tooltip.
    var btnMenu = toolbar.appendButton("menu");
    btnMenu.label = "menu";
    btnMenu.tooltip = "Click button to show menu";

    // Add a check mark menu item with a label.
    var check = btnMenu.menu.appendMenuItem();
    check.label = "Check mark item";
    // When it's clicked, toggle the check mark.
    check.oncommand = ToggleCheckedState;
    ...
}

2.3 Create a Menu with Radio Dot Menu Items


A radio dot item can be added to a menu button. Radio dot items work like radio buttons, representing mutually exclusive settings or options. They should be grouped together so that only one of the items can be selected at a time. The image below shows a new menu button on the toolbar with two radio dot menu items, followed by sample code that creates the radio dot menu items and manages their state. 

// Manage a group of radio dot menu items.
function CheckRadioItem(miFirst, miLast)
{
    // Check the current radio item (srcElement) and clear the others.
    var miClicked = toolbar.srcElement;
    for( var mi = miFirst; mi != null; mi = mi.nextMenuItem )
    {
        mi.checked = (mi == miClicked);
        if( mi == miLast ) break;
    }
}

function OnToolbarInit()
{
    // Add a menu button with a label and a tooltip.
    var btnMenu = toolbar.appendButton("menu");
    btnMenu.label = "menu";
    btnMenu.tooltip = "Click button to show menu";

    // Add a radio dot menu item with a label to the menu.
    radio1 = btnMenu.menu.appendMenuItem();
    radio1.label = "Radio item 1";
    radio1.radio = true;
    // When it's clicked, check it, and uncheck the other items.
    radio1.oncommand = "CheckRadioItem(radio1, radio2)";

    // Add another radio dot menu item.
    radio2 = btnMenu.menu.appendMenuItem();
    radio2.label = "Radio item 2";
    radio2.radio = true;
    radio2.oncommand = "CheckRadioItem(radio1, radio2)";
}

2.4 Create a Menu with Sub-menu Items


A sub-menu item can be created on a menu. To add a sub-menu item to a menu, we will use the menu appendMenuItem() method with the menu item type "menu". The image below shows a sub-menu item in a menu button on the toolbar, followed by the sample code that creates the sub-menu item. 

function OnToolbarInit()
{
    ...
    // Add a menu button with a label and a tooltip.
    var btnMenu = toolbar.appendButton("menu");
    btnMenu.label = "menu";
    btnMenu.tooltip = "Click button to show menu";

    // Add a sub-menu item with a label to the menu.
    var itemSubmenu = btnMenu.menu.appendMenuItem("menu");
    itemSubmenu.label = "More options";

    // Add a menu item with a label to the sub-menu.
    var option1 = itemSubmenu.menu.appendMenuItem();
    option1.label = "Sub-menu Option";
    ...
}

2.5 Show an Image in a Menu Item


An image can be added to a menu item. It will appear to the left of the label. A menu item image must be a 16x16 bitmap.

If your menu item represents a check mark or radio dot setting, you can also add a checked image to the menu item. Your checked image will be displayed instead of the default check mark or radio dot image when your menu item is checked.

To show an image in a menu item, set the menu item object's image property to the name of the image bitmap file. To set a custom check mark or radio dot image on a menu item, set the menu item object's checkedImage property.

The following sample code shows an image and a checked image being added to the radio dot menu items created above in section 2.3. 

function CheckRadioItem(miFirst, miLast)
{
    var miClicked = toolbar.srcElement;
    for( var mi = miFirst; mi != null; mi = mi.nextMenuItem )
    {
        mi.checked = (mi == miClicked);
        if( mi == miLast ) break;
    }
}

function OnToolbarInit()
{
    var btnMenu = toolbar.appendButton("menu");
    btnMenu.label = "menu";
    btnMenu.tooltip = "Click button to show menu";

    radio1 = btnMenu.menu.appendMenuItem();
    // This will be a radio dot menu item.
    // Use our own images to display menu item state.
    radio1.image = "examples\\customradio_off.bmp";
    radio1.checkedImage = "examples\\customradio_on.bmp";
    radio1.label = "Radio item 1";
    radio1.radio = true;
    radio1.oncommand = "CheckRadioItem(radio1, radio2)";

    radio2 = btnMenu.menu.appendMenuItem();
    // This will be a radio dot menu item.
    // Use our own images to display menu item state.
    radio2.image = "examples\\customradio_off.bmp";
    radio2.checkedImage = "examples\\customradio_on.bmp";
    radio2.label = "Radio item 2";
    radio2.radio = true;
    radio2.oncommand = "CheckRadioItem(radio1, radio2)";
}

2.6 Create a Menu Separator


A horizontal separator bar can be used to divide the menu items into logical functional groups. To add a separator to the menu, call the menu appendMenuItem() method with "separator" as the menu item type. 

function OnToolbarInit()
{
    ...
    // Add a menu button with a label and a tooltip.
    var btnMenu = toolbar.appendButton("menu");
    btnMenu.label = "menu";
    btnMenu.tooltip = "Click button to show menu";

    // Add a menu item with a label.
    var option1 = btnMenu.menu.appendMenuItem();
    option1.label = "Option 1";

    // Add a menu separator.
    btnMenu.menu.appendMenuItem("separator");

    // Add another menu item with a label.
    var option2 = btnMenu.menu.appendMenuItem();
    option2.label = "Option 2";
    ...
}

2.7 Change Menu UI


There are two settings you can use to give your menus a slick, stylish look. Both are properties of the toolbar object, and both control all of the menus shown from your toolbar.

The first is the menu edge color. In your menus, the area to the left of a menu item's text is called the image column. This is where the menu item's image will appear (if you use an image). The area behind your image is painted with a background color, which you can change by setting the toolbar object's menuEdgeColor property. In the Toolbar.js that was installed with the SDK, this color is set to gray. However, you can change it by setting your own color. If you do not set a menu edge color, it will default to the same color used for the rest of the menu (the Windows menu color), and the image column will not be noticeable. 

function OnToolbarInit()
{
    ...
    // Set the menu edge color to gray.
    toolbar.menuEdgeColor = "#C4C3AC";

    var btnMenu = toolbar.appendButton("menu");
    btnMenu.label = "menu";
    btnMenu.tooltip = "Click button to show menu";

    var option1 = btnMenu.menu.appendMenuItem();
    option1.label = "Option 1";

    btnMenu.menu.appendMenuItem("separator");

    var option2 = btnMenu.menu.appendMenuItem();
    option2.label = "Option 2";
    ...
}

The second property is toolbar.menuEdgeGradient which controls whether menu image columns are rendered as a gradient. By default, this property is false and your image columns are rendered as a solid color. But if you set it to true, your image columns are rendered as a gentle gradient from the Windows menu color (at the left) to the menu edge color (at the right). The following sample shows how you can enable gradients. 

function OnToolbarInit()
{
    ...
    // Set the menu edge color to gray.
    toolbar.menuEdgeColor = "#C4C3AC";
    // And use gradients.
    toolbar.menuEdgeGradient = true;

    var btnMenu = toolbar.appendButton("menu");
    btnMenu.label = "menu";
    btnMenu.tooltip = "Click button to show menu";

    var option1 = btnMenu.menu.appendMenuItem();
    option1.label = "Option 1";

    btnMenu.menu.appendMenuItem("separator");

    var option2 = btnMenu.menu.appendMenuItem();
    option2.label = "Option 2";
    ...
}

CXP Developer Guide > Tutorials > Chapter 2: All About Menus Next: Chapter 3: Special Buttons