Welcome to the Chart FX Interactive Samples and Resource Center

Whether you are just starting with Chart FX or you are an experienced Chart FX developer, here you will find a wealth of documentation and samples that will help you benefit from Chart FX in your development environment.

As an added benefit, this Resource Center not only provides a "Programmer's Guide" reference that discusses interesting Chart FX topics, but also includes the Chart FX API, an Internet Reference specifically catered for Web development and a wealth of actual samples and charts (and code) that you can integrate and test in your applications.

Exporting the code to your application

It is important to note that this application is capable of dynamically producing ASP or VB code that you can use in your projects. To do this, use the following steps:

1. The ChartFX Resource Center allows you to select the type of application you're developing for, between Windows Forms, Web Forms, Smart Device applications, ASP pages or VB6 Desktop applications. It is important that you select the appropriate button, as some features are only available for a particular environment. The interactive samples are also specifically created for Windows Forms, Web Forms, Smart Devices, ASP pages or VB6 Desktop and should be used in the intended development environment to avoid errors. (See location 1)

2. Once your application preference has been selected, the appropriate API reference is loaded. You may select which reference guide to view by selecting the appropriate tab. (See location 2)

3. Once you have selected your desired reference guide, you can navigate to the appropriate sample or topic using the tree control located on the left. (See location 3). It is important to note that you can size the space allotted to the tree control by positioning the mouse next to the right margin of the tree and dragging it to a desired width.

4. The Resource Center samples provide the source code used to create each sample in different programming languages. To view the sample code, simply click the appropriate tab according to the code you are using in your application. (See location 4)

5. The code can then be copied using the "Copy Code" button located next to these tabs. Using this button will copy all the code needed to duplicate the sample to your clipboard, which you can then paste into a project. (See location 5)

Please note samples may provide data or code that is not specific to the sample shown or that you may want to remove once integrated into your application. Each sample separates the relevant code from the cosmetic code by color coding.

Please let us know if this is a valuable resource to you. As always, we strive in providing the best support in the business and we believe tools like this will ultimately ease the coding and integration process.

We hope you enjoy Chart FX as much as we enjoyed developing it for you.

@2005 Software FX, Inc. All Rights Reserved. Chart FX is a registered trademark of Software FX, Inc.
All other names are trademarks or registered trademarks of their respective owners.


Getting Help

There are a variety of different resources available to developers when trying to get help using Chart FX. The largest collection of information supporting the product can be found in the Chart FX Resource Center, which includes the API references, tutorial programmer's guide, an Internet reference guide and samples. Below are some ways to get help for Chart FX:

  • Chart FX Resource Center (API, Tutorial, Internet Reference, Samples)
  • Dynamic Help
  • Intellisense within your IDE
  • Support Web Sites
  • Newsgroups
  • 30-day Free Trial Support
  • Paid Support Account

Chart FX Resource Center

The Chart FX Resource Center is a compilation of information supporting development for Windows Forms, Web Forms and Smart Devices using Chart FX for .NET. Included in the Resource Center are the API references, tutorial programmer's guide, an Internet Reference, and plenty of samples to help you find the answers to your questions.

The API Reference documents the supported classes of Chart FX, describing every property, method and event available in the charting component. If you are looking for a particular feature, the API reference is a good starting point.

The Interactive Samples provides samples and information about topics like passing data, axis handling, tool customization, and much more. The Interactive Samples are designed to allow you to cut and paste code into your projects to quickly produce charts and reduce your learning curve. The samples have also been created in C# and Visual Basic, so you will not have to spend time converting any of the samples.

The Internet Reference is specific to Web Forms development and covers many of the features available only in the Internet version of Chart FX for .NET.

Dynamic Help / IntelliSense

The Chart FX for .NET API references for both Windows Forms and Web Forms have been integrated into the .NET Framework Dynamic Help. This allows you to access Chart FX help files directly from your development environment.

1. Dynamic Help Window
2. Main Help
3. Search/Index Window
4. Search/Index Results Window

By integrating Chart FX help files within Visual Studio .NET, we are able to take advantage of the Dynamic help features by providing immediate context-base assistance while developing within the environment. Whenever you wish to reference additional information, you can select the appropriate link in the Dynamic Help window or just use the F1 hotkey. Other aids that the Chart FX for .NET Dynamic Help integration provides are:

  • Selecting a Chart FX property from the property dialog and pressing F1 will automatically load the corresponding property help page in the Main Help Frame.
  • Filtering allows you to select exactly what information the Dynamic Help references.
  • When a supported property or method is selected in the Code Editor, a tool tip will be displayed with a description of that property or method.
  • When a property is selected in the property dialog, a description of that property can be seen in the description window below the dialog.
  • When the Chart control has focus in the design form, pressing F1 will activate the Dynamic Help specific to the chart.
  • The IntelliSense feature in your IDE can also act as an aid by prompting developers with possible coding options and information. When a function or statement is entered into the Code Editor, its complete syntax and arguments are shown in a ToolTip. In addition, languages that supports early binding display available functions, statements, constants, and other values in a list that you can choose from.

Support Web Sites

Support for Chart FX for .NET is available on the web for free. Support.SoftwareFX.com was designed to help you quickly and easily find the information you need. In this site, you can view knowledgebase articles, sample code, documentation, product updates and other important technical support information. Please be aware that in order to use the support site, you are required to have a Windows-based system with a browser that supports client-side components (both Internet Explorer and Netscape are supported!).

Individual sites have been created specifically for Windows Forms and Web Forms development and can be accessed at the following URL:

http://support.softwarefx.com/cfxnet

SoftwareFX support site:

http://support.softwarefx.com

Newsgroups

Newsgroups are a great way to receive feedback from the Software FX Support Team, as well as other Chart FX developers. The Software FX staff is dedicated to providing the best support possible, so monitoring the Newsgroups is a daily routine, plus access to the Newsgroups is free. You can access the Software FX Newsgroups at:

Newsgroups URL: news://news.softwarefx.com

30 Day Trial and Paid Support Accounts

Registered users of Chart FX for .NET may sign up for a support account online. The account is free for the first 30 days. If you require further assistance after that period, you may renew your support account for a yearly fee. You can create your support account at the following URL:

Account Registration:http://support.softwarefx.com/Accounts

Contact Support

The Technical Support contact information can be found at: http://support.softwarefx.com.


The Chart FX for .NET Design Time Wizard

As an added feature for developers, Chart FX for .NET provides a design time wizard that allows you to easily customize general settings for a myriad of charts with minimal programming effort. The Wizard walks the programmer through a series of steps (in the form of dialogs) to complete the task of building a chart. This helps developers familiarize themselves with properties used to customize particular chart elements and create sophisticated charts without the need of referencing the Chart FX API or Resource Center help pages. With this in mind, the Wizard was designed to provide support for the most commonly used Chart FX properties.

Accessing the Wizard

Developers may access the Chart FX for .NET Wizard in a few different ways:

  • The first time you drop a chart control from the toolbox on a form.
  • Accessing the 'Wizard' option from the right click context menu of the chart control at design time.
  • Clicking the 'Wizard' link below the design time properties dialog when the chart control has the focus.

Setting properties using the Wizard

Creating a chart using the Wizard is easy. The first time the Wizard is activated; all the necessary assemblies are created and may take a moment to start. Once this has completed, the first screen displayed will be the Chart Gallery configuration dialog. From there you will continue to set the chart's color scheme, visual elements and other miscellaneous properties. Located at the bottom of the Wizard are the navigation controls that consist of forward, back, finish and cancel commands. The navigation controls are available on all Wizard dialog pages.

Chart Gallery Dialog - Step 1

The Chart Gallery Dialog allows you to select from a variety of chart types including Bars/Columns, Area, Lines, Bubble, Pie/Doughnut/Pyramid, Scatter, Financial, Surface, Contour and Combination charts. By selecting a particular category from the gallery combo box, the available charts will be displayed in the main frame. You can then select a chart by using the mouse cursor.

There are also options available to filter 2D charts as well as to modify the display style for the available gallery types. You can select between graphical or detailed list styles.

Located in the bottom right corner of the Chart Gallery Dialog is the "Show wizard next time" checkbox used to disable the Wizard. Once you have selected the chart type you can click next to continue.

Note: Please note that the Wizard charts have a set number of points and series. When you pass your data to a selected chart, the appearance may vary based on the actual values.

Color Scheme Dialog - Step 2

The Color Scheme Dialog allows you to select the palette to be applied to the chart. From time to time Chart FX introduces new palettes; so check the latest service pack for new palette updates.

Visual Elements Dialog - Step 3

The Visual Elements Dialog provides a means of including Chart FX Tools as well as cosmetic attributes to charts using the Wizard. Located near the top of the dialog are a series of tabs marked Borders, Legends, Data Views and Gradients. By selecting the appropriate tab, you can assign attributes specific to that chart element.

  • The Borders tab allows you to assign an ImageBorder to your chart. You can also select the border color.
  • The Legends tab allows you to add the series legend box to the chart and control the positioning, alignment and border style attributes.
  • The Data Views tab allows you to add and customize the data editor. Using the supported controls, you can assign position, alignment, border style, interlaced grid, and header attributes.
  • The Gradients tab allows you assign a gradient to the background or series markers in a chart. From the Wizard you can select the gradient type and beginning and ending gradient colors.

Miscellaneous Dialog - Step 4

The Miscellaneous Dialog gives access to title, X Axis, Y Axis and point label properties. Again located near the top of the dial are a series of tabs, which allow customization for these chart elements.

  • The Chart Title tab allows you to set text for the title, configure the alignment of the text, change font and control the dock area of the title relevant to the chart.
  • The X Axis tab allows you to show or hide the axis, assign a title, set a grid, and control label formatting (Angle or Staggered).
  • The Y Axis tab also allows you to show or hide the axis, assign a title, set a grid, and control label formatting. (Decimals or Axis Format)
  • The Point Labels tab allows you to show or hide point labels, control alignment and set label angle.

Note: Please note that none of the properties or settings available via the design time wizard is data-related.

Finishing the Wizard

At any point during the creation of a chart using the Wizard, you may select to finish to apply the current chart to your form. If you do not want the settings configured in the Wizard to be applied to the chart, you can simply select "Cancel" and return to the previous design time development environment.

Disabling the Wizard

When developers have reached the point where the Wizard is no longer needed to assist in creating charts, they can disable the Wizard from automatically running when a chart control is dropped to a form. To disable the Wizard, simply uncheck the "Show wizard next time" checkbox located at the bottom right corner of the Chart Gallery wizard screen. If you need to access the Wizard again, you will need to use the right click menu or link described in the "Accessing the Wizard" section.

Re-entry Capabilities

Re-entry capability refers to the idea that the Wizard remembers the previously configured chart's properties. For example, you create a Radar chart using the Wizard, select finish to apply the selected chart to your form. Once the chart has been applied to the form, you decide that a title should be added to the top of the chart. When you access the Wizard again, your chart will be the first chart available in the Wizard.

The Wizard can also be used after you have started assigning properties using the properties dialog window. Let's say you drop a chart and configure a palette and title. When you open the Wizard, those settings will already be applied to the first available chart in the collection. Below is a screenshot of the Wizard after a radar chart has been created and the Wizard has been reopened.

Design-Time Data

Many of the charts that can be created from the Wizard use random data to populate the chart, however, there are cases when random data will not allow a chart to represent what it was designed to represent correctly. In these cases, Chart FX allows data to be passed through the use of a property called DesignTimeData. Charts designed with the Wizard that rely on fixed data will continue to use the Chart FX fixed data until any data related method (i.e. OpenData or CloseData) is called within the application. This instructs Chart FX for .NET to disregard the fixed data set with the DesignTimeData property and use the data passed by the developer. If a data related method is called but no data is passed, the chart will be populated with random data that may cause undesirable results.

The Chart class supports two design time properties, NSeries and NValues, which control the number of series and points a chart will contain. Normally, when you set these properties at design time, Chart FX calculates the values for those points randomly. However, if you have the DesignTimeData property set, you may not adjust the NSeries and NValues properties because the data determines the number of series and points. You can reset the DesignTimeData by right clicking the property label in the properties dialog and selecting 'Reset' or by removing the configured path from the setting. This will then allow access to the NSeries and NValues properties. Below is a screen shot of resetting the DesignTimeData:

Note: Design Time wizard is not available in Pocket Chart FX for .NET Compact Framework.


What's new in Chart FX for .NET 6.2

New Features

The majority of the new features enabled for Chart FX for .NET 6.2 are related to data analysis. Some of the new features implemented include:

  • Smart Axis Labeling - Chart FX now allows you more control over your axes with improved axis labeling functionality.
  • Data Driven Labeling - Chart FX also offers more dynamic labeling based on data.
  • Flash Support - Chart FX employs the power of Flash! Now you can choose to export your charts in Flash native format.
  • Conditional Attributes - Marker and Axis Labels attributes can now be changed automatically, based on a given condition. Simply setup your conditions at design time or code it as complex as you require.
  • Extended URL Linking Capabilities - The new version of Chart FX for .NET will allow you to configure URL linking from each of the Legend and DataEditor entries.
  • Multiple Panes - Chart FX for .NET 6.2 allows you to render multiple panes within the same chart. Now you can compare multiple unrelated entities which share a Y axis, all on the same chart.
  • Enhanced Annotation Clipping and Positioning - Position the annotation object at your will with new and improved options for attaching, anchoring and clipping.
  • Statistical Analysis - The Chart FX for .NET 6.2 is also compatible with the new Chart FX for .NET Statistical Extension. Chart FX Statistical extends the power of Chart FX by adding statistical analysis capabilities to your charting applications. Chart FX Statistical seamlessly integrates to Visual Studio .NET, providing additional chart types, a myriad of pre-defined statistical studies, new classes for statistical calculations and much more.

**For more information on these topics, please see the appropriate section in the Chart FX for .NET 6.2 Programmer's Guide and Resource Center.

There are many new features that have been added to Chart FX for .NET 6.2. Some of these implementations are enabled in by default, which makes the chart behave differently than the previous Chart FX for .NET version.

Notable Changes for Developers

Highlight Feature
The first of these notable changes is the Highlighting feature. Chart FX now includes a highlighting feature which allows end users to hover over chart elements to highlight them in the chart. This feature is only available for .NET Charts, charts generated as images do not include this functionality.

Although this data analysis feature may be beneficial to many users, some developers may choose not to include this functionality. To disable this default feature, you may set the Enabled property to false using the following line of code programmatically:

' To disable the Highlight Feature
chart1.Highlight.Enabled = False

// To disable the Highlight feature
chart1.Highlight.Enabled = false;

' To disable the Highlight feature
Chart1.Highlight.Enabled = False

' To disable the Highlight feature
Chart1.Highlight.Enabled = False

The Chart FX for .NET API also supports classes which allow developers to fully customize the highlighting action, please check the API and programmer's guide for additional information.

Anti-Aliasing (ClearType detection)
Chart FX for .NET 6.2 now by default uses the system settings of your computer to determine if you have ClearType enabled for your machine. With Windows XP, ClearType delivers improved font display resolution over traditional anti-aliasing. It improves readability on color LCD monitors with a digital interface, such as those in laptops and high-quality flat desktop displays. Readability on CRT screens can also be somewhat improved.

If you do not have ClearType enabled, the default behavior is to display text in the chart without utilizing any anti-aliasing features. If you wish to instruct your charts to use anti-aliasing and disregard the ClearType default, the SmoothFlags property may be used as follows:

'Manually configure the desired anti-aliasing
chart1.SmoothFlags = SmoothFlags.Text Or SmoothFlags.Fill Or SmoothFlags.Border

// Manually configure the desired anti-aliasing
chart1.SmoothFlags = SmoothFlags.Text | SmoothFlags.Fill | SmoothFlags.Border;

' Manually configure the desired anti-aliasing
Chart1.SmoothFlags = SmoothFlags_Text Or SmoothFlags_Fill Or SmoothFlags_Border

' Manually configure the desired anti-aliasing
Chart1.SmoothFlags = SmoothFlags_Text Or SmoothFlags_Fill Or SmoothFlags_Border

Web Forms: Client Side Events
In order for client side events to fire when developing Web Form applications with Chart FX for .NET, the .NET Security Settings must be configured to FULL TRUST for the appropriate zone (the applications is accessed) on the client's computer. Chart FX for .NET 6.2 also requires this configuration on the client's computer for the event to fire. If FULL TRUST is not enabled on the client's machine, an exception will be thrown due to the insufficient rights. This differs from Chart FX for .NET 6.0, as no exception was previously thrown.

New Palettes
Chart FX for .NET now in includes four new palettes:

  • Natural.Sky
  • Natural.Adventure
  • Mesa
  • Vivid

Note: Six additional ImageBorders are also expected to be included in the final release of Chart FX for .NET 6.2.


Migrating CfxNET Projects

Migrating Existing Chart FX for .NET Projects from 6.0 to 6.2

In order to include the new functionality of Chart FX for .NET 6.2 in your existing Chart FX applications, it will be required to update the references to the latest Chart FX assemblies within the project and rebuild.

Developers may manually remove all Chart FX references, re-add the latest assemblies and rebuild their projects to achieve this; however there is also another quick solution. The new assemblies, by default are installed to a new physical location on your local machine, i.e. C:\Program Files\ChartFX for .NET 6.2\bin. By simply modifying a path attribute in the project to point to this new location and rebuilding the project, you can update your applications.

Below are the steps required to update your applications to reference the new assemblies using this second method:

1. First Install the latest build of Chart FX for .NET v. 6.2 on your development machine. Please note it is possible to have multiple versions of Chart FX for .NET installed.

2. Open your existing Chart FX for .NET application in VS.NET.

3. Navigate to Solution Explorer, select the project and Select Properties.

4. Once you have accessed the project properties dialog, select the "References Path" section in the properties. In the main frame, Modify the existing path for the Chart FX references. If there is no path configured, enter the path to the bin folder of the new assemblies, i.e. C:\Program Files\ChartFX for .NET 6.2\bin. Select OK to save.

5. Rebuild your project and your application will be updated using the latest version of Chart FX for .NET.


Obsolete API Members

Chart FX for .NET previosly included old API members from Chart FX Internet and Chart FX Client Server for compatilibity purposes. However, these members have been removed from version 6.2 to streamline the build. These obsolete members have been replaced with new members to support the same functionality. If you are using any of these obsolete members in your applications, you will need to update your applications:

Chart Class Obsolete Members

Axis Class Obsolete Members

UserLegendBoxItem Class Obsolete Members

CommandID Type Obsolete Enumerations


Chart FX for .NET Integration and Deployment

Integrating Chart FX into Windows Forms application

Chart FX for .NET provides an assembly (ChartFX.dll) that has been designed to be integrated into Windows Forms applications only; it supports VB.NET, C# or any other .NET programming language as a coding language.

You will need the following tools to properly use Chart FX for .NET:

  • A .NET Development environment, i.e. Microsoft Visual Studio .NET, Microsoft Visual Basic .NET, Borland C# Builder, etc.
  • .NET Framework

Note: If you are looking to integrate Chart FX into a Web Forms application, please refer to Chart FX for .NET Internet Reference later in this manual. This product provides server-side assemblies for ASP.NET as well as design time components compatible with Borland C# Builder and Visual Studio .NET Web Forms; and special Chart FX assemblies that run inside the browser. Similarly, if you're looking to integrate Chart FX in your Smart Device application, this product provides assemblies that support the .NET Compact Framework. Please refer to the Smart Devices integration later in this manual for further details.

To integrate Chart FX in Visual Studio .NET:

  • Select the Windows Forms Tab
  • Right-click on the Toolbox background
  • Select Customize Toolbox
  • On the Customize Toolbox Dialog, select the ".NET Framework Components" tab
  • Press the "Browse Button"
  • Locate and Select the "ChartFX.dll" assembly on the Chart FX installation directory.

Important Note: Using the Imports "SoftwareFX.ChartFX" statement before any declarations, including Module or Class statements, and before any references to identifiers will allow you to access Chart FX enumerations and classes without qualification. This process will also allow easy code migration when upgrading to other Chart FX versions.

Important Note: If you plan access data through the use of arrays or files within your charting applications, you should also add references to ChartFX.Data.dll assemblies.

To integrate Chart FX in C# Builder:

  • Right-click on the Tool Pallete background
  • Select Customize .NET Components
  • Press the "Select an Assembly..." button
  • Locate and Select the "ChartFX.dll" assembly on the Chart FX installation directory.

Deploying Chart FX with your Windows Forms applications

Chart FX consists of several compiled assemblies that must be redistributed along with your application. This assembly (DLL) does not require registry entries and can be copied to the application's directory.

You have a royalty-free right to redistribute ChartFX.dll with your Windows Forms applications. However, please read carefully and make sure you comply with the Chart FX for .NET License Agreement before deploying your application.

Chart FX runs entirely as managed code within the .NET CLR (Common Language Runtime). It is important to note that .NET controls also create deployment advantages that were not previously possible with COM.

For example,

  • You can run different versions of the application side-by-side with different Chart FX versions.
  • You can also update Chart FX and other controls without closing the application.
  • Because you control whether Chart FX is shared, you can run the application simultaneously with other applications that use Chart FX, without DLL conflicts.

When building a Windows Forms application, your .NET development tool will copy all the assemblies you use to the bin\release folder (you may have named the folders differently). All you need to do to deploy is make sure all the assemblies you are using are copied to the same folder as your EXE, normally these assemblies will be:

  • ChartFX.dll
  • ChartFX.Base.dll
  • ChartFX.Data.dll
  • ChartFX.Borders.dll

For more information on .NET deployment techniques please visit the Microsoft web site.


Web Forms

Chart FX for .NET and Web Forms

Just like Windows Forms, your development environment provides a graphical programming environment for developing web applications that can be viewed in any browser or client device.

The Web Forms paradigm is based on dividing the programming interface into two distinct pieces: the visual component and the logic. If you have worked with tools like Visual Basic or Visual C++, you will recognize this division between the visible portion of a form and the code behind the form that interacts with it.

In Visual Studio .NET and Borland C# Builder, Web Forms pages work as a container for controls you want to display in your web application like text, lists, calendars and charts. The logic for these Web Forms consist of C# or VB.NET or any other .NET code that you create to interact with the page and controls inside the forms. These files are referred to as the "code-behind" files and have an ".aspx.vb" or "aspx.cs" extension. Essentially, Web Forms pages bring to Web applications the familiar model of writing event handlers for events that occur on either the client or the server.

To provide an extension to the programming environment, for example, your IDE features Server Controls that are visible to the Visual Studio .NET design environment (Web Forms) and provide an implementation that makes them available and programmable on the server.

Chart FX for .NET not only provides components that can be integrated into your .NET development tool's Web Forms environment but server components that:

  • Allow the creation and integration of charts that will function correctly in all commonly used browsers, providing widespread reach to a diverse browsing audience.
  • Detect the browser type and automatically take advantage of many of the advanced capabilities in Internet Explorer 5.5 and later versions.
  • Provide a rich object model that supports the type-safe programming capabilities and extended charting capabilities of your web servers.
  • Provide an API based entirely on .NET that allows programmers to implement and run their web applications managed within the .NET CLR - on both the server and the client-side.
  • Work on ASP.NET intricate server architectures like Web Farms, and are optimized for server performance and scalability.
  • Support extended .NET functionality that create unique advantages in areas like chart presentation, security and deployment.

This section will introduce you to the Chart FX for .NET Web Forms server control and basic techniques on integrating this control into your Web Forms applications.

Please note you can also use Chart FX for .NET on "Single Page" web applications, or ASP.NET applications that combine the visual elements and code in the same file (similar to regular ASP files). This topic is covered later in this chapter.

Installing Chart FX for .NET for web development purposes

Before you install Chart FX for .NET, you must have previously installed the following components on your development machine

  • A .NET Development environment, i.e. Borland C# Builder, Microsoft Visual Studio .NET, Microsoft Visual Basic .NET, etc.
  • .NET Framework
  • Internet Information Server (IIS)

Chart FX for .NET provides 2 distinct installation files:

1: Development Seat: that will copy and configure all the necessary files, including documentation and samples, on the machine that has been provisioned with an appropriate development environment. This installation will setup all the necessary assemblies so you can integrate charts and debug your Web Forms and Windows Forms (if applicable) projects.
Please note, a Chart FX test server assembly will be configured on your local machine so you can test web applications before they are deployed to a production server.

2: Production Server: that will copy and configure all the necessary files and components on your production or "live" server to respond to ASP.NET pages that display charts. Please note, this setup file should not be used on the machines that are used for development purposes.

Important Licensing Information: Please note some of the Chart FX for .NET assemblies have restricted distribution capabilities. So please make sure you read and abide by the Chart FX for .NET License Agreement before installing, using or deploying assemblies on multiple servers or development machines.

Integrating Chart FX for .NET into a VS.NET Web Forms Project

Integrating Chart FX into a Web Forms project is very similar to integrating Chart FX in Windows Forms applications. Just do the following:

  • 1: Create a New Web Forms project in Visual Studio .NET
  • 2: Select the Web Forms Tab.
  • 3: Right-click on the Toolbox background.
  • 4: Select Customize Toolbox.
  • 5: On the Customize Toolbox Dialog, select the ".NET Framework Components" tab.
  • 6: Press the "Browse" Button.
  • 7: Locate and Select the "ChartFX.Internet.dll" assembly on the Chart FX bin directory.

Please note the "Web Forms" tab on the Toolbox will not be visible unless you are positioned in the .aspx file (or Web Form). So please make sure you are positioned in the right section within your project before customizing the Toolbox. As an alternative method, you can use the "Tools - Customize Toolbox" option from the Visual Studio .NET toolbar.

Important Note: If you plan to access data through the use of arrays or files within your charting applications, you should also add references to the ChartFX.Data.dll assemblies.

Once the control has been added to the Toolbox you can simply Drag and Drop the control in a Web Forms application as depicted in the following figure:

Integrating Chart FX for .NET into a Borland C# Builder Web Forms Project

  • Right-click on the Tool Pallete background
  • Select Customize .NET Components
  • Press the "Select an Assembly..." button
  • Locate and Select the "ChartFX.Internet.dll" assembly at the Chart FX installation directory.

The Web Forms page works as a container for the charts and other design elements. The Logic is then added in a separate file ("aspx.vb" or "aspx.cs") from the user interface file. This file is referred to as the "code-behind" file. The code-behind class files for all Web Forms pages in a project are compiled into the project dynamic-link library (.dll). The first time a user browses to the .aspx page, ASP.NET automatically generates a .NET class file that represents the page, and compiles it to a second .dll file.

When a user requests the web page URL, the .dll files run on the server and dynamically produce the chart and other HTML output for your page.


ASPX Pages

While Web Forms introduces a new programming model for web applications built around server-side controls, many programmers will still prefer to use and code in ASP.NET in the same way ASP applications are built today; that is combining ASP.NET and HTML code in a single file.

Unfortunately, most IDE's are oriented toward the two-file, code-behind model, and there is limited support for single-file pages. Among the limitations we can mention:

  • You cannot directly create a single-file Web Forms page in most IDE's. To create a single-file page, you must initially create it as text file and then change its extension to .aspx.
  • You cannot add non-visual components to the page (such as data components) by dragging them from the Toolbox, because the Web Forms designer will not persist them in the page. Instead you should add such components in code.
  • You write code in HTML view, not in the Code Editor.
  • When you are writing code, IntelliSense is not supported - this means you do not get syntax checks or statement completion, tabbing or code formatting.
  • You must bind events to event handlers manually. For single-file Web Forms pages, your IDE does not support double-clicking to create the handler for a control's default event, nor the dropdown lists of classes and events in the Code Editor.
  • Some debugging features are not supported.
  • Because the code in the page is not compiled into the project assembly, compile-time errors are not caught until the page runs.
  • You must create Imports and declarations manually in the .aspx file.

Nevertheless, a single-file page has the advantage that it can be easier to deploy, since the source code is deployed along with the Web Forms page. Essentially, the code is physically in the .aspx file (The user does not see the code - only the results rendered when the page runs are sent to the user).

Integrating a chart into a single .aspx file is as simple as creating and instantiating the chart object, setting the desired chart properties and finally invoking a method (GetHtmlTag or GetHtmlData) that allows the Chart FX server component to generate the appropriate HTML output (images or active components) supported by the browser posting the page request.

The following code is an example of how a simple chart can be included in a single-file .aspx application:

                <%@ Page Language="C#" %>

                <%@ Import Namespace="SoftwareFX.ChartFX.Internet.Server"%>

                <%@ Import Namespace="System.Drawing"%>

                Welcome to my first .aspx page that contains a chart:

                <%

                Chart Chart1 = new Chart(this);

                // Change the Gallery Type to Lines

                Chart1.Gallery = SoftwareFX.ChartFX.Gallery.Lines;

                // Change the background color

                Chart1.BackColor = Color.FromArgb(102,153,255);

                // Change the marker shape to Rectangles

                Chart1.MarkerShape = SoftwareFX.ChartFX.MarkerShape.Rect;

                // Generate a chart of 500x350 pixels

                %>

                <%= Chart1.GetHtmlTag("500","350") %>

                <%@ Page Language="vb" %>

                <%@ Import Namespace="SoftwareFX.ChartFX.Internet.Server"%>

                <%@ Import Namespace="System.Drawing"%>

                Welcome to my first .aspx page that contains a chart:

                <%

                Dim Chart1 As Chart

                Chart1 = New Chart(Me)

                ' Change the Gallery Type to Lines

                Chart1.Gallery = SoftwareFX.ChartFX.Gallery.Lines

                ' Change the background color

                Chart1.BackColor = Color.FromArgb(102,153,255)

                ' Change the marker shape to Rectangles

                Chart1.MarkerShape = SoftwareFX.ChartFX.MarkerShape.Rect

                ' Generate a chart of 500x350 pixels

                %>

                <%= Chart1.GetHtmlTag("500","350")%>

Notes:

  • Please use the Chart FX for .NET API Reference for more information on properties and methods that can be applied to the Chart object. Also note that each chart contains an ID that uniquely identifies each chart in the .aspx file. You can use this ID to set properties to different charts contained in the same .aspx file.
  • The chart displayed above will display random data. For more information on how to populate the chart from a database or any other data source please refer to "Passing Data" in this manual.
  • Please be sure to include the Imports statements, as they are necessary to access the Chart FX enumerations without qualification. Similarly the System.Drawing Import statement is necessary to access system resources like colors and fonts.
  • Don't forget to check out Interactive Tutorial and Samples, and the Chart FX for .NET support site at support.softwarefx.com.


Pocket Chart FX for .Net Integration, Deployment and Licensing

What is Pocket Chart FX for .NET?

Pocket Chart FX for .NET is the member of the Chart FX family of products specifically designed to integrate with your Smart Device applications. It supports the .NET Compact Framework, and is adapted to the reduced resolution and memory availability of mobile devices. Therefore, not all the features of Chart FX for .NET are included in Pocket Chart FX but only those which make the most sense considering the device's restrictions. Since many features are common across all products, we have marked with a footnote those not available in Pocket Chart FX, to make documentation clearer and easier to comprehend. In the API reference, we identify the members compatible with Pocket Chart FX using the standard formatting used by Visual Studio .NET.

Integrating Pocket Chart FX for .NET into Smart Device application

Pocket Chart FX for .NET provides two assemblies, one for design time integration and one for run time execution:

  • ChartFX.CF.Designer.dll: this assembly is used to provide design-time integration with Visual Studio .NET 2003 (Note: Visual Studio 2002 does not support Smart Device applications). This assembly must reside in the following folder inside the Visual Studio installation directory: <VS.NET install dir>\CompactFrameworkSDK\v1.0.5000\Windows CE\Designer.
  • ChartFX.CF.dll: this is the run-time assembly that may be deployed with your application. This assembly must also reside in the Windows CE subfolder within Visual Studio .NET: <VS.NET install dir>\CompactFrameworkSDK\v1.0.5000\Windows CE. A successful installation procedure will copy both files to their respective locations.

Integrating Pocket Chart FX for .NET into a Smart Device application is as simple as adding Chart FX for .NET to a Windows or Web Form. Here are the steps required to complete the process:

  • From the New Project menu, select Smart Device application.
  • In most cases, the installer will create a Chart FX tab in your VS.NET toolbox containing the Pocket Chart icon. In some circumstances, such as when Chart FX is installed while Visual Studio is running, the tab and icon are not integrated automatically into the IDE. If this is the case, you must manually add the icon to the toolbox following the next two steps.
  • Right click the toolbox and select Add/Remove Items.
  • Navigate to ChartFX.CF.Designer.dll and add it to the toolbox.
  • Drop a chart onto the form; notice that a reference has been added for you.
  • Select Emulator or Device as your deployment target.

At this point, you can build or debug your Smart Device application as you would with any other Visual Studio project.

Note: By including the "SoftwareFX.ChartFX.CF" namespace you will be able to access Pocket Chart FX enumerations and classes without having to fully qualify them. This will also allow easy code migration when upgrading to other Pocket Chart FX versions.

Licensing and Deploying Pocket Chart FX for .NET with your Smart Device application

Pocket Chart FX for .NET consists of a single assembly called ChartFX.CF.dll that must be deployed with your application. This assembly is deployed automatically by Visual Studio .NET to the selected deployment device. If you're deploying to a real device rather than an emulator you will need to have Microsoft's ActiveSync installed.

Pocket Chart FX for .NET requires a valid license in order to run on a device (you don't need a license to deploy it to an emulator). The license is a string provided to you with your purchase of one or more deployment licenses of Pocket Chart FX for .NET. Once you have obtained your license string, you must add the following code to your application, prior to the creation of the chart, in the InitializeComponent function:

SoftwareFX.ChartFX.CF.Chart.SetLicenseString("<Your license string>")

Software FX offers diverse deployment packages you can purchase. If you're deploying your application to a large number of devices you may qualify for an OEM agreement with volume discounts. Please contact Software FX at sales@softwarefx.com for further details or to obtain your license string.


Gallery Overview

In many scenarios, developers require their charting applications to include a variety of different chart types when displaying data. Depending on the type of data they are graphically displaying the best chart type could vary. Chart FX recognizes this and provides one of the most complete libraries of chart types available. These chart types may be set using the Gallery property of the Chart and Series objects.

The following chart galleries are supported by the core Chart FX component:

  • Area
  • Bar
  • Bubble
  • CandleStick
  • Contour
  • Cube
  • Curve (*)
  • CurveArea (*)
  • Doughnut (*)
  • Gantt (**)
  • HiLowClose
  • Lines
  • OpenHiLowClose
  • Pareto
  • Pie (**)
  • Pyramid (*)
  • Radar
  • Scatter
  • Step
  • Surface (*)

Additionally, the Chart FX Extensions provide even more chart galleries. Specifically, using the Maps extension developers can incorporate SVG files to be used as the map source. This allows for infinite possibilities considering that developers may even create their own custom SVG's to be imported. Please see the Chart FX Extensions for more information.

By default, Chart FX will produce a Bar chart populated with random data. When a developer passes a data to the chart using either the API or a supported data provider, the values plotted will represent the values passed. The ability to change the gallery is available to end users through the context menus and toolbars, however, this feature is not available when generating images in Chart FX Internet.

Developers can modify the gallery using either the design time property dialog of their development environment or programmatically using the Gallery property. To set the chart to a Pie chart, the following code may be used:

' Set the Gallery to Pie Globally
Chart1.Gallery = Gallery.Pie

// Set the Gallery to Pie Globally
chart1.Gallery = Gallery.Pie;

' Set the Gallery to Pie Globally
Chart1.Gallery = Gallery_Pie

' Set the Gallery to Pie Globally
Chart1.Gallery = Gallery_Pie

Combination Charts

Not only does Chart FX support a myriad of galleries, but they may also be used in combination by employing the Gallery property of the Series object. Applying this property to a specific series will create a multiple type chart, where different Chart Types can be combined in the same chart. For example, if you initially created a bar chart with 3 series, you can convert the first series to a line chart as follows:

' Set the 1st Series to the Line Gallery
chart1.Series(0).Gallery = Gallery.Lines

// Set the 1st Series to the Line Gallery
chart1.Series[0].Gallery = Gallery.Lines;

' Set the 1st Series to the Line Gallery
Chart1.Series(0).Gallery = Gallery_Lines

' Set the 1st Series to the Line Gallery
Chart1.Series(0).Gallery = Gallery_Lines

You must be careful of the galleries selected to combine, as not all combinations will produce desirable results. For example, combining a chart that does not have numerical axis (e.g. Pie Chart) with a chart that has a numerical axis (e.g. Line Chart) will produce a chart that can't be read by the end user.

A rule of thumb is that you can combine axis charts with similar types and non-axis charts with similar types, as follows:

  • Axis Charts: Lines, Bar, Curve, Scatter, Area, Step, HiLowClose, Cube, Bubble, CandleStick, CurveArea.
  • Non-axis charts: Pie, Radar, Polar, Doughnut, Pyramid.
  • Note: Gantt, Surface and Contour can't be combined with other chart types.

Another important issue to keep in mind when creating combination charts is the number of series each chart type requires to properly plot the data. For example, an Open-Hi-Lo-Close chart requires 4 consecutive series to properly plot the data, so if you want to combine this chart type with a line chart, the series containing the data for the line chart must be either the first or the last series in the data set.

The GalleryObj

The GalleryObj object is used to apply additional properties to selected galleries. For example, when you obtain the GalleryObj of a Pie chart, you can set shadows, configure exploding pie slices, etc. The use of additional galleryobj classes is a feature supported by many but not all gallery types. Please see the GalleryObj object in the Chart FX API for all the supported chart types.


Bubble Charts

Bubble Charts without X Coordinate

A Bubble chart compares a set of two values with one of the values specifying the size of the bubble marker, and the second value specifying the location in Y axis where the bubble center is painted.

To pass data simply set a chart with two data series and set Bubble to the Gallery property as follows:

Chart1.Gallery = Gallery.Bubble
Chart1.OpenData(COD.Values, 2, 5)
For j = 0 To 4
   'Set the series that contains the y value for the bubble marker
   Chart1.Value(0,j) = 'Bubble Y Value
   'Set the series that contains the bubble size
   Chart1.Value(1,j) = ' Bubble Size
Next j
Chart1.CloseData(COD.Values)

chart1.Gallery = Gallery.Bubble;
chart1.OpenData(COD.Values, 2, 5);
for(int j=0;j<=4;j++) {
   // Set the series that contains the y value for the bubble marker
   chart1.Value[0,j] = // Bubble Y Value;
   //Set the series that contains the bubble size
   chart1.Value[1,j] = // Bubble Size;
}
chart1.CloseData(COD.Values);

Chart1.Gallery = Gallery_Bubble
Chart1.OpenData COD_Values, 2, 5
For j = 0 To 4
   ' Set the series that contains the y value for the bubble marker
   Chart1.Value(0, j) = ' Bubble Y Value
   'Set the series that contains the bubble size
   Chart1.Value(1, j) = ' Bubble size
Next
Chart1.CloseData COD_Values

Chart1.Gallery = Gallery_Bubble
Chart1.OpenData COD_Values, 2, 5
For j = 0 To 4
   ' Set the series that contains the y value for the bubble marker
   Chart1.Value(0, j) = ' Bubble Y Value
   'Set the series that contains the bubble size
   Chart1.Value(1, j) = ' Bubble size
Next
Chart1.CloseData COD_Values

After setting these values the bubble chart should look like:

Using a secondary Y-axis to control the size of the bubble

In some cases, the difference in the values used as Y Value and Bubble size is too big to produce a good chart. For example, if we take the previous example, and we divide the second series by 10, we will get a chart like this:

Assigning the second series to an extra Y-axis, will allow you to work with a different scale and control the bubble size:

Note: showing the secondary Y-axis is optional.

Bubble charts with an X Coordinate

These bubble charts will compare a set of three values with one of the values specifying the size of the bubble marker. Basically, these bubble charts are similar to an XY Plot, where the bubble position is defined by two coordinates (x,y) and a third coordinate that specifies the size of the bubble.

To pass data you must open an additional communications channel to specify the x coordinate with the XValue property, as follows:

Chart1.Gallery = Gallery.Bubble

Chart1.OpenData(COD.Values, 2, 5)
Chart1.OpenData(COD.XValues, 1, 5)
For j = 0 To 4
     'Set the series that contains the y value for the bubble marker
     Chart1.Value(0,j) = 'Bubble Y Value
     'Set the x value for the bubble marker
     Chart1.XValue(0,j) = 'Bubble X Value
     'Set the series that contains the bubble size
     Chart1.Value(1,j) = ' Bubble Size
Next j

Chart1.CloseData(COD.Values)
Chart1.CloseData(COD.XValues)

chart1.Gallery = Gallery.Bubble;

chart1.OpenData(COD.Values, 2, 5);
chart1.OpenData(COD.XValues, 1, 5);
for(int j=0;j<=4;j++) {
   // Set the series that contains the y value for the bubble marker
   chart1.Value[0,j] = // Bubble Y Value;
   //Set the x value for the bubble marker
   chart1.XValue[0,j] = // Bubble X Value
   //Set the series that contains the bubble size
   chart1.Value[1,j] = // Bubble Size;
}

chart1.CloseData(COD.Values);
chart1.CloseData(COD.XValues);

Chart1.Gallery = Gallery_Bubble

Chart1.OpenData COD_Values, 2, 5
Chart1.OpenData COD_XValues, 1, 5
For j = 0 To 4
   ' Set the series that contains the y value for the bubble marker
   Chart1.Value(0, j) = ' Bubble Y Value
   ' Set the series that contains the x value for the bubble marker
   Chart1.XValue(0, j) = ' Bubble X Value
   'Set the series that contains the bubble size
   Chart1.Value(1, j) = ' Bubble size
Next

Chart1.CloseData COD_Values
Chart1.CloseData COD_XValues

Chart1.Gallery = Gallery_Bubble
Chart1.OpenData COD_Values, 2, 5
Chart1.OpenData COD_XValues, 1, 5
For j = 0 To 4
   ' Set the series that contains the y value for the bubble marker
   Chart1.Value(0, j) = ' Bubble Y Value
   ' Set the series that contains the x value for the bubble marker
   Chart1.XValue(0, j) = ' Bubble X Value
   'Set the series that contains the bubble size
   Chart1.Value(1, j) = ' Bubble size
Next
Chart1.CloseData COD_Values
Chart1.CloseData COD_XValues

For this type of chart, the bubble is not restricted to a specific x coordinate but can be painted anywhere in the X Axis (numerical axis) as described in the XY Plot chapter.

The Volume Property Effect

When creating bubble charts, you must be aware that the Volume property has a specific effect on the way bubble charts are displayed as the Size will be divided by the setting in the Volume property.

For example, if the Volume property is set to 50, it means that Chart FX will force the marker to occupy 1/2 of the space allotted. When you set the bubble size to 100, you would expect the bubble to occupy the entire space allotted; however in this case the bubble will only occupy 1/2 of the space allotted. Similarly, if the Volume is set to 50 and the bubble size is 50, the bubble will occupy 1/4 of the space allotted.


Scatter & XY Plots

An XY Plot is a chart that shows the relationship or degree of relationship between numeric values in several series, or plots two groups of numbers as one series of x,y coordinates.

Because each point in an XY Plot is defined by two coordinates (x, y), you must make additional calls to be able to pass numeric data accordingly.

Passing Data to a scatter plot with the Value and XValue properties

The only special case when passing data to an XY Plot is that you're going to make two OpenData method calls (one with COD.Values or y coordinate and another one with COD.XValues or x coordinate ) and finally use the Value property to assign the appropriate y values and the XValue property to assign the x values of each point in the chart. The source code should look as follows:

' Open the VALUES channel specifying "nSeries" Series and "nPoints" Points
Chart1.OpenData(COD.Values, nSeries, nPoints)
Chart1.OpenData(COD.XValues, nSeries, nPoints)

' Code to set the data
For i = 0 To nSeries - 1
   For j = 0 To nPoints - 1
      Chart1.Value(i, j) = Y Coordinate Value
      Chart1.XValue(i, j) = X Coordinate value
   Next j
Next i

' Close the VALUES and XVALUES channels
Chart1.CloseData(COD.Values)
Chart1.CloseData(COD.XValues)

// Open the VALUES channel specifying "nSeries" Series and "nPoints" Points
chart1.OpenData(COD.Values, nSeries, nPoints);
chart1.OpenData(COD.XValues, nSeries, nPoints);

// Code to set the data
for(int i=0;i<nSeries;i++)
   for(int j=0;j<nPoints;j++) {
      chart1.Value[i, j] = Y Coordinate Value;
      chart1.XValue[i, j] = X Coordinate value;
   }

// Close the VALUES and XVALUES channels
chart1.CloseData(COD.Values);
chart1.CloseData(COD.XValues);

' Open the VALUES channel specifying "nSeries" Series and "nPoints" Points
Chart1.OpenData COD_Values, nSeries, nPoints
Chart1.OpenData COD_XValues, nSeries, nPoints

' Code to set the data
For i = 0 To (nSeries - 1)
   For j = 0 To (nPoints - 1)
       Chart1.Value(i, j) = 5
       Chart1.XValue(i, j) = 5
   Next
Next

' Close the VALUES and XVALUES channels
Chart1.CloseData COD_Values
Chart1.CloseData COD_XValues

' Open the VALUES channel specifying "nSeries" Series and "nPoints" Points
Chart1.OpenData COD_Values, nSeries, nPoints
Chart1.OpenData COD_XValues, nSeries, nPoints
' Code to set the data
For i = 0 To (nSeries - 1)
   For j = 0 To (nPoints - 1)
       Chart1.Value(i, j) = 5
       Chart1.XValue(i, j) = 5
   Next
Next
' Close the VALUES and XVALUES channels
Chart1.CloseData COD_Values
Chart1.CloseData COD_XValues

Please remember that in an XY Plot chart the X-axis becomes a numerical (not a categorical) axis that you can customize with the Axis object properties. This means that instead of legends you will be setting scales, min, max and other numerical values to the X-axis.

XY Plots - Frequently Asked Questions

Which Chart Types are supported as XY Plots?

Although the most common use for XY Plots are Scatter charts (or Point charts) , Chart FX allows you to change to the following chart types when you set data values as x,y coordinates: Line, Curve, Area, Step Lines, Surface, Bubble, Contour and Curve Area.

This means that if you want an XY Plot to show connected lines all you need to do is change the Gallery property to Lines.

How can I instruct a DataSet that I'm creating a scatter plot?

Normally, when a chart is bound to a DataSet or if you use a Data Command or are reading from a file (text or XML) to retrieve data and populate the chart, Chart FX will assume that you want to create a regular chart type and not an XY Plot. This means that if you are connecting to a database that contains X and Y coordinates for an XY Plot, Chart FX by default will create a chart with two series instead of an XY Plot.

This default behavior can be overwritten using the DataType property. For example, if you have a SQL Statement like:

SELECT YValue,XValue FROM MyTable

SELECT YValue,XValue FROM MyTable;

SELECT YValue,XValue FROM MyTable

SELECT YValue,XValue FROM MyTable

You can set the DataType property as follows:

Chart1.DataSourceSettings.DataType(0) = DataType.Value
Chart1.DataSourceSettings.DataType(1) = DataType.XValue

chart1.DataSourceSettings.DataType[0] = DataType.Value;
chart1.DataSourceSettings.DataType[1] = DataType.XValue;

Chart1.DataSourceSettings.DataType(0) = DataType_Value
Chart1.DataSourceSettings.DataType(1) = DataType_XValue

Chart1.DataSourceSettings.DataType.Item(0) = DataType_Value
Chart1.DataSourceSettings.DataType.Item(1) = DataType_XValue

This will force Chart FX to assign the information appropriately for the XYPlot.

Important Note: The DataType property must be set before you assign the DataSource property to the chart control.

Can I force lines to display the same color as point markers?

Yes, you may use the TypeMask property to force Chart FX to display lines in the same color as the point markers instead of black, as follows:

Chart1.TypeMask = Chart1.TypeMask Or ChartType.ColorLine

chart1.TypeMask = chart1.TypeMask | ChartType.ColorLine;

Chart1.TypeMask = Chart1.TypeMask Or ChartType_ColorLine

Chart1.TypeMask = Chart1.TypeMask Or ChartType_ColorLine

Can I use different point markers in a scatter plot?

Yes, please refer to the MarkerShape property supported by the SeriesAttributes and PointAttibutes objects.

Can I highlight points in a scatter chart? Say for example, I have a certain limit I want to control and highlight points that plot above that limit.

The answer to this question not only applies to scatter charts,but all types of charts in Chart FX. You have two options:

1) Use Chart FX "Constant Lines and Color Stripes" feature to highlight the limit or range, respectively.

2) You may change the color of the points that plot above that limit. If this is what you want, you can force Chart FX to assign different colors for each point in the chart. The code should look like:

totSeries = Chart1.NSeries
totValues = Chart1.NValues

Dim redPoints As New PointAttributes(Chart1)
redPoints.Color = Color.Red

Dim bluePoints As New PointAttributes(Chart1)
bluePoints.Color = Color.Blue

For i = 0 To totSeries - 1
   For j = 0 To (totValues - 1)
      If (Chart1.Value(i, j) >= myLimit) Then
         'Red to the points that plot above the limit
         Chart1.Point(i, j) = redPoints
      Else
         ' Blue color to the points that plot inside the limit
         Chart1.Point(i, j) = bluePoints
      End If
   Next j
Next i

int totSeries = chart1.NSeries;
int totValues = chart1.NValues;

PointAttributes redPoints = new PointAttributes(chart1);
redPoints.Color = Color.Red;

PointAttributes bluePoints = new PointAttributes(chart1);
bluePoints.Color = Color.Blue;

for(int i=0;i<totSeries;i++)
   for(int j=0;j<totValues;j++)
      if (chart1.Value[i, j] >= myLimit) {
         //Red to the points that plot above the limit
         chart1.Point[i, j] = redPoints;
      }
      else {
         // Blue color to the points that plot inside the limit
         chart1.Point[i, j] = bluePoints;
      }

Dim totSeries
totSeries = Chart1.NSeries
Dim totValues
totValues = Chart1.NValues

Dim redPoints
Set redPoints = Server.CreateObject("ChartFX.ASP.PointAttributes")
redPoints.Color = RGB(255,0,0)
Dim bluePoints
Set bluePoints = Server.CreateObject("ChartFX.ASP.PointAttributes")
bluePoints.Color = RGB(0,0,255)

For i = 0 To (totSeries - 1)
   For j = 0 To (totValues - 1)
      If (chart1.Value(i, j) >= CDbl(myLimit)) Then
         'Red to the points that plot above the limit
         Chart1.Point(i, j) = redPoints
      Else
         ' Blue color to the points that plot inside the limit
         Chart1.Point(i, j) = bluePoints
      End If
   Next
Next

Dim totSeries
totSeries = Chart1.NSeries
Dim totValues
totValues = Chart1.NValues
Dim redPoints as PointAttributes
Set redPoints = New PointAttributes
redPoints.Color = RGB(255,0,0)
Dim bluePoints as PointAttributes
Set bluePoints = New PointAttributes
bluePoints.Color = RGB(0,0,255)
For i = 0 To (totSeries - 1)
   For j = 0 To (totValues - 1)
      If (chart1.Value(i, j) >= CDbl(myLimit)) Then
         'Red to the points that plot above the limit
         Chart1.Point(i, j) = redPoints
      Else
         ' Blue color to the points that plot inside the limit
         Chart1.Point(i, j) = bluePoints
      End If
   Next
Next


Financial Charts

As part of the standard chart types, Chart FX provides support for three different types of financial charts: Hi-Low-Close, Open-Hi-Low-Close and Candlestick charts. Financial charts also provide support for Multi-Gallery charts, so you can plot an Open-Hi-Low-Close combined with a line or a volume (bar) chart. Please refer to a sample later in this section.

The method of passing data to a financial chart is exactly the same as with other charts: opening a communication channel (OpenData method), passing the numerical information and finally closing the communication channel.

Each marker is defined by several values. For a Hi-Low-Close chart you'll need three series and for Open-Hi-Low-Close you will need four. Finally, you'll need to pass special constants in the Value property to instruct Chart FX which numerical values go with the Open, Hi, Low and Close values.

The first step you need to do when plotting a financial chart is to handle the Gallery property either at design or run time to specify the type of chart you'll be handling, as follows:

Chart1.Gallery = Gallery.HiLowClose [ or Gallery.OpenHiLowClose or Gallery.Candlestick ]

chart1.Gallery = Gallery.HiLowClose; [ or Gallery.OpenHiLowClose or Gallery.Candlestick ]

Chart1.Gallery = Gallery_HiLowClose [ or Gallery_OpenHiLowClose or Gallery_Candlestick ]

Chart1.Gallery = Gallery_HiLowClose [ or Gallery_OpenHiLowClose or Gallery_Candlestick ]

To pass data to an Open-Hi-Lo-Close chart you must specify the appropriate constant in the Value property as follows:

' Open the VALUES channel specifying 4 Series (OPEN, HIGH,LOW and CLOSE)
' and "nPoints" Points
Chart1.OpenData(COD.Values, 4, nPoints)

' Code to set the data
For j = 0 To nPoints -1
    Chart1.Value(OHLC.LOW,j) = Low value!
    Chart1.Value(OHLC.OPEN,j) = Open value!
    Chart1.Value(OHLC.CLOSE,j) = Close value!
    Chart1.Value(OHLC.HIGH,j) = High value!
Next j

' Close the VALUES channel
Chart1.CloseData(COD.Values)

// Open the VALUES channel specifying 4 Series (OPEN, HIGH,LOW and CLOSE)
// and "nPoints" Points
chart1.OpenData(COD.Values, 4, nPoints);

// Code to set the data
for(int j=0;j<nPoints;j++) {
    chart1.Value[OHLC.LOW,j] = Low value!;
    chart1.Value[OHLC.OPEN,j] = Open value!;
    chart1.Value[OHLC.CLOSE,j] = Close value!;
    chart1.Value[OHLC.HIGH,j] = High value!;
}

// Close the VALUES channel
chart1.CloseData(COD.Values);

' Open the VALUES channel specifying 4 Series (OPEN, HIGH,LOW and CLOSE)
' and "nPoints" Points
Chart1.OpenData COD_Values, 4, nPoints

' Code to set the data
For j = 0 To (nPoints - 1)
    Chart1.Value(OHLC.LOW, j) = Low value!
    Chart1.Value(OHLC.OPEN, j) = Open value!
    Chart1.Value(OHLC.CLOSE, j) = Close value!
    Chart1.Value(OHLC.HIGH, j) = High value!
Next

' Close the VALUES channel
Chart1.CloseData COD_Values

' Open the VALUES channel specifying 4 Series (OPEN, HIGH,LOW and CLOSE)
' and "nPoints" Points
Chart1.OpenData COD_Values, 4, nPoints
' Code to set the data
For j = 0 To (nPoints - 1)
    Chart1.Value(OHLC.LOW, j) = Low value!
    Chart1.Value(OHLC.OPEN, j) = Open value!
    Chart1.Value(OHLC.CLOSE, j) = Close value!
    Chart1.Value(OHLC.HIGH, j) = High value!
Next
' Close the VALUES channel
Chart1.CloseData COD_Values

MultiType Financial Charts

It is a common practice to combine a financial chart with another chart (i.e. Lines or Bar) to display other relevant information (e.g. Volume Traded). The Gallery property provided by the Series object can be used to achieve this. Another Chart FX feature that can be used with combined financial charts is the double Y-axis because the volume traded moves in a different range of scale than the price of a stock.

In the following sample, we will create a Open-Hi-Low-Close chart with a volume bar chart and associate the volume series with a secondary Y-axis:

' Open the VALUES channel specifying 5 Series (OPEN, HIGH,LOW,CLOSE
' and VOLUME) and "nPoints" Points
Chart1.OpenData(COD.Values, 5, nPoints)

' Code to set the data
For j = 0 To nPoints - 1
   ' First three series contain Hi-Lo-Close Information
   Chart1.Value(OHLC.OPEN,j) = Open value!
   Chart1.Value(OHLC.HIGH,j) = Hi value!
   Chart1.Value(OHLC.LOW,j) = Low value!
   Chart1.Value(OHLC.CLOSE,j) = Close value!
   ' Fifth Series contains Volume information
   Chart1.Value(4,j) = Volume Traded in day!
Next j

' Close the VALUES channel
Chart1.CloseData(COD.Values)

' Now that all data is there, we use the Gallery property in the series
' object to create a bar volume
Dim series As SeriesAttributes = Chart1.Series(4)
series.Gallery = Gallery.Bar

' Assign the volume chart to a secondary y axis
series.YAxis = YAxis.Secondary

// Open the VALUES channel specifying 5 Series (OPEN, HIGH,LOW,CLOSE and VOLUME)
// and "nPoints" Points
chart1.OpenData(COD.Values, 5, nPoints);

// Code to set the data
for(int j=0;j<nPoints;j++) {
    chart1.Value[OHLC.LOW,j] = Low value!;
    chart1.Value[OHLC.OPEN,j] = Open value!;
    chart1.Value[OHLC.CLOSE,j] = Close value!;
    chart1.Value[OHLC.HIGH,j] = High value!;
    //Fifth Series contains Volume information
    chart1.Value(4,j) = Volume Traded in day!
}

// Close the VALUES channel
chart1.CloseData(COD.Values);

// Now that all data is there, we use the Gallery property in the series
// object to create a bar volume
SeriesAttributes series SeriesAttributes = chart1.Series[4];
series.Gallery = Gallery.Bar;

// Assign the volume chart to a secondary y axis
series.YAxis = YAxis.Secondary;

' Open the VALUES channel specifying 4 Series (OPEN, HIGH,LOW,CLOSE and VOLUME)
' and "nPoints" Points
Chart1.OpenData COD_Values, 5, nPoints

' Code to set the data
For j = 0 To (nPoints - 1)
    Chart1.Value(OHLC.LOW, j) = Low value!
    Chart1.Value(OHLC.OPEN, j) = Open value!
    Chart1.Value(OHLC.CLOSE, j) = Close value!
    Chart1.Value(OHLC.HIGH, j) = High value!
Next

' Close the VALUES channel
Chart1.CloseData COD_Values

' Now that all data is there, we use the Gallery property in the series
' object to create a bar volume
Dim Series
Set Series = Chart1.Series(4)
Series.Gallery = Gallery_Bar

' Assign the volume chart to a secondary y axis
Series.YAxis = YAxis_Secondary

' Open the VALUES channel specifying 4 Series (OPEN, HIGH,LOW,CLOSE and VOLUME)
' and "nPoints" Points
Chart1.OpenData COD_Values, 5, nPoints
' Code to set the data
For j = 0 To (nPoints - 1)
    Chart1.Value(OHLC.LOW, j) = Low value!
    Chart1.Value(OHLC.OPEN, j) = Open value!
    Chart1.Value(OHLC.CLOSE, j) = Close value!
    Chart1.Value(OHLC.HIGH, j) = High value!
Next
' Close the VALUES channel
Chart1.CloseData COD_Values
' Now that all data is there, we use the Gallery property in the series
' object to create a bar volume
Dim Series
Set Series = Chart1.Series(4)
Series.Gallery = Gallery_Bar
' Assign the volume chart to a secondary y axis
Series.YAxis = YAxis_Secondary


Surface & Contour Charts

The Surface plot is usually displayed in a 3D representation. The number of points determines the width of the chart while the number of series determines the depth of the chart. For example, if we want to display a 3D surface chart with 10 Points and 10 Points per series with all values set to zero, it would look like:

As depicted in the figure, you must now locate which data points you want to change in order for the chart to start looking like a surface plot. For example, if we change the value of the points and series highlighted in the figure, the chart will look like:

In order to achieve the chart displayed in the figure shown above, your code should look like:

Chart1.Gallery = Gallery.Surface

'Assign 0 values to all points
Chart1.OpenData(COD.Values, 10, 10)
For i = 0 To 9
   For j = 0 To 9
      Chart1.Value(i, j) = 0
   Next j
Next i

'Now change Series 2, Point 2 to a value of 9 (Zero based indexes)
Chart1.Value(1, 1) = 9
'Change Series 5, Point 9 to a value of 20
Chart1.Value(5, 8) = 20
'Change Series 7, Point 5 to a value of 15
Chart1.Value(7, 5) = 15

Chart1.CloseData(COD.Values)

'Add dash lines
Dim mySurface As SoftwareFX.ChartFX.GalleryObj.Surface
mySurface = Chart1.GalleryObj
mySurface.ShowBorders = True
Chart1.LineStyle = Drawing.Drawing2D.DashStyle.Dash

'Set Y axis attributes
Chart1.AxisY.Max = 20
Chart1.AxisY.Min = -20
Chart1.AxisY.Step = 10

'Set visual attributes
Chart1.Chart3D = True
Chart1.View3D = True
Chart1.AngleX = 25
Chart1.AngleY = 40

chart1.Gallery = Gallery.Surface;

//Assign 0 values to all points
chart1.OpenData(COD.Values, 10, 10);
for(int i=0;i<=9;i++)
   for(int j=0;j<=9;j++)
      chart1.Value[i, j] = 0;

// Now change Series 2, Point 2 to a value of 9 [Zero based indexes]
chart1.Value[1, 1] = 9;
// Change Series 5, Point 9 to a value of 20
chart1.Value[5, 8] = 20;
// Change Series 7, Point 5 to a value of 15
chart1.Value[7, 5] = 15;

chart1.CloseData(COD.Values);

// Add dash lines
SoftwareFX.ChartFX.GalleryObj.Surface mySurface = (SoftwareFX.ChartFX.GalleryObj.Surface) chart1.GalleryObj;
mySurface.ShowBorders = true;
chart1.LineStyle = System.Drawing.Drawing2D.DashStyle.Dash;

// Set Y axis attributes
chart1.AxisY.Max = 20;
chart1.AxisY.Min = -20;
chart1.AxisY.Step = 10;

// Set visual attributes
chart1.Chart3D = true;
chart1.View3D = true;
chart1.AngleX = 25;
chart1.AngleY = 40;

Chart1.Gallery = Gallery_Surface

'Assign 0 values to all points
Chart1.OpenData COD_Values, 10, 10
For i = 0 To 9
   For j = 0 To 9
      Chart1.Value(i, j) = 0
   Next
Next

' Now change Series 2, Point 2 to a value of 9 [Zero based indexes]
Chart1.Value(1, 1) = 9
' Change Series 5, Point 9 to a value of 20
Chart1.Value(5, 8) = 20
' Change Series 7, Point 5 to a value of 15
Chart1.Value(7, 5) = 15

Chart1.CloseData COD_Values

' Add dash lines
Dim mySurface
Set mySurface = Chart1.GalleryObj
mySurface.ShowBorders = True
Chart1.LineStyle = DashStyle_Dash

' Set Y axis attributes
Chart1.AxisY.Max = 20
Chart1.AxisY.Min = -20
Chart1.AxisY.Step = 10

' Set visual attributes
Chart1.Chart3D = True
Chart1.View3D = True
Chart1.AngleX = 25
Chart1.AngleY = 40

Chart1.Gallery = Gallery_Surface
'Assign 0 values to all points
Chart1.OpenData COD_Values, 10, 10
For i = 0 To 9
   For j = 0 To 9
      Chart1.Value(i, j) = 0
   Next
Next
' Now change Series 2, Point 2 to a value of 9 [Zero based indexes]
Chart1.Value(1, 1) = 9
' Change Series 5, Point 9 to a value of 20
Chart1.Value(5, 8) = 20
' Change Series 7, Point 5 to a value of 15
Chart1.Value(7, 5) = 15
Chart1.CloseData COD_Values
' Add dash lines
Dim mySurface
Set mySurface = Chart1.GalleryObj
mySurface.ShowBorders = True
Chart1.LineStyle = DashStyle_Dash
' Set Y axis attributes
Chart1.AxisY.Max = 20
Chart1.AxisY.Min = -20
Chart1.AxisY.Step = 10
' Set visual attributes
Chart1.Chart3D = True
Chart1.View3D = True
Chart1.AngleX = 25
Chart1.AngleY = 40

Handling Level Colors

One of the most important settings in a surface plot is the level of detail that the chart contains. Displaying different colors according to the value of each data point increases the detail of the chart. The color will gradually change from the Color of the first series to its AlternateColor.

Notice that although values have been set, the level of detail shown in the chart may not be enough for the scale selected for the Y-axis (-20, 20). What we need is the surface plot to show more colors according to the height of each point.

To achieve this, simply change the step of the primary Y-axis to achieve the level of detail you need in the surface plot. For example, in the figure shown above the step has been set to 10, not allowing the surface to display enough colors. However, changing the Step to 2 as follows will allow greater detail to be displayed:

Chart1.AxisY.Step = 2

chart1.AxisY.Step = 2;

Chart1.AxisY.Step = 2

Chart1.AxisY.Step = 2

An alternative way to do this is by using the axis MinorStep property to get a gradual change in color without modifying axis Step:

Chart1.AxisY.MinorStep = 2

chart1.AxisY.MinorStep = 2;

Chart1.AxisY.MinorStep = 2

Chart1.AxisY.MinorStep = 2

The result can be seen in the next figure.

Automatic Labeling & Scaling

Because most surface and contour chart displays levels, we have included a way to allow automatic point labeling according to a specific scale factor.

Setting the AutoCountourLabels property for the UserLegendBoxObj will automatically assign legends based on the chart Step. When step is not set, the legends will be automatically assigned with a best fit step chosen by Chart FX.

Note: When invoking this method, Chart FX will assign user legends indicating the color for each level in the Contour Plot. So be aware that any user legend you previously had in the chart will be erased when invoking this method.

When you invoke this method as follows:

Chart1.UserLegendBox = True
Chart1.UserLegendBoxObj.AutoContourLabels = True

chart1.UserLegendBox = true;
chart1.UserLegendBoxObj.AutoContourLabels = true;

Chart1.UserLegendBox = True
Chart1.UserLegendBoxObj.AutoContourLabels = True

Chart1.UserLegendBox = True
Chart1.UserLegendBoxObj.AutoContourLabels = True

A contour chart will look like:


Multi-Gallery Charts

One of the most powerful features in Chart FX is the Multi-Gallery chart. Multi-Gallery Charts allow you to specify a different chart type for the series contained in a chart. Not all chart types in Chart FX can be combined to create a Multi-Gallery chart, only a subset of the chart types available in Chart FX can be used with this option.

If you have a chart with more than one series, you can use the Gallery property in the Series object to assign a different chart type to a different series in the chart. For example, if you have a three series chart and you want the first series to be bar, the second series to be curves and the third series to be area, your code should look like:

Chart1.Series(0).Gallery = Gallery.Curve
Chart1.Series(1).Gallery = Gallery.Bar
Chart1.Series(2).Gallery = Gallery.Area

chart1.Series[0].Gallery = Gallery.Curve;
chart1.Series[1].Gallery = Gallery.Bar;
chart1.Series[2].Gallery = Gallery.Area;

Chart1.Series(0).Gallery = Gallery_Curve
Chart1.Series(1).Gallery = Gallery_Bar
Chart1.Series(2).Gallery = Gallery_Area

Chart1.Series(0).Gallery = Gallery_Curve
Chart1.Series(1).Gallery = Gallery_Bar
Chart1.Series(2).Gallery = Gallery_Area

All Multi-Gallery charts provide 2D/3D support rotation capabilities.

It is also important to note that there is also a Gallery property in the Chart object that applies to all series in the chart. So you must be careful to reference the series object when creating Multi-Gallery charts. For example:

' Will apply lines to all series in the chart
Chart1.Gallery = Gallery.Lines

' Will convert the first data series to lines
Chart1.Series(0).Gallery = Gallery.Lines

// Will apply lines to all series in the chart
chart1.Gallery = Gallery.Lines;

// Will convert the first data series to lines
chart1.Series[0].Gallery = Gallery.Lines ;

' Will apply lines to all series in the chart
Chart1.Gallery = Gallery_Lines

' Will convert the first data series to lines
Chart1.Series(0).Gallery = Gallery_Lines

' Will apply lines to all series in the chart
Chart1.Gallery = Gallery_Lines
' Will convert the first data series to lines
Chart1.Series(0).Gallery = Gallery_Lines


Statistical Extension

Chart FX Statistical extends the power of Chart FX by adding statistical analysis capabilities to your charting applications. Chart FX Statistical seamlessly integrates to Visual Studio .NET, providing additional chart types, a myriad of pre-defined statistical studies, new classes for statistical calculations and much more.

Not only does the Statistical Extension provide the developer with a wide variety of pre-defined studies, study groups, calculations and testing algorithms, but also introduces a new library of supported gallery types. The BoxPlot, Histogram, FrequencyPolygon, Ogive and Regression galleries are all supported with the Chart FX for .NET Statistical Extension.

The Statistical Extension allows Chart FX for .NET developers to quickly apply statistical analysis without the task of incorporating complex mathematical algorithms into their code. Simply configure the extension to compute the desired calculations and Chart FX Statistical will generate the deliver the desired chart.

The newly designed Statistical UI allows end users to apply different formulas, view properties and observe relationships between studies. Opacity and color-coding features have also been included to improve readability of the statistical results graphically.

For additional information or evaluation downloads of the Chart FX Extensions product line, please visit the Chart FX Extensions portal located at: www.softwarefx.com/extensions/


Polar Extension

The Chart FX for .NET Polar Extension is a FREE Add-On which complements the core Chart FX for .NET product by allowing developers to create Polar charts. A Polar chart is a circular graph which is used to plot polar coordinates. This chart type is very similar to the Radar gallery chart type, however, the supported members of the Polar Class allow you to create graphs specific for ploting polar coordinates.

To download the Free Chart FX for .NET Polar Extension, please visit the Chart FX Extensions portal located at www.softwarefx.com/extensions/.

The properties of the Polar class allow you to customize the visual attributes of a Polar chart. In order to make the supported members available, you must first create a 'Polar' gallery object:

Dim myPolar As New GalleryObj.Polar()
myPolar.Circular = True
Chart1.GalleryObj = myPolar

GalleryObj.Polar myPolar = new GalleryObj.Polar();
myPolar.Circular = true;
chart1.GalleryObj = myPolar;

Once this has been done, using the newly created object you can assign these special attributes for the Polar gallery in your chart. Please note that in order to access the Polar class, you must add a reference to the ChartFX.Polar.dll assembly to your project. More information and the free downloadable add-on is available from the Chart FX Extensions portal at www.softwarefx.com/extensions/.


Gantt Charts

Gantt charts are commonly used to track activities during time. With little code you can achieve, in Chart FX, a Gantt chart like the following

Setting the Gantt Type

The first step in creating a Gantt style chart is to set the Gallery property with the GANTT chart type as follows:

Chart1.Gallery = Gallery.Gantt

chart1.Gallery = Gallery.Gantt;

Chart1.Gallery = Gallery_Gantt

Chart1.Gallery = Gallery_Gantt

It is important to understand that when you set this style, the axis will be shifted. The X-axis (categorical) draws vertically (left side) and the Y-axis (numerical) draws in the bottom of the chart. This is important to mention as all of the properties that you set regarding the Y-axis will affect the bottom axis and not the left side axis as you would normally expect.

Also, the GANTT type will display horizontal bars in the Plot area.

Passing Data to Gantt Charts

There are two parameters you must pass to a Gantt chart: where the bar begins and where it ends, according to the data type that the Y-axis (bottom) has been set. This means that if you set a Min of 0 and a Max of 200 for the Y-axis, the bars must contain a beginning value and an ending value that are numbers.

On the other hand, if you set the Min and Max to be dates, the value of the bars must be set with dates so they can be represented according to the format of the Y-axis.

The properties involved in passing data to a Gantt chart are the Value property and IniValue property that must be used in conjunction with OpenData and CloseData methods.

The following example shows how you can set values for a Gantt chart with a Y-axis represented in a numerical format. Please note how the Y-axis is set with numerical values for its min and max before sending the data to the chart.

'First set the Min and Max for the Y-axis
Chart1.AxisY.Min = 0
Chart1.AxisY.Max = 200

'Then we can use the Value and IniValue for the Gantt Chart. Let's suppose it has 3 bars
Chart1.OpenData(COD.Values, 1, 3)
Chart1.OpenData(COD.IniValues, 1, 3)

Chart1.IniValue(0, 0) = 10
Chart1.Value(0, 0) = 30
Chart1.IniValue(0, 1) = 40
Chart1.Value(0, 1) = 80
Chart1.IniValue(0, 2) = 100
Chart1.Value(0, 2) = 180

Chart1.CloseData(COD.Values)
Chart1.CloseData(COD.IniValues)

//First set the Min and Max for the Y-axis
chart1.AxisY.Min = 0;
chart1.AxisY.Max = 200

//Then we can use the Value and IniValue for the Gantt Chart. Let's suppose it has 3 bars
chart1.OpenData(COD.Values, 1, 3);
chart1.OpenData(COD.IniValues, 1, 3);

chart1.IniValue[0, 0] = 10;
chart1.Value[0, 0] = 30;
chart1.IniValue[0, 1] = 40;
chart1.Value[0, 1] = 80;
chart1.IniValue[0, 2] = 100;
chart1.Value[0, 2] = 180;

chart1.CloseData(COD.Values);
chart1.CloseData(COD.IniValues);

'First set the Min and Max for the Y-axis
Chart1.AxisY.Min = 0
Chart1.AxisY.Max = 200

'Then we can use the Value and IniValue for the Gantt Chart. Let's suppose it has 3 bars
Chart1.OpenData COD_Values, 1, 3
Chart1.OpenData COD_IniValues, 1, 3

Chart1.IniValue(0, 0) = 10
Chart1.Value(0, 0) = 30
Chart1.IniValue(0, 1) = 40
Chart1.Value(0, 1) = 80
Chart1.IniValue(0, 2) = 100
Chart1.Value(0, 2) = 180

Chart1.CloseData COD_Values
Chart1.CloseData COD_IniValues

'First set the Min and Max for the Y-axis
Chart1.AxisY.Min = 0
Chart1.AxisY.Max = 200
'Then we can use the Value and IniValue for the Gantt Chart. Let's suppose it has 3 bars
Chart1.OpenData COD_Values, 1, 3
Chart1.OpenData COD_IniValues, 1, 3
Chart1.IniValue(0, 0) = 10
Chart1.Value(0, 0) = 30
Chart1.IniValue(0, 1) = 40
Chart1.Value(0, 1) = 80
Chart1.IniValue(0, 2) = 100
Chart1.Value(0, 2) = 180
Chart1.CloseData COD_Values
Chart1.CloseData COD_IniValues

The following example shows how you can set values for a Gantt chart with an axis represented in a date-formatted. Please note how dates are set for the Min and Max in the Y-axis and values set with the Value and the IniValue properties correspond to dates:

'First set the Min and Max for the Y-axis
Chart1.AxisY.Min = DateTime.Today.ToOADate
Chart1.AxisY.Max = DateTime.Today.AddDays(120).ToOADate '3 months

'Then we can use the ValueEX and IniValueEX for the Gantt Chart. Let's suppose it has 3 bars
Chart1.OpenData(COD.Values, 1, 3)
Chart1.OpenData(COD.IniValues, 1, 3)

Chart1.IniValue(0, 0) = DateTime.Today.ToOADate
Chart1.Value(0, 0) = DateTime.Today.AddDays(10).ToOADate
Chart1.IniValue(0, 1) = DateTime.Today.AddDays(30).ToOADate
Chart1.Value(0, 1) = DateTime.Today.AddDays(80).ToOADate
Chart1.IniValue(0, 2) = DateTime.Today.AddDays(90).ToOADate
Chart1.Value(0, 2) = DateTime.Today.AddDays(110).ToOADate

Chart1.CloseData(COD.Values)
Chart1.CloseData(COD.IniValues)

//First set the Min and Max for the Y-axis
chart1.AxisY.Min = DateTime.Today.ToOADate();
chart1.AxisY.Max = DateTime.Today.AddDays(120).ToOADate(); //3 months

//Then we can use the ValueEX and IniValueEX for the Gantt Chart. Let's suppose it has 3 bars
chart1.OpenData(COD.Values, 1, 3);
chart1.OpenData(COD.IniValues, 1, 3);

chart1.IniValue[0, 0] = DateTime.Today.ToOADate();
chart1.Value[0, 0] = DateTime.Today.AddDays(10).ToOADate();
chart1.IniValue[0, 1] = DateTime.Today.AddDays(30).ToOADate();
chart1.Value[0, 1] = DateTime.Today.AddDays(80).ToOADate();
chart1.IniValue[0, 2] = DateTime.Today.AddDays(90).ToOADate();
chart1.Value[0, 2] = DateTime.Today.AddDays(110).ToOADate();

chart1.CloseData(COD.Values);
chart1.CloseData(COD.IniValues);

'First set the Min and Max for the Y-axis
Chart1.AxisY.Min = CDbl(Now)
Chart1.AxisY.Max = CDbl(DateAdd("d",120,Now))  '3 months

'Then we can use the ValueEX and IniValueEX for the Gantt Chart. Let's suppose it has 3 bars
Chart1.OpenData COD_Values, 1, 3
Chart1.OpenData COD_IniValues, 1, 3

Chart1.IniValue(0, 0) = CDbl(Now)
Chart1.Value(0, 0) = CDbl(DateAdd("d",10,Now))
Chart1.IniValue(0, 1) = CDbl(DateAdd("d",30,Now))
Chart1.Value(0, 1) = CDbl(DateAdd("d",80,Now))
Chart1.IniValue(0, 2) = CDbl(DateAdd("d",90,Now))
Chart1.Value(0, 2) = CDbl(DateAdd("d",110,Now))

Chart1.CloseData COD_Values
Chart1.CloseData COD_IniValues

'First set the Min and Max for the Y-axis
Chart1.AxisY.Min = CDbl(Now)
Chart1.AxisY.Max = CDbl(DateAdd("d",120,Now))
'3 months
'Then we can use the ValueEX and IniValueEX for the Gantt Chart. Let's suppose it has 3 bars
Chart1.OpenData COD_Values, 1, 3
Chart1.OpenData COD_IniValues, 1, 3
Chart1.IniValue(0, 0) = CDbl(Now)
Chart1.Value(0, 0) = CDbl(DateAdd("d",10,Now))
Chart1.IniValue(0, 1) = CDbl(DateAdd("d",30,Now))
Chart1.Value(0, 1) = CDbl(DateAdd("d",80,Now))
Chart1.IniValue(0, 2) = CDbl(DateAdd("d",90,Now))
Chart1.Value(0, 2) = CDbl(DateAdd("d",110,Now))
Chart1.CloseData COD_Values
Chart1.CloseData COD_IniValues

When using data binding, you will need to use the DataType property to set the IniValues, as follows:

' DataSet = SELECT Activity, Start, Duration FROM TASKS
Chart1.DataType(0) = DataType.Label
Chart1.DataType(1) = DataType.IniValue
Chart1.DataType(2) = DataType.Value

// DataSet = SELECT Activity, Start, Duration FROM TASKS
chart1.DataType[0] = DataType.Label;
chart1.DataType[1] = DataType.IniValue;
chart1.DataType[2] = DataType.Value;

' ResultSet = SELECT Activity, Start, Duration FROM TASKS
Chart1.DataType(0) = DataType_Label
Chart1.DataType(1) = DataType_IniValue
Chart1.DataType(2) = DataType_Value

' DataSet = SELECT Activity, Start, Duration FROM TASKS
Chart1.DataType.Item(0) = DataType_Label
Chart1.DataType.Item(1) = DataType_IniValue
Chart1.DataType.Item(2) = DataType_Value

More information about DataType can be found on the Passing Data to Chart FX chapter.

But my Y-axis is displayed on the bottom of the chart and I want it on top?

In order to create the chart displayed in the figure shown above, we made use of a secondary Y-axis, where the data series was assigned to the secondary Y-axis and its settings (Min, Max, etc.) while the primary Y-axis Visible property was set to false, as follows:

'First set the Min and Max for the Y-axis
Dim axis As Axis = Chart1.Axis(1)
axis.Min = DateTime.Today.ToOADate
axis.Max = DateTime.Today.AddDays(120).ToOADate '3 months

'Finally the Primary Y-axis is hidden in the chart
Chart1.AxisY.Visible = False

//First set the Min and Max for the Y-axis
Axis axis = chart1.Axis[1];
axis.Min = DateTime.Today.ToOADate();
axis.Max = DateTime.Today.AddDays(120).ToOADate(); //3 months

//Finally the Primary Y-axis is hidden in the chart
chart1.AxisY.Visible = false;

'First set the Min and Max for the Y-axis
Dim axis
Set axis = Chart1.Axis(1)
axis.Min = CDbl(Now)
axis.Max = CDbl(DateAdd("d",120,Now))  '3 months

'Finally the Primary Y-axis is hidden in the chart
Chart1.AxisY.Visible = False

'First set the Min and Max for the Y-axis
Dim axis as Object
Set axis = Chart1.Axis(1)
axis.Min = CDbl(Now)
axis.Max = CDbl(DateAdd("d",120,Now))
'3 months
'Finally the Primary Y-axis is hidden in the chart
Chart1.AxisY.Visible = False

Assigning Activity Labels

Activity labels are set like any other legend in the chart. Using the Legend property or the Label property in the Axis Object.

What about independent colors?

You may change the color of the bars assigning different colors for each point in the chart. The code should look like:

totSeries = Chart1.NSeries
totValues = Chart1.NValues

Dim redPoints As New PointAttributes(Chart1)
redPoints.Color = Color.Red

Dim bluePoints As New PointAttributes(Chart1)
bluePoints.Color = Color.Blue

For i = 0 To totSeries - 1
   For j = 0 To (totValues - 1)
      If (Chart1.Value(i, j) >= myLimit) Then
         'Red to the points that plot above the limit
         Chart1.Point(i, j) = redPoints
      Else
         ' Blue color to the points that plot inside the limit
         Chart1.Point(i, j) = bluePoints
      End If
   Next j
Next i

int totSeries = chart1.NSeries;
int totValues = chart1.NValues;

PointAttributes redPoints = new PointAttributes(chart1);
redPoints.Color = Color.Red;

PointAttributes bluePoints = new PointAttributes(chart1);
bluePoints.Color = Color.Blue;

for(int i=0;i<totSeries;i++)
   for(int j=0;j<totValues;j++)
      if (chart1.Value[i, j] >= myLimit) {
         //Red to the points that plot above the limit
         chart1.Point[i, j] = redPoints;
      }
      else {
         // Blue color to the points that plot inside the limit
         chart1.Point[i, j] = bluePoints;
      }

Dim totSeries
totSeries = Chart1.NSeries
Dim totValues
totValues = Chart1.NValues

Dim redPoints
Set redPoints = Server.CreateObject("ChartFX.ASP.PointAttributes")
redPoints.Color = RGB(255,0,0)
Dim bluePoints
Set bluePoints = Server.CreateObject("ChartFX.ASP.PointAttributes")
bluePoints.Color = RGB(0,0,255)

For i = 0 To (totSeries - 1)
   For j = 0 To (totValues - 1)
      If (Chart1.Value(i, j) >= CDbl(myLimit)) Then
         'Red to the points that plot above the limit
         Chart1.Point(i, j) = redPoints
      Else
         ' Blue color to the points that plot inside the limit
         Chart1.Point(i, j) = bluePoints
      End If
   Next
Next

Dim totSeries
totSeries = Chart1.NSeries
Dim totValues
totValues = Chart1.NValues
Dim redPoints
Set redPoints = New PointAttributes
redPoints.Color = RGB(255,0,0)
Dim bluePoints
Set bluePoints = New PointAttributes
bluePoints.Color = RGB(0,0,255)
For i = 0 To (totSeries - 1)
   For j = 0 To (totValues - 1)
      If (Chart1.Value(i, j) >= CDbl(myLimit)) Then
         'Red to the points that plot above the limit
         Chart1.Point(i, j) = redPoints
      Else
         ' Blue color to the points that plot inside the limit
         Chart1.Point(i, j) = bluePoints
      End If
   Next
Next


MultiStacked Charts

Most charting tools allow you to stack bar and area charts in different modes. Most common are regular stack and 100% stack charts. Not only does Chart FX allow you to stack charts using these common methods, but you can easily achieve MultiStacked charts where different series in the chart can be presented as different groups of stacked bar or area charts.

If you want to stack all series in the chart, you can use the Stacked property as follows:

' Regular stacked
Chart1.Stacked = Stacked.Normal

' or 100% stacked
Chart1.Stacked = Stacked.Stacked100

' Regular stacked
chart1.Stacked = Stacked.Normal;

' or 100% stacked
chart1.Stacked = Stacked.Stacked100;

' Regular stacked
Chart1.Stacked = Stacked_Normal

' or 100% stacked
Chart1.Stacked = Stacked_Stacked100

' Regular stacked
Chart1.Stacked = Stacked_Normal
' or 100% stacked
Chart1.Stacked = Stacked_Stacked100

The stacked property is also exposed by the Series object, with the difference that it will apply to a specific series in the chart. When you manipulate the Stacked property in the Series object you will instruct Chart FX to stack that series on top of the previous one, which must be of a stacked type (area or bar). For example, the following code creates a MultiStacked chart with a curve in front of the different stacked groups:

'Produce 2 bars and 1 curve
Chart1.Series(0).Gallery = Gallery.Bar

Dim series2 As SeriesAttributes = Chart1.Series(1)
series2.Gallery = Gallery.Bar
series2.Stacked = True ' On top of 0
Chart1.Series(2).Gallery = Gallery.Bar

Dim series4 As SeriesAttributes = Chart1.Series(3)
series4.Gallery = Gallery.Bar
series4.Stacked = True ' On top of 2

Dim series5 As SeriesAttributes = Chart1.Series(4)
series5.Gallery = Gallery.Bar
series5.Stacked = True ' On top of 3

Dim series6 As SeriesAttributes = Chart1.Series(5)
series6.Gallery = Gallery.Curve
series6.Color = Color.Black

' Adjust scale
Chart1.RecalcScale()

//Produce 2 bars and 1 curve
chart1.Series[0].Gallery = Gallery.Bar;

SeriesAttributes series2 = chart1.Series[1];
series2.Gallery = Gallery.Bar;
series2.Stacked = true; // On top of 0
chart1.Series[2].Gallery = Gallery.Bar;

SeriesAttributes series4 = chart1.Series[3];
series4.Gallery = Gallery.Bar;
series4.Stacked = true; // On top of 2

SeriesAttributes series5 = chart1.Series[4];
series5.Gallery = Gallery.Bar;
series5.Stacked = true; // On top of 3

SeriesAttributes series6 = chart1.Series[5];
series6.Gallery = Gallery.Curve;
series6.Color = Color.Black;

// Adjust scale
chart1.RecalcScale();

'Produce 2 bars and 1 curve
Chart1.Series(0).Gallery = Gallery_Bar

Dim series2
Set series2 = Chart1.Series(1)
series2.Gallery = Gallery_Bar
series2.Stacked = True  ' On top of 0
chart1.Series(2).Gallery = Gallery_Bar

Dim series4
Set series4 = Chart1.Series(3)
series4.Gallery = Gallery_Bar
series4.Stacked = True  ' On top of 2

Dim series5
Set series5 = Chart1.Series(4)
series5.Gallery = Gallery_Bar
series5.Stacked = True  ' On top of 3

Dim series6
Set series6 = Chart1.Series(5)
series6.Gallery = Gallery_Curve
series6.Color = RGB(0,0,0)

' Adjust scale
Chart1.RecalcScale

'Produce 2 bars and 1 curve
Chart1.Series(0).Gallery = Gallery_Bar
Dim series2 as Object
Set series2 = Chart1.Series(1)
series2.Gallery = Gallery_Bar
series2.Stacked = True
' On top of 0
Chart1.Series(2).Gallery = Gallery_Bar
Dim series4 as Object
Set series4 = Chart1.Series(3)
series4.Gallery = Gallery_Bar
series4.Stacked = True
' On top of 2
Dim series5 as Object
Set series5 = Chart1.Series(4)
series5.Gallery = Gallery_Bar
series5.Stacked = True
' On top of 3
Dim series6 as Object
Set series6 = Chart1.Series(5)
series6.Gallery = Gallery_Curve
series6.Color = RGB(0,0,0)
' Adjust scale
Chart1.RecalcScale

The previous code produces the following chart:


Chart FX Maps Extension

Just like the entire Chart FX for .NET Extensions product line, the Chart FX Maps is an add-on that complements the Chart FX for .NET core. Adding the Maps Extension to your repertoire will enable you to combine cutting edge graphical map representation with the dynamic functionality of Chart FX for .NET.

This new technology addresses the issue of combining vector objects with scripting facilities, and may be integrated into both Windows Forms and WebForms applications using proprietary data supplied by the developer. By providing a full-library of world continents, countries, U.S. states, counties and zip code maps, you can have fully functional map applications in virtually minutes.

Chart FX Maps Extension is a powerful way to integrate geographical maps into your applications, however, keep in mind that the extension supports much more. By creating your own proprietary SVG's, the Maps Extension possibilities are endless.

Chart FX Maps offers powerful features like customizable legend and data views, drill-down capabilities, fully customizable labels, the ability to add custom maps to the library and many more.

For additional information or evaluation downloads of the Chart FX Extensions product line, please visit the Chart FX Extensions portal located at:
www.softwarefx.com/extensions/


Passing Data to Chart FX for .NET Overview

The most basic method of passing data to a chart using Chart FX for .NET is to utilize the built-in API. The Chart FX for .NET API provides properties and methods to load and manipulate data into a chart. However, one of the features of Chart FX for .NET is the ability to read or pass data from many sources. These sources include databases, text files, XML, arrays, collections, and many others.

Passing data from databases and text files is supported by Chart FX's core, however, all the code required to read data from XML, array and collection sources has been isolated in an additional assembly (ChartFX.Data.DLL) allowing Software FX to easily build additional "Chart FX for .NET Data Providers."

By providing an additional assembly exclusively used for data, the programmer can decide when to include or exclude the assembly, thus giving control of what is to be deployed. Although data functionality requires an additional assembly to be deployed as part of your application, it allows Chart FX for .NET to provide easy integration of new data sources, e.g. Active Directory, Grids, OLAP, etc.

In Chart FX, there is no need to loop through data points to populate the charts. If you have a previously filled data array, just pass it to Chart FX and have the chart filled with data with as little as one line of code.

Additionally, Chart FX for .NET supports data binding with data controls and data readers. If you drop an ADO.NET DataSet control in your form, just set a property in Chart FX that will allow the chart to take information from the data control directly. Or, if you prefer, load the data to the chart by coding in an event handler using a DataSet or even a Data Command.

This chapter will explain how to populate your charts from the most common data sources. These sources include:

  • API
  • Database
  • Text (*)
  • XML (*)
  • Arrays (*)
  • Collections (*)
  • Crosstab (*)
  • OLAP (*)

(*) Not supported by Pocket Chart FX for .NET


Passing Data using the Chart FX API

Passing numeric values using the Chart FX API is as simple as opening a communication channel using the OpenData method, setting the values and then closing the communication channel using the CloseData method. You can pass data using the API through any loop command (while, for, etc.) supported in your development environment.

The comunication chanel can be opened in different ways depending of the type of data that needs to be set. The OpenData and CloseData method will recieve a COD (Channel of Data) parameter that will indicate what kind of date will be passed to the chart: Values, Constants, iniValues, XValues, etc.

Important Note: This section will explain how to pass numerical information to Chart FX, if you want to set legends and other text information to the chart, please refer to Axis Labeling - Understanding a Categorical Axis in this manual This section also describes how to pass information to the majority of chart types provided by Chart FX. If you're creating special chart types, such as financial, scatter and other, please refer to later chapters in this help file, as additional properties need to be set to create these charts appropriately.

Passing Data using the Value property

Sometimes the easiest or most convenient way to pass numerical data to Chart FX is to use the Value method, which allows you to set the numerical value for a point in a particular series in the chart.

The Value method takes the index of the series (zero based) and the index of the point you want to populate (zero based), and the value. For example, if you want to set a value of 40 for point 3 of series 2, you must use the Value method as follows:

Chart1.Value(1,2) = 40

chart1.Value[1,2] = 40;

Chart1.Value(1,2) = 40

Chart1.Value(1, 2) = 40

Please note the Value method will have no effect unless you invoke it between an OpenData and CloseData methods. For example, if you want to set points to the entire chart, you can loop through the points and use the Value method as follows:

'Open the communication channel
Chart1.OpenData(COD.Values, 2, 6)
For i = 0 To 1
   For j = 0 To 5
      'Assign the values to the series selected
      Chart1.Value(i, j) = Rnd() * 100
   Next j
Next i
'Close the communication channel
Chart1.CloseData(COD.Values)

Random rnd = new Random();
// Open the communication channel
chart1.OpenData(COD.Values, 2, 6);
for(int i=0;i<=1;i++)
   for(int j=0;j<=5;j++) {
      // Assign the values to the series selected
      chart1.Value[i, j] = rnd.NextDouble() * 100;
   }

//Close the communication channel
chart1.CloseData(COD.Values);

' Open the communication channel
chart1.OpenData COD_Values, 2, 6

For i = 0 To 1
   For j = 0 To 5
      ' Assign the values to the series selected
      chart1.Value(i, j) = (Rnd()) * 100
   Next
Next

'Close the communication channel
chart1.CloseData COD_Values

' Open the communication channel
Chart1.OpenData COD_Values, 2, 6
Dim i as Integer
i = 0
Do While (i <= 1)
    Dim j as Integer
    j = 0
    Do While (j <= 5)
' Assign the values to the series selected
        Chart1.Value(i, j) = (Rnd()) * 100
        j = j + 1
    Loop
    i = i + 1
Loop
'Close the communication channel
Chart1.CloseData COD_Values

Unknown Number of Points

Sometimes, knowing the number of points that the chart will hold is not possible and you'll end up in a situation where you don't know how to set the third parameter in the OpenData Method.

For example, if you're retrieving values from a database according to end users requests, it will be impractical to fetch all records and count them just to know the value Chart FX needs to open the communications channel. The OpenData method supports a setting called COD_Unknown, which will force Chart FX to allocate memory dynamically as you pass numeric values to it. The variable COD_Unknown is defined in the ChartFX.ASP.Core.inc include file. The following code shows you how to use the COD_Unknown setting appropriately.

Chart1.OpenData(COD.Values, 1, CType(COD.Unknown, Integer))
j = 0
While Fetching Records
   Chart1.Value(0, j) = Field1
   j = j + 1
Next
Chart1.CloseData(COD.Values)

chart1.OpenData(COD.Values, 1, (int) COD.Unknown);
int j = 0;
while (Fetching Records) {
   chart1.Value[0, j] = Field1;
   j++;
}
chart1.CloseData(COD.Values);

Chart1.OpenData(COD_Values, 1, COD_Unknown)
j = 0
While Fetching Records
   Chart1.Value(0, j) = Field1
   j = j + 1
Next
Chart1.CloseData(COD_Values)

Chart1.OpenData(COD_Values, 1, COD_Unknown)
j = 0
While Fetching Records
   Chart1.Value(0, j) = Field1
   j = j + 1
Next
Chart1.CloseData(COD_Values)

Note: Please notice that COD_Unknown is valid only for an unknown number of points. The number of series in the chart must be preset when calling the OpenData method.

Axes Rescaling

When data is loaded to the chart, by default, Chart FX automatically adjusts the axes Min and Max to guarantee that every value is inside the range. This behavior is controlled by the axes AutoScale method.

However, if a new set of values is loaded on the same chart,Chart FX will adjust the Min and Max again, only increasing when necessary but never decreasing them, which can affect the chart visualization. To force the Min and Max to be recalculated based on the new set of data, call the axes ResetScale method before loading the new data.

Hidden Points

Another interesting feature of Chart FX is the ability to create hidden points in the chart. Although Chart FX forces the same amount of points per series, you may specify hidden points to create the illusion of some invisible points in the chart. All you need to do to create a hidden point is to assign the Chart_Hidden constant when using the Value method toassign the numeric value to a point. The Chart_Hidden variable is defined in the ChartFX.ASP.Core.inc include file.

Chart1.Value(0, 3) = Chart.Hidden

chart1.Value[0, 3] = Chart.Hidden;

Chart1.Value(0, 3) = Chart_Hidden

Chart1.Value(0, 3) = Chart_Hidden

Note: Remember to use the OpenData and CloseData Methods when setting values to the chart.

Existing Values in the Chart

If you've already populated the chart and all you want to do is change an isolated value, you may do so without sending all the data again. The OpenData method supports a setting called COD_Unchange that will cause the data memory to remain intact, yet allowing you to change values in the chart. The COD_Unchange variable is defined in the ChartFX.ASP.Core.inc include file.

For example, if you want to change programmatically the numeric value for point No. 4 in the third Series your code should look like:

Chart1.OpenData(COD.Values, COD.Unchange, COD.Unchange)
Chart1.Value(2, 3) = 560
Chart1.CloseData(COD.Values)

chart1.OpenData(COD.Values, COD.Unchange, COD.Unchange);
chart1.Value[2, 3] = 560;
chart1.CloseData(COD.Values);

Chart1.OpenData COD_Values, COD_Unchange, COD_Unchange
Chart1.Value(2, 3) = 560
Chart1.CloseData COD_Values

Chart1.OpenData COD_Values, COD_Unchange, COD_Unchange
Chart1.Value(2, 3) = 560
Chart1.CloseData COD_Values


The Chart FX Data Assembly

When you install Chart FX for .NET, a Default Data assembly will also be installed. This assembly allows you to read information from XML, arrays, collections, etc. In the following pages, we will show you how you can use this additional assembly to read information and populate the chart from any of these sources.

How to integrate ChartFX.Data.dll Assembly

The Chart FX for .NET data assembly may be integrated into your project by adding a reference to ChartFX.Data.dll. Because other data providers are assemblies, you can integrate them as well with a reference to the appropriate DLL.

By including this reference as part of your .NET Development project, you can create objects that are implemented by the data assembly. Please refer to later topics in this section for more information on how to use the ChartFX.Data.dll objects with different data sources.

Important Note: Using the "Imports SoftwareFX.ChartFX.Data" (or "Using SoftwareFX.ChartFX.Data" in C#) statement before any declarations including Module or Class statements, and before any references to identifiers will allow you to access Chart FX for .NET Data Provider enumerations and classes without qualification.


Populating the chart from a Database

In most cases, you will want to populate charts with data coming from a database table or query. Chart FX for .NET supports data binding through ADO.NET.

ADO.NET offers you two basic ways to work with data: using a DataSet or working directly against a database. In the DataSet model, you create an in-memory store of the records you want to work with, load the store using a data adapter, manipulate the data, and then, optionally, use the data adapter to write changes back to the database.

Alternatively, you can work directly against the database. In this model, you configure a data command object with a SQL statement or the name of a stored procedure. You then execute the data command.

It is important to note, development strategies used for database access vary greatly from application to application. Furthermore, ADO.NET can be used to integrate data from complex application tiers. Therefore, this section is focused on describing basic techniques on how Chart FX for .NET uses ADO.NET connections to populate charts in Web Forms, Windows Forms or Smart Devices applications.


Using DataSets

Using DataSets

Creating a DataSet in Visual Studio .NET

Before you bind the chart to a DataSet in Visual Studio .NET, you must first create a DataSet that contains a copy of the database records. In this section you will add a DataSet to a form that connects to an Access database to fetch records from a single table.

Essentially, creating a DataSet at design time in Visual Studio can be accomplished by using the Data Adapter Wizard. The adapter contains SQL statements used to read database information. If necessary, the wizard also creates a database connection. Then a data schema must be generated.

To create the data connection and data adapter

1: From the Data Tab of the Visual Studio Toolbox, drag an OleDbDataAdapter object onto the form. The Data Adapter Configuration Wizard will start.

2: In the wizard do the following:

  • In the second pane, create or choose a connection to the desired database. In our case we'll point to an Access database called Test.mdb.
  • In the third pane, specify that you want to use a SQL statement to access the database.
  • In the fourth pane, type the desired SQL statement. In our case we will write the following statement that contains monthly sales information for 2 different products in a table: "SELECT Month,Product1,Product2 from Sales". Please note, you can simply type the SQL statement or get assistance from the wizard Query Builder.
  • Click Finish.

To create the DataSet

Visual Studio can generate the DataSet automatically based on the query you specified for the data adapter. The DataSet is an instance of the DataSet class based on a corresponding schema (.xsd file) that describes the class' elements (table, columns and constraints). To generate a DataSet do the following:

1: Click on the Form, from the Data menu, choose Generate DataSet.

2: In the Generate DataSet dialog, select the New option and name the dataset. In our case we will name the DataSet dsSales.

3: Check Add this DataSet to the designer, then click OK.

Visual Studio generates a typed DataSet class (dsSales) and a schema that defines the DataSet. Finally, Visual Studio adds an instance of the new DataSet class (dsSales1) to the form.

Configuring the chart control with the new DataSet class

1: Drag a chart control onto the form, select the chart.

2: In the chart Datasource property, select the new DataSet class and its member (in our case dsSales1.sales).

Setting this property binds the sales table in the dsSales1 DataSet to the chart.

Filling the DataSet and displaying data in the chart control

Although the chart is bound to the DataSet you've created, the DataSet itself is not automatically filled. Instead you must fill the DataSet yourself by calling a data adapter method. After the DataSet is filled, the chart control automatically displays the data.

In the Page_Load event handler call the data adapter's Fill method, passing it the DataSet you want to populate, as follows:

OleDbDataAdapter1.Fill(dsSales1)

Chart1.DataSourceSettings.DataSource = dsSales1.Tables(0)

Important Note: If you are building a Web Forms application, you do not need to refill the DataSet and bind the chart with each round trip. Once the chart control has been populated with data, its values are preserved in view state each time the page is posted. Therefore, you only need to fill the dataset and bind the chart the first time the page is called. You can test this using the page's IsPostBack property as follows:

Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs)
    Handles MyBase.Load

   If Not IsPostBack Then
      OleDbDataAdapter1.Fill(DsSales1)
      Chart1.DataSourceSettings.DataSource = DsSales1.Tables(0)
   End If
...

private void Form1_Load(object sender,System.EventArgs e)
{
    if (!IsPostBack)
       OleDbDataAdapter1.Fill(DsSales1);
       chart1.DataSourceSettings.DataSource = DsSales1.Tables[0];
...

Creating and configuring a DataSet by code in an event handler

Sometimes, the steps for creating a Data Adapter and filling a DataSet need to be executed as a result of a condition or as part of an event handler. For example, when the user clicks a button the data adapter is created and the DataSet is filled.

Sometimes, adding the data adapter and configuring it at design time is not practical or does not provide enough programming flexibility. The following VB.NET code accomplishes the same tasks as described in previous pages for creating and configuring a dataset within Visual Studio .NET, except that the code can be assigned to an event handler or used outside the designer environment:

Dim myConnectionString, mySelectQuery As String
Dim dsSales As New DataSet()
Dim adapter As System.Data.OleDb.OleDbDataAdapter
Dim myConnection As System.Data.OleDb.OleDbConnection

'Create the connection string
myConnectionString = "Provider=Microsoft.Jet.OLEDB.4.0; Data Source=Test.mdb"

' Fill the query statement
mySelectQuery = "SELECT Month,Product1,Product2 from Sales"
myConnection = New System.Data.OleDb.OleDbConnection(myConnectionString)

' Create the DataSet and Data Adapter
dsSales = New DataSet("Sales")
adapter = New System.Data.OleDb.OleDbDataAdapter()

adapter.SelectCommand = New System.Data.OleDb.OleDbCommand(mySelectQuery, myConnection)

' Fill the dataset
adapter.Fill(dsSales)

' Bind the chart to the dataset
Chart1.DataSourceSettings.DataSource = dsSales.Tables(0)

string myConnectionString, mySelectQuery;
DataSet dsSales = new DataSet();
System.Data.OleDb.OleDbDataAdapter adapter;
System.Data.OleDb.OleDbConnection myConnection;

// Create the connection string
myConnectionString = "Provider=Microsoft.Jet.OLEDB.4.0; Data Source=Test.mdb";

// Fill the query statement
mySelectQuery = "SELECT Month,Product1,Product2 from Sales";
myConnection = new System.Data.OleDb.OleDbConnection(myConnectionString);

// Create the DataSet and Data Adapter
dsSales = new DataSet("Sales");
adapter = new System.Data.OleDb.OleDbDataAdapter();

adapter.SelectCommand = new System.Data.OleDb.OleDbCommand(mySelectQuery, myConnection);

// Fill the dataset
adapter.Fill(dsSales);

// Bind the chart to the dataset
chart1.DataSourceSettings.DataSource = dsSales.Tables[0];

Creating and configuring a DataSet by code in a single-file web application

If you are developing Web Forms applications with Visual Studio, the environment will automatically perform much of the configuration process. However, if you want to connect to a database in a single-file .aspx application, you must remember to import the appropriate namespaces in the .aspx file.

The following C# code embedded in a single-file web application will configure a data adapter and bind the chart to a desired database table:

<%@ Import Namespace="SoftwareFX.ChartFX"%>
<%@ Import Namespace="SoftwareFX.ChartFX.Internet.Server"%>
<%@ Import Namespace="System.Drawing"%>
<%@ Import Namespace="System.Data"%>
<%@ Import Namespace="System.Data.OleDb"%>
<%
Dim Chart1 As New Chart(Me)

' Create the database connection object
Dim myConnection As New OleDbConnection("Provider=Microsoft.Jet.OLEDB.4.0; Data Source=Test.mdb ")

' Create the command and DataSet
Dim myCommand As New OleDbDataAdapter("SELECT Month,Product1,Product2From Sales", myConnection)

Dim dsSales As New DataSet()

' Fill the data set
myCommand.Fill(dsSales, "Sales")

' Assign the contents of the ResultSet to the Chart
chart1.DataSourceSettings.DataSource = dsSales.Tables(0)
%>

<%= Chart1.GetHtmlTag(500,350)%>

<%@ Import Namespace="SoftwareFX.ChartFX"%>
<%@ Import Namespace="SoftwareFX.ChartFX.Internet.Server"%>
<%@ Import Namespace="System.Drawing"%>
<%@ Import Namespace="System.Data"%>
<%@ Import Namespace="System.Data.OleDb"%>
<%
Chart Chart1 = new Chart(this);

// Create the database connection object
OleDbConnection myConnection = new OleDbConnection("Provider=Microsoft.Jet.OLEDB.4.0; Data Source=Test.mdb");

// Create the command and DataSet
OleDbDataAdapter myCommand = new OleDbDataAdapter("SELECT Month,Product1,Product2From Sales", myConnection);

DataSet dsSales = new DataSet();

// Fill the data set
myCommand.Fill(dsSales, "Sales");

// Assign the contents of the ResultSet to the Chart
chart1.DataSourceSettings.DataSource=dsSales.Tables[0];
%>

<%= Chart1.GetHtmlTag(500,350)%>


Using Data Command

Populating a chart with a Data Command

By using data commands, you can execute SELECT statements that return a result set you can read directly, rather than loading it into the DataSet. To read the results, you use a data reader (OleDbDataReader or SqlDataReader object), which works like a read-only, forward-only cursor, to which you can bind charts. This is a useful strategy for reducing memory usage and loading read-only data very quickly.

The following VB.NET code creates a Data Command and uses a data reader to fetch records directly from the database (without filling a DataSet) to populate the charts:

Dim mySelectQuery As String = "SELECT Month,Product1,Product2 FROM Sales"
Dim myConnString As String = "Provider=Microsoft.Jet.OLEDB.4.0; Data Source=test.mdb"
Dim myConnection As New OleDbConnection(myConnString)
Dim myCommand As New OleDbCommand(mySelectQuery, myConnection)

myConnection.Open()

Dim myReader As OleDbDataReader

myReader = myCommand.ExecuteReader()
Chart1.DataSourceSettings.DataSource = myReader

myReader.Close()

' Close the connection when done with it.
myConnection.Close()

string mySelectQuery = "SELECT Month,Product1,Product2 FROM Sales";
string myConnString = "Provider=Microsoft.Jet.OLEDB.4.0; Data Source=test.mdb";
OleDbConnection myConnection = new OleDbConnection(myConnString);
OleDbCommand myCommand = new OleDbCommand(mySelectQuery, myConnection);

myConnection.Open();

OleDbDataReader myReader;

myReader = myCommand.ExecuteReader();
chart1.DataSourceSettings.DataSource = myReader;

myReader.Close();

// Close the connection when done with it.myConnection.Close()


SQL Statements

Chart FX Tabular Data Interpretation

Chart FX will apply default rules to construct the chart when it has been bound to a database. These rules pick the information from the result set of the query and assign legends and values to the chart according to the field type. This behavior allows the creation of a default chart that fits or closely resembles the chart you want to achieve.

The rules to construct a chart when bound to a database table are:

  • All numerical columns in the query will be plotted as different series and all string and/or date columns will be plotted as point or X-axis labels (joined by the '-' character).
  • Series Legends will be taken from the numerical field names.
  • All string and numerical fields specified in the SELECT statement will be plotted in the chart.

For example, if you have a database table containing the following fields:

and bind the chart to the result set of the following SQL query:

SELECT Month,Product1,Product2 FROM Sales

The resulting chart will contain 2 series (Product1 and Product2) and X-axis labels containing the name of the months available in the Month field.

To change the default data binding behavior, Chart FX provides 2 properties (DataType and DataStyle) that allow you to change this automatic method of plotting the data values and assigning chart labels and legends.

DataType Property

The DataType property is an array property that indicates the type of every field and how it should be extracted from the SQL query and used in the chart. For example, in a 5 field SELECT statement such as:

SELECT year,sales,projected,returns,name FROM Sales

The Chart FX default behavior is that the year field will be considered another series since it is a numeric field. Instead, we want this field to be used as a label in the X-axis tick marks. Also, since this SQL query is also being used to fill a grid control (which contains more information than the chart) we do not want to get rid of the returns and name fields in the query but we also don't want them to be used anywhere in the chart. However, the Chart FX default behavior would cause these fields to be appended as X-axis labels.

We can easily override the Chart FX default behavior by setting DataType property as follows, using the DataType method:

' We have to instruct Chart FX to consider the year field as a label for the x-axis.
Chart1.DataSourceSettings.DataType(0) = DataType.Label

'Then assigned the Value enumeration to the numeric fields
Chart1.DataSourceSettings.DataType(1) = DataType.Value
Chart1.DataSourceSettings.DataType(2) = DataType.Value

'Finally, assign the NotUsed enumeration to those fields we don't want to plot.
Chart1.DataSourceSettings.DataType(3) = DataType.NotUsed
Chart1.DataSourceSettings.DataType(4) = DataType.NotUsed

// We have to instruct Chart FX to consider the year field as a label for the x-axis.
chart1.DataSourceSettings.DataType[0] = DataType.Label;

//Then assigned the Value enumeration to the numeric fields
chart1.DataSourceSettings.DataType[1] = DataType.Value;
chart1.DataSourceSettings.DataType[2] = DataType.Value;

//Finally, assign the NotUsed enumeration to those fields we don't want to plot.
chart1.DataSourceSettings.DataType[3] = DataType.NotUsed;
chart1.DataSourceSettings.DataType[4] = DataType.NotUsed;

' We have to instruct Chart FX to consider the year field as a label for the x-axis.
Chart1.DataSourceSettings.DataType(0) = DataType_Label

'Then assigned the Value enumeration to the numeric fields
Chart1.DataSourceSettings.DataType(1) = DataType_Value
Chart1.DataSourceSettings.DataType(2) = DataType_Value

'Finally, assign the NotUsed enumeration to those fields we don't want to plot.
Chart1.DataSourceSettings.DataType(3) = DataType_NotUsed
Chart1.DataSourceSettings.DataType(4) = DataType_NotUsed

' We have to instruct Chart FX to consider the year field as a label for the x-axis.
Chart1.DataSourceSettings.DataType.Item(0) = DataType_Label
'Then assigned the Value enumeration to the numeric fields
Chart1.DataSourceSettings.DataType.Item(1) = DataType_Value
Chart1.DataSourceSettings.DataType.Item(2) = DataType_Value
'Finally, assign the NotUsed enumeration to those fields we don't want to plot.
Chart1.DataSourceSettings.DataType.Item(3) = DataType_NotUsed
Chart1.DataSourceSettings.DataType.Item(4) = DataType_NotUsed

DataStyle Property

When having different string or date fields Chart FX will construct a long string with every string and date field to assign to every legend point in the chart. If you want to avoid this behavior, just turn OFF the appropriate constants using the DataStyle property. For example, if you want to force Chart FX not to use field names as series legends and use date fields as point legends, you should use the DataStyle property as follows:

Chart1.DataSourceSettings.DataStyle = Chart1.DataSourceSettings.DataStyle Or DataStyle.DatesAsLabels And Not DataStyle.KeepSerLeg

chart1.DataSourceSettings.DataStyle = chart1.DataSourceSettings.DataStyle | DataStyle.DatesAsLabels & ~DataStyle.KeepSerLeg;

Chart1.DataSourceSettings.DataStyle = chart1.DataSourceSettings.DataStyle Or DataStyle_DatesAsLabels And DataStyle_KeepSerLeg

Chart1.DataSourceSettings.DataStyle = Chart1.DataSourceSettings.DataStyle Or DataStyle_DatesAsLabels And Not DataStyle_KeepSerLeg

Note: The DataStyle property applies to all data-binding methods covered in this chapter: Text File, XML, Arrays, etc.

Pocket Chart FX for .NET Compact Framework and SQL Server CE

SqlCeConnection conn = new SqlCeConnection ("Data Source = Test.sdf");
SqlCeCommand cmd = new SqlCeCommand();
conn.Open();

cmd.CommandText = "SELECT * FROM sfxTest";
SqlCeDataReader rdr = cmd.ExecuteReader();

chart1.DataType[0] = DataType.Label;
chart1.DataType[1] = DataType.Value;

chart1.DataSource = rdr;

conn.Close();

Dim conn AS New SqlCeConnection("Data Source = Test.sdf")
Dim cmd As New SqlCeCommand
conn.Open()

cmd.CommandText = "SELECT * FROM sfxTest"
Dim rdr AS SqlCeDataReader = cmd.ExecuteReader()

chart1.DataType(0) = DataType.Label
chart1.DataType(1) = DataType.Value

chart1.DataSource = rdr

conn.Close()


Reading from Arrays and Collections

In many situations, the data is contained in a memory array. Although you can use the Chart FX API to loop through array elements, read and populate the chart, you can also do so in an easier way.

This feature is supported by the ListProvider class, implemented by the Chart FX for .NET Data Providers Assembly (ChartFX.Data.dll) and the chart's DataSource property, as follows:

Dim valArray() As Integer = {12, 15, 10, 7, 5}
Dim lstProvider as New ListProvider(valArray)
Chart1.DataSourceSettings.DataSource = lstProvider

int[] valArray = {12, 15, 10, 7, 5} ;
ListProvider lstProvider = new ListProvider(valArray);
chart1.DataSourceSettings.DataSource = lstProvider;

Note: Please refer to the Data Providers section for more information about integrating the default Data Provider.

If you want to load data from more than one array, you can use the method shown in the following example:

Dim series1() As Integer = {12, 15, 10}
Dim series2() As Integer = {20, 25, 7}
Dim labels() As String = {"Yes", "No", "Don't know"}
Dim allArrays(2) As Object

'Load Array of Arrays
allArrays(0) = series1
allArrays(1) = series2
allArrays(2) = labels

Dim lstProvider As New ListProvider(allArrays)
Chart1.DataSourceSettings.DataSource = lstProvider

int[] series1 = {12, 15, 10};
int[] series2 = {20, 25, 7};
string[] labels = {"Yes", "No", "Don't know"};
object[] allArrays = new object[2];

//Load Array of Arrays
allArrays[0] = series1;
allArrays[1] = series2;
allArrays[2] = labels;

ListProvider lstProvider = new ListProvider(allArrays);
chart1.DataSourceSettings.DataSource = lstProvider;

Please note that you can pass arrays filled with Numerical Data as well as String or Dates, which will be taken as legends in the chart. In this particular sample there are 3 arrays, two containing numerical data to be contained in the chart and the other containing legends for each point in the nValues array. This means, there's no limitation on the number of arrays you can pass using this technique.

Important: you cannot pass multi-dimensional arrays to Chart FX for .NET. This means, if you create a matrix or a multi-dimensional array as nData(10,10), Chart FX for .NET will not know how to process this information. An error will occur.

Reading Data From Collections

Collections provide a more powerful way to store data as they don't have a fixed size (efficient memory handling) and can grow accordingly (flexibility). Chart FX for .NET can also read information from collections exactly the same way that reading from arrays is supported. Please refer to your .NET Development Studio documentation or more information on how to handle collections in you NET programming language.

'Replace <collection> for any Collection: ArrayList, SortedList...
Dim series1 = New Collection()
Dim series2 = New Collection()
Dim labels = New Collection()
Dim allColl = New Collection()

series1.Add(12)
series1.Add(15)
series1.Add(10)
series2.Add(20)
series2.Add(25)
series2.Add(7)
labels.Add("Yes")
labels.Add("No")
labels.Add("Don't know")

'Load Collection of Collections
allColl.add(series1)
allColl.add(series2)
allColl.add(labels)

Dim lstProvider As New ListProvider(allColl)
Chart1.DataSourceSettings.DataSource = lstProvider

//Replace <collection> for any Collection: ArrayList, SortedList...
<collection> series1 = new <collection>();
<collection> series2 = new <collection>();
<collection> labels = new <collection>();
<collection> allColl = new <collection>();

series1.Add(12);
series1.Add(15);
series1.Add(10);
series2.Add(20);
series2.Add(25);
series2.Add(7);
labels.Add("Yes");
labels.Add("No");
labels.Add("Don't know");

//Load Collection of Collections
allColl.add(series1);
allColl.add(series2);
allColl.add(labels);

ListProvider lstProvider = new ListProvider(allColl);
chart1.DataSourceSettings.DataSource = lstProvider;

Because collections are not strongly typed, Chart FX for .NET will use the first element in the collection to determine the data type stored in it, and expect all the elements to be the same type. For example, if a collection contains numbers and words, Chart FX for .NET will fail when assigning the ListProvider to the Charts' DataSource property.

Important Note: The order you use to add the collections to the data provider is really important as you can use the DataType property to instruct Chart FX to manipulate the collections differently. For example, you can use the DataType property to instruct Chart FX to use a particular numerical collection as legends in the chart.

Using the DataType property

The DataType property is an array property that indicates the type of every position and how it should be extracted from the Array or Collection and used in the chart. For example, with two arrays:

Dim year() as Integer = {1999,2000,2001}
Dim sales() as Double = {100000, 125000, 150000}
Dim all() As Object = {year, sales}

int[] year = {1999,2000,2001};
double[] sales = {100000, 125000, 150000};
object[] all = {year, sales};

Chart FX for .NET will consider the year array as another series since it is a numeric field. Instead, we want this field to be used as a value for the X Axis. We can easily override the Chart FX default behavior by filling the DataType property as follows:

Chart1.DataSourceSettings.DataType(0) = DataType.XValue
Chart1.DataSourceSettings.DataType(1) = DataType.Value

chart1.DataSourceSettings.DataType[0] = DataType.XValue;
chart1.DataSourceSettings.DataType[1] = DataType.Value;


Reading Data from Text Files

Chart FX can also read information stored in text files or text streams. Both Tab separated values (TSV) and Comma separated values (CSV) are valid and can be accessed by Chart FX by default, but other formats can also be used.

This feature is supported by the TextProvider object and chart's DataSource property, which are both implemented by the Chart FX core as follows:

Dim txtProvider As New TextProvider("TextFile.txt")
Chart1.DataSource = txtProvider

TextProvider txtProvider = new TextProvider("TextFile.txt");
chart1.DataSource = txtProvider;

Dim txtProvider
Set txtProvider = Server.CreateObject("ChartFX.ASP.TextProvider")
txtProvider.Open Server.MapPath(".\TextFile.txt")
Chart1.DataSource = txtProvider

Dim txtProvider as Cfx62ClientServerCtl.TextProvider
Set txtProvider = New Cfx62ClientServerCtl.TextProvider
txtProvider.Open "TextFile.txt"
Chart1.DataSource = txtProvider

Dim stream As New StreamReader("TextFile.txt")
Dim txtProvider As New TextProvider(stream)
Chart1.DataSource = txtProvider

StreamReader stream = new StreamReader("TextFile.txt");
TextProvider txtProvider = new TextProvider(stream);
chart1.DataSource = txtProvider;

The format of the text file depends on the actual data you want Chart FX to take. It may have just numerical information or it may include corresponding labels that Chart FX will use to assign to legends. In any case, the format of the text file must follow these guidelines:

  • There are as many columns as series in the chart.
  • There are as many rows as points per series in the chart.
  • Columns must be separated by a tab or comma, or any other character specified in the Separators Property.
  • Each row ends in a carriage return.
  • No empty lines are allowed after the last row of data.
  • Series Legends will be taken from Column headings.
  • Point legends (X-axis legends) will be taken from Row headings.

For example, creating a text file that Chart FX will use to:

Please note there's a tab character in the first cell to make the "Sales" label appear as a heading for the first column.

Separators

By default, Chart FX's TextProvider understands commas and tabs as separators. However, columns within the text file can be separated with many other characters, as long as they are always the same, configuring the Text Provider is done as follows:

' Columns are separated by pipes
txtProvider.Separators = "|"

// Columns are separated by pipes
txtProvider.Separators = "|";

' Columns are separated by pipes
txtProvider.Separators = "|"

' Columns are separated by pipes
txtProvider.Separators = "|"

Important Note: Dashes ("-") are not a valid separator since they are used to identify negative values.

Date Formats

When date values are included in the text file in another format than "mm/dd/yyyy" (which is the default format for Chart FX TextProvider), the DateFormat property must be used to create a mask that will instruct Chart FX how to understand the values.

' Date are formatted like 01-Jan-2004
txtProvider.DateFormat = "dd-MMM-yyy"

// Date are formatted like 01-Jan-2004
txtProvider.DateFormat = "dd-MMM-yyy";

' Date are formatted like 01-Jan-2004
txtProvider.DateFormat = "dd-MMM-yyy"

' Date are formatted like 01-Jan-2004
txtProvider.DateFormat = "dd-MMM-yyy"


Reading Data from XML

XML has proven to be a very dynamic and flexible means of data storage. Chart FX for has been developed with this in mind and allows you to populate your charts with data directly from XML files.

The Load method is supported by the XMLDataProvider object. To use this feature properly, you must create a new XmlDataProvider object, load the XML data and finally set the DataSource property, as follows:

Dim cfxXML As New XmlDataProvider()
cfxXML.Load("d:\temp\myxml2.xml")
Chart1.DataSourceSettings.DataSource = cfxXML

XmlDataProvider cfxXML = new XmlDataProvider();
cfxXML.Load("d:\\temp\\myxml2.xml");
chart1.DataSourceSettings.DataSource = cfxXML;

Dim cfxXML
Set cfxXML = Server.CreateObject("ChartFX.ASP.XmlProvider")
cfxXML.Load Server.MapPath(".\myxml2.xml")
Chart1.DataSourceSettings.DataSource = cfxXML

Dim cfxXML as Cfx62ClientServerData.XmlDataProvider
Set cfxXML = New Cfx62ClientServerData.XmlDataProvider
cfxXML.Load "d:\temp\myxml2.xml"
Chart1.DataSourceSettings.DataSource = cfxXML

When passing the data using the XML data provider, the data is passed as columns and rows, the same as with a table. The following rules apply:

a) There must be a special tag indicating that the information enclosed is the column's definition. By default this tag is named <COLUMNS>. Each column will need a separate COLUMN tag. The format is:

<COLUMNS>
<COLUMN NAME="Column1_Name" TYPE="Column1_Type" DESCRIPTION="Column1_Desciption" />
...
COLUMN NAME="ColumnN_Name" TYPE="ColumnN_Type"DESCRIPTION="Column1_Desciption" />
    DESCRIPTION="Column1_Desciption" />
</COLUMNS>

The Description attribute is optional. If it is included, it will be used as a Series or Value legend. If it is not present, the Name will be assigned as a Series or Value legend instead.

b) As you can see above, each column name is configured with a type. The supported data types are String, Integer, Double, Short, Float, Boolean, Byte and Date.

c) Every row is then defined using the following format:

<ROW Column1_Name="Value" ... ColumnN_Name="Value"/>

This is a sample of an XML file used to populate a chart:

<?xml version="1.0"?>
<CHARTFX>
 <COLUMNS>
    <COLUMN NAME="Product" TYPE="String"/>
    <COLUMN NAME="Q1" TYPE="Integer"/>
    <COLUMN NAME="Q2" TYPE="Integer"/>
    <COLUMN NAME="Q3" TYPE="Integer"/>
    <COLUMN NAME="Q4" TYPE="Integer"/>
    </COLUMNS>
 <ROW Product="ChartFX 98" Q1="9200" Q2="7835"
        Q3="10245" Q4="8762"/>
 <ROW Product="ChartFX IE 3.5" Q1="14350" Q2="11233"
        Q3="16754" Q4="987"/>
 <ROW Product="ReportFX" Q1="12398" Q2="7654"
        Q3="5678" Q4="9087"/>
 <ROW Product="Image Toppings" Q1="8742" Q2="12358"
        Q3="14321" Q4="8702"/>
 <ROW Product="ChartFX IE 2000" Q1="15672" Q2="17529"
        Q3="16524" Q4="654"/>
 <ROW Product="WebBarFX" Q1="6890" Q2="12389"
        Q3="9804" Q4="10723"/>
 <ROW Product="WebTreeFX" Q1="11320" Q2="12908"
        Q3="6521" Q4="7590"/>
</CHARTFX>

Reading XML as a String

The sample above illustrates how you can read xml data from an xml file. This is done using the load method of the XmlDataProvider class. However, there may be a situation where you would like to read xml data as a string. The following example will demonstrate how Chart FX can read xml data from a string using the LoadXml method. The string is a concatenated xml file:

Dim SfxXML As New SoftwareFX.ChartFX.Data.XmlDataProvider()
Dim myString As String

myString = "<?xml version=""1.0""?><CHARTFX><COLUMNS>"
myString = myString + "<COLUMN NAME=""Product"" TYPE=""String""/>"
myString = myString + "<COLUMN NAME=""Q1"" TYPE=""Integer""/>"
myString = myString + "<COLUMN NAME=""Q2"" TYPE=""Integer""/>"
myString = myString + "<COLUMN NAME=""Q3"" TYPE=""Integer""/>"
myString = myString + "<COLUMN NAME=""Q4"" TYPE=""Integer""/>"
myString = myString + "</COLUMNS>"
myString = myString + "<ROW Product=""ChartFX 98"" Q1=""9200"" "
myString = myString + "Q2=""7835"" Q3=""10245"" Q4=""8762""/>"
myString = myString + "<ROW Product=""ChartFX IE 3.5"" Q1=""14350"" "
myString = myString + "Q2=""11233"" Q3=""16754"" Q4=""15672""/>"
myString = myString + "<ROW Product=""ReportFX"" Q1=""12398"" "
myString = myString + "Q2=""7654"" Q3=""5678"" Q4=""9087""/>"
myString = myString + "<ROW Product=""Image Toppings"" Q1=""8742"" "
myString = myString + "Q2=""12358"" Q3=""14321"" Q4=""8702""/>"
myString = myString + "<ROW Product=""ChartFX IE 2000"" Q1=""15672"" "
myString = myString + "Q2=""17529"" Q3=""16524"" Q4=""7654""/>"
myString = myString + "<ROW Product=""WebBarFX"" Q1=""6890"" "
myString = myString + "Q2=""12389"" Q3=""9804"" Q4=""10723""/>"
myString = myString + "<ROW Product=""WebTreeFX"" Q1=""11320"" "
myString = myString + "Q2=""12908"" Q3=""6521"" Q4=""7590""/>"
myString = myString + "</CHARTFX>"

SfxXML.LoadXml(myString)
Chart1.DataSourceSettings.DataSource = SfxXML

SoftwareFX.ChartFX.Data.XmlDataProvider SfxXML = new SoftwareFX.ChartFX.Data.XmlDataProvider();
string myString;

myString = @"<?xml version=""1.0""?><CHARTFX><COLUMNS>";
myString = myString + @"<COLUMN NAME=""Product"" TYPE=""String""/>";
myString = myString + @"<COLUMN NAME=""Q1"" TYPE=""Integer""/>";
myString = myString + @"<COLUMN NAME=""Q2"" TYPE=""Integer""/>";
myString = myString + @"<COLUMN NAME=""Q3"" TYPE=""Integer""/>";
myString = myString + @"<COLUMN NAME=""Q4"" TYPE=""Integer""/>";
myString = myString + "</COLUMNS>";
myString = myString + @"<ROW Product=""ChartFX 98"" Q1=""9200"" ";
myString = myString + @"Q2=""7835"" Q3=""10245"" Q4=""8762""/>";
myString = myString + @"<ROW Product=""ChartFX IE 3.5"" Q1=""14350"" ";
myString = myString + @"Q2=""11233"" Q3=""16754"" Q4=""15672""/>";
myString = myString + @"<ROW Product=""ReportFX"" Q1=""12398"" ";
myString = myString + @"Q2=""7654"" Q3=""5678"" Q4=""9087""/>";
myString = myString + @"<ROW Product=""Image Toppings"" Q1=""8742"" ";
myString = myString + @"Q2=""12358"" Q3=""14321"" Q4=""8702""/>";
myString = myString + @"<ROW Product=""ChartFX IE 2000"" Q1=""15672"" ";
myString = myString + @"Q2=""17529"" Q3=""16524"" Q4=""7654""/>";
myString = myString + @"<ROW Product=""WebBarFX"" Q1=""6890"" ";
myString = myString + @"Q2=""12389"" Q3=""9804"" Q4=""10723""/>";
myString = myString + @"<ROW Product=""WebTreeFX"" Q1=""11320"" ";
myString = myString + @"Q2=""12908"" Q3=""6521"" Q4=""7590""/>";
myString = myString + "</CHARTFX>";

SfxXML.LoadXml(myString);
chart1.DataSourceSettings.DataSource = SfxXML;

Dim SfxXML
Set SfxXML = Server.CreateObject("ChartFX.ASP.XmlDataProvider")
Dim myString

myString = "<?xml version=""1.0""?><CHARTFX><COLUMNS>"
myString = myString + "<COLUMN NAME=""Product"" TYPE=""String""/>"
myString = myString + "<COLUMN NAME=""Q1"" TYPE=""Integer""/>"
myString = myString + "<COLUMN NAME=""Q2"" TYPE=""Integer""/>"
myString = myString + "<COLUMN NAME=""Q3"" TYPE=""Integer""/>"
myString = myString + "<COLUMN NAME=""Q4"" TYPE=""Integer""/>"
myString = myString + "</COLUMNS>"
myString = myString + "<ROW Product=""ChartFX 98"" Q1=""9200"" "
myString = myString + "Q2=""7835"" Q3=""10245"" Q4=""8762""/>"
myString = myString + "<ROW Product=""ChartFX IE 3.5"" Q1=""14350"" "
myString = myString + "Q2=""11233"" Q3=""16754"" Q4=""15672""/>"
myString = myString + "<ROW Product=""ReportFX"" Q1=""12398"" "
myString = myString + "Q2=""7654"" Q3=""5678"" Q4=""9087""/>"
myString = myString + "<ROW Product=""Image Toppings"" Q1=""8742"" "
myString = myString + "Q2=""12358"" Q3=""14321"" Q4=""8702""/>"
myString = myString + "<ROW Product=""ChartFX IE 2000"" Q1=""15672"" "
myString = myString + "Q2=""17529"" Q3=""16524"" Q4=""7654""/>"
myString = myString + "<ROW Product=""WebBarFX"" Q1=""6890"" "
myString = myString + "Q2=""12389"" Q3=""9804"" Q4=""10723""/>"
myString = myString + "<ROW Product=""WebTreeFX"" Q1=""11320"" "
myString = myString + "Q2=""12908"" Q3=""6521"" Q4=""7590""/>"
myString = myString + "</CHARTFX>"

SfxXML.LoadXml myString
Chart1.DataSourceSettings.DataSource = SfxXML

Dim SfxXML as Cfx62ClientServerData.XmlDataProvider
Set SfxXML = New Cfx62ClientServerData.XmlDataProvider
Dim myString as String
myString = "<?xml version=""1.0""?><CHARTFX><COLUMNS>"
myString = myString + "<COLUMN NAME=""Product"" TYPE=""String""/>"
myString = myString + "<COLUMN NAME=""Q1"" TYPE=""Integer""/>"
myString = myString + "<COLUMN NAME=""Q2"" TYPE=""Integer""/>"
myString = myString + "<COLUMN NAME=""Q3"" TYPE=""Integer""/>"
myString = myString + "<COLUMN NAME=""Q4"" TYPE=""Integer""/>"
myString = myString + "</COLUMNS>"
myString = myString + "<ROW Product=""ChartFX 98"" Q1=""9200"" "
myString = myString + "Q2=""7835"" Q3=""10245"" Q4=""8762""/>"
myString = myString + "<ROW Product=""ChartFX IE 3.5"" Q1=""14350"" "
myString = myString + "Q2=""11233"" Q3=""16754"" Q4=""15672""/>"
myString = myString + "<ROW Product=""ReportFX"" Q1=""12398"" "
myString = myString + "Q2=""7654"" Q3=""5678"" Q4=""9087""/>"
myString = myString + "<ROW Product=""Image Toppings"" Q1=""8742"" "
myString = myString + "Q2=""12358"" Q3=""14321"" Q4=""8702""/>"
myString = myString + "<ROW Product=""ChartFX IE 2000"" Q1=""15672"" "
myString = myString + "Q2=""17529"" Q3=""16524"" Q4=""7654""/>"
myString = myString + "<ROW Product=""WebBarFX"" Q1=""6890"" "
myString = myString + "Q2=""12389"" Q3=""9804"" Q4=""10723""/>"
myString = myString + "<ROW Product=""WebTreeFX"" Q1=""11320"" "
myString = myString + "Q2=""12908"" Q3=""6521"" Q4=""7590""/>"
myString = myString + "</CHARTFX>"
SfxXML.LoadXml myString
Chart1.DataSourceSettings.DataSource = SfxXML


Reading Attributes from XML

Chart FX not only reads chart data from XML, but can also read chart properties to set visual attributes and formatting for your charts. The XML property files can be read and applied to a chart by utilizing the Import method. The following is used to set properties for a chart:

Chart1.Import(FileFormat.XML, System.Windows.Forms.Application.StartupPath + "\\PropertyXml.xml")

chart1.Import(FileFormat.XML, System.Windows.Forms.Application.StartupPath + "\\PropertyXml.xml");

Chart1.Import FileFormat_XML, Server.MapPath(".") + "\PropertyXml.xml"

Chart1.Import FileFormat_XML, ((App.Path) + "\PropertyXml.xml")

A formal schema has not been created, however each property is a tag, and properties for sub objects (series, point, axis, etc.) should be sub tags. When customizing per series or per point attributes there is no tag per series, instead an index attribute is used. Here is a sample of a property XML file.

Note: When specifying an axis property, you must use the integer index parameter instead of constants such as X, X2, Y or Y2.

<CHARTFX>
    <VOLUME>35</VOLUME>
    <VOLUME>35</VOLUME>
    <TITLES>
        <TITLE>
            <TEXT>My First Chart</TEXT>
        </TITLE>
    </TITLES>
        <SERLEGBOXOBJ>
            <DOCKED>Left</DOCKED>
            <DRAWINGAREA>true</DRAWINGAREA>
            <FONT>
                <NAME>Verdana</NAME>
            </FONT>
            <ALIGNMENT>Center</ALIGNMENT>
        </SERLEGBOXOBJ>
    <SERLEGBOX>True</SERLEGBOX>
    <SERLEG>
        <LEGEND>Sales</LEGEND>
        <LEGEND>Projected</LEGEND>
    </SERLEG>
    <SERIES>
        <SERIES index="0">
            <BORDER>True</BORDER>
            <GALLERY>LINES</GALLERY>
        </SERIES>
        <SERIES index="1">
            <BORDER>True</BORDER>
            <GALLERY>Lines</GALLERY>
        </SERIES>
    </SERIES>
    <POINT>
        <POINT series="1" point="2">
            <COLOR>Red</COLOR>
            <MARKERSHAPE>Rect</MARKERSHAPE>
        </POINT>
    </POINT>
    <STRIPES>
        <STRIPE>
            <AXIS>0</AXIS>
            <TO>20</TO>
            <FROM>30</FROM>
        </STRIPE>
    </STRIPES>
</CHARTFX>

Note: Using the Export method, you can export the properties of a chart to an XML file to examine how Chart FX will read the same information.

Setting Chart FX Properties using XML

There are a number of different scenarios for setting Chart FX properties using XML. This document will not enumerate all the properties in the API; rather it will give examples of each of the categories of properties.

  • Simple Properties
  • Compound Properties
  • Simple Collection Properties
  • Collection Index Properties
  • Point Attribute Properties
  • External Object Properties
  • Extensions

Simple Properties

This represents the most basic type of property setting. These properties are set in a very straight forward fashion; use the property name for the opening and closing tag and the value in the middle. For example, to set the Gallery property you could use the following code:

<GALLERY>Curve</GALLERY>

This category includes all the general chart settings that are not related to a particular series, point or axis object.

Compound Properties

A compound property is one that contains multiple attributes. A property of this genre will contain tags for each attribute and its value inside of the parent property’s tag. For example, when setting fonts there can be numerous settings including the name and size of the font.

<FONT>
    <NAME>Bookman Old Style</NAME>
    <SIZE>15</SIZE>
</FONT>

You should be cognizant of the fact that fonts are usually set for a particular chart element (unless, of course, you are setting the font for the chart object itself). Therefore the above XML code will be included inside of a parent object; like an axis or a title.

Simple Collection Properties

Simple collection objects are those objects that don’t use a particular index, therefore the order they appear in the XML is significant. For instance, in the following stripe collection sample the "OrangeRed" stripe is added to the chart as the first stripe and the "Yellow" Stripe is added as the second stripe. This variety of objects includes constant lines and stripes. Notice that the various items in the collection are not indexed with any particular number:

<STRIPES>
    <ITEM>
        <COLOR>Red</COLOR>
        <TO>5</TO>
        <FROM>2.5</FROM>
        <AXIS>2</AXIS>
        <URL>http://support.softwarefx.com</URL>
    </ITEM>
    <ITEM>
        <COLOR>Yellow</COLOR>
        <TO>8</TO>
        <FROM>7</FROM>
        <AXIS>2</AXIS>
    </ITEM>
</STRIPES>

Title settings also belong in this category. Notice in the following sample how the font settings are nested inside of the parent TITLES tag.

<TITLES>
    <ITEM>
        <TEXT>Chart Title</TEXT>
        <COLOR>Purple</COLOR>
        <FONT>
            <NAME>Bookman Old Style</NAME>
            <SIZE>15</SIZE>
        </FONT>
    </ITEM>
</TITLES>

Collection Index Properties

What differentiates this class of properties from the previous type is the indexed number. This means that the order in the XML is not significant. The objects in the collection will be added to the chart based on their index number. It is also important to note that you may skip index numbers, as the chart will simply add the objects in ascending indexed order without regard for consecutive numbers. This allows you to skip numbers in order to objects later. This category includes such items as series settings and axis settings. You will notice in the following sample that each item in the collection receives a unique index to distinguish it from the other items in the collection.

<AXIS>
    <ITEM index="0">
        <STYLE>SingleLine, BreakZero, LongTick</STYLE>
        <AUTOSCALE>False</AUTOSCALE>
        <LABELSFORMAT>
            <DECIMALS>0</DECIMALS>
        </LABELSFORMAT>
        <GRIDLINES>True</GRIDLINES>
        <MIN>0</MIN>
        <MAX>50</MAX>
    </ITEM>
    <ITEM index="2">
        <TICKMARK>Cross</TICKMARK>
        <GRIDLINES>True</GRIDLINES>
    </ITEM>
    <ITEM index="3">
        <STYLE>SingleLine, BreakZero, LongTick</STYLE>
        <AUTOSCALE>False</AUTOSCALE>
        <LABELANGLE>45</LABELANGLE>
        <POSITION>Far</POSITION>
        <FONT>
            <SIZE>12</SIZE>
        </FONT>
        <TEXTCOLOR>Red</TEXTCOLOR>
        <MIN>-12</MIN>
        <MAX>25</MAX>
    </ITEM>
</AXIS>

Point Attribute Properties

Point attributes require two indexed numbers in order to set their properties. These two numbers represent the specific series and point whose attributes are being set. Please note that when setting point attributes you can set either a specific point of a particular series, or you may set a certain set of attributes that will be common to all indexed points of all the series in the chart. In the latter case the series index should be set to -1, as follows:

<POINT>
    <ITEM series="0" point="2">
        <MARKERSHAPE>InvertedTriangle</MARKERSHAPE>
        <MARKERSIZE>7</MARKERSIZE>
        <COLOR>Yellow</COLOR>
    </ITEM>
    <ITEM series="-1" point="0">
        <ALTERNATECOLOR>Bisque</ALTERNATECOLOR>
        <COLOR>Red</COLOR>
    </ITEM>
</POINT>

External Object Properties

Certain objects are not included in the core ChartFX.dll (or ChartFX.Internet.dll) when you set properties in this category you must include a reference to the required assembly. For example when setting border attributes, in addition to setting the attributes themselves, you must add the reference explicitly:

<BORDEROBJECT type="SoftwareFX.ChartFX.Borders.ImageBorder"
assembly="ChartFX.Borders">
<TYPE>Colonial</TYPE>
</BORDEROBJECT>

<EXTENSIONS>
        <COUNT>1</COUNT>
        <ITEM0 type="SoftwareFX.ChartFX.Annotation.AnnotationX" assembly="ChartFX.Annotation">
            <LIST type="SoftwareFX.ChartFX.Annotation.AnnotationList">
                <ITEM type="SoftwareFX.ChartFX.Annotation.AnnotationText">
                    <LEFT>119</LEFT>
                    <TOP>136</TOP>
                    <WIDTH>111</WIDTH>
                    <HEIGHT>16</HEIGHT>
                    <ATTACHED>Center</ATTACHED>
                    <LOGICALPOSITION>
                        <ITEM index="0">
                            4
                        </ITEM>
                        <ITEM index="1">
                            25
                        </ITEM>
                    </LOGICALPOSITION>
                    <BORDER>
                        <WIDTH>2</WIDTH>
                        <COLOR>Violet</COLOR>
                    </BORDER>
                    <TEXT>[TEXT GOES HERE]</TEXT>
                </ITEM>
            </LIST>
            <ENABLED>True</ENABLED>
        </ITEM0>
    </EXTENSIONS>

<EXTENSIONS>
        <COUNT>1</COUNT>
        <ITEM0 type="SoftwareFX.ChartFX.Annotation.AnnotationX" assembly="ChartFX.Annotation">
            <LIST type="SoftwareFX.ChartFX.Annotation.AnnotationList">
                <ITEM type="SoftwareFX.ChartFX.Annotation.AnnotationText">
                    <LEFT>119</LEFT>
                    <TOP>136</TOP>
                    <WIDTH>111</WIDTH>
                    <HEIGHT>16</HEIGHT>
                    <ATTACHED>Center</ATTACHED>
                    <LOGICALPOSITION>
                        <ITEM index="0">
                            4
                        </ITEM>
                        <ITEM index="1">
                            25
                        </ITEM>
                    </LOGICALPOSITION>
                    <BORDER>
                        <WIDTH>2</WIDTH>
                        <COLOR>Violet</COLOR>
                    </BORDER>
                    <TEXT>[TEXT GOES HERE]</TEXT>
                </ITEM>
            </LIST>
            <ENABLED>True</ENABLED>
        </ITEM0>
    </EXTENSIONS>

Additional Notes

It is important to understand that when you import an XML file you must specify all the settings that want to be included in the chart. For example, if you were displaying a Pie chart and the user clicks a button to import a bar chart from an XML file, if the XML does not explicitly set the gallery property to Bar the chart will retain the gallery setting from the previous chart. This is particularly important to keep in mind in the case that you exported an existing Bar chart to an XML file and then you desire to re-import it. Unlike binary chart files, the XML does include default chart settings (in order to keep the files smaller in size).


Crosstab Data Provider

As you know, Chart FX supports data organized in columnar format. In many cases, however, data is actually stored in tabular format, which previously required manual translation into columnar format prior to passing the data to Chart FX. This often-complicated translation of data format is costly in terms of development time. The Crosstab Data Provider included with Chart FX is an extension that automatically converts data from tabular to columnar format.

Suppose you want to chart the quarterly sales for various products. This can be accomplished by creating a standard SELECT query that uses the GROUP BY clause for the Product Name and Invoice date fields, and sums the values in the otal Sale field:

SELECT ProductName,datepart('q',InvoiceDate), Sum(TotalSale)
FROM InvoiceDetails
GROUP BY ProductName, datepart('q',InvoiceDate)
ORDER BY datepart('q',InvoiceDate),ProductName

This query produces the following output:

The previous table when passed to Chart FX will generate the following chart:

In most cases, this is not the chart you prefer to generate. The ProductName field information is repeated for each row and in order to compare the quarter sales for various products in different quarters, you must match numbers that are physically distant from one another on the page. Additionally, it could be easily overlooked that there are some quarters with no sales for a specific product.

In order to solve this problem, you should reorganize the data into columns to achieve the following table:

The following chart is generated from the previous table data:

This chart displays the data in this sample scenario much more effectively. The Crosstab Data Provider automatically converts the data from tabular to columnar format, using some definitions that are explained in the following section

The Crosstab Data Provider Functionality

There are two important aspects to effectively use the Crosstab Data Provider:

  • How the Crosstab Data Provider integrates with Chart FX.
  • How to configure it to convert tabular data to columnar data.

Taking advantage of the extensibility of Chart FX's design, the Crosstab Data Provider is a separate component that can be integrated into Chart FX as a data provider. The Crosstab Data Provider's input must be in the form of a supported Chart FX data provider, such as an array, collection, text file, XML or database among others. For more information on data providers, please refer to the Data Providers section of the Programmer's Guide or Resource Center.

Configuring the Crosstab Data Provider to Convert Tabular Data to Columnar Data

Due to the multitude of possible scenarios, the Crosstab Data Provider needs to be given rules for the conversion of tabular to columnar data. These rules define how each column in the tabular format is used. A column may be defined as any of the following options using the DataType property: Column Heading, Row Heading, Value, IniValue or Not Used.

Column Heading: When data in a column of the tabular data is used as column headings, each unique item that appears in that column will form a column in the resulting columnar format. There can only be one Column Heading defined; if more than one column heading is defined the first one defined will be used.

Row Headings: When a column or set of columns of the tabular data is used as a Row Heading, each unique item that appears in the columns specified will form a row in the resulting columnar format. The number of row headings that can be defined is unlimited.

If more than one column is specified as a row heading, the Crosstab Data Provider will concatenate the values into a single string in left-to-right order. The Separator property can be used to define a string that will separate each part of the row heading. By default, there is no separator.

IniValue: When a column of the tabular data is defined as IniValue, the Crosstab Data Provider will use it's content as the initial value for data points to achieve floating bars and area charts.

Value: When a column of the tabular data is defined as Value, the Crosstab Data Provider will use its content as the value of the element in the matrix, at the intersection of a specific row and column. Only one value column can be defined; if more than one value is defined, the first one defined will be used.

Not Used: When a column of the tabular format is defined as Not Used, the Crosstab Data Provider will ignore that column. By default, all the columns are not used.

For further explanation consider the following example:

If this data is used:

This chart is returned:

However, if the Column and Row headings are changed:

This chart is returned:

Other Crosstab Data Provider Properties

DataSource: The DataSource property is used to instruct the Crosstab provider to retrieve the information from an external data provider. The configured external data provider must be configured to a valid data provider such as a TextProvider, XmlDataProvider, ListProvider, etc.

CfxCT.DataSource = dt

cfxCT.DataSource = dt;

CfxCT.DataSource = rs;

cfxCT.DataSource = dt

DateFormat: The DateFormat property is used to instruct Chart FX how to format the dates when a column specified as a Row Heading is a date. If no DateFormat is specified, the format will be set from the Culture property. By default, the Culture property is set to en-US.

ct.DateFormat = "mm-dd-yyyy"

ct.DateFormat = "mm-dd-yyyy";

ct.DateFormat = "mm-dd-yyyy"

ct.DateFormat = "mm-dd-yyyy"

NullColumnHeading: The NullColumnHeading property is used to instruct Chart FX to use the configured string value when a null column heading is encountered.

ct.NullColumnHeading = "N/A"

ct.NullColumnHeading = "N/A";

ct.NullColumnHeading = "N/A"

ct.NullColumnHeading = "N/A"

Separator: The Separator property sets the separator between two or more fields that form the point label when more than one Row Heading is configured as a DataType.

ct.Separator = "/"

ct.Separator = "/";

ct.Separator = "/"

ct.Separator = "/"

XValue: The XValue property instructs Chart FX to use a single row heading as XValues instead of X Axis labels. Setting this property to True will instruct Chart FX to plot the row heading values as Xvalues instead of X Axis labels. This does not apply when you have multiple row headings configured.

ct.XValue = True

ct.XValue = true;

ct.XValue = True

ct.XValue = True

Crosstab Data Provider to Populate a Chart

This sample shows you how to connect a chart to a Crosstab Data Provider that specifies only one Row Heading. The Crosstab Data Provider connects record set to read the data from a database. Similarly, it can connect to any other data provider supported by Chart FX.

Data that generates this chart (in tabular format):

Referencing the Crosstab Data Provider

When you wish to utilize the Crosstab Data Provider in your Chart FX applications, you will need to create a new CrosstabProvider object in your project. The Chart FX data dll (ChartFX.ASP.Data.dll) must be used in order for the Crosstab provider to work.

Dim myConnectionString As String
Dim ds As System.Data.DataSet
Dim adapter As New System.Data.OleDb.OleDbDataAdapter
Dim myselectQuery = "Select * from crossdata"

myConnectionString = "Provider=Microsoft.Jet.OLEDB.4.0; Data Source= ct.mdb"
Dim myConnection As New System.Data.OleDb.OleDbConnection(myConnectionString)
ds = New DataSet("crossdata")
adapter.SelectCommand = New System.Data.OleDb.OleDbCommand(myselectQuery, myConnection)
adapter.Fill(ds)

Dim dt As New DataTableProvider(ds.Tables(0))

Dim cfxCT As New CrosstabDataProvider()
cfxCT.DataType(0) = CrosstabDataType.ColumnHeading
cfxCT.DataType(1) = CrosstabDataType.RowHeading
cfxCT.DataType(2) = CrosstabDataType.Value
cfxCT.DataSource = dt
Chart1.DataSourceSettings.DataSource = cfxCT

string myConnectionString;
System.Data.DataSet ds;
System.Data.OleDb.OleDbDataAdapter adapter = new System.Data.OleDb.OleDbDataAdapter();
string myselectQuery = "Select * from crossdata";

myConnectionString = "Provider=Microsoft.Jet.OLEDB.4.0; Data Source= ct.mdb";
System.Data.OleDb.OleDbConnection myConnection;
myConnection = new System.Data.OleDb.OleDbConnection(myConnectionString);
ds = new DataSet("crossdata");
adapter.SelectCommand = new System.Data.OleDb.OleDbCommand(myselectQuery, myConnection);
adapter.Fill(ds);

DataTableProvider dt = new DataTableProvider(ds.Tables[0]);

CrosstabDataProvider cfxCT = new CrosstabDataProvider();
cfxCT.DataType[0] = CrosstabDataType.ColumnHeading;
cfxCT.DataType[1] = CrosstabDataType.RowHeading;
cfxCT.DataType[2] = CrosstabDataType.Value;
cfxCT.DataSource = dt;
chart1.DataSourceSettings.DataSource = cfxCT;

mySelectQuery = "SELECT * from crossdata"
myConnectionString = "Provider=Microsoft.Jet.OLEDB.4.0; Data Source=ct.mdb;"
Dim myConnection
Set myConnection=Server.CreateObject("ADODB.Connection")
myConnection.Open(myConnectionString)
Dim rs
Set rs = myConnection.Execute(mySelectQuery)

Dim dt
Set dt = Server.CreateObject("ChartFX.ASP.AdoDataProvider")
dt.ResultSet = rs

' Crosstab Settings
Dim cfxCT
Set cfxCT = Server.CreateObject("ChartFX.ASP.CrosstabProvider")
cfxCT.DataType(0) = CrosstabDataType_ColumnHeading
cfxCT.DataType(1) = CrosstabDataType_RowHeading
cfxCT.DataType(2) = CrosstabDataType_Value
cfxCT.DataSource = dt
chart1.DataSourceSettings.DataSource = cfxCT

Dim mySelectQuery As String
mySelectQuery = "SELECT * from CrossTab1"
Dim myConnectionString As String
myConnectionString = "Provider=Microsoft.Jet.OLEDB.4.0; Data Source=" + (App.Path) + "\ChartfxSamples.mdb;"
Dim myConnection As New ADODB.Connection
Set myConnection = New ADODB.Connection
myConnection.Open (myConnectionString)
Dim adapter As Object
Dim rs
Set rs = myConnection.Execute(mySelectQuery)

Dim dt as Cfx62ClientServerCtl.AdoDataProvider
Set dt = New Cfx62ClientServerCtl.AdoDataProvider
dt.ResultSet = rs

' Crosstab Settings
Dim cfxCT  As CrosstabDataProvider
Set cfxCT = New CrosstabDataProvider
dt.ResultSet = rs
cfxCT.DataType(0) = CrosstabDataType_ColumnHeading
cfxCT.DataType(1) = CrosstabDataType_RowHeading
cfxCT.DataType(2) = CrosstabDataType_RowHeading
cfxCT.DataType(3) = CrosstabDataType_Value
cfxCT.DataSource = dt
cfxCT.Separator = "-"
chart1.DataSourceSettings.DataSource = cfxCT


OLAP Extension

Overview

Companies worldwide use relational databases and OLAP to increase the productivity of business managers, developers, and whole organizations. OLAP enables organizations to respond more quickly to market demands. Market responsiveness, in turn, often yields improved revenue and profitability.

Developers also benefit from OLAP for a simple reason: end users of OLAP applications can become more self-sufficient since they are no longer dependent on IT to make schema changes, to create joins, or build their own models.

Unfortunately, most if not all, OLAP vendors provide standalone applications that are expensive, proprietary and provide limited deployment options. If you want to OLAP-enable your intranet of enterprise applications, read on; Chart FX for OLAP may just be the right solution for you!

What is Chart FX for OLAP?

Chart FX for OLAP is the first .NET OLAP front end for developers that seamlessly integrate to Visual Studio .NET allowing you to build and deploy fully OLAP provisioned charts in your Windows Forms and Web Forms applications.

Chart FX for OLAP virtually connects to any relational database through ADO-MD and XML for Analysis serving as the only data analysis charting solution geared for developers and integrating to major leading OLAP server vendors like Microsoft SQL Server® and Hyperion Essbase®.

Chart FX for OLAP picks up the information and presents the hierarchical structure to the user in an intuitive way, enabling users to pivot, slice and dice data to uncover vital information. All this end user functionality is provided with little or no intervention from the developer, thus reducing development time and increasing customer satisfaction.

Also, as a fully managed .NET component, Chart FX for OLAP is a sensibly priced solution that supports a myriad of deployment scenarios, so whether you are building a browser based intranet application or a commercial or enterprise grade application, Chart FX for OLAP is the right solution for you!

For additional information or evaluation downloads of the Chart FX Extensions product line, please visit the Chart FX Extensions portal located at:
http://www.softwarefx.com/extensions/


Axis Control Overview

Axes are one of the most important aspects of a chart because they provide users with a visual means to read and analyze data. Therefore, a charting tool must provide mechanisms to manipulate axis settings programmatically.

Chart FX automatically configures axes accommodating the data that was used to populate the chart. This behavior will minimize the initial programming effort of customizing the chart's axes. However, in some cases, programmers will face complex needs like special labeling, scrolling, formatting and scaling that must be addressed via code. To achieve this, Chart FX provides a powerful object-oriented API letting programmers customize virtually anY-axis setting.

In this section, you will learn how to use the Chart FX API to customize any of the chart's axes. We will also describe special techniques that are used to enhance the chart's readability through axis customization and the creation of multiple axes.

Note: Chart FX gives end users the ability to change axis settings at run time by simply right-clicking and accessing axis properties through an intuitive interface. For more information, please refer to the "Chart FX User Interface" later in this manual.

The AxisX, AxisY and Axis Objects

Most charts contain 2 axes: a numerical axis (Y-axis) and categorical axis (X-axis).

Chart FX exposes 2 objects (AxisX and AxisY) that list a myriad of properties that allow control over many axis settings, including labeling, scaling and formatting attributes like colors, gridlines and tick marks. These objects, and their properties, can be accessed directly from your IDE at design time by clicking on a chart control and using the properties list or they can be accessed directly via code.

The Axis object is also provided to extend the capabilities of Chart FX to support an unlimited number of axes. Multiple axes support (including a Secondary Y-axis) is described later in this section.


Axis Scaling

Understanding Numerical Axes and Automatic Axis Scaling

When you populate a chart, Chart FX will automatically calculate the scale values for all numerical axes in the chart. Scale values include: Minimum (or where the axis starts), Maximum (or where the axis ends) and Step (or major unit).

These values are chosen according to the data and the chart's size (in the form) and then adjusted so the axis shows "nice" values in the chart. For example, if you pass the following data array to a chart:

[17.3, 78, 34.5, 58.9, 90.5, 35.3]

Chart FX will automatically select "nice" scale values to show in the Y-axis as depicted in the figure shown. Then the markers will be plotted in the chart area according to their value and the position in the chosen scale.

The Step property controls where labels and tick marks are shown in a numerical axis. This fraction is usually called the major unit. A numerical axis also supports a MinorStep property that allows you to set a minor unit on which you can only show and configure tick marks and gridlines.

For more information on tick marks please refer to Gridlines and Tick Marks later in this section.

If new data is set for a chart, Chart FX will then recalculate the scale values according to the new data set. This behavior is controlled by the AutoScale property of the axis, which is enabled by default. If you don't want to recalculate scale values every time data is sent to the chart you can simply disable this behavior as follows:

Chart1.AxisY.AutoScale = False

chart1.AxisY.AutoScale = false;

Chart1.AxisY.AutoScale = False

Chart1.AxisY.AutoScale = False

Note: you must set Min and Max if you set AutoScale = False.

Also, you can use the Min, Max, and Step properties of the AxisY object to force specific scale values, for example:

Dim axis As Axis = Chart1.AxisY
axis.Min = 10
axis.Max = 200
axis.Step = 5

Axis axis = chart1.AxisY;
axis.Min = 10;
axis.Max = 200;
axis.Step = 5;

Dim axis
Set axis = Chart1.AxisY
axis.Min = 10
axis.Max = 200
axis.Step = 5

Dim axis as Object
Set axis = Chart1.AxisY
axis.Min = 10
axis.Max = 200
axis.Step = 5

However, if you force scale values, Chart FX will not recalculate them when new data is set to the chart. This behavior can be altered by invoking the chart's RecalcScale method. This method recalculates scale values associated to ALL numerical axes, and can be invoked as follows:

Chart1.RecalcScale()

chart1.RecalcScale();

Chart1.RecalcScale()

Chart1.RecalcScale

Important Note: Please keep in mind that RecalcScale method applies to ALL numerical axes and reads the entire data array. In other words, you should avoid calling this method repeatedly as it will adversely affect the performance of your application.


Axis Formatting

Formatting a numerical axis is as simple as setting any of the pre-defined axis formats in Chart FX using the Format property supported by the ValueFormat class. For example, if you want scientific notation in the primary Y-axis, your code should look like this:

Chart1.AxisY.LabelsFormat.Format = AxisFormat.Scientific

chart1.AxisY.LabelsFormat.Format = AxisFormat.Scientific;

Chart1.AxisY.LabelsFormat.Format = AxisFormat_Scientific

Chart1.AxisY.LabelsFormat.Format = AxisFormat_Scientific

Please make sure you check the Format property on the API for more information on any pre-defined formats supported by Chart FX.

User-Defined Formats

Because Chart FX supports dates as well as numbers in an axis, you can define your own formats by creating a mask that will instruct Chart FX how to format and display labels in the selected axis. For example, if you set dates for the X-axis, you may create the following custom format:

Chart1.AxisY.LabelsFormat.CustomFormat = "Ddd-MMM-yy"

chart1.AxisY.LabelsFormat.CustomFormat = "Ddd-MMM-yy";

Chart1.AxisY.LabelsFormat.CustomFormat = "Ddd-MMM-yy"

Chart1.AxisY.LabelsFormat.CustomFormat = "Ddd-MMM-yy"

Note: When setting the CustomFormat property to a specific decimal value, any settings configured using the Decimals property will be ignored.

Logarithmic Scales

When plotting large numbers, Chart FX supports independent logarithmic scales on any of the axes (Primary, Secondary Y and X when used in a numerical sense). You may have Log-Log, Linear-Log or Log-Linear scales.

To set a Logarithmic scale for any of the Chart FX numerical axes you can use the LogBase property. This property will set a logarithmic scale for a numerical axis and recalculate the values as powers equal to the setting of this property. For example, if you want to set the Y-axis to be logarithmic with base 10 your code should look like the following:

Chart1.AxisY.LogBase = 10

chart1.AxisY.LogBase = 10;

Chart1.AxisY.LogBase = 10

Chart1.AxisY.LogBase = 10

Manipulating Dates and Times in X/Y charts

You have learned that Chart FX provides a means of formatting the axis labels to display date/time format rather than a number format through the ValueFormat class Format property.

After you have set the format of the axis you can then use the Min, Max, and Step properties to modify the display.

Dim axis As Axis = Chart1.AxisX
axis.LabelsFormat.Format = AxisFormat.Date
axis.Min = CDate(#2/20/2002#).ToOADate
axis.Max = CDate(#3/10/2002#).ToOADate
' Increase the step by ten days
axis.Step = 10

Axis axis = chart1.AxisX;
axis.LabelsFormat.Format = AxisFormat.Date;
axis.Min = (new DateTime(2002,2,20)).ToOADate();
axis.Max = (new DateTime(2002,3,10)).ToOADate();
// Increase the step by ten days
axis.Step = 10;

Dim axis
Set axis = Chart1.AxisX
axis.LabelsFormat.Format = AxisFormat_Date
axis.Min = CDbl(DateSerial(2002,2,20))
axis.Max = CDbl(DateSerial(2002,3,10))
' Increase the step by ten days
axis.Step = 10

Dim axis as Object
Set axis = Chart1.AxisX
axis.LabelsFormat.Format = AxisFormat_Date
axis.Min = CDbl(DateSerial(2002,2,20))
axis.Max = CDbl(DateSerial(2002,3,10))
' Increase the step by ten days
axis.Step = 10

This additional sample code shows how to display time labels for a period of 2 days with step set to 1 hour:

Dim axis As Axis = Chart1.AxisX
axis.LabelsFormat.Format = AxisFormat.Time
axis.Min = CDate(#2/20/2002#).ToOADate
axis.Max = CDate(#2/22/2002#).ToOADate
' Increase the step by one hour
axis.Step = 1.0/24

Axis axis = chart1.AxisX;
axis.LabelsFormat.Format = AxisFormat.Time;
axis.Min = (new DateTime(2002,2,20)).ToOADate();
axis.Max = (new DateTime(2002,2,22)).ToOADate();
// Increase the step by one hour
axis.Step = 1.0/24;

Dim axis
Set axis = chart1.AxisX
axis.LabelsFormat.Format = AxisFormat_Time
axis.Min = CDbl(DateSerial(2002,2,20))
axis.Max = CDbl(DateSerial(2002,2,22))
' Increase the step by one hour
axis.Step = CDbl(1/24)

Dim axis as Object
Set axis = Chart1.AxisX
axis.LabelsFormat.Format = AxisFormat_Time
axis.Min = CDbl(DateSerial(2002,2,20))
axis.Max = CDbl(DateSerial(2002,2,22))
' Increase the step by one hour
axis.Step = 1 / 24


Axis Labeling

Understanding Categorical Axes and Labeling

By default, a categorical axis (X-axis) is labeled with tag numbers (1,2,3...) on every tick mark. You can improve the chart's readability by assigning meaningful information to tick marks in the categorical axis. The Label property can be used for this purpose. This property receives the appropriate tick mark index to label, as follows:

Dim axis As Axis = Chart1.AxisX
axis.Label(0) = "January"
axis.Label(1) = "February"
axis.Label(2) = "March"
...

Axis axis = chart1.AxisX;
axis.Label[0] = "January";
axis.Label[1] = "February";
axis.Label[2] = "March";
...

Dim axis
Set axis = Chart1.AxisX
axis.Label(0) = "January"
axis.Label(1) = "February"
axis.Label(2) = "March"
...

Dim axis
Set axis = Chart1.AxisX
axis.Label(0) = "January"
axis.Label(1) = "February"
axis.Label(2) = "March"
...

Note: If you populated the chart from a database, these labels are automatically assigned from text fields in the query. For more information on populating charts with data coming from a database please refer to the "Passing Data" section earlier in this manual.

By default, Chart FX will calculate the number of labels that can be displayed according to the chart size and will hide some labels if all cannot be shown. There are some properties and techniques that will help you fit more labels on a categorical axis.

Just like a numerical axis, a categorical axis supports the Step property to control how often labels are shown in the axis. For example, when a Step of 3 is set to a categorical axis, labels will be placed on positions 3,6,9 and so on. The FirstLabel property works in a similar way, only that it forces the first label to be placed on an specific tick mark. For example, if a FirstLabel is set to 1, then X-axis labels will be shown at positions 1,4,7 and so on. The Step and FirstLabel properties can be set as follows:

Chart1.AxisX.LabelValue = 3

Chart1.AxisX.Step = 3

chart1.AxisX.LabelValue = 3;

chart1.AxisX.Step = 3;

Chart1.AxisX.LabelValue = 3
Chart1.AxisX.Step = 3

Chart1.AxisX.LabelValue = 3
Chart1.AxisX.Step = 3

NOTE:When using the FirstLabel property in the X Axis of a chart with values ranging from 0 to 1, the axis' MinorStep is used to calculate which label is the first, second, third, etc. When X Axis values range >1, then the axis' Step is used for this calcuation.

Chart1.Gallery = Gallery.Lines

Chart1.OpenData(COD.Values, 1, 5)
Chart1.OpenData(COD.XValues, 1, 5)

Chart1.Value(0, 0) = 27
Chart1.Value(0, 1) = 65
Chart1.Value(0, 2) = 34
Chart1.Value(0, 3) = 22
Chart1.Value(0, 4) = 26

Chart1.XValue(0, 0) = 0.2
Chart1.XValue(0, 1) = 0.4
Chart1.XValue(0, 2) = 0.6
Chart1.XValue(0, 3) = 0.8
Chart1.XValue(0, 4) = 1

Chart1.CloseData(COD.Values)
Chart1.CloseData(COD.XValues)

Chart1.AxisX.FirstLabel = 2
Chart1.AxisX.MinorStep = 0.2
Chart1.AxisX.Step = 0.2

Chart1.AxisX.LabelsFormat.Decimals = 1

chart1.Gallery = Gallery.Lines;

chart1.OpenData(COD.Values,1,5);
chart1.OpenData(COD.XValues,1,5);

chart1.Value[0,0] = 27;
chart1.Value[0,1] = 65;
chart1.Value[0,2] = 34;
chart1.Value[0,3] = 22;
chart1.Value[0,4] = 26;

chart1.XValue[0,0] = .2;
chart1.XValue[0,1] = .4;
chart1.XValue[0,2] = .6;
chart1.XValue[0,3] = .8;
chart1.XValue[0,4] = 1;

chart1.CloseData(COD.Values);
chart1.CloseData(COD.XValues);

chart1.AxisX.FirstLabel = 2;
chart1.AxisX.MinorStep = .2;
chart1.AxisX.Step = .2;

chart1.AxisX.LabelsFormat.Decimals = 1;

chart1.Gallery = Gallery_Lines

chart1.OpenData COD_Values, 1, 5
chart1.OpenData COD_XValues, 1, 5

chart1.Value(0, 0) = 27
chart1.Value(0, 1) = 65
chart1.Value(0, 2) = 34
chart1.Value(0, 3) = 22
chart1.Value(0, 4) = 26

chart1.XValue(0, 0) = 0.2
chart1.XValue(0, 1) = 0.4
chart1.XValue(0, 2) = 0.6
chart1.XValue(0, 3) = 0.8
chart1.XValue(0, 4) = 1

chart1.CloseData COD_Values
chart1.CloseData COD_XValues

chart1.AxisX.FirstLabel = 2
chart1.AxisX.MinorStep = 0.2
chart1.AxisX.Step = 0.2

chart1.AxisX.LabelsFormat.Decimals = 1

Chart1.Gallery = Gallery_Lines
Chart1.OpenData COD_Values, 1, 5
Chart1.OpenData COD_XValues, 1, 5
Chart1.Value(0, 0) = 27
Chart1.Value(0, 1) = 65
Chart1.Value(0, 2) = 34
Chart1.Value(0, 3) = 22
Chart1.Value(0, 4) = 26
Chart1.XValue(0, 0) = 0.2
Chart1.XValue(0, 1) = 0.4
Chart1.XValue(0, 2) = 0.6
Chart1.XValue(0, 3) = 0.8
Chart1.XValue(0, 4) = 1
Chart1.CloseData COD_Values
Chart1.CloseData COD_XValues
Chart1.AxisX.FirstLabel = 2
Chart1.AxisX.MinorStep = 0.2
Chart1.AxisX.Step = 0.2
Chart1.AxisX.LabelsFormat.Decimals = 1

You can also make room for more labels if you rotate them 90 degrees using the LabelAngle property as follows:

Chart1.AxisX.LabelAngle = 90

chart1.AxisX.LabelAngle = 90;

Chart1.AxisX.LabelAngle = 90

Chart1.AxisX.LabelAngle = 90

Or you can make the labels staggered, using the Style property as follows:

Chart1.AxisX.Style = Chart1.AxisX.Style Or SoftwareFX.ChartFX.AxisStyle.Show2Levels

chart1.AxisX.Style = chart1.AxisX.Style | SoftwareFX.ChartFX.AxisStyle.Show2Levels;

Chart1.AxisX.Style = Chart1.AxisX.Style Or AxisStyle_Show2Levels

Chart1.AxisX.Style = Chart1.AxisX.Style Or AxisStyle_Show2Levels

Note: The Style is a flag property that requires the bitwise operator (OR) to add or remove settings from the property. For more information, please refer to the AxisX.Style property in the Chart FX API.

The AxisX and AxisY objects support a myriad of properties that can be used to customize labels such as font, gridlines, tick marks, colors, axis styles, label rotation and other special effects. For more information, please refer to the Axis object in the Chart FX API where all the properties are listed and described.

Custom Labeling a Numerical Axis

Assigning custom labels to a categorical axis is as simple as using the Label property supported by the Axis object. However, there's a trick to using custom labels on a numerical axis that is best described using a real case scenario. For example, assume there is a numerical axis ranging from 0 to 100 with a step of 20.

You'll end up with a chart with 6 tick marks on the axis (0, 20, 40, 60, 80 and 100). If this chart is to be used to display "customer satisfaction" ratings where:

0 = Very poor
20 = Poor
40 = Average
60 = Good
80 = Very Good
100 = Excellent

The numerical axis will then display numbers that have no meaning to the user in this context. The following code will let you replace the numbers with labels:

Dim axis As Axis = Chart1.AxisY
axis.Label(0) = "Very Poor"
axis.Label(1) = "Poor"
axis.Label(2) = "Average"
axis.Label(3) = "Good"
axis.Label(4) = "Very Good"
axis.Label(5) = "Excellent"

Axis axis = chart1.AxisY;
axis.Label[0] = "Very Poor";
axis.Label[1] = "Poor";
axis.Label[2] = "Average";
axis.Label[3] = "Good";
axis.Label[4] = "Very Good";
axis.Label[5] = "Excellent";

Dim axis
Set axis = Chart1.AxisY
axis.Label(0) = "Very Poor"
axis.Label(1) = "Poor"
axis.Label(2) = "Average"
axis.Label(3) = "Good"
axis.Label(4) = "Very Good"
axis.Label(5) = "Excellent"

Dim axis as Object
Set axis = Chart1.AxisY
axis.Label(0) = "Very Poor"
axis.Label(1) = "Poor"
axis.Label(2) = "Average"
axis.Label(3) = "Good"
axis.Label(4) = "Very Good"
axis.Label(5) = "Excellent"

However, in a numerical axis the index specified in the Label property does not truly identify where the label should be placed. The LabelValue property allows you to specify where those labels should be placed in a numerical axis, so if you specify a LabelValue of 20 as follows:

Chart1.AxisY.LabelValue = 20

chart1.AxisY.LabelValue = 20;

Chart1.AxisY.LabelValue = 20

Chart1.AxisY.LabelValue = 20

Each label will be placed exactly where you intended it to be on the numerical axis as depicted in the following figure:


Axis Scrolling

Although Chart FX provides a wealth of properties to control how labels are displayed on an axis, the number of data points and the chart size become important factors as to how many labels you could fit in a chart or how much data is actually visible. In other words, some charts simply have too much data for the desired chart size and there's little you can do to improve the chart's readability.

Chart FX provides an elegantly designed scroll bar that attaches to an axis and allows end users to zoom in and view portions of an entire chart. It is important to note that ALL axes in Chart FX support scrolling.

To enable scrolling you must enable the Chart object's Scrollable property as follows:

Chart1.Scrollable = True

chart1.Scrollable = true;

Chart1.Scrollable = True

Chart1.Scrollable = True

The scroll bar will appear docked to the right next to the axis labels as depicted in the figure.

The user can now drag the scroll bar thumb to a desired position in the chart.

The advantage of using a scroll bar is that data points will not be crunched inside the chart area and most points can show their respective labels. This enhances the chart's readability and allows the user to select portions of the chart at a time.

Controlling the Scroll Position programmatically

Although the scroll bar is an end user tool, you may want to control the number of points that are visible in a specific chart. This can easily be done with the SetScrollView method supported by the Axis object.

For a categorical axis, this method receives the index of the points you want to see in the chart. For example, if you have 300 points and you want to force Chart FX to show points 30 to 60 in the categorical axis, you can set the SetScrollView method as follows:

Chart1.AxisX.SetScrollView(30,60)

chart1.AxisX.SetScrollView(30,60);

Chart1.AxisX.SetScrollView 30, 60

Chart1.AxisX.SetScrollView 30, 60

For a numerical axis, the SetScrollView method receives the values that want to show in a specific scroll view. For example, if your numerical axis is scaled between 0 and 300 and you want to set a scroll view between 10.5 and 50.5, you can set the ScrollView method as follows:

Chart1.AxisY.SetScrollView(10.5,50.5)

chart1.AxisY.SetScrollView(10.5,50.5);

Chart1.AxisY.SetScrollView 10.5, 50.5

Chart1.AxisY.SetScrollView 10.5, 50.5

Similarly, Chart FX will dispatch a UserScroll event every time the user interacts with the axis scroll bar. This event is particularly useful if you need to synchronize several charts as the user interacts with a scroll bar.

Please refer to the Chart FX API for more information on the UserScroll event supported by Chart FX.

The PixPerUnit Property

Essentially, the SetScrollView method uses the PixPerUnit property of the axis to control how labels are displayed. The PixPerUnit property allows you to specify the amount of physical pixels each tick mark will occupy in the chart. For example, if you have labeled the X-axis with long strings you may increase the size of each tick mark so that each label may be visible.

The PixPerUnit property is very useful when you want to create a scroll bar associated with the selected axis or to increase the separation between tick marks. The PixPerUnit effect varies depending on which type of axis to which it is applied, as follows:

PixPerUnit in a Categorical Axis

When you set a PixPerUnit to a categorical axis (e.g. X-axis), the value is an integer that will set the separation (physical distance measured in pixels) between major tick marks.

You may want to change the PixPerUnit value for a categorical axis when:

1) The labels associated with the chart are too long and do not fit in the allotted space. In this particular case, the PixPerUnit should be increased. If all points do not fit in one screen a scroll bar will be shown. This scenario requires the Scrollable Property to be set to TRUE.

2) You want to fit more points in one screen. In this particular case, the PixPerUnit should be decreased. You must be careful with Labels associated with each tick mark if the PixPerUnit is too small.

3) You want to view a specific amount of points per screen. In this particular case, we recommend the use of the SetScrollView method as it will allow you to set these values without any calculations on your part.

4) If you don't want to show a scroll bar, you may set the PixPerUnit to zero (0). This will remove the scroll bar for that axis and Chart FX will set the appropriate PixPerUnit to fit all values in one screen.

PixPerUnit in a Numerical Axis

When applied to a numerical axis (e.g. Y-axis), the PixPerUnit property is very useful to display a scroll bar and allow users to scroll through data without affecting the scale (Min, Max, Step) of the axis.

Because a numerical axis can be displayed in different units (currency, scientific, date, etc.), it is sometimes difficult to imagine what a PixPerUnit measures. This concept is even more complex when we take into consideration that a numerical axis ranges in different values (millions, thousands, fractions, etc).

When applied to a numerical axis, the PixPerUnit value is no longer an integer. The general rule of thumb is to take the size allotted to the chart (in pixels) divide it by the Maximum in the numerical axis and then divide that number by the number of pages you want the scroll bar to have.

For example, if you have a 400 pixel chart that ranges between Min=0 and Max=1 million and you want to create a scroll bar that contains 5 pages, the PixPerUnit should be set to:

PixPerUnit = (400/1000000)/5 = 0.00008, this means there are 0.00008 pixels per unit in the Y-axis.

On the other hand, if the same chart would have ranged between 0 and 1, the PixPerUnit setting must be calculated as follows:

PixPerUnit = (400/1)/5 = 80

Setting the PixPerUnit to zero(0) will remove the scroll bar and let Chart FX calculate the appropriate PixPerUnit value.


Gridlines and Tickmarks

In some situations, you may want to make use of gridlines and tick marks to improve the chart's readability. You have learned that you can control scaling with the Step property and MinorStep property. It is important to note that you can create and control gridlines and tick marks around major and minor units in the chart. These elements allow the user to easily detect when a particular value is plotted as a certain value or within a certain range.

Both the AxisX and AxisY objects list properties that allow you to set parameters that configure gridlines and tick marks on any axes of the chart. However, it is important to understand where gridlines and tick marks are positioned in the chart.

You must remember axis labels are placed in the major unit controlled by the Step property. Visual line attributesmay be applied to gridlines using the Grid property in conjunction with the supported Line class members(Color, Style, Width, EndCap and StartCap). The Gridlines property is used to show or hide the grid lines in the chart area, and the TickMark property is used to control tick marks. In the figure shown below it is easy to identify a step of 10, with tick marks placed outside the axis and Dash-Dotted blue gridlines:

Dim axis As Axis = Chart1.AxisY
axis.Step = 10
axis.Gridlines = True
axis.TickMark = TickMark.Outside
axis.Grid.Style = System.Drawing.Drawing2D.DashStyle.Dot
axis.Grid.Color = Color.FromArgb(0, 0, 128)

Axis axis = chart1.AxisY;
axis.Step = 10;
axis.Gridlines = true;
axis.TickMark = TickMark.Outside;
axis.Grid.Style = System.Drawing.Drawing2D.DashStyle.Dot;
axis.Grid.Color = Color.FromArgb(0, 0, 128);

Dim axis
Set axis = Chart1.AxisY
axis.Step = 10
axis.Gridlines = True
axis.TickMark = TickMark_Outside
axis.Grid.Style = DashStyle_Dot
axis.Grid.Color = RGB(0,0,128)

Dim axis as Object
Set axis = Chart1.AxisY
axis.Step = 10
axis.Gridlines = True
axis.TickMark = TickMark_Outside
axis.Grid.Style = DashStyle_Dot
axis.Grid.Color = RGB(0,0,128)

Similarly, when you set a minor unit using the MinorStep property, labels will not be shown in this location but gridlines and tick marks can be set. For example, in the figure shown below, the MinorStep property has been set to 5 with minor tick marks shown as a "cross" and a solid gridline associated with the minor unit:

Dim axis As Axis = Chart1.AxisY
axis.MinorStep = 5
axis.MinorGridLines = True
axis.MinorTickMark = TickMark.Cross
axis.MinorGrid.Style = System.Drawing.Drawing2D.DashStyle.Solid
axis.MinorGrid.Color = Color.FromArgb(128, 128, 255)

Axis axis = chart1.AxisY;
axis.MinorStep = 5;
axis.MinorGridlines = true;
axis.MinorTickMark = TickMark.Cross;
axis.MinorGrid.Style = System.Drawing.Drawing2D.DashStyle.Solid;
axis.MinorGrid.Color = Color.FromArgb(128, 128, 255);

Dim axis
Set axis = Chart1.AxisY
axis.MinorStep = 5
axis.MinorGridlines = True
axis.MinorTickMark = TickMark_Cross
axis.MinorGrid.Style = DashStyle_Solid
axis.MinorGrid.Color = RGB(128,128,255)

Dim axis as Object
Set axis = Chart1.AxisY
axis.MinorStep = 5
axis.MinorGridlines = True
axis.MinorTickMark = TickMark_Cross
axis.MinorGrid.Style = DashStyle_Solid
axis.MinorGrid.Color = RGB(128,128,255)

Interlaced Grids

In some cases interlaced gridlines greatly improve the chart's readability, as depicted in the following figure:

To achieve this effect, you need to set the chart's InsideColor property, the line's Color and the axis AlternateColor properties with the color you want for the interlaced stripes, plus set the Interlaced property supported in the Axis object. If you don't specify this color Chart FX will create a color based on the InsideColor property setting.

The code needed to acheive this is as follows:

Chart1.InsideColor = Color.Silver
Dim axis As Axis = Chart1.AxisY
axis.Grid.Color = Color.Black
axis.AlternateColor = Color.White
axis.Interlaced = True

chart1.InsideColor = Color.Silver;
Axis axis = chart1.AxisY;
axis.Grid.Color = Color.Black;
axis.AlternateColor = Color.White;
axis.Interlaced = true;

chart1.InsideColor = RGB(192,192,192)
Dim axis
Set axis = Chart1.AxisY
axis.Grid.Color = RGB(0,0,0)
axis.AlternateColor = RGB(255,255,255)
axis.Interlaced = True

Chart1.InsideColor = RGB(192,192,192)
Dim axis as Object
Set axis = Chart1.AxisY
axis.Grid.Color = RGB(0,0,0)
axis.AlternateColor = RGB(255,255,255)
axis.Interlaced = True


Multiple Axes

Chart FX supports the creation of multiple axes so you can plot values in different scales on the same chart. This section describes how you can create and assign series to additional axes in the chart.

Please note that additional axes must be referenced through the Axis object that takes an index of the axis and lists all properties and techniques described previously in this chapter.

Creating a Secondary Y-axis

In order to create a two series chart with the first series' values ranging between 1-100 and the second series' values ranging between 100000-200000, the first series will not be visible because the scale chosen by Chart FX will be between 0 - 200000, making all values between 0-100 invisible to the eye.

In this case, you may want to assign one of the series to a secondary Y-axis and assign a completely different scale by accessing the Y-axis property in the Series object as follows:

Chart1.Series(1).YAxis = YAxis.Secondary

chart1.Series[1].YAxis = YAxis.Secondary;

Chart1.Series(1).YAxis = YAxis_Secondary

Chart1.Series(1).YAxis = YAxis_Secondary

Important Note: You must assign the series to the secondary Y-axis BEFORE the chart is populated. This will allow Chart FX to initialize the secondary Y-axis appropriately. If you can't assign the series before the data is passed, you must invoke the RecalcScale method so all of the axes are recalculated.

Essentially, you will use the same properties that you have read about in this chapter to handle scales, gridlines and different settings for the secondary Y-axis. For example, if you want to set the Min, Max and Step and Decimals for the secondary Y-axis, you will use the Axis object with the 1 index to access the secondary Y Axis as follows:

Dim axis As Axis = Chart1.Axis(1)
axis.Min = 300000
axis.Max = 2500000
axis.Step = 200000
axis.LabelsFormat.Decimals = 0

Axis axis = chart1.Axis[1];
axis.Min = 300000;
axis.Max = 2500000;
axis.Step = 200000;
axis.LabelsFormat.Decimals = 0;

Dim axis
Set axis = Chart1.Axis(1)
axis.Min = 300000
axis.Max = 2500000
axis.Step = 200000
axis.LabelsFormat.Decimals = 0

Dim axis as Object
Set axis = Chart1.Axis(1)
axis.Min = 300000
axis.Max = 2500000
axis.Step = 200000
axis.LabelsFormat.Decimals = 0

The secondary Y-axis will be shown to the right of the chart as depicted in the following figure:

Creating Additional Axes

Creating and displaying additional axes in the chart is very similar to assigning a secondary Y-axis.

For example, if you want to add a third series to the previous chart, which values range between 0 and 1; both scales (0-100 and 0-2000000) are still inadequate to represent fractions between 0 and 1. Therefore, we need a fourth axis to represent these values. Please remember that three axes are already displayed in the chart: Y-axis, Secondary Y-axis and the X Axis.

To do this we will assign the third series to the Y-axis who's index is 3, as follows:

Chart1.Series(2).YAxis = 3

chart1.Series[2].YAxis = 3;

Chart1.Series(2).YAxis = 3

Chart1.Series(2).YAxis = 3

Please remember Chart FX indexes are zero based, therefore the code shown above should be read: assign the third series to a fourth axis.

Also remember this code must be invoked before the chart is populated so Chart FX can initialize the fourth axis properly. If this can't be done, then use the RecalcScale method after populating the chart.

Then you can use properties exposed by the Axis(3) object to configure the chart. For example, to show the new axis on the left side you can use the Position property as follows:

Dim axis As Axis = Chart1.Axis(3)
axis.Position = AxisPosition.Near
axis.Visible = True

Axis axis = chart1.Axis[3];
axis.Position = AxisPosition.Near;
axis.Visible = true;

Dim axis
Set axis = Chart1.Axis(3)
axis.Position = AxisPosition_Near
axis.Visible = True

Dim axis as Object
Set axis = Chart1.Axis(3)
axis.Position = AxisPosition_Near
axis.Visible = True

The example shown above can be repeated for as many axes as needed in your chart.


Chart Panes

The Panes feature of Chart FX allows the developer to display multiple panes of data in a single chart window. This data analysis feature allows developers to separate or combine several series allowing for improved analysis experience. This could be used for many applications, the most obvious being to simplify the display of a chart.

In the sample below, three series are each assigned to in individual pane. As you can see, each pane as several attributes unique per pane instance, such as the InsideBackObject, InsideColor, Proportion, Separation and Title. Also observe how each of the panes has an independent axis.

Populating Panes
Adding a series to a selected pane is as easy as assigning a chart axis to a pane. As you know, you can assign a data series to a selected axis object in the chart. Chart FX also supports the creating of multiple axes. Therefore, developers may create an additional axis for each pane. Assign a series to each of the newly created axes. And finally, set each of the axes to a selected pane. Please note that multiple series may be configured to a single pane as well.

Pane Attributes
The Pane attributes are the collection of API members that allow the developer to control basic visual attributes for a selected pane item. Please see the short description of each below, for further details please review the API reference:

  • InsideBackObject - This member is used to configure a BackgroundImage or GradientBackground object to a chart pane. For more information regarding creating GradientBackrounds, please see the Visual Attributes of the Programmer's Guide/Interactive samples in the Chart FX Resource Center.
  • InsideColor - This member is used to get or set a inside color for a selected Pane object.
  • Proportion - This member is used to get or set a value indicating the proportional size of the selected pane. For example, lets say there are three panes in a chart. Pane1's proportion is configured to the value "1". Pane2's proportion is configured to the value "2". Pane3's proportion is set to the value of "1" as well. Now assuming the entire charting area represents 100%, Pane1 will use 25% of the chart area, Pane2 will use 50%, and Pane3 will use 25%. Note that other chart tools configured as visible in the chart area may also affect the size of the panes.
  • Separation - This member is used to get or set a value indicating the space in between panes. The Proportion property may be used to configure the height of panes in a chart.
  • Title - This member is used to obtain the Title object used for a selected Pane object. All the supported members of the Title class are exposed for the pane's title.


Axis Sections

The Axis Section implementation is another analytical feature embedded into Chart FX. Utilizing this object in your charting applications allows end users to quickly identify focus areas of a chart and determine whether values fall into this range. This analytic enhancement makes data driven charts more pleasing to the eye and easily deciphered by users.

The AxisSection class allows the creation and customization of the configured chart axes. This provides the developer with a way to emphasize axis sections in order to improve readability of charts. To create an axis section, first you must specify which Axis object in the chart you want to create a section. This can be done using the AxisX or AxisY properties of the Chart object:

' Obtain an AxisSection Object for the X and Y Axes
Dim as1 As AxisSection = chart1.AxisY.Sections(0)
Dim as2 As AxisSection = chart1.AxisX.Sections(0)

// Obtain an AxisSection Object for the X and Y Axes
AxisSection as1 = chart1.AxisY.Sections[0];
AxisSection as2 = chart1.AxisX.Sections[0];

' Obtain an AxisSection Object for the X and Y Axes
Dim as1
Set as1 = Chart1.AxisY.Sections(0)
Dim as2
Set as2 = Chart1.AxisX.Sections(0)

' Obtain an AxisSection Object for the X and Y Axes
Dim as1 as Object
Set as1 = Chart1.AxisY.Sections(0)
Dim as2 as Object
Set as2 = Chart1.AxisX.Sections(0)

Note: You may also use the Axis property instead of the AxisX and AxisY properties. You may also configure multiple sections per axis.

Once the AxisSection object has been created, you may specify the range (To and From), the BackColor, grids and grid attributes, tick marks, and much more. Many of the properties supported by the Axis object itself are customizable for the AxisSection object. Please see the API reference for a complete overview of the AxisSection and AxisSectionBase classes.

For examples of the implementation for AxisSection objects, please refer to the Interactive Samples section in the Chart FX Resource Center.


Data Driven Labeling

The most basic means of customizing X Axis labeling is accomplished by passing string values to the chart. This method is effective, however, does not allow Chart FX to play much of a role in determining labeling dynamically. To improve the label handling for Chart FX, the Data Driven Labeling feature has been implemented. Please note this feature is only available for the X Axis and for chart galleries that do not normally support an X value (Bars, Gantt, etc.).

Using this feature in conjunction with the Smart Labeling implementation, developers may create charts with categorical axes charts that include dynamic labeling functionality. By simply passing X Values to chart galleries types that do not normally accept an X Value, developers can configure Chart FX to dynamically label the X Axis.

Lets say that you wish to display a Bar chart and display dates in the X Axis as labels. Previously, developers would need to pass the data and then set the desired string as the label. However, with the data driven feature implemented, simply passing an X Value will instruct Chart FX to use that value as a label and dynamically paint 'nice' labels.

The following code may be used to pass an X Value to a categorical bar chart, utilizing the Data Driven Labeling feature:

Dim dt As New DateTime(2003, 1, 1)
Dim r As New Random()

Chart1.AxisX.LabelsFormat.Format = AxisFormat.Date
Chart1.AxisX.LabelAngle = 90

Chart1.OpenData(COD.Values, 1, 365)
Chart1.OpenData(COD.XValues, 1, 365)

For i = 0 To 0
   For j = 0 To 364
       Chart1.Value(i, j) = r.NextDouble() * 100
       Chart1.XValue(i, j) = dt.AddDays(j).ToOADate()
   Next j
Next i
Chart1.CloseData(COD.Values)
Chart1.CloseData(COD.XValues)

DateTime dt = new DateTime(2003,1,1);
Random r = new Random();

chart1.AxisX.LabelsFormat.Format = AxisFormat.Date;
chart1.AxisX.LabelAngle = 90;

chart1.OpenData(COD.Values,1,365);
chart1.OpenData(COD.XValues,1,365);

for (int i=0;i<1;i++)
   for(int j=0;j<365;j++)
   {
      chart1.Value[i,j] = r.NextDouble() *100;
      chart1.XValue[i,j] = dt.AddDays(j).ToOADate();
   }
chart1.CloseData(COD.Values);
chart1.CloseData(COD.XValues);

Dim dt
dt = DateSerial(2003,1,1)

Chart1.AxisX.LabelsFormat.Format = AxisFormat_Date
Chart1.AxisX.LabelAngle = 90

Chart1.OpenData COD_Values, 1, 365
Chart1.OpenData COD_XValues, 1, 365

For i = 0 To 0
      For j = 0 To 364
          Chart1.Value(i, j) = (Rnd()) * 100
          Chart1.XValue(i, j) = CDbl(DateAdd("d",CDbl(j),dt))
      Next
Next
Chart1.CloseData COD_Values
Chart1.CloseData COD_XValues

Dim dt
dt = DateSerial(2003,1,1)
Chart1.AxisX.LabelsFormat.Format = AxisFormat_Date
Chart1.AxisX.LabelAngle = 90
Chart1.OpenData COD_Values, 1, 365
Chart1.OpenData COD_XValues, 1, 365
For i = 0 To 0
      For j = 0 To 364
          Chart1.Value(i, j) = (Rnd()) * 100
          Chart1.XValue(i, j) = CDbl(DateAdd("d",CDbl(j),dt))
      Next
Next
Chart1.CloseData COD_Values
Chart1.CloseData COD_XValues


Properties and Attributes

Chart FX supports a myriad of general chart properties exposed by the Chart class that allows the assignment of attributes directly to elements present in a given chart. These general properties are considered to be global for the chart because when assigned, they take affect for all points and series contained within the chart.

However, there are times when setting these properties globally does not allow you to generate the chart output you desire to display to end users. Chart FX exposes the Point and Series objects, which provide the mechanism for setting per-point and per-series attributes for a selected chart.

By providing these objects in Chart FX, the developer may create combination charts (Gallery type) as well as setting per-point and per-series attributes that can help convey information to end users. For example, you can color markers individually or separate a pie slice from a pie chart based on a condition.

General Properties

General chart properties are exposed by the Chart class and when configured affect all points and series included in the selected chart. An example of setting a general chart property is setting the chart's Gallery or chart type. Setting the gallery for the chart using the Chart class Gallery property will set a chart type globally, in other words, only one chart type will be displayed at a time (Bar, Lines, etc.).

Chart1.Gallery = Gallery.Area

chart1.Gallery = Gallery.Area;

Chart1.Gallery = Gallery_Area

Chart1.Gallery = Gallery_Area

Some other supported members of the Chart class include the Border, BorderColor, BorderEffect, CylSides, MarkerShape, MarkerSize, PointLabels, Scheme, TypeMask, Volume, MarkerStep, etc. These are just a few of the general properties exposed by the Chart class, for more supported members please reference the Chart FX API Reference.

Per-Series Attributes

The SeriesAttributes class exposes many of the same properties described as General properties, however, when configured only affect the selected series in the chart. By allowing customization on a per-series basis, Chart FX provides the developer with more control over the supported chart elements. Setting different chart galleries for selected series in a chart permits you to create combination charts to convey more information to the end users at one time. The Series object also allows you to set visual attributes to a series that can bring attention to a selected series. Below is an example of creating a combination chart with two series:

Chart1.Series(0).Gallery = Gallery.Area
Chart1.Series(1).Gallery = Gallery.Lines

chart1.Series[0].Gallery = Gallery.Area;
chart1.Series[1].Gallery = Gallery.Lines;

Chart1.Series(0).Gallery = Gallery_Area
Chart1.Series(1).Gallery = Gallery_Lines

Chart1.Series(0).Gallery = Gallery_Area
Chart1.Series(1).Gallery = Gallery_Lines

Per-Point Attributes

The PointAttributes class also exposes many of the same properties available in the Chart class. Once again, giving the developer access to the point object increases the control over charts generated using Chart FX. The supported PointAttributes class members allow you to set border, color, marker, point label and scheme attributes, as well as many others, directly to a selected point included in the chart.

Setting per-point attributes is most useful for highlighting special points or groups of points within charts. By highlighting selected points in a chart, you can focus the attention of end users to specific information conveyed in the chart. Another useful tool when setting per-point attributes is the user legend box. The user legend box is configured exclusively by the developer and can act as a legend for these special points.

The following code sets the color for a particular point to red; this could be used to show a high or low level for that particular point:

Chart1.Point(1,3).Color = Color.Red

chart1.Point[1,3].Color = Color.Red;

Chart1.Point(1, 3).Color = RGB(255,0,0)

Chart1.Point(1, 3).Color = RGB(255,0,0)

When setting per-point attributes you should also consider efficiency of code, specifically the reuse of per-point attribute objects. In the following code sample, every time the color is assigned for a particular point, a new point attribute is created in memory:

totSeries = Chart1.NSeries
totValues = Chart1.NValues

For i = 0 To totSeries - 1
    For j = 0 To (totValues - 1)
        If (Chart1.Value(i, j) >= myLimit) Then
            'Red to the points that plot above the limit
            Chart1.Point(i, j).Color = Color.Red
        Else
            ' Blue color to the points that plot inside the limit
            Chart1.Point(i, j).Color = Color.Blue
        End If
    Next j
Next i

totSeries = chart1.NSeries;
totValues = chart1.NValues;

for (int i=0;i<totSeries;i++)
    for (int j=0;j<totValues;j++)
        if (chart1.Value[i, j] >= myLimit) {
           //Red to the points that plot above the limit
           chart1.Point[i, j].Color = Color.Red;
        }
        else {
          // Blue color to the points that plot inside the limit
          chart1.Point[i, j].Color = Color.Blue;
        }

totSeries = chart1.NSeries
totValues = chart1.NValues

For i = 0 To (totSeries - 1)
      For j = 0 To (totValues - 1)
          If ((Chart1.Value(i, j)) >= CDbl(myLimit)) Then
             'Red to the points that plot above the limit
             Chart1.Point(i, j).Color = RGB(255,0,0)
          Else
             ' Blue color to the points that plot inside the limit
             Chart1.Point(i, j).Color = RGB(0,0,255)
          End If
      Next
Next

totSeries = chart1.NSeries
totValues = chart1.NValues
For i = 0 To (totSeries - 1)
      For j = 0 To (totValues - 1)
          If ((Chart1.Value(i, j)) >= CDbl(myLimit)) Then
             'Red to the points that plot above the limit
             Chart1.Point(i, j).Color = RGB(255,0,0)
          Else
             ' Blue color to the points that plot inside the limit
             Chart1.Point(i, j).Color = RGB(0,0,255)
          End If
      Next
Next

Notice even though there are more lines of code in this example, only two point attribute objects are created; this code is more efficient, takes less memory and will run much faster:

Dim myLimit As Integer = 50
Dim totSeries As Integer = chart1.NSeries()
Dim totValues As Integer = chart1.NValues()

' Create PointAttributes objects
Dim redPoints As New PointAttributes(Chart1)
redPoints.Color = Color.Red

Dim bluePoints As New PointAttributes(Chart1)
bluePoints.Color = Color.Blue

For i = 0 To totSeries - 1
   For j = 0 To totValues - 1
      If Chart1.Value(i, j) >= myLimit Then
          ' Red for points that plot above the limit
          Chart1.Point(i, j) = redPoints
      Else
          ' Blue for points that plot below the limit
          Chart1.Point(i, j) = bluePoints
      End If
   Next j
Next i

int myLimit = 50;
int totSeries = chart1.NSeries;
int totValues = chart1.NValues;

// Create PointAttributes objects
PointAttributes redPoints = new PointAttributes(chart1);
redPoints.Color = Color.Red;

PointAttributes bluePoints = new PointAttributes(chart1);
bluePoints.Color = Color.Blue;

for (int i=0;i<totSeries;i++)
   for (int j=0;j<totValues;j++)
   {
      if (chart1.Value[i,j] >= myLimit){
         // Red for points that plot above the limit
         chart1.Point[i, j] = redPoints;
      }
      else {
         // Blue for points that plot below the limit
         chart1.Point[i, j] = bluePoints;
      }
   }

Dim myLimit
myLimit = 50
Dim totSeries
totSeries = Chart1.NSeries
Dim totValues
totValues = Chart1.NValues

' Create PointAttributes objects
Dim redPoints
Set redPoints = Server.CreateObject("ChartFX.ASP.PointAttributes")
redPoints.Color = RGB(255,0,0)

Dim bluePoints
Set bluePoints = Server.CreateObject("ChartFX.ASP.PointAttributes")
bluePoints.Color = RGB(0,0,255)

For i = 0 To (totSeries - 1)
      For j = 0 To (totValues - 1)
          If ((Chart1.Value(i, j)) >= (CDbl(myLimit))) Then
             ' Red for points that plot above the limit
             Chart1.Point(i, j) = redPoints
          Else
           ' Blue for points that plot below the limit
            Chart1.Point(i, j) = bluePoints
          End If
      Next
Next

Dim myLimit as Integer
myLimit = 50
Dim totSeries as Integer
totSeries = Chart1.NSeries
Dim totValues as Integer
totValues = Chart1.NValues
' Create PointAttributes objects
Dim redPoints as PointAttributes
Set redPoints = New PointAttributes
redPoints.Color = RGB(255,0,0)
Dim bluePoints as PointAttributes
Set bluePoints = New PointAttributes
bluePoints.Color = RGB(0,0,255)
Dim i as Integer
i = 0
Do While (i < totSeries)
    Dim j as Integer
    j = 0
    Do While (j < totValues)
        If ((Chart1.Value(i, j)) >= (CDbl(myLimit))) Then
' Red for points that plot above the limit
            Chart1.Point(i, j) = redPoints
        Else
' Blue for points that plot below the limit
            Chart1.Point(i, j) = bluePoints
        End If
        j = j + 1
    Loop
    i = i + 1
Loop

Also, when you reuse a point attribute object, you can change all the assigned points by modifying the existing object once, rather than looping back through all the points:

redPoints.Color = Color.Yellow a

redPoints.Color = Color.Yellow;

redPoints.Color = RGB(255,255,0)

redPoints.Color = RGB(255,255,0)


Labels

Chart FX supports a variety of different labeling capabilities. The two most common label types are the axis labels and series labels. Smart labeling and data driven labeling features provide advanced label handling functionality for Chart FX, while other API members allow developers to configure short or abbreviated axis, series and z-axis labels.

Labels may be configured in a number of ways. By default, Chart FX will attempt to label a selected axis based on its configured format (numerical by default). When data is passed to Chart FX via one of the supported Data Providers, Chart FX will use string fields for labels and numerical fields for chart values.

Chart FX will determine these assignments using built-in algorithms, however, developers may also configure how fields will be used within a chart by utilizing the DataType property. By specifying a field as a Label, you can control exactly what values will be painted as labels in the chart.

Note: Legends may also be configured using the DataType property when using a supported Chart FX Data Provider. Please see the Passing Data section in the programmer's guide for more information.

Setting Labels using the API

Setting the Labels for an axis may be done using the Axis object Label member. This property is used to read/write labels for a categorical axis. By default, the X axis is a categorical axis containing labels associated with each major tick mark, while the Y axis label is a numerical axis where labels are controlled by the scale (Min, Max, etc) and numerical data contained in the chart.

You can set as many labels as points are available in the chart. These labels will be shown in the major tick marks of the selected axis. Some of them can be left empty so no labels are shown on that specific major tick mark.

You can control how frequent these labels are displayed by using the Step property. Label Visual attributes like rotation, color and font are also accessible through the LabelAngle, TextColor, and Font properties, respectively.

By default, Chart FX does not associate any labels to the categorical axis (X axis) and a "TAG" number will be shown. When you use this property, the TAG numbers will be replaced by settings specified in this property.

When used in conjunction with the LabelValue property, this property can be used to set string values to a numerical axis.

You can easily remove all labels set to an axis with the ClearLabels method.

The following code could be employed to set the X Axis labels to the months of the year:

Chart1.AxisX.Label(0) = "January"
Chart1.AxisX.Label(1) = "February"
Chart1.AxisX.Label(2) = "March"
Chart1.AxisX.Label(3) = "April"
Chart1.AxisX.Label(4) = "May"
Chart1.AxisX.Label(5) = "June"
Chart1.AxisX.Label(6) = "July"
Chart1.AxisX.Label(7) = "August"
Chart1.AxisX.Label(8) = "September"
Chart1.AxisX.Label(9) = "October"
Chart1.AxisX.Label(10) = "November"
Chart1.AxisX.Label(11) = "December"

chart1.AxisX.Label[0] = "January";
chart1.AxisX.Label[1] = "February";
chart1.AxisX.Label[2] = "March";
chart1.AxisX.Label[3] = "April";
chart1.AxisX.Label[4] = "May";
chart1.AxisX.Label[5] = "June";
chart1.AxisX.Label[6] = "July";
chart1.AxisX.Label[7] = "August";
chart1.AxisX.Label[8] = "September";
chart1.AxisX.Label[9] = "October";
chart1.AxisX.Label[10] = "November";
chart1.AxisX.Label[11] = "December";

Chart1.AxisX.Label(0) = "January"
Chart1.AxisX.Label(1) = "February"
Chart1.AxisX.Label(2) = "March"
Chart1.AxisX.Label(3) = "April"
Chart1.AxisX.Label(4) = "May"
Chart1.AxisX.Label(5) = "June"
Chart1.AxisX.Label(6) = "July"
Chart1.AxisX.Label(7) = "August"
Chart1.AxisX.Label(8) = "September"
Chart1.AxisX.Label(9) = "October"
Chart1.AxisX.Label(10) = "November"
Chart1.AxisX.Label(11) = "December"

Chart1.AxisX.Label(0) = "January"
Chart1.AxisX.Label(1) = "February"
Chart1.AxisX.Label(2) = "March"
Chart1.AxisX.Label(3) = "April"
Chart1.AxisX.Label(4) = "May"
Chart1.AxisX.Label(5) = "June"
Chart1.AxisX.Label(6) = "July"
Chart1.AxisX.Label(7) = "August"
Chart1.AxisX.Label(8) = "September"
Chart1.AxisX.Label(9) = "October"
Chart1.AxisX.Label(10) = "November"
Chart1.AxisX.Label(11) = "December"

Note: The Chart classLegend property may also be used to configure X axis labels.

KeyLeg Property

You normally use the Label or Legend property to assign labels to the tick marks in the x-axis (when it is categorical). However, depending on the amount of points in the chart, these labels may be too long to properly fit in the space allotted for each tick mark in the x-axis.

Although you can control how frequent or how these labels are displayed with other properties supported by the Axis object, sometimes you still have space limitations because of the size of the chart or the number of points.

This property can help you display shorter labels in the x-axis while maintaining longer labels in the legend window. Let's give you an example:

Let's suppose you have assigned the following labels to the x-axis with the Legend property:
"January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November" and "December"

Now, these labels may or may not fit in the space allotted for each tick mark in the x-axis. If one of them does not fit, Chart FX will immediately display a TAG (red number) indicating that such label cannot fit in the space allotted for it. This problem increases as the number of points in the chart increase.

With this property you can assign key labels (shorter strings) like:
"Jan","Feb","Mar",Apr", etc.

These will be displayed in the x-axis itself, while the Legend window will display both the Key Legend and the Legend set with the Label property as depicted in the following figure:

Chart1.KeyLeg(0) = "Jan"
Chart1.KeyLeg(1) = "Feb"
Chart1.KeyLeg(2) = "Mar"
Chart1.KeyLeg(3) = "Apr"
Chart1.KeyLeg(4) = "May"
Chart1.KeyLeg(5) = "Jun"
Chart1.KeyLeg(6) = "Jul"
Chart1.KeyLeg(7) = "Aug"
Chart1.KeyLeg(8) = "Sep"
Chart1.KeyLeg(9) = "Oct"
Chart1.KeyLeg(10) = "Nov"
Chart1.KeyLeg(11) = "Dec"

chart1.KeyLeg[0] = "Jan";
chart1.KeyLeg[1] = "Feb";
chart1.KeyLeg[2] = "Mar";
chart1.KeyLeg[3] = "Apr";
chart1.KeyLeg[4] = "May";
chart1.KeyLeg[5] = "Jun";
chart1.KeyLeg[6] = "Jul";
chart1.KeyLeg[7] = "Aug";
chart1.KeyLeg[8] = "Sep";
chart1.KeyLeg[9] = "Oct";
chart1.KeyLeg[10] = "Nov";
chart1.KeyLeg[11] = "Dec";

Chart1.KeyLeg(0) = "Jan"
Chart1.KeyLeg(1) = "Feb"
Chart1.KeyLeg(2) = "Mar"
Chart1.KeyLeg(3) = "Apr"
Chart1.KeyLeg(4) = "May"
Chart1.KeyLeg(5) = "Jun"
Chart1.KeyLeg(6) = "Jul"
Chart1.KeyLeg(7) = "Aug"
Chart1.KeyLeg(8) = "Sep"
Chart1.KeyLeg(9) = "Oct"
Chart1.KeyLeg(10) = "Nov"
Chart1.KeyLeg(11) = "Dec"

Chart1.KeyLeg(0) = "Jan"
Chart1.KeyLeg(1) = "Feb"
Chart1.KeyLeg(2) = "Mar"
Chart1.KeyLeg(3) = "Apr"
Chart1.KeyLeg(4) = "May"
Chart1.KeyLeg(5) = "Jun"
Chart1.KeyLeg(6) = "Jul"
Chart1.KeyLeg(7) = "Aug"
Chart1.KeyLeg(8) = "Sep"
Chart1.KeyLeg(9) = "Oct"
Chart1.KeyLeg(10) = "Nov"
Chart1.KeyLeg(11) = "Dec"

Series Legend

Setting the Labels for an axis may be done using the Series class Legend member. This property is used to read/write legends for selected series in the chart. It is important to specify the correct index in for the Series object in order to set the correct legend string.

To configure the series legend for a chart, the following code may be used:

Chart1.Series(0).Legend = "Product A"
Chart1.Series(1).Legend = "Product B"
Chart1.Series(2).Legend = "Product C"
Chart1.Series(3).Legend = "Product D"
Chart1.Series(4).Legend = "Product F"

chart1.Series[0].Legend = "Product A";
chart1.Series[1].Legend = "Product B";
chart1.Series[2].Legend = "Product C";
chart1.Series[3].Legend = "Product D";
chart1.Series[4].Legend = "Product F";

Chart1.Series(0).Legend = "Product A"
Chart1.Series(1).Legend = "Product B"
Chart1.Series(2).Legend = "Product C"
Chart1.Series(3).Legend = "Product D"
Chart1.Series(4).Legend = "Product F"

Chart1.Series(0).Legend = "Product A"
Chart1.Series(1).Legend = "Product B"
Chart1.Series(2).Legend = "Product C"
Chart1.Series(3).Legend = "Product D"
Chart1.Series(4).Legend = "Product F"

The SerLeg property may also be used to accomplish the same series legend assignment:

Chart1.SerLeg(0) = "Product A"
Chart1.SerLeg(1) = "Product B"
Chart1.SerLeg(2) = "Product C"
Chart1.SerLeg(3) = "Product D"
Chart1.SerLeg(4) = "Product F"

chart1.SerLeg[0] = "Product A";
chart1.SerLeg[1] = "Product B";
chart1.SerLeg[2] = "Product C";
chart1.SerLeg[3] = "Product D";
chart1.SerLeg[4] = "Product F";

Chart1.SerLeg(0) = "Product A"
Chart1.SerLeg(1) = "Product B"
Chart1.SerLeg(2) = "Product C"
Chart1.SerLeg(3) = "Product D"
Chart1.SerLeg(4) = "Product F"

Chart1.SerLeg(0) = "Product A"
Chart1.SerLeg(1) = "Product B"
Chart1.SerLeg(2) = "Product C"
Chart1.SerLeg(3) = "Product D"
Chart1.SerLeg(4) = "Product F"

Once you have set a series legend to some (or all) series in the chart, you can treat the legend window as an additional tool with different properties that can be accessed using the Series Legend object. This object may be returned by the SerLegBoxObj property exposed by the Chart class.

SerKey Property

The SerKey property may be used to label the series in the Z-Axis when a chart is clustered (3D). It may also be used on configured a short series legend label, much like the KeyLeg proeprty. Here is some quick sample code showing how to set labels for the Z-Axis of a clustered bar chart:

Dim r As New Random()
Chart1.Cluster = True
Chart1.OpenData(COD.Values, 5, 6)
For i = 0 To 4
   For j = 0 To 5
      Chart1.Value(i, j) = 100 * r.NextDouble()
      Chart1.SerLeg(i) = "S" +(i + 1).ToString()
      Chart1.SerKey(i) = "S" +(i + 1).ToString()
   Next j
Next i
Chart1.CloseData(COD.Values)

Random r = new Random();
chart1.Cluster = true;
chart1.OpenData(COD.Values,5,6);
for (int i=0;i<5;i++)
   for (int j=0;j<6;j++)
   {
      chart1.Value[i,j] = 100 * r.NextDouble();
      chart1.SerLeg[i] = "S" + (i+1).ToString();
      chart1.SerKey[i] = "S" + (i+1).ToString();
   }
chart1.CloseData(COD.Values);

Chart1.Cluster = True
Chart1.OpenData COD_Values, 5, 6
For i = 0 To 4
      For j = 0 To 5
          Chart1.Value(i, j) = 100 * (Rnd())
          Chart1.SerLeg(i) = "S" + (CStr((i + 1)))
          Chart1.SerKey(i) = "S" + (CStr((i + 1)))
      Next
Next
Chart1.CloseData COD_Values

Chart1.Cluster = True
Chart1.OpenData COD_Values, 5, 6
Dim i as Integer
i = 0
Do While (i < 4)
    Dim j as Integer
    j = 0
    Do While (j < 5)
        Chart1.Value(i, j) = 100 * (Rnd())
        Chart1.SerLeg(i) = "S" + (CStr((i + 1)))
        Chart1.SerKey(i) = "S" + (CStr((i + 1)))
        j = j + 1
    Loop
    i = i + 1
Loop
Chart1.CloseData COD_Values


Smart Labeling

The Smart Labeling feature paint labels for charts automatically by evaluating X values and determining the best logical step to view data clearly. This feature is embedded into Chart FX; therefore, it is by default in effect. However, by manually configuring a selected axis step, this feature may be easily overridden.

Note: The Smart Labeling feature is only employed when Date and DateTime X Values are present in a chart. Please review XY Plots & Scatter in the Gallery Types section of the Programmer's Guide for more information on these types of graphs.

This feature has been found to be most helpful developers and useful to end-users when chart data includes date and time as X Values. This feature is also commonly used in conjunction with Data Driven Labeling. For more information regarding this topic, please see the Data Driven Labeling section of this reference.

Depending on the values passed to the chart and the dimensions of the chart (width), Chart FX will calculate a 'nice' increment to display for the labels. For example, when you have a year of data, and they chart size permits, each month could be used for the string. When dealing with date-formatted axes, the label step is as follows:

  • Year
  • Semi-Anual
  • Quarter
  • Bi-Monthly
  • Month
  • Bi-Weekly
  • Day

It is also important to mention the last day of a label break will be used for the label. For example, when the 'Bi-Monthly' step is applied, the last day of the 2-month range will be used as the label string (painting the tick mark and label on that day). Inversely, when the range has a name, such as a Year, Quarter or Month, each section will be labeled using a Centered style and using the appropriate name.

When dealing with time-formatted axes, additional label steps are supported. The label steps for time are as follows:

  • 12 hour
  • 6 hour
  • 1 hour
  • 1/2 hour
  • 1/4 hour
  • 10 min
  • 5 min
  • 1 min
  • 30 sec
  • 15 sec
  • 10 sec
  • 5 sec
  • 1 sec
  • less that 0.5 sec leave alone

Note: If you manually configure the axis scale using the Step property of the Axis object, all the smart labeling logic is disregarded.

Below is some sample code that forces Chart FX to utilize the embedded Smart Labeling feature. If you set the Dock property of the chart to Fill for the chart in a windows form applications and resize the chart, you will see how the scale will change based on the size of the chart. This is the Smart Labeling feature at work.

Chart1.Dock = System.Windows.Forms.DockStyle.Fill

Dim dt As New DateTime(2004, 1, 1)
Dim r As New Random()

Chart1.MarkerShape = MarkerShape.None
Cchart1.Gallery = Gallery.Lines

Chart1.AxisX.LabelsFormat.Format = AxisFormat.Date
Chart1.AxisX.LabelAngle = 90

Chart1.OpenData(COD.Values, 1, 365)
Chart1.OpenData(COD.XValues, 1, 365)
For i = 0 To 0
   For j = 0 To 364
      Chart1.Value(i, j) = r.NextDouble() * 100
      Chart1.XValue(i, j) = dt.AddDays(j).ToOADate()
   Next j
Next i
chart1.CloseData(COD.Values)
chart1.CloseData(COD.XValues)

chart1.Dock = System.Windows.Forms.DockStyle.Fill;

DateTime dt = new DateTime(2004,1,1);
Random r = new Random();

chart1.MarkerShape = MarkerShape.None;
chart1.Gallery = Gallery.Lines;

chart1.AxisX.LabelsFormat.Format = AxisFormat.Date;
chart1.AxisX.LabelAngle = 90;

chart1.OpenData(COD.Values,1,365);
chart1.OpenData(COD.XValues,1,365);

for (int i=0;i<1;i++)
   for(int j=0;j<365;j++)
   {
       chart1.Value[i,j] = r.NextDouble() *100;
       chart1.XValue[i,j] = dt.AddDays(j).ToOADate();
   }
chart1.CloseData(COD.Values);
chart1.CloseData(COD.XValues);

Dim dt
dt = DateSerial(2004,1,1)

Chart1.MarkerShape = MarkerShape_None
Chart1.Gallery = Gallery_Lines

Chart1.AxisX.LabelsFormat.Format = AxisFormat_Date
Chart1.AxisX.LabelAngle = 90

Chart1.OpenData COD_Values, 1, 365
Chart1.OpenData COD_XValues, 1, 365

For i = 0 To 0
      For j = 0 To 364
          Chart1.Value(i, j) = (Rnd()) * 100
          Chart1.XValue(i, j) = CDbl(DateAdd("d",CDbl(j),dt))
      Next
Next
Chart1.CloseData COD_Values
Chart1.CloseData COD_XValues

Dim dt
dt = DateSerial(2004,1,1)
Chart1.MarkerShape = MarkerShape_None
Chart1.Gallery = Gallery_Lines
Chart1.AxisX.LabelsFormat.Format = AxisFormat_Date
Chart1.AxisX.LabelAngle = 90
Chart1.OpenData COD_Values, 1, 365
Chart1.OpenData COD_XValues, 1, 365
For i = 0 To 0
      For j = 0 To 364
          Chart1.Value(i, j) = (Rnd()) * 100
          Chart1.XValue(i, j) = CDbl(DateAdd("d",CDbl(j),dt))
      Next
Next
Chart1.CloseData COD_Values
Chart1.CloseData COD_XValues

This code will produce the following Chart:

As you resize the form, the labeling will be changing as shown in the following pictures:


Chart Titles

To improve a chart's readability, Chart FX supports the creation of titles that you can use to create a chart's main title. A title is a string that can be assigned to any portion outside the main chart area.

This string can be positioned, aligned and formatted according to the different properties supported by TitleDockable object that supports an unlimited number of titles in the chart area. Titles can be assigned via the Chart FX designer properties list or you can create and control them programmatically.

By default, all the titles you create will be positioned at top of the chart, or where the main chart title is displayed. For example, if you add the following code to an event handler (button) it will create a title on the top portion of the chart.

Chart1.Titles(0).Text = "My Chart Title"

chart1.Titles[0].Text = "My Chart Title";

Chart1.Titles(0).Text = "My Chart Title"

Chart1.Titles(0).Text = "My Chart Title"

You can create multi-line titles by simply adding an additional title in the same position. These lines can then be independently aligned and formatted.

The Title object supports a series of properties that you can use to align, position and format the different titles in the chart. For example, the following code adds a main title and labels the chart's Y-axis.

Dim title1 As Title = Chart1.Titles(0)
title1.Alignment = System.Drawing.StringAlignment.Center
title1.Font = New System.Drawing.Font("Arial", 16.75)
title1.Text = "My Chart Title"
title1.TextColor = System.Drawing.Color.White
title1.BackColor = Color.DarkBlue
title1.DrawingArea = False

Dim title2 As TitleDockable = Chart1.Titles(1)
title2.DockArea = DockArea.Left
title2.LineAlignment = StringAlignment.Far
title2.Font = New System.Drawing.Font("Arial", 10.75)
title2.Text = "Sales in Dollars"
title2.TextColor = System.Drawing.Color.Black

Title title1 = chart1.Titles[0];
title1.Alignment = System.Drawing.StringAlignment.Center;
title1.Font = new System.Drawing.Font("Arial", (float) 16.75);
title1.Text = "My Chart Title";
title1.TextColor = System.Drawing.Color.White;
title1.BackColor = Color.DarkBlue;
title1.DrawingArea = false;

TitleDockable title2 = chart1.Titles[1];
title2.DockArea = DockArea.Left;
title2.LineAlignment = StringAlignment.Far;
title2.Font = new System.Drawing.Font("Arial", (float) 10.75);
title2.Text = "Sales in Dollars";
title2.TextColor = System.Drawing.Color.Black;

Dim title1
Set title1 = Chart1.Titles(0)
title1.Alignment = StringAlignment_Center
title1.Font.Name = "Arial"
title1.Font.Size = 16.75
title1.Text = "My Chart Title"
title1.TextColor = RGB(255,255,255)
title1.BackColor = RGB(0,0,139)
title1.DrawingArea = False

Dim title2
Set title2 = Chart1.Titles(1)
title2.DockArea = DockArea_Left
title2.LineAlignment = StringAlignment_Far
title2.Font.Name = "Arial"
title2.Font.Size = 10.75
title2.Text = "Sales in Dollars"
title2.TextColor = RGB(0,0,0)

Dim title1 as Object
Set title1 = Chart1.Titles(0)
title1.Alignment = StringAlignment_Center
title1.Font.Name = "Arial"
title1.Font.Size = 16.75
title1.Text = "My Chart Title"
title1.TextColor = RGB(255,255,255)
title1.BackColor = RGB(0,0,139)
title1.DrawingArea = False
Dim title2 as Object
Set title2 = Chart1.Titles(1)
title2.DockArea = DockArea_Left
title2.LineAlignment = StringAlignment_Far
title2.Font.Name = "Arial"
title2.Font.Size = 10.75
title2.Text = "Sales in Dollars"
title2.TextColor = RGB(0,0,0)

TitleDockable Class

The TitleDockable class supports the DockArea property and LineAlignment property that allow a title to be docked in the chart area. In order to utilize this functionality, you must create your title objects as a TitleDockable object. In the previous sample, title2 was created using the TitleDockable class.


Axes Titles

Titles can be created on a chart's axes. They can be assigned, aligned and formatted according to the different properties supported by Title object. Axes Titles can be assigned via the Chart FX designer properties list or you can create and control them programmatically.

All Axes titles you create, by default, are aligned at the center. For example, if you add the following code:

Chart1.AxisX.Title.Text = "X Axis Title"
Chart1.AxisY.Title.Text = "Y Axis Title"

chart1.AxisX.Title.Text = "X Axis Title";
chart1.AxisY.Title.Text = "Y Axis Title";

Chart1.AxisX.Title.Text = "X Axis Title"
Chart1.AxisY.Title.Text = "Y Axis Title"

Chart1.AxisX.Title.Text = "X Axis Title"
Chart1.AxisY.Title.Text = "Y Axis Title"

You will get the following chart:

Axes Titles are attached to the Axis to which they belong. If the Y-axis gets moved to the right side of the chart (Far), the Y-axis Title will get moved there as well. If the X-axis is hidden, the X-axis Title will be hidden also.

You can create a multi-line title by including the newline character (\n) within the Title Text:

Chart1.AxisY.Title.Text = "Unit Sales" + chr(10)+ "(In Millions)"

chart1.AxisY.Title.Text = "Unit Sales \n (In Millions)";

Chart1.AxisY.Title.Text = "Unit Sales " + VbCrLf + " (In Millions)"

Chart1.AxisY.Title.Text = "Unit Sales "+VbCrLf+" (In Millions)"


Color Palettes

In most situations, you will want to assign colors to chart elements like markers, backgrounds and labels. However, our design team invested a lot of time creating default color palettes for Chart FX. This way, when you create a chart and populate it with data, everything looks nice and consistent (even if you have not taken the time to assign default colors to chart elements).

If you buy into the Chart FX way of coloring your chart, you'll find out Chart FX provides other palettes that you, or your end users, can use to quickly change the chart.

Essentially, Palettes are a group of colors that will apply to the different elements in the chart. When a palette is changed all the elements that have not been forced to have a specific color will adapt to the new palette.

Using palettes from the Chart FX interface

Palettes provide a special functionality since they allow end users to customize the chart colors with a single click. All default and extended palettes are listed in the Chart FX toolbar as a combo box that can be used to preview or apply a desired palette to the current chart. The image below shows the supported palettes which are available from the toolbar:

Please refer to the "Tool Customization" for more information on displaying and customizing the Toolbar in the Chart.

Using Palettes programmatically

Palettes are supported through your IDE properties list or you can load and apply them through the chart using the Palette property.

Please note, the palette property receives a string parameter with the name of the palette you want to load. Chart FX supports the following default palettes: Windows, Alternate, EarthTones, ModernBusiness, ChartFX6.

Each of these palettes belongs to a default palette list in Chart FX. Therefore, the "Default." String must precede each of these names to properly load the palette. The Palette property must be set as follows:

Chart1.Palette = "Default.EarthTones"

chart1.Palette = "Default.EarthTones";

Chart1.Palette = "Default.EarthTones"

Chart1.Palette = "Default.EarthTones"

Please note Chart FX palettes are extensible. This means, you can create and integrate your own palettes programmatically, or let your users use them through the Chart FX Toolbar. We have used this functionality to create 7 additional palettes in Chart FX:

  • Natural.Sky
  • Natural.Adventure
  • Mesa
  • Vivid
  • ChartFX5
  • HighContrast
  • DarkPastels.Pastels

To properly load these palettes, you will simply use their string names as follows:

Chart1.Palette = "Natural.Adventure"

chart1.Palette = "Natural.Adventure";

Chart1.Palette = "Natural.Adventure"

Chart1.Palette = "Natural.Adventure"

Important Note: For more information on extending palettes and the palettes file format, please contact support or visit the Chart FX support site.

Palette Naming Convention

Notice how the many of the palettes use a name consisting of two words separated by a period (DarkPastels.Pastels). Each of the Chart FX palettes is derived from a base color scheme, the "first word". The unique combination of colors used to create a selected palette from a base color scheme is the "second word" in the name. Therefore, if a base color scheme only has one combination, the second word is not required. This can be observed in the Vivid palette for example. Because there is only one palette existing in Vivid, you only need to specify the base color scheme to complete the configuration:

Chart1.Palette = "Vivid"

chart1.Palette = "Vivid";

Chart1.Palette = "Vivid"

Chart1.Palette = "Vivid"


Chart FX Image Borders

Until the advent of the Internet as a viable development platform, desktop applications were developed with strict user interface guidelines. This put constraints on a developer's ability to let components integrate custom interfaces or designs that could jeopardize the application's accessibility.

Nevertheless, the Internet, and more specifically HTML, promoted a new breed of applications. Today, both desktop and browser-based applications must distinguish themselves with original designs and innovative user interfaces. In this regard, Chart FX has pioneered the charting industry by adding features and tools that help developers to integrate extraordinary charts into their desktop applications and web sites with minimal programming effort.

No other charting product provides the graphic pizzazz and innovative tools that Chart FX offers today. Charts now support features like smoothing, transparency, gradients, double-buffering repainting and many others. However, of all the features built into Chart FX geared to enhance the chart's presentation layer, none stand out more than Image Borders.

The GDI+ API alpha blending capability is used to display Chart FX image borders. These borders consist of a series of bitmaps that have transparent or semi-transparent pixels. In addition to a red, green, and blue color channel, each pixel in a border bitmap has a transparency component known as its alpha channel.

The alpha channel lets you control the color of the chart background as well as the color of the HTML page or form while keeping the effect of the border intact, resulting in an outstanding presentation effect for your charts without the restrictions imposed by static bitmaps that can't be changed programmatically.

Image Borders are very simple to integrate and require little or no programming efforts on your part. Also, image borders are supported in a separate assembly that allows you to decide if you want to use and deploy them as part of your application or server.

This section will show you how you can display image borders on your Chart FX applications.

Borders and Background Color

The Chart FX ImageBorders use shading and great edge detail to give a multidimensional effect when they are placed in your forms. When using image borders, you will want them to seamlessly integrate into your page or form design. If you have set the background color of your form to a color other that white, an undesirable white block will be visible around the chart.

The PageColor property can be used to modify the background color of the shaded area around ImageBorders. Setting the PageColor property to match the background color of the webpage will achieve a seamless visual effect.

'Set the page color to blue
Chart1.PageColor = Color.Blue

//Set the page color to blue
chart1.PageColor = Color.Blue;

'Set the page color to blue
Chart1.PageColor = RGB(0,0,255)

'Set the page color to blue
Chart1.PageColor = RGB(0,0,255)

The following code instantiates a new border object and assigns it to the chart. Please note how the Border Object exposes a variable called Color that can be used to change the border color

Dim myBorder As ImageBorder
myBorder = New ImageBorder(ImageBorderType.SolidLines)
myBorder.Color = Color.Beige
Chart1.BorderObject = myBorder

ImageBorder myBorder;
myBorder = new ImageBorder(ImageBorderType.SolidLines);
myBorder.Color = Color.Beige;
chart1.BorderObject = myBorder;

Dim myBorder
Set myBorder = Server.CreateObject("ChartFX.ASP.ImageBorder")
myBorder.Type = ImageBorderType_SolidLines
myBorder.Color = RGB(245,245,220)
Chart1.BorderObject = myBorder

Dim myBorder as Cfx62ClientServerBorders.ImageBorder
Set myBorder = New Cfx62ClientServerBorders.ImageBorder
myBorder.Type = ImageBorderType_SolidLines
myBorder.Color = RGB(245,245,220)
Chart1.BorderObject = myBorder

Note: You can also integrate and display image borders from the Chart FX Wizard and Properties List (if supported, through the BorderObject property). The advantage of adding borders using these tools is that you can quickly select among the different supported borders visually, instead of adding the code, compiling and running the application.

Borders and other chart tools

Finally, it is important to mention, Chart FX image borders are prepared to handle additional tools and windows that can be displayed in the chart area, including Toolbar, Legend windows and Data Editor.

The chart displayed uses an Embed image border and notice how the different elements are properly rendered with the same border type.


Gradients in Chart Markers

In most situations, gradients are commonly used to achieve a cosmetic fill effect on a particular shape. However, when used in chart markers, Chart FX gradients serve a different purpose as they allow the user to immediately recognize data trends and help the user recognize important data in the chart.

To illustrate, the chart displayed uses a gradient fill that allows the user to immediately recognize markers that fall within a range with just a quick glance at the chart.

To achieve this effect, you must set a special color scheme that activates the markers' gradient fill. Then, Chart FX defines a virtual rectangle that starts at the top of the chart (defined by the Y-axis Max) and uses the marker color as a starting point (top) and an alternate color to blend uniformly to the bottom (X-axis).

The code that creates the gradient shown above looks as follows:

' First set the Gradient Scheme
Chart1.Scheme = SoftwareFX.ChartFX.Scheme.Gradient

' Then change the Series Color and Alternate Color
Dim series As SeriesAttributes = Chart1.Series(0)
series.Color = Color.Yellow
series.AlternateColor = Color.Green

// First set the Gradient Scheme
chart1.Scheme = SoftwareFX.ChartFX.Scheme.Gradient;
// Then change the Series Color and Alternate Color
SeriesAttributes series  = chart1.Series[0];
series.Color = Color.Yellow;
series.AlternateColor = Color.Green;

' First set the Gradient Scheme
chart1.Scheme = Scheme_Gradient

' Then change the Series Color and Alternate Color
Dim series
Set series = Chart1.Series(0)
series.Color = RGB(255,255,0)
series.AlternateColor = RGB(0,128,0)

' First set the Gradient Scheme
Chart1.Scheme = Scheme_Gradient
' Then change the Series Color and Alternate Color
Dim series as Object
Set series = Chart1.Series(0)
series.Color = RGB(255,255,0)
series.AlternateColor = RGB(0,128,0)

It is important to note marker gradients are used for data analysis purposes in Chart FX. Therefore, marker gradients accept only two colors and are limited to a vertical effect.

Finally, please remember the Y-axis Maximum will significantly affect the virtual rectangle on which the gradient is going to be painted. For example, in the chart shown above if the Y-axis Maximum is changed from 100 to 200, all chart markers will have an intensity close to the alternate color (green) as they will be farther away from the top of the chart where the marker color (yellow) is used.


Gradients in Chart Background

As opposed to marker gradients, background gradients are used for cosmetic purposes only. In other words, background gradients are only used to enhance the chart's visual appearance and have no direct relation to the data contained in the chart.

In Chart FX, gradients can be applied to 2 rectangular areas in the chart area: The chart's inside background and the main background.

Chart FX allows horizontal, vertical, diagonal and radial gradients when applying gradient fills to either of these areas of the chart.

In order to create background gradients, you can use the Chart FX Wizard, or you can use Chart FX objects and its properties to create and display gradient fills.

By default, the color in a linear gradient changes uniformly. However, in this chapter you will learn how to use the Chart FX API so you can create and customize linear gradients so that the color may change in a non-uniform fashion.

Creating a gradient object

Creating a gradient object is no more than instantiating an object from the ChartFX.Borders.dll called GradientBackground. The following code creates a new variable and instantiates a new gradient object:

' First create the variable
Dim myGradient as GradientBackground

' Then instantiate the object
myGradient = New GradientBackground(GradientType.ForwardDiagonal)

// First create the variable
GradientBackground myGradient;

// Then instantiate the object
myGradient = new GradientBackground(GradientType.ForwardDiagonal);

' First create the variable
Dim myGradient

' Then instantiate the object
Set myGradient = Server.CreateObject("ChartFX.ASP.GradientBackground")
myGradient.Type = GradientType_ForwardDiagonal

' First create the variable
Dim myGradient as Cfx62ClientServerBorders.GradientBackground
' Then instantiate the object
Set myGradient = New Cfx62ClientServerBorders.GradientBackground
myGradient.Type = GradientType_ForwardDiagonal

Please note the GradientBackground object constructor receives a parameter indicating the type of gradient you want to create. Your development environment InstelliSense feature should help you choose your desired gradient effect.

Assigning the gradient object to any of the chart backgrounds

Once you have created the gradient object you can set properties like colors and positions. This topic is covered in detail in the following sections. Once these properties have been set, you will need to assign the gradient object to the appropriate chart background.

To assign the gradient to the chart inside background, your code will look as follows:

' First create the variable
Dim myGradient as GradientBackground

' Then instantiate the object
myGradient = New GradientBackground(GradientType.ForwardDiagonal)

Chart1.InsideBackObject = myGradient

// First create the variable
GradientBackground myGradient;

// Then instantiate the object
myGradient = new GradientBackground(GradientType.ForwardDiagonal);

chart1.InsideBackObject = myGradient;

' First create the variable
Dim myGradient

' Then instantiate the object
Set myGradient = Server.CreateObject("ChartFX.ASP.GradientBackground")
myGradient.Type = GradientType_ForwardDiagonal

Chart1.InsideBackObject = myGradient

' First create the variable
Dim myGradient as Cfx62ClientServerBorders.GradientBackground
' Then instantiate the object
Set myGradient = New Cfx62ClientServerBorders.GradientBackground
myGradient.Type = GradientType_ForwardDiagonal
Chart1.InsideBackObject = myGradient

Or, to assign the gradient to the chart main background, you will use the BackObject and it is important you remember to set the Inside background to a transparent color so the gradient is visible across the entire chart area, as follows:

' First create the variable
Dim myGradient as GradientBackground

' Then instantiate the object
myGradient = New GradientBackground(GradientType.ForwardDiagonal)

Chart1.BackObject = myGradient
Chart1.InsideColor = Color.Transparent

// First create the variable
GradientBackground myGradient;

// Then instantiate the object
myGradient = new GradientBackground(GradientType.ForwardDiagonal);

chart1.BackObject = myGradient;
chart1.InsideColor = Color.Transparent;

' First create the variable
Dim myGradient

' Then instantiate the object
Set myGradient = Server.CreateObject("ChartFX.ASP.GradientBackground")
myGradient.Type = GradientType_ForwardDiagonal

Chart1.BackObject = myGradient
Chart1.InsideColor = CHART_ARGB(0,0,0,0)

' First create the variable
Dim myGradient as Cfx62ClientServerBorders.GradientBackground
' Then instantiate the object
Set myGradient = New Cfx62ClientServerBorders.GradientBackground
myGradient.Type = GradientType_ForwardDiagonal
Chart1.BackObject = myGradient
Chart1.InsideColor = Chart.ColorFromArgb(0, 0, 0, 0)

Manipulating gradient colors, positions

Once the gradient object has been instantiated, you can manipulate the object's properties to set visual attributes like colors, positions and color intensity. The following section will show you how to create multicolor and bi-color gradients.

Essentially, a gradient object provides a Color array property that you can use to set the colors you want for your gradient. These colors will then be uniformly blended in the chart's background by dividing the bounding rectangle into equal sections and blending from one color to another in the Color array. For example, you can set the following color array for your gradient:

Dim myGradient as GradientBackground
myGradient = New GradientBackground(GradientType.ForwardDiagonal)

' Filling the color array
myGradient.Color(0) = Color.Blue
myGradient.Color(1) = Color.Red
myGradient.Color(2) = Color.Yellow
myGradient.Color(3) = Color.Green

Chart1.InsideBackObject = myGradient

GradientBackground myGradient;
myGradient = new GradientBackground(GradientType.ForwardDiagonal);

// Filling the color array
myGradient.Color[0] = Color.Blue;
myGradient.Color[1] = Color.Red;
myGradient.Color[2] = Color.Yellow;
myGradient.Color[3] = Color.Green;

chart1.InsideBackObject = myGradient;

Dim myGradient
Set myGradient = Server.CreateObject("ChartFX.ASP.GradientBackground")
myGradient.Type = GradientType_ForwardDiagonal

' Filling the color array
myGradient.Colors.Item(0) = RGB(0,0,255)
myGradient.Colors.Item(1) = RGB(255,0,0)
myGradient.Colors.Item(2) = RGB(255,255,0)
myGradient.Colors.Item(3) = RGB(0,128,0)

Chart1.InsideBackObject = myGradient

Dim myGradient as Cfx62ClientServerBorders.GradientBackground
Set myGradient = New Cfx62ClientServerBorders.GradientBackground
myGradient.Type = GradientType_ForwardDiagonal
' Filling the color array
myGradient.Colors.Item(0) = RGB(0,0,255)
myGradient.Colors.Item(1) = RGB(255,0,0)
myGradient.Colors.Item(2) = RGB(255,255,0)
myGradient.Colors.Item(3) = RGB(0,128,0)
Chart1.InsideBackObject = myGradient

The preceding code, if applied to the chart's inside background will create a Forward Diagonal gradient with 3 regions that will blend uniformly:

1) from Blue to Red

2) from Red to Yellow

3) from Yellow to Green

If this arrangement is not convenient, you may alter the positions of each blending area by using the Position array supported by the GradientBackground object.

To understand how positions work in the bounding rectangle, imagine the first position (where the gradient starts) as position 0; the ending position would then be 1 and then intermediate positions would be fractions between 0 and 1.

For example, in our previous example if we wanted the gradient from blue to red to occupy only 10% of the bounding rectangle and the gradient from Red to Yellow to fill 70% of the area, we could have used the Position array as follows:

Dim myGradient as GradientBackground
myGradient = New GradientBackground(GradientType.ForwardDiagonal)

' Filling the color array
myGradient.Color(0) = Color.Blue
myGradient.Color(1) = Color.Red
myGradient.Color(2) = Color.Yellow
myGradient.Color(3) = Color.Green

' Filling the Position array
myGradient.Position(0) = 0
myGradient.Position(1) = 0.1
myGradient.Position(2) = 0.8
myGradient.Position(3) = 1

Chart1.InsideBackObject = myGradient

GradientBackground myGradient;
myGradient = new GradientBackground(GradientType.ForwardDiagonal);

// Filling the color array
myGradient.Color[0] = Color.Blue;
myGradient.Color[1] = Color.Red;
myGradient.Color[2] = Color.Yellow;
myGradient.Color[3] = Color.Green;

// Filling the Position array
myGradient.Position[0] = 0;
myGradient.Position[1] = 0.1F;
myGradient.Position[2] = 0.8F;
myGradient.Position[3] = 1;

chart1.InsideBackObject = myGradient;

Dim myGradient
Set myGradient = Server.CreateObject("ChartFX.ASP.GradientBackground")
myGradient.Type = GradientType_ForwardDiagonal

' Filling the color array
myGradient.Colors.Item(0) = RGB(0,0,255)
myGradient.Colors.Item(1) = RGB(255,0,0)
myGradient.Colors.Item(2) = RGB(255,255,0)
myGradient.Colors.Item(3) = RGB(0,128,0)

' Filling the Position array
myGradient.Position.Item(0) = 0
myGradient.Position.Item(1) = 0.1
 myGradient.Position.Item(2) = 0.8
myGradient.Position.Item(3) = 1

Chart1.InsideBackObject = myGradient

Dim myGradient as Cfx62ClientServerBorders.GradientBackground
Set myGradient = New Cfx62ClientServerBorders.GradientBackground
myGradient.Type = GradientType_ForwardDiagonal
' Filling the color array
myGradient.Colors.Item(0) = RGB(0,0,255)
myGradient.Colors.Item(1) = RGB(255,0,0)
myGradient.Colors.Item(2) = RGB(255,255,0)
myGradient.Colors.Item(3) = RGB(0,128,0)
' Filling the Position array
myGradient.Position.Item(0) = 0
myGradient.Position.Item(1) = 0.1
myGradient.Position.Item(2) = 0.8
myGradient.Position.Item(3) = 1
Chart1.InsideBackObject = myGradient

Bi-Color Gradients

In some cases, you may want to work with bi-color gradients and simply repeat a gradient pattern across the chart's background. If this is the case, instead of defining a Color array with the 2 same colors over and over, you can simply create a bi-color gradient.

A bi-color gradient requires Position and Factor (color intensity) arrays to display a repeating pattern across the chart's background. Previously we described the effect the Position array had on the gradient. In bi-color gradients a new Factor array must be defined to instruct Chart FX on the color intensity on each position.

To understand the Factor array, consider that the values it takes are a fraction between the 2 colors in the color array. If set to 0, then the resulting color will be the color available in the position 0 of the Color array and similarly with a value of 1.

For example take a closer look at the Factor array and the effect it creates on the gradient in the following 2 samples:

myGradient.Color(0) = Color.Blue
myGradient.Color(1) = Color.Red

myGradient.Position(0) = 0
myGradient.Position(1) = 0.25
myGradient.Position(2) = 0.75
myGradient.Position(3) = 1

myGradient.Factor(0) = 0
myGradient.Factor(1) = 1
myGradient.Factor(2) = 0
myGradient.Factor(3) = 1

myGradient.Color[0] = Color.Blue;
myGradient.Color[1] = Color.Red;

myGradient.Position[0] = 0;
myGradient.Position[1] = 0.25F;
myGradient.Position[2] = 0.75F;
myGradient.Position[3] = 1;

myGradient.Factor[0] = 0;
myGradient.Factor[1] = 1;
myGradient.Factor[2] = 0;
myGradient.Factor[3] = 1;

myGradient.Colors.Item(0) = RGB(0, 0, 255)
myGradient.Colors.Item(1) = RGB(255, 0, 0)

myGradient.Position.Item(0) = 0
myGradient.Position.Item(1) = 0.25
myGradient.Position.Item(2) = 0.75
myGradient.Position.Item(3) = 1

myGradient.Factor.Item(0) = 0
myGradient.Factor.Item(1) = 1
myGradient.Factor.Item(2) = 0
myGradient.Factor.Item(3) = 1

myGradient.Colors.Item(0) = RGB(0, 0, 255)
myGradient.Colors.Item(1) = RGB(255, 0, 0)

myGradient.Position.Item(0) = 0
myGradient.Position.Item(1) = 0.25
myGradient.Position.Item(2) = 0.75
myGradient.Position.Item(3) = 1

myGradient.Factor.Item(0) = 0
myGradient.Factor.Item(1) = 1
myGradient.Factor.Item(2) = 0
myGradient.Factor.Item(3) = 1

myGradient.Color(0) = Color.Blue
myGradient.Color(1) = Color.Red

myGradient.Position(0) = 0
myGradient.Position(1) = 0.25
myGradient.Position(2) = 0.75
myGradient.Position(3) = 1

myGradient.Factor(0) = 0
myGradient.Factor(1) = 0.8
myGradient.Factor(2) = 0.9
myGradient.Factor(3) = 0

myGradient.Color[0] = Color.Blue;
myGradient.Color[1] = Color.Red;

myGradient.Position[0] = 0;
myGradient.Position[1] = 0.25F;
myGradient.Position[2] = 0.75F;
myGradient.Position[3] = 1;

myGradient.Factor[0] = 0;
myGradient.Factor[1] = 0.8F;
myGradient.Factor[2] = 0.9F;
myGradient.Factor[3] = 0;

myGradient.Colors.Item(0) = RGB(0, 0, 255)
myGradient.Colors.Item(1) = RGB(255, 0, 0)

myGradient.Position.Item(0) = 0
myGradient.Position.Item(1) = 0.25
myGradient.Position.Item(2) = 0.75
myGradient.Position.Item(3) = 1

myGradient.Factor.Item(0) = 0
myGradient.Factor.Item(1) = 0.8
myGradient.Factor.Item(2) = 0.9
myGradient.Factor.Item(3) = 0

myGradient.Colors.Item(0) = RGB(0, 0, 255)
myGradient.Colors.Item(1) = RGB(255, 0, 0)

myGradient.Position.Item(0) = 0
myGradient.Position.Item(1) = 0.25
myGradient.Position.Item(2) = 0.75
myGradient.Position.Item(3) = 1

myGradient.Factor.Item(0) = 0
myGradient.Factor.Item(1) = 0.8
myGradient.Factor.Item(2) = 0.9
myGradient.Factor.Item(3) = 0

Please note the Factor array does not apply to multicolor gradients (3 or more colors).


Transparency

With transparency, you can make chart elements such as background pictures and gradients that apply to the entire chart completely invisible in the chart area. Also note that this setting can be applied to any chart element that receives a color. For example, if you have a scatter chart and you want to hide certain points, you can use the Point property and assign a transparent color to only certain points in the chart.

Essentially, transparency is achieved by setting the 4th parameter in the Color constructor as follows:

Chart1.InsideColor = Color.Transparent

chart1.InsideColor = Color.Transparent;

Chart1.InsideColor = CHART_ARGB(0,0,0,0)

Chart1.InsideColor = Chart.ColorFromArgb(0, 0, 0, 0)

Note: Setting the BackColor property to transparent is only supported when generating PNG images using the Chart FX.

Semi-Transparency

In Chart FX, the alpha blending feature is used to display a chart element that has semi-transparent pixels. In addition to a red, green and blue color channel, each pixel in an alpha bitmap has a transparency component known as its alpha channel. The alpha channel typically contains as many bits as a color channel. For example, an 8-bit alpha channel can represent 256 levels of transparency, from 0 (the entire pixel is transparent) to 255 (the entire pixel is opaque). For example, if you want to make the third series of your chart a semi-transparent green, you will use the code as follows:

Chart1.Series(2).Color = Color.FromArgb(120,0,255,0)

chart1.Series[2].Color = Color.FromArgb(120,0,255,0);

Chart1.Series(2).Color = CHART_ARGB(120,0,255,0)

Chart1.Series(2).Color = Chart.ColorFromArgb(120,0,255,0)

Changing the transparency of an object evenly reveals the image elements that lie beneath the object and because semi-transparency can be applied to any chart element that supports a color, you can create a myriad of effects. For example, in a 3D oblique chart, you can make the first series semi-transparent so other series are revealed in the 3D view or you can use the Point object to have particular marker(s) display semi-transparency. Similarly, you can make the chart background semi-transparent so a background image is blended into the chart, create a nice watermark effect.


Series Legend

In a multiple series chart, it is standard practice to add a box containing descriptions of the series displayed.Series legend box keys may be set using the Chart class SerLeg property or the Legend property of the SeriesAttributes class.Once you have set the legend keys, you may set position and style attributes using the SerLegBoxObj property.

Using the SerLegBoxObj property you can control the position and other important aspects of this tool in the chart.For example, the following code can be used to show and position the series legend on the bottom and to the left of the chart:

Chart1.SerLegBox = True
Chart1.SerLegBoxObj.Alignment = ToolAlignment.Near
Chart1.SerLegBoxObj.Docked = Docked.Bottom

Chart1.Series(0).Legend = "Product 1"
Chart1.Series(1).Legend = "Product 2"
Chart1.Series(2).Legend = "Product 3"

chart1.SerLegBox = true;
chart1.SerLegBoxObj.Alignment = ToolAlignment.Near;
chart1.SerLegBoxObj.Docked = Docked.Bottom;

chart1.Series[0].Legend = "Product 1";
chart1.Series[1].Legend = "Product 2";
chart1.Series[2].Legend = "Product 3";

Chart1.SerLegBox = True
Chart1.SerLegBoxObj.Alignment = ToolAlignment_Near
Chart1.SerLegBoxObj.Docked = Docked_Bottom

Chart1.Series(0).Legend = "Product 1"
Chart1.Series(1).Legend = "Product 2"
Chart1.Series(2).Legend = "Product 3"

Chart1.SerLegBox = True
Chart1.SerLegBoxObj.Alignment = ToolAlignment_Near
Chart1.SerLegBoxObj.Docked = Docked_Bottom
Chart1.Series(0).Legend = "Product 1"
Chart1.Series(1).Legend = "Product 2"
Chart1.Series(2).Legend = "Product 3"

And the chart will look like:


Chart Legend

The LegendBox is a window that shows the data point labels set with the chart's Legend property or that AxisX Label property. Usually these labels are displayed in the categorical X Axis. However, sometimes these labels are long strings and they will not fit in the space allotted for them. Showing the Legend Box with this property can help increase the chart's readability.

The LegendBox is used to display legends associated with data points (not series). It is particularly useful to improve chart readability for charts like Pie, which have no axes but point labels are still needed.

The LegendBox is always shown docked to a margin (right margin by default). Additionally, the Alignment property can be used to align the LegendBox within the margin.The Chart class LegendBoxObj property is used to set position and style attributes directly to the legend box.

For example, the following code would be used to show a LegendBox for a Pie chart docked to the left margin and aligned in the bottom of the chart area:

Chart1.LegendBox = True
Chart1.LegendBoxObj.Docked = Docked.Left
Chart1.LegendBoxObj.Alignment = ToolAlignment.Far

Chart1.Legend(0) = "January"
Chart1.Legend(1) = "February"
Chart1.Legend(2) = "March"
Chart1.Legend(3) = "April"
Chart1.Legend(4) = "May"

chart1.LegendBox = true;
chart1.LegendBoxObj.Docked = Docked.Left;
chart1.LegendBoxObj.Alignment = ToolAlignment.Far;

chart1.Legend[0] = "January";
chart1.Legend[1] = "February";
chart1.Legend[2] = "March";
chart1.Legend[3] = "April";
chart1.Legend[4] = "May";

Chart1.LegendBox = True
Chart1.LegendBoxObj.Docked = Docked_Left
Chart1.LegendBoxObj.Alignment = ToolAlignment_Far

Chart1.Legend(0) = "January"
Chart1.Legend(1) = "February"
Chart1.Legend(2) = "March"
Chart1.Legend(3) = "April"
Chart1.Legend(4) = "May"

Chart1.LegendBox = True
Chart1.LegendBoxObj.Docked = Docked_Left
Chart1.LegendBoxObj.Alignment = ToolAlignment_Far
Chart1.Legend(0) = "January"
Chart1.Legend(1) = "February"
Chart1.Legend(2) = "March"
Chart1.Legend(3) = "April"
Chart1.Legend(4) = "May"

And the chart will look like the following picture:


UserLegendBox

In most cases, the legend box and series legend box provide the necessary information that users need to successfully understand a chart. Other times, there is a void where the legend box and series legend box cannot provide this to the end user. The user legend box allows you as the developer to create legends to provide essential information about a chart that normally cannot be relayed using the series legend box or the value legend box.

A user legend box is very useful in many situations, one of which is when the number of colors in a chart is not related to the number of series in a chart. For example, when a Contour gallery type chart is used, colors in the chart represent intensity of a particular condition. By enabling the user legend box, you can define legend keys to help an end user decipher exactly what the chart is representing.

Another situation when the user legend could be very useful is when you assign per point attributes to your chart. For example, all red points may represent values over 50, where all blue points represent values under 50. A user legend box could be used to make the user understand this relation more clearly. User legends are also a great way to define or explain abbreviations or symbols that are included in financial charting applications.

Enabling the UserLegendBox

The user legend box is enabled in the same way as both the series legend box and legend box objects. The UserLegendBox property is a Boolean property, which allows you to show or hide the user legend box with one line of code.

' Show the user legend box
Chart1.UserLegendBox = True

' Hide the user legend box
Chart1.UserLegendBox = False

// Show the user legend box
chart1.UserLegendBox = true;
// Hide the user legend box
chart1.UserLegendBox = false;

' Show the user legend box
Chart1.UserLegendBox = True
' Hide the user legend box
Chart1.UserLegendBox = False

' Show the user legend box
Chart1.UserLegendBox = True
' Hide the user legend box
Chart1.UserLegendBox = False

Defining of the UserLegendBox

The beauty of the user legend box is the myriad of information that may be used to define the legend keys for the chart. The user legend will allow you to display any information you wish, however there is a trade off. In order to populate the user legend box, you will need to define every key the legend will display. To do this, Chart FX offers the UserLegendBoxObj and Item objects.

The user legend box object and supported properties provide the mechanism to customize position and style as well as to define the contents of the user legend. The UserLegendBoxObj object inherits all the properties from the SerLegBoxObj object and offers many more.
To dock the user legend box on the right side of the chart, you could use the following code:

' Dock the user legend box on the right
Chart1.UserLegendBoxObj.Docked = Docked.Right

' Make the user legend box visible
Chart1.UserLegendBox = True

// Dock the user legend box on the right
chart1.UserLegendBoxObj.Docked = Docked.Right;
// Make the user legend box visible
chart1.UserLegendBox = true;

' Dock the user legend box on the right
Chart1.UserLegendBoxObj.Docked = Docked_Right
' Make the user legend box visible
Chart1.UserLegendBox = True

' Dock the user legend box on the right
Chart1.UserLegendBoxObj.Docked = Docked_Right
' Make the user legend box visible
Chart1.UserLegendBox = True

The previous code will make the user legend box visible and docked to the right of the chart. However, there are still no keys in the legend that describe the chart content.

The Item object is collection which allows you to create and assign attributes to each key that will exist in the user legend box. The Item object has several properties that allow you to relate the configured key to the chart, such as color or marker shape.

In the sample chart shown, each bar represents the volume of calls into a tech support call center. Each bar has been assigned a color based on the number of incoming calls for that day. The user legend box has been created to describe what each color represents: Red = Warning, Yellow = Caution, or Green = Normal. The label, color, marker shape, border effect and border color for each key in the user legend needs to be configured in order display the desired information.

Below is the code used to create the user legend box of the displayed chart:

' define the first user legend key
Dim item1 As UserLegendBoxItem = Chart1.UserLegendBoxObj.Item(0)
item1.Label = "Warning"
item1.Color = Color.Red
item1.MarkerShape = MarkerShape.Rect
item1.BorderEffect = BorderEffect.None
item1.BorderColor = Color.Black

'define the second user legend key
Dim item2 As UserLegendBoxItem = Chart1.UserLegendBoxObj.Item(1)
item2.Label = "Caution"
item2.Color = Color.Yellow
item2.MarkerShape = MarkerShape.Rect
item2.BorderEffect = BorderEffect.None
item2.BorderColor = Color.Black

' define the third user legend key
Dim item3 As UserLegendBoxItem = Chart1.UserLegendBoxObj.Item(2)
item3.Label = "Normal"
item3.Color = Color.Green
item3.MarkerShape = MarkerShape.Rect
item3.BorderEffect = BorderEffect.None
item3.BorderColor = Color.Black

' Show the user legend box in the chart
Chart1.UserLegendBox = True

// define the first user legend key
UserLegendBoxItem item1 = chart1.UserLegendBoxObj.Item[0];
item1.Label = "Warning";
item1.Color = Color.Red;
item1.MarkerShape = MarkerShape.Rect;
item1.BorderEffect = BorderEffect.None;
item1.BorderColor = Color.Black;

// define the second user legend
UserLegendBoxItem item2 = chart1.UserLegendBoxObj.Item[1];
item2.Label = "Caution";
item2.Color = Color.Yellow;
item2.MarkerShape = MarkerShape.Rect;
item2.BorderEffect = BorderEffect.None;
item2.BorderColor = Color.Black;

// define the third user legend
UserLegendBoxItem item3 = chart1.UserLegendBoxObj.Item[2];
item3.Label = "Normal";
item3.Color = Color.Green;
item3.MarkerShape = MarkerShape.Rect;
item3.BorderEffect = BorderEffect.None;
item3.BorderColor = Color.Black;

// Show the user legend box in the chart
chart1.UserLegendBox = true;

' define the first user legend key
Dim item1
Set item1 = Chart1.UserLegendBoxObj.Item(0)
item1.Label = "Warning"
item1.Color = RGB(255,0,0)
item1.MarkerShape = MarkerShape_Rect
item1.BorderEffect = BorderEffect_None
item1.BorderColor = RGB(0,0,0)

' define the second user legend
Dim item2
Set item2 = Chart1.UserLegendBoxObj.Item(1)
item2.Label = "Caution"
item2.Color = RGB(255,255,0)
item2.MarkerShape = MarkerShape_Rect
item2.BorderEffect = BorderEffect_None
item2.BorderColor = RGB(0,0,0)

' define the third user legend
Dim item3
Set item3 = Chart1.UserLegendBoxObj.Item(2)
item3.Label = "Normal"
item3.Color = RGB(0,128,0)
 item3.MarkerShape = MarkerShape_Rect
item3.BorderEffect = BorderEffect_None
item3.BorderColor = RGB(0,0,0)

' Show the user legend box in the chart
Chart1.UserLegendBox = True

' define the first user legend key
Dim item1 as Object
Set item1 = Chart1.UserLegendBoxObj.Item(0)
item1.Label = "Warning"
item1.Color = RGB(255,0,0)
item1.MarkerShape = MarkerShape_Rect
item1.BorderEffect = BorderEffect_None
item1.BorderColor = RGB(0,0,0)
' define the second user legend
Dim item2 as Object
Set item2 = Chart1.UserLegendBoxObj.Item(1)
item2.Label = "Caution"
item2.Color = RGB(255,255,0)
item2.MarkerShape = MarkerShape_Rect
item2.BorderEffect = BorderEffect_None
item2.BorderColor = RGB(0,0,0)
' define the third user legend
Dim item3 as Object
Set item3 = Chart1.UserLegendBoxObj.Item(2)
item3.Label = "Normal"
item3.Color = RGB(0,128,0)
item3.MarkerShape = MarkerShape_Rect
item3.BorderEffect = BorderEffect_None
item3.BorderColor = RGB(0,0,0)
' Show the user legend box in the chart
Chart1.UserLegendBox = True


Data Editor

Chart FX provides a spreadsheet called Data Editor that allows users to see the data contained in the chart in tabular format. It also allows the user to modify any legend or value contained in the chart (if allowed by the programmer).

Just like other Chart FX tools, the end user can control position and style attributes for the Data in the chart area.

The DataEditorObjproperty provides the developer with control over the Data Editor. With this member you can control the position, color and other important aspects of this tool in the chart. For example, to show and position the Data Editor at the bottom of the chart, the DataEditorObj property may be used as follows:

Chart1.DataEditor = True
Chart1.DataEditorObj.Docked = Docked.Bottom

Chart1.Series(0).Legend = "Product 1"
Chart1.Series(1).Legend = "Product 2"
Chart1.Series(2).Legend = "Product 3"

chart1.DataEditor = true;
chart1.DataEditorObj.Docked = Docked.Bottom;
chart1.Series[0].Legend = "Product 1";
chart1.Series[1].Legend = "Product 2";
chart1.Series[2].Legend = "Product 3";

Chart1.DataEditor = True
Chart1.DataEditorObj.Docked = Docked_Bottom
Chart1.Series(0).Legend = "Product 1"
Chart1.Series(1).Legend = "Product 2"
Chart1.Series(2).Legend = "Product 3"

Chart1.DataEditor = True
Chart1.DataEditorObj.Docked = Docked_Bottom
Chart1.Series(0).Legend = "Product 1"
Chart1.Series(1).Legend = "Product 2"
Chart1.Series(2).Legend = "Product 3"

And the chart will look like:


Highlighting Features

Chart FX supports Highlighting features that improve end users readability by allowing them to select chart elements in which to focus attention. This analytic tool allows users to easily discover values in the chart. There are several scenarios in which this is very useful, for example when a large number of points are visible in the chart area. Providing this feature in the chart allows end users to highlight and discover points. When an item is highlighted in a chart, the other Chart FX tools visible also reflect the action.

By default, when only a single series is plotted in a chart and a point is highlighted, that point will retain the "highlight" status. All other series will be dimmed while the highlighted point is slightly accentuated. When there are multiple series in a chart and a user highlights a chart, the entire series is highlighted, while all other series are dimmed.

This default behavior may be easily customized; for example, instead of the default dimming action of non-selected points, developers could programmatically configure non-selected points not to change and only the selected or highlighted element display highlighted attributes.

Setting colors, styles, highlight speed, grid attributes, if enabled and much more are all possible using the HighlightSettings, HighlightGridSettings, HighlightToolSettings and HighlightEventArgs classes.

Important Note: The Highlight feature is ONLY functional when generating active charts, such as a.NET Client Control or an ActiveX chart. When rendering images in web applications, this feature is not available.

Using the chart API, you configure attributes for the chart when the OnHighlight event is raised. Here is an example of how to use the OnHighlight event in your application. Once you have attached the event to your application, you could use the point object to configure highlighted points to remain Red after even after highlighted event occurs:

Private Sub Form1_Load(ByVal sender As System.Object,
                       e As System.EventArgs) Handles MyBase.Load

   ' Chart code in this section

   ' Set Dimmed false
   chart1.Highlight.Dimmed = False

   ' Attach OnHighlight Event
   AddHandler chart1.Highlight.OnHighlight, AddressOf Me.chart1_OnHighlight

End Sub

Private Sub chart1_OnHighlight(ByVal sender As Object,
                               e As SoftwareFX.ChartFX.Base.HighlightEventArgs)

   ' Set highlighted point Red
   chart1.Point(e.Series,e.Point).Color = Color.Red

End Sub

private void Form1_Load(object sender, System.EventArgs e)
{
   // Chart code in this section

   // Set Dimmed false
   chart1.Highlight.Dimmed = false;

   // Attach OnHighlight Event
   chart1.Highlight.OnHighlight += new HighlightEventHandler(chart1_OnHighlight);
}

private void chart1_OnHighlight(object sender,
                                SoftwareFX.ChartFX.Base.HighlightEventArgs e)
{
    // Set highlighted point Red
    chart1.Point[e.Series,e.Point].Color = Color.Red;
}

HighlightSettings Class

This class is the core class for the highlighting feature. Using the supported members, you can turn the highlight feature on and off (Enabled), highlight chart items programmatically, add additional code to highlight processing (using OnHighlight event), clear highlights, control how points will be painted when highlighted and much more. The PointAttributes property returns a PointAttributes object. Using this object, you can control how points will be displayed in the chart when highlighted.

HighlightGridSettings Class

This class is used for customization of the DataEditor when a highligh event occurs. Setting colors for data cells, border colors, text color, etc.

HighlightToolSettings Class

This class is used to instruct how the other chart tools will interpret a highlight event; whether the tool will be affected by a highlight event or not.

HighlightEventArgs Class

This class supports the properties available to the developer during the OnHighlight Event.

Note: For more information regarding these objects, please refer to the Chart FX API Reference.


Constant Lines & Stripes

Constant lines

Constant lines are some of the most useful objects when it comes to highlighting information in the chart area. You may want to create constant lines to highlight limits or specific points of interest in the chart. For example, in a scientific application, you may want to use the constant line object to highlight an alarm limit, or in a financial application you may want to highlight a target price or date.

Constant lines are lines that you can draw anywhere in the chart area and associate them with a particular value in the axis that they're assigned to, as illustrated in the following figure.

All constant lines are handled by the Line and ConstantLine classes and their supported members. Using the Line class, you can control the line color, styles and width. The ContstantLine class members allow control over other attributes such as the associated axis.

Creating a constant line does not require a new data series and you can also configure labels and line styles, colors and width. If you wish to highlight a range of values instead of a specific value, please refer to the Stripe sample next in this section.

The following code creates the constant lines for the previous figure shown.

Dim constantlineHorz As ConstantLine = Chart1.ConstantLines(0)
constantlineHorz.Value = 30
constantlineHorz.Color = Color.Red
constantlineHorz.Axis = AxisItem.Y
constantlineHorz.Text = "Alarm Limit 1"
constantlineHorz.Width = 1
constantlineHorz.Style = Drawing.Drawing2D.DashStyle.Dash

Dim constantlineVert As ConstantLine = Chart1.ConstantLines(1)
constantlineVert.Value = 8
constantlineVert.Color = Color.Orange
constantlineVert.Axis = AxisItem.X
constantlineVert.Text = "Limit 2"
constantlineVert.Width = 3

ConstantLine constantlineHorz = chart1.ConstantLines[0];
constantlineHorz.Value = 30;
constantlineHorz.Color = Color.Red;
constantlineHorz.Axis = AxisItem.Y;
constantlineHorz.Text = "Alarm Limit 1";
constantlineHorz.Width = 1;
constantlineHorz.Style = Drawing.Drawing2D.DashStyle.Dash;

ConstantLine constantlineVert = chart1.ConstantLines[1];
constantlineVert.Value = 8;
constantlineVert.Color = Color.Orange;
constantlineVert.Axis = AxisItem.X;
constantlineVert.Text = "Limit 2";
constantlineVert.Width = 3;

Dim constantlineHorz
Set constantlineHorz = Chart1.ConstantLines(0)
constantlineHorz.Value = 30
constantlineHorz.Color = RGB(255,0,0)
constantlineHorz.Axis = AxisItem_Y
constantlineHorz.Text = "Alarm Limit 1"
constantlineHorz.Width = 1
constantlineHorz.Style = DashStyle_Dash

Dim constantlineVert
Set constantlineVert = Chart1.ConstantLines(1)
constantlineVert.Value = 8
constantlineVert.Color = RGB(255,165,0)
constantlineVert.Axis = AxisItem_X
constantlineVert.Text = "Limit 2"
constantlineVert.Width = 3

Dim constantlineHorz as Object
Set constantlineHorz = Chart1.ConstantLines(0)
constantlineHorz.Value = 30
constantlineHorz.Color = RGB(255,0,0)
constantlineHorz.Axis = AxisItem_Y
constantlineHorz.Text = "Alarm Limit 1"
constantlineHorz.Width = 1
constantlineHorz.Style = DashStyle_Dash
Dim constantlineVert as Object
Set constantlineVert = Chart1.ConstantLines(1)
constantlineVert.Value = 8
constantlineVert.Color = RGB(255,165,0)
constantlineVert.Axis = AxisItem_X
constantlineVert.Text = "Limit 2"
constantlineVert.Width = 3

Stripes

Stripes can also be very useful objects to highlight information in the chart area. They allow you to highlight a range of values associated with any of the axes by drawing a color frame in the chart background. For example, in a scientific application you may want the user to recognize points that plot between 20 and 80 with a blue stripe object as depicted in the following figure:

The Stripe object handles stripes and their properties, where you can set color, range and which axis the stripe is associated to. If you want to highlight a specific value instead of a range, please refer to the Constant Lines sample in the previous section.

The following code creates the stripes for the previous figure shown.

Dim stripeHorz As Stripe = Chart1.Stripes(0)
stripeHorz.From = 20
stripeHorz.To = 50
stripeHorz.Color = Color.FromArgb(192, 192, 255)
stripeHorz.Axis = AxisItem.Y

Dim stripeVert As Stripe = Chart1.Stripes(1)
stripeVert.From = 3
stripeVert.To = 5
stripeVert.Color = Color.FromArgb(128, 255, 128)
stripeVert.Axis = AxisItem.X

Stripe stripeHorz = chart1.Stripes[0];
stripeHorz.From = 20;
stripeHorz.To = 50;
stripeHorz.Color = Color.FromArgb(192, 192, 255);
stripeHorz.Axis = AxisItem.Y;

Stripe stripeVert = chart1.Stripes[1];
stripeVert.From = 3;
stripeVert.To = 5;
stripeVert.Color = Color.FromArgb(128, 255, 128);
stripeVert.Axis = AxisItem.X;

Dim stripeHorz
Set stripeHorz = Chart1.Stripes(0)
stripeHorz.From = 20
stripeHorz.To = 50
stripeHorz.Color = RGB(192,192,255)
stripeHorz.Axis = AxisItem_Y

Dim stripeVert
Set stripeVert = Chart1.Stripes(1)
stripeVert.From = 3
stripeVert.To = 5
stripeVert.Color = RGB(128,255,128)
stripeVert.Axis = AxisItem_X

Dim stripeHorz as Object
Set stripeHorz = Chart1.Stripes(0)
stripeHorz.From = 20
stripeHorz.To = 50
stripeHorz.Color = RGB(192,192,255)
stripeHorz.Axis = AxisItem_Y
Dim stripeVert as Object
Set stripeVert = Chart1.Stripes(1)
stripeVert.From = 3
stripeVert.To = 5
stripeVert.Color = RGB(128,255,128)
stripeVert.Axis = AxisItem_X


Conditional Attributes

The Conditional Attributes feature of Chart FX provides a built in solution to configure point attributes for chart points that meet a configured condition. The value of each point is evaluated against the items in the ConditionalAttributes collection. When the point's value meets the conditions configured, that ConditionalAttributes object would be assigned to the point; retaining the configured attributes.

The conditional attributes allow coloring points and setting marker size and shape independently without the need for creating complex algorithms to evaluate chart values. The ConditionalAttributes class derives from the PointAttributes class. For more information regarding the supported members of these classes, please consult the Chart FX API Reference.

In the following chart, Stripe objects where configured to show the different ranges in a chart. The ranges are 0-33 (green), 33-66 (yellow) and 66-100 (red). Using 3 conditional attributes, one for each range, the points of the scatter plot were customized depending on their value.

There are a myriad of applications for this feature, and the API is very simple. As stated before, the ConditionalAttributes class derives from the PointAttributes class. The Condition class is what is used to configure the conditions used to evaluate each point.

The Conditional Range
The conditional range is determined by two properties, To and From. These two properties specify the beginning and ending values of a range, which the point must fall between in order for a ConditionalAttributes object to be applied. The ToOpen and FromOpen properties are used to specify whether the beginning or ending values will be included in the range.

Other Condition Class Members
Other API members included allow you to configure a selected ConditionalAttributes item as inactive (Active property), or to Evaluate a point to determine whether it would meet the conditions of a particular conditional attributes object or not.

The Inverse property allows developers to reverse the To and From attributes of a conditional attributes item. As an alternative to creating two independent ConditionalAttributes, in some situations developers may use this attribute to achieve the same functionality.

For example, lets imagine that you want to color all points less than 50 AND greater than 70 Blue, all values between are to be Red. Normally you would create 3 conditional attributes to achieve this, however, using the Inverse property this can be done using only two conditional attribute items.

  • The first attribute item will be configured: From 50, To 70, Color Blue, Inverse True.
  • The second attribute item will be configured: From 50, To 70, Color Red.

Please see the API Reference (Chart FX Resource Center) for a complete reference of the supported members for the Condition and ConditionalAttributes classes. Also, please see the Visual Attributes Section of the Interactive Samples (Chart FX Resource Center).


The Printer Object

The Printer object provides important and very helpful properties to print a chart. Using this object, you will have control over the margins, paper orientation, color or pattern printing, among others. The supported methods will also allow you to prompt the user with page setup, preview and print dialogs to ensure the user prints exactly what they want.

Important Note: Methods used to print or prompt dialogs may only be called using client side scripting. The server component does not support these API members since they will have no use on the server side.

Setting the Page Layout

When you are ready to add printing functionality to your chart, there are questions you should take into account:

  • Would you like to use the default printer margins or specify custom margins?
  • Should the printed chart use a landscape or portrait page orientation?
  • Should you prompt the user with a preview or setup dialog to make these choices themselves?

Chart FX supports properties and methods that allow you to specify the exact page layout desired.

Margins

If no margins are set for a chart, the default printer margins will be used when the chart is printed. Chart FX allows you to specify the top, bottom, right and left margins using the Margins property. The margins property is set using an integer and is measured in hundredths of an inch; therefore, if you would like to set an inch margin around the chart, each margin must be set to 100.

'Set an inch margin around the entire chart
Chart1.Printer.Margins = New Printing.Margins(100, 100, 100, 100)

'Prompt the print preview dialog
Chart1.Printer.PrintPreview()

//Set an inch margin around the entire chart
chart1.Printer.Margins = new Printing.Margins(100, 100, 100, 100);

//Prompt the print preview dialog
chart1.Printer.PrintPreview();

If you would rather allow the user to configure the printing margins, you may do so by calling the PageSetup method. The PageSetup method will prompt the user with a page setup dialog box (shown above) that allows end user access to the page margins and page orientation (Landscape/Portrait). The print preview dialog may also be prompted to the user by calling the PrintPreview method.

Orientation

From the page setup dialog, the end user my select to print the chart in either the landscape or portrait formats. The landscape format is longer from left to right, while the portrait format is longer from top to bottom.

You can also set the page orientation programmatically using the Orientation property. The code below will print the chart in a landscape format:

' Set the page orientation to landscape

Chart1.Printer.Orientation = Orientation.Landscape

// Set the page orientation to landscape

chart1.Printer.Orientation = Orientation.Landscape;

Printing Colors

Normally if you have a black and white printer and try printing a color chart, you will receive a printout that is virtually unreadable due to the grayscales that are printed instead of the true palette colors. To resolve this type of issue, Chart FX includes the ForceColors property. When a color chart is printed to a B&W printer while this property is set to "False", each color in the chart is printed as a hatched pattern. This helps the end user read different series in the chart based on the contrasting patterns created in the printout. If the chart is to be printed with a color printer, you can force Chart FX to print a color chart by setting this property to "True". Below the ForceColors property is set to "True" and the chart is printed:

'Force colors to be printed
Chart1.Printer.ForceColors = True

'Print the entire chart
Chart1.Printer.Print()

//Force colors to be printed
chart1.Printer.ForceColors = true;

//Print the entire chart
chart1.Printer.Print();

Important Note: The ForeColors property will have no effect when the Chart is printed with a Color Printer.

Printing the Chart

Another major consideration is the number of pages that are needed to print a chart. When you have a chart with a large number of points (Scrollable) and you print that chart, Chart FX will print as many pages as necessary. The Compress property forces Chart FX to print the chart in just one page by recalculating the appropriate values so that all the points can be fixed in one page. Please note the printed chart may have a different look if you use the Compress property before printing. Below is the code used to compress and print a chart:

'Compress the chart to one printed page
Chart1.Printer.Compress = True

'Print the chart
Chart1.Printer.Print()

//Compress the chart to one printed page
chart1.Printer.Compress = true;

//Print the chart
chart1.Printer.Print();

In the code above, the print method is called to print the compressed chart. As you can see, there were no additional parameters passed with the Print method in order to print the chart. When the Print method is called with no parameters, Chart FX will print the entire chart. To print selected pages of a chart, the nFrom and nTo parameters can be passed to the chart when the method is called. This will print only the specified range of pages for the chart. If the nTo parameter is configured to zero, Chart FX will print from the specified nFrom page to the end of the chart. And if both the nFrom and nTo parameters are set to –1, only the screen shown is printed (used to print a zoomed area of a chart). Below are examples of these configurations:

'Print pages 3 thru 6
Chart1.Printer.Print(3, 6)

'Print pages 3 thru remaining pages
Chart1.Printer.Print(3, 0)

'Print the Screen (used to print a zoom area)
Chart1.Printer.Print(-1, -1)

//Print pages 3 thru 6
chart1.Printer.Print(3, 6);
//Print pages 3 thru remaining pages
chart1.Printer.Print(3, 0);
//Print the Screen (used to print a zoom area)
chart1.Printer.Print(-1, -1);

If you would like to prompt the user with a print dialog, you may do so by calling the PrintDialog method. The print dialog allows the user to select the printer to be used, specify the print range and configure the number of copies to be printed. This property also uses a Boolean parameter called nFrom. When set to "true" users can modify the print range; when "false", the print range options are not available to the user. The following code will prompt the user with a print dialog:

'Prompt print dialog that allows print range modification
Chart1.Printer.PrintDialog(True)

//Prompt print dialog that allows print range modification
chart1.Printer.PrintDialog(true);

Important Note: Methods used to print or prompt dialogs may only be called using client side scripting. The server component does not support these API members since they will have no use on the server side.


Chart FX Tools

The Chart FX Tools are used to allow end users to customize visual attributes of the chart. These tools give end users the ability to interact with the chart more efficiently and access features without any additional programming efforts on your part. You, as a programmer, may restrict access or customize these tools as you please.

ToolBar and MenuBar

One of the most useful tools in Chart FX is the toolbar; many programmers appreciate this feature because they are not required to add additional lines of code in their applications to give end users more freedom to customize their charts.

Using the ToolBar and the MenuBar, end users can, for example, change the Chart Gallery, show egends and Lables, rotathe the Chart, etc.

Sometimes, customizing the toolbar becomes imperative when you wish to deny end users access to a particular feature, extend the original functionality provided by a Chart FX command or you simply want to change a tooltip that a command button displays. As a matter of fact, there could be thousands of reasons why you may want to modify the original Toolbar displayed by Chart FX

Important Note: Please note the properties and methods used to customize the toolbar and menubar are derived from the same class, therefore are identical. If you need to customize the menubar, you would use the supported members of the class in conjunction with the MenuBarObj property.

Context Menus

Chart FX supports context sensitive menus for charting applications to allow end user chart customization (not supported with image maps). By default, a context menu will be prompted when the user right-clicks a particular element in the chart. This menu consists of a pull-down dialog with options specific for customizing the selected element.

These display the chart Series, Background and Axis context menus. Other chart objects that support context menus are the constant line, stripe, title, data editor and legends.

The context menus may be disabled using the ContextMenus property. By default, this property is set to 'True', when set to 'False' the context menus are not accessible by right-clicking in the chart area.

Chart1.ContextMenus = False

chart1.ContextMenus = false;

chart1.ContextMenus = False

Chart1.ContextMenus = False


Customizing the Chart FX Tools

The Chart FX active chart tools provide an easy way for users to access the supported commands. Providing this functionality to charting applications can dramatically improve the usability and appeal of charts. However if you plan to restrict access to any of the commands it is important to keep in mind that there are many ways to access any one command. For example, an end user may select the gallery command via the ToolBar, MenuBar or right-click context sensitive menus.

This introduces an additional level of complexity as customizing only the ToolBar does not mean that other tools are not exposing the same command. For example, if you do not want end users to select an area chart, you may end up changing the ToolBar, ManuBar, the right-click menus, or any other tool where the Area button may appear.

To increase control over these commands, Chart FX introduces the Commands object. The Commands object contains all the Chart FX commands available and their definitions (picture, text, etc). This allows the developer to remove or disable a command one time that will effect all the tools used to create and display the user interface for Chart FX.

Other important properties supported by the Chart FX API are the chart class ToolBarObj and MenuBarObj properties which allow a programmer to control ToolBar and ManuBar positioning, visual attributes and command customization.


Relationship between the Commands & ToolBar

When customizing the ToolBar, it is imperative that you understand the relationship between the Commands and ToolBar classes.

When it comes to changing general settings, such as position and visibility, the supported members of the ToolBar class should be used. The chart ToolBarObj or MenuBarObj properties expose the members that are used to change the general visual attributes of the selected ToolBar.

On the other hand, if you want to customize items (buttons) in the ToolBar, many of the features you may want to change (ToolTips, Picture, etc) are configured using the members of the Commands class. Items accessed using the Commands object is usually available to any of the Chart FX Tools.

In the following figure, you'll see that for a particular button in the ToolBar many of the important visible attributes like text, picture (icon), and style are controlled by the Commands object and not by the ToolBar object.


General Controls

Showing & Hiding the ToolBar

The ToolBar class exposes the Visible property that allows you to show or hide a selected ToolBar in the chart. The Boolean property may be used as follows:

'Show the Chart FX ToolBar and hide the MenuBar
Chart1.ToolBarObj.Visible = True
Chart1.MenuBarObj.Visible = False

//Show the Chart FX ToolBar and hide the MenuBar
chart1.ToolBarObj.Visible = true;
chart1.MenuBarObj.Visible = false;

'Show the Chart FX ToolBar and hide the MenuBar
Chart1.ToolBarObj.Visible = True
Chart1.MenuBarObj.Visible = False

'Show the Chart FX ToolBar and hide the MenuBar
Chart1.ToolBarObj.Visible = True
Chart1.MenuBarObj.Visible = False

Note: Please note that you can also use the properties dialog to configure this setting at design time.

Positioning the ToolBar

The ToolBar class exposes several members that allow you to position the ToolBar in the chart's bounding rectangle. By default, the position of the ToolBar is docked to the top margin. However, by using the Docked property you can position the selected ToolBar anywhere in the chart. For example, if you want to dock the ToolBar to the left margin programmatically, you can use the Docked property as follows:

'Dock the ToolBar to the left
Chart1.ToolBarObj.Docked = Docked.Left

//Dock the ToolBar to the left
chart1.ToolBarObj.Docked = Docked.Left;

'Dock the ToolBar to the left
Chart1.ToolBarObj.Docked = Docked_Left

'Dock the ToolBar to the left
Chart1.ToolBarObj.Docked = Docked_Left


Customizing the ToolBar

Removing Items from a ToolBar

You may want to remove buttons in the ToolBar as a result of a specific condition in your application. For example, you may not want the end user to switch between 2D and 3D modes therefore you can remove that button in the ToolBar. Or you may not want to allow users to save or open chart files. In this case, you can remove those buttons from the Chart FX ToolBar.

The ToolBar class supports the removeAt method to remove one or more items in the ToolBar. When using this method, please be aware that removed buttons will no longer exist in the ToolBar and all the indexes will be recalculated by Chart FX. For example, if you remove the first button in the ToolBar using the removeAt method, the index of the second button will become index 0, the index of the third button will become index 1, etc.

The removeAt method accepts 2 parameters; the first parameter receives the position from where to start removing items and the second parameter specifies the number of items to remove. Also, be aware that vertical separators count as additional ToolBar items, so if you plan to remove several buttons and they are separated, you must include the separators when calling the removeAt method. To remove the first two buttons in the ToolBar, you may call the removeAt method as follows:

'Remove the fist two buttons
Chart1.ToolBarObj.RemoveAt(0, 2)

//Remove the fist two buttons
chart1.ToolBarObj.RemoveAt(0, 2);

'Remove the fist two buttons
Chart1.ToolBarObj.RemoveAt 0, 2

'Remove the fist two buttons
Chart1.ToolBarObj.RemoveAt 0, 2

Inserting Items in the ToolBar

There may be a situation where you want to include additional items in a selected ToolBar. To allow this the ToolBar class exposes the insertAt method. This method allows you to insert additional command buttons to the ToolBar that can be configured to execute existing Chart FX commands or a custom command that you may want to include in your application.

Chart FX exposes a wide variety of pre-defined commands through the CommandID constants. As stated earlier, these commands can be used to overwrite the functionality of existing buttons in the ToolBar or to assign actions to newly added buttons.

When adding buttons please be aware that the Chart FX ToolBar can handle up to 32 items (including buttons and separators), so when adding buttons in the ToolBar please be careful not to exceed that limit.

Let's suppose you want to limit the number of available gallery types that the end users may select from in a particular chart. The only gallery types that you want to grant access to are the Line, Area or Bar types. You decide that you want to remove the default gallery command from the ToolBar, and add three additional buttons in the ToolBar to select from the desired chart types.

The first thing you need to do is remove the gallery selector by using the removeAt method, covered earlier in the "Removing Buttons from a ToolBar" section. The gallery selector is the third item in the ToolBar, so to remove it we can use the removeAt method as follows:

Chart1.ToolBarObj.RemoveAt(4, 1)

chart1.ToolBarObj.RemoveAt(4, 1);

Chart1.ToolBarObj.RemoveAt 4, 1

Chart1.ToolBarObj.RemoveAt 4, 1

Once you have removed the gallery selector from the ToolBar, you will want to insert the desired gallery commands into the ToolBar. In order not to overwrite other commands in the ToolBar, you will need to insert some "place-holders" for the additional gallery commands. The ToolBar class provides the insertAt method that allows you to specify the index of where you would like to insert items into the ToolBar as well as the number of items you would like to add. The following code will insert 3 additional items into the ToolBar, and then assign those items the tree gallery commands:

'Insert 3 items and assign a command for each
Chart1.ToolBarObj.InsertAt(0,3)
Chart1.ToolBarObj(0) = CommandID.Bar
Chart1.ToolBarObj(1) = CommandID.Area
Chart1.ToolBarObj(2) = CommandID.Line

//Insert 3 items and assign a command for each
chart1.ToolBarObj.InsertAt(0,3);
chart1.ToolBarObj[0] = (int) CommandID.Bar;
chart1.ToolBarObj[1] = (int) CommandID.Area;
chart1.ToolBarObj[2] = (int) CommandID.Line;

'Insert 3 items and assign a command for each
Chart1.ToolBarObj.InsertAt 0, 3
Chart1.ToolBarObj(0) = CommandID_Bar
Chart1.ToolBarObj(1) = CommandID_Area
Chart1.ToolBarObj(2) = CommandID_Line

'Insert 3 items and assign a command for each
Chart1.ToolBarObj.InsertAt 0, 3
Chart1.ToolBarObj(0) = CommandID_Bar
Chart1.ToolBarObj(1) = CommandID_Area
Chart1.ToolBarObj(2) = CommandID_Line

Please note that when you use the insertAt method, the indexes for other buttons in the ToolBar will be recalculated appropriately. In other words, because we have added 3 buttons at the beginning of the ToolBar, the index for the button that used to be in the first position is no longer 0 but 3 and the buttons that we have added will have indexes 0,1 and 2 respectively.

Important Note: Modifying just the ToolBar is no guarantee that the end user can only switch to those 3 chart types. The above example shows how to use the insertAt method to add buttons to the ToolBar. If you really want to prevent the end user from switching to other chart types, you have to modify the Commands list appropriately so those chart types may not be accessed from another tool in the Chart FX UI.


Changing Item Functions

Changing Functions of Existing ToolBar Items

Chart FX exposes a wide variety of pre-defined commands that you can use to overwrite the functionality of buttons on the default ToolBar. New buttons can also be added to the ToolBar and configured to perform such actions. Not only can you use the existing commands Chart FX includes, but you can also cretate custom commands that can be processed internally by your application.

The CommandID constants allows you to easily overwrite the default actions performed by a ToolBar button (item) with any of the pre-defined Chart FX commands. For example, the Print button in the Chart FX ToolBar allows the end user to print the chart. This button prompts the user with a dialog where they select the number of copies and their printer. There may be a case where you do not want the users prompted by this dialog. The Chart FX pre-defined commands include a print command that will print a chart without prompting the user for any additional settings.

In the following sample, the default "Print with Printer dialog" command for the Chart FX ToolBar will be changed to the "Print without Printer dialog" command. Before you can change the command, you must determine the index of the print button item in the ToolBar.

As you can see, the print icon in the ToolBar is the third item visible; therefore the index of the item is 2. Now that we have established the index of the print button in the ToolBar, we can now assign the "Print without Printer dialog" command to that position. The following code will set the third item in the ToolBar to the Chart FX pre-defined print command:

'No print dialog is prompted
Chart1.ToolBarObj(2) = CommandID.Print

//No print dialog is prompted
chart1.ToolBarObj[2] = (int) CommandID.Print;

'No print dialog is prompted
Chart1.ToolBarObj(2) = CommandID_Print

'No print dialog is prompted
Chart1.ToolBarObj(2) = CommandID_Print

To change the command back to the default, you would do the following:

'Change back to print with dialog
Chart1.ToolBarObj(2) = CommandID.PrintDialog

//Change back to print with dialog
chart1.ToolBarObj[2] = (int) CommandID.PrintDialog;

'Change back to print with dialog
Chart1.ToolBarObj(2) = CommandID_PrintDialog

'Change back to print with dialog
Chart1.ToolBarObj(2) = CommandID_PrintDialog

Modifying ToolTips

A ToolTip is text that appears when the user positions the mouse over any button in the ToolBar. This is very helpful as it informs the end user about the functionality of the button, without actually pressing it and performing the action.

You may think this ToolTip is part of the ToolBar, however, this text is also used in other parts of the Chart FX UI and therefore is controlled by the Commands class. This means that when you change the ToolTip associated with a particular command, this change will be consistent through out the Chart FX UI. Another point to keep in mind when changing ToolTips is that the text can be displayed somewhere else such as the MenuBar or context menus. Therefore, you must be careful not to make ToolTip strings too long or they will not be readable elsewhere.

To change the ToolTip associated with a particular command, you must first identify the command ID for the command you wish to modify. For example, if you want to change the ToolTip for the Gallery selector, you would reference the gallery enumeration (CommandID.Gallery). Once the desired command is referenced, you can set the text property for the command to modify the ToolTip:

'Modify a Tooltip of an existing gallery item
Chart1.Commands(CType(CommandID.Gallery, Integer)).Text = "New Tooltip"
setText("Bar Chart Custom ToolTip")

//Modify a Tooltip of an existing gallery item
chart1.Commands[(int) CommandID.Gallery].Text = "New Tooltip";
setText("Bar Chart Custom ToolTip");

'Modify a Tooltip of an existing gallery item
Chart1.Commands(CommandID_Gallery).Text = "New Tooltip"
setText("Bar Chart Custom ToolTip")

'Modify a Tooltip of an existing gallery item
Chart1.Commands(CommandID_Gallery).Text = "New Tooltip"
setText("Bar Chart Custom ToolTip")


Changing Toolbar Icons

The entire collection of Chart FX tools shares the same icons used in the ToolBar, therefore the Commands class controls them. When you change an icon for a particular command, that change will be reflected in all of the other tools that allow access to that command. For example, the Data Editor icon is used in the ToolBar as well as the right-click context menus. When you change the icon associated with the Data Editor command, both tools will reflect the change.

Any command may be assigned a pre-defined Chart FX icon from the icon list or a custom icon that you add to the pre-defined list. This section will explain how to do both.

Selecting a Pre-Defined Icon

Chart FX provides a pre-defined list of 16x15 icons that are used for all the pre-defined commands. You can assign these pre-defined icons to other commands throughout the Chart FX user interface. To do this, the Commands class supports the setPicture property. Setting this property to the index of a desired icon in the icon list will assign that icon image to the referenced CommandID. Below is an example of the pre-defined icon list:

To change the Bar Chart command icon to the 'File' icon (index 1 in commands picture), you would use the following code:

'Change the Icon for the Gallery Item
Chart1.Commands(CType(CommandID.Gallery, Integer)).Picture = 1

//Change the Icon for the Gallery Item
chart1.Commands[(int)CommandID.Gallery].Picture = 1;

'Change the Icon for the Gallery Item
Chart1.Commands(CommandID_Gallery).Picture = 1

'Change the Icon for the Gallery Item
Chart1.Commands(CommandID_Gallery).Picture = 1

Adding & Replacing Command Icons

Selecting an icon from the pre-defined list is not particularly useful because most of them are used by other Chart FX commands. This can cause confusion for the end user because the icons will not be unique to the function of a particular command. The addPicture and changePicture methods may be used to add and replace icons in the pre-defined icon list.

The addPicture method is particularly useful when you are adding custom commands to the Chart FX UI. This method will append one or more icons to the pre-defined icons list that you can use to assign to existing or new commands.

The changePicture method is most useful when you want to change icons that are already being used by Chart FX. This method allows you to replace all or part of the existing icon list. When adding or replacing any image in the icon list, it is important that your custom icons have the proper dimensions (16 X 15 pixels). When adding multiple icons you must ensure there are no spaces between the custom icon images.

AddPicture Sample

Suppose you have two new icons you want to add to the icons list. Both of these icons are placed into a single bitmap file. Once you have added the new icons, you want to assign the first icon to the 'Gallery' command and the second for the 'PrintDialog' command. The AddPicture method returns the index position where the icons were added to the list. This reference can be used when assigning the new icons to the desired command. Below the sample code to accomplish this:

'Add two icons and assign them to existing commands
Dim picIndex As Integer
//PicIndex = Chart1.Commands.AddPicture(New Bitmap("d:\icons.bmp"))
Chart1.Commands(CType(CommandID.Gallery, Integer)).Picture = picIndex
Chart1.Commands(CType(CommandID.PrintDialog, Integer)).Picture = picIndex+1

//Add two icons and assign them to existing commands
int picIndex;
picIndex = chart1.Commands.AddPicture(new Bitmap("d:\\icons.bmp"));
chart1.Commands[(int) CommandID.Gallery].Picture = picIndex;
chart1.Commands[(int) CommandID.PrintDialog].Picture = picIndex+1;

'Add two icons and assign them to existing commands
Dim picIndex
picIndex = chart1.Commands.AddPicture(Server.CreateObject("ChartFX.ASP.Image")
picIndex.Path = "d:\icons.bmp")
chart1.Commands(CommandID_Gallery).Picture = picIndex
chart1.Commands(CommandID_PrintDialog).Picture = picIndex + 1

'Add two icons and assign them to existing commands
Dim picIndex as Integer
picIndex = Chart1.Commands.AddPicture((App.Path) + "\Data\computer.gif")
Chart1.Commands(CommandID_Gallery).Picture = picIndex
Chart1.Commands(CommandID_PrintDialog).Picture = picIndex + 1

ChangePicture Sample

If you want to replace some or all icons currently used by Chart FX, you will want to utilize the ChangePicture method. Please note that Chart FX uses icons in a particular order as depicted in the following figure:

Because the icons are in a specific order, if you want to replace two different icons in the list and those icons are not located next to each other in the image array, then you will need to make two separate changes (one for each specific icon index). For example, if you need to replace the 3rd and 7th icons in icon list, you will use the following code:

'change the 3rd and 7th icon images
Chart1.Commands.ChangePicture(2, New Bitmap("d:\icon1.bmp"))
Chart1.Commands.ChangePicture(6, New Bitmap("d:\icon2.bmp"))

//change the 3rd and 7th icon images
chart1.Commands.ChangePicture(2, new Bitmap("d:\\icon1.bmp"));
chart1.Commands.ChangePicture(6, new Bitmap("d:\\icon2.bmp"));

'change the 3rd and 7th icon images
Dim Bitmap1
Set Bitmap1 = Server.CreateObject("ChartFX.ASP.Image")
Bitmap1.Path = "d:\icon1.bmp"
Dim Bitmap2
Set Bitmap2 = Server.CreateObject("ChartFX.ASP.Image")
Bitmap2.Path = "d:\icon1.bmp"
chart1.Commands.ChangePicture 2, Bitmap1
chart1.Commands.ChangePicture 6, Bitmap2

'change the 3rd and 7th icon images
Chart1.Commands.ChangePicture 2, LoadPicture((App.Path) + "d:\\icon1.bmp")
Chart1.Commands.ChangePicture 6, LoadPicture((App.Path) + "d:\\icon2.bmp")


Working With SubCommands

Although most buttons in the Chart FX user interface (ToolBar, menu bar, etc) perform a specific action when pressed, there are other buttons that present a list of subcommands, one of which may be selected. For example, the Personalization button in the Chart FX ToolBar presents a list that allows the user to select personalization preferences, as depicted in the following figure:

These are called Subcommands lists and you can create or modify existing subcommands lists in the Chart FX user Interface. For this purpose, the Commands class exposes the getSubCommandID property as well as the removeSubCommand and removeAllSubCommands methods.

Removing Existing Subcommands

In the figure shown above, you can see how the Personalization Options command presents a list of subcommands that allow the end user to select which preference to apply to the chart. Let's suppose you want to remove end user access to the 'Restore Defaults' subcommand selection. You can easily remove that option from the Personalization Options subcommand list by invoking the removeSubCommand method as follows:

'Remove the 'Restore Defaults' subcommand
Chart1.Commands(CType(CommandID.PersonalizedOptions, Integer)).RemoveSubCommand(3)

//Remove the 'Restore Defaults' subcommand
chart1.Commands[(int) CommandID.PersonalizedOptions].RemoveSubCommand(3);

'Remove the 'Restore Defaults' subcommand
Chart1.Commands(CommandID_PersonalizedOptions).RemoveSubCommand 3

'Remove the 'Restore Defaults' subcommand
Chart1.Commands(CommandID_PersonalizedOptions).RemoveSubCommand 3

Please note that when you remove a particular subcommand from the subcommand list, the indexes will be shifted to the actual number of subcommands available in the command. For example, if you wanted to remove the 'Remove Defaults' subcommand and the separator above it, you would need to remove the same index twice:

'Removing one subcommand forces Chart FX to recalculate item indexes
Chart1.Commands(CType(CommandID.PersonalizedOptions, Integer)).RemoveSubCommand(2)
Chart1.Commands(CType(CommandID.PersonalizedOptions, Integer)).RemoveSubCommand(2)

//Removing one subcommand forces Chart FX to recalculate item indexes
chart1.Commands[(int) CommandID.PersonalizedOptions].RemoveSubCommand(2);
chart1.Commands[(int) CommandID.PersonalizedOptions].RemoveSubCommand(2);

'Removing one subcommand forces Chart FX to recalculate item indexes
Chart1.Commands(CommandID_PersonalizedOptions).RemoveSubCommand 2
Chart1.Commands(CommandID_PersonalizedOptions).RemoveSubCommand 2

'Removing one subcommand forces Chart FX to recalculate item indexes
Chart1.Commands(CommandID_PersonalizedOptions).RemoveSubCommand 2
Chart1.Commands(CommandID_PersonalizedOptions).RemoveSubCommand 2

You can also remove all subcommands from a command list by using the removeAllSubCommands method:

'Remove all subcommands
Chart1.Commands(Ctype(CommandID.PersonalizedOptions,Integer)).RemoveAllSubCommands()

//Remove all subcommands
chart1.Commands[(int) CommandID.PersonalizedOptions].RemoveAllSubCommands();

'Remove all subcommands
Chart1.Commands(CommandID_PersonalizedOptions).RemoveAllSubCommands

'Remove all subcommands
Chart1.Commands(CommandID_PersonalizedOptions).RemoveAllSubCommands

By removing a subcommand from the list, you will also remove this option from other tools that may use the same command ID.

Adding Subcommands

To add a subcommand to a list you will use the setSubCommandID property. If you are adding subcommands to a specific command you must make sure to keep the indexes in order as non-consecutive indexes may cause unpredictable results.

This feature is particularly useful when you are working with custom commands. So please refer to the "Adding Custom Commands" chapter, where we show a custom command that contains several subcommands.

Working with Selectors

A selector is a command that contains a list of subcommands that when pressed will show a list of images (icons) for selection and when closed will show the current selection. In Chart FX, the gallery icon in the ToolBar is a selector as shown in the following figure:

The only notable difference between selectors and subcommand lists is that the style for the subcommand has been set to 'Selector'. For more information on controlling the style for a particular command, please refer to the setStyle property in the commands class.


Adding Custom Commands

In previous topics you learned the API provided by the ToolBar and Commands classes to add, remove or modify the Chart FX pre-defined list of commands. This was useful as you were able to customize the default Chart FX ToolBar, by removing existing commands, changing the icons and other important aspects related to the Chart FX User Interface.

Chart FX allows not only the customization of the default ToolBar with pre-defined Chart FX commands, but also the addition of custom commands that you can process internally in your application.

Let's say, for example, you want to add a button in the Chart FX ToolBar that when pressed loads another chart with new data and new visual attributes. It is clear that Chart FX will not provide this functionality as a pre-defined command because it will not know how to react when end users actually press such a button. Therefore, you'll need to add a custom command that will give you the desired results.

As a matter of fact, not only can you create custom buttons but groups of buttons, lists and selectors that will seamlessly integrate into your application. This section explains the necessary steps to add custom commands to the Chart FX User Interface.

Adding a custom command to the ToolBar means setting the correct attributes using the Commands class and then using the properties and methods provided in the ToolBar class to physically add (or replace) that button in the ToolBar.

The following are the steps you need to follow to add a custom command to the Chart FX ToolBar:

1. Add a Custom Commands' ID to the Chart FX Commands List

The first step in adding one or more custom commands to the Chart FX UI is adding each ID to the Chart FX Commands list. You do this with the AddCommand method supported by the Commands class.

The ID is an integer that Chart FX will use to identify the command when the user presses or interacts with it. This is a unique ID that will be associated to the custom command and should never be duplicated for use with another command. Chart FX defines its pre-defined IDs between 'CommandID.FIRST' (29440) and 'CommandID.LAST' (29951), so please make sure you don't use a number in this range as it will cause unpredictable results. You can add a custom command with ID 4 as follows:

'Add a command ID to the command list
Chart1.Commands.AddCommand(4)

//Add a command ID to the command list
chart1.Commands.AddCommand(4);

'Add a command ID to the command list
Chart1.Commands.AddCommand 4

'Add a command ID to the command list
Chart1.Commands.AddCommand 4

2. Setting the Visual Attributes of the Custom Command

Once the Command ID has been added to the list, you must instruct Chart FX how to display this command in the UI (is it a button or a list?, what icon is it going to use?, what text is it going to display?, is it enabled?). There is a property for each particular attribute in the commands object as follows:

Style. The Style property allows you to tell Chart FX if the command you're adding is a two-state button, a list, a selector or member of a group. If you do not set the Style property, the custom command is added as a regular button. If you want to create a two-state button you can set the Style property as follows:

'Set the Style of the command button
Chart1.Commands(4).Style = CommandStyle.TwoState

//Set the Style of the command button
chart1.Commands[4].Style = CommandStyle.TwoState;

'Set the Style of the command button
Chart1.Commands(4).Style = CommandStyle_TwoState

'Set the Style of the command button
Chart1.Commands(4).Style = CommandStyle_TwoState

Picture. The Picture property allows you to specify the icon to be used in the button. Please note that you can add your own buttons as described in the "Changing/Adding icons" section. Here is a sample of how to set the picture to the pre-defined icon with the index 2:

'Set an icon for the new commmand
Chart1.Commands(4).Picture = 2

//Set an icon for the new commmand
chart1.Commands[4].Picture = 2;

'Set an icon for the new commmand
Chart1.Commands(4).Picture = 2

'Set an icon for the new commmand
Chart1.Commands(4).Picture = 2

Text. The Text property allows you to set the ToolTip to be displayed or the text if the command is to be shown in the MenuBar. For example, to set a new ToolTip for the button you can set the Text property as follows:

'Set a customTooltip
Chart1.Commands(4).Text = "New Tooltip"

//Set a customTooltip
chart1.Commands[4].Text = "New Tooltip";

'Set a customTooltip
Chart1.Commands(4).Text = "New Tooltip"

'Set a customTooltip
Chart1.Commands(4).Text = "New Tooltip"

3. Adding the Custom Command to the ToolBar

To add the EditTitle command to the ToolBar after the 3rd position, you can use the InsertAt method and the CommandID properties exposed by the ToolBar class, as follows:

' Insert a new item in the 4th position of the ToolBar
Chart1.ToolBarObj.InsertAt(3,1)
' Now assign the command id to added button
Chart1.ToolBarObj(3) = CommandID.EditTitle

// Insert a new item in the 4th position of the ToolBar
chart1.ToolBarObj.InsertAt(3,1);
// Now assign the command id to added button
chart1.ToolBarObj[3] = (int) CommandID.EditTitle;

' Insert a new item in the 4th position of the ToolBar
Chart1.ToolBarObj.InsertAt 3, 1
' Now assign the command id to added button
Chart1.ToolBarObj(3) = CommandID_EditTitle

' Insert a new item in the 4th position of the ToolBar
Chart1.ToolBarObj.InsertAt 3, 1
' Now assign the command id to added button
Chart1.ToolBarObj(3) = CommandID_EditTitle

4. Processing the Custom Command

Now that you have added a Custom command to the Chart FX commands list and added a button to the ToolBar, you need a mechanism to add your custom code that processes that particular command. The UserCommand Event is posted to your application when the user clicks or interacts with the custom command you have added. So if you want to change the chart gallery to lines when the user presses the button, you will process the UserCommand event as follows:

'Change the chart gallery to lines when the item commandID 4 is selected
Private Sub Chart1_UserCommand(ByVal sender As Object, ByVal e As
      ByVal e As SoftwareFX.ChartFX.CommandUIEventArgs)
      Handles Chart1.UserCommand

   If (e.ID = 4) Then
         Chart1.Gallery = Gallery.Lines
   End If
End Sub

//Change the chart gallery to lines when the item commandID 4 is selected
private void chart1_UserCommand(object sender,SoftwareFX.ChartFX.CommandUIEventArgs e)
{
    if (e.ID == 4)
       chart1.Gallery = Gallery.Lines;
}


Import and Export Methods

Chart FX provides two important methods (Import and Export) that enable you (or your end users) to save chart files, images and data in a variety of formats.

There are also other file types in Chart FX called "Chart Templates" that allow you to save the appearance (Colors, Chart Types and Styles, Visible Tools, etc.) of the chart in a file so you can later apply it to another chart. This allows you to reuse code instead of setting the same attributes for all of your individual charts.

Note: Templates save all the information that is not data related. This means, it will not save the values, number of series or points, or any other property related to this data, such as MultiType settings and Min, Max values in the chart axes.

File Formats

  • Binary: Exports and imports chart settings to a binary file.
  • BinaryTemplate: Exports chart settings to a binary file with 'Template' pre-assigned, using the FileMask property.
  • XML: Exports chart settings to an XML file.
  • Text: Exports chart data to a Text File.
  • Bitmap: Exports the chart as a Windows Bitmap.
  • Metafile: Exports the chart as a Windows Metafile.
  • JPEG: Exports the charts as a JPEG image (only supported on Web Forms version).
  • PNG: Exports the chart as a PNG image (only supported on Web Forms version).
  • External: Uses an external encoder to export the file (only supported on Web Forms version).

The Export Method

This method is used to export the chart data and/or set properties to the clipboard, file or stream in different formats.

Exporting to a File

Chart1.Export(FileFormat, FileName)

chart1.Export(FileFormat, FileName);

Chart1.Export FileFormat, FileName

Chart1.Export FileFormat, FileName

Where FileFormat can be any of the supported file formats, and FileName is the file name (including the path). Example:

Chart1.Export(FileFormat.Bitmap, "c:\export\chart.bmp")

chart1.Export(FileFormat.Bitmap, "c:\\export\\chart.bmp");

Chart1.Export FileFormat_Bitmap, "c:\export\chart.bmp"

Chart1.Export FileFormat_Bitmap, "c:\export\chart.bmp"

Exporting to a Stream

Chart1.Export(FileFormat, StreamName)

chart1.Export(FileFormat, StreamName);

chart1.Export FileFormat, StreamName

chart1.Export FileFormat, StreamName

Where FileFormat can be any of the supported file formats, and StreamName is the name of a previously opened Stream. Example:

Dim myStream As New System.IO.MemoryStream()
Chart1.Export(FileFormat.XML, myStream)

System.IO.MemoryStream myStream = new System.IO.MemoryStream();
chart1.Export(FileFormat.XML, myStream);

Dim myStream
Set myStream = Server.CreateObject("Not.Found")
Chart1.Export FileFormat_XML, myStream

Dim mySteam As Stream
Set mySteam = New Stream
Chart1.Export FileFormat_XML, mySteam

Exporting the chart to an open stream is useful when you need to save the chart inside one of your proprietary files; in other words, it allows you to save the chart and any other data into the same file.

Also, streams are particularly useful if you want to save the chart in a database.

Exporting to the Clipboard

Chart1.Export(FileFormat)

chart1.Export(FileFormat);

Chart1.Export FileFormat

Chart1.Export FileFormat

Where FileFormat can be: Text, Bitmap or Metafile. Example:

Chart1.Export(FileFormat.Metafile)

chart1.Export(FileFormat.Metafile);

Chart1.Export FileFormat_Metafile

Chart1.Export FileFormat_Metafile

The External File Format

The External file format is only supported by Chart FX in Web applications, and it provides support other formats, using external encoders. At this moment, the only external encoder available is for SVG files; in the future, other external encoders will be released, e.g. Flash.

In order to use the External format, the chart's ImageTags property must be loaded with the format to be exported:

Chart1.ImgTags = "SVG"
Chart1.Export(FileFormat.External,"c:\export\chart.svg")

chart1.ImgTags = "SVG";
chart1.Export(FileFormat.External,"c:\\export\\chart.svg");

The FileMask Property

Whether you are saving chart files in Binary or XML format, you can control what is saved in the file by manipulating the FileMask property. The Binary format will save visual attributes and data; XML will save only visual attributes.

This is a mask property that allows you to specify which visual attributes you want the chart file to save when you invoke the Export method. By default, this property is set to save all visual attributes including the data.

However, if you want to save everything but the titles in the chart, you will set this property before invoking the Export method as follows:

Chart1.FileMask = FileMask.All And Not FileMask.Titles

chart1.FileMask = FileMask.All & ~FileMask.Titles;

Chart1.FileMask = FileMask_All And Not FileMask_Titles

Chart1.FileMask = FileMask_All And Not FileMask_Titles

This property is particularly useful because it allows you to customize how chart files are saved, this way you can build your own chart templates.

This property is a mask property, which means all settings represent a bit in the word that you need to turn on or off according to what you want. For this purpose you'll use the bitwise operators (And, Or, Not, Xor) provided by your development tool.

Because it is a mask property, you must make sure you use these operators to turn on/off bits and avoid losing previous settings to the property. For example, if you want to turn on the TOOLS setting, the right way of setting this property is:

Chart1.FileMask = FileMask.All And FileMask.Tools

chart1.FileMask = FileMask.All & FileMask.Tools;

Chart1.FileMask = FileMask_All And FileMask_Tools

Chart1.FileMask = FileMask_All And FileMask_Tools

Additionally, the BinaryTemplate format will save a Binary format with only a set of pre-defined visual attributes.

The Import Method

The Import method is used to import a chart previously saved with the Export method. The Import method works exactly like the Export methods and uses the same syntax and parameters. Below are some samples:

Chart1.Import(FileFormat.BinaryTemplate, "c:\export\chart.cfx")

chart1.Import(FileFormat.BinaryTemplate, "c:\\export\\chart.cfx");

 Chart1.Import FileFormat_BinaryTemplate, "c:\export\chart.cfx"

Chart1.Import FileFormat_BinaryTemplate, "c:\export\chart.cfx"

Chart1.Import(FileFormat.Metafile,"c:\export\chart.emf")

chart1.Import(FileFormat.Metafile,"c:\\export\\chart.emf");

Chart1.Import FileFormat_Metafile, "c:\export\chart.emf"

Chart1.Import FileFormat_Metafile, "c:\export\chart.emf"


The Chart FX Annotation Extension

The Chart FX Annotation Extension allows you to include floating objects in the chart. It also provides a User Interface so your users can create objects and highlight different areas in the chart. Using the Annotation Extension, you can add text, arrows, different shapes and even images that you can freely move around the chart area. This allows you to direct the attention of an end user directly to a particular portion of the chart. Below is an example of an annotation arrow and text object used in a chart:

Integrating Annotation in your Project

If you plan to utilize the Annotation features of Chart FX, it will be necessary to use an additional dll (ChartFX.ASP.Annotation.dll) in your project.


Creating the Annotation Extension Object

Once you have added the reference to the Annotation assembly in your project, you are ready to create the Annotation Extension object. The Annotation Extension object must be created as a type AnnotationX. Once created, the Extension object may be added to the chart using the Chart class Extensions property. Below is an example of creating the Annotation Extension and adding it to the chart.

Dim annotx As New SoftwareFX.ChartFX.Annotation.AnnotationX()
Chart1.Extensions.Add(annotx)

SoftwareFX.ChartFX.Annotation.AnnotationX annotx = new SoftwareFX.ChartFX.Annotation.AnnotationX();
chart1.Extensions.Add(annotx);

Dim annotx
Set annotx = Server.CreateObject("ChartFX.ASP.Annotation")
Chart1.Extensions.Add annotx

Dim annotx as Cfx62ClientServerAnnotation.AnnotationX
Set annotx = New Cfx62ClientServerAnnotation.AnnotationX
Chart1.Extensions.Add annotx

Configuring the Annotation List Object

Every Annotation Extension object created will include an Annotation Object List. The Annotation Object List consists of all the individual annotation objects that you wish to appear in your chart. To add floating text, you would simply create an annotation text object, set the desired attributes and add that object to the Annotation List. As long as the Extension object has been added to the chart, the text object will appear in the chart. Below is an example:

Dim annotx As New SoftwareFX.ChartFX.Annotation.AnnotationX()
Chart1.Extensions.Add(annotx)
Dim text As New AnnotationText()
annotx.List.Add(text)
text.TextColor = Color.Blue
text.Text = "Sample Text"
text.Height = 50
text.Width = 50
text.Attach(2, 20)
text.Refresh()

SoftwareFX.ChartFX.Annotation.AnnotationX annotx = new SoftwareFX.ChartFX.Annotation.AnnotationX();
chart1.Extensions.Add(annotx);
AnnotationText text = new AnnotationText();
annotx.List.Add(text);
text.TextColor = Color.Blue;
text.Text = "Sample Text";
text.Height = 50;
text.Width = 50;
text.Attach(2, 20);
text.Refresh();

Dim annotx
Set annotx = Server.CreateObject("ChartFX.ASP.Annotation")
chart1.Extensions.Add annotx
Dim text
Set text = Server.CreateObject("ChartFX.ASP.AnnotationText")
annotx.List.Add text
text.TextColor = RGB(0,0,255)
text.Text = "Sample Text"
text.Height = 50
text.Width = 50
text.Attach 2, 20
text.Refresh

Dim annotx as Cfx62ClientServerAnnotation.AnnotationX
Set annotx = New Cfx62ClientServerAnnotation.AnnotationX
Chart1.Extensions.Add annotx
Dim text as Cfx62ClientServerAnnotation.AnnotationText
Set text = New Cfx62ClientServerAnnotation.AnnotationText
annotx.List.Add text
text.TextColor = RGB(0,0,255)
text.Text = "Sample Text"
text.Height = 50
text.Width = 50
text.Attach 2, 20
text.Refresh

By using the List property of the AnnotationX class, you may access methods and properties that allow you to add, clear, count, remove and access particular elements in the Annotation Object List. To clear all the objects currently included in the object list you can use the following code:

annotx.List.Clear()

annotx.List.Clear();

annotx.List.Clear

annotx.List.Clear

Creating Instances of Annotation Objects

There are a variety of different Annotation objects that are exposed when you add the Annotation Extension to your project. The following objects may be included in your charting applications by implementing the Annotation Extension:

  • Arc (AnnotationArc class)
  • Arrow (AnnotationArrow class)
  • Balloon (AnnotationBalloon class)
  • Circle (AnnotationCircle class)
  • Group (AnnotationGroup class)
  • Picture (AnnotationPicture class)
  • Polygon (AnnotationPolygon class)
  • Rectangle (AnnotationRectangle class)
  • Text (AnnotationText class)

Annotation objects and their properties belong to another class. This means you should create a new instance of an object with the "New" clause in order to access the supported class members. The code below will create a new annotation circle object and add the object to the Annotation Object List:

Dim circle As New AnnotationCircle()
annotx.List.Add(circle)

AnnotationCircle circle = new AnnotationCircle();
annotx.List.Add(circle);

Dim circle
Set circle = Server.CreateObject("ChartFX.ASP.AnnotationCircle")
annotx.List.Add circle

Dim circle as Cfx62ClientServerAnnotation.AnnotationCircle
Set circle = New Cfx62ClientServerAnnotation.AnnotationCircle
annotx.List.Add circle

Once the circle object has been created, you may begin to assign supported attributes to the object. The circle object does not expose any additional properties or methods; rather it shares a set of common properties (AnnotationObject class) that may be applied to any of the annotation objects. Other objects expose specific properties that must be set to display the object appropriately in the chart area. For example, all objects expose the Top and Left properties that allow you to position the element; additionally the annotation arrow object also exposes a specific property TailStyle, which allows you to configure the arrow tail style.

Below is a full example of creating an Annotation Extension object, adding the extension to the chart, creating an annotation circle object with attributes and adding the circle to the Annotation Object List:

Dim annotx As New SoftwareFX.ChartFX.Annotation.AnnotationX()
Chart1.Extensions.Add(annotx)

Dim circle As New AnnotationCircle
annotx.List.Add(circle)

circle.Color = Color.Red
circle.Border.Color = Color.Black
circle.Height = 30
circle.Width = 30
circle.Attach(0, 50)
circle.Refresh()

SoftwareFX.ChartFX.Annotation.AnnotationX annotx = new SoftwareFX.ChartFX.Annotation.AnnotationX();
chart1.Extensions.Add(annotx);

AnnotationCircle circle = new AnnotationCircle();
annotx.List.Add(circle);

circle.Color = Color.Red;
circle.Border.Color = Color.Black;
circle.Height = 30;
circle.Width = 30;
circle.Attach(0, 50);
circle.Refresh();

Dim annotx
Set annotx = Server.CreateObject("ChartFX.ASP.Annotation")
Chart1.Extensions.Add annotx

Dim circle
Set circle = Server.CreateObject("ChartFX.ASP.AnnotationCircle")
annotx.List.Add circle

 circle.Color = RGB(255,0,0)
circle.Border.Color = RGB(0,0,0)
circle.Height = 30
circle.Width = 30
circle.Attach 0, 50
circle.Refresh

Dim annotx as Cfx62ClientServerAnnotation.AnnotationX
Set annotx = New Cfx62ClientServerAnnotation.AnnotationX
Chart1.Extensions.Add annotx
Dim circle as Cfx62ClientServerAnnotation.AnnotationCircle
Set circle = New Cfx62ClientServerAnnotation.AnnotationCircle
annotx.List.Add circle
circle.Color = RGB(255,0,0)
circle.Border.Color = RGB(0,0,0)
circle.Height = 30
circle.Width = 30
circle.Attach 0, 50
circle.Refresh

It is also important to call the Refresh method for an object when added or any attribute of the object is modified. Due to performance reasons Chart FX does not do this automatically.

Using the Enabled property of the AnnotationX class, developers may allow or prevent users from interacting with annotation objects added to charts programmatically. By default this property is set to False. Setting the property to True permits users to change the size, color, location, etc., of annotation objects in the chart. When displaying the annotation toolbar, the Enabled property must be set to True before the annotation object is added as an extension to the chart. Please see the annotation toolbar section for more information.

Note: The AnnotationObject class supports the AllowMove and AllowModify properties that also allow and deny modification of individual annotation objects.


Positioning an Object in the Chart

The most common means of positioning an annotation object in a chart area is utilizing the Top and Left properties. These properties accept pixel values for configuration, where the origin of the chart (0,0) is located at the top left corner of the chart area.

The Attach method of the AnnObj class has also been implemented to attach annotation objects to a particular point in a chart. The beauty of using the Attach method is that it accepts chart axis values instead of pixel values that the Top and Left properties require. The Attach method is an overloaded method that supports three different configurations:

AnnObj.Attach(dx,dy)

AnnObj.Attach(dxLeft,dyTop,dxRight,dyBottom)

AnnObj.Attach(vert stringAlignment, dx, horz stringAlignment, dy)

When attaching an object using the two-parameter configuration, you are attaching the center of the annotation object to the selected point. Because you are attaching at the center, it is still required to set the height and width of the annotation object. The parameter dx represents the X axis point, and the dy represents the Y axis point you wish to attach the object.

Note: When attaching an object to a chart using the attach center method (Attach(dx,dy)), it is important to understand that the center of the annotation object will be attached to the configured point. Therefore, if you attach an arrow object to a chart, the head of the arrow will not be attached to that point, rather the center point in the line of the arrow will be attached to the configured point.

When using the four-parameter configuration, the parameter dxLeft represents the left X axis value, dyTop represents the top Y axis value, dxRight represents the Right X axis value and dyBottom represents the bottom Y axis value. When attaching an object using the four-parameter configuration, each of the corners of the annotation object is attached to a particular point in the chart. Because this automatically sets the size of the object, the height and width properties are not needed unless you wish to control the object's orientation. Another benefit to using the four-parameter approach is that each of the four corners of the object is anchored to a point in the chart. This allows the object to resize when the chart itself is resized.

The Attach method (Alignment overload)has been exposed which accepts a horizontal and vertical alignment setting. This allows developers to position an object (based on the black handles shown in the image) to any logical point in the plot area.

This code would attach the bottom, middle handle to the (5,20) X,Y coordinate in the chart:

' Use the 3rd Overload to Attach an Annotation text object (Attach Alignment)
annText.Attach(StringAlignment.Center,5, StringAlignment.Near,20)

// Use the 3rd Overload to Attach an Annotation text object (Attach Alignment)
annText.Attach(StringAlignment.Center,5, StringAlignment.Near,20);

' Use the 3rd Overload to Attach an Annotation text object (Attach Alignment)
annText.Attach "Center",5,"Near",20

' Use the 3rd Overload to Attach an Annotation text object (Attach Alignment)
annText.Attach "Center",5,"Near",20

The advanced anchoring feature allows developers to configure a Top, Left pixel coordinate and anchor the object to that distance from the selected margin. Therefore, if an object was anchored to the right and left of a chart while the chart was resized horizontally, the object would stretch and shrink based on the resizing.

The DrawingArea property is used to instruct how Chart FX Annotation objects will be when they overlap a chart margin. When set to true, objects will be clipped when they are positioned or scrolled over a chart margin.

Height, Width and Object Orientation

When working with annotation objects, it is very important to set the appropriate Height and Width for any object that you create. By default the height and width of each annotation object is zero (0), so by neglecting to set these properties the object will not appear in the chart.

These properties also have different effects on individual object types. For example, manipulating the height and width values for a circle object allows you to create ellipses and oval shapes. If you are creating an arrow annotation object, setting the height and width to negative values will configure the arrowhead to point in different directions. For example assigning a positive width will cause the arrow to point to the right-bottom portion of the chart. Similarly, assigning a negative value for the width will cause the arrow to point to the top-right corner of the chart. The orientation of many of the annotation objects can be altered through the use of the height and width properties including the rectangle, circle, arrow, arc and balloon objects.

Positioning an Object in the Chart

The most common means of positioning an annotation object in a chart area is utilizing the Top and Left properties. >These properties accept pixel values for configuration, where the origin of the chart (0,0) is located at the top left corner of the chart area.

The Attach style="mso-spacerun: yes"> method of the AnnotationObject class has also been implemented to attach annotation objects to a particular point in a chart. style="mso-spacerun: yes"> The beauty of using the Attach method is that it accepts chart axis values instead of pixel values that the Top and Left properties require. The Attach method is an overloaded method that supports two different configurations:

AnnotationObject.Attach(dx,dy)

AnnotationObject.Attach(dxLeft,dyTop,dxRight,dyBottom)

Note: The Attach method may NOT be used when positioning the AnnotationPolygon object. The AnnotationPolygon is the only annotation object that does not support the Attach method. Please use the Vertices property.

When attaching an object using the two-parameter configuration, you are attaching the center of the annotation object to the selected point. style="mso-spacerun: yes"> Because you are attaching at the center, it is still required to set the height and width of the annotation object. style="mso-spacerun: yes"> The parameter dx represents the X Axis point and the dy represents the Y Axis point you wish to attach the object.

Note: When attaching an object to a chart using the attach center method (Attach(dx,dy)), it is important to understand that the center of the annotation object will be attached to the configured point. Therefore, if you attach an arrow object to a chart, the head of the arrow will not be attached to that point, rather the center point in the line of the arrow will be attached to the configured point.

When using the four-parameter configuration, the parameter dxLeft represents the left X Axis value, dyTop represents the top Y Axis value, dxRight represents the right X Axis value and dyBottom represents the bottom Y Axis value. style="mso-spacerun: yes"> When attaching an object using the four-parameter configuration, each of the corners of the annotation object is attached to a particular point in the chart. Because this automatically sets the size of the object, the height and width properties are not needed unless you wish to control the object's orientation. Another benefit to using the four-parameter approach is that each of the four corners of the object is anchored to a point in the chart. This allows the object to resize when the chart itself is resized.


Annotation Group

Annotation Group

The AnnotationGroup class allows you to create annotation group objects. An annotation group will consist of multiple instances of annotation objects. One advantage of working with this is that the group object exposes all common properties (AnnotationObject class), so you could change visual attributes of all of the objects in a group with just one property call. Another advantage is that when objects are grouped together, they may be rotated and moved as a group. For example, let's say you create a stick person figure using circles and line annotation objects. If each object is rotated individually, the stick figure looses its shape. Conversely, if you create a group of objects that make a stick figure and then rotate the group, all the objects will keep there shape and the stick figure will stay intact.

Creating an annotation group object is exactly like creating any other annotation object. Once the group object has been created, you may begin to add individual objects to the group. Once all the desired objects have been added to the group, the group can be added to the annotation list object. By setting attributes to the group object, all the individual objects added to the group are altered. Below is an example of creating an annotation group consisting of a circle and a balloon object:

Dim annotx As New SoftwareFX.ChartFX.Annotation.AnnotationX()
Chart1.Extensions.Add(annotx)

Dim group As New AnnotationGroup()
annotx.List.Add(group)

Dim balloon As New AnnotationBalloon()
balloon.Height = 100
balloon.Width = 100
balloon.Attach(3, 40)
balloon.Text = "Sample Text"

Dim circle As New AnnotationCircle()
circle.Color = Color.Blue
circle.Height = 30
circle.Width = 30
circle.Top = 40
circle.Left = 40

group.List.Add(balloon)
group.List.Add(circle)
circle.Refresh()
balloon.Refresh()
group.RecalcBounds()

SoftwareFX.ChartFX.Annotation.AnnotationX annotx = new SoftwareFX.ChartFX.Annotation.AnnotationX();
chart1.Extensions.Add(annotx);

AnnotationGroup group = new AnnotationGroup();
annotx.List.Add(group);

AnnotationBalloon balloon = new AnnotationBalloon();
balloon.Height = 100;
balloon.Width = 100;
balloon.Attach(3, 40);
balloon.Text = "Sample Text";

AnnotationCircle circle = new AnnotationCircle();
circle.Color = Color.Blue;
circle.Height = 30;
circle.Width = 30;
circle.Top = 40;
circle.Left = 40;

group.List.Add(balloon);
group.List.Add(circle);
circle.Refresh();
balloon.Refresh();
group.RecalcBounds();

Dim annotx
Set annotx = Server.CreateObject("ChartFX.ASP.Annotation")
chart1.Extensions.Add annotx

Dim group
Set group = Server.CreateObject("ChartFX.ASP.AnnotationGroup")
annotx.List.Add group

Dim balloon
Set balloon = Server.CreateObject("ChartFX.ASP.AnnotationBalloon")
balloon.Height = 100
balloon.Width = 100
balloon.Attach 3, 40
balloon.Text = "Sample Text"

Dim circle
Set circle = Server.CreateObject("ChartFX.ASP.AnnotationCircle")
circle.Color = RGB(0,0,255)
circle.Height = 30
circle.Width = 30
circle.Top = 40
circle.Left = 40

group.List.Add balloon
group.List.Add circle
circle.Refresh
balloon.Refresh
group.RecalcBounds

Dim annotx as Cfx62ClientServerAnnotation.AnnotationX
Set annotx = New Cfx62ClientServerAnnotation.AnnotationX
Chart1.Extensions.Add annotx
Dim group as Cfx62ClientServerAnnotation.AnnotationGroup
Set group = New Cfx62ClientServerAnnotation.AnnotationGroup
annotx.List.Add group
Dim balloon as Cfx62ClientServerAnnotation.AnnotationBalloon
Set balloon = New Cfx62ClientServerAnnotation.AnnotationBalloon
balloon.Height = 100
balloon.Width = 100
balloon.Attach 3, 40
balloon.Text = "Sample Text"
Dim circle as Cfx62ClientServerAnnotation.AnnotationCircle
Set circle = New Cfx62ClientServerAnnotation.AnnotationCircle
circle.Color = RGB(0,0,255)
circle.Height = 30
circle.Width = 30
circle.Top = 40
circle.Left = 40
group.List.Add balloon
group.List.Add circle
circle.Refresh
balloon.Refresh
group.RecalcBounds

Recalculating the Group Object Bounds

Whenever a group is added to the annotation list, the bounds of the group object must be set. This may be done by setting the height and width of the group as well as attaching or configuring a position in the chart for the group. Instead of setting these properties manually, you can instruct Chart FX to calculate these values for you by calling the RecalcBounds method. This method should also be invoked every time an object is added to a group or when any of the objects contained in a group are resized or moved.

group.RecalcBounds()

group.RecalcBounds();

group.RecalcBounds

group.RecalcBounds


Real-Time Charts

Chart FX for .NET supports true real-time charting capabilities by giving specific functions that support chart scrolling in an accelerated painting mode (without flickering). To prevent data overflow, Chart FX provides Real-Time Charts with a pre-defined maximum point buffer. This allows the library to accept points up to that buffer value; once the buffer is full, a new value will be inserted into the chart while the initial value set is lost.

Chart FX for .NET supports two different Real-Time Charts:

1: Limited Real Time: A limited real-time chart will display only a pre-defined number of points at any one time (previously allocated buffer). This type of chart is the fastest real-time chart available in Chart FX since memory is allocated only once (when you call the BufferSize property). This means that the chart will have the maximum setting until it begins to lose points (i.e. setting 15 as the maximum number of points means that you will lose point 1 when passing value for point 16).

If losing previously passed points is not important, we suggest you use this type of charts for real-time purposes when implementing a rapid data input rate. Two variations of this kind of chart are also available in Chart FX:

Standard: When the buffer is full (BufferSize has been reached) and a new point is inserted the data will "scroll". This means you will lose the first point plotted and the nth point will become the nth-1.

Loop Position: Same as standard but every time you set a new value, a customizable vertical line will pass through the point that is being updated (the last acquired point). When reaching the end of the data set, the looping marker will move to the beginning.

2: Unlimited Real Time: This type of real-time chart can add points to the chart without losing any previously set values. You may also choose to set the chart to scroll every time it receives a new point. Depending on the context of your application, this allows you to set automatic scrolling real-time charts.

Note: Real-time functionality is only supported for Windows Form development.


Passing Data to Real-Time Charts

Below are the steps used to create and pass data to a real-time chart:

  • You will need to set the 'EvenSpacing' flag of the TypeMask property. This may be set at design time or run time to unsure that the points will be equally distanced in the X Axis.

'All points will be equally distanced on the X Axis
Chart1.TypeMask = Chart1.TypeMask Or ChartType.EvenSpacing

//All points will be equally distanced on the X Axis
chart1.TypeMask = chart1.TypeMask | ChartType.EvenSpacing;
  • Set the BufferSize property to a positive integer value to represent the real-time charts point buffer if you want to create a Limited Real-Time Chart (strongly suggested!). This will allow the points in the chart to be plotted much faster.

'Set the Buffer Size to 20
Chart1.RealTimeSettings.BufferSize = 20

//Set the Buffer Size to 20
chart1.RealTimeSettings.BufferSize = 20;
  • Set the real-time Style property to select the real-time style you want to be applied to the chart. The different styles allow you to implement a loop marker as well as hide the default hourglass icon.

'Set the real-time style
Chart1.RealTimeSettings.Style = RealTimeStyle.LoopPos Or
                                RealTimeStyle.NoWaitArrow

//Set the real-time style
chart1.RealTimeSettings.Style = RealTimeStyle.LoopPos | RealTimeStyle.NoWaitArrow;
  • Open the communication channel (OpenData Method) to the real-time chart using the 'AddPoints' Or 'InsertPoints' flags combined with 'Values' enumeration (see explanation later in this section). This will allow the pointers to the data array to be relative to the last point added, so there is no need to remember the number of points the chart currently has or the index of the last point passed.

'Open the communications channel
Chart1.OpenData(COD.Values Or COD.AddPoints, 2, 1)

//Open the communications channel
chart1.OpenData(COD.Values | COD.AddPoints, 2, 1);
  • Set the corresponding value of the new points using an offset instead of an absolute index to the points. This means that if you want to add two (2) new points to the chart (before the CloseData method) you must use index 0 and 1 for the point index in the Value Property.

'Add a new point for each series
Chart1.Value(0, 0) = -50 + Rnd() * 100
Chart1.Value(1, 0) = -50 + Rnd() * 100

//Add a new point for each series
Random r = new Random();
chart1.Value[0, 0] = -50 + r.NextDouble() * 100;
chart1.Value[1, 0] = -50 + r.NextDouble() * 100;
  • Call the CloseData method with a combination of 'Values' flag with any of the following enumerations:

RealTime - Chart FX will not scroll to the end of the data set.
RealTimeScroll - Chart FX will scroll the chart to the end of the data set.

'Close communications channel using values and realtime scroll style
Chart1.CloseData(COD.Values Or COD.RealTime)

//Close communications channel using values and realtime scroll style
chart1.CloseData(COD.Values | COD.RealTime);

The following sample assumes that you have a timer that calls our application with two new values every second, so the idea is to include these points in a chart in real-time mode:

'Preparing the chart to be Real-Time
Chart1.TypeMask = Chart1.TypeMask Or ChartType.EvenSpacing
'Setting a buffer size of 50 points
Chart1.RealTimeSettings.BufferSize = 50
'Add a Loop marker and hiding the hourglass cursor
Chart1.RealTimeSettings.Style = RealTimeStyle.LoopPos Or
                                RealTimeStyle.NoWaitArrow
...
'Finally when the timer calls set the new data
Chart1.OpenData(COD.Values Or COD.AddPoints,1,2)
'Set two new points for series 1
Chart1.Value(0,0) = -50 + Rnd() * 100
Chart1.Value(0,1) = -50 + Rnd() * 100
'Close the channel forcing scroll
Chart1.CloseData(COD.Values Or COD.RealTimeScroll)

//Preparing the chart to be Real-Time
chart1.TypeMask = chart1.TypeMask | ChartType.EvenSpacing;
//Setting a buffer size of 50 points
chart1.RealTimeSettings.BufferSize = 50;
//Add a Loop marker and hiding the hourglass cursor
chart1.RealTimeSettings.Style = RealTimeStyle.LoopPos | RealTimeStyle.NoWaitArrow;
...
//Finally when the timer calls set the new data
chart1.OpenData(COD.Values | COD.AddPoints,1,2);
//Set two new points for series 1
Random r = new Random();
chart1.Value[0,0] = -50 + r.NextDouble() * 100;
chart1.Value[0,1] = -50 + r.NextDouble() * 100;
//Close the channel forcing scroll
chart1.CloseData(COD.Values | COD.RealTimeScroll);

AddPoints vs. InsertPoints

Sometimes you want newly acquired points to be appended to the right of the chart forcing the chart to scroll to the left. In this situation you will use COD.AddPoints. If you want the opposite behavior (points inserted in the beginning of the chart forcing the chart to scroll to the right) you will use the COD.InsertPoints constant with the OpenData method call.

This behavior is depicted in the following figure


Setting the Real-Time Style

The real-time style refers to the visual features you can control during display of the chart in your application. Basically the two different settings available to this feature are showing the loop marker and hiding the hourglass cursor from the real-time chart.

The RealTimeSettings Class Style property allows you to control the cursor icon and loop marker with the following enumerations; you may also combine the flags:

  • LoopPos: Show Loop Marker
  • NoWaitArrow: Hide Hourglass cursor

'Show the loop marker and hide the hourglass cursor
Chart1.RealTimeSettings.Style = RealTimeStyle.LoopPos Or RealTimeStyle.NoWaitArrow

//Show the loop marker and hide the hourglass cursor
chart1.RealTimeSettings.Style = RealTimeStyle.LoopPos | RealTimeStyle.NoWaitArrow;

The following figure includes a loop marker:


Scrolling the X-Axis Labels in Real-Time Mode

If you're working with a real-time chart and also assigning legends to the points in the X-axis, it is imperative that you scroll these legends in order to have your real-time chart display the appropriate legends every time new data is received.

In order to scroll the X-axis legends you must follow these rules:

  • Turn on the 'NoLegInvalidate' enumeration of the TypeEx property. When this flag is on, the chart will not be invalidated when the legends are set.

'Turn the 'NoLegInvalidate' flag
Chart1.TypeEx = Chart1.TypeEx Or ChartTypeEx.NoLegInvalidate

//Turn the 'NoLegInvalidate' flag
chart1.TypeEx = chart1.TypeEx | ChartTypeEx.NoLegInvalidate;
  • Open the communication channel (OpenData method) in combination with either the 'AddPoints' or 'InsertPoints' enumeration. One of these must always be used when creating real-time charts.

'You must always select AddPoints or InsertPoints with real-time charts
Chart1.OpenData(COD.Values Or COD.InsertPoints, 2, 1)

//You must always select AddPoints or InsertPoints with real-time charts
chart1.OpenData(COD.Values | COD.InsertPoints, 2, 1);
  • Set the value for the new point using the relative position in the Value property.

'Assign data to the first point of each series (relative position)
Chart1.Value(0, 0) = -50 + Rnd() * 100
Chart1.Value(1, 0) = -50 + Rnd() * 100

//Assign data to the first point of each series (relative position)
Random r = new Random();
chart1.Value[0, 0] = -50 + r.NextDouble() * 100;
chart1.Value[1, 0] = -50 + r.NextDouble() * 100;
  • Within the same communication channel opened to pass the data using the value property, you can use the legend property to assign the X Axis label. You should set the new label using the relative position with the legend property. (nOffset is the incrementing counter that will be used to assign the label)

'Add the label value for the new points
Chart1.Legend(0) = Str(nOffset + 1)

//Add the label value for the new points
chart1.Legend[0] = Convert.ToString(nOffset + 1);
  • Finally, in the CloseData Method include the 'ScrollLegends' enumeration to force Chart FX to scroll the legends.

'Close the communications channel using the ScrollLegends flag
Chart1.CloseData(COD.Values Or COD.ScrollLegend)

//Close the communications channel using the ScrollLegends flag
chart1.CloseData(COD.Values | COD.ScrollLegend);

Note: Scrolling legends do not apply when using the loop marker in your real-time charts.

Note: If you are not working with a buffer assigned to your real-time chart (BufferSize property) you must use the actual number of points in order to set the last point legend. You can read the nValues property and set the legend using the nValues-1 index instead of the BufferSize-1 index.


Real-time Chart Sample: Visual Basic

The following is a complete Visual Basic sample of a Limited Real-time chart. Other windows forms controls, such as checkbox and counter are used in this sample. Below are the steps to create a real-time chart in Visual Basic .NET.

  • Create a new Visual Basic Windows Form applictaion. On a blank form, drop a Chart FX for .NET chart control, a Windows form checkbox and a Windows form timer.

  • Once you have added these controls to the form, you can switch to the Form1.vb page and begin to add code. You should add the following namespace to the project:

Imports SoftwareFX.ChartFX

using SoftwareFX.ChartFX;
  • You will also need to declare two variables. You can do this in the declarations section of your project.

Const BufferSize = 20
Dim nOffset As Long

const int BufferSize = 20;
long nOffset;
  • Paste the following code into the main section of the project.

Private Sub AddPoint()

   'Switch real-time styles once buffer is full
   If nOffset = BufferSize Then
      Chart1.RealTimeSettings.Style = RealTimeStyle.NoWaitArrow
      Chart1.Refresh()
   End If

   'Set Communication Channel styles
   'These COD values instruct Chart FX about the Realtime settings
   'the chart, values and legend.

   Dim nCOD As SoftwareFX.ChartFX.COD
   nCOD = COD.Values Or COD.RealTime
   nCOD = nCOD Or COD.ScrollLegend

   'Add a point for each sereis to the right of the chart
   'Using the legend property, set the legend values

   Chart1.OpenData(COD.Values Or COD.AddPoints, 2, 1)
   Chart1.Value(0, 0) = -50 + Rnd() * 100
   Chart1.Value(1, 0) = -50 + Rnd() * 100
   Chart1.Legend(0) = Str(nOffset + 1)
   Chart1.CloseData(nCOD)
   nOffset = nOffset + 1

End Sub

Private Sub Form1_Load(ByVal sender As System.Object,
      e As System.EventArgs) Handles MyBase.Load

   'Set the buffer size to create a Limited Real-time chart.
   Chart1.RealTimeSettings.BufferSize = BufferSize

   'Initialize the number of points in the chart and assign corresponding labels.
   Dim i As Integer
   Chart1.OpenData(COD.Values Or COD.Remove Or COD.AllocHidden, 2, BufferSize)
   For i = 0 To BufferSize - 1
     Chart1.Legend(i) = Str(i + 1)
   Next
   Chart1.CloseData(COD.Values)

   'Set the Max and Min since no data was passed.
   Chart1.AxisY.Max = 100
   Chart1.AxisY.Min = -100

   ' Optimize scrolling. These lines will make the chart scroll faster.
   Chart1.TypeMask = Chart1.TypeMask Or ChartType.EvenSpacing
   Chart1.TypeEx = Chart1.TypeEx Or ChartTypeEx.NoLegInvalidate
   Chart1.RealTimeSettings.Style = RealTimeStyle.NoWaitArrow
                                   Or RealTimeStyle.LoopPos
   nOffset = 0

End Sub

Private Sub CheckBox1_CheckedChanged(ByVal sender As System.Object,
              e As System.EventArgs) Handles CheckBox1.CheckedChanged

   'Start timer when checkbox is checked
   Timer1.Enabled = CheckBox1.Checked

End Sub

Private Sub Timer1_Tick(ByVal sender As System.Object,
       ByVal e As System.EventArgs) Handles Timer1.Tick

   AddPoint()

End Sub

private void AddPoint()
{
    //Switch real-time styles once buffer is full
    if (nOffset == BufferSize) {
        chart1.RealTimeSettings.Style = RealTimeStyle.NoWaitArrow;
        chart1.Refresh();
    }

    //Set Communication Channel styles
    //These COD values instruct Chart FX about the Realtime settings
    //the chart, values and legend.

    SoftwareFX.ChartFX.COD nCOD;
    nCOD = COD.Values | COD.RealTime;
    nCOD = nCOD | COD.ScrollLegend;

    //Add a point for each sereis to the right of the chart
    //Using the legend property, set the legend values

    Random r = new Random();
    Chart1.OpenData(COD.Values | COD.AddPoints, 2, 1);
    Chart1.Value[0, 0] = -50 + r.Next() * 100;
    Chart1.Value[1, 0] = -50 + r.Next() * 100;
    Chart1.Legend[0] = Convert.ToString(nOffset + 1);
    Chart1.CloseData(nCOD);
    nOffset = nOffset + 1;
}

private void Form1_Load(object sender, System.EventArgs e)
{
    //Set the buffer size to create a Limited Real-time chart.
    Chart1.RealTimeSettings.BufferSize = BufferSize;

    //Initialize the number of points in the chart and assign corresponding labels.
    Chart1.OpenData(COD.Values | COD.Remove | COD.AllocHidden, 2, BufferSize);
    for (int i=0;i<=BufferSize-1;i++)
       chart1.Legend[i] = Convert.ToString(i + 1);
    Chart1.CloseData(COD.Values);

    //Set the Max and Min since no data was passed.
    Chart1.AxisY.Max = 100;
    Chart1.AxisY.Min = -100;

    // Optimize scrolling. These lines will make the chart scroll faster.
    Chart1.TypeMask = Chart1.TypeMask | ChartType.EvenSpacing;
    Chart1.TypeEx = Chart1.TypeEx | ChartTypeEx.NoLegInvalidate;
    Chart1.RealTimeSettings.Style = RealTimeStyle.NoWaitArrow | RealTimeStyle.LoopPos;
    nOffset = 0;
}

private void CheckBox1_CheckedChanged(object sender, System.EventArgs e)
{
    //Start timer when checkbox is checked
    Timer1.Enabled = CheckBox1.Checked;
}

private void Timer1_Tick(object sender, System.EventArgs e)
{
    AddPoint();
}
  • Run the application to see the chart.


Real-time Chart Sample: C#

The following is a complete C# sample of a Limited Real-time chart. Other windows forms controls, such as checkbox and counter are used in this sample. Below are the steps to create a real-time chart in C# .NET.

  • Create a new C# Windows Form applictaion. On a blank form, drop a Chart FX for .NET chart control, a Windows form checkbox and a Windows form timer.

  • Once you have added these controls to the form, you can switch to the Form1.cs page and begin to add code. You should add the following namespace to the project:

Imports SoftwareFX.ChartFX

using SoftwareFX.ChartFX;
  • You will also need to declare two variables. You can do this in the declarations section of your project.

Dim nOffset As Double
Const BufferSize As Integer = 20

double nOffset;
const int BufferSize = 20;
  • Access the design form and double-click on the form to add an event handler for the Form1_Load event. The Code Editor will open with the insertion point placed within the event handler. Place the following code for the Form1_Load event:

 'Set the buffer size to create a Limited Real-time chart.
Chart1.RealTimeSettings.BufferSize = BufferSize

'Initialize the number of points in the chart and assign corresponding
'labels.

Chart1.OpenData(COD.Values Or COD.Remove Or COD.AllocHidden, 2, BufferSize)
Dim i As Integer
For i = 0 To (BufferSize - 2)
    Chart1.Legend(i) =(i + 1).ToString()
Next i
Chart1.CloseData(COD.Values)

'Set the Max and Min since no data was passed.
chart1.AxisY.Max = 100
chart1.AxisY.Min = -100

'Optimize scrolling. These lines will make the chart scroll faster.
Chart1.TypeMask = Chart1.TypeMask Or ChartType.EvenSpacing
Chart1.TypeEx = Chart1.TypeEx Or ChartTypeEx.NoLegInvalidate
Chart1.RealTimeSettings.Style = RealTimeStyle.NoWaitArrow Or RealTimeStyle.LoopPos
nOffset = 0

//Set the buffer size to create a Limited Real-time chart.
chart1.RealTimeSettings.BufferSize = BufferSize;

//Initialize the number of points in the chart and assign corresponding
//labels.

chart1.OpenData(COD.Values | COD.Remove | COD.AllocHidden, 2, BufferSize);
for(int i = 0; i< BufferSize - 1; i++)
{
    chart1.Legend[i] = (i + 1).ToString();
}
chart1.CloseData(COD.Values);

//Set the Max and Min since no data was passed.
chart1.AxisY.Max = 100;
chart1.AxisY.Min = -100;

//Optimize scrolling. These lines will make the chart scroll faster.
chart1.TypeMask = chart1.TypeMask | ChartType.EvenSpacing;
chart1.TypeEx = chart1.TypeEx | ChartTypeEx.NoLegInvalidate;
chart1.RealTimeSettings.Style = RealTimeStyle.NoWaitArrow | RealTimeStyle.LoopPos;
nOffset = 0;
  • Return to the design form and double-click the checkbox control to add an event handler for the checkBox1_CheckedChanged event. The Code Editor will open with the insertion point placed within the event handler. Place the following code for the checkBox1_CheckedChanged event:

timer1.Enabled = checkBox1.Checked

timer1.Enabled = checkBox1.Checked;
  • Return to the design form and double-click the timer control to add an event handler for the timer1_Tick event. The Code Editor will open with the insertion point placed within the event handler. Place the following code for the timer1_Tick event:

AddPoint()

AddPoint();
  • While you are still in the Code Editor, insert the following code into the main section as its own subrountine:

Private Sub AddPoint()
     ' Switch real-time styles once buffer is full
     If nOffset = BufferSize Then
        chart1.RealTimeSettings.Style = RealTimeStyle.NoWaitArrow
        chart1.Refresh()
     End If
     'Set Communication Channel styles
     'These COD values instruct Chart FX about the Realtime settings
     'the chart, values and legend.
     Dim nCOD As SoftwareFX.ChartFX.COD
     nCOD = SoftwareFX.ChartFX.COD.Values Or SoftwareFX.ChartFX.COD.RealTime
     nCOD = nCOD Or SoftwareFX.ChartFX.COD.ScrollLegend
     'Add a point for each sereis to the right of the chart
     'Using the legend property, set the legend values
     Dim r As System.Random
     r = New System.Random()
     chart1.OpenData(COD.Values Or COD.AddPoints, 2, 1)
     chart1.Value(0, 0) = - 50 + r.NextDouble() * 100
     chart1.Value(1, 0) = - 50 + r.NextDouble() * 100
     chart1.Legend(0) =(nOffset + 1).ToString()
     chart1.CloseData(nCOD)
     nOffset = nOffset + 1
End Sub

private void AddPoint()
{
   // Switch real-time styles once buffer is full
   if (nOffset == BufferSize) {
      chart1.RealTimeSettings.Style = RealTimeStyle.NoWaitArrow;
      chart1.Refresh();
   }
   //Set Communication Channel styles
   //These COD values instruct Chart FX about the Realtime settings
   //the chart, values and legend.
   SoftwareFX.ChartFX.COD nCOD;
   nCOD = SoftwareFX.ChartFX.COD.Values | SoftwareFX.ChartFX.COD.RealTime;
   nCOD = nCOD | SoftwareFX.ChartFX.COD.ScrollLegend;
   //Add a point for each sereis to the right of the chart
   //Using the legend property, set the legend values
   System.Random r;   r = new System.Random();
   chart1.OpenData(COD.Values | COD.AddPoints, 2, 1);
   chart1.Value[0, 0] = -50 + (r.NextDouble() * 100);
   chart1.Value[1, 0] = -50 + (r.NextDouble() * 100);
   chart1.Legend[0] = (nOffset + 1).ToString();
   chart1.CloseData(nCOD);
   nOffset = nOffset + 1;
}
  • Run the application by pressing F5.


Personalizing Charts

As commercial web sites, corporate intranets and client applications become more and more sophisticated, users require and demand information on an individual basis. This is one of the reasons why web sites and client applications are beginning to support customized content with individual topics of interest and other personal information.

When it comes to Chart FX, there are many attributes the user may customize for each chart. Picture this, a particular user likes the graphical capabilities of Chart FX in your application; there is, however, one minor issue that annoys him, which is the color scheme you have chosen for your charts. There is another user asking you to change your default bar chart for a line chart. You instruct them to use the Chart FX user interface to change the visual attributes of the chart every time they log on to your site.

But, wouldn't it be nice if your application could provide charts with visual attributes they like but with new data for subsequent visits?

Chart FX can deliver personalized charts to your users. here are two ways to provide personalized charts: using the Chart FX User Interface (UI) with a few clicks by the end-user, or totally automatic through the API.

Personalizing a Chart using the User Interface

One of the options of the Chart FX toolbar is the PersonalizedCharts icon. It provides the user 3 options:

Load My Chart: when the user clicks on this option, any previously saved transformations will be applied to the new data. These transformations have been saved through either UI or API. If there are no transformations saved, no changes will be applied to the chart.

Save My Chart: when it's clicked, all the transformations made by the end-user to the original chart will be saved in a small file (approx. 1K) in the user's personal folder, typically located under the user's personal section of the local drive (Documents and Settings\...).

Reset Defaults: this option clears all the transformations made by the end-user and resets the chart to the original look established in the application. By default this option is disabled but it will be enabled as soon as the end-user modifies any attribute of the chart or a saved chart is loaded.

Personalizing a Chart using the API

When chart personalization is applied through the UI, user intervention is required to save and apply the transformations. In many cases the developer wants to provide an automatic mechanism to save and apply those changes. Chart FX provides this through the PersonalizedFlags property. With this property, the developer has the ability to decide whether the changes will be saved and/or loaded automatically. The supported flags are:

PersonalizedFlags.AutoLoad: before the chart is rendered, Chart FX will look for a saved transformation file in the user's Isolated Storage, and will apply it to the new data if found. This functions as if the user selected the "Load My Chart" option. By default this option is disabled.

PersonalizedFlags.AutoSave: any transformations made to the chart will be automatically saved to the Isolated Storage when the chart is destroyed (the browser is refreshed or closed, or another page is invoked). By default this option is disabled.

PersonalizedFlags.EnableRestore: as soon as the user makes the first change to the chart through the UI, the original chart is saved in memory to allow the Reset Defaults option. If you don't want to provide such option to the end-user, you may avoid the process of saving the chart in memory. This can be accomplished by turning off the EnableRestore flag (enabled by default). You must use the bitwise combination of the flags and property, as follows:

Chart1.PersonalizedFlags = Chart1.PersonalizedFlags And Not
PersonalizedFlags.EnableRestore

chart1.PersonalizedFlags = chart1.PersonalizedFlags & ~PersonalizedFlags.EnableRestore;

Chart1.PersonalizedFlags = chart1.PersonalizedFlags And Not PersonalizedFlags_EnableRestore

Chart1.PersonalizedFlags = Chart1.PersonalizedFlags And Not PersonalizedFlags_EnableRestore


Capturing Mouse Events

Chart FX provides different properties, methods and events that allow you to control how the chart reacts to mouse interactions from the user. For example, you can customize the way tooltips are displayed, if the user is capable of dragging markers, thus changing the value for a particular point, or you can add your own code when the user right-clicks on a chart title. You can even simulate mouse clicks at a particular location in the chart to see if the user is positioned over a particular element in it.

Let's start by introducing the properties provided by Chart FX that will affect how the chart reacts to mouse interaction.

Marker Dragging

By default, a Chart FX chart is created with the AllowDrag property if set to "False". When set to TRUE, it allows the end user to change the value for a particular marker by positioning the mouse over a particular data point and dragging the marker to a desired value. Although this is a cool feature it is not useful if you don't want the user to change the values in the chart.

Menus on Demand

Another property related to mouse interaction in the chart is called ContextMenus. Whenever the user right-clicks a particular element in a chart, a menu on demand will appear with options to customize that particular element. For example, if a user right-clicks on the Y Axis, a menu will appear and the user will be able to access all axis properties. Setting the ContextMenus property to "False" will disable menus on demand in your chart.

Note: If you want to customize certain options "inside" each menu that appears when the user right-clicks a particular element in the chart, please refer to the "Customizing the Toolbar" chapter.

Customizing DataTips

By default, when the user positions the mouse over an element in the chart (Not the Toolbar) a tool tip will appear with specifics about the element. Particularly important are data points that display information, such as the series legend, the point legend and value, inside the tool tip. This behavior can be easily changed with the TipMask property, where you can specify the information you want inside a tool tip.

For example, if in an XY Plot, you want to modify the text displayed in the tool tip with just the X & Y Coordinates of the point, you can set the TipMask property with the variables you want to display in the tool tip as follows:

Chart1.TipMask = "%x%v"

chart1.TipMask = "%x%v";

This property can also be combined with custom text to provide a clearer message to the user. For example if you want the tool tip to display: "I'm Series 1 and my value is 13.5", you can set the TipMask property as follows:

Chart1.TipMask = "I'm series: "+"%S "+" my value is: "+"%v"

chart1.TipMask = "I'm series: "+"%S "+" my value is: "+"%v";

Although the TipMask property is the simplest way to customize data tips, the GetTip event is provided so you can add context sensitive information to particular data points in the chart. For example, you want a particular data tip to show specific text different than other points. When processing the GetTip event, you may detect which data tip is about to be displayed and change the message for that particular point only. Example:

Private Sub Chart1_GetTip(ByVal sender As Object, ByVal e As _
         SoftwareFX.ChartFX.GetTipEventArgs) Handles Chart1.GetTip

   'Capture tool tip text
   sOldtext = e.Text

   'Modify default text
   sNewText = "Hello, my value is " + sOldtext

   'Set the new text to the tool tip
   e.Text = sNewText

End Sub

private void chart1_GetTip(object sender, SoftwareFX.ChartFX.GetTipEventArgs e)
{
   //Capture tool tip text
   sOldtext = e.Text;

   //Modify default text
   sNewText = "Hello, my value is " + sOldtext;

   //Set the new text to the tool tip
   e.Text = sNewText;
}

Other Mouse Related Events

Chart FX provides several mouse events that allow you to customize how the chart reacts to mouse interaction coming from the user, they are: DoubleClick, MouseDown, MouseMove and MouseUp. You may process these events to add specific functionality in your application.

All mouse events return a MouseEventArgsX object which contains all necessary data to handle the event: Buttons, Clicks, HitType, Points, Series, X, Y, etc.


Tracking the Mouse

Sometimes you may need to track mouse movements in the chart area and detect where the mouse pointer is positioned and at which element the mouse is pointing. You can use the MouseMove event in conjunction with the HitType MouseEvent argument returned from the supported mouse events.

For example, if you want to highlight the Chart Title when the mouse moves over it, this is how your code should look:

Private Overloads Sub Chart1_MouseMove(ByVal sender As Object, _
                ByVal e As SoftwareFX.ChartFX.MouseEventArgsX) _
                Handles Chart1.MouseMove

   If e.HitType = HitType.Title Then

      ' Title Highlight code goes here.

   End If

End Sub

private Overloads void chart1_MouseMove(object sender,SoftwareFX.ChartFX.MouseEventArgsX e)
{

    If (e.HitType == HitType.Title)
    {
        // Title Highlight code goes here.
     }
}


Capturing Stylus taps in Smart Device applications

When interacting with the Chart, the stylus functions much like a computer mouse. Tapping with a stylus is equivalent to clicking with a mouse. When this event occurs in a chart created using Pocket Chart FX for .NET, the MouseDown event is raised.

The MouseDown event is the only mouse event supported by Pocket Chart FX for .NET. In the context of Smart Devices, it was decided this was the only relevant event to be supported.

When the MouseDown event occurs, a MouseEventArgsX event argument is returned. This object supports several attributes which contain information specific to where in the chart area the stylus tab occurred. These attributes include:

  • Button - Gets which mouse button was pressed. This works using the mouse with an emulator but is not really relevant when using an actual device with a stylus.
  • Handled - Allows you to specify if you would like Chart FX to perform its default processing or not.
  • HitType - Gets the element type hit when the event occurred.
  • Object - Gets the object hit by the user when the event occurred.
  • Point - Gets the Point index for the point of the mouse event. -1 if no point was selected.
  • Series - Gets the Series index for the point of the mouse event. -1 if no point was selected.
  • Value - Gets the value of the object hit in the event if it supports a value property.
  • X - Gets the x-coordinate of the mouse event.
  • Y - Gets the y-coordinate of the mouse event.

Below is an example of how the MouseDown event may be captured and handled in a Visual Basic Smart Device application:

' Capture the MouseDown event to track clicks on the chart.
' This is useful to implement drilldown.
Private Sub chart1_MouseDown(ByVal sender As Object, ByVal e As _
SoftwareFX.ChartFX.CF.MouseEventArgsX) Handles Chart1.MouseDown
    Dim sMessage As String
    Dim axis As SoftwareFX.ChartFX.CF.Axis
    ' Determine in what section of the chart occurred the click
    Dim ht As SoftwareFX.ChartFX.CF.HitType = e.HitType
    Dim X As Integer = e.X
    Dim Y As Integer = e.Y
    sMessage = String.Format("Type: {0}" + ControlChars.Lf + "X: {1} -_
    Y: {2}" + ControlChars.Lf, ht, X, Y)
    ' Click on a point
    If ht = SoftwareFX.ChartFX.CF.HitType.Point Then
        sMessage += String.Format("Point: {0}" + ControlChars.Lf + "Series: {1}"_
        + ControlChars.Lf, e.Point, e.Series)
    Else
        ' Click on an axis
        If ht = SoftwareFX.ChartFX.CF.HitType.Axis Then
            axis = CType(e.Object, SoftwareFX.ChartFX.CF.Axis)
            If axis Is Chart1.AxisX Then
                sMessage += String.Format("Axis: AxisX")
            Else
                sMessage += String.Format("Axis: AxisY")
            End If
        End If
    End If
    MessageBox.Show(sMessage)
End Sub

// Capture the MouseDown event to track clicks on the chart.
// This is useful to implement drilldown.
private void chart1_MouseDown(object sender, SoftwareFX.ChartFX.CF.MouseEventArgsX e)
{
    string sMessage;
    SoftwareFX.ChartFX.CF.Axis axis;
    // Determine in what section of the chart occurred the click
    SoftwareFX.ChartFX.CF.HitType ht = e.HitType;
    int X = e.X;
    int Y = e.Y;
    sMessage = String.Format("Type: {0} \n X: {1} - Y: {2}\n", ht, X, Y);
    // Click on a point
    if (ht == SoftwareFX.ChartFX.CF.HitType.Point)
          sMessage += String.Format("Point: {0} \n Series: {1}\n", e.Point, e.Series);
    else
    {
        // Click on an axis
        if (ht == SoftwareFX.ChartFX.CF.HitType.Axis) {
             axis = (SoftwareFX.ChartFX.CF.Axis) e.Object;
            if (axis == chart1.AxisX)
                sMessage += String.Format("Axis: AxisX");
            else
                sMessage += String.Format("Axis: AxisY");
        }
    }
    MessageBox.Show(sMessage);
}


Chart FX for .NET Localization

Chart FX for .NET can be localized to any language or culture. The following process describes how you may translate resource files using .NET Framework Tools and localize your Chart FX for .NET applications. (without using VS.NET)

SoftwareFX provides all the required resources, tools, commands, and special versions of the main Chart FX for .NET assemblies needed for the translation that will help make the process go smoothly. All the files needed to complete this process can be found in Localization.zip (localization package). After completing the translation of the provided resources, send these files to SoftwareFX via email to support@softwarefx.com so they may be compiled using the SoftwareFX strong name. Once completed, SoftwareFX will return the assembly required to begin working with the localized version.

The .NET Framework will only load satellite assemblies (localized assemblies) whose attributes match the main assembly, because of this and the fact that all ChartFX assemblies are signed using a SoftwareFX strong-name, we need to sign all localized assemblies. To help in the localization process we include two ChartFX assemblies (ChartFX.dll and ChartFX.Designer.dll) that are not strong-named, these assemblies should ONLY be used for localizing purposes and never distributed to end-users. These assemblies will allow you to test your localized resources without the need of our strong-name, once all resources are localized we will need to sign the resulting assembly so that it can be consumed by ChartFX.

Chart FX for .NET localization has been completed in the following languages. You may click the link to download a .zip containing the appropriate ChartFX.resources.dll:

  • Japanese
  • Korean
  • Spanish
  • German
  • Italian
  • French
  • Portuguese
  • Simplified Chinese

To use any of these translated resources, you must make sure it is installed in a subdirectory of your application named as the culture you are translating to (copy the ChartFX.resources.dll to this folder).

e.g. If you using Japanese, your folder name would be ja.

Below are the steps to complete the localization process, you can find more detailed information in the localization package:

  • Download Localization.zip and read the readme.rtf for details to complete the localization process. e.g. If you save the file SoftwareFX.Chart FX.UI.GeneralPage.resources in French, the file will be saved as SoftwareFX.ChartFX.UI.GeneralPage.fr.resources
  • Open and translate the file SoftwareFX.ChartFX.CfxStrings.txt, we recommend you rename this file using the same naming convention used by WinRes. Save this file in Unicode format. e.g. SoftwareFX.ChartFX.CfxStrings.fr.txt (for French translation)
  • Open and translate the file SoftwareFX.ChartFX.CmdStrings.txt, we recommend you rename this file using the same naming convention used by WinRes. Save this file in Unicode format. e.g. SoftwareFX.ChartFX.CmdStrings.fr.txt (for French translation)
  • Edit the Build.cmd and replace the XX placeholder with the culture code you are translating (e.g. fr for French translation)
  • Run the Build.cmd. Note that this command invokes the ResGen and AL tools, therefore, you may want to locate these tools on your hard drive and add the corresponding path in the Build.cmd or to your path environment variable. This command will generate ChartFX.Resources.dll.
  • To test your translated resource, you must make sure it is installed in a subdirectory of your application named as the culture you are translating to (copy the ChartFX.resources.dll to this folder).
  • To test your translated resource, you must make sure it is installed in a subdirectory of your application named as the culture you are translating to (copy the ChartFX.resources.dll to this folder). e.g. If you were translating to French, your folder name would be fr
  • If your regional settings do not match the culture you are translating, you should also set the Thread.CurrentThread.CurrentUICulture to the correct culture in your application. The following code should be placed into the Main function of your form and the Localizable property of your form should be set to true. Below is an example of how to set the Thread.CurrentThread.CurrentUICulture if you are translating to French in France:

Thread.CurrentThread.CurrentUICulture = New CultureInfo("fr")
Thread.CurrentThread.CurrentCulture = New CultureInfo("fr-FR")

Thread.CurrentThread.CurrentUICulture = new CultureInfo("fr");
Thread.CurrentThread.CurrentCulture = new CultureInfo("fr-FR");


Chart FX for .NET Internet Reference

Chart FX for .NET was designed for Webmasters and Internet Developers wanting to provide charts on their web sites or corporate intranets. To start using this product you must be familiarized with the following:

  • Hardware platform you are using to run your web site
  • Web Server software you are using (e.g. Internet Information Server, etc.)
  • Microsoft .NET Framework
  • A .NET programming language basics (VB.NET, C# or other)
  • Database access (including ADO.NET and ODBC)
  • HTML Language basics

This portion of the documentation will help you install and integrate Chart FX for .NET on your server with minimal effort. It will also describe in detail internet enabled features in this product and how it was designed to work seamlessly integrated with your web server to provide powerful charts to your users.

This reference help file does not intend to list or describe each property, object or method supported at the programming level. For that purpose please refer to the Chart FX for .NET API help file and the Resource Center, installed with Chart FX for NET.


Server Side Component

Chart FX for .NET provides a server-side component. This component performs the following important tasks:

  • Integration with database drivers like ADO.NET (ASP.NET) to connect to a database, retrieve data and populate the chart.
  • Provide support for the server-side execution language, or ASP.NET pages, which allow developers to customize how the chart looks before it is displayed on the browser.
  • Process the HTTP_USER_AGENT coming from the browser to determine the browser's ability to display active content and produce a compatible HTML tag so the charts can be viewed on any browser. This means, the Chart FX for .NET server-side component is responsible for the provision of a browser-neutral approach in Chart FX for .NET.
  • When the browser posting the request to the page containing a chart does not provide support for active .NET content, the Chart FX for .NET server-side component is responsible for rendering a compatible image such as a PNG or JPEG.
  • Generate image maps whenever a chart image contains links to URLs.

Server-Side Component Assemblies:

  • ChartFX.Internet.dll : This is the "main" assembly, if you are using a .NET development environment for building web apps, this is the library you want to add to your toolbox.
  • ChartFX.Base.dll: This assembly is referenced by ChartFX.Internet, if you are using a .NET development environment for building web apps, it should be automatically added to your references when you drop a chart into a web form and deployed to the bin folder of your app.
  • ChartFX.Data.dll: This assembly will need to be referenced when you use certain data providers to read data from sources such as text files, lists, XML files or Crosstab. A data related class, DataSourceSettings, is also included in this assembly and supports members such as DataSource and DataType.
  • ChartFX.Borders.dll: Reference this assembly if you want to use the additional borders or gradient backgrounds.
  • ChartFX.Annotation.dll: This assembly needs to be referenced when you want use an Annotation object in your chart.

Important Compatibility Note: The Chart FX for .NET server-side component requires a web server (such as Internet Information Server) to be running on a Windows box with the Microsoft .NET Framework properly installed.

Licensing considerations

The Chart FX for .NET server-side component is licensed on a per server basis for deployment, and on a per developer basis for development. For more information please refer to the Chart FX for .NET License Agreement or call (800) 392-4278 or email us to sales@softwarefx.com for more information on licensing arrangements.


Client Side Components

In many cases, your users will be using .NET Framework compatible systems to access your commercial web site or corporate intranet. For these users, Chart FX for .NET provides client-side components that allow them to interact with the charts directly from their browsers. These components are responsible for providing:

  • Access data pre-processed by Chart FX for .NET server-side component.
  • Fully interactive charts on their browsers.
  • A pleasant experience from your web site.

Although client-side components may be used independently, the most common way to use it is in conjunction with the Chart FX for .NET server-side components. Integrating them into your web site is a transparent process, because the server will return an HTML tag to instantiate the appropriate component model or to generate an image whenever the browser does not support any .NET component or Chart FX for .NET doesn't support such platform. Therefore, using these components DOES NOT mean limiting or restricting the user base you can reach. Please remember, Chart FX for .NET will always provide a compatible tag with the browser being used by the client.

ChartFX for .NET currently provides the following client component:

  • .NET Client Control for Internet Explorer
    This control is automatically downloaded by Internet Explorer 5.01 or later. It allows the end user to interact with the chart directly from the browser. This component is located in the /ChartFX6/Download virtual directory of your web server. Installation is automatic since it uses only .NET managed code.

Client-Side Component Assemblies:

  • ChartFX.Internet.Client.dll: This is the main assembly, equivalent to ChartFX.Internet.dll in the server.
  • ChartFX.MainClient.dll: This is the client assembly downloaded when MainClient is set to true. Please see "Decreasing Chart Download Time" in the Performance and Scalability section.
  • ChartFX.Internet.Base.dll, ChartFX.Internet.Borders.dll, ChartFX.Writer.Accessibility.dll, ChartFX.Writer.SVG.dll and ChartFX.Annotation.dll : These assemblies are equivalent to their counterparts in the server.

Important Compatibility Note: The Chart FX for .NET client-side component is provided only for versions of Windows with the .NET Framework properly installed, including Windows 98 and Windows NT/2000/XP.

Please call Software FX, Inc. for more information on the availability of additional Chart FX for .NET client-side components. Our phone number is (800) 392-4278 or refer to our web site at http://www.softwarefx.com for the latest client components information.

Licensing Considerations

The Chart FX for .NET client-side components are royalty-free for distribution provided that you do not redistribute the LIC files required to instantiate them on a browser; this LIC file must always remain on your server. For more information on licensing options please contact us at (800) 392-4278 or email us at sales@softwarefx.com.


Designer Components

Because Chart FX for .NET provides an extensive API (Application Programming Interface) or properties and methods that allow developers to customize how the chart looks, it provides designer components that allow developers to make the chart's configuration process faster and easier. The following Designer components are provided with Chart FX for .NET:

  • .NET Web Forms Design-time Component
    This control is used within a .NET development tool Web Forms designer. This component allows developers to quickly integrate and customize charts as the developers interact with the property pages and UI (User Interface) of the chart. This is extremely important as you will be able to create a chart in just minutes without learning a single property or method from the Chart FX for .NET API.

The Chart FX for .NET design-time components are programming utilities. Therefore, these tools are not intended for end users.

Designer Component Assemblies:

  • Designer Component Assemblies:

Licensing Considerations

The Chart FX for .NET Design-time components are licensed on a per developer basis. With Chart FX for .NET you have 1 license of the Chart FX for .NET Designer components. If you have additional developers, you must purchase additional development licenses. For more information on licensing options and pricing please contact us at (800) 392-4278 or email us at sales@softwarefx.com.


Requirements

Installation Requirements

To properly install and run Chart FX for .NET on a production or development server you will need the following:

  • Windows server with Internet Information Server (IIS) or any other .NET compatible web server
  • Microsoft .NET Framework 1.0 or above

Additionally, for the development of the web pages/applications you will require:

  • A .NET Development environment, e.g. Borland C# Builder, Visual Studio .NET, Visual Basic .NET, etc.


Installation

Installing Chart FX for .NET to create Web applications

Because Chart FX for .NET provides Production and Development installations, there are two steps you need to complete to properly install this product:

Installation on systems used to develop the web pages/applications

Chart FX for .NET provides a Development components setup file (CfxNetDevelopment.exe).This will copy and configure all the necessary files, including documentation and samples, that will be required by your .NET Development tool, and a Chart FX for .NET Test Server, which is specially designed for development purposes.

This installation will setup all the necessary assemblies so that you can integrate charts and debug your Web Forms projects. This way, developers can properly develop and test their application in development machines. This setup requires a web server to be installed and properly configured on the development machine.

Please note that the Chart FX for .NET Development components are licensed on a per developer basis. With your purchase of Chart FX for .NET, you received 1 licensed copy of these components which entitles use for 1 developer only. If you have additional developers you must purchase additional development licenses.

Installation on a Production web server

There's a Production Server setup file (CfxNetProduction.exe). This file must be run on the machine that is acting as the Production web server. This setup application requires a web server to be installed and properly running on the machine.

Please note that the Chart FX for .NET Production servers are licensed on a per server basis. With your purchase of Chart FX for .NET, you received 1 licensed copy of these components which entitles deployment on 1 Production server only. If you need to deploy it to additional servers you must purchase additional deployment licenses. Software FX also offers volume discounts and OEM agreements for developers in need to integrate Chart FX for .NET in their web applications. Please contact us at (561) 999-8888, (800) 392-4278 or email us sales@softwarefx.com.

If you are installing Chart FX for .NET on a Windows NT box, you may want to learn about IIS Installation Issues

Important Client-side Components Information

The Chart FX for .NET client-side components are included in the Development and Production setup applications. These files are copied in the /ChartFX62/Download virtual directory of your web server so they can be properly downloaded and installed by client systems. These files are downloaded by the browser automatically when the chart is rendered as a client component. These files can not be redistributed unless are used in conjunction with the server components. For further licensing details please contact Software FX at sales@softwarefx.com.


Installation Issues

Internet Information Server Issues

Both, the Development and Production setup applications will copy all server and client components and will create the appropriate directories to make Chart FX work properly with IIS. The following virtual directories will be created under wwwroot:

ChartFXInt62 directory will be created to store the files specific to this version of Chart FX. This way you may have installed multiple versions of Chart FX that will not collide with each other. Inside ChartFXInt62 there will be created the following subdirectories:

  • /Download directory will be created with the Client component files.
  • /Temp directory will be created to store all charts temporary files. Whenever a browser posts a request for a page that contains a chart, the Chart FX server-side component will create either an image (PNG or JPEG) or a chart file (CHW) or any other file type used to render charts, such as SVG or Flash. These files are later downloaded by the browser to display the chart on the client. These files can be removed by a utility shipped with Chart FX called SfxRemove. If you want to prevent file or image generation because of security issues, you may also generate a bit stream containing the chart file preventing the generation of a file in this directory. This topic is discussed later in this chapter.

You can change the location of the Temp directory by changing the file ChartFX.Internet.config installed in the same directory where the Chart FX server dll resides.


ChartFX.Internet.Config

Chart FX supports the use of configuration files that may be used to store web application settings. A variety of different settings may be controlled from this XML configuration file. Some of the supported attributes include the Relative path, RequiredRoot, DefaultWriter, etc. Please review the table below for a complete explanation of the supported configuration tags:

To utilize this configuration, developers must include the file in the directory on the server where the server dll resides. At the time of chart creation, the configuration file will be loaded and used by the Chart FX server assemblies. Therefore it is required that this file be manually copied to the web server.

Here is an example of a valid ChartFX.Internet.Config file:

<CfxIESettings>
    <Relative>/ChartFX62/Temp</Relative>
    <RequiredRoot>http://yourServer.com</RequiredRoot>
</CfxIESettings>

<CfxIESettings>
  <Relative>/ChartFX62/Temp</Relative>
  <RequiredRoot>http://yourServer.com</RequiredRoot>
</CfxIESettings>

<CfxIESettings>
  <Relative>/ChartFXInt62/Temp</Relative>
  <RequiredRoot>http://yourServer.com</RequiredRoot>
</CfxIESettings>


Accessing a Web Forms Application

If you are developing a Web Forms application, it helps to understand exactly what takes place when running your application from your .NET development tool for debugging or testing purposes or when your end users access the application with the browser. For information about integrating Chart FX for .NET into a Web Forms project, please see the "Integrating and Deploying Chart FX for .NET" section.

An application is defined as a set of files in an IIS virtual directory and its subdirectories. For example, if you create a Web Forms project with Visual Studio .NET or Borland C# Builder, a new virtual directory is automatically created for you. On top of the files and directories that constitute an ASP.NET application, the IDE will automatically copy the necessary Chart FX for .NET assemblies into the application's bin directory. Please refer to your .NET development tool documentation for more information on how the Web Forms applications are handled.

Additionally, the Chart FX for .NET Server control uses a ChartFX62 virtual directory that was automatically created by the Chart FX for .NET installer on IIS. The following additional sub-directories were created:

  • Temporary directory (/Temp), used to store chart files that will be loaded by the browser when the application is accessed.
  • Download directory (/Download), where the appropriate .NET components are stored in the form of dll. These .NET components make user interaction possible in the browser.

For additional information on the location and specific settings of these directories, please access the Internet Information Services console found in Administrative tools of your development machine or web server.

Essentially, the Web Forms page works as a container for the charts and other design elements. The logic is then added in a separate file ("aspx.vb" or "aspx.cs") from the user interface file. This file is referred to as the "code-behind" file. The code-behind class files for all Web Forms pages in a project are compiled into the project dynamic-link library (.dll). The first time a user browses to the .aspx page, ASP.NET automatically generates a .NET class file that represents the page, and compiles it to a second .dll file.

When a user or your IDE requests the web page URL, the .dll files run on the server and dynamically produce the chart and other HTML output for your page. If you selected an image as your chart output method, then the file will be dynamically produced and stored in the /temp directory. If an active .NET component is required, then an assembly will be requested from the /download directory, installed on the client and finally a proprietary chart file will be created in /temp directory, this file will then be automatically downloaded and displayed on by the Chart FX Client control.

Please note that the Chart FX client controls are royalty-free for distribution, when used in conjunction with the server components. However, it is accompanied by a licensing scheme that will not allow your end users to develop applications with it.


Controlling Chart's Size

When you drop a chart in a Web form you are free to resize it accordingly. When you resize the chart you are essentially instructing the server component to generate a chart of those dimensions.

Nevertheless, If you plan to use a .NET component on the browser, you can use the Height and Width properties with percentages so the control can be properly resized according to the browser's window size on the client.

This technique is particularly useful with charts that are displayed as a single control in an application as it improves readability when the user maximizes or resizes the browser. For example, if you want the chart to occupy 100% of the browser's width and 80% of its height, you can set the Width and Height properties as depicted in the picture.

If the user resizes the browser, the chart control accommodates itself to the new size using these percentages. However, if a browser hits this page and an image must be generated (because the browser does not allow client side components), then the resulting image will be generated with a fixed size, producing undesired results when the percentages are applied.

Important: Please note you can also set the Width and Height properties to a specific number of pixels.

The way to solve this limitation (and be able to combine percentages with a fixed image size) is to use the Width and Height properties in conjunction with the ImgWidth and ImgHeight properties of the chart object. For example, if you set the following properties:

chart.ImgWidth = 500
chart.ImgHeight = 300

and

chart.Width = 100%
chart.Height = 80%

Chart FX will be able to generate the percentages when the client side component is used, and an expected image size when image generation is required.


Setting Image Properties

Because the Chart FX Server control is capable of generating images, a series of properties are provided so you can control various aspects of image generation. These properties are:

ImgQuality: sets the quality of JPEG images. It applies to JPEG images only, with range from 0 (lowest quality) to 100 (highest quality).

ImgSizeable: is a Boolean property that indicates if the image is resizable when percentages are specified in the Width or Height properties. More info on "Controlling the chart size" was available previously in this chapter.

ImgMap: refers to the Image Map generation capability. More info on the "Image Maps" topic later in this manual.

SmoothFlags: controls the smoothness of the image, using anti-aliased rendering. It can be set for the Chart's inside, border and text.

ImgTags : is a string property that will be appended to the IMG tag created by Chart FX. For example you can set this property to BORDER=0 in which case the resulting <IMG> tag will have that string inside of it.


Selecting the Chart's Output

As a server control, Chart FX supports a method called GetHtmlTag that allows the developer to select, among other things, the type of desired output for your charts. By default, Chart FX will generate a PNG image of the chart, yet you may configure the getHtmlTag method or the HtmlTag property to the desired format. Among the options, Chart FX can generate the following chart formats:

ActiveX

Format: ActiveX.
Comments: ActiveX component download is required on the browser.
Interactivity: Full interactivity (including user toolbar).
Accessibility: Internet Explorer 4 or above is required.

.NET

Format: .NET format.
Comments: Component is required on the browser. Full managed code, no signatures are required. Full security.
Interactivity: Full interactivity (including user toolbar).
Accessibility: Windows .NET clients only. For more information related to the .NET Client Control format, please read "The Truth about Client Controls" pdf file available from our website.

PNG

Format: Raster format.
Comments: Best image format for producing charts.
Interactivity: Provides limited interactivity through image maps.
Accessibility: Supported in most current browsers.

JPEG

Format: Raster format.
Comments: Slightly faster than PNG, however, charts are not as crisp.
Interactivity: No interactivity.
Accessibility: Universal access.

SVG

Format: Vector format.
Comments: Enhances performance significantly; files are small and painted on the client.
Interactivity: Limited interactivity.
Accessibility: Accessible from many platforms.

Flash

Format: Macromedia Flash format.
Comments: Enhances performance significantly; files are generated and later viewed using rich client technology.
Interactivity: Limited interactivity.
Accessibility: Accessible from many platforms.

By default, Chart FX will generate an image. By setting the third parameter to "Auto", Chart FX will generate the most interactive format depending on the User Agent of the browser requesting the chart. If the browser is Internet Explorer with the .NET Framework installed, Chart FX will generate a .NET component. If the browser is Internet Explorer 4 or above, without the .NET Framework, an ActiveX will be generated. For the rest of the browsers an image will be generated in Png or Jpeg format, depending on the browser's capabilities.


Image Generation

Although Chart FX was designed so the user can take advantage of the browser capability to display Active Charts, many developers want to stay away from client-side components and want to force image generation no matter what kind of browser or OS the client is using. Chart FX is even more powerful as it allows you to generate Image Maps which will allow your users to click on a particular chart marker that has been defined as a link in the code. Therefore, chart images are no longer static images since you can actually create entire applications based on the images created by Chart FX.

Forcing Chart FX to Generate Images

In order to force Chart FX to always generate images, you must change the GetHtmlTag method and prevent the automatic Browser Detection capability. If you change the third parameter of the GetHtmlTag method to "Image", Chart FX will generate images no matter what the browser being used to access the page is. In order to generate images, your GetHtmlTag method call should look like:

<%=chart.GetHtmlTag(500,300,"Image")%>

What image formats can Chart FX generate?

If you read the GetHtmlTag definition carefully, you'll notice that "PNG" and "JPEG" are supported as possible parameters (instead of "Image"). This means Chart FX is capable of generating JPEG and PNG images.

PNG Images

The PNG algorithm is particularly effective for drawing vector images (such as charts), as images will experience no quality degradation or color dithering. This format came as a response to Unisys prohibiting the public distribution of the GIF generation algorithm. This format is even better in terms of quality and compression than GIF and supports many more features, such as transparency, interlaced, 24-bit palettes and many other advantages over GIF images.

This means PNG is the preferred image format for Chart FX. However, the drawback is that many older browsers do not support this image format. Therefore, the JPEG format is also available for these older browsers.

JPEG Images

This format was created to compress and display photo quality images (not vector images such as charts). As a result, displaying charts using this algorithm is not advisable as you will obtain quality degradation and color dithering when creating JPEG images.


DrillDown Capabilities

In most situations, you will want to let the user click on a particular chart element to request another page which in turn provides information about the clicked marker (or series). However, this is a major issue taking into consideration that the Chart FX Server component can generate active charts (ActiveX and .NET Client Controls) or images. You will be happy to know, not only does Chart FX support drill down capabilities but it also allows you to:

  • Generate Image Maps when PNG or JPEG Images are being generated. This allows users to drill down even when charts images are generated by the server component.
  • Pass parameters from the referrer URL, for example, when a user clicks on a particular series you can decide to pass parameters like value, series and other related chart information. This takes only a property setting and allows you to customize the resulting page using information coming directly from the chart.
  • Customize the drill down capabilities. If you want to redirect the request when the user clicks on different chart objects, such as points, series, title, stripes and constant lines, you can easily customize this setting.
  • Reload charts without reloading the entire page. This creates a seamless storyboard effect as the page will not be reloaded when a chart is invoked in the same bounding rectangle.

The Drill Down API

The Chart FX server-side component provides several important properties that allow you to achieve drill down capabilities:

Link.Url
Each different object that supports drill down capabilities will provide a Link object. Using the supported members of this class, the Url may be configured. It's a string of the URL to be invoked when a user clicks on the objects. Chart FX provides the Link object for the following objects:

  • Chart.Link.Url: when this general property is set, all the markers will invoke this URL when clicked.
  • Chart.Series(<index>).Link.Url: each particular Series can have its own URL string. This property overrides the generic Chart.Link.URL if it has been set.
  • Chart.Point(<series>,<index>).Link.Url: a specific marker can have its own URL string. This property overrides the generic Chart.Link.URL and the Chart.Series.Link.URL properties.
  • Chart.Title(<index>).Link.Url: each Title can be set its own specific URL string, which will be invoked when the user clicks on the title.
  • Chart.Stripe(<index>).Link.Url: each Stripe will support an indivually set URL string.
  • Chart.ConstantLine(<index>).Link.Url: each ConstantLine can have its own URL.

IMPORTANT NOTE: The Url property supports flags that may be used to configure parameters for the configured Url. The same flags that are supported with the TipMask property are supported in the URL property. For example, if you wanted to jump to a page and pass the series and point index for the point of a URL, the following code could be used:

'Use the URL Parameters for the Series (%S) and Point (%N)
Chart.Link.Url = "chart2.aspx?Series=%S&Point=%N"

//Use the URL Parameters for the Series (%S) and Point (%N)
Chart.Link.Url = "chart2.aspx?Series=%S&Point=%N";

'Use the URL Parameters for the Series (%S) and Point (%N)
Chart.Link.Url = "chart2.aspxSeries=%S&Point=%N"

'Use the URL Parameters and invoke a client side javascript
Chart.Link.Url = "JavaScript:MyFunction(%v)"

//Use the URL Parameters and invoke a client side javascript
Chart.Link.Url = "JavaScript:MyFunction(%v)";

'Use the URL Parameters and invoke a client side javascript
Chart.Link.Url = "JavaScript:MyFunction(%v)"

Link.Reload
Boolean that allows you to specify whether Chart FX will reload the chart or jump to another page.

Link.Target
String property that contains the target frame or HTML Frame that should be used when jumping. It's the same for all the objects.

IMPORTANT NOTE: Chart FX does not maintain a history of the charts invoked using this methodology, therefore it is your responsibility to generate the appropriate URLs in the web pages that are being invoked by the referer.


DrillDown Sample

The first step is to configure the Link.Url property for the desired chart object. You may set this property globally by utilizing the Chart.Link object Url property, or specific to the desired objects using the supported class member. For example, you can set a unique URL for the Series, Point, Title, Stripe or Constant Line as noted above. In this sample the Chart.Link object Url property is used:

'Assign the URL which the Drill Down will connect
Chart1.Link.Url = "ParamNet.aspx"

//Assign the URL which the Drill Down will connect
chart1.Link.Url = "ParamNet.aspx";

'Assign the URL which the Drill Down will connect
Chart1.Link.Url = "Param.asp"

Next, you can specify whether the Drill Down will 'jump' to another page or 'reload' the chart in the current page. This can be configured using the Reload property supported by the Link object:

'Specify to Jump to the configured URL
Chart1.Link.Reload = False

//Specify to Jump to the configured URL
chart1.Link.Reload = false;

'Specify to Jump to the configured URL
Chart1.Link.Reload = False

The Target property will specify the target frame for the configured URL to be loaded, and should be configured when the Link.Reload property is configured to 'False''. In this sample, the Link.Target is configured to the string '_blank' which will load the configured URL in a new browser instance:

'Specify to load the configured URL in a new
browser instance
Chart1.Link.Target = "_blank"

// Specify to load the configured URL in a new
browser instance
chart1.Link.Target = "_blank";

'Specify to load the configured URL in a new
browser instance
Chart1.Link.Target = "_blank"

Finally, the URL property allows you to configure the parameters to pass to the configured URL. You may set your own custom parameters or use the supported mask flags to pass information specific to the chart element selected. Please see the Chart.TipMask property in the API Reference for the supported settings (they are the same for both properties):

'Specify the parameters to pass
Chart1.Link.Url="chart.aspx?MyParam=1&Series_Index=%S&Points_Index=%N&Value=%v&Label=%l&Tag_String=%L"

// Specify the parameters to pass
chart1.Link.Url="chart.aspx?MyParam=1&Series_Index=%S&Points_Index=%N&Value=%v&Label=%l&Tag_String=%L";

'Specify the parameters to pass
Chart1.Link.Url="chart.asp?MyParam=1&Series_Index=%S&Points_Index=%N&Value=%v&Label=%l&Tag_String=%L"

Below is the complete sample (drilldownjump.asp) using the assignments below. The URL is configured to a second script (param.asp) which displays the configured parameters:

' Cosmetic Code
Chart1.Gallery = SoftwareFX.ChartFX.Gallery.Bar

Dim title As SoftwareFX.ChartFX.Internet.Server.TitleDockable = Chart1.Titles(0)
title.Alignment = System.Drawing.StringAlignment.Center
title.Text = "Drill Down"
title.TextColor = System.Drawing.Color.Black

Dim borderObj As New SoftwareFX.ChartFX.Borders.ImageBorder()
borderObj.Type = SoftwareFX.ChartFX.Borders.ImageBorderType.Colonial
Chart1.BorderObject = borderObj

'Create the object on the server
Chart1.OpenData(SoftwareFX.ChartFX.COD.Values, 2, 4)
Chart1.Value(0, 0) = 70.00
Chart1.Value(1, 0) = 77.00

Chart1.Value(0, 1) = 53.34
Chart1.Value(1, 1) = 45

Chart1.Value(0, 2) = 57.95
Chart1.Value(1, 2) = 55.07

Chart1.Value(0, 3) = 28.96
Chart1.Value(1, 3) = 81.45

Chart1.Value(0, 4) = 30.19
Chart1.Value(1, 4) = 60.9
Chart1.CloseData(SoftwareFX.ChartFX.COD.Values)

Chart1.Legend(0) = "Jan"
Chart1.Legend(1) = "Feb"
Chart1.Legend(2) = "Mar"
Chart1.Legend(3) = "Apr"
Chart1.Legend(4) = "May"

Chart1.Point(0, 0).Tag = "Tag string 1"
Chart1.Point(0, 1).Tag = "Tag string 2"
Chart1.Point(0, 2).Tag = "Tag string 3"
Chart1.Point(0, 3).Tag = "Tag string 4"
Chart1.Point(0, 4).Tag = "Tag string 5"

Chart1.Point(1, 0).Tag = "Tag string 6"
Chart1.Point(1, 1).Tag = "Tag string 7"
Chart1.Point(1, 2).Tag = "Tag string 8"
Chart1.Point(1, 3).Tag = "Tag string 9"
Chart1.Point(1, 4).Tag = "Tag string 10"

'Assign the URL where you want to connect with Url Parameters.
'Please note other URL Parameter flags are supported
Chart1.Link.Url = "paramNet.aspx?Series=%S&Point=%N&Value=%v&Label=%l&Tag_String=%L"
Chart1.Link.Target = "_blank"
Chart1.Link.Reload = False

// Cosmetic Code
chart1.Gallery = SoftwareFX.ChartFX.Gallery.Bar;
SoftwareFX.ChartFX.Internet.Server.TitleDockable title = chart1.Titles[0];
title.Alignment = System.Drawing.StringAlignment.Center;
title.Text = "Drill Down";
title.TextColor = System.Drawing.Color.Black;
SoftwareFX.ChartFX.Borders.ImageBorder borderObj = new SoftwareFX.ChartFX.Borders.ImageBorder();
borderObj.Type = SoftwareFX.ChartFX.Borders.ImageBorderType.Colonial;
chart1.BorderObject = borderObj;
// Create the object on the server
chart1.OpenData(SoftwareFX.ChartFX.COD.Values, 2, 4);
chart1.Value[0, 0] = 70.00;
chart1.Value[1, 0] = 77.00;

chart1.Value[0, 1] = 53.34;
chart1.Value[1, 1] = 45;

chart1.Value[0, 2] = 57.95;
chart1.Value[1, 2] = 55.07;

chart1.Value[0, 3] = 28.96;
chart1.Value[1, 3] = 81.45;

chart1.Value[0, 4] = 30.19;
chart1.Value[1, 4] = 60.9;
chart1.CloseData(SoftwareFX.ChartFX.COD.Values);

chart1.Legend[0] = "Jan";
chart1.Legend[1] = "Feb";
chart1.Legend[2] = "Mar";
chart1.Legend[3] = "Apr";
chart1.Legend[4] = "May";
chart1.Point[0, 0].Tag = "Tag string 1";
chart1.Point[0, 1].Tag = "Tag string 2";
chart1.Point[0, 2].Tag = "Tag string 3";
chart1.Point[0, 3].Tag = "Tag string 4";
chart1.Point[0, 4].Tag = "Tag string 5";

chart1.Point[1, 0].Tag = "Tag string 6";
chart1.Point[1, 1].Tag = "Tag string 7";
chart1.Point[1, 2].Tag = "Tag string 8";
chart1.Point[1, 3].Tag = "Tag string 9";
chart1.Point[1, 4].Tag = "Tag string 10";
// Assign the URL where you want to connect with Url Parameters.
// Please note other URL Parameter flags are supported
chart1.Link.Url = "paramNet.aspx?Series=%S&Point=%N&Value=%v&Label=%l&Tag_String=%L";
chart1.Link.Target = "_blank";
chart1.Link.Reload = false;

Dim chart1
Set chart1 = Server.CreateObject("ChartFX.ASP.Server")
' Cosmetic Code
chart1.Gallery = Gallery_Bar
Dim title
Set title = chart1.Titles(0)
title.Alignment = StringAlignment_Center
title.Text = "Drill Down"
title.TextColor = RGB(0,0,0)
Dim borderObj
Set borderObj = Server.CreateObject("ChartFX.ASP.ImageBorder")
borderObj.Type = ImageBorderType_Colonial
chart1.BorderObject = borderObj
' Create the object on the server
chart1.OpenData COD_Values, 2, 4
chart1.Value(0, 0) = 70
chart1.Value(1, 0) = 77
chart1.Value(0, 1) = 53.34
chart1.Value(1, 1) = 45
chart1.Value(0, 2) = 57.95
chart1.Value(1, 2) = 55.07
chart1.Value(0, 3) = 28.96
chart1.Value(1, 3) = 81.45
chart1.Value(0, 4) = 30.19
chart1.Value(1, 4) = 60.9
chart1.CloseData COD_Values
chart1.Legend(0) = "Jan"
chart1.Legend(1) = "Feb"
chart1.Legend(2) = "Mar"
chart1.Legend(3) = "Apr"
chart1.Legend(4) = "May"
chart1.Point(0, 0).Tag = "Tag string 1"
chart1.Point(0, 1).Tag = "Tag string 2"
chart1.Point(0, 2).Tag = "Tag string 3"
chart1.Point(0, 3).Tag = "Tag string 4"
chart1.Point(0, 4).Tag = "Tag string 5"
chart1.Point(1, 0).Tag = "Tag string 6"
chart1.Point(1, 1).Tag = "Tag string 7"
chart1.Point(1, 2).Tag = "Tag string 8"
chart1.Point(1, 3).Tag = "Tag string 9"
chart1.Point(1, 4).Tag = "Tag string 10"
' Assign the URL where you want to connect with Url Parameters.
' Please note other URL Parameter flags are supported
chart1.Link.Url = "paramNet.aspx?Series=%S&Point=%N&Value=%v&Label=%l&Tag_String=%L"
chart1.Link.Target = "_blank"
chart1.Link.Reload = False

param.asp

<HTML>
<BODY>
Parameters passed to this page
from Chart FX for .NET:<br>
<p>
<TABLE BORDER=1>

<TR>
<TD><b>Variable</b></TD>
<TD><b>Value</b></TD>
</TR>
<%
int loop1, loop2;
' Load NameValueCollection
object.
'BOLD=1
NameValueCollection
coll=Request.QueryString;
'BOLD=0
' Get names of all keys into a string
array.
String[] arr1 = coll.AllKeys;
for (loop1 = 0; loop1 <
arr1.Length; loop1++)
{%>
<TR><TD><%= arr1[loop1]
%></TD>

<%
String[] arr2 = coll.GetValues(arr1[loop1]);
for (loop2 = 0; loop2 <
arr2.Length; loop2++)
{
%>
<TD><%= arr2[loop2]%></TD></TR>
<%
}
}
%>
</TABLE>
<hr>
</BODY>
</HTML>

<HTML>
<BODY>
Parameters passed to this page
from Chart FX for .NET:<br>
<p>
<TABLE BORDER=1>

<TR>
<TD><b>Variable</b></TD>
<TD><b>Value</b></TD>
</TR>
<%
int loop1, loop2;
// Load NameValueCollection
object.
//BOLD=1
NameValueCollection
coll=Request.QueryString;
//BOLD=0
// Get names of all keys into a string
array.
String[] arr1 = coll.AllKeys;
for (loop1 = 0; loop1 <
arr1.Length; loop1++)
{%>
<TR><TD><%= arr1[loop1]
%></TD>

<%
String[] arr2 = coll.GetValues(arr1[loop1]);
for (loop2 = 0; loop2 <
arr2.Length; loop2++)
{
%>
<TD><%= arr2[loop2]%></TD></TR>
<%
}
}
%>
</TABLE>
<hr>
</BODY>
</HTML>

<HTML>
<BODY>
Parameters passed to this page
from ChartFX Internet:<br>
<p>
<TABLE BORDER=1>

<TR>
<TD><b>Variable</b></font></TD>
<TD><b>Value</b></font></TD>
</TR>
<%
For Each param In Request.QueryString
     value = Request.QueryString(param)
%><TR><TD><%= param %></TD><TD><%= value %></TD></TR>
<% Next %>
</TABLE>
<hr>
</font>
</BODY>
</HTML>


Image Maps Generation

Chart FX is able to generate Image Maps for charts generated as images. Image Maps are commonly used for providing DrillDown capabilities in image charts. Also, image maps are useful for showing ToolTips in image charts, even without using Chart FX's DrillDown capabilities.

DrillDown charts will be functional even when Chart FX generates images (PNG or JPEGs). This way your original site functionality will not be lost when Chart FX can't provide active client-side components to the browser or if you have decided that Chart FX will always generate images.

Before you read this topic, please make sure you understand how to setup drill down capabilities for the charts. For more information please refer to the DrillDown Capabilities section.

When Chart FX is producing an image and the DrillDown capabilities are enabled in the code, Chart FX will generate a client-side Map with the location of the different markers in the resulting image.

These maps may be quite large depending on the number of points and series you have in your chart. Therefore, you must be aware that generating Image Maps could represent a work overload on your server. Please note that the number of lines in the image map depends on the number of markers in your chart, e.g. a 3D bar chart with 2 series and 10 points will generate an image map with 2*10*3 objects. (3 polygons are required to paint a 3D bar chart)

The resulting image map has the following characteristics:

  • It is embedded in the resulting page. External image maps are not supported.
  • It is a client side image map. This means the browser is responsible for processing the mouse position.
  • You can control how to generate the Title attribute in the AREA tags with the ImgMap property.

IMPORTANT NOTE: Image Maps are not supported for Curve charts or when you are using the BitStream chart generation capability of Chart FX.

How are parameters appended to the actual link in the image map?

The answer to this question can be found in the DrillDown Capabilities section. Basically, the URL property supports a mask you can use in the parameters section of your URL, which are passed to the page that is being called as a result of a click in an AREA pointed by the Image Map. For example, if you setup the code as follows:

Chart.URL = "DrillParam.aspx?Series=%s&Value=%v"
Chart.Reload = True

chart.URL = "DrillParam.aspx?Series=%s&Value=%v";
chart.Reload = true;

chart.URL = "DrillParam.asp?Series=%s&Value=%v"
chart.Reload = True

Then the Image Map will be generated with a link like:

DrillParam.aspx?Series=1&Value=30.6

DrillParam.aspx?Series=1&Value=30.6

DrillParam.asp?Series=1&Value=30.6

IMPORTANT NOTE: Chart FX handles escaping its own strings (+ instead of space). Therefore, you don't have to worry about encoding the URLParamMask. In other words, when you invoke a page with parameters that contains blank spaces you must replace blank spaces with + signs; this can be done through URL Encoding. Chart FX, however, does this for you in case you're passing a string that contains spaces.

Can I control ToolTips that are shown in the chart?

The TipMask property allows you to configure the text that is to be shown when the user positions the mouse over a particular element in the chart that belongs to the Image map. However, because browsers support ToolTips in a different way, Chart FX provides the ImgMap property which allows you to control how the ToolTip will appear; it takes one of the following settings:

ImgMap.TitleTip

If you are displaying your charts on Internet Explorer 3.0 and above, the ToolTip will be displayed with the contents of the TITLE attribute. Therefore, when you set the ImgMap property to this setting it will show the ToolTip in Internet Explorer. This feature is not supported by Netscape but looks great in Internet Explorer.

ImgMap.MouseTip

If you want to achieve browser independence for displaying ToolTips you can set the ImgMap property to this setting which allows you to invoke a javascript to show the ToolTip on any browser. It will add the following function calls to the AREA tag:

onmouseover="popupon('<ToolTip>',event)": this function will be called when the mouse passes over the Image Map area.

onmouseout="popupoff()": this function will be called when the mouse abandons the Image Map area.

You will be responsible for the implementation of these functions. For further details on how to implement a browser independent displaying ToolTips see the following sample.

For example, if you want to show ToolTips in all browsers you can setup your code as follows:

' Create the chart object on the server
Dim Chart1 As Chart
Chart1 = New Chart(Me)
' Generate Title attribute in AREA tags
Chart1.ImgMap = ImgMap.MouseTip

' If you want to customize the string that appears on the tooltip you
' can use the TipMask property
Chart1.TipMask = "Value is %v"

' This chart will jump to the same URL passing parameters depending on
' where you click

Chart1.Link.URL = "DrillParam.aspx"

// Create the chart object on the server
Chart Chart1 = new Chart(this);
// Generate Title attribute in AREA tags
Chart1.ImgMap = ImgMap.MouseTip;
// If you want to customize the string that appears on the tooltip you
// can use the TipMask property
Chart1.TipMask = "Value is %v";
// This chart will jump to the same URL passing parameters depending on
// where you click

Chart1.Link.URL = "DrillParam.aspx";

Dim Chart1
Set chart1 = Server.CreateObject("ChartFX.ASP.Server")
' Generate Title attribute in AREA tags
Chart1.ImgMap = ImgMap_MouseTip

' If you want to customize the string that appears on the tooltip you
' can use the TipMask property
Chart1.TipMask = "Value is %v"

' This chart will jump to the same URL passing parameters depending on
' where you click

Chart1.Link.URL = "DrillParam.asp"

IMPORTANT NOTE: Annotation Tools with the URL property will also have its corresponding Image Map. This way you can link using chart elements and annotation objects in your chart.


SVG Generation

One of the most useful features of Chart FX is its versatility to render charts in different formats, in order to take advantage of the browser capability to display active content. One of the formats supported by Chart FX is SVG (Scalable Vector Graphics).

Based on XML (Extensible Markup Language), SVG is a graphics format that will allow Web designers to add high-quality interactive vector graphics and animation to Web pages using only plain text commands. SVG enables Web developers and designers to create dynamically generated graphics from real-time data with precise structural and visual control. With this powerful new technology, developers can create a new generation of Web applications utilizing data-driven, interactive and personalized graphics.

Chart FX can provide DrillDown functionality to charts using the SVG format, in the same way that is done with Image Maps. For further details on how to implement DrillDown using SVG and/or Image Maps, please refer to the Image Maps Generation section earlier in this help file.

SVG is still a Proposed Recommendation and additional information and status is available at the official SVG site: http://www.w3.org/Graphics/SVG/Overview.htm8.

In order to use this writer, you must configure the OutputWriter property to a valid SVGWriter object as follows:

'Configure the SVG Writer to generate the SVG
Chart1.OutputWriter = New SoftwareFX.ChartFX.SVG.SVGWriter()

// Configure the SVG Writer to generate the SVG
chart1.OutputWriter = new SoftwareFX.ChartFX.SVG.SVGWriter();

Dim chart1
Set chart1 = Server.CreateObject("ChartFX.ASP.Server")
'Configure the SVG Writer to generate the SVG

Dim svgWriter
Set svgWriter = Server.CreateObject("ChartFX.ASP.SVGWriter")
chart1.OutputWriter = svgWriter

<%=chart.GetHtmlTag(<width>,<height>,"SVG")%>

<%=chart.GetHtmlTag(<width>,<height>,"SVG")%>

A SVG reader is required on the client in order to view the chart in SVG format. If no SVG reader is found on the client, Chart FX will instruct the browser to download a reader from the URL specified in the SVGDownload tag of the configuration ChartFX.Internet.config file. By default, the download URL is http://www.adobe.com/svg/viewer/install/ .


Flash Generation

One of the most useful features of Chart FX is its versatility to render charts in different formats, in order to take advantage of the browser capability to display active content. One of the formats supported by Chart FX is Macromedia Flash.

Macromedia Flash Player is the most widely used rich client technology to deploy content and applications. It implements vector-based content and applications download faster than their bitmap equivalents. Streaming data content appears immediately, without having to wait for the entire piece to download.

Chart FX can provide DrillDown charts using the Flash format, in the same way it provides Image Maps. For further details on how to implement DrillDown using Flash, SVG and/or Image Maps, please refer to the Image Maps Generation section earlier in this help file.

In order to use this writer, you must configure the OutputWriter property to a valid FlashWriter object as follows:

'Configure the Flash Writer as the OutputWriter to generate the Flash chart
chart.OutputWriter = New SoftwareFX.ChartFX.Flash.FlashWriter()

// Configure the Flash Writer to generate the Flash chart
chart1.OutputWriter = new SoftwareFX.ChartFX.Flash.FlashWriter();

Dim chart1
Set chart1 = Server.CreateObject("ChartFX.ASP.Server")
'Configure the Flash Writer to generate the Flash chart

Dim flashWriter
Set flashWriter = Server.CreateObject("ChartFX.ASP.FlashWriter")
chart1.OutputWriter = flashWriter

<%= chart.GetHtmlTag(<width>,<height>,"Flash") %>

<%= chart.GetHtmlTag(<width>,<height>,"Flash") %>


Chart FX for .NET Accessibility Feature

The Chart FX for .NET Accessiblity Extension is a FREE Add-on component which provides the necessary functionality to make Chart FX accessible to people with disabilities as required by Section 508.

More information and the free downloadable add-on is available from the Chart FX Extensions portal at www.softwarefx.com/extensions/.

Chart FX for .NET Accessibility Feature

In 1998, Congress amended the Rehabilitation Act to require Federal agencies to make their electronic and information technology accessible to people with disabilities. Inaccessible technology interferes with an individual's ability to obtain and use information quickly and easily. Section 508 was enacted to eliminate barriers in information technology, to make available new opportunities for people with disabilities, and to encourage development of technologies that will help achieve these goals.

Chart FX for .NET includes an assembly that is used to provide an alternate text version of any chart generated. Chart FX for .NET has been developed with the idea that end users of charts will consist of a very diverse group. This feature is also allows web sites using Chart FX as a charting engine to comply with the Section 508 of the Rehabilitation Act (http://www.section508.gov).

ChartFX.Writer.Accessibility.dll

The accessibility writer works as an enhancer writer for Chart FX for .NET and is only available with WebForms applications. An enhancer writer is a Chart FX for .NET writer that is used to complement a standard writer, such as PNG, JPG or SVG.

In order to use this writer, you must add a reference to the ChartFX.Writer.Accessiblity.dll in your application. The accessibility assembly is located in the /bin folder of your Chart FX for .NET installation. Once included, you may create an accessibility writer object and assign it as the chart OutputWriter to generate the text version of the chart. The code below is used to generate the default alternate text.

<%@ Import  Namespace="SoftwareFX.ChartFX.Accessibility" %>

'Create the ChartText Object
Dim ct as New ChartText()

'Instruct to use the ChartText Writer
Chart1.OutputWriter = ct

Once you have created the ChartText object, you may set attributes to customize the alternate text generated. Some of these properties include WriteOrder, OutputMode, WriteMask, PreviousText, PostText, ShortPause, LongPause, FontFace, FontSize and FontColor.

Below is an example of what the Accessibility text will appear when generated:

Soda Forecasts vs. Sales
Year 2001

Combination graph with 2 series and 6 values.
Value 1, Coke.
Forecasts, 41.00, Detail for Coke, Forecasts.
Sales, From 0.00 to 141.00, Detail for Coke, Sales.
Value 2, Pepsi.
Forecasts, 44.00, Detail for Pepsi, Forecasts.
Sales, From 0.00 to 144.00, Detail for Pepsi, Sales.
Value 3, Dr. Pepper.
Forecasts, 34.00.
Sales, From 0.00 to 134.00.
Value 4, Sprite.
Forecasts, 24.00.
Sales, From 0.00 to 124.00.
Value 5, Seven Up.
Forecasts, 17.00.
Sales, From 0.00 to 117.00.
Value 6, Other.
Forecasts, 13.00.
Sales, From 0.00 to 123.00.

Source: Soda Marketing Research
This is the post text.

For more information regarding the supported members of the ChartText class, please see the Chart FX for .NET API.


BitStream Chart Generation

Since we released Chart FX Internet a few years ago, many large corporations have incorporated Chart FX as an essential reporting tool for their Internet, intranet and extranet sites. Many of these companies impose strict security on their users through the use of firewalls and proxy servers; some of them even go to the extent of configuring the browser so it does not accept anything that may become harmful to their network. Needless to say many of these companies do not allow users to download and use Client Control objects, even if they come from trusted third party vendors like Software FX.

Even though Chart FX always generates images by default, for many corporations the fact that these images are being generated and stored in a particular directory (/Temp) poses a security concern to many of them. For example, a hacker could determine a chart name, create a page and load the chart in his machine before it is actually erased. Many sites display very sensitive data where that risk is simply unacceptable.

With this security concern in mind, Chart FX allows web developers to easily setup pages that return charts as BitStreams instead of generating chart files and letting browsers download files that were previously generated in the Temp directory.

The GetHtmlData method is a method provided by Chart FX that allows the browser to receive a BitStream instead of a chart file from the Chart FX Temp directory of your web server. The GetHtmlData method receives the same parameters as the GetHtmlTag method, except that the result will be a data push directly to the browser. No references to download a file will be generated when using this GetHtmlData method.

In fact, when the user attempts to view the source for the resulting page, no information about the chart file will be displayed. This is because all the necessary information was sent to the browser via a BitStream instead of a chart file or image.


BitStream Chart Image Generation

Creating a Chart Image Without Downloading a File

This technique is used when a chart image (PNG or JPEG) will be generated by the server side component. The idea is as simple as including the <IMG> tag wherever you want the chart to be displayed and the SRC parameter points to the file that generates the BitStream by invoking the getHtmlData method. The IMG tag should read as follows:

<IMG SRC="chart.aspx">

<IMG SRC="chart.aspx">

<IMG SRC="chart.asp">

The chart.asp file will contain the code that generates the desired chart and invokes the GetHtmlData method. An important issue when generating this .aspx page is to make sure there are no other HTML tags or Line feeds in the resulting file as the chart may not be correctly returned and displayed in the browser. In other words, make sure the chart.asp file only returns the results of the GetHtmlData method with no additional characters. For example a valid chart.asp file may look like:

<%@ Page Language="vb"%><%
' Create the chart object on the server
' Please note the way this ASP.NET is coded to avoid any newline or other characters
' to be sent to the client (all the code is SERVER side code)
Dim Chart1 As Chart
Chart1 = New Chart(Me)

' Note the use of GetHtmlData instead of GetHtmlTag
Chart1.GetHTMLData(500,300,"Image")
%>

<%@ Page Language="C#"%><%
// Create the chart object on the server
// Please note the way this ASP.NET is coded to avoid any newline or other characters
// to be sent to the client (all the code is SERVER side code)
SoftwareFX.ChartFX.Internet.Server.Chart chart1 = new SoftwareFX.ChartFX.Internet.Server.Chart(this);
// Note the use of GetHtmlData instead of GetHtmlTag
chart1.GetHtmlData(500,350,"Image");%>

<!-- #include virtual="/ChartFXInt62/Include/ChartFX.ASP.Core.inc" --><%
  ' Create the chart object on the server
  ' Please note the way this ASP is coded to avoid any newline or other characters
  ' to be sent to the client (all the code is SERVER side code)
  Dim Chart1
  Set Chart1 = Server.CreateObject("ChartFX.ASP.Server")
  ' Note the use of GetHtmlData instead of GetHtmlTag
  Chart1.GetHtmlData 500,350,"Image"%>

Please remember there must not be any spaces or carriage returns before the start of the code (<%). If you press [Enter] then a carriage return will be generated in the result of the page and the IMG tag will not be able to read the image generated by Chart FX. Therefore it is strongly advised that you use a plain text editor when generating these files as many advanced editors may include undesired HTML tags in the resulting file.


BitStream Chart Generation

Creating a .NET Chart Without Downloading a File

This technique is used when a .NET Active Chart will be generated by the server side component. The idea is as simple as including the <OBJECT> tag wherever you want the chart to be displayed and the VALUE parameter points to the page that generates the BitStream by invoking the getHtmlData method. The tag should read as follows:

<html>
<body>

<object="Chart1"
classid="/chartfx62/download/ChartFX.MainClient.DLL#SoftwareFX.ChartFX.Internet.MainClient"
WIDTH="300px" HEIGHT="300px">
<PARAM NAME="DataPath" VALUE="/support/aspx/chart.aspx">
<PARAM NAME="AssemblyTarget" VALUE="ChartFX.Internet.Client,
Version=6.2.1486.27906, Culture=neutral, PublicKeyToken=a1878e2052c08dce" >
<PARAM NAME="ClassTarget" VALUE="SoftwareFX.ChartFX.Internet.Client.Chart" >
</object>

</body>
</html>

<html>
<body>

<object="Chart1"
classid="/chartfx62/download/ChartFX.MainClient.DLL#SoftwareFX.ChartFX.Internet.MainClient"
WIDTH="300px" HEIGHT="300px">
<PARAM NAME="DataPath" VALUE="/support/aspx/chart.aspx">
<PARAM NAME="AssemblyTarget" VALUE="ChartFX.Internet.Client,
Version=6.2.1486.27906, Culture=neutral, PublicKeyToken=a1878e2052c08dce" >
<PARAM NAME="ClassTarget" VALUE="SoftwareFX.ChartFX.Internet.Client.Chart" >
</object>

</body>
</html>

<html>
<body>

<object="Chart1"
classid="/ChartfxInt62/download/ChartFX.MainClient.DLL#SoftwareFX.ChartFX.Internet.MainClient"
WIDTH="300px" HEIGHT="300px">
<PARAM NAME="DataPath" VALUE="/support/asp/chart.asp">
<PARAM NAME="AssemblyTarget" VALUE="ChartFX.Internet.Client,
Version=6.2.1486.27906, Culture=neutral, PublicKeyToken=a1878e2052c08dce" >
<PARAM NAME="ClassTarget" VALUE="SoftwareFX.ChartFX.Internet.Client.Chart" >
</object>

</body>
</html>

The chart.asp file will contain the code that generates the chart and invokes the GetHtmlData method. An important issue when generating this file is to make sure there are no other HTML tags or Line feeds in the resulting file as the chart may not be correctly returned and displayed in the browser. In other words, make sure the chart.asp file only returns the results of the GetHtmlData method with no additional characters. For example a valid chart.asp file may look like:

<%@ Page Language="C#"%><%
// Create the chart object on the server
// Please note the way this ASP.NET is coded to avoid any newline or other characters
// to be sent to the client (all the code is SERVER side code)
SoftwareFX.ChartFX.Internet.Server.Chart Chart1 = new SoftwareFX.ChartFX.Internet.Server.Chart(this);
// Note the use of GetHtmlData instead of GetHtmlTag
Chart1.GetHtmlData(500,350,".NET");%>

<%@ Page Language="vb"%><%
' Create the chart object on the server
' Please note the way this ASP.NET is coded to avoid any newline or other characters
' to be sent to the client (all the code is SERVER side code)
Dim Chart1 As Chart
Chart1 = New Chart(Me)

' Note the use of GetHtmlData instead of GetHtmlTag
Chart1.GetHTMLData(500,300,".NET")
%>

<!-- #include virtual="/ChartFXInt62/Include/ChartFX.ASP.Core.inc" --><%
  ' Create the chart object on the server
  ' Please note the way this ASP is coded to avoid any newline or other characters
  ' to be sent to the client (all the code is SERVER side code)
  Dim Chart1
  Set Chart1 = Server.CreateObject("ChartFX.ASP.Server")
  ' Note the use of GetHtmlData instead of GetHtmlTag
  Chart1.GetHtmlData 500,350,".NET"%>

Please remember there must not be any spaces or carriage returns before the start of the code (<%). If you press [Enter] then a carriage return will be generated in the result of the code and the client will not be able to read the image generated by the Chart FX. Therefore it is strongly advised that you use a plain text editor when generating these files as many advanced editors may include undesired HTML tags in the resulting file.


BitStream Chart SVG Generation

Creating a SVG Chart Without Downloading a File

This technique is used when a chart image (SVG) will be generated by the server side component. The idea is as simple as including the <EMBED> tag wherever you want the chart to be displayed and the SRC parameter points to the file that generates the BitStream by invoking the GetHtmlData method. The tag should read as follows:

<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>GetHtmlData SVG</title>
</head>
<body>
<EMBED SRC="chart.aspx" NAME="Chart1" TYPE="image/svg-xml"
PLUGINSPAGE="http://www.adobe.com/svg/viewer/install/" WIDTH="400" HEIGHT="300" >
</body>
</html>

<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>GetHtmlData SVG</title>
</head>
<body>
<EMBED SRC="chart.aspx" NAME="Chart1" TYPE="image/svg-xml"
PLUGINSPAGE="http://www.adobe.com/svg/viewer/install/" WIDTH="400" HEIGHT="300" >
</body>
</html>

<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>GetHtmlData SVG</title>
</head>
<body>
<EMBED SRC="chart.asp" NAME="Chart1" TYPE="image/svg-xml"
PLUGINSPAGE="http://www.adobe.com/svg/viewer/install/" WIDTH="400" HEIGHT="300" >
</body>
</html>

The chart.asp file will contain the necessary code that generates the desired chart and invokes the GetHtmlData method as a result of the page. A very important issue when generating this code is to make sure there are no other HTML tags or Line feeds in the resulting file as the chart may not be correctly returned and displayed in the browser. In other words, make sure the chart.asp file only returns the results of the GetHtmlData method with no additional characters. For example a valid chart.asp file may look like:

<%@ Page Language="vb"%><%
' Create the chart object on the server
' Please note the way this ASP.NET is coded to avoid any newline or other characters
' to be sent to the client (all the code is SERVER side code)
Dim Chart1 As New SoftwareFX.ChartFX.Internet.Server.Chart(Me)
Chart1.OutputWriter = New SoftwareFX.ChartFX.SVG.SvgWriter()
' Note the use of GetHtmlData instead of GetHtmlTag
Chart1.GetHtmlData(500,350,"SVG")%>

<%@ Page Language="C#"%><%
// Create the chart object on the server
// Please note the way this ASP.NET is coded to avoid any newline or other characters
// to be sent to the client (all the code is SERVER side code)
SoftwareFX.ChartFX.Internet.Server.Chart Chart1 = new SoftwareFX.ChartFX.Internet.Server.Chart(this);
Chart1.OutputWriter = new SoftwareFX.ChartFX.SVG.SvgWriter();
// Note the use of GetHtmlData instead of GetHtmlTag
Chart1.GetHtmlData(500,350,"SVG");%>

<!-- #include virtual="/ChartFXInt62/Include/ChartFX.ASP.Core.inc" --><%
  ' Create the chart object on the server
  ' Please note the way this ASP is coded to avoid any newline or other characters
  ' to be sent to the client (all the code is SERVER side code)
  Dim Chart1
  Set Chart1 = Server.CreateObject("ChartFX.ASP.Server")
  Dim Svg1
  Set Svg1= Server.CreateObject("ChartFX.ASP.SVGWriter")
  Chart1.OutputWriter = Svg1
  ' Note the use of GetHtmlData instead of GetHtmlTag
  Chart1.GetHtmlData 500,350,"SVG"%>

Please remember there must not be any spaces or carriage returns before the start of the code (<%). If you press [Enter] then a carriage return will be generated in the result of the code and the client will not be able to read the image generated by Chart FX. Therefore it is strongly advised that you use a plain text editor when generating these files as many advanced editors may include undesired HTML tags in the resulting file.


BitStream Chart FlashGeneration

Creating a Flash Chart Without Downloading a File

This technique is used when a Flash chart will be generated by the server side component. The idea involves including the <OBJECT> tag wherever you want the chart to be displayed and the VALUE parameter points to the .aspx that generates the BitStream by invoking the getHtmlData method. The tag should read as follows:

<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>GetHtmlData Flash</title>
</head>
<body>

<OBJECT name="Chart1" classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#Version=5,0,0,0"
WIDTH="450" HEIGHT="280" VIEWASTEXT>
<param name="Chart1" value="chart.aspx" />
<EMBED name="Chart1" type="application/x-shockwave-flash" src="chart.aspx"
pluginspage="http://www.macromedia.com/shockwave/download/index.cgi?P1_Prod_Version=ShockwaveFlash"
 WIDTH="450" HEIGHT="280" ></EMBED>
</OBJECT>
</body>
</html>

<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>GetHtmlData Flash</title>
</head>
<body>

<OBJECT name="Chart1" classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#Version=5,0,0,0"
WIDTH="450" HEIGHT="280" VIEWASTEXT>
<param name="Chart1" value="chart.aspx" />
<EMBED name="Chart1" type="application/x-shockwave-flash" src="chart.aspx"
pluginspage="http://www.macromedia.com/shockwave/download/index.cgi?P1_Prod_Version=ShockwaveFlash"
 WIDTH="450" HEIGHT="280" ></EMBED>
</OBJECT>
</body>
</html>

<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>GetHtmlData Flash</title>
</head>
<body>

<OBJECT name="Chart1" classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#Version=5,0,0,0"
WIDTH="450" HEIGHT="280" VIEWASTEXT>
<param name="Chart1" value="chart.asp" />
<EMBED name="Chart1" type="application/x-shockwave-flash" src="chart.asp"
pluginspage="http://www.macromedia.com/shockwave/download/index.cgi?P1_Prod_Version=ShockwaveFlash"
 WIDTH="450" HEIGHT="280" ></EMBED>
</OBJECT>
</body>
</html>

The chart.asp file will contain the necessary code that generates the desired chart and invokes the GetHtmlData method as a result of the page. A very important issue when generating this file is to make sure there are no other HTML tags or Line feeds in the resulting file as the chart may not be correctly returned and displayed in the browser. In other words, make sure the chart.asp file only returns the results of the GetHtmlData method with no additional characters. For example a valid chart.asp file may look like:

<%@ Page Language="vb"%><%
' Create the chart object on the server
' Please note the way this ASP.NET is coded to avoid any newline or other characters
' to be sent to the client (all the code is SERVER side code)
Dim Chart1 As New SoftwareFX.ChartFX.Internet.Server.Chart(Me)
Chart1.OutputWriter = New SoftwareFX.ChartFX.Flash.FlashWriter()
' Note the use of GetHtmlData instead of GetHtmlTag
Chart1.GetHtmlData(500,350,"FLASH")%>

<%@ Page Language="C#"%><%
// Create the chart object on the server
// Please note the way this ASP.NET is coded to avoid any newline or other characters
// to be sent to the client (all the code is SERVER side code)
SoftwareFX.ChartFX.Internet.Server.Chart Chart1 = new SoftwareFX.ChartFX.Internet.Server.Chart(this);
Chart1.OutputWriter = new SoftwareFX.ChartFX.Flash.FlashWriter();
// Note the use of GetHtmlData instead of GetHtmlTag
Chart1.GetHtmlData(500,350,"FLASH");%>

<!-- #include virtual="/ChartFXInt62/Include/ChartFX.ASP.Core.inc" --><%
  ' Create the chart object on the server
  ' Please note the way this ASP is coded to avoid any newline or other characters
  ' to be sent to the client (all the code is SERVER side code)
  Dim Chart1
  Set Chart1 = Server.CreateObject("ChartFX.ASP.Server")
  Dim Flash1
  Set Flash1 = Server.CreateObject("ChartFX.ASP.FlashWriter")
  Chart1.OutputWriter = Flash1
  ' Note the use of GetHtmlData instead of GetHtmlTag
  Chart1.GetHtmlData 500,350,"Flash"%>

Please remember there must not be any spaces or carriage returns before the start of the code (<%). If you press [Enter] then a carriage return will be generated in the resulting file and the client will not be able to read the results generated by Chart FX. Therefore it is strongly advised that you use a plain text editor when generating these files as many advanced editors may include undesired HTML tags in the resulting file.


Maintaining Browser Independence

Maintaining Browser Independence to Display Images or Use Client-Side Components

If you want Chart FX to detect the browser being used and return the appropriate <OBJECT> or <IMG> tags but without any files being generated as a result of this request, then you just include the GetHtmlTag in your page and invoke the file that generates the chart and returns the BitStream using the GetHtmlData method. For example, if you want to include a chart in a page that generates no temporary file but still detects the browser posting the request to send back a client-side component or image, use:

<%= Chart.GetHtmlTag(550,250,"#chart.aspx?Param=1") %>

<%= chart.GetHtmlTag(550,250,"#chart.aspx?Param=1") %>

<%= Chart.GetHtmlTag(550,250,"#chart.asp?Param=1") %>

Please note that the third parameter of the GetHtmlTag has the following characteristics:

  • It starts with the # sign
  • The # sign is followed by the file that must invoked to generate the BitStream using the GetHtmlData method
  • You can invoke, if necessary, the file with parameters (such as the Param shown in the GetHTMLTag method above)

Then the chart.asp looks like:

<%' Create the chart object on the server
' Please note the way this ASP.NET is coded to avoid any newline or other characters
' to be sent to the client (all the code is SERVER side code)
Dim Chart1 As Chart
Chart1 = New Chart(Me)
Chart1.Gallery = Gallery.Area

' Note the use of GetHtmlData instead of GetHtmlTag
Chart1.GetHTMLData(500,300,"Auto")%>

<%// Create the chart object on the server
// Please note the way this ASP.NET is coded to avoid any newline or other characters
// to be sent to the client (all the code is SERVER side code)
Chart Chart1 = new Chart(this);
Chart1.Gallery = Gallery.Area;
// Note the use of GetHtmlData instead of GetHtmlTag
Chart1.GetHTMLData(500,300,"Auto");%>

<!-- #include virtual="/ChartFXInt62/Include/ChartFX.ASP.Core.inc" -->
<%' Create the chart object on the server
' Please note the way this ASP is coded to avoid any newline or other characters
' to be sent to the client (all the code is SERVER side code)
Dim Chart1
Set Chart1 = Server.CreateObject("ChartFX.ASP.Server")
Chart1.Gallery = Gallery_Area
' Note the use of GetHtmlData instead of GetHtmlTag
Chart1.GetHTMLData(500,300,"Auto")%>

As it was said before, there must not be a space or carriage return before the start of the code.

IMPORTANT NOTE: If you are using "Image Maps" in the charts, you must use GetHtmlDataEx instead. Please review the documentation for further details about the GetHtmlDataEx method.


Removing Temporary Files

As you may already know, Chart FX generates a temporary file (either a chw file or chart image) every time a user hits a page that contains a chart. These temporary files are stored in a directory (usually /ChartFXInt62/Temp) pointed by ChartFX.Internet.config.

As a matter of fact, Chart FX will generate temp files for every user and every hit you receive. Therefore, you'll need a scheduled mechanism that allows you to keep this directory clean. The answer to this problem is a utility provided by Chart FX called SfxRemove.

SfxRemove is a utility that can be used to remove "old" files (Chart files and images) in any directory. You can schedule this utility to be invoked once per day using the Windows NT/2000/XP AT command. You can specify the directory (usually Temp in which the temporary files are generated), and amount of time in hours or minutes (e.g. 24h means files older than 1 day will be removed). For example, if you installed Chart FX in the C: drive, you must use:

SfxRemove "C:\Program Files\Chart FX\ChartFX62\Temp" 24h
SfxRemove "C:\Program Files\Chart FX\ChartFX62\Temp" 30m

SfxRemove "C:\Program Files\Chart FX\ChartFX62\Temp" 24h
SfxRemove "C:\Program Files\Chart FX\ChartFX62\Temp" 30m

SfxRemove "C:\Program Files\Chart FX\ChartFXInt62\Temp" 24h
SfxRemove "C:\Program Files\Chart FX\ChartFXInt62\Temp" 30m

We strongly suggest the use of the SfxRemove utility to remove "old" chart files and images. If you fail to do this you might end up with a large amount of files in your /Temp directory.


Tuning Chart FX for Performance and Scalability

While it is true that web applications have many advantages, such as easy deployment and wide availability, in the end, this paradigm presents a whole new challenge for developers: server scalability and performance.

The real issue in web application design is user experience; to make the application perform as a traditional desktop application when it is actually a distributed application that could be simultaneously servicing hundreds or even thousands of users.

This section is geared to developers using Chart FX in their Web applications. In the following paragraphs, you will learn how to fine-tune Chart FX to improve your application's ability to accommodate a growing number of users and give each user a satisfactory level of responsiveness.

To understand how Chart FX can impact server performance, consider that every time an .aspx page is accessed, the Chart FX Server controls will essentially create a chart in memory using a device context created on the server. This means, hardware and software settings on your server will affect how quickly these charts can be created.

In general, Chart FX performance will depend to a great extent on the chart format generation (Image, ActiveX, .NET Control, SVG, etc) and the chart return mechanisms (GetHtmlTag or GetHtmlData) you choose in your code. Also, when generating chart images you should pay close attention to the Chart FX default property settings, image quality and chart size as major performance factors when the server is under heavy load.


Default Settings and Performance

It is important to note that Chart FX was designed to conform to web development guidelines and to take advantage of the server-bound nature of web applications. Nevertheless, many of the product's default settings were selected to improve the chart's look rather than focusing on server performance.

For example, Chart FX uses a default smoothing algorithm on text and markers that will negatively impact server performance. This feature can be turned off by using the SmoothFlags property as follows:

Chart1.SmoothFlags = SmoothFlags.None

chart1.SmoothFlags = SmoothFlags.None;

Chart1.SmoothFlags = SmoothFlags_None

Turning off the smoothing feature will enhance server performance and ultimately increase the amount of users you can serve concurrently.

In general, if server performance is of real concern you should avoid using features that are geared toward achieve a cosmetic look for the chart. In particular, features like Borders, Transparency and Gradients use GDI+ heavily as a way to improve the way charts look.


Chart Render Size

A common practice among web developers is to create a big chart that can be easily read on a browser. However, this practice can be an important factor on how your server behaves and performs under heavy load. Essentially, a bigger chart means a larger image that needs to be processed, generated, stored and finally downloaded. This affects in one way or another, the application's overall performance, therefore, you must be careful when choosing the final chart rendering size in the page if server performance is a concern.

To illustrate this, suppose you increase the size of a 400x300 Png image of a chart and measure its impact on server performance.

We found that for every 30% increase on the chart width and height, the server experienced a significant decrease in the number of Requests per Second it could process.

Changing the chart size may be costly on your overall page design. However, it may be an excellent source to boost performance if you have exhausted all other options.

While reducing the chart size considerably will benefit server performance, you must be careful not to select a size so small that will compromise the chart's readability.


Image Compression

The Chart FX server Png algorithm provides an image compression factor that can be used to reduce file size. This value ranges from 0-100, being 100 the maximum compression ratio.

Maximum compression will enhance download time of chart images considerably. Unfortunately, this compression algorithm has an adverse effect on server performance. Similarly, uncompressed Png images will resemble pixelated bitmap images which are simply too big for a web application and will also have an adverse effect on server performance by significantly increasing hard disk usage.

You should commit for a compression setting that will produce well compressed images without significantly affecting server performance. You can do this by using the ImgCompression property of the chart control as follows:

Chart1.ImgCompression = 30


Chart Format

As a server-side component, Chart FX allows developers to generate charts in a myriad of formats. Which one to choose depends not only on performance and scalability, but also on other important issues such as browser compatibility, interactivity, accessibility and security.

The Chart FX server control can dynamically generate and render Png, Jpeg, ActiveX, .NET client, Flash and SVG chart files. Other formats may also be supported in the future. Please see OutputWriter for more information.

In general, chart formats that require a viewer (e.g. Flash and SVG) enhance server performance since chart files are very small and each client will carry much of the chart painting processing load. These viewers also provide a better analytical experience by allowing browser interaction without additional intervention from the developer or trips back to the server. However, they do not provide universal access plus some organizations do not allow the use of viewers because of security and accessibility reasons.

In general, viewers are acceptable under a controlled environment like an intranet. However, if you must reach a wide audience, you may be forced to generate universally accepted images like Png and Jpeg.

These raster images decrease performance since each chart needs to be painted and even stored on the server. Also, these charts will provide limited or no analytical capabilities on the browser since they are rendered as static images, except for PNG images which supports hot spots or URL links on most chart elements. The major advantage of using chart images is that they provide universal access to charts from any browser, platform or operating system.


Decreasing Chart Download Time

One of the available rendering options Chart FX provides is a .NET client control. Web applications generating charts in such format as opposed to ActiveX or images take additional time to generate and download all the required components. This wait time can be associated with the connection speed of the end user as well as the process which the Microsoft .NET Framework utilizes in order to display .NET controls.

The first time a browser encounters a .NET control in a page it has to load the .NET framework; in addition the "main" control (in this case the Chart FX for .NET Internet Client Control) is downloaded to compare against the version in the download cache (this is done on a per-session basis).

In order to prevent the entire Chart FX for .NET Internet Client Control from being downloaded each time, a smaller wrapper control is downloaded with the version information and is compared to the version of the Chart FX for .NET Internet Client Control in the downloaded cache. If the version is compatible, the control in cache is used instead of requiring another download.

To change the Chart FX behavior so your charts generate an object with a small "wrapper" control, you can set the MainClient property of the chart (in your page) to true.

Chart1.MainClient = True

chart1.MainClient = true;

Chart1.MainClient = True

On some slower connections, we have measured an improvement from 30 seconds to about 7 seconds (on the first hit of a browser session).

If this works for you, there is a registry setting that will generate all your charts using this approach.

Registry key: HKLM\Software\Software FX, Inc.\ChartFX for .NET\6.2\Server
Name: MainClient
Value: 1 (DWORD value)


Chart Return Mechanisms

To improve the level of responsiveness as well as enhancing support for different server architectures, Chart FX provides two ways of processing and returning charts to the browser. These mechanisms are provided by 2 methods: the GetHtmlTag method and the GetHtmlData method.

When a user hits a page containing the GetHtmlTag method; a chart file is saved to disk and an HTML tag (IMG, OBJECT) is returned so the browser can know the location of the chart file on the web server. Finally a second trip back to the server is necessary to pull the chart from the server and display it on the page as a static image or an active component. One of GetHtmlTag's greatest advantages is that charts can be easily integrated into your existing pages and it allows support for automatic browser detection. However, saving a file to disk can take its toll on server performance.

On the other hand, the GetHtmlData method prevents the chart file from being saved to disk by bit-streaming the chart directly to the browser; this process leads to fewer round-trips between the client and the server. However, integration into the page is awkward because you must point to another file that returns the bit-stream to the browser. Also, no browser detection is provided using this methodology, preventing your application from making "smart" decisions based on the user's browser capabilities.

In terms of performance, you will learn that although the GetHtmlData method is processor intensive it allows developers to boost performance and scalability and it permits the use of Chart FX on intricate server architectures such as web farms.


Chart FX and Web Farms (Server clustering)

Once you hit a certain threshold, cost-effective scalability requires the use of multiple processors spread across multiple servers. In other words, you'll need a Web Farm.

We mentioned that when using the GetHTmlTag method a chart file is saved to disk. The one problem with web farm architecture is that when the browser comes back to the server to retrieve the file; the HTTP request could be directed to another server on the farm on which the chart was not originally saved, resulting in an empty chart placeholder on the page.

To address this issue, you can do the following:

1. Change the server affinity setting, which lets you instruct the service to route HTTP requests over the same physical server once the first request has gone through. However, affinity slows the system down by requiring it to maintain a user-to-server mapping and perform a lookup upon each request. In other words, changing server affinity compromises scalability and the benefits of request-based load balancing are lost.

2. Replicate the chart file on all servers in the web farm. Although this is possible in a variety of ways, there is no way to guarantee the chart file will be successfully replicated and stored on all servers by the time the browser requests it. This is especially true on intranets where latency effects are virtually non-existent.

3. Force all servers in the farm to generate charts on a unique server. In other words, tweak the code to have all servers generate charts in a specified directory on a particular machine if the farm and make the browser look for charts in that directory. Although a viable solution, this makes chart integration and maintenance much more difficult. It will also shift performance bottlenecks to the hard drive on which the charts are being stored and prevent the application to be server fault tolerant, which is a nice addition when using a web farm.

In other words, generating a chart file that will be saved to disk poses many server performance and scalability problems on a Web Farm. Therefore, we suggest you use the GetHtmlData method which bit-streams the chart directly to the browser, preventing many of the abovementioned issues and providing a more natural integration to a web farm.


Using the PSS Extension

Chart FX for .NET PSS Extension Architecture

The Chart FX for .NET PSS extension includes a Service and a .NET assembly. The service (ChartFX.Enterprise.Server.exe) communicates with the server component and handles caching, delayed generation and security according to the conditions set in the configuration file and/or in the code. The Service must run on the same server where the Chart FX for .NET server component is running.

The .NET assembly is used to instruct Chart FX to use the service, and programmatically set its behavior. It must reside in the same folder as the ChartFX.Internet.dll.

Using the Chart FX for .NET PSS Extension

Loading the Chart FX .NET extension is as simple as creating a new instance of the extension and binding it to the main chart object in your ASP.NET page as follows:

'Create the extension object
Dim entWriter As New SoftwareFX.ChartFX.Enterprise.EnterpriseWriter()

'Bind the extension to the chart
Chart1.OutputWriter = entWriter

You will need the code above only if the EnterpriseWriter is not your default writer. If you modify the ChartFX.Internet.config XML file, you can instruct Chart FX for .NET to use the EnterpriseWriter by default, setting the DefaultWriter as follows:

<CfxIESettings> ...
<Enterprise.OutputWriter> ..
<DefaultWriter>SoftwareFX.ChartFX.Enterprise.EnterpriseWriter,
ChartFX.Enterprise.OutputWriter</DefaultWriter>
</Enterprise.OutputWriter>
</CfxIESettings>

In this case, the EnterpriseWriter will be your default OutputWriter. The following code will be required to obtain the EnterpriseWriter for further customization:

'Obtain the Enterprise Writer from the chart
Dim entWriter As SoftwareFX.ChartFX.Enterprise.EnterpriseWriter
entWriter = Chart1.OutputWriter

'Set the entWriter properties now...

Note: Be aware that the Chart FX for .NET PSS extension applies default caching, delayed generation and security values that may cause an unexpected behavior from the Chart FX for .NET server component. Please refer to this document for more information on default values and their impact on the Chart FX server component original behavior.

Caching

Caching is a technique used to store items in memory the initial time they are requested with the purpose of improving performance and scalability. In a web application, this technique allows a server to avoid recreating information that satisfied a previous request, saving time and resources by utilizing server time more efficiently.

The Chart FX for .NET PSS extension provides a powerful caching mechanism that allows subsequent requests for a particular chart to be satisfied from the cache so the code that initially creates the chart does not have to be run upon subsequent requests.

To understand how caching increases server's throughput, consider that when the ASP.NET page is running, the Chart FX server component will essentially create and paint a chart in memory using a device context created on the server, the server must then store the chart on disk for immediate access by the browser. This process is repeated for each subsequent request, whether the chart intrinsic data has changed or not. For example, without caching an ASP page that displays the "Chart of the Day" will force the server to create the chart as many times as the page is requested thus wasting server time and resources. In contrast, with caching this chart will be created, stored in memory and delivered only once according to an expiration time set by the programmer.

Activating Chart Caching

As soon as the Chart FX for .NET PSS extension is installed on your server, you are capable of activating caching on a per chart basis by loading the extension as showed in previous paragraphs and by setting the ExpirationTime property as follows:

'7 minutes cache

Dim ts As New TimeSpan(0, 7, 0)
entWriter.ExpirationTime = ts

Once you have enabled caching, the Chart FX for .NET PSS extension places the chart in direct access memory for the amount of time you specify.

Note: To turn caching off you must set the ExpirationTime property back to 0.

Processing Page Parameters

In most cases, charts are created with a number of possible parameters that are used to connect to a data source and generate various responses or intrinsic chart data. For example, if a sales chart is generated as a result of an HTML form that allows users to filter data by store location, date, city and zip code input boxes, the chart will be different for each user and thus caching a single chart will not render the desired results.

By default, the Chart FX for .NET PSS extension will cache a version of the chart based on the page parameters. In other words, each chart will have stored the string or form POST parameters that are passed with a request, by the HTTP headers passed with a request. This behavior is controlled by the CacheParameters property, as follows:

entWriter.CacheParameters = False

Note: Please note turning the CacheParameters property to FALSE will force Chart FX to ignore the parameters that were selected by the user or sent as part of the page request. Therefore, we suggest doing this only if the parameters are not being used by the chart component.

It is important to note that ALL parameters will be cached, even if they are not related to the chart. For example, if a chart is created as a result of an HTML form that lists name, address, city and date as form fields but only city and date are actually used to create the chart you may want to force Chart FX to ignore the rest of the fields so charts with different cities and dates are cached.

This can be done easily with the ParametersToCache property. A string array property that allows you to specify the actual parameters you want to cache. For example, if only city and date are to be used to cache charts, you may want to set this property as follows:

Dim ParamToCache(2) As String
ParamToCache(0) = "City"
ParamToCache(1) = "Date"

entWriter.ParametersToCache = ParamToCache

Note: Failing to set this property on fields that are not related to the chart will cause Chart FX to cache an unnecessary number of charts in memory since it will cache ALL parameters associated to the page where the chart is located.

The Chart FX for .NET server component is capable of producing different file formats (PNG, JPG and SVG among others) when the chart is requested***. Although some programmers will force Chart FX to produce a single format, most will simply let Chart FX decide which format is best according to the browser posting the request.

For obvious performance reasons, Chart FX does not create and render all formats when the page is requested. Therefore, this browser detection mechanism has an adverse effect when caching since a chart that is expected to look consistent on all formats may end up being different because it was produced at a different time.

The ConsistentOutput property allows Chart FX to keep in-sync the charts being produced regardless of their format. This property can be set as follows:

entWriter.ConsistentOutput = True

Note: The ConsistentOutput property will apply to one and the same server. Please note this property will not guarantee consistency on a web farm. For more information on web farm issues and caching please contact Software FX support.

*** Refer to GetHtmlTag method in Chart FX for .NET API Reference

Sliding Cache Expiration

In some applications, the absolute nature of the ExpirationTime property can have adverse effects on the server. For example, if an application handles hundreds or even thousands of charts, the caching mechanism may end up storing charts in memory that are not being frequently used or accessed and thus not needed in memory.

The MemorySlidingExpiration property sets a time that will be renewed with each request, when the MemorySlidingExpiration reaches its value and the chart has not been requested it will then be removed from memory and stored on disk. In contrast, if the chart is accessed within the limits of the MemorySlidingExpiration property the chart will be kept in memory and the time will be reset with each subsequent request. This mechanism allows the server to make better use of its memory and other server resources.

For example, you can set the ExpirationTime property to 2 days and the MemorySlidingExpiration property at 1 hour. If a chart is accessed for a second time within an hour then the sliding cache time will be renewed to 1 hour and the chart will be kept in memory. If the chart is not accessed within an hour the chart will be removed from memory and stored on disk, when the chart is then requested again it is loaded into memory and the sliding cache will be reset to 1 hour. It is important to note the chart will be removed from the cache 2 days after it was first accessed (as instructed in the ExpirationTime property).

The following code shows how to set the ExpirationTime and MemorySlidingExpiration properties:

'2 Days Cache
Dim et As New TimeSpan(2, 0, 0, 0)
entWriter.ExpirationTime = et

'1 hour memory sliding expiration
Dim mse As New TimeSpan(1, 0, 0)
entWriter.MemorySlidingExpiration = mse

IIS Buffering and Chart Delayed Generation

When page output is buffered, the server does not send a response to the client until all of the server scripts on the current page have been processed. For long scripts, this may cause a perceptible delay.

The Chart FX for .NET PSS extension delay generation mechanism can significantly improve the performance of large ASP.NET applications in which users primarily connect to the application by means of a modem by making better use of the roundtrip time thus maximizing server processing time.

This mechanism allows the GetHtmlTag method to generate a tag that can be used by the browser and immediately return control to the page without waiting until the chart gets generated on the server. When the page output is buffered, this will result in a significant improvement on performance since server scripts will be processed faster without waiting until the Chart FX server controls generates, paints and stores the chart and returns control so the rest of the script completes execution.

In essence, this mechanism of returning control immediately so the rest of the server script can continue running without further delay from the chart control allows for a better use of server idle time when data is traveling from the server to the clients.

Chart delay generation does not expose any properties and it is always running when the Chart FX for .NET PSS Extension is used.

Note: Please note the chart delay generation mechanism may not have the same advantages in a non-buffered environment (or page) where elements written to the Response object are sent to the client browser as quickly as possible.

At a later time, when the chart is requested by the browser, the Chart FX will automatically dispose it. Nevertheless, the ChartFX.Enterprise.Service.Config XML file provides a setting that instructs the server to dispose of charts that have been generated but not requested by the client browser. This file is located in the same folder where the PSS Service is running, and the TimeWaitForRequest can be set as follows:

<configuration>
<appSettings>
<add
key="TimeWaitForRequest" value="0:7:0"
/>
</appSettings>
</configuration>

*** In IIS 4.0, the Buffer property of the ASP Response object was set to FALSE by default. With a new installation of IIS 5.1, the Buffer property is set to TRUE by default. During an upgrade from previous versions of IIS to IIS 5.1, the Buffer property is not changed from its previous setting.

Security

When you use Chart FX for .NET, a directory (virtual root) is created on IIS. Subsequently, all chart files will be stored on this directory on a temporary basis until a scheduled maintenance utility (see SfxRemove in Chart FX for .NET documentation) is invoked and charts are permanently removed from disk.

This process unveils two critical security issues:

First, while files remain in this directory a hacker may find ways to view and inspect charts that were generated by the Chart FX server component. Secondly, since this directory is used by the Chart FX server component as a general directory it can't apply discretionary authentication information to files being generated by the server component. For example, charts with private data such as employee salary information may end up requiring authentication, but since it is stored on the same directory it will inherit the same security restrictions as the rest of the files in this folder. In most cases, this Temp directory is created with anonymous access which means all files can be accessed by virtually anyone.

In practical terms, these issues are minimized by the fact that each chart name is generated with a random seed that makes it impossible to detect unless directory search is allowed in IIS.

Nevertheless, the Chart FX for .NET PSS extension takes a safer approach and addresses both issues by avoiding generated chart files from being stored on disk. Instead, chart files are kept in memory and once requested they are discarded preventing a hacker from inspecting files stored in a directory.

Also, each chart is signed with each user authentication and it is returned only to the user who initially requested the chart thus making Chart FX for .NET security as strong as the security policies imposed by IIS.

Once you load the Chart FX for .NET PSS extension the user authentication will be enabled. If you want you can disable this feature with the UseAuthentication property as follows:


Client SIde Events Overview

Using Client Side events with the .NET Client Component Chart

When developers choose to generate and display charts to end users as .NET Client Controls, many new features are extended to end users through intuitive IU controls. A toolbar is available with a multitude of options which provide users the ability to change visual attributes, view data values and even save data.

Along with the introduction of these features to the end user, the same chart events that are supported with the Windows Form component are now also available in a webform application at the client side. This is all made possible because client assemblies are downloaded to the client’s computer.

There are some requirements in order to utilize client side scripting with WebForm charts. In order to use these chart events:

  • Developers need to utilize client side JavaScript or VBScript scripting.
  • Client events require that the client’s computer has the proper trust level enabled.
  • Special attributes must be set in the chart’s server code for any event to fire.
  • Some Events require special settings in order for the event to fire.
  • Because Internet Explorer (IE6) lacks support for complex (object) parameters, events in the client component have different parameters than the Windows form version. Developers must use the parameters defined in this section.

Chart Attributes Required for Client Side Events
It is necessary to instruct the chart not to utilize the MainClient assembly when using client side events. This assembly is used to speed the download and display of charts; However, when using client side events, it is required that this assembly is not used. To ensure this, you can configure the chart’s MainClient property to false as follows:

http://support.softwarefx.com/kb/614/1/001.htm

Chart Attributes Required for Client Side Events
It is necessary to instruct the chart not to utilize the MainClient assembly when using client side events. This assembly is used to speed the download and display of charts; However, when using client side events, it is required that this assembly is not used. To ensure this, you can configure the chart’s MainClient property to false as follows:

Chart1.MainClient = false;

As mentioned earlier, client side chart events are only supported by the .NET Client Control chart type. To render the chart in this format, you must set the HtmlTag:

Chart1.HtmlTag = “.NET”;

If you are generating the chart by calling the GetHtmlTag property, you must specify the chart’s name that will be used in the client side event handler. For example, you would call the GetHtmlTag in your server code as follows:

Response.Write(Chart1.GetHtmlTag(“350”, “500”, “.NET”, “Chart1”));

Because “Chart1” is specified in the 4th parameter of the GetHtmlTag call, the client side event handler for the MouseDown event would look as follows:

sub Chart1_MouseDown( nButton, nClicks, nHitType, x, y, nSeries, nPoint, obj)

Client Side Event Parameters

Because Internet Explorer (IE6) lacks support for complex (object) parameters, events in the client component have different parameters than the Windows form version. Since all parameters are simple types and passed by value, a property (only present in the client component) exist called ReturnValue is used to return data from the event. This property is an object and can be assigned to anything; each event gives a different meaning to this property. Note the usage of this property for each of the events.

Accessing the Chart object in VBScript

Accessing the Chart object in VBScript may be done using the name of the Form object and accessing the Chart as follows:

sub Chart1_GetPointLabel(nAxis, nPoint, nSeries, sLabel)
'Return value used to modify text string for label
Form1.Chart1.ReturnValue = "USA"
Form1.Chart1.Chart3D = True
end sub

Accessing the Chart object in JavaScript

Accessing the Chart object in JavaScript does not require using the Form object to be included, simply the name of the Chart object specified in the event handler:

<script lang="JavaScript" for="Chart1"
event="GetPointLabel( nAxis, nSeries, nPoint, sLabel)">
// Return value used to modify text string for label
Chart1.ReturnValue = "USA";
Chart1.Chart3D = true;
</script>


ChangedByUser Event

void ChangedByUser()

Where,
This event has no parameters.

VBScript Sample

<script language="VBScript">
<!--
sub Chart1_ChangedByUser()
msgbox("ChangedByUser_fired")
end sub
-->
</script>

JavaScript Sample

<script lang="JavaScript" for="Chart1" event="ChangedByUser()">
alert("ChangedByUser_fired");
</script>


ConditionalAttributesCallBack Event

void ConditionalAttributesCallback(int32 nSeries, int32 nPoint)

Where,
nSeries - Returns the index of the Series affected
nPoint - Returns the index of the Point affected
ReturnValue - - In this event, if ReturnValue is set to an integer, that value will be used to specify the Conditional Attributes index to assign to the point.

VBScript Sample

<script language="VBScript">
<!--
sub Chart1_ConditionalAttributesCallback( nSeries, nPoint)
msgbox("ConditionalAttributesCallback_fired")
end sub
-->
</script>

JavaScript Sample

<script lang="JavaScript" for="Chart1" event="ConditionalAttributesCallback( nSeries, Point)">
alert("ConditionalAttributesCallback_fired");
</script>


DataChangedByUser Event

void DataChangedByUser(int32 nAxis, int32 nSeries, int32 nPoint, string sLabel)

Where,
nAxis - Returns the index of the Axis affected
nSeries - Returns the index of the Series affected
nPoint - Returns the index of the Point affected
sLabel - Returns the new string value for the data (from the user)
ReturnValue - In this event, if the ReturnValue property is set to a Boolean value, this specifies to either to continue default processing or stop processing (event handled by developer). By configuring ReturnValue to True, developers are instructing the chart stop default processing. If ReturnValue is set to a string, that value will be used to modify the chart instead of the sLabel parameter value returned initially.

VBScript Sample

<script language="VBScript">
<!—-
sub Chart1_DataChangedByUser(nAxis, nSeries, nPoint, sLabel) msgbox("DataChangedByUser_fired")
end sub
-->
</script>

JavaScript Sample

<script lang="JavaScript" for="Chart1"
event="DataChangedByUser(nAxis, nSeries, nPoint, sLabel)">
alert("DataChangedByUser_fired");
</script>


DoubleClick Event

void DoubleClick(int32 nButton, int32 nClicks, int32 nHitType, int32 x, int32 y, int32 nSeries, int32 nPoint, object obj)

Where,
nButton - Returns which mouse button was pressed
nClicks - Returns the number of times the mouse button was pressed and released
nHitType - Returns the element type hit by when the event occurred
x - Returns the x-coordinate of the mouse event
y - Returns the y-coordinate of the mouse event
nSeries - Returns the index of the Series affected
nPoint - Returns the index of the Point affected
obj - Returns the object hit by the user when the event occurred
ReturnValue - In this event, if the ReturnValue property is set to a Boolean value, this specifies to either to continue default processing or stop processing (event handled by developer). By configuring ReturnValue to True, developers are instructing the chart stop default processing.

VBScript Sample

<script language="VBScript">
<!--
sub Chart1_DoubleClick( nButton, nClicks, nHitType, x, y, nSeries, nPoint, obj)
msgbox("DoubleClick_fired")
end sub
-->
</script>

JavaScript Sample

<script lang="JavaScript" for="Chart1"
event="DoubleClick( nButton, nClicks, nHitType, x, y, nSeries, nPoint, obj)">
alert("DoubleClick_fired");
</script>


GetAxisLabel Event

void GetAxisLabel(int32 nAxis, string sLabel)

Where,
nAxis - Returns the index of the Axis affected
sLabel - Returns the string value of the axis label
ReturnValue - If ReturnValue is set to a string, that value will be used to modify the axis label instead of the sLabel parameter value returned initially.

** Special Note ** In order for this event to fire, you must configure the Axis.Notify property to true for the axis object you wish this event to be raised:

Chart1.AxisY.Notify = true;

VBScript Sample

<script language="VBScript">
<!--
sub Chart1_GetAxisLabel( nAxis, sLabel)
msgbox("GetAxisLabel_fired")
end sub
-->
</script>

JavaScript Sample

<script lang="JavaScript" for="Chart1" event="GetAxisLabel( nAxis, sLabel)">
alert("GetAxisLabel_fired");
</script>


GetPointLabel Event

void GetPointLabel(int32 nAxis, int32 nSeries, int32 nPoint, string sLabel)

Where,
nAxis - Returns the index of the Axis affected
nSeries - Returns the index of the Series affected
nPoint - Returns the index of the Point affected
sLabel - Returns the string value of the point label
ReturnValue - In this event, if the ReturnValue property is set to a Boolean value, this specifies to either to continue default processing or stop processing (event handled by developer). By configuring ReturnValue to True, developers are instructing the chart stop default processing. If ReturnValue is set to a string, that value will be used to modify the point label instead of the sLabel parameter value returned initially.

** Special Note ** In order for this event to fire, you must configure the Axis.Notify property to true for the axis object that the series associated with the point labels is assigned:

Chart1.AxisY.Notify = true;

VBScript Sample

<script language="VBScript">
<!--
sub Chart1_GetPointLabel( nAxis, nSeries, nPoint, sLabel)
msgbox("GetPointLabel_fired")
end sub
-->
</script>

JavaScript Sample

<script lang="JavaScript" for="Chart1"
event="GetPointLabel( nAxis, nSeries, nPoint, sLabel)">
alert("GetPointLabel_fired");
</script>


GetTip Event

void GetTip(int32 nHitType, int32 x, int32 y, object obj, string sText)

Where,
nHitType - the element type hit by when the event occurred
x - Returns the x-coordinate of the tooltip
y - Returns the y-coordinate of the tooltip
obj - Returns the object hit by the tooltip when the event occurred
sText - Returns the string to be used for the tooltip
ReturnValue - If ReturnValue is set to a string, that value will be used to modify the tooltip instead of the sText parameter value returned initially.

VBScript Sample

<script language="VBScript">
<!--
sub Chart1_GetTip( nHitType, x, y, obj, sText)
msgbox("GetTip_fired")
end sub
-->
</script>

JavaScript Sample

<script lang="JavaScript" for="Chart1"
event="GetTip( nHitType, x, y, obj, sText)">
alert("GetTip_fired");
</script>


InternalCommand Event

void InternalCommand(int32 nID)

Where,
nID - Returns the CommandID value for the internal command fired.
ReturnValue - In this event, if the ReturnValue property is set to a Boolean value, this specifies to either to continue default processing or stop processing (event handled by developer). By configuring ReturnValue to True, developers are instructing the chart stop default processing.
-

VBScript Sample

<script language="VBScript">
<!--
sub Chart1_InternalCommand( nID)
msgbox("InternalCommand_fired")
end sub
-->
</script>

JavaScript Sample

<script lang="JavaScript" for="Chart1" event="InternalCommand( nID)">
alert("InternalCommand_fired");
</script>


MouseDown Event

void MouseDown(int32 nButton, int32 nClicks, int32 nHitType, int32 x, int32 y, int32 nSeries, int32 nPoint, object obj)

Where,
nButton -
nClicks - Returns the number of times the mouse button was pressed and released
nHitType - Returns the element type hit by when the event occurred
x - Returns the x-coordinate of the mouse event
y - Returns the y-coordinate of the mouse event
nSeries - Returns the index of the Series affected
nPoint - Returns the index of the Point affected
obj - Returns the object hit by the user when the event occurred
ReturnValue - In this event, if the ReturnValue property is set to a Boolean value, this specifies to either to continue default processing or stop processing (event handled by developer). By configuring ReturnValue to True, developers are instructing the chart stop default processing.

VBScript Sample

<script language="VBScript">
<!--
sub Chart1_MouseDown( nButton, nClicks, nHitType, x, y, nSeries, nPoint, obj)
msgbox("MouseDown_fired")
end sub
-->
</script>

JavaScript Sample

<script lang="JavaScript" for="Chart1"
event="MouseDown( nButton, nClicks, nHitType, x, y, nSeries, nPoint, obj)">
alert("MouseDown_fired");
</script>


MouseMove Event

void MouseMove(int32 nButton, int32 nClicks, int32 nHitType, int32 x, int32 y, int32 nSeries, int32 nPoint, object obj)

Where,
nButton - Returns which mouse button was pressed
nClicks - Returns the number of times the mouse button was pressed and released
nHitType - Returns the element type hit by when the event occurred
x - Returns the x-coordinate of the mouse event
y - Returns the y-coordinate of the mouse event
nSeries - Returns the index of the Series affected
nPoint - Returns the index of the Point affected
obj - Returns the object hit by the user when the event occurred
ReturnValue - In this event, if the ReturnValue property is set to a Boolean value, this specifies to either to continue default processing or stop processing (event handled by developer). By configuring ReturnValue to True, developers are instructing the chart stop default processing.

VBScript Sample

<script language="VBScript">
<!--
sub Chart1_MouseMove( nButton, nClicks, nHitType, x, y, nSeries, nPoint, obj)
msgbox("MouseMove_fired")
end sub
-->
</script>

JavaScript Sample

<script lang="JavaScript" for="Chart1"
event="MouseMove( nButton, nClicks, nHitType, x, y, nSeries, nPoint, obj)">
alert("MouseMove_fired");
</script>


MouseUp Event

void MouseUp(int32 nButton, int32 nClicks, int32 nHitType, int32 x, int32 y, int32 nSeries, int32 nPoint, object obj)

Where,
nButton - Returns which mouse button was pressed
nClicks - Returns the number of times the mouse button was pressed and released
nHitType - Returns the element type hit by when the event occurred
x - Returns the x-coordinate of the mouse event
y - Returns the y-coordinate of the mouse event
nSeries - Returns the index of the Series affected
nPoint - Returns the index of the Point affected
obj - Returns the object hit by the user when the event occurred
ReturnValue - In this event, if the ReturnValue property is set to a Boolean value, this specifies to either to continue default processing or stop processing (event handled by developer). By configuring ReturnValue to True, developers are instructing the chart stop default processing.

VBScript Sample

<script language="VBScript">
<!--
sub Chart1_MouseUp( nButton, nClicks, nHitType, x, y, nSeries, nPoint, obj)
msgbox("MouseUp_fired")
end sub
-->
</script>

JavaScript Sample

<script lang="JavaScript" for="Chart1"
event="MouseUp( nButton, nClicks, nHitType, x, y, nSeries, nPoint, obj)">
alert("MouseUp_fired");
</script>


PostPaint Event

void PostPaint(int32 w, int32 h, object objGraphics)

Where,
w - Returns the Width of the chart
h - Returns the Height of the chart
objGraphics - Returns the Graphics object used for painting
ReturnValue - In this event, if the ReturnValue property is set to a Boolean value, this specifies to either to continue default processing or stop processing (event handled by developer). By configuring ReturnValue to True, developers are instructing the chart stop default processing.

VBScript Sample

<script language="VBScript">
<!--
sub Chart1_PostPaint( w, h, objGraphics)
msgbox("PostPaint_fired")
end sub
-->
</script>

JavaScript Sample

<script lang="JavaScript" for="Chart1" event="PostPaint( w, h, objGraphics">
alert("PostPaint_fired");
</script>


PrePaint Event

void PrePaint(int32 w, int32 h, object objGraphics)

Where,
w - Returns the Width of the chart
h - Returns the Height of the chart
objGraphics - Returns the Graphics object used for painting
ReturnValue - In this event, if the ReturnValue property is set to a Boolean value, this specifies to either to continue default processing or stop processing (event handled by developer). By configuring ReturnValue to True, developers are instructing the chart stop default processing.

VBScript Sample

<script language="VBScript">
<!--
sub Chart1_PrePaint( w, h, objGraphics)
msgbox("PrePaint_fired")
end sub
-->
</script>

JavaScript Sample

<script lang="JavaScript" for="Chart1" event="PrePaint( w, h, objGraphics)">
alert("PrePaint_fired");
</script>


PrePaintMarker Event

void PrePaintMarker(object objGraphics, int32 nSeries, int32 nPoint, int32 x, int32 y)

Where,
objGraphics - Returns the Graphics object used for painting
nSeries - Returns the index of the Series affected
nPoint - Returns the index of the Point affected
x - Returns the x-coordinate of the marker
y - Returns the y-coordinate of the marker
ReturnValue - In this event, if the ReturnValue property is set to a Boolean value, this specifies to either to continue default processing or stop processing (event handled by developer). By configuring ReturnValue to True, developers are instructing the chart stop default processing.

** Special Note ** In order for this event to fire, you must turn the PaintMarker flag of the Chart.TypeMask property on:

Chart1.TypeMask = Chart1.TypeMask | ChartType.PaintMarker;

VBScript Sample

<script language="VBScript">
<!--
sub Chart1_PrePaintMarker( objGraphics, nSeries, nPoint, x, y)
msgbox("PrePaintMarker_fired")
end sub
-->
</script>

JavaScript Sample

<script lang="JavaScript" for="Chart1"
event="PrePaintMarker( objGraphics, nSeries, nPoint, x, y)">
alert("PrePaintMarker_fired");
</script>


ProcessUrl Event

void ProcessUrl(string sURL, string sFrame)

Where,
sURL - Returns the URL processed
sFrame - Returns the Frame for the URL processing
ReturnValue - Not used.

VBScript Sample

<script language="VBScript">
<!--
sub Chart1_ProcessUrl( sURL, sFrame)
msgbox("ProcessUrl_fired")
end sub
-->
</script>

JavaScript Sample

<script lang="JavaScript" for="Chart1" event="ProcessUrl( sURL, sFrame)">
alert("ProcessUrl_fired");
</script>


UserCommand Event

void UserCommand(int32 nID)

Where,
nID - Returns the CommandID value for the user command fired.
ReturnValue - In this event, if the ReturnValue property is set to a Boolean value, this specifies to either to continue default processing or stop processing (event handled by developer). By configuring ReturnValue to True, developers are instructing the chart stop default processing.

VBScript Sample

<script language="VBScript">
<!--
sub Chart1_UserCommand( nID)
msgbox("UserCommand_fired")
end sub
-->
</script>

JavaScript Sample

<script lang="JavaScript" for="Chart1" event="UserCommand( nID)">
alert("UserCommand_fired");
</script>


UserScroll Event

void UserScroll(int32 nAxis)

Where,
nAxis - the index of the Axis affected
ReturnValue - Not used.

VBScript Sample

<script language="VBScript">
<!--
sub Chart1_UserScroll( nAxis)
msgbox("UserScroll_fired")
end sub
-->
</script>

JavaScript Sample

<script lang="JavaScript" for="Chart1" event="UserScroll( nAxis)">
alert("UserScroll_fired");
</script>


ASP Pages

Integrating a chart into an ASP file is as simple as creating and instantiating the chart object, setting the desired chart properties and finally invoking a method (GetHtmlTag or GetHtmlData) that allows the Chart FX server component to generate the appropriate HTML output (images or active components) supported by the browser posting the page request.

The following code is an example of how a simple chart can be included in a ASP page of a web application:

                <!-- #include virtual="/ChartFXInt62/Include/ChartFX.ASP.Core.inc" -->

                Welcome to my first ASP page that contains a chart:<br>

                <%

                ' Create the chart object

                Dim Chart1

                Set Chart1 = Server.CreateObject("ChartFX.ASP.Server")

                ' Change the Gallery Type to Lines

                Chart1.Gallery = Gallery_Lines

                ' Change the background color

                Chart1.BackColor = RGB(102,153,255)

                ' Change the marker shape to Rectangles

                Chart1.MarkerShape = MarkerShape_Rect

                ' Generate a chart of 500x350 pixels

                %>

                <%= Chart1.GetHtmlTag(500,350) %>

Notes:

  • Please use the Chart FX API Reference for more information on properties and methods that can be applied to the Chart object.
  • The chart displayed above will display random data. For more information on how to populate the chart from a database or any other data source please refer to "Passing Data" in this manual.
  • Please be sure to add the Include statement to your page, as it's necessary to access the Chart FX enumerations and other variables defined in such include file. Other include files are available in the ChartFXInt62\Include subfolder of your Chart FX installation directory.
  • Don't forget to check out Interactive Tutorial and Samples, and the Chart FX Internet support site at support.softwarefx.com.


Client Side Components

In many cases, your users will be using a Windows-based Internet Explorer, and in many ocassions even .NET Framework compatible systems to access your commercial web site or corporate intranet. For these users, Chart FX Internet provides client-side components that allow them to interact with the charts directly from their browsers. These components are responsible for providing:

  • Access data pre-processed by Chart FX Internet server-side component.
  • Fully interactive charts on their browsers.
  • A pleasant experience from your web site.

Although client-side components may be used independently, the most common way to use it is in conjunction with the Chart FX Internet server-side components. Integrating them into your web site is a transparent process, because the server will return an HTML tag to instantiate the appropriate component model or to generate an image whenever the browser does not support any active component. Therefore, using these components DOES NOT mean limiting or restricting the user base you can reach. Please remember, Chart FX Internet will always provide a compatible tag with the browser being used by the client.

Chart FX Internet currently provides the following client components:

  • ActiveX Client Control for Internet Explorer
    This control is automatically downloaded by Internet Explorer 4 or later. It allows the end user to interact with the chart directly from the browser. This component is located in the /ChartFXInt62/Download virtual directory of your web server. Installation is automatic but requires the end-user to accept the installation of the component. Requirements: Windows system with Internet Explorer 4 or above.
  • .NET Client Control for Internet Explorer
    This control is automatically downloaded by Internet Explorer 5.01 or later. It allows the end user to interact with the chart directly from the browser. This component is located in the /ChartFXInt62/Download virtual directory of your web server. Installation is automatic with no user intervention since it uses only .NET managed code. Requirements: Windows system with Internet Explorer 5.01 or above and the .NET Framework 1.0 or later.

Client-Side Component libraries and assemblies:

For the ActiveX:

  • ChartFX.ComIEClient.Core.dll: This is the main library, equivalent to ChartFX.ASP.Core.dll in the server.

For the .NET Client control:

  • ChartFX.Internet.Client.dll: This is the main assembly, equivalent to ChartFX.ASP.Core.dll in the server.
  • ChartFX.MainClient.dll: This is the client assembly downloaded when MainClient is set to true. Please see "Decreasing Chart Download Time" in the Performance and Scalability section.
  • ChartFX.Internet.Base.dll, ChartFX.Internet.Borders.dll, ChartFX.Writer.Accessibility.dll, ChartFX.Writer.SVG.dll and ChartFX.Annotation.dll : These assemblies are equivalent to their counterparts in the server.

Important Compatibility Note: The Chart FX for .NET client-side component is provided only for versions of Windows with the .NET Framework properly installed, including Windows 98 and Windows NT/2000/XP.

Please contact Software FX, Inc. for more information on the availability of additional Chart FX client-side components. Our phone number is (800) 392-4278 or refer to our web site at http://www.softwarefx.com for the latest client components information.

Licensing Considerations

The Chart FX client-side components are royalty-free for distribution provided that you use it in conjunction with the server-side components licensed appropriately. For more information on licensing options please contact Software FX at (800) 392-4278 or email us at sales@softwarefx.com.


Reading from Arrays and Collections

In many situations, the data is contained in a memory array. Although you can use the Chart FX API to loop through array elements, read and populate the chart, you can also do so in an easier way.

This feature is supported by the ListDataProvider object, implemented in the Chart FX Data Providers library and the chart's DataSource property, as follows:

' Create the array
Dim valArray(4)
valArray(0) = 12
valArray(1) = 15
valArray(2) = 10
valArray(3) = 7
valArray(4) = 5
' Create the ListDataProvider
Dim lstProvider
Set lstProvider = Server.CreateObject("ChartFX.ASP.ListProvider")
' Add the array to the ListDataProvider
lstProvider.AddCollection valArray
' Populate the chart with the ListDataProvider
Chart1.DataSource = lstProvider

' Create the array
Dim valArray(4)
valArray(0) = 12
valArray(1) = 15
valArray(2) = 10
valArray(3) = 7
valArray(4) = 5
' Create the ListDataProvider
Dim lstProviderSet As Cfx62ClientServerData.ListDataProvider
lstProvider = New Cfx62ClientServerData.ListDataProvider
' Add the array to the ListDataProvider
lstProvider.AddCollection valArray
' Populate the chart with the ListDataProvider
Chart1.DataSource = lstProvider

Note: Please refer to the Data Providers section for more information about integrating the default Data Provider.

If you want to load data from more than one array, you can use the method shown in the following example:

' Create the arrays
Dim series1(2)
series1(0) = 12
series1(1) = 15
series1(2) = 20
Dim series2(2)
series2(0) = 20
series2(1) = 25
series2(2) = 7
Dim labels(2)
labels(0) = "Yes"
labels(1) = "No"
labels(2) = "Don't know"
' Create the ListDataProvider
Dim lstProvider
Set lstProvider = Server.CreateObject("ChartFX.ASP.ListProvider")
' Add the arrays to the ListDataProvider
lstProvider.AddCollection series1
lstProvider.AddCollection series2
lstProvider.AddCollection labels
' Populate the chart with the ListDataProvider
Chart1.DataSource = lstProvider

' Create the arrays
Dim series1(2)
series1(0) = 12
series1(1) = 15
series1(2) = 20
Dim series2(2)
series2(0) = 20
series2(1) = 25
series2(2) = 7
Dim labels(2)
labels(0) = "Yes"
labels(1) = "No"
labels(2) = "Don't know"
' Create the ListDataProvider
Dim lstProvider As Cfx62ClientServerData.ListDataProvider
Set lstProvider = New Cfx62ClientServerData.ListDataProvider
' Add the arrays to the ListDataProvider
lstProvider.AddCollection series1
lstProvider.AddCollection series2
lstProvider.AddCollection labels
' Populate the chart with the ListDataProvider
Chart1.DataSource = lstProvider

Please note that you can pass arrays filled with Numerical Data as well as String or Dates, which will be taken as legends in the chart. In this particular sample there are 3 arrays, two containing numerical data to be contained in the chart and the other containing legends for each point in the nValues array. This means, there's no limitation on the number of arrays you can pass using this technique.

Important Note: The order you use to add the arrays to the data provider is really important as you can use the DataType property to instruct Chart FX to manipulate the collections differently. For example, you can use the DataType property to instruct Chart FX to use a particular numerical collection as legends in the chart.

Using the DataType property

The DataType property is an array property that indicates the type of every position and how it should be extracted from the Array or Collection and used in the chart. For example, with two arrays:

// Create an array for the years
Dim year(2)
year(0) = 1999
year(1) = 2000
year(2) = 2001

// Create another array for the values
Dim sales(2)
sales(0) = 100000
sales(1) = 125000
sales(2) = 150000

' Create an array for the years
Dim year(2)
year(0) = 1999
year(1) = 2000
year(2) = 2001

' Create another array for the values
Dim sales(2)
sales(0) = 100000
sales(1) = 125000
sales(2) = 150000

Chart FX will consider the year array as another series since it is a numeric field. Instead, we want this field to be used as a value for the X Axis. We can easily override the Chart FX default behavior by filling the DataType property as follows:

Chart1.DataType(0) = DataType_XValue
Chart1.DataType(1) = DataType_Value

Chart1.DataType(0) = DataType_XValue
Chart1.DataType(1) = DataType_Value


Populating the chart from a Database

In most cases, you will want to populate charts with data coming from a database table or query. Chart FX supports data binding through ADO Recordsets. Connecting to a database via ADO is supported by the Chart FX core, so no additional data libraries need to be deployed in this case.

The following code shows how to connect to a database through an ADO recordset:

<!-- #include virtual="/ChartFXInt62/Include/ChartFX.ASP.Core.inc" -->
<%
Dim chart1
Set chart1 = Server.CreateObject("ChartFX.ASP.Server")

' Database code. Filling the chart1 with database information
mySelectQuery = "SELECT * from Samples"
myConnectionString = "Provider=Microsoft.Jet.OLEDB.4.0; Data Source=" + Server.MapPath("ChartfxSamples.mdb;")
Set myConnection = Server.CreateObject("ADODB.Connection")
myConnection.Open(myConnectionString)
Set rs = myConnection.Execute(mySelectQuery)

' Assign the recordset to the chart
chart1.DataSource = rs
%>

<%= chart1.GetHtmlData(400,400) %>

Dim mySelectQuery as String
mySelectQuery = "SELECT * from SampleFinancial1"
Dim myConnectionString as String
myConnectionString = "Provider=Microsoft.Jet.OLEDB.4.0; Data Source=" + (App.Path) + "\ChartfxSamples.mdb;"
Dim myConnection as New ADODB.Connection
Set myConnection = New ADODB.Connection
myConnection.Open(myConnectionString)
Dim adapter as Object
Dim rs
Set rs = myConnection.Execute(mySelectQuery)

For details of how Chart FX interprets the SQL statement, please refer to the SQL section of the Programmer's Guide or Resource Center.


Passing Data to Chart FX Overview

The most basic method of passing data to a chart using Chart FX is to utilize the built-in API. The Chart FX API provides properties and methods to load and manipulate data into a chart. However, one of the features of Chart FX is the ability to read or pass data from many sources. These sources include databases, text files, XML files, arrays, collections, and many others.

Passing data from databases and text files is supported by Chart FX's core. However, all the code required to read data from XML, Crosstab, array and collection sources has been isolated in an additional library (ChartFX.ASP.Data.dll) allowing Software FX to easily build additional "Chart FX Data Providers".

By providing an additional library exclusively used for data, the programmer can decide when to include or exclude the dll, thus giving control of what is to be deployed. Although data functionality requires an additional library to be deployed as part of your application, it allows Chart FX to provide easy integration of new data sources, e.g. Active Directory, Grids, OLAP, etc.

In Chart FX, there is no need to loop through data points to populate the charts. If you have a previously filled data array, just pass it to Chart FX and have the chart filled with data with as little as one line of code. Additionally, Chart FX supports connection to an existing ADO Recordset.

This chapter will explain how to populate your charts from the most common data sources. These sources include:

  • API
  • Database
  • Text files
  • XML files
  • Arrays and Collections
  • Crosstab


The Chart FX Data Library

When you install Chart FX, a default Data library will also be installed. This library allows you to read information from XML, Crosstab, arrays, collections, etc. In the following pages, we will show you how you can use this additional library to read information and populate the chart from any of these sources.

How to integrate the Chart FX Data Library

The Chart FX data library may be integrated into your project by simply using and deploying the appropriate file: ChartFX.ASP.Data.dll (Chart FX Internet) or ChartFX.ClientServer.Data.dll (Chart FX Client Server). Because other data providers are libraries, you can integrate them as well with a reference to the appropriate DLL.

By including and referencing this file as part of your development project, you can create objects that are implemented by the data library. Please refer to later topics in this section for more information on how to use the objects available in the data library with different data sources.

Important Note for Chart FX Internet users: constants required by some objects in the Data library are available in a separate include file (ChartFX.ASP.Data.inc), available in the ChartFXInt62/Include folder.


Getting Help

There are a variety of different resources available to developers when trying to get help using Chart FX. The largest collection of information supporting the product can be found in the Chart FX Resource Center, which includes the API references, tutorial programmer's guide, an Internet reference guide and samples. Below are some ways to get help for Chart FX:

  • Chart FX Resource Center (API, Tutorial, Internet Reference, Samples)
  • Help File
  • Intellisense within your IDE
  • Support Web Sites
  • Newsgroups
  • 30-day Free Trial Support
  • Paid Support Account

Chart FX Resource Center

The Chart FX Resource Center is a compilation of information supporting development for ASP and VB using Chart FX. Included in the Resource Center are the API references, tutorial programmer's guide, an Internet Reference, and plenty of samples to help you find the answers to your questions.

The API Reference documents the supported objects of Chart FX, describing every property, method and event available in the charting component. If you are looking for a particular feature, the API reference is a good starting point.

The Interactive Samples provides samples and information about topics like passing data, axis handling, tool customization, and much more. The Interactive Samples are designed to allow you to cut and paste code into your projects to quickly produce charts and reduce your learning curve. The samples have also been created in ASP and VB, so you will not have to spend time converting any of the samples.

The Internet Reference is specific to Web development and covers many of the features available only in Chart FX Internet.

Help Files / IntelliSense

The Chart FX API and Programmer's Guide help files are available for both Chart FX Internet and Chart FX Client Server in CHM format. An Internet Reference help file is also available for Chart FX Internet.

The IntelliSense feature in your IDE, such as VB, can also act as an aid by prompting developers with possible coding options and information. When a function or statement is entered into the Code Editor, its complete syntax and arguments are shown in a ToolTip. In addition, languages that supports early binding display available functions, statements, constants, and other values in a list that you can choose from.

Support Web Sites

Support for Chart FX is available on the web for free. Support.SoftwareFX.com was designed to help you quickly and easily find the information you need. In this site, you can view knowledgebase articles, sample code, documentation, product updates and other important technical support information. Please be aware that in order to use the support site, you are required to have a Windows-based system with a browser that supports client-side components (both Internet Explorer and Netscape are supported!).

Individual sites have been created specifically for Chart FX Internet and Chart FX Client Server, which can be accessed at the following URL's:

Chart FX Internet: http://support.softwarefx.com/cfxint62

Chart FX Client Server: http://support.softwarefx.com/cfxcs62

SoftwareFX support site:

http://support.softwarefx.com

Newsgroups

Newsgroups are a great way to receive feedback from the Software FX Support Team, as well as other Chart FX developers. The Software FX staff is dedicated to providing the best support possible, so monitoring the Newsgroups is a daily routine, plus access to the Newsgroups is free. You can access the Software FX Newsgroups at:

Newsgroups URL: news://news.softwarefx.com

30 Day Trial and Paid Support Accounts

Registered users of Chart FX may sign up for a support account online. The account is free for the first 30 days. If you require further assistance after that period, you may renew your support account for a yearly fee. You can create your support account at the following URL:

Account Registration:http://support.softwarefx.com/Accounts

Contact Support

The Technical Support contact information can be found at: http://support.softwarefx.com.


Installation

Installing Chart FX Internet to create Web applications

Because Chart FX Internet provides Production and Development installations, there are two steps you need to complete to properly install this product:

Installation on systems used to develop the web pages/applications

Chart FX Internet provides a Development components setup file (CfxInternetDevelopment.exe).This will copy and configure all the necessary files, including documentation and samples, that will be required to develop your application, and a Chart FX Internet Test/Development Server, which is specially designed for development purposes.

This installation will setup all the necessary libraries so that you can integrate charts in your Web applications. This way, developers can properly develop and test their application in development machines. This setup requires a web server to be installed and properly configured on the development machine.

Please note that the Chart FX Internet Development components are licensed on a per developer basis. With your purchase of Chart FX Internet, you received 1 licensed copy of these components which entitles use for 1 developer only. If you have additional developers you must purchase additional development licenses.

Installation on a Production web server

There's a Production Server setup file (CfxInternetProduction.exe). This file must be run on the machine that is acting as the Production web server. This setup application requires a web server to be installed and properly running on the machine.

Please note that the Chart FX Internet Production servers are licensed on a per server basis. With your purchase of Chart FX Internet, you received 1 licensed copy of these components which entitles deployment on 1 Production server only. If you need to deploy it to additional servers you must purchase additional deployment licenses. Software FX also offers volume discounts and OEM agreements for developers in need to integrate Chart FX Internet in their web applications. Please contact us at (561) 999-8888, (800) 392-4278 or email us sales@softwarefx.com.

If you are installing Chart FX Internet on a Windows NT box, you may want to learn about IIS Installation Issues

Important Client-side Components Information

The Chart FX fInternet client-side components are included in the Development and Production setup applications. These files are copied in the /ChartFXInt62/Download virtual directory of your web server so they can be properly downloaded and installed by client systems. These files are downloaded by the browser automatically when the chart is rendered as a client component. These files can not be redistributed unless are used in conjunction with the server components. For further licensing details please contact Software FX at sales@softwarefx.com.


Chart FX Internet Web Reference

Chart FX Internet was designed for Webmasters and Internet Developers wanting to provide charts on their web sites or corporate intranets. To start using this product you must be familiarized with the following:

  • Hardware platform you are using to run your web site
  • Web Server software you are using (e.g. Internet Information Server, etc.)
  • ASP programming language basics
  • Database access (including ADO and ODBC)
  • HTML Language basics

This portion of the documentation will help you install and integrate Chart FX Internet on your server with minimal effort. It will also describe in detail Internet enabled features in this product and how it was designed to work seamlessly integrated with your web server to provide powerful charts to your users.

This reference help file does not intend to list or describe each property, object or method supported at the programming level. For that purpose please refer to the Chart FX API help file and the Resource Center, installed with Chart FX Internet.


Requirements

Installation Requirements

To properly install and run Chart FX Internet on a production or development server you will need the following:

  • Windows server with Internet Information Server (IIS) or any other ASP compatible web server

Additionally, for the development of the web pages/applications you will require:

  • Microsoft .NET Framework 1.0 or above. This is required only for the use of the Resource & Samples Center and the Chart FX Internet Designer. This is NOT required by the Chart FX Internet Server or Client side components.


Server Side Component

Chart FX Internet provides a server-side component. This component performs the following important tasks:

  • Integration with database drivers like ADO to connect to a database, retrieve data and populate the chart.
  • Provide support for the server-side execution language, or ASP pages, which allow developers to customize how the chart looks before it is displayed on the browser.
  • Process the HTTP_USER_AGENT coming from the browser to determine the browser's ability to display active content and produce a compatible HTML tag so the charts can be viewed on any browser. This means, the Chart FX Internet server-side component is responsible for the provision of a browser-neutral approach in Chart FX Internet.
  • When the browser posting the request to the page containing a chart does not provide support for active content, the Chart FX Internet server-side component is responsible for rendering a compatible image such as a PNG or JPEG.
  • Generate image maps whenever a chart image contains links to URLs.

Server-Side Component Libraries:

  • ChartFX.ASP.Core.dll : This is the "main" library of Chart FX Internet.
  • ChartFX.ASP.Base.dll: This library contains the implementation of many of the functions in Chart FX Internet and is required in order to use the core component.
  • ChartFX.ASP.Data.dll: This library will need to be used when you use certain data providers to read data from sources such as text files, lists, XML files or Crosstab. A data related object, DataSourceSettings, is also included in this library and supports members such as DataSource and DataType.
  • ChartFX.ASP.Borders.dll: use this library if you want to use the additional borders or gradient backgrounds.
  • ChartFX.ASP.Annotation.dll: This library needs to be referenced when you want use an Annotation object in your chart.

Important Compatibility Note: The Chart FX Internet server-side component requires a web server (such as Internet Information Server) to be running on a Windows box.

Licensing considerations

The Chart FX Internet server-side component is licensed on a per server basis for deployment, and on a per developer basis for development. For more information please refer to the Chart FX Internet License Agreement or call (800) 392-4278 or email us to sales@softwarefx.com for more information on licensing arrangements.


Welcome to the Chart FX for .NET Interactive Samples and Resource Center

Welcome to the Chart FX Interactive Samples and Resource Center

Whether you are just starting with Chart FX or you are an experienced Chart FX developer, here you will find a wealth of documentation and samples that will help you benefit from Chart FX in your developement environment.

As an added benefit, this resource center not only provides a "Programmer's Guide" reference that discusses interesting Chart FX topics, but also includes the Chart FX API, an Internet Reference specifically catered for ASP development and a wealth of actual samples and charts (and code) that you can integrate and test in your applications.

Exporting the code to your application

It is important to note that this application is capable of dynamically producing VBScript code that you can use in your .asp files. To do this, use the following steps:

1. The ChartFX Resource Center allows you to select the type of application you're developing for, between Windows Forms, Web Forms and Smart Device applications. It is important that you select the appropriate button, as some features are only available for a particular environment. The interactive samples are also specifically created for Windows Forms, Web Forms or Smart Devices and should be used in the intended development environment to avoid errors. (See location 1)

2. Once your application preference has been selected, the appropriate API reference is loaded as well as the Internet Reference (for Web Forms applications only). You may select which reference guide to view by selecting the appropriate tab. (See location 2)

3. Once you have selected your desired reference guide, you can navigate to the appropriate sample or topic using the tree control located on the left. (See location 3). It is important to note that you can size the space allotted to the tree control by positioning the mouse next to the right margin of the tree and dragging it to a desired width.

4. The Resource Center samples provide the source code used to create each sample in different programming languages. To view the sample code, simply click the appropriate tab according to the code you are using in your application. (See location 4)

5. The code can then be copied using the "Copy Code" button located next to these tabs. Using this button will copy all the code needed to duplicate the sample to your clipboard, which you can then paste into a project. (See location 5)

We suggest you paste this code as part of an event handler in your application (e.g. a button), so you can test before it is finally integrated into your application.

Please note samples may provide data or code that is not specific to the sample shown or that you may want to remove once integrated into your application. Each sample separates the relevant code from the cosmetic code by color coding.

6. If you are using Chart FX for .NET in a single .aspx file, you should use the .aspx button so the code parser can add the code that is needed to properly use Chart FX for .NET outside your IDE. This option is only available when the type of application selected is Web Forms. (See location 6)

Please let us know if this is a valuable resource to you. As always, we strive in providing the best support in the business and we believe tools like this will ultimately ease the coding and integration process.

We hope you enjoy Chart FX for .NET as much as we enjoyed developing it for you.
@2004 Software FX, Inc. All Rights Reserved. Chart FX is a registered trademark of Software FX, Inc.