Dundas Chart for Windows Forms Send comments on this topic.
Scrolling And Zooming
See Also



Glossary Item Box

Overview

Dundas Chart for Windows Forms delivers unprecedented highlighting, scrolling, and zooming functionality to all of your Windows Forms applications. Zooming and scrolling is made possible by using data views. These data views allow the Chart to display a subset of its data for increased readability and analysis.

 

Data Views

A data view is represented by the AxisDataView class, which is exposed via the Axis class' View property. A view has a size, position and size type (represented by the Size, Position and SizeType properties, respectively) which determines the sub-set of data that it displays (see Figure 1 below).

 

Figure 1: Position and Size of a Data View.

 

There are three different ways to display a view:

  1. By setting the Position, Size and SizeType properties of an AxisDataView object directly.
  2. As a result of a zooming operation caused by the end-user clicking and dragging the left-mouse button.
  3. As a result of calling the overloaded Zoom method.

The following are several other important view properties (note that the size-related properties have no effect when a view is displayed programmatically using code):

For further information concerning small and large scrolling sizes see the Scrolling section.

A data view can also be reset, either by an end-user or programmatically. Every time an end-user zooms in on data the previous view is saved, and when the end-user clicks on the ZoomReset button (see the Scrolling section for a picture of a scrollbar's elements) the previous view is displayed. When zooming on data using the overloaded Zoom method it is up to the developer to save the previous view (depends on the Zoom definition used). When resetting a view using the overloaded ZoomReset method any of the saved views can be displayed, including the originally displayed data (i.e. no zooming).

To determine the maximum and minimum axis values of a view use the GetViewMaximum and GetViewMinimum methods, respectively.

Axis margins also effect what is displayed for data views (if Axis.Margin is set to TRUE then margins will be displayed).

The default behavior of the various scrollbar buttons can be overridden using the AxisScrollBarClicked event, described in the Related Events section. Also, when an end-user changes a view the AxisViewChanged and AxisViewChanging event are raised.

The default position of the scrollbars is within the chart area along the edge of the plotting area. However, there are times that, when automatic positioning is used, the scrollbars may appear to jump around while scrolling. This is the result of the plot position dimensions changing for the new chart view. To overcome this behavior, the PositionInside property can be used to cause the placement of the scrollbars at the edge of the chart area.

 

Zooming

End-users can zoom in on data when an end-user clicks within a chart area and drags the left-mouse button (assuming that range selection and zooming is enabled, which is described below). The result of a zoom operation is the display of a view, along with accompanying scrollbars.

Zooming is enabled via the Zoomable property of the AxisDataView class, which is exposed as the View property of Axis objects. For end-users to be able to zoom in on data range selection must also be enabled, which is accomplished via the UserSelection property of Cursor objects (exposed as the CursorX and CursorY properties of chart areas).

 

Caution
If the axis interval type is a time (e.g. hours, minutes, etc.) then in order to have zooming function correctly the Cursor.IntervalType must be set to a time value as well. For example, if ChartArea1.AxisX.IntervalType is hours then ChartArea1.CursorX.IntervalType could be set to minutes.

 

Example

We will enable end-user range selection, cursors and zooming for the X axis only of a chart area named "Default".

Visual Basic Copy Code
Imports Dundas.Charting.WinControl
...

' We allow the end-user to zoom on data, and we also enable range selection and cursors
chart1.ChartAreas("Default").AxisX.View.Zoomable = True
chart1.ChartAreas("Default").CursorX.UserEnabled = True
chart1.ChartAreas("Default").CursorX.UserSelection = True 
C# Copy Code
using Dundas.Charting.WinControl
...

// We allow the end-user to zoom in on data, and we also enable range selection and cursors
chart1.ChartAreas["Default"].AxisX.View.Zoomable = true;
chart1.ChartAreas["Default"].CursorX.UserEnabled = true;
chart1.ChartAreas["Default"].CursorX.UserSelection = true;

 

When zooming occurs via end-user interaction the resulting size of a view may be limited, depending on the View.MinSize property value. If this property value is not set (Double.NaN) then no minimum view size will be used.

Programmatic zooming is accomplished via the overloaded Zoom method. The start and end axis positions of the new view may be specified, or the position and size of a view can be specified (see Figure 1 above). Also, the size and position of the current view can optionally be saved before displaying zooming.

 

Note
When zooming occurs all of the Interval properties of labels, grids and tick marks are automatically recalculated. To control how labels are displayed when the end-user zooms on data use the Axis.LabelStyle property.

 

Example

The following example zooms in on data with a given data view position and size. We assume that a series is being plotted in a chart area named "Default", and that the series has DateTime X value types. We also save the state of the previous view.

Visual Basic Copy Code
Imports Dundas.Charting.WinControl
...

Dim myStartDate As New DateTime()
myStartDate = myStartDate.Parse("January 10,2000")


' Zoom in on data. We specify a start position of January 10, and the size of the view is two days.
'  The Interval type is set to automatic, and we save the previous view state
chart1.ChartAreas("Default").AxisX.View.Zoom (myStartDate.ToOADate, 2, DateTimeIntervalType.Auto, true)
    

C# Copy Code
using Dundas.Charting.WinControl;
...

DateTime myStartDate = DateTime.Parse("January 10,2000");

// Zoom in on data.  We specify a start position of January 10, and the size of the view is two days.
//  The Size type is set to automatic, and we save the previous view state
chart1.ChartAreas["Default"].AxisX.View.Zoom(myStartDate.ToOADate(), 2, DateTimeIntervalType.Auto, true);


Scrolling

Scrolling can occur by either the end-user using a scrollbar (see Figure 2 below) or programmatically by calling the overloaded Scroll method.

Figure 2: Elements of a Scrollbar

 

It is important to know that there are two types of scrolling:

  • Large scrolling: with end-users large scrolling occurs when the end-user clicks on the background of a scrollbar (i.e. not on the thumb, but beside the thumb). The "large scrolling size" is equal to the size of the view, which is represented by the Size property. Since zooming results in a smaller size of view being displayed the "large scrolling size" decreases after each zoom. To limit this use the MinSize property to set a minimum large scrolling size.
  • Small scrolling: with end-users small scrolling occurs when the end-user clicks on an up/down or right/left button. The "small scrolling size" is determined by the SmallScrollSize property, and if it is not set (Double.NaN) then it is automatically recalculated to a smaller value after each zoom operation. When SmallScrollSize is not set the SmallScrollMinSize property can be used to set a minimum value. However, if SmallScrollSize is set to an explicit value then this value is always used for small scrolling, regardless of how many times zooming occurs (so setting SmallScrollMinSize therefore has no effect).

To decrement or increment a view one small or large scrolling size programmatically call the scroll method definition that uses a ScrollType enumeration value.

Call the Scroll method when scrolling programmatically. Scrolling does not change the size of a view, rather, it changes the position of a view. When calling the Scroll method the developer has the option of:

  • Scrolling to a specified location along an axis, using a definition that takes a newPosition parameter, or;
  • Incrementing or decrementing the view position by one small or large scrolling size by using the definition that takes a ScrollType parameter. This method definition can also be used to scroll to the last of first saved data view.

Example

The following example decrements the data view one large scrolling unit (equal to the size of the view) along the primary X axis in a chart area named "Default".

Visual Basic Copy Code
Imports Dundas.Charting.WinControl
...

' Decrement data view one large scrolling unit
chart1.ChartAreas("Default").AxisX.View.Scroll(ScrollType.LargeDecrement)


C# Copy Code
using Dundas.Charting.WinControl;
...

// Decrement data view one large scrolling unit
chart1.ChartAreas["Default"].AxisX.View.Scroll(ScrollType.LargeDecrement);

When a scrollbar is clicked the AxisScrollBarClicked event is raised. When a view size and/or position is changed the AxisViewChanging and AxisViewChanged events are raised (see the Related Events section for further details).

 

Scrollbars

Scrollbars are represented by the AxisScrollBar class, which is exposed via the Axis.ScrollBar property. This AxisScrollBar class controls the appearance of scrollbars, setting such things as the color of arrows and symbols via the LineColor property, the background color of the scrollbar via the BackColor property and which buttons are displayed (e.g. zoomreset button, left/right and up/down buttons, etc.) via the Buttons property.

AxisScrollBar also enables/disables a scrollbar using the Enabled property. However, even if a scrollbar is enabled it may not be displayed since it will only be displayed if the axis that it belongs is displaying an associated data view. To test if a scrollbar is actually visible please use the IsVisible method.

The default position of the scrollbars is within the chart area along the edge of the plotting area. However, there are times that, when automatic positioning is used, the scrollbars may appear to jump around while scrolling. This is the result of the plot position dimensions changing for the new chart view. To overcome this behavior, the PositionInside property can be used to cause the placement of the scrollbars at the edge of the chart area.

Example

The following example enables a scrollbar along the X axis for a chart area named "Default". We only display Small Scrolling buttons (left/right buttons if horizontal scrollbar, or up/down if vertical scrollbar).

Visual Basic Copy Code
Imports Dundas.Charting.WinControl
...

chart1.ChartAreas("Default").AxisX.ScrollBar.Enabled = True
chart1.ChartAreas("Default").AxisX.ScrollBar.PositionInside = False
chart1.ChartAreas("Default").AxisX.ScrollBar.Buttons = ScrollBarButtonStyle.SmallScroll 

C# Copy Code
using Dundas.Charting.WinControl;
...

chart1.ChartAreas["Default"].AxisX.ScrollBar.Enabled = true;
chart1.ChartAreas["Default"].AxisX.ScrollBar.PositionInside = false;
chart1.ChartAreas["Default"].AxisX.ScrollBar.Buttons = ScrollBarButtonStyle.SmallScroll;

Related Events

AxisScrollBarClicked Event

The AxisScrollBarClicked event is raised every time an end-user clicks anywhere within a scrollbar, and can be used to provide custom handling of end-user scrolling. The event handler has two arguments: one with a type of Chart, which provides access to the root chart object, and one of type ScrollBarEventArgs, which has the following properties:

  • ChartArea. Used to get the ChartArea object the event was raised for. The ChartArea.Name property gets the name of the chart area, and other chart area properties can also be set.
  • Axis. Used to determine the Axis object the scrollbar belongs to via the Axis.Type property. Also, other Axis properties can also be set.
  • ButtonType. Used to get the scrollbar element the end-user clicked on.
  • Handled. If set to TRUE the Chart control will not implement default handling of the scrollbar button click after the code in the event finishes execution.
  • the MousePositionX property, which is the X position of the mouse cursor at the time the end-user clicked on the scrollbar element.
  • the MousePositionY property, which is the Y position of the mouse cursor at the time the end-user clicked on the scrollbar element.

 

Example

In this example we override the default behavior when the user clicks on the reset button. Normally clicking on the reset button will result in the previous view being displayed, but using the AxisScrollBarClicked event we reset the view to its original state (i.e. no zooming). We only do this for the X axis of a chart area named "Default".

Visual Basic Copy Code
Imports Dundas.Charting.WinControl
...

Private Sub chart1_AxisScrollBarClicked(ByVal sender As Object, _
ByVal e As Dundas.Charting.WinControl.ScrollBarEventArgs) Handles chart1.AxisScrollBarClicked

        'first check for zoom/reset button being clicked for X axis in chart area named "Default"
        If e.ChartArea.Name = "Default" Then

                If e.Axis.Name = "X axis" Then

                        If e.ButtonType = ScrollBarButtonType.ZoomReset Then

                        ' Reset view to original view (no zooming)
                        e.Axis.View.ZoomReset(0)

                        ' further handling of event is not required
                        e.Handled = true

                        End If

                End If

        End If

End Sub

C# Copy Code
using Dundas.Charting.WinControl;
...

// Note that events in C# should be added via the Events button in the Properties window, so
//   that the necessary code is added to InitializeComponent() 
private void chart1_AxisScrollBarClicked(object sender, Dundas.Charting.WinControl.ScrollBarEventArgs e){

        // First check for zoom/reset button being clicked for X axis in chart area named "Default"
        if(e.ChartArea.Name == "Default")
        {

                if(e.Axis.Name == "X axis")
                {

                        if(e.ButtonType == ScrollBarButtonType.ZoomReset)
                        {

                        // Reset view to original view (no zooming)
                        e.Axis.View.ZoomReset(0);

                        // further handling of event is not required
                        e.Handled = true;

                        }

                }

        }

}


AxisViewChanging and AxisViewChanged Events

The events are raised when the size and/or position of a view changes as a result of end-user interaction. The AxisViewChanged event is raised once after a view is changed, while the AxisViewChanging event is raised just prior to a view being redrawn.

The AxisViewChanging event can be used to restrict the size and/or position of a view, and like the AxisViewChanged event uses two arguments: one of type Chart, which provides access to the root Chart object, and one of type ViewEventArgs, which has the following properties:

  • ChartArea. Used to get the ChartArea object the view is being displayed in. The ChartArea.Name property gets the name of the chart area, and other chart area properties can also be set.
  • Axis. Used to get the Axis object the view is associated with. To determine the type of axis use the Axis.Type property (i.e. X, X2, Y and Y2). Other axis properties can also be set.
  • NewPosition. Represents the new position of a view, and can be changed in the AxisViewChanging event.
  • NewSize. Represents the new size of a view, and can be changed in the AxisViewChanging event.
  • NewSizeType. Represents the unit of measurement for the size of a view, and can be changed in the AxisViewChanging event.

The NewSize or NewPosition parameters may have Double.NaN values, which indicates that the Size or Position was not changed by the end-user. For example, if the NewSize parameter has a Double.NaN value then only the position of the view changed, and not the size (which occurs as a result of scrolling, as opposed to zooming).

Setting both the NewSize and NewPosition parameters to Double.NaN in these events will result in the view being disabled.

Sample Code

In this example we limit the view along the Y axis for a chart area named "Chart Area 1". We assume that the Y axis values are 1, 2, 3, etc., and the user isn't allowed to view any data that has a Y value that is greater than 15.

Visual Basic Copy Code
Imports Dundas.Charting.WinControl
...

Private Sub chart1_AxisViewChanging(ByVal sender As Object, _
ByVal e As Dundas.Charting.WinControl.CursorEventArgs) Handles chart1.AxisViewChanging

        If e.ChartArea.Name = "Chart Area 1" Then

                If e.Axis.Type = AxisName.X Then 

                        If e.NewPosition + e.NewSize > 15 Then e.NewSize = 15 - e.NewPosition

                End If

        End If

End Sub



C# Copy Code
using Dundas.Charting.WinControl;
...

// Note that events in C# should be added via the Events button in the Properties window, so
//   that the necessary code is added to InitializeComponent() 
private void chart1_AxisViewChanging(object sender, Dundas.Charting.WinControl.CursorEventArgs e){

        if(e.ChartArea.Name == "Chart Area 1"){

                if(e.Axis.Type == AxisName.X){

                        if(e.NewPosition + e.NewSize > 15)
                        e.NewSize = 15 - e.NewPosition;

                }

        }

}


 

See Also