Telerik UI for Windows 8 HTML

RadRadialMenu for Windows 8 is an HTML/JavaScript component that provides rich APIs for constructing a circular context menu. In this getting started article, you will learn how to create a basic radial menu, reference it in JavaScript, modify its properties, and attach event handlers to it.

This topic contains the following sections.

Prerequisites

Before you declare a Telerik control in your application, make sure that you have added the references to the needed JavaScript and CSS resources, as described here:

Adding Telerik UI for Windows 8 HTML to an HTML Page

Creating a RadRadialMenu

You can initialize RadRadialMenu like all other Telerik UI for Windows 8 HTML controls. To create a RadRadialMenu in the HTML markup, add an empty div element with a data-win-control attribute with a value of Telerik.UI.RadRadialMenu.

Code Listing 1: Radial Menu Mark-up Declaration Copy imageCopy
<div data-win-control="Telerik.UI.RadRadialMenu"></div>

Alternatively, you can initialize RadRadialMenu programmatically by first defining an empty div element with an id and passing it to the control's constructor in JavaScript.

Code Listing 2: Mark-up Copy imageCopy
<div id="myRadialMenu"></div>
Code Listing 3: Radial Menu JavaScript Declaration Copy imageCopy
var myRadialMenu = new Telerik.UI.RadRadialMenu(document.getElementById("myRadialMenu"));

Defining RadRadialMenu with no properties set will not produce a usable control. A context menu needs at least some items to serve its purpose. You can see a basic example of declaring a usable RadRadialMenu in Code Listing 4 in the next section.

Setting RadRadialMenu Options

Just like any other Windows Runtime JavaScript control, RadRadialMenu options can be defined through the data-win-options attribute in the mark-up. In the following example two menu items are added and a textarea HTML element is set as a target for the radial menu.

Code Listing 4: Setting Options in the Mark-up Copy imageCopy
<textarea id="target1"></textarea>
<div data-win-control="Telerik.UI.RadRadialMenu" data-win-options="{
        target: '#target1',
        items: [
            {
                text: 'Font size',
                icon: '\uE1C8'
            }, {
                text: 'Font',
                icon: '\uE185'
            }
        ]
    }"></div>

Alternatively, you can programmatically pass an options object as a second argument to the control constructor:

Code Listing 5: Mark-up Copy imageCopy
<textarea id="target2"></textarea>
<div id="myMenuWithOptions"></div>
Code Listing 6: Setting Options in JavaScript Copy imageCopy
var myMenuWithOptions = new Telerik.UI.RadRadialMenu(document.getElementById("myMenuWithOptions"), {
    target: '#target2',
    items: [
        {
            text: 'Font size',
            icon: '\uE1C8'
        }, {
            text: 'Font',
            icon: '\uE185'
        }
    ]
});

For detailed information regarding RadRadialMenu's properties refer to the related articles at the bottom of the article.

Both examples produce the same output. You can see the radial menu in Figure 1 below.

Figure 1: Basic RadRadialMenu
radialmenu-getting-started-options

Referencing RadRadialMenu Control Instance

At some point you might need to access the control in JavaScript to modify properties or get data. If RadRadialMenu has been initialized in the mark-up, you will need to get a reference to it. As described in this MSDN article about adding controls to a Windows Store app, any control in a Windows Runtime JavaScript application requires a call to WinJS.UI.processAll() for proper initialization. The same holds true for any of the Telerik UI controls. Once, the WinJS framework has initialized all the controls on the page, the RadRadialMenu control instance associated with a host HTML element can be retrieved using the winControl expando property of the host HTML element.

Get RadialMenu Control Reference Copy imageCopy
WinJS.UI.processAll().then(function () {
    //wait for the processAll() method to finish, then find the
    //menu control from the host element's winControl property
    var menuElement = document.getElementById("myRadialMenu");
    var menuControl = menuElement.winControl;
    console.log(menuControl instanceof Telerik.UI.RadRadialMenu); // true
});

Modifying RadRadialMenu Properties

Once RadRadialMenu is loaded and the control is referenced in JavaScript, the control exposes an extensive set of properties, methods and events. In the below example the background, innerBackground and border property values are modified after the control's initialization.

Code Listing 7: Modifying RadRadialMenu Properties Copy imageCopy
menuControl.background = "#000";
menuControl.innerBackground = "#72F0FF";
menuControl.border = "#72F0FF";

To see all available configuration options, look at the members, constructors, methods, properties and events available for the RadRadialMenu class.

Attaching Events

A context menu is not of much use if the menu items don't do anything. To add function to RadRadialMenu, you need to attach handlers to its events. You can either declare an event handler in the options object that you pass to the control during initialization, or you can use the addEventListener method to attach a function for execution upon a certain event. Below you can see samples of both approaches:

Code Listing 8: Declaring Event Handlers in JavaScript Copy imageCopy
var changingColorsMenu = new Telerik.UI.RadRadialMenu(document.getElementById("changingColorsMenu"), {
    target: '#target3',
    onexpand: changeInnerBackground
});

// or

var changingColorsMenu = new Telerik.UI.RadRadialMenu(document.getElementById("changingColorsMenu"), {
    target: '#target3',
    onexpand: function (e) {
        var colors = ["red", "green", "blue", "yellow"];
        var randomColorIndex = Math.floor(Math.random() * 3);

        var menu = e.menu;
        menu.innerBackground = colors[randomColorIndex];
    }
});
Note

You can also declare event handlers in HTML mark-up in the data-win-options attribute. To do that you need to mark the handler function as safe in your code, using the WinJS.Utilities.markSupportedForProcessing function.

Code Listing 9: Adding Event Listener to the RadialMenu Control After Initialization Copy imageCopy
changingColorsMenu.addEventListener("expand", changeInnerBackground);

In the above examples, the radial menu's inner background color is randomized between four predefined colors when the expand event is triggered.

You can also add event handlers to each single menu item to make it functional. This can be done in a declarative manner in the options object of the control or through the addEventListner method.

Code Listing 10: Adding Event Listener to the RadialMenu Control After Initialization Copy imageCopy
var myMenu = new Telerik.UI.RadRadialMenu(document.getElementById("itemEventsMenu"), {
    target: '#target4',
    items: [
        {
            id: 'ChangeColor',
            text: 'Change Color',
            icon: '\uE186',
            onaction: changeInnerBackground
        }
    ]
});

// or

myMenu.getItem('ChangeColor').addEventListener("action", changeInnerBackground);