Silverlight Navigator API

Programming Interface (asp.net API)

The navigator is designed to function with any charts by changing single setting. (Chart.Navigator.Enabled = true) While all current chart types may not be supported, the goal is to support them all soon. There are two API layers in this navigator. One controls the UI and behavior and the other interacts with the chart in real-time.

A temporary directory setting is also required like with image charts where temporary data can be stored for the client to download.

Enabling the Navigator

The following code snippen is an example of the required code to enable the Navigator.

chart.Navigator.Enabled = true
chart.TempDirectory = "temp"
chart.LegendBox.Position = LegendBoxPosition.ChartArea

Using the chart area legendbox position enabled richer functionality.

UI / Behavior API

The chart.Navigator class contains almost all the settings to configure the different navigator options. They provide a way to turn interactivity features on and off, as well as showing and removing parts of the chart. These settings are broken into sections below.

Navigation Bar

Disabling The Navigation Bar
Chart.Navigator.NavigationBar.Visible = false

Disabling History
Chart.Navigator.NavigationBar.EnableHistory = false

Disabling Range Selectors
Chart.Navigator.NavigationBar.EnableRangeSelectors = false

Styling the bar
Chart.Navigator.NavigationBar.Background.Color = Color.Red

Chart.Navigator.NavigationBar inherits from a Box class which offers all the styling properties such as background, padding, and corners.

Sample: Feature Set > Navigator > NavigatorNavBarStyling

Quick Zoom Buttons (Default Setting)
Chart.Navigator.NavigationBar.QuickZoomIntervals = "Auto"

Disabling Quick Zoom Buttons
Chart.Navigator.NavigationBar.QuickZoomIntervals = ""

The Quick Zoom intervals are controled by a single string which can disable the buttons, make them determined automatically, specify what intervals to use, and optionally the label text of the buttons. The buttons support localization so users in different cultures will see the appropriate day/month abbreviations.

The string takes a comma delimited list of intervals and supports custom label specification with an equal sign. Setting it to "Auto" will let the chart determine what the best buttons are.

Syntax

"[Multiplier][TimeInterval]=[Label],..."

Intervals that are larger than the axis range or smaller than the zoomLimit will be omitted.

Sample: Feature Set > Navigator > NavigatorNavBarStyling

Examples

Setting	Result
""	No buttons
"1min,30min,5h,5d"	[1min][30min][5h][5d]
"Auto"	Automatically determined based on scale range
"1d,5d=FiveDays"	[1d][FiveDays]
"1d,1m,1y,YTD=Year To Date,Max"	[1d][1m][1y][Year To Date][Max]

Time Interval specifiers

Specifier	Meaning
ms	millisecond
s	second
min	minute
h	hour
d	day
m	month
y	year
YTD	year to date
Max	maximum

Chart Area Legend

Enabling ChartArea Legend
Chart.LegendBox.Position = LegendBoxPosition.ChartArea

Controling the range display
Chart.LegendBox.Value = "%PercentageChange"

Sample: Feature Set > Navigator > NavigatorFinance

Controling the display of a single element's value
DefaultElement.SmartLabel.Text = "%YValue"

Arranging the range display mode
Chart.LegendBox.Template = "%Value%Icon%Name"

Other Samples:

Feature Set > Navigator > NavigatorFinance
Feature Set > Navigator > NavigatorCALegendStyling
Feature Set > Navigator > NavigatorStockDB

When the legend is not in the chart area it is not dynamic and it shows the values for the entire dataset. When the legend is placed inside the chart area however, it behaved dynamically by updating its value in real-time. The display of each series in the chart area as shown above can be specified through the respective LegendBox.Template. When the mouse is on the chart area, it displays the values of each element. This value can be specified with DefaultElement.SmartLabel.Text and all the element tokens can be used.

By setting Series.LegendEntry.Value = "" for any series, the chart will not perform any calculations on the displaying info about the visible or highlighted range.

Chart Area Legend Behavior Notes

Legend Entries in the chart area cannot use label markup
If LegendEntry.Value is set to "%PercentageChange" and the entry labelStyling color is not set, the color will be dynamic; green for positive change and red for negative.
When the legendEntry.LabelStyling color is not set, the legend entry name will use the series color.

Chart Area

Not showing the chart area
Chart.ChartArea.Visible = false

Sample: Feature Set > Navigator > NavigatorSelector

Specifying UI Features
Chart.ChartArea.NavigatorOptions =
     ChartAreaNavigationOptions.DragScrolling
     | ChartAreaNavigationOptions.ArbitrarySelection
     | ChartAreaNavigationOptions.ScrollWheel;

Omiting any options will disable them.

Sample: Feature Set > Navigator > NavigatorSelectorSeparate

Specify drag area vs. selection area
Chart.ChartArea.NavigatorDragAreaPercentage

Chart Area Axis

Make cells smaller then axis ticks available
Chart.Navigator.EnableCellVisualCues = true

When the chart area is disabled, the chart area axis will also be collapsed.
When the preview area supports cell selection, it will be available on the chart area axis.
The chart area axis will inherit its background color from the chart area.

Preview Area

Specifying Preview Area Height
Chart.Navigator.PreviewAreaHeight = 35

Disabling/Hiding Preview Area
Chart.Navigator.PreviewAreaHeight = 0

Disable chart data drawing
Chart.Navigator.EnablePreviewAreaChart = false

Specifying UI Features
Chart.Navigator.PreviewAreaNavigationOptions =
     PreviewAreaNavigationOptions.Cells
     | PreviewAreaNavigationOptions.ArbitrarySelection
     | PreviewAreaNavigationOptions.ScrollWheel;

Omiting any options will disable them.

The preview area provides a visual representation of the time range and data the scrollbar represents. They work together so disabling the scrollbar disables the preview as well. The preview area supports cell and arbitrary selection, dragging handles that mirror the scrollbar handles and scrollwheel zooming..

Disabling the scrollbar will remove the preview area as well.

ScrollBar

Disabling the Scrollbar
Chart.Navigator.EnableXScrollbar = false

Disabling the scrollbar will remove the preview area as well.

Sample: Feature Set > Navigator > NavigatorDetails

General Options

Chart Sizing

A chart size can be specified in the traditional way. However, with the navigator, if the width or height is not specified, the chart will size to 100% of the available width or height.

Sample: Feature Set > Navigator > NavigatorDynamicSizing

Disable Browser Status Help Messages
Chart.Navigator.EnableBrowserStatusHelp = false

This may not work for some browsers by default.
For example, to enable it in IE 8, choose Internet Options > Security tab > custom level > Under Scripting > Allow status bar updates via script, choose the Enable radio button. Using the SetHelpMessageHost javascript property of the client side chart, a text box or other element can be associated with this message.

Silverlight plugin installation handling
The chart provides some options for handling users without silverlight installed. The options are defined by the SilverlightInstall enumeration.
Chart.Navigator.SilverlightInstall = SilverlightInstall.Automatic

Specify Animation Duration (in milliseconds)
Chart.Navigator.AnimationDuration = 200

Disable Mouse Tracking
Chart.Navigator.EnableMouseTracking = false

Limiting the zooming depth
Chart.Navigator.ZoomLimit = TimeInterval.Day
Chart.Navigator.ZoomLimit = TimeSpan.FromDays(5)

Set a starting zoom position
Chart.XAxis.Viewport.ScaleRange
= new ScaleRange(new DateTime(2010,1,1),new DateTime(2010,5,1))

Culcutre Settings
Server and client side charts may be running on machines with different culture settings. By default the client side chart will inherit the hosting machines culture. In some cases this may be a problem, for example if using formatting such as currency for values, using the clients default culture may incorrectly represent monetary values. On the other hand, using the clients culture for x axis time scale labels is useful. Culture settings may be specified for the entire chart or any specific axis:

Chart.DefaultCultureName = "en-US"
Chart.YAxis.CultureName = "en-US"

Windowless Mode
A property is available to allow the Silverlight Navigator plugin to operate in windowless mode. This feature is useful when the navigator obscures other dynamic content on a page. For more information on this feature, see this page.

Chart.Navigator.EnableWindowlessMode = true;

Navigator Initialization

Loading Strings
When the navigator is initializing it displays strings such as "Please Wait...", "Downloading", "Loading". There is a property which allows overwriting these strings if they must be in a different language or just to change the wording.

Chart.Navigator.LoadingTextOverride = "Wait|Downloading(%Percentage)|Loading";

This property takes a single string which can have three different strings separated by a '|' character. The downloading string can contain the token "%Percentage" which will be replaced with the percent downloaded when the chart is loading.

WARNING: The %Percentage token is case sensitive.

LoadingAnimation
There is a number of loading animation visuals available for display while the Navigator is loading.

Chart.Navigator.LoadingAnimation = LoadingAnimation.Snake;

Preview Image Genration
When the Navigator is loading, the chart is capable of displaying a preview of what the navigator will look like when it is loaded. This provides a more seamless experience for end users.

Chart.Navigator.GenerateImagePreview = false;

Preview Image Performance
If the initial navigator view does not contain many elements, this image can be generated very quickly to show while all the data is downloading. However, if the initial view contains a large number of elements (thousands for instance) the preview image may take a moment to generate. In this scenario, it may be worthwhile disabling the preview image. This can improve the time necessary for the navigator to load, but the navigator must load fully before the chart is visible. For most cases, the preview image generates very quickly and it's best to keep it enabled. When it becomes a problem and is affecting the website performance, disable it.

Client Side Programming Interface (Real-Time JavaScript API)

Several properties and methods allow the chart to be manipulated through JavaScript and allows the chart to call functions and update objects on a page. For example the standard navigation bar on top of Navigator charts can be created from HTML elements and communicate with the chart through Javascript directly.

Control The Chart

In order to use the JavaScript interface of the silverlight chart, a unique ID must be specified for the control like with the following asp.net code

Chart.Navigator.ControlID = "slPlugin"

Now the chart object can be accessed from JavaScript on the page. Consider the following code snippet:

function goback() {
var control = document.getElementById(chartID);
control.Content.Chart.PageLeft();
}
</script>

This code defines a function that accesses the chart object and calls the chart's PageLeft() method.

Sample: Feature Set > Navigator > NavigatorPageInteraction

Getting information from the Chart

The Javascript chart interface provides the ability to get information about the position status of the chart. The following JavaScript method gets the time range of the visible chart area and updates the visible range to show only the last 10 days from the current right position.

function leftten() {
       var control = document.getElementById(chartID);
       var range = control.Content.Chart.GetVisibleRange();
       var leftDate = range.ValueHigh;
       var tmpDate = range.ValueHigh;
       leftDate.setDate(leftDate.getDate() - 10);

control.Content.Chart.NavigateToVisibleRange(leftDate, tmpDate);
}

</script>

Sample: Feature Set > Navigator > NavigatorPageInteraction

Chart Controlling the Page

The chart can call a Javascript functon when the viewport is updated by the user and it can update an HTML element with a help message text.

The following example will let the chart update the text of a div element with a help message while using the navigator. The first part of this task requires registering a method or property with the chart. Consider the following JavaScript code.

// This function registers the location update handler when the silverlight chart loads.
function initEvents() {
       var control = document.getElementById("slPlugin");
       if (control) {
             control.Content.Chart.SetHelpMessageHost("helpDiv.innerHTML");
             clearInterval(initID);
       }

}

// Try to register the location update handler with the chart until it is succeeds.
var initID = setInterval("initEvents()", 1000);

</script>

The initEvents() method tells the chart to update the innerHTML property of the div tag named helpDiv with a help message. The if, else statement ensures that the silverlight control is loaded before this property is assigned. If it is not loaded, it waits 1000 milliseconds before it tries again.

Samples:
Feature Set > Navigator > NavigatorPageInteraction
Feature Set > Navigator > NavigatorSelector
Feature Set > Navigator > NavigatorSelectorControl
Feature Set > Navigator > NavigatorSelectorSeparate

ChartArea Tokens
The navigator supports all the same label tokens as a static charts. However, it offers a couple additional tokens that are not supported by static charts. The reason this is not available with static charts is because these tokens are evaluated in real-time and based on the mouse position over the chart area. The tokens %XValue and %Value can be used in chart area hotspots. Consider this setting:

Chart.ChartArea.Hotspot.Tooltip = "%XValue, %YValue"

When the mouse is hovering the chart area, a tooltip will appear showing the axis values at the current mouse position. Then can be used in hotspot URL with enables passing the clicked axis values to javascript.

Sample: Feature Set > Navigator > NavigatorGetSeriesValue

Slideshow Presentation with Navigator

Including a Navigator chart in a slideshow presentation is easy to do. Refer to sample [Feature Set > Navigator > NavigatorSlideshow]

It contains information about the slideshow in javascript arrays including a text message, delay in milliseconds, and left and right positions to move the chart for each slide.

var myTextArr = [...];
var delayArr = [...];
var leftDTArr = [...];
var rightDTArr = [...];

A displaySlide function will update the page with the specified slide.

function displaySlide(frame) {
    var control = document.getElementById(chartID);
    control.Content.Chart.NavigateToVisibleRange(leftDTArr[frame], rightDTArr[frame], delayArr[frame])
    var tText = myTextArr[frame];
    setTimeout('displayText("' + tText + '");', delayArr[frame]);
}

The startSlideshow() function initiates the slide show and playSlide() function handles itarating the slides with a delay between them. playSlide() ensures only the available slides are shown and initiates the next slide by calling itself on a delay.

function startSlideshow() {
playSlide(0)
}

function playSlide(frame) {
    displaySlide(frame);
    var nextFrame = frame + 1;
    if (nextFrame < myTextArr.length) {
        setTimeout('playSlide(' + nextFrame + ')', delayArr[frame] + slidesPause);
    }
}

Possible Uses

The interface is designed to allow users to use the chart to control content of the page or let the content of your page control the chart itself. The chart is able to animate between views of data such as zooming in or out which gives the user a better idea of how a subset of the the data relates to a bigger picture. A page that lets the user navigate articles related to specific dates for example can update the chart view to encompass data that is related to those articles.

A page that emulates a slideshow type movie can be connected to a chart so that when each slide is shown the chart animates to the appropriate data. Methods that control the navigation also provide the option to specify the duration any animation between the different ranges.

Sample: FeatureSet > Navigator > NavigatorIncludeInAxisScale

Javascript Interface Reference

Below is a list of available methods provided by this interface.

Method/Property	Description
Control The Chart
PageLeft()	Pages the scrollbar left.
PageRight()	Pages the scrollbar right.
NavigatorForward()	Navigates the zoomer forward to the next location. Same as clicking the forward button on the navigation bar.
NavigateBack()	Navigates the zoomer back to the previous location. Same as clicking the back button on the navigation bar.
NavigateToCenter (object centerVal, int milliseconds)	Animates the zoomer to center at the specified x axis value maintaining the scrollbar width in the specified amount of time. centerVal - X axis value to center on, this value can be numeric, DateTime or string. milliseconds - Time of the animation in milliseconds
NavigateToCenter (object centerVal)	Animates the zoomer to center at the specified x axis value maintaining the scrollbar width. centerVal - X axis value to center on, this value can be numeric, DateTime or string.
NavigateToVisibleRange (object leftVal, object rightVal, int milliseconds)	Animates the view to the specified x axis value range in the specified amount of time. leftVal - Value of the new left position. rightVal - Value of the new right position. milliseconds - Time of the animation in milliseconds
NavigateToVisibleRange (object leftVal, object rightVal)	Animates the view to the specified x axis value range. leftVal - Value of the new left position. rightVal - Value of the new right position.
NavigateToVisibleRangePerc (double left, double right, int milliseconds)	Animates the view to the specified percentage range in the specified amount of time. The percentage range is a numeric value from 0 to 1 representing the maximum left and right positions. A range of 0 to 1 means the chart is fully zoomed out. left - Left percent position from 0 to 1. Value must be less than the right position. right - Right percent position from 0 to 1. Value must be more than the left position. milliseconds - Time of the animation in milliseconds.
NavigateToVisibleRangePerc (double left, double right)	Navigates the view to the specified percentage range. The percentage range is a numeric value from 0 to 1 representing the maximum left and right positions. A range of 0 to 1 means the chart is fully zoomed out. left - Left percent position from 0 to 1. Value must be less than the right position. right - Right percent position from 0 to 1. Value must be more than the left position.
Get info from chart.
ScaleRange GetVisibleRangePerc()	Gets the visible x axis percentage range. The percentage range is a numeric value from 0 to 1 representing the viewport left and right positions. A resulting range of 0 to 1 means the chart is fully zoomed out.
ScaleRange GetVisibleRange()	Gets the visible x axis range values.
double GetSeriesYValueAtX(string name,object xValue)	Gets the element y value of the series specified at a given x position. name - Name of the series to search for elements in. xValue - The x value to match with an element.
Have the chart control the page.
SetLocationUpdateHandler(string)	Sets the name of a JavaScript method with two parameters (lowValue, highValue) on the current page that will be called when the chart viewport is updated and the new range will be passed to it.
SetHelpMessageHost(string)	Sets the property of an HTML or Javascript object on the page which will be updated by the chart with a help message when the user is interacting with the chart.

Notes:

JavaScript DateHandling
Unlike asp.net, when Javascript dates are created they assume the DateTime is given in universal GMT time. When passing dateTime values to the navigator, the navigator will adjust for the timezone difference so that dates passed from javascript to Navigator will be treated as the GMT time is actually the local time. This makes working with dates more convenient without having to adjust the time manually.

This conversion was introduced in version 6.1. If a chart passing dates in parameters to JS methods was developed with version 6.0, time zone conversions were necessary, but they can be removed if the same code will be running with version 6.1.

Range vs RangePerc
The Percentage range of the chart is a coordinate system where 0 = the maximum left and 1 = maximum right chart positions.

The range represents the actual values of the x axis and can be given in DateTime or numeric data types. Category scales also use a numeric scale range numbering each element name from 0-n.

Performance Considerations

This chart is designed to animate large sets of data smoothly utilizing silverlight which is a subset of WPF. While WPF has very powerful graphics capabilities, silverlight does not have all the same capabilities of WPF. There are a few things that can help improve the performance of your charts if they become to slow down.

Bar Charts

A bar series includes some extra graphical elements such as a borders and the bar face itself. A chart with thousands of such bars can be made much more efficient utilizing the finance bar series types. This will make the bars thin but when so many bars are available they will usually be very close together anyway. However, these bar widths can be controled with Series.Line.Width . Using the following code a series can be converted to utilize this performance enhancement.

mySeries.Type = SeriesTypeFinancial.Bar;
// In order to improve the performance of this chart, the volume series will utilize the finance bars instead of full columns.
foreach (Element el in mySeries.Elements)
{
      // This applies the y value to high and 0 to low so that the finance bars appear as a column series would.
      el.High = el.YValue;
      el.Low = 0;
}

mySeries.Type = SeriesTypeFinancial.Bar
' In order to improve the performance of this chart, the volume series will utilize the finance bars instead of full columns.
For Each el As Element In mySeries.Elements
      ' This applies the y value to high and 0 to low so that the finance bars appear as a column series would.
      el.High = el.YValue
      el.Low = 0
Next

Sample: Feature Set > Navigator > NavigatorStockDB

Line and AreaLine Marker Behavior

Lines with many points have element markers for each. When these elements exceed a count of 250 the element markers will automatically be removed. However, in charts with fewer points, removing the element markers can also improve performance.

Chart Size

The chart size has a great influence on animation performance. If the charts starts getting slow, making it smaller is likely to speed it up a great deal.

Mouse Tracking

Disabling mouse tracking can improve performance of client side charts when the user hovers their mouse over the chart areas.

Element Hotspots

Using element hotspots to make them clickable or with tooltips can add also add a performance penalty when the user hovers their mouse over the chart areas.

Axis AlternateGridBackground & GridLines

Everything that needs to move on the chart area requires processing time. Disabling the alternateGridBackground color can help as a start. In addition, disabling gridlines can help also.

Axis Scale

The chart is capable of scrolling easily, however, when the y axis range updates dynamically the chart area must not only scroll but also scale everything on it. Setting a static axis range (YAxis.ScaleRange = ...) can lock in the axis range making the chart very fast to scroll and zoom.

Caching

The server side processing can be cached so that each request of a page with charts on them doesnt require generating them each time. To use this feature, you must set a static filename for the chart such as: Chart.FileName = "ChartA1"; Then enable fragment caching for the hosting aspx page.

For more information see:

- How To Perform Fragment Caching in ASP.NET by Using Visual C# .NET

- Chart File Handling

Tutorials

Overview

User Interface